import type { InstalledHttpContract, } from "../../contracts/external-contract-runtime.ts"; import type { Result } from "../../contracts/result.ts"; import type { BoundaryMappingResult } from "../../contracts/boundary-mapper.ts"; import { createFailure, kindForStatus, type AppFailure, type FailureEffectCertainty, type FailureKind, type ValidationIssue, } from "../../contracts/errors.ts"; import type { MutationIntent } from "../../contracts/mutation-intent.ts"; import type { ExecutionContext } from "../../platform/execution/execution-context.ts"; import { envelopeFailureReading, type EnvelopePage, } from "./backend-envelope.ts"; import type { HttpContractViolation, HttpExecutionOutcome, HttpRequestRejectionReason, 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; execution?: ExecutionContext; }>, ): Promise>; }>; export type FeatureHttpProblemMapping = Readonly<{ kind: FailureKind; code: string; /** * 03-04. Field issues read from the problem body. Only `path` and `code` * survive; `createFailure` bounds them with `projectValidationIssues`. */ validationIssues?: readonly ValidationIssue[]; }>; /** * 1103/03-02. What a success answer carries besides its validated value. */ export type FeatureHttpSuccessContext = Readonly<{ /** * An Envelope page list's `meta.page` (the paired backend's offset page: * `number`, `size`, `total`, `sort`). Absent on every other answer. */ page?: EnvelopePage; }>; const NO_SUCCESS_CONTEXT: FeatureHttpSuccessContext = Object.freeze({}); type FeatureHttpOperationSpec< Contract, Value, RouteId extends string, > = Readonly<{ contract: Contract; routeId: RouteId; mapSuccess( value: HttpContractWireOutput, context: FeatureHttpSuccessContext, ): BoundaryMappingResult; 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; execution?: ExecutionContext; }>, ): Promise, AppFailure>>; }>; /** * 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; execution?: ExecutionContext; }> = {}, ): Promise, AppFailure>> { 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 }), ...(context.execution === undefined ? {} : { execution: context.execution }), }); return projectExecutionOutcome( operation.operationId, operation.mapSuccess as ( value: WireOutput, context: FeatureHttpSuccessContext, ) => BoundaryMappingResult, problemMapper( operation.mapProblem as | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, contract.contract.responseEnvelope === "ENVELOPE_V1", ), outcome, ); }, }); } /** * 1101 README 14.3. An Envelope operation's problem is the backend `error` * object, so what the feature does not map still reads as the backend means * it: its code, field issues from a validation failure, and the status kind. */ function problemMapper( mapProblem: | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, enveloped: boolean, ): | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined { if (!enveloped) return mapProblem; return (problem, metadata) => mapProblem?.(problem, metadata) ?? envelopeProblemMapping(problem, metadata.status); } function envelopeProblemMapping( problem: unknown, status: number, ): FeatureHttpProblemMapping | undefined { if (!problem || typeof problem !== "object") return undefined; const { code, details } = problem as Readonly>; return typeof code === "string" && /^[A-Z0-9_]{1,64}$/u.test(code) ? envelopeFailureReading(status, { code, details }) : undefined; } /** * 03-03. A failure carries the server's echoed correlation id as `requestId`, * so the support reference a user reports points at one server log entry. * 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops * the header) it is the id the request carried. * 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`. */ function projectExecutionOutcome( operationId: string, mapSuccess: ( value: WireOutput, context: FeatureHttpSuccessContext, ) => BoundaryMappingResult, mapProblem: | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, ): Result { const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome); const metadata = "metadata" in outcome ? outcome.metadata : undefined; const requestId = metadata?.correlationReference ?? outcome.sentRequestId; const traceId = metadata?.traceReference; return projected.ok || (requestId === undefined && traceId === undefined) ? projected : Object.freeze({ ok: false as const, error: Object.freeze({ ...projected.error, ...(requestId === undefined ? {} : { requestId }), ...(traceId === undefined ? {} : { traceId }), }), }); } function projectOutcome( operationId: string, mapSuccess: ( value: WireOutput, context: FeatureHttpSuccessContext, ) => BoundaryMappingResult, mapProblem: | (( problem: Problem, metadata: SafeResponseMetadata, ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, ): Result { // A throwing feature mapper is a mapping defect, not a transport failure: it // must not reject and lose the effect the server already confirmed. const mapperThrew = ( effect: FailureEffectCertainty, httpStatus: number, ): Result => failure( "MAPPING_CONTRACT_VIOLATION", operationId, "MAPPING_CONTRACT_VIOLATION", { httpStatus, effect }, ); switch (outcome.kind) { case "SUCCESS": { let mapped: BoundaryMappingResult; try { mapped = mapSuccess( outcome.value, outcome.page === undefined ? NO_SUCCESS_CONTEXT : Object.freeze({ page: outcome.page }), ); } catch { return mapperThrew(outcome.effect, outcome.metadata.status); } return mapped.ok ? Object.freeze({ ok: true as const, value: mapped.value }) : failure( "MAPPING_CONTRACT_VIOLATION", operationId, mapped.code, { effect: outcome.effect }, ); } case "PROBLEM": { let mapped: FeatureHttpProblemMapping | undefined; try { mapped = mapProblem?.(outcome.problem, outcome.metadata); } catch { return mapperThrew(outcome.effect, outcome.metadata.status); } return failure( mapped?.kind ?? kindForStatus(outcome.metadata.status), operationId, mapped?.code ?? "CONTRACT_PROBLEM", { httpStatus: outcome.metadata.status, // 백엔드 1101/02-01. A resend of an unknown answer waits on it. ...(outcome.metadata.retryAfterMs === undefined ? {} : { retryAfterMs: outcome.metadata.retryAfterMs }), effect: outcome.effect, ...(mapped?.validationIssues === undefined ? {} : { validationIssues: mapped.validationIssues }), }, ); } 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": { const httpStatus = outcome.metadata?.status; // R-3.3. A gateway 5xx/408/425 with an HTML or empty body is a server // outage: keep its status and retryability instead of "contact support". if (httpStatus !== undefined && isServerFailureStatus(httpStatus)) { return failure("SERVER_FAILURE", operationId, outcome.violation.kind, { httpStatus, effect: outcome.effect, }); } return failure( failureKindForViolation(outcome.violation), operationId, outcome.violation.kind, { ...(httpStatus === undefined ? {} : { httpStatus }), effect: outcome.effect, }, ); } } } function isServerFailureStatus(status: number): boolean { return status >= 500 || status === 408 || status === 425; } /** * 03-02. Pre-dispatch refusals the user can fix by changing what they entered. * Every other refusal reason is a wiring defect in this client, and a refusal * without a reason keeps the input reading it always had. */ const USER_INPUT_REJECTIONS: ReadonlySet = new Set([ "INPUT_INVALID", "PATH_VALUE_INVALID", "QUERY_TOO_LARGE", "URL_TOO_LARGE", "REQUEST_BODY_TOO_LARGE", ]); function failureKindForViolation(violation: HttpContractViolation): FailureKind { switch (violation.kind) { 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"; // Rejected before dispatch: the request, not the server answer, was wrong. // 03-02. Only input the user can change is "input rejected"; a client // wiring defect (contract not installed, path template and projection // disagree, intent policy disagrees with the contract) cannot be fixed by // the user. case "FINAL_REQUEST_INVARIANT_FAILED": return violation.reason === undefined || USER_INPUT_REJECTIONS.has(violation.reason) ? "VALIDATION_REJECTED" : "UNKNOWN_CLIENT_FAILURE"; case "MISSING_IDEMPOTENCY_KEY": case "UNEXPECTED_IDEMPOTENCY_KEY": return "UNKNOWN_CLIENT_FAILURE"; default: return "ENVELOPE_MISMATCH"; } } function failure( kind: FailureKind, operationId: string, code: string, details: Readonly<{ httpStatus?: number; retryAfterMs?: number; effect?: FailureEffectCertainty; validationIssues?: readonly ValidationIssue[]; }> = {}, ): Result { return Object.freeze({ ok: false as const, error: createFailure(kind, operationId, 0, { code, ...details }), }); }