fix(http): retry 408/425 server failures and parse Retry-After with the kernel (R3-1)

- retry-policy: a SERVER_FAILURE with status 408/425 follows the
  502/503/504 rule (safe or keyed only; never idempotency "none" or
  retry "never"). Retry-After is honored and its 30s ceiling applies to
  any failure that carries it, not only RATE_LIMITED.
- client: Retry-After is parsed by platform/retry-after.ts for
  408/425/429, on every failure path (gateway bodies included).
  The local parseRetryAfterHeader is removed.

RED (before the fix, 15 failing):
- 408/425 gateway body on a safe GET: expected 3 fetches, got 1
- keyed command on 408/425: expected 3 fetches, got 1
- 408/425 with Retry-After: 2: expected ok after a 2000ms wait, got the
  first failure
- 408/425 with Retry-After: 31: retryAfterMs missing on the failure
- 429 Retry-After "1.5": slept 1500ms instead of the 125ms backoff;
  "Thursday, 01-Jan-70 00:00:05 GMT": slept 5000ms; "1e3", "0x10",
  "-1", "2099-01-01T00:00:00Z": accepted by the old parser, so the
  request was not retried with the 125ms backoff
- unit shouldRetry(safe, SERVER_FAILURE 408): false
Non-idempotent command on 408/425 stays 1 fetch (pinned, passed before
and after).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 15:16:56 +09:00
co-authored by Claude Opus 5.5
parent e0b20f50db
commit db1bc1fc7e
4 changed files with 194 additions and 21 deletions
+14 -14
View File
@@ -7,6 +7,7 @@ import {
} from "../../contracts/errors.ts";
import { mapOperationPayload } from "./resource-mapper.ts";
import { retryDelay, shouldRetry } from "./retry-policy.ts";
import { parseRetryAfterDelay } from "../platform/retry-after.ts";
import {
validateEnvelope,
validateOperationPayload,
@@ -863,6 +864,11 @@ 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)
? (parseRetryAfterDelay(response.headers.get("retry-after"), now) ??
undefined)
: undefined;
const contentType = mediaType(response.headers.get("content-type"));
const acceptedMedia = operation.responseMediaTypes ?? ["application/json"];
if (!contentType || !acceptedMedia.includes(contentType)) {
@@ -876,7 +882,11 @@ async function parseResponse(
gatewayFailureOr(response.status, "CONTENT_TYPE_MISMATCH"),
operation.operationId,
attempt,
{ code: "CONTENT_TYPE_MISMATCH", httpStatus: response.status },
{
code: "CONTENT_TYPE_MISMATCH",
httpStatus: response.status,
retryAfterMs,
},
),
};
}
@@ -892,7 +902,7 @@ async function parseResponse(
gatewayFailureOr(response.status, decoded.code),
operation.operationId,
attempt,
{ code: decoded.code, httpStatus: response.status },
{ code: decoded.code, httpStatus: response.status, retryAfterMs },
),
};
}
@@ -911,6 +921,7 @@ async function parseResponse(
{
code: response.ok ? "ENVELOPE_MISMATCH" : "HTTP_FAILURE",
httpStatus: response.status,
retryAfterMs,
},
),
};
@@ -982,7 +993,6 @@ async function parseResponse(
}
const kind = statusKind(response.status);
const retryAfter = response.headers.get("retry-after");
const backendError =
envelopeRecord.error && typeof envelopeRecord.error === "object"
? (envelopeRecord.error as Record<string, unknown>)
@@ -994,10 +1004,7 @@ async function parseResponse(
httpStatus: response.status,
requestId: safeMeta(envelopeRecord.meta).requestId,
traceId: safeMeta(envelopeRecord.meta).traceId,
retryAfterMs:
response.status === 429 && retryAfter
? parseRetryAfterHeader(retryAfter, now)
: undefined,
retryAfterMs,
validationIssues:
response.status === 422
? safeValidationIssues(backendError.details)
@@ -1081,13 +1088,6 @@ function safeMeta(meta: unknown): Record<string, string> {
};
}
function parseRetryAfterHeader(value: string, now: number): number | undefined {
const seconds = Number(value);
if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1_000;
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
}
function safeIdentifier(
value: string,
property: "requestId" | "traceId",
+1 -4
View File
@@ -47,12 +47,11 @@ export function shouldRetry(
if (
failure.kind === "SERVER_FAILURE" &&
failure.httpStatus !== undefined &&
![502, 503, 504].includes(failure.httpStatus)
![408, 425, 502, 503, 504].includes(failure.httpStatus)
) {
return false;
}
if (
failure.kind === "RATE_LIMITED" &&
typeof failure.retryAfterMs === "number" &&
failure.retryAfterMs > 30_000
) {
@@ -68,8 +67,6 @@ export function retryDelay(
now = Date.now(),
): number {
const localBackoff = calculateBackoff(retryIndex, random);
if (failure.kind !== "RATE_LIMITED") return localBackoff;
const retryAfterMs =
typeof failure.retryAfterMs === "number"
? failure.retryAfterMs
+155 -3
View File
@@ -3,7 +3,10 @@ import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import { createHttpClient } from "../../src/adapters/http/client.ts";
import { TEST_HTTP_CONTRACT } from "../helpers/http-contract-fixture.ts";
import {
TEST_HTTP_CONTRACT,
TEST_OPERATIONS,
} from "../helpers/http-contract-fixture.ts";
let attempts = 0;
const server = setupServer(
@@ -160,12 +163,13 @@ describe("shared HTTP client", () => {
// Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
// server outage, not a contract breach: it keeps its status and the V2
// SERVER_FAILURE retry rule (502/503/504 only).
// SERVER_FAILURE retry rule (408/425/502/503/504, R3-1).
it.each([
{ status: 502, contentType: "text/html", body: "<secret>raw body</secret>", fetches: 3 },
{ status: 503, contentType: "application/json", body: "", fetches: 3 },
{ status: 504, contentType: "application/json", body: "{", fetches: 3 },
{ status: 408, contentType: "text/plain", body: "timeout", fetches: 1 },
{ status: 408, contentType: "text/plain", body: "timeout", fetches: 3 },
{ status: 425, contentType: "text/html", body: "<p>too early</p>", fetches: 3 },
])(
"keeps a $status gateway body as a server failure with its status",
async ({ status, contentType, body, fetches }) => {
@@ -195,6 +199,154 @@ 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 }) => {
let fetched = 0;
server.use(
http.post("https://api.test/api/entities", () => {
fetched += 1;
return new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain" },
});
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
getOperation: () => ({ ...TEST_OPERATIONS.CREATE_ENTITY, idempotency }),
});
const result = await client.execute("CREATE_ENTITY", {
body: { name: "n" },
...(idempotency === "keyed" ? { idempotencyKey: "key-1" } : {}),
});
expect(result).toMatchObject({
ok: false,
error: { kind: "SERVER_FAILURE", httpStatus: status },
});
expect(fetched).toBe(fetches);
},
);
function retryAfterClient(delays: number[]) {
return testClient({
baseUrl: "https://api.test",
clock: {
now: () => 0,
sleep: async (ms: number) => {
delays.push(ms);
},
},
random: () => 0.5, // local backoff for the first retry: 125ms
});
}
// 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" },
});
}),
);
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([2_000]);
},
);
it.each([408, 425])(
"does not retry a %i whose Retry-After exceeds 30 seconds",
async (status) => {
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" },
});
}),
);
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({
ok: false,
error: { kind: "SERVER_FAILURE", httpStatus: status, retryAfterMs: 31_000 },
});
expect(fetched).toBe(1);
expect(delays).toEqual([]);
},
);
// R3-1. Retry-After goes through the platform kernel parser: delta-seconds
// or an IMF-fixdate only. Anything else falls back to the local backoff.
it.each([
{ value: "2", delay: 2_000 },
{ value: " 2 ", delay: 2_000 },
{ value: "Thu, 01 Jan 1970 00:00:05 GMT", delay: 5_000 },
{ value: "", delay: 125 },
{ value: " ", delay: 125 },
{ value: "1e3", delay: 125 },
{ value: "1.5", delay: 125 },
{ value: "0x10", delay: 125 },
{ value: "-1", delay: 125 },
{ value: "2099-01-01T00:00:00Z", delay: 125 },
{ value: "Thursday, 01-Jan-70 00:00:05 GMT", delay: 125 },
])("parses a 429 Retry-After of $value as $delay ms", async ({ value, delay }) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return fetched === 1
? HttpResponse.json(
{
success: false,
error: { code: "RATE_LIMITED" },
meta: { requestId: "request-1", traceId: "trace-1" },
},
{ status: 429, headers: { "Retry-After": value } },
)
: HttpResponse.json({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([delay]);
});
it("classifies malformed JSON and invalid payloads at the boundary", async () => {
server.use(
http.get(
+24
View File
@@ -45,6 +45,30 @@ describe("HTTP retry policy", () => {
).toBe(false);
});
// R3-1. 408/425 server failures share the 502/503/504 rule and honor
// Retry-After with the same 30s ceiling.
it("retries 408 and 425 server failures only for safe or keyed requests", () => {
for (const httpStatus of [408, 425]) {
const failure = { kind: "SERVER_FAILURE", httpStatus };
expect(shouldRetry({ idempotency: "safe" }, failure, 0)).toBe(true);
expect(shouldRetry({ idempotency: "keyed" }, failure, 0)).toBe(true);
expect(shouldRetry({ idempotency: "none" }, failure, 0)).toBe(false);
expect(
shouldRetry({ idempotency: "safe", retry: "never" }, failure, 0),
).toBe(false);
expect(
retryDelay({ ...failure, retryAfterMs: 1_500 }, 0, () => 0),
).toBe(1_500);
expect(
shouldRetry(
{ idempotency: "safe" },
{ ...failure, retryAfterMs: 31_000 },
0,
),
).toBe(false);
}
});
it("does not automatically wait beyond 30 seconds", () => {
expect(
shouldRetry(