fix(http): classify 408/425 error envelopes as server failures and honor 503 Retry-After (R3-1)

- client: the final V2 classification step maps a 408/425 response with a
  valid error envelope to SERVER_FAILURE (via gatewayFailureOr), keeping
  the backend code and request/trace ids. contracts/errors.ts is unchanged.
- client: Retry-After is also parsed (kernel parser) on 503, so the retry
  waits at least that long and the 30s ceiling applies. 502/504 keep the
  local backoff.

RED (before the fix, 14 failing in tests/integration/http-client.test.ts):
- safe GET on a 408/425 error envelope: kind UNKNOWN_CLIENT_FAILURE,
  fetched once (expected SERVER_FAILURE, 3 fetches, code UPSTREAM_BUSY)
- none/keyed command on a 408/425 error envelope: kind
  UNKNOWN_CLIENT_FAILURE; keyed fetched once instead of 3 times
- 408/425 error envelope with Retry-After: 2: not retried
- 503 (gateway body and envelope) with Retry-After: 2: slept 125ms
  instead of 2000ms
- 408/425 envelope and 503 with Retry-After: 31: retryAfterMs missing
Pins that passed before and after: a non-idempotent command is sent once
on 408/425/503 gateway bodies and on a 503 envelope; 502/504 ignore
Retry-After (125ms).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 15:19:42 +09:00
co-authored by Claude Opus 5.5
parent db1bc1fc7e
commit 108ac6a606
2 changed files with 111 additions and 44 deletions
+6 -3
View File
@@ -864,8 +864,9 @@ async function parseResponse(
) => MappingResult<unknown>,
now: number,
): Promise<HttpResult> {
// R3-1. Retry-After is read only where the retry policy honors it.
const retryAfterMs = [408, 425, 429].includes(response.status)
// R3-1. Retry-After is read only where the retry policy honors it; 502/504
// keep the local backoff.
const retryAfterMs = [408, 425, 429, 503].includes(response.status)
? (parseRetryAfterDelay(response.headers.get("retry-after"), now) ??
undefined)
: undefined;
@@ -992,7 +993,9 @@ async function parseResponse(
};
}
const kind = statusKind(response.status);
// R3-1. V2 treats a 408/425 error envelope as the same server failure as a
// gateway body; the shared status map in contracts is not changed.
const kind = gatewayFailureOr(response.status, statusKind(response.status));
const backendError =
envelopeRecord.error && typeof envelopeRecord.error === "object"
? (envelopeRecord.error as Record<string, unknown>)
+105 -41
View File
@@ -199,24 +199,77 @@ describe("shared HTTP client", () => {
},
);
// R3-1. 408/425 follow the retry rule of the operation: a keyed command may
// replay, a non-idempotent command is never replayed.
it.each([
{ status: 408, idempotency: "none", fetches: 1 },
{ status: 425, idempotency: "none", fetches: 1 },
{ status: 408, idempotency: "keyed", fetches: 3 },
{ status: 425, idempotency: "keyed", fetches: 3 },
] as const)(
"sends a $idempotency command $fetches time(s) on $status",
async ({ status, idempotency, fetches }) => {
const errorEnvelope = {
success: false,
error: { code: "UPSTREAM_BUSY" },
meta: { requestId: "request-1", traceId: "trace-1" },
};
// A gateway body (not an envelope) or a valid V2 error envelope.
function busyResponse(
status: number,
envelope: boolean,
headers: Record<string, string> = {},
) {
return envelope
? HttpResponse.json(errorEnvelope, { status, headers })
: new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain", ...headers },
});
}
const busyCases = [408, 425, 503].flatMap((status) => [
{ status, envelope: false },
{ status, envelope: true },
]);
// R3-1. A 408/425 with a valid error envelope is a server failure in V2 and
// keeps the backend code the envelope carries.
it.each([408, 425, 503])(
"retries a safe request on a %i error envelope and keeps its code",
async (status) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return busyResponse(status, true);
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
});
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: false,
error: {
kind: "SERVER_FAILURE",
code: "UPSTREAM_BUSY",
httpStatus: status,
requestId: "request-1",
},
});
expect(fetched).toBe(3);
},
);
// R3-1. 408/425/503 follow the retry rule of the operation: a keyed command
// may replay, a non-idempotent command is never replayed.
it.each(
busyCases.flatMap((busy) => [
{ ...busy, idempotency: "none" as const, fetches: 1 },
{ ...busy, idempotency: "keyed" as const, fetches: 3 },
]),
)(
"sends a $idempotency command $fetches time(s) on $status (envelope: $envelope)",
async ({ status, envelope, idempotency, fetches }) => {
let fetched = 0;
server.use(
http.post("https://api.test/api/entities", () => {
fetched += 1;
return new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain" },
});
return busyResponse(status, envelope);
}),
);
const client = testClient({
@@ -251,27 +304,28 @@ describe("shared HTTP client", () => {
});
}
// R3-1. The retry waits at least the Retry-After of a 408/425, under the
// same 30s ceiling as a 429.
it.each([408, 425])(
"waits for the Retry-After of a %i before the retry",
async (status) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return fetched === 1
? new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain", "Retry-After": "2" },
})
: HttpResponse.json({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
function listAfter(first: () => Response) {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return fetched === 1
? first()
: HttpResponse.json({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
}
// R3-1. The retry waits at least the Retry-After of a 408/425/503, under
// the same 30s ceiling as a 429.
it.each(busyCases)(
"waits for the Retry-After of a $status (envelope: $envelope)",
async ({ status, envelope }) => {
listAfter(() => busyResponse(status, envelope, { "Retry-After": "2" }));
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
@@ -280,17 +334,27 @@ describe("shared HTTP client", () => {
},
);
it.each([408, 425])(
"does not retry a %i whose Retry-After exceeds 30 seconds",
// R3-1. 502/504 keep the local backoff whatever Retry-After says.
it.each([502, 504])(
"ignores the Retry-After of a %i",
async (status) => {
listAfter(() => busyResponse(status, true, { "Retry-After": "2" }));
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([125]);
},
);
it.each(busyCases)(
"does not retry a $status whose Retry-After exceeds 30 seconds (envelope: $envelope)",
async ({ status, envelope }) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain", "Retry-After": "31" },
});
return busyResponse(status, envelope, { "Retry-After": "31" });
}),
);
const delays: number[] = [];