From db1bc1fc7e879dc139cdcdb8931ab574765080e2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 15:16:30 +0900 Subject: [PATCH] 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 --- src/adapters/http/client.ts | 28 ++--- src/adapters/http/retry-policy.ts | 5 +- tests/integration/http-client.test.ts | 158 +++++++++++++++++++++++++- tests/unit/retry-policy.test.ts | 24 ++++ 4 files changed, 194 insertions(+), 21 deletions(-) diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts index 7cc38916..af0abda1 100644 --- a/src/adapters/http/client.ts +++ b/src/adapters/http/client.ts @@ -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, now: number, ): Promise { + // 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) @@ -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 { }; } -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", diff --git a/src/adapters/http/retry-policy.ts b/src/adapters/http/retry-policy.ts index baddfae3..5809bc8b 100644 --- a/src/adapters/http/retry-policy.ts +++ b/src/adapters/http/retry-policy.ts @@ -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 diff --git a/tests/integration/http-client.test.ts b/tests/integration/http-client.test.ts index 2390124f..1912e81c 100644 --- a/tests/integration/http-client.test.ts +++ b/tests/integration/http-client.test.ts @@ -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: "raw body", 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: "

too early

", 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( diff --git a/tests/unit/retry-policy.test.ts b/tests/unit/retry-policy.test.ts index cf3da93c..3241bf0e 100644 --- a/tests/unit/retry-policy.test.ts +++ b/tests/unit/retry-policy.test.ts @@ -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(