import { HttpResponse, http } from "msw"; 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, TEST_OPERATIONS, } from "../helpers/http-contract-fixture.ts"; let attempts = 0; const server = setupServer( http.get("https://api.test/api/entities", () => { attempts += 1; if (attempts < 3) { return HttpResponse.json( { success: false, error: { code: "TEMPORARY" } }, { status: 503 }, ); } return HttpResponse.json({ success: true, data: [{ id: "resource-1", name: "Example" }], meta: { requestId: "request-1", traceId: "trace-1" }, }); }), ); beforeAll(() => server.listen({ onUnhandledRequest: "error" })); afterEach(() => { attempts = 0; server.resetHandlers(); }); afterAll(() => server.close()); const clock = { now: () => 0, sleep: async () => {}, }; type HttpDependencies = Parameters[0]; function testClient(options: HttpDependencies) { return createHttpClient({ ...TEST_HTTP_CONTRACT, ...options }); } describe("shared HTTP client", () => { it("retries a safe request at most twice and returns validated data", async () => { const client = testClient({ baseUrl: "https://api.test", clock, random: () => 0, }); await expect( client.execute("LIST_ENTITIES", { routeId: "TEST_ROUTE" }), ).resolves.toMatchObject({ ok: true, value: [{ id: "resource-1", displayName: "Example" }], meta: { requestId: "request-1" }, }); expect(attempts).toBe(3); }); it.each(["", " ", "bad\u0000key", "x".repeat(513)])( "rejects invalid keyed command key %j before credentials and fetch", async (idempotencyKey) => { let fetched = 0; let credentialAttempts = 0; server.use( http.post("https://api.test/api/entities", () => { fetched += 1; return HttpResponse.json({ success: true, data: {} }); }), ); const client = testClient({ baseUrl: "https://api.test", clock, authSession: { getState: () => "authenticated", getSubject: () => "user-a", subscribe: () => () => {}, beginSignIn: async () => {}, signOut: async () => {}, async credentialPatch() { credentialAttempts += 1; return { headers: {} }; }, recover: async () => "no-session" as const, onUnauthenticated: () => {}, }, }); await expect( client.execute("CREATE_ENTITY", { body: { name: "n" }, idempotencyKey, }), ).resolves.toMatchObject({ ok: false, error: { kind: "VALIDATION_REJECTED", code: "IDEMPOTENCY_KEY_INVALID", // The repository reports attempt counts as 1-based; the invariant // proved below is that no physical attempt happened at all. attemptCount: 1, }, }); expect(fetched).toBe(0); expect(credentialAttempts).toBe(0); }, ); it("bounds a non-cooperative legacy credential owner by total deadline", async () => { let fetched = 0; let observedSignal: AbortSignal | undefined; server.use( http.get("https://api.test/api/entities", () => { fetched += 1; return HttpResponse.json({ success: true, data: [] }); }), ); const client = testClient({ baseUrl: "https://api.test", timeoutMs: 5, clock: { now: () => 0, sleep: async () => {} }, authSession: { getState: () => "authenticated", getSubject: () => "user-a", subscribe: () => () => {}, beginSignIn: async () => {}, signOut: async () => {}, credentialPatch: (_binding, context) => { observedSignal = context?.signal; // Never settles on its own. return new Promise(() => {}); }, recover: async () => "no-session" as const, onUnauthenticated: () => {}, }, }); const result = await client.execute("LIST_ENTITIES"); expect(result).toMatchObject({ ok: false }); expect(fetched).toBe(0); expect(observedSignal).toBeDefined(); }); it("rejects a non-JSON response without exposing its body", async () => { server.use( http.get( "https://api.test/api/entities", () => new HttpResponse("raw body", { status: 200 }), ), ); const client = testClient({ baseUrl: "https://api.test", clock }); const result = await client.execute("LIST_ENTITIES"); expect(result).toMatchObject({ ok: false, error: { kind: "CONTENT_TYPE_MISMATCH" }, }); expect(JSON.stringify(result)).not.toContain("raw body"); }); // 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 (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: 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 }) => { let fetched = 0; server.use( http.get("https://api.test/api/entities", () => { fetched += 1; return new HttpResponse(body, { status, headers: { "Content-Type": contentType }, }); }), ); const client = testClient({ baseUrl: "https://api.test", clock, random: () => 0, }); const result = await client.execute("LIST_ENTITIES"); expect(result).toMatchObject({ ok: false, error: { kind: "SERVER_FAILURE", httpStatus: status }, }); expect(fetched).toBe(fetches); expect(JSON.stringify(result)).not.toContain("raw body"); }, ); 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 = {}, ) { 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 busyResponse(status, envelope); }), ); 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 }); } 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"), ).resolves.toMatchObject({ ok: true }); expect(delays).toEqual([2_000]); }, ); // 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 busyResponse(status, envelope, { "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( "https://api.test/api/entities", () => new HttpResponse("{", { headers: { "Content-Type": "application/json" }, }), ), ); const client = testClient({ baseUrl: "https://api.test", clock }); await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({ ok: false, error: { kind: "MALFORMED_JSON" }, }); server.use( http.get("https://api.test/api/entities", () => HttpResponse.json({ success: true, data: [{ id: "resource-1", name: 42 }], meta: { requestId: "request-1", traceId: "trace-1" }, }), ), ); await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({ ok: false, error: { kind: "SCHEMA_MISMATCH" }, }); }); it("projects only approved 422 issue path and code metadata", async () => { server.use( http.post("https://api.test/api/entities", () => HttpResponse.json( { success: false, error: { code: "INVALID_INPUT", message: "raw backend secret", details: { issues: [ { path: "name", code: "REQUIRED", message: "raw field copy" }, { path: 42, code: "INVALID" }, ], }, }, meta: { requestId: "request-422", traceId: "trace-422" }, }, { status: 422 }, ), ), ); const client = testClient({ baseUrl: "https://api.test", clock }); const result = await client.execute("CREATE_ENTITY", { routeId: "TEST_FORM", body: { name: "Valid" }, }); expect(result).toMatchObject({ ok: false, error: { kind: "VALIDATION_REJECTED", validationIssues: [{ path: "name", code: "REQUIRED" }], }, }); expect(JSON.stringify(result)).not.toContain("raw backend secret"); expect(JSON.stringify(result)).not.toContain("raw field copy"); }); it("guards mapper exceptions as a mapping contract violation", async () => { server.use( http.get("https://api.test/api/entities", () => HttpResponse.json({ success: true, data: [{ id: "resource-1", name: "Example" }], meta: { requestId: "request-1", traceId: "trace-1" }, }), ), ); const client = testClient({ baseUrl: "https://api.test", clock, mapPayload: () => { throw new Error("raw mapper detail"); }, }); const result = await client.execute("LIST_ENTITIES"); expect(result).toMatchObject({ ok: false, error: { kind: "MAPPING_CONTRACT_VIOLATION" }, }); expect(JSON.stringify(result)).not.toContain("raw mapper detail"); }); });