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:
DongHyeonka
2026-09-24 12:25:01 +09:00
co-authored by Claude Opus 5.5
parent 70158d17c1
commit 861edd4fe5
4 changed files with 133 additions and 6 deletions
+24 -2
View File
@@ -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";
}
+13 -3
View File
@@ -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,
});
}