From 861edd4fe5786b4e311cd9173fe5e75e1aef01ba Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 12:18:44 +0900 Subject: [PATCH] fix(http): keep status of a 5xx without a usable problem body (R-3.3) A gateway 502/503/504 (or 408/425) with an HTML, empty or broken body ended as CONTRACT_VIOLATION without response metadata, so httpStatus and http_status_group were lost, and the feature binding turned it into a non-retryable "contact support" failure. Request-side violations (FINAL_REQUEST_INVARIANT_FAILED, MISSING/UNEXPECTED_IDEMPOTENCY_KEY) fell through to ENVELOPE_MISMATCH, a server-response error. - V3: violations raised while admitting an error-status response now carry the response `metadata` (additive optional field on CONTRACT_VIOLATION). The observation status reads `metadata` from any outcome that has it, so telemetry keeps http_status_group (this also gives a server 401 "4xx"). - Binding: a violation whose status is 5xx/408/425 becomes SERVER_FAILURE with httpStatus (retryable, action "retry" unless the effect is uncertain). Other violations keep their kind and now include httpStatus when known. Request-side violations map to VALIDATION_REJECTED. RED before fix: http-execution-v3.test.ts "ends a 502/503/504/408 response as a retryable server failure with its status" (observation status undefined, binding kind CONTENT_TYPE_MISMATCH/SCHEMA_MISMATCH/...), feature-http-binding.test.ts "does not report the request-side violation ... as a server envelope mismatch" (got ENVELOPE_MISMATCH). Gates: check:architecture, check:types:app, check:types:test, lint, test:component, test:integration, test:contract, test:platform, test:reference-feature pass (reference-page "mounts list and detail keys" timed out once under load avg ~50 and passed on rerun). test:unit passes except removal-fixture.test.ts (needs generated artifacts/ release evidence absent in a fresh worktree; unrelated). Co-Authored-By: Claude Opus 5.5 --- src/adapters/http/feature-http-binding.ts | 26 ++++++- src/adapters/http/http-execution-v3.ts | 16 ++++- .../feature-http-binding.test.ts | 30 +++++++++ tests/unit/http-execution-v3.test.ts | 67 ++++++++++++++++++- 4 files changed, 133 insertions(+), 6 deletions(-) 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", + }, + }); + }, + ); +});