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 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
70158d17c1
commit
861edd4fe5
@@ -353,16 +353,33 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
|
||||
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<unknown, unknown>,
|
||||
@@ -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";
|
||||
}
|
||||
|
||||
@@ -153,6 +153,11 @@ export type HttpExecutionOutcome<Value, Problem> =
|
||||
| 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<unknown, unknown>,
|
||||
): 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<Input, WireOutput, Problem>(
|
||||
"PROBLEM_SCHEMA_INVALID",
|
||||
"VALIDATION",
|
||||
postDispatchEffect(isCommand),
|
||||
metadata,
|
||||
),
|
||||
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
|
||||
retryHint: retryable,
|
||||
@@ -1508,6 +1512,7 @@ async function admitProblem<Input, WireOutput, Problem>(
|
||||
"CONTENT_TYPE_MISMATCH",
|
||||
"RESPONSE",
|
||||
postDispatchEffect(isCommand),
|
||||
metadata,
|
||||
),
|
||||
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
|
||||
retryHint: retryable,
|
||||
@@ -1522,6 +1527,7 @@ async function admitProblem<Input, WireOutput, Problem>(
|
||||
decoded.code,
|
||||
"RESPONSE",
|
||||
postDispatchEffect(isCommand),
|
||||
metadata,
|
||||
),
|
||||
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
|
||||
retryHint: retryable,
|
||||
@@ -1540,6 +1546,7 @@ async function admitProblem<Input, WireOutput, Problem>(
|
||||
"PROBLEM_SCHEMA_INVALID",
|
||||
"VALIDATION",
|
||||
postDispatchEffect(isCommand),
|
||||
metadata,
|
||||
),
|
||||
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
|
||||
retryHint: false,
|
||||
@@ -1556,6 +1563,7 @@ async function admitProblem<Input, WireOutput, Problem>(
|
||||
: "PROBLEM_SCHEMA_INVALID",
|
||||
"VALIDATION",
|
||||
postDispatchEffect(isCommand),
|
||||
metadata,
|
||||
),
|
||||
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
|
||||
retryHint: retryable,
|
||||
@@ -1618,10 +1626,12 @@ function violation<Value, Problem>(
|
||||
kind: HttpContractViolationKind,
|
||||
operation: HttpContractViolation["operation"],
|
||||
effect: HttpEffectCertainty,
|
||||
metadata?: SafeResponseMetadata,
|
||||
): HttpExecutionOutcome<Value, Problem> {
|
||||
return Object.freeze({
|
||||
kind: "CONTRACT_VIOLATION" as const,
|
||||
violation: Object.freeze({ kind, operation }),
|
||||
...(metadata === undefined ? {} : { metadata }),
|
||||
effect,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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<ResourceWire, ResourceProblem>(
|
||||
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<ResourceWire, ResourceProblem>(
|
||||
Object.freeze({
|
||||
|
||||
@@ -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", "<html>Bad Gateway</html>"],
|
||||
[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",
|
||||
},
|
||||
});
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user