import type { InstalledHttpContract, } from "../../contracts/external-contract-runtime.ts"; import type { Result } from "../../contracts/result.ts"; import type { MappingResult } from "../../contracts/boundary-mapper.ts"; import { createFailure, kindForStatus, type ApiFailure, type FailureEffectCertainty, type FailureKind, } from "../../contracts/errors.ts"; import type { MutationIntent } from "../../contracts/mutation-intent.ts"; import type { HttpExecutionOutcome, SafeResponseMetadata, } from "./http-execution-v3.ts"; type ValidatorValue = Validator extends Readonly<{ safeParse(value: unknown): infer ParseResult; }> ? Extract< ParseResult, Readonly<{ success: true; data: unknown }> > extends Readonly<{ data: infer Value }> ? Value : never : never; export type HttpContractInput = Contract extends Readonly<{ contract: Readonly<{ inputValidator: infer Validator }>; }> ? ValidatorValue : never; export type HttpContractWireOutput = Contract extends Readonly<{ contract: Readonly<{ outputValidator: infer Validator }>; }> ? ValidatorValue : never; export type HttpContractProblem = Contract extends Readonly<{ contract: Readonly<{ problemValidator: infer Validator }>; }> ? ValidatorValue : never; export type HttpContractOperationId = Contract extends Readonly<{ contract: Readonly<{ operationId: infer OperationId extends string }>; }> ? OperationId : never; export type InstalledHttpOperationExecutor = Readonly<{ execute( contract: InstalledHttpContract, input: Input, context: Readonly<{ routeId: string; signal?: AbortSignal; intent?: MutationIntent; }>, ): Promise>; }>; export type FeatureHttpProblemMapping = Readonly<{ kind: FailureKind; code: string; }>; type FeatureHttpOperationSpec< Contract, Value, RouteId extends string, > = Readonly<{ contract: Contract; routeId: RouteId; mapSuccess( value: HttpContractWireOutput, ): MappingResult; mapProblem?( problem: HttpContractProblem, metadata: SafeResponseMetadata, ): FeatureHttpProblemMapping | undefined; }>; export type FeatureHttpOperation< Contract, Value, RouteId extends string = string, > = FeatureHttpOperationSpec & Readonly<{ operationId: HttpContractOperationId; /** * Compile-time only carrier. The runtime object has no extra type payload; * the contract remains the authority for input/wire/problem types. */ __types?: Readonly<{ value: Value; }>; }>; type ContractValidity = HttpContractOperationId extends never ? never : HttpContractInput extends never ? never : HttpContractWireOutput extends never ? never : HttpContractProblem extends never ? never : unknown; function defineFeatureHttpOperationForRoute< const RouteId extends string, const Contract, Value, >( spec: FeatureHttpOperationSpec & ContractValidity, ): FeatureHttpOperation { return Object.freeze({ ...spec, operationId: (spec.contract as Readonly<{ contract: Readonly<{ operationId: HttpContractOperationId }>; }>).contract.operationId, }) as FeatureHttpOperation; } export function defineFeatureHttpOperation< const Contract, Value, const RouteId extends string, >( spec: FeatureHttpOperationSpec & ContractValidity, ): FeatureHttpOperation { return defineFeatureHttpOperationForRoute(spec); } /** * Feature-local route typing without introducing a dependency from the HTTP * capability to the presentation route registry. */ export function defineFeatureHttpOperationForRoutes< const RouteId extends string, >() { return function defineRouteBoundFeatureHttpOperation< const Contract, Value, >( spec: FeatureHttpOperationSpec & ContractValidity, ): FeatureHttpOperation { return defineFeatureHttpOperationForRoute(spec); }; } type FeatureHttpOperationShape = Readonly<{ contract: object; operationId: string; routeId: string; mapSuccess: (...args: never[]) => unknown; mapProblem?: (...args: never[]) => unknown; }>; type OperationContract = Operation extends Readonly<{ contract: infer Contract }> ? Contract : never; type OperationInput = HttpContractInput>; type OperationWireOutput = HttpContractWireOutput>; type OperationProblem = HttpContractProblem>; type OperationValue = Operation extends FeatureHttpOperation ? Value : never; type InvalidOperationRegistryKeys< Operations extends Readonly>, > = { [OperationId in keyof Operations & string]: OperationId extends Operations[OperationId]["operationId"] ? Operations[OperationId]["operationId"] extends OperationId ? never : OperationId : OperationId; }[keyof Operations & string]; type ValidOperationRegistry< Operations extends Readonly>, > = InvalidOperationRegistryKeys extends never ? unknown : Readonly<{ __operationRegistryKeyMismatch: InvalidOperationRegistryKeys; }>; export type FeatureHttpBinding< Operations extends Readonly>, > = Readonly<{ execute( operationId: OperationId, input: OperationInput, context?: Readonly<{ signal?: AbortSignal; intent?: MutationIntent; }>, ): Promise, ApiFailure>>; }>; /** * Capability-specific feature binding for the installed HTTP runtime. * * The installed contract is the single type authority. A feature contributes * only a route identity plus wire-to-domain/problem interpretation. Transport, * retry, validation and effect-certainty stay in the reusable HTTP capability. */ export function createFeatureHttpBinding< const Operations extends Readonly>, >( executor: InstalledHttpOperationExecutor, operations: Operations & ValidOperationRegistry, ): FeatureHttpBinding { for (const [registryId, operation] of Object.entries(operations)) { if (registryId !== operation.operationId) { throw new TypeError( `Feature HTTP operation key mismatch: ${registryId} !== ${operation.operationId}`, ); } } return Object.freeze({ async execute( operationId: OperationId, input: OperationInput, context: Readonly<{ signal?: AbortSignal; intent?: MutationIntent; }> = {}, ): Promise, ApiFailure>> { const operation = operations[operationId]; type SelectedOperation = Operations[OperationId]; type Input = OperationInput; type WireOutput = OperationWireOutput; type Problem = OperationProblem; type Value = OperationValue; const contract = operation.contract as InstalledHttpContract< Input, WireOutput, Problem >; const outcome = await executor.execute(contract, input, { routeId: operation.routeId, ...(context.signal === undefined ? {} : { signal: context.signal }), ...(context.intent === undefined ? {} : { intent: context.intent }), }); return projectExecutionOutcome( operation.operationId, operation.mapSuccess as (value: WireOutput) => MappingResult, operation.mapProblem as | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, outcome, ); }, }); } function projectExecutionOutcome( operationId: string, mapSuccess: (value: WireOutput) => MappingResult, mapProblem: | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, ): Result { switch (outcome.kind) { case "SUCCESS": { const mapped = mapSuccess(outcome.value); return mapped.ok ? Object.freeze({ ok: true as const, value: mapped.value }) : failure( "MAPPING_CONTRACT_VIOLATION", operationId, mapped.code, { effect: outcome.effect }, ); } case "PROBLEM": { const mapped = mapProblem?.(outcome.problem, outcome.metadata); return failure( mapped?.kind ?? kindForStatus(outcome.metadata.status), operationId, mapped?.code ?? "CONTRACT_PROBLEM", { httpStatus: outcome.metadata.status, effect: outcome.effect }, ); } case "UNAUTHENTICATED": return failure("AUTH_REQUIRED", operationId, "UNAUTHENTICATED", { effect: outcome.effect, }); case "FORBIDDEN": return failure("FORBIDDEN", operationId, "FORBIDDEN", { effect: outcome.effect, }); case "RATE_LIMITED": return failure("RATE_LIMITED", operationId, "RATE_LIMITED", { ...(outcome.retryAfterMs === undefined ? {} : { retryAfterMs: outcome.retryAfterMs }), effect: outcome.effect, }); case "CANCELLED": return failure("REQUEST_ABORTED", operationId, "REQUEST_ABORTED", { effect: outcome.effect, }); case "AUTH_INTEGRATION_FAILURE": return failure( "AUTH_INTEGRATION_FAILURE", operationId, outcome.reason, { effect: outcome.effect }, ); case "TRANSPORT_FAILURE": return failure( outcome.failure.kind === "TIMEOUT" ? "REQUEST_TIMEOUT" : outcome.failure.kind === "ABORTED_BY_SCOPE" ? "SCOPE_GENERATION_CHANGED" : "NETWORK_UNREACHABLE", operationId, outcome.failure.kind, { effect: outcome.effect }, ); case "CONTRACT_VIOLATION": return failure( failureKindForViolation(outcome.violation.kind), operationId, outcome.violation.kind, { effect: outcome.effect }, ); } } function failureKindForViolation( violation: Extract< HttpExecutionOutcome, { kind: "CONTRACT_VIOLATION" } >["violation"]["kind"], ): FailureKind { switch (violation) { case "CONTENT_TYPE_MISMATCH": return "CONTENT_TYPE_MISMATCH"; case "RESPONSE_TOO_LARGE": return "RESPONSE_BODY_LIMIT"; case "UTF8_INVALID": case "JSON_INVALID": return "MALFORMED_JSON"; case "MAPPING_CONTRACT_VIOLATION": return "MAPPING_CONTRACT_VIOLATION"; case "SCOPE_FENCED": return "SCOPE_GENERATION_CHANGED"; case "SUCCESS_SCHEMA_INVALID": case "PROBLEM_SCHEMA_INVALID": case "VALIDATOR_RUNTIME_FAILURE": return "SCHEMA_MISMATCH"; default: return "ENVELOPE_MISMATCH"; } } function failure( kind: FailureKind, operationId: string, code: string, details: Readonly<{ httpStatus?: number; retryAfterMs?: number; effect?: FailureEffectCertainty; }> = {}, ): Result { return Object.freeze({ ok: false as const, error: createFailure(kind, operationId, 0, { code, ...details }), }); }