import { createDemoSessionAdapter, createExternalAuthSessionAdapter, createUnavailableSessionAdapter, type ExternalSessionOwner, } from "../adapters/auth/external-session-adapter.ts"; import { createDiagnosticsAdapter } from "../adapters/diagnostics/bounded-diagnostics.ts"; import { createHttpClient } from "../adapters/http/client.ts"; import { createContractHttpExecutor } from "../adapters/http/http-execution-v3.ts"; import { createBrowserCrossContextInvalidationFromHost } from "../adapters/cross-context-invalidation/index.ts"; import { createTanStackCacheCoordinator, } from "../adapters/query-cache/tanstack-cache-coordinator.ts"; import { createQueryClient } from "../adapters/query-cache/tanstack-query-cache.ts"; import { createServerStateScopeRuntime } from "../adapters/query-cache/server-state-scope-runtime.ts"; import { createConditionalValidatorStore } from "../adapters/query-cache/conditional-validator-store.ts"; import { createBrowserStorageAdapter } from "../adapters/storage/browser-storage-adapter.ts"; import { createTelemetryAdapter } from "../adapters/telemetry/best-effort-telemetry.ts"; import type { AuthSessionPort } from "../application/ports/auth-session-port.ts"; import type { ReleaseInfo } from "../application/ports/release-info-port.ts"; import { createRestProviderProfile } from "../contracts/rest-profiles.ts"; import type { ClockPort } from "../application/ports/clock-port.ts"; import { createInstalledFeatureInputs } from "../features/installed-feature-adapters.ts"; import { INVALIDATION_REGISTRY, INVALIDATION_TOPIC_VERSIONS, } from "../features/installed-feature-contracts.ts"; import { INSTALLED_RUNTIME_CAPABILITIES } from "../features/installed-runtime-capabilities.ts"; import { describeRuntimeCapabilities } from "../contracts/runtime-capabilities.ts"; import { fetchReleaseManifest, type ReleaseManifest, } from "./load-release-manifest.ts"; import type { RuntimeConfigLoadResult } from "./load-runtime-config.ts"; import { createServerStateGenerationStore } from "./server-state-generation-store.ts"; import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../features/installed-contract-contributions.ts"; import { indexInvalidationRegistry, indexInvalidationTopicVersions, } from "../contracts/query-invalidation.ts"; type HttpClientDependencies = Parameters[0]; export type RuntimeHttpContract = Pick< HttpClientDependencies, "getOperation" | "validatePayload" | "validateRequest" | "mapPayload" >; type RuntimeHttpContext = Readonly<{ runtime: RuntimeConfigLoadResult; authSession: AuthSessionPort; fetcher?: typeof fetch; clock?: ClockPort; scheduler?: HttpClientDependencies["scheduler"]; diagnostics?: HttpClientDependencies["diagnostics"]; telemetry?: HttpClientDependencies["telemetry"]; }>; export type RuntimeAdaptersContext = Readonly<{ runtime: RuntimeConfigLoadResult; release: Readonly; host?: Record; fetcher?: typeof fetch; }>; /** * ยง5.2. The composition root is where a manifest becomes release info. A V2 * manifest states contract identity as a verified contract set and a V1 * manifest as the legacy scalar; the application layer sees one shape and never * branches on the schema version to find the identity. */ function toReleaseInfo(manifest: Readonly): ReleaseInfo { const { contractSet, legacyApiContractVersion, ...rest } = structuredClone(manifest); return Object.freeze({ ...rest, ...(legacyApiContractVersion === undefined ? {} : { apiContractVersion: legacyApiContractVersion }), ...(contractSet === null ? {} : { contractSetDigest: contractSet.setDigest }), }); } const EXTERNAL_OWNER_METHODS = Object.freeze([ "readState", "subscribe", "beginSignIn", "signOut", "attachCredential", "recoverSession", "notifyUnauthenticated", ] as const); function isRecord(value: unknown): value is Record { return Boolean(value) && typeof value === "object"; } function externalOwnerFrom( host: Record, ): ExternalSessionOwner | null { const candidate = host.__CA_FRONTEND_AUTH_OWNER__; if (!isRecord(candidate)) return null; return EXTERNAL_OWNER_METHODS.every( (name) => typeof candidate[name] === "function", ) ? (candidate as ExternalSessionOwner) : null; } function hostValue( host: Record, property: string, ): unknown { try { return Reflect.get(host, property); } catch { return undefined; } } function storageOrUndefined(value: unknown): Storage | undefined { if (!value || typeof value !== "object") return undefined; const candidate = value as Record; try { return ["getItem", "setItem", "removeItem"].every( (method) => typeof Reflect.get(candidate, method) === "function", ) ? (value as Storage) : undefined; } catch { return undefined; } } /** * Runtime-aware transport factory. Feature gateway composition calls this * factory when a registered API capability is installed. */ export function createRuntimeHttpClient( context: RuntimeHttpContext, contract: RuntimeHttpContract = {}, ) { return createHttpClient({ baseUrl: context.runtime.config.API_BASE_URL, timeoutMs: context.runtime.config.REQUEST_TIMEOUT_MS, maxRetryAttempts: context.runtime.config.MAX_RETRY_ATTEMPTS, authSession: context.authSession, providerProfile: createRestProviderProfile( "PRIMARY_API", context.runtime.config.API_BASE_URL, ["omit"], ), fetcher: context.fetcher, clock: context.clock, scheduler: context.scheduler, diagnostics: context.diagnostics, telemetry: context.telemetry, ...contract, }); } export async function createRuntimeAdapters( context: RuntimeAdaptersContext, ) { const host = context.host ?? (globalThis as unknown as Record); const config = context.runtime.config; const externalOwner = externalOwnerFrom(host); const authSession = config.AUTH_MODE === "demo" ? createDemoSessionAdapter() : externalOwner ? createExternalAuthSessionAdapter(externalOwner) : createUnavailableSessionAdapter(); const diagnostics = createDiagnosticsAdapter(); const telemetry = createTelemetryAdapter({ enabled: config.TELEMETRY_ENABLED, endpoint: config.TELEMETRY_ENDPOINT, fetcher: context.fetcher, onDrop(event) { const attributes = event.attributes && typeof event.attributes === "object" ? event.attributes : {}; diagnostics.record({ level: "warn", eventId: "telemetry.delivery.dropped", context: attributes, }); }, }); const invalidationIndex = indexInvalidationRegistry(INVALIDATION_REGISTRY); const invalidationTopicVersions = indexInvalidationTopicVersions( INVALIDATION_REGISTRY, INVALIDATION_TOPIC_VERSIONS, ); const conditionalValidators = createConditionalValidatorStore(); const serverStateGeneration = createServerStateGenerationStore(() => { const queryClient = createQueryClient({ diagnostics }); const crossContextInvalidation = createBrowserCrossContextInvalidationFromHost({ ...(context.host === undefined ? {} : { host: context.host }), cacheEpoch: `release.${context.release.releaseId}`, topics: [...invalidationTopicVersions].map(([topic, topicVersion]) => Object.freeze({ topic, topicVersion, }), ), observe(observation) { if ( observation.outcome !== "FAILED" && observation.outcome !== "DEGRADED" ) { return; } diagnostics.record({ level: "warn", eventId: "cache.operation.failed", context: { operation: observation.operation, outcome: observation.outcome, reason: observation.reason, }, }); }, }); const queryInvalidation = createTanStackCacheCoordinator({ queryClient, invalidationIndex, topicVersions: invalidationTopicVersions, crossContext: crossContextInvalidation, diagnostics, }); return Object.freeze({ queryClient, queryInvalidation, crossContextStatus: () => crossContextInvalidation?.getStatus() ?? "DEGRADED_LOCAL_ONLY", }); }); const serverStateScope = createServerStateScopeRuntime({ session: authSession, queryInvalidation: { resetLocal: () => serverStateGeneration.resetCurrent(), }, participants: [ { order: 4, label: "conditional-validators", close: () => conditionalValidators.clear(), }, ], activateNextGeneration: () => serverStateGeneration.activateNext(), }); const storage = createBrowserStorageAdapter({ localStorage: storageOrUndefined(hostValue(host, "localStorage")), sessionStorage: storageOrUndefined( hostValue(host, "sessionStorage"), ), diagnostics, }); const releaseInfo = Object.freeze({ async getCurrent() { return toReleaseInfo(context.release); }, async refresh() { return toReleaseInfo( await fetchReleaseManifest(config.RELEASE_MANIFEST_URL, { fetcher: context.fetcher, buildId: context.release.buildId, releaseId: context.release.releaseId, }), ); }, }); const runtimeCapabilities = Object.freeze({ getSnapshot() { return describeRuntimeCapabilities( INSTALLED_RUNTIME_CAPABILITIES, config.CAPABILITY_OVERRIDES, ); }, }); const navigation = Object.freeze({ reload() { const location = host.location; if (!isRecord(location) || typeof location.reload !== "function") { throw new Error("Browser reload is unavailable"); } location.reload(); }, }); const contractHttp = createContractHttpExecutor({ baseUrl: config.API_BASE_URL, maxRetryAttempts: config.MAX_RETRY_ATTEMPTS, fetcher: context.fetcher, async attachCredentials(operation) { if (serverStateScope.getPhase() !== "READY") { return Object.freeze({ kind: "SCOPE_FENCED" as const }); } const state = authSession.getState(); if (state === "integration-failed") { return Object.freeze({ kind: "UNAVAILABLE" as const }); } if (state !== "authenticated") { return Object.freeze({ kind: "UNAUTHENTICATED" as const }); } try { const patch = await authSession.credentialPatch({ origin: new URL(config.API_BASE_URL).origin, method: operation.method, operationId: operation.operationId, }); if (serverStateScope.getPhase() !== "READY") { return Object.freeze({ kind: "SCOPE_FENCED" as const }); } return Object.freeze({ kind: "READY" as const, headers: patch.headers, credentials: "omit" as const, }); } catch { return Object.freeze({ kind: "UNAVAILABLE" as const }); } }, observe(observation) { try { diagnostics.record({ level: observation.outcome === "SUCCESS" ? "info" : "warn", eventId: "http.request.completed", context: { operation_id: observation.diagnosticsOperation, outcome: observation.outcome, attempts: observation.attempts, certainty: observation.certainty, }, }); } catch { // Diagnostics cannot change a contract execution outcome. } }, }); let contractExecutionSequence = 0; const contractOperations = Object.freeze({ async execute( operationId: string, input: unknown, executionContext: Readonly<{ signal?: AbortSignal }> = {}, ) { const operation = COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.get(operationId); if (!operation) { return Object.freeze({ kind: "CONTRACT_VIOLATION" as const, effect: "NOT_STARTED" as const, violation: Object.freeze({ kind: "FINAL_REQUEST_INVARIANT_FAILED" as const, operation: "REQUEST" as const, }), }); } contractExecutionSequence += 1; const intentId = `http-intent-${contractExecutionSequence}`; const isCommand = operation.contract.commandEffect !== null; const requiresKey = operation.contract.retrySemantics === "KEYED"; const outcome = await contractHttp.execute(operation, input, { scope: serverStateScope.getSnapshot(), ...(executionContext.signal === undefined ? {} : { signal: executionContext.signal }), ...(isCommand ? { intent: Object.freeze({ intentId, startedBy: "USER" as const, ...(requiresKey ? { idempotencyKey: `http-key-${contractExecutionSequence}` } : {}), }), } : {}), }); if (outcome.kind === "UNAUTHENTICATED") { authSession.onUnauthenticated(); } return outcome; }, }); const featureInputs = createInstalledFeatureInputs({ contractOperations, }); return Object.freeze({ outputPorts: Object.freeze({ session: authSession, preferences: storage, diagnostics, telemetry, releaseInfo, runtimeCapabilities, navigation, }), infrastructure: Object.freeze({ get queryClient() { return serverStateGeneration.getSnapshot().queryClient; }, get queryInvalidation() { return serverStateGeneration.getSnapshot().queryInvalidation; }, serverStateGeneration, serverStateScope, conditionalValidators, crossContextInvalidationStatus: () => serverStateGeneration.getSnapshot().crossContextStatus(), dispose() { conditionalValidators.clear(); serverStateScope.dispose(); serverStateGeneration.dispose(); }, }), featureInputs, }); }