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:
co-authored by
Claude Opus 5.5
parent
db1bc1fc7e
commit
108ac6a606
@@ -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>)
|
||||
|
||||
@@ -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[] = [];
|
||||
|
||||
Reference in New Issue
Block a user