diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index 644d96c2..c6a2f267 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -353,16 +353,33 @@ function projectExecutionOutcome( outcome.failure.kind, { effect: outcome.effect }, ); - case "CONTRACT_VIOLATION": + 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.kind), operationId, outcome.violation.kind, - { effect: outcome.effect }, + { + ...(httpStatus === undefined ? {} : { httpStatus }), + effect: outcome.effect, + }, ); + } } } +function isServerFailureStatus(status: number): boolean { + return status >= 500 || status === 408 || status === 425; +} + function failureKindForViolation( violation: Extract< HttpExecutionOutcome, @@ -385,6 +402,11 @@ function failureKindForViolation( case "PROBLEM_SCHEMA_INVALID": case "VALIDATOR_RUNTIME_FAILURE": return "SCHEMA_MISMATCH"; + // Rejected before dispatch: the request, not the server answer, was wrong. + case "FINAL_REQUEST_INVARIANT_FAILED": + case "MISSING_IDEMPOTENCY_KEY": + case "UNEXPECTED_IDEMPOTENCY_KEY": + return "VALIDATION_REJECTED"; default: return "ENVELOPE_MISMATCH"; } diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 08f82fec..992c8aa2 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -153,6 +153,11 @@ export type HttpExecutionOutcome = | Readonly<{ kind: "CONTRACT_VIOLATION"; violation: HttpContractViolation; + /** + * Present when an error status arrived without a usable problem body. + * A 5xx/408/425 here is a server outage, not a contract breach (R-3.3). + */ + metadata?: SafeResponseMetadata; effect: HttpEffectCertainty; }> | Readonly<{ @@ -305,9 +310,7 @@ function observationErrorKind( function observationStatus( outcome: HttpExecutionOutcome, ): number | undefined { - return outcome.kind === "SUCCESS" || outcome.kind === "PROBLEM" - ? outcome.metadata.status - : undefined; + return "metadata" in outcome ? outcome.metadata?.status : undefined; } export type ContractHttpExecutorDependencies = Readonly<{ @@ -1496,6 +1499,7 @@ async function admitProblem( "PROBLEM_SCHEMA_INVALID", "VALIDATION", postDispatchEffect(isCommand), + metadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: retryable, @@ -1508,6 +1512,7 @@ async function admitProblem( "CONTENT_TYPE_MISMATCH", "RESPONSE", postDispatchEffect(isCommand), + metadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: retryable, @@ -1522,6 +1527,7 @@ async function admitProblem( decoded.code, "RESPONSE", postDispatchEffect(isCommand), + metadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: retryable, @@ -1540,6 +1546,7 @@ async function admitProblem( "PROBLEM_SCHEMA_INVALID", "VALIDATION", postDispatchEffect(isCommand), + metadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: false, @@ -1556,6 +1563,7 @@ async function admitProblem( : "PROBLEM_SCHEMA_INVALID", "VALIDATION", postDispatchEffect(isCommand), + metadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: retryable, @@ -1618,10 +1626,12 @@ function violation( kind: HttpContractViolationKind, operation: HttpContractViolation["operation"], effect: HttpEffectCertainty, + metadata?: SafeResponseMetadata, ): HttpExecutionOutcome { return Object.freeze({ kind: "CONTRACT_VIOLATION" as const, violation: Object.freeze({ kind, operation }), + ...(metadata === undefined ? {} : { metadata }), effect, }); } diff --git a/tests/contract/reusable-capability/feature-http-binding.test.ts b/tests/contract/reusable-capability/feature-http-binding.test.ts index 271e090f..a2e65f58 100644 --- a/tests/contract/reusable-capability/feature-http-binding.test.ts +++ b/tests/contract/reusable-capability/feature-http-binding.test.ts @@ -189,6 +189,36 @@ describe("feature HTTP binding", () => { expect(result.error.code).toBe("MAPPING_INVARIANT_REJECTED"); }); + it.each([ + "FINAL_REQUEST_INVARIANT_FAILED", + "MISSING_IDEMPOTENCY_KEY", + "UNEXPECTED_IDEMPOTENCY_KEY", + ] as const)( + "does not report the request-side violation %s as a server envelope mismatch", + async (violationKind) => { + const scripted = scriptedExecutor( + Object.freeze({ + kind: "CONTRACT_VIOLATION" as const, + violation: Object.freeze({ + kind: violationKind, + operation: "REQUEST" as const, + }), + effect: "NOT_APPLICABLE" as const, + }), + ); + const binding = createFeatureHttpBinding(scripted.executor, OPERATIONS); + + const result = await binding.execute("LOAD_RESOURCE", { + resourceId: "resource-1", + }); + + expect(result).toMatchObject({ + ok: false, + error: { kind: "VALIDATION_REJECTED", code: violationKind }, + }); + }, + ); + it("lets the feature interpret a typed business problem", async () => { const scripted = scriptedExecutor( Object.freeze({ diff --git a/tests/unit/http-execution-v3.test.ts b/tests/unit/http-execution-v3.test.ts index fbc5f5aa..85df28f7 100644 --- a/tests/unit/http-execution-v3.test.ts +++ b/tests/unit/http-execution-v3.test.ts @@ -1,6 +1,14 @@ import { describe, expect, it, vi } from "vitest"; -import { createContractHttpExecutor } from "../../src/adapters/http/http-execution-v3.ts"; +import { + createFeatureHttpBinding, + defineFeatureHttpOperation, +} from "../../src/adapters/http/feature-http-binding.ts"; +import { + createContractHttpExecutor, + type HttpExecutionObservation, +} from "../../src/adapters/http/http-execution-v3.ts"; +import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts"; import type { InstalledHttpContract } from "../../src/contracts/external-contract-runtime.ts"; import { TEST_CREATE_HTTP_CONTRACT, @@ -777,3 +785,60 @@ describe("descriptor-driven HTTP execution lifetime", () => { }); }); }); + +/** + * R-3.3. A gateway 5xx/408 with an HTML, empty or broken body is a server + * outage. It must keep its status and stay retryable instead of surfacing as a + * "contact support" contract breach. + */ +describe("gateway failures without a usable problem body", () => { + it.each([ + [502, "text/html", "Bad Gateway"], + [503, "application/json", ""], + [504, "application/json", "{"], + [408, "text/plain", "timeout"], + ])( + "ends a %i response as a retryable server failure with its status", + async (status, contentType, body) => { + const fetcher = vi.fn( + async () => + new Response(body, { status, headers: { "content-type": contentType } }), + ); + const observations: HttpExecutionObservation[] = []; + const executor = createContractHttpExecutor({ + baseUrl: "https://api.example/", + maxRetryAttempts: 1, + attachCredentials: () => ({ kind: "READY", headers: {} }), + fetcher, + sleep: async () => {}, + observe: (observation) => void observations.push(observation), + }); + const list = defineFeatureHttpOperation({ + contract: TEST_LIST_HTTP_CONTRACT, + routeId: ROUTE_ID, + mapSuccess: (value) => mappingSuccess(value), + }); + const binding = createFeatureHttpBinding( + { + execute: (contract, input, context) => + executor.execute(contract, input, { ...context, scope }), + }, + { [list.operationId]: list }, + ); + + const result = await binding.execute(list.operationId, { limit: 20 }); + + expect(fetcher).toHaveBeenCalledTimes(2); + expect(observations.at(-1)?.status).toBe(status); + expect(result).toMatchObject({ + ok: false, + error: { + kind: "SERVER_FAILURE", + httpStatus: status, + retryable: true, + action: "retry", + }, + }); + }, + ); +});