import { describe, expect, it, vi } from "vitest"; import { createFeatureHttpBinding, defineFeatureHttpOperation, } from "../../src/adapters/http/feature-http-binding.ts"; import { createContractHttpExecutor, type HttpExecutionObservation, } from "../../src/adapters/http/http-execution-v3.ts"; import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts"; import type { InstalledHttpContract } from "../../src/contracts/external-contract-runtime.ts"; import { createExecutionContext, type ExecutionContext, } from "../../src/platform/execution/execution-context.ts"; import { TEST_CREATE_HTTP_CONTRACT, TEST_LIST_HTTP_CONTRACT, } from "../helpers/external-contract-fixture.ts"; const installed: InstalledHttpContract = TEST_LIST_HTTP_CONTRACT; const ROUTE_ID = "TEST_ROUTE"; const scope = Object.freeze({ generation: 1, fingerprint: "scope-1", identities: Object.freeze({}) as never, signal: new AbortController().signal, isCurrent: () => true, }); const createInstalled: InstalledHttpContract = TEST_CREATE_HTTP_CONTRACT; function mutationIntent( overrides: Readonly<{ intentId?: string; operationId?: string; idempotencyKey?: string | null; }> = {}, ) { return Object.freeze({ intentId: overrides.intentId ?? "intent-1", operationId: overrides.operationId ?? "TEST_CREATE_ENTITY", canonicalInputIdentity: "opaque-input-identity", ...(overrides.idempotencyKey === null ? {} : { idempotencyKey: overrides.idempotencyKey ?? "key-1" }), createdAtMonotonicMs: 1, }); } function operation( overrides: Readonly<{ deadlineMs?: number; responseBody?: "REQUIRED_JSON" | "OPTIONAL_JSON" | "NONE"; }> = {}, ): InstalledHttpContract { return { ...installed, contract: { ...installed.contract, responseBody: overrides.responseBody ?? installed.contract.responseBody, }, frontend: { ...installed.frontend, totalDeadlineMs: overrides.deadlineMs ?? installed.frontend.totalDeadlineMs, }, }; } async function flushMicrotasks(): Promise { await Promise.resolve(); await Promise.resolve(); await Promise.resolve(); } describe("runtime request deadline ceiling", () => { /** * `REQUEST_TIMEOUT_MS` was validated by the runtime config schema and then * never handed to the V3 executor, so the deployment dial did nothing and * every operation ran on its contract's own deadline. It is a ceiling: it may * tighten an operation, never loosen one. */ async function settlesWithin( contractDeadlineMs: number, ceilingMs: number | undefined, advanceMs: number, ): Promise { vi.useFakeTimers(); try { const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, ...(ceilingMs === undefined ? {} : { requestDeadlineCeilingMs: ceilingMs }), attachCredentials: () => ({ kind: "READY", headers: {} }), // A request that only ever ends by being cut off, so what settles it is // exactly the deadline under test. fetcher: (_input, init) => new Promise((_resolve, reject) => { const signal = (init as RequestInit | undefined)?.signal; signal?.addEventListener( "abort", () => reject(new DOMException("aborted", "AbortError")), { once: true }, ); }), }); let settled = false; const pending = executor .execute(operation({ deadlineMs: contractDeadlineMs }), {}, { routeId: ROUTE_ID, scope, }) .then( () => { settled = true; }, () => { settled = true; }, ); await vi.advanceTimersByTimeAsync(advanceMs); await flushMicrotasks(); const observed = settled; if (!observed) await vi.advanceTimersByTimeAsync(contractDeadlineMs + 1_000); await pending; return observed; } finally { vi.useRealTimers(); } } it("applies the tighter of the contract and deployment bounds", async () => { await expect(settlesWithin(5_000, 500, 800)).resolves.toBe(true); await expect(settlesWithin(5_000, undefined, 800)).resolves.toBe(false); }); it("never extends a contract deadline", async () => { await expect(settlesWithin(500, 60_000, 800)).resolves.toBe(true); }); it("ignores a ceiling that is not a usable duration", async () => { for (const ceiling of [0, -1, Number.NaN]) { await expect(settlesWithin(5_000, ceiling, 800), String(ceiling)).resolves.toBe( false, ); } }); }); describe("descriptor-driven HTTP execution lifetime", () => { it("tells a missing credential apart from a server 401", async () => { const refusedFetcher = vi.fn(); const refused = await createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "UNAUTHENTICATED" }), fetcher: refusedFetcher, }).execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope }); const rejected = await createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher: async () => new Response(null, { status: 401 }), }).execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope }); // Only the server's answer carries response metadata; the composition // root reports just that one to the session owner. expect(refusedFetcher).not.toHaveBeenCalled(); expect(refused).toEqual({ kind: "UNAUTHENTICATED", effect: "NOT_APPLICABLE" }); expect(rejected).toMatchObject({ kind: "UNAUTHENTICATED", effect: "NOT_APPLICABLE", metadata: { status: 401 }, }); }); it("normalizes a read-side 429 to the non-applicable effect vocabulary", async () => { const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: async () => Response.json( { type: "about:blank", title: "limited", status: 429 }, { status: 429 }, ), }); await expect( executor.execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope }), ).resolves.toMatchObject({ kind: "RATE_LIMITED", effect: "NOT_APPLICABLE", }); }); it.each([ ["absent intent", () => undefined], ["empty key", () => mutationIntent({ idempotencyKey: "" })], ["control-character key", () => mutationIntent({ idempotencyKey: "key\u0000private" })], ["over-budget key", () => mutationIntent({ idempotencyKey: "k".repeat(257) })], [ "wrong operation", () => mutationIntent({ operationId: "TEST_OTHER_COMMAND" }), ], ])( "rejects a KEYED command with %s before credentials or fetch", async (_label, intentFactory) => { const attachCredentials = vi.fn(() => ({ kind: "READY" as const, headers: {}, })); const fetcher = vi.fn(); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials, fetcher, }); const intent = intentFactory(); await expect( executor.execute( createInstalled, { name: "created" }, { routeId: ROUTE_ID, scope, ...(intent === undefined ? {} : { intent }) }, ), ).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "MISSING_IDEMPOTENCY_KEY", operation: "REQUEST", }, effect: "NOT_STARTED", }); expect(attachCredentials).not.toHaveBeenCalled(); expect(fetcher).not.toHaveBeenCalled(); }, ); it.each([ ["an intent without a key", mutationIntent({ idempotencyKey: null })], ["an intent with a key", mutationIntent()], ])( "rejects a query carrying %s before credentials or fetch", async (_label, intent) => { const attachCredentials = vi.fn(() => ({ kind: "READY" as const, headers: {}, })); const fetcher = vi.fn(); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials, fetcher, }); await expect( executor.execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope, intent }), ).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "UNEXPECTED_IDEMPOTENCY_KEY", operation: "REQUEST", }, effect: "NOT_STARTED", }); expect(attachCredentials).not.toHaveBeenCalled(); expect(fetcher).not.toHaveBeenCalled(); }, ); it.each([ { label: "query with the canonical reserved header", operation: installed, input: { limit: 20 }, context: { routeId: ROUTE_ID, scope }, headerName: "Idempotency-Key", }, { label: "valid KEYED command with a case-variant reserved header", operation: createInstalled, input: { name: "created" }, context: { routeId: ROUTE_ID, scope, intent: mutationIntent() }, headerName: "iDeMpOtEnCy-KeY", }, ])( "rejects a credential patch for $label before fetch", async ({ operation, input, context, headerName }) => { const attachCredentials = vi.fn(() => ({ kind: "READY" as const, headers: { [headerName]: "credential-owned-key" }, })); const fetcher = vi.fn(); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials, fetcher, }); await expect( executor.execute(operation, input, context), ).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "UNEXPECTED_IDEMPOTENCY_KEY", operation: "REQUEST", }, effect: "NOT_STARTED", }); expect(attachCredentials).toHaveBeenCalledOnce(); expect(fetcher).not.toHaveBeenCalled(); }, ); it("reuses one supplied idempotency key across every physical retry", async () => { const observedKeys: Array = []; let attempt = 0; const fetcher = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => { observedKeys.push(new Headers(init?.headers).get("Idempotency-Key")); attempt += 1; if (attempt === 1) throw new TypeError("synchronous pre-dispatch failure"); return Promise.resolve( Response.json( { id: "created", name: "Created" }, { status: 201 }, ), ); }); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 1, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher, sleep: async () => {}, random: () => 0, }); const retryingCreate = { ...createInstalled, frontend: { ...createInstalled.frontend, retryBudget: 1 as const, }, }; await expect( executor.execute( retryingCreate, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent({ idempotencyKey: "logical-key" }) }, ), ).resolves.toMatchObject({ kind: "SUCCESS" }); expect(fetcher).toHaveBeenCalledTimes(2); expect(observedKeys).toEqual(["logical-key", "logical-key"]); }); it("never emits a mutation idempotency header for a query", async () => { const observedKeys: Array = []; const fetcher = vi.fn( async (_input: RequestInfo | URL, init?: RequestInit) => { observedKeys.push( new Headers(init?.headers).get("Idempotency-Key"), ); return Response.json([]); }, ); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher, }); await expect( executor.execute( installed, { limit: 20 }, { routeId: ROUTE_ID, scope }, ), ).resolves.toMatchObject({ kind: "SUCCESS" }); expect(fetcher).toHaveBeenCalledOnce(); expect(observedKeys).toEqual([null]); }); it("keeps intent identities out of request URLs and safe observations", async () => { const urls: string[] = []; const observations: unknown[] = []; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(async (input) => { urls.push(String(input)); return Response.json( { id: "created", name: "Created" }, { status: 201 }, ); }), observe: (observation) => observations.push(observation), }); await expect( executor.execute( createInstalled, { name: "created" }, { routeId: ROUTE_ID, scope, intent: Object.freeze({ intentId: "private-intent-id", operationId: "TEST_CREATE_ENTITY", canonicalInputIdentity: "private-canonical-input", idempotencyKey: "private-idempotency-key", createdAtMonotonicMs: 1, }), }, ), ).resolves.toMatchObject({ kind: "SUCCESS" }); const safeEvidence = JSON.stringify({ urls, observations }); expect(urls).toEqual(["https://api.example/api/test-entities"]); expect(observations).toHaveLength(1); expect(safeEvidence).not.toContain("private-intent-id"); expect(safeEvidence).not.toContain("private-canonical-input"); expect(safeEvidence).not.toContain("private-idempotency-key"); }); it.each([ [{}, "limit=20"], [{ limit: "7" }, "limit=7"], ])("projects the canonical validated input %#", async (input, expectedQuery) => { const fetcher = vi.fn(async () => Response.json([])); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher, }); await expect(executor.execute(installed, input, { routeId: ROUTE_ID, scope })).resolves.toMatchObject({ kind: "SUCCESS", }); expect(String((fetcher.mock.calls as unknown[][])[0]?.[0])).toContain( expectedQuery, ); }); it("contains throwing and malformed external request projections", async () => { const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(), }); const throwing = { ...installed, contract: { ...installed.contract, projectRequest: () => { throw new Error("external descriptor defect"); }, }, }; const malformed = { ...installed, contract: { ...installed.contract, projectRequest: () => ({ pathValues: {}, queryEntries: [["limit"]], body: null }), }, } as unknown as typeof installed; await expect(executor.execute(throwing, { limit: 20 }, { routeId: ROUTE_ID, scope })).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", effect: "NOT_APPLICABLE", }); await expect(executor.execute(malformed, { limit: 20 }, { routeId: ROUTE_ID, scope })).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", effect: "NOT_APPLICABLE", }); }); it("preserves MAYBE_APPLIED for a malformed command response after dispatch", async () => { const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(async () => Response.json({ malformed: true }, { status: 201 })), }); await expect( executor.execute( createInstalled, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent(), }, ), ).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "SUCCESS_SCHEMA_INVALID" }, effect: "MAYBE_APPLIED", }); }); it("preserves MAYBE_APPLIED when a command response arrives after its scope fence", async () => { let current = true; const lifetime = new AbortController(); const fencedScope = Object.freeze({ ...scope, signal: lifetime.signal, isCurrent: () => current, }); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(async () => { current = false; lifetime.abort(); return Response.json( { id: "created", name: "Created" }, { status: 201 }, ); }), }); await expect( executor.execute( createInstalled, { name: "created" }, { routeId: ROUTE_ID, scope: fencedScope, intent: mutationIntent({ intentId: "intent-2", idempotencyKey: "key-2" }), }, ), ).resolves.toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "SCOPE_FENCED" }, effect: "MAYBE_APPLIED", }); }); it("keeps a dispatched command MAYBE_APPLIED when a retry-time fence lands between scope checks", async () => { // Attempt 1 dispatches an idempotent command and receives 429. The retry // sleep resolves, the loop-entry scope check is still current, and only the // pre-dispatch final invariant observes the fence. let armed = false; let checksAfterArming = 0; const idempotentCommand: InstalledHttpContract = { ...createInstalled, contract: { ...createInstalled.contract, retrySemantics: "IDEMPOTENT" as const, }, frontend: { ...createInstalled.frontend, retryBudget: 1 as const }, }; const racingScope = Object.freeze({ ...scope, isCurrent: () => { if (!armed) return true; checksAfterArming += 1; // The retry loop entry still observes a current scope; the pre-dispatch // final invariant is the first observation of the fence. return checksAfterArming <= 1; }, }); const fetcher = vi.fn(async () => Response.json({ type: "about:blank", title: "slow down", status: 429 }, { status: 429, }), ); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 1, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, sleep: async () => { armed = true; }, random: () => 0, }); const outcome = await executor.execute( idempotentCommand, { name: "created" }, { routeId: ROUTE_ID, scope: racingScope, intent: mutationIntent({ idempotencyKey: null }), }, ); expect(fetcher).toHaveBeenCalledTimes(1); expect(outcome).toMatchObject({ kind: "CONTRACT_VIOLATION", violation: { kind: "SCOPE_FENCED" }, effect: "MAYBE_APPLIED", }); }); it("settles a credential hang at the total operation deadline", async () => { vi.useFakeTimers(); let settled = false; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => new Promise(() => {}), }); const result = executor .execute(operation({ deadlineMs: 5 }), { limit: 20 }, { routeId: ROUTE_ID, scope }) .then((outcome) => { settled = true; return outcome; }); await vi.advanceTimersByTimeAsync(5); await flushMicrotasks(); expect(settled).toBe(true); await expect(result).resolves.toMatchObject({ kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" }, }); vi.useRealTimers(); }); it("never retries a deadline-owned abort while the monotonic clock still has a sub-tick budget", async () => { vi.useFakeTimers(); try { const iterationCount = 100; const sleep = vi.fn(async () => { throw new Error("a deadline-owned abort must not enter retry sleep"); }); const fetcher = vi.fn( (_input: RequestInfo | URL, init?: RequestInit) => new Promise((_resolve, reject) => { init?.signal?.addEventListener( "abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true }, ); }), ); const observe = vi.fn(); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 2, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher, monotonicNow: () => 0, random: () => 0, sleep, observe, }); for (let iteration = 0; iteration < iterationCount; iteration += 1) { const result = executor.execute( operation({ deadlineMs: 5 }), { limit: 20 }, { routeId: ROUTE_ID, scope }, ); await vi.advanceTimersByTimeAsync(5); await flushMicrotasks(); await expect(result).resolves.toMatchObject({ kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" }, }); } expect(fetcher).toHaveBeenCalledTimes(iterationCount); expect(sleep).not.toHaveBeenCalled(); expect(observe).toHaveBeenCalledTimes(iterationCount); for (const [observation] of observe.mock.calls) { expect(observation).toEqual( expect.objectContaining({ attemptCount: 1, errorKind: "TIMEOUT", terminalReason: "TIMEOUT", cancellationOwner: "DEADLINE", routeId: ROUTE_ID, operationId: "TEST_LIST_ENTITIES", }), ); } } finally { vi.useRealTimers(); } }); it("cancels a non-cooperative retry sleep when the caller aborts", async () => { const caller = new AbortController(); let sleepSignal: AbortSignal | undefined; let settled = false; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 2, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(async () => Response.json( { type: "about:blank", title: "temporary", status: 503 }, { status: 503 }, ), ), sleep: (_ms, signal) => { sleepSignal = signal; return new Promise(() => {}); }, random: () => 0, }); const result = executor .execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope, signal: caller.signal }) .then((outcome) => { settled = true; return outcome; }); await vi.waitFor(() => expect(sleepSignal).toBeDefined()); caller.abort(); await flushMicrotasks(); expect(sleepSignal?.aborted).toBe(true); expect(settled).toBe(true); await expect(result).resolves.toMatchObject({ kind: "CANCELLED" }); }); // 1103/10-04 ②. A signal is shared by many requests (a screen, a session // scope). Every abort listener an execution adds to the caller's and the // scope's signal is removed when it ends, however it ends. it.each(["an answer", "a caller abort"] as const)( "removes the listeners it added to the caller and scope signals after %s", async (ending) => { const caller = new AbortController(); const scopeLifetime = new AbortController(); const watched = [caller.signal, scopeLifetime.signal].map((signal) => ({ add: vi.spyOn(signal, "addEventListener"), remove: vi.spyOn(signal, "removeEventListener"), })); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher: vi.fn(async () => Response.json([])), }); const result = executor.execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope: { ...scope, signal: scopeLifetime.signal }, signal: caller.signal, }); if (ending === "a caller abort") caller.abort(); await expect(result).resolves.toMatchObject({ kind: ending === "an answer" ? "SUCCESS" : "CANCELLED", }); for (const { add, remove } of watched) { const added = add.mock.calls .filter(([type]) => type === "abort") .map(([, listener]) => listener); const removed = remove.mock.calls .filter(([type]) => type === "abort") .map(([, listener]) => listener); expect(added).toHaveLength(1); expect(removed).toEqual(added); } }, ); it("treats an unreadable forbidden-body probe as a transport failure", async () => { const body = new ReadableStream({ pull(controller) { controller.error(new TypeError("stream failed")); }, }); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {}, }), fetcher: vi.fn(async () => new Response(body, { status: 200 })), }); await expect( executor.execute( operation({ responseBody: "NONE" }), { limit: 20 }, { routeId: ROUTE_ID, scope }, ), ).resolves.toMatchObject({ kind: "TRANSPORT_FAILURE", failure: { kind: "RESPONSE_STREAM_FAILURE" }, }); }); }); /** * R-3.3. A gateway 5xx/408 with an HTML, empty or broken body is a server * outage. It must keep its status and stay retryable instead of surfacing as a * "contact support" contract breach. */ describe("gateway failures without a usable problem body", () => { it.each([ [502, "text/html", "Bad Gateway"], [503, "application/json", ""], [504, "application/json", "{"], [408, "text/plain", "timeout"], ])( "ends a %i response as a retryable server failure with its status", async (status, contentType, body) => { const fetcher = vi.fn( async () => new Response(body, { status, headers: { "content-type": contentType } }), ); const observations: HttpExecutionObservation[] = []; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 1, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, sleep: async () => {}, observe: (observation) => void observations.push(observation), }); const list = defineFeatureHttpOperation({ contract: TEST_LIST_HTTP_CONTRACT, routeId: ROUTE_ID, mapSuccess: (value) => mappingSuccess(value), }); const binding = createFeatureHttpBinding( { execute: (contract, input, context) => executor.execute(contract, input, { ...context, scope }), }, { [list.operationId]: list }, ); const result = await binding.execute(list.operationId, { limit: 20 }); expect(fetcher).toHaveBeenCalledTimes(2); expect(observations.at(-1)?.status).toBe(status); expect(result).toMatchObject({ ok: false, error: { kind: "SERVER_FAILURE", httpStatus: status, retryable: true, action: "retry", }, }); }, ); }); /** * Q-6.3-6. Every wait the lifetime signal can end reports its owner the same * way: the caller cancels, the deadline times out, and a scope fence ends as a * scope abort — a transport abort before response headers, the stale-generation * violation after them. A fence during a retry backoff used to read as TIMEOUT. */ describe("terminal owner classification at every wait", () => { const phases = [ "credentials", "lease", "dispatch", "transport backoff", "admission", "retry backoff", ] as const; type Phase = (typeof phases)[number]; type Owner = "CALLER" | "SCOPE_FENCE" | "DEADLINE"; const hang = () => new Promise(() => {}); async function endWaitAt(phase: Phase, owner: Owner) { const caller = new AbortController(); const fence = new AbortController(); const fencedScope = Object.freeze({ ...scope, signal: fence.signal, isCurrent: () => !fence.signal.aborted, }); let reached = false; const reach = () => { reached = true; }; let execution: ExecutionContext | undefined; if (phase === "lease") { execution = createExecutionContext({ interactionId: "held-lease", deadlineMs: 10_000, traffic: { maxPhysicalRequests: 4, maxRetries: 2, maxConcurrentRequests: 1, maxQueuedRequests: 1, }, }); await execution.traffic.concurrency.acquire(new AbortController().signal); } const observations: HttpExecutionObservation[] = []; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 2, attachCredentials: () => phase === "credentials" ? (reach(), hang()) : { kind: "READY", headers: {} }, fetcher: vi.fn(async () => { switch (phase) { case "transport backoff": throw new TypeError("network down"); case "admission": return new Response( new ReadableStream({ pull: () => (reach(), hang()), }), { status: 200, headers: { "content-type": "application/json" } }, ); case "retry backoff": return Response.json( { type: "about:blank", title: "temporary", status: 503 }, { status: 503 }, ); default: reach(); return hang(); } }), sleep: () => (reach(), hang()), random: () => 0, observe: (observation) => void observations.push(observation), }); const pending = executor.execute( operation({ deadlineMs: owner === "DEADLINE" ? 30 : 10_000 }), { limit: 20 }, { routeId: ROUTE_ID, scope: fencedScope, signal: caller.signal, ...(execution === undefined ? {} : { execution }), }, ); if (owner !== "DEADLINE") { await vi.waitFor(() => expect(reached || execution?.traffic.concurrency.queued === 1).toBe( true, ), ); (owner === "CALLER" ? caller : fence).abort(); } const outcome = await pending; return { outcome, cancellationOwner: observations.at(-1)?.cancellationOwner, }; } it.each(phases)( "cancels at the %s wait when the caller aborts", async (phase) => { await expect(endWaitAt(phase, "CALLER")).resolves.toMatchObject({ outcome: { kind: "CANCELLED", effect: "NOT_STARTED" }, cancellationOwner: "CALLER", }); }, ); it.each(phases)( "times out at the %s wait when the deadline fires", async (phase) => { await expect(endWaitAt(phase, "DEADLINE")).resolves.toMatchObject({ outcome: { kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" } }, cancellationOwner: "DEADLINE", }); }, ); it.each(phases)( "ends the %s wait as a scope abort when the scope is fenced", async (phase) => { await expect(endWaitAt(phase, "SCOPE_FENCE")).resolves.toMatchObject({ outcome: phase === "admission" ? { kind: "CONTRACT_VIOLATION", violation: { kind: "SCOPE_FENCED" }, } : { kind: "TRANSPORT_FAILURE", failure: { kind: "ABORTED_BY_SCOPE" }, }, cancellationOwner: "SCOPE_FENCE", }); }, ); }); /** * 10-03. The executor, not only the pure rule, must read the contract's retry * semantics: a KEYED command with budget left retries a send that never left, * and never replays one that was dispatched. */ describe("KEYED retry budget through the executor", () => { const keyedWithBudget: InstalledHttpContract = { ...createInstalled, frontend: { ...createInstalled.frontend, retryBudget: 2 as const }, }; function keyedExecutor(fetcher: typeof fetch) { return createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 2, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, sleep: async () => {}, random: () => 0, }); } it("retries a KEYED send that failed before dispatch, with the same key", async () => { const keys: (string | null)[] = []; const fetcher = vi.fn((_input, init) => { keys.push(new Headers(init?.headers).get("idempotency-key")); if (keys.length === 1) throw new TypeError("fetch refused to start"); return Promise.resolve( Response.json({ id: "created", name: "created" }, { status: 201 }), ); }); const outcome = await keyedExecutor(fetcher).execute( keyedWithBudget, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent() }, ); expect(fetcher).toHaveBeenCalledTimes(2); expect(keys).toEqual(["key-1", "key-1"]); expect(outcome).toMatchObject({ kind: "SUCCESS", effect: "APPLIED_CONFIRMED", }); }); it("does not replay a dispatched KEYED send even with budget left", async () => { const fetcher = vi.fn(async () => { throw new TypeError("connection reset"); }); const outcome = await keyedExecutor(fetcher).execute( keyedWithBudget, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent() }, ); expect(fetcher).toHaveBeenCalledOnce(); expect(outcome).toMatchObject({ kind: "TRANSPORT_FAILURE", effect: "MAYBE_APPLIED", }); }); }); /** * 03-03. A support reference must reach the server log: every logical * execution sends one request id, and a failure carries the server's echoed * `x-correlation-id` as `requestId`. */ describe("request correlation", () => { it("sends one request id per logical execution, shared by its retries", async () => { const sent: (string | null)[] = []; const fetcher = vi.fn(async (_input, init) => { sent.push(new Headers(init?.headers).get("x-correlation-id")); return sent.length === 1 ? new Response(null, { status: 503 }) : Response.json([{ id: "a", name: "A" }]); }); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 2, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, sleep: async () => {}, random: () => 0, }); const retried = { ...installed, frontend: { ...installed.frontend, retryBudget: 1 as const }, }; await executor.execute(retried, { limit: 20 }, { routeId: ROUTE_ID, scope }); await executor.execute(retried, { limit: 20 }, { routeId: ROUTE_ID, scope }); expect(sent).toHaveLength(3); expect(sent[0]).toMatch(/^[A-Za-z0-9._:-]{1,128}$/u); expect(sent[1]).toBe(sent[0]); expect(sent[2]).not.toBe(sent[0]); }); it("still sends the request when no request id can be made", async () => { const fetcher = vi.fn(async () => Response.json([{ id: "a", name: "A" }]), ); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, createRequestId: () => { throw new TypeError("randomUUID needs a secure context"); }, }); const outcome = await executor.execute(installed, { limit: 20 }, { routeId: ROUTE_ID, scope, }); expect(outcome.kind).toBe("SUCCESS"); expect( new Headers(fetcher.mock.calls[0]?.[1]?.headers).get("x-correlation-id"), ).toBeNull(); }); it.each([ ["a problem", 400, { type: "about:blank", title: "rejected", status: 400 }], ["an unauthenticated answer", 401, null], ["a forbidden answer", 403, null], ["a rate limit", 429, null], ["a gateway outage", 504, null], ] as const)("carries the server correlation id on %s", async (_label, status, body) => { const observations: HttpExecutionObservation[] = []; const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher: vi.fn(async () => body === null ? new Response(null, { status, headers: { "x-correlation-id": "server-ref-42" }, }) : Response.json(body, { status, headers: { "x-correlation-id": "server-ref-42" }, }), ), observe: (observation) => observations.push(observation), }); const list = defineFeatureHttpOperation({ contract: TEST_LIST_HTTP_CONTRACT, routeId: ROUTE_ID, mapSuccess: (value) => mappingSuccess(value), }); const binding = createFeatureHttpBinding( { execute: (contract, input, context) => executor.execute(contract, input, { ...context, scope }), }, { [list.operationId]: list }, ); const result = await binding.execute(list.operationId, { limit: 20 }); expect(result).toMatchObject({ ok: false, error: { requestId: "server-ref-42" }, }); expect(observations.at(-1)?.correlationId).toBe("server-ref-42"); }); }); /** * D-2 (03-02). 401, 403 and 429 are admitted before any problem body is read. * The package may classify them by status; without a classifier, or when it * misbehaves, a dispatched command stays MAYBE_APPLIED. */ describe("command status classification", () => { function withStatusClassifier( classifyStatus: ((status: 401 | 403 | 429) => unknown) | undefined, ): InstalledHttpContract { return { ...createInstalled, contract: { ...createInstalled.contract, commandEffect: { ...createInstalled.contract.commandEffect!, ...(classifyStatus === undefined ? {} : { classifyStatus }), } as NonNullable, }, }; } async function effectFor( status: number, contract: InstalledHttpContract, ) { const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 0, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher: vi.fn(async () => new Response(null, { status })), }); const outcome = await executor.execute( contract, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent() }, ); return { kind: outcome.kind, effect: outcome.effect }; } it.each([ [401, "UNAUTHENTICATED"], [403, "FORBIDDEN"], [429, "RATE_LIMITED"], ] as const)("uses the package classifier for %i", async (status, kind) => { const classifyStatus = vi.fn(() => "NOT_APPLIED"); await expect( effectFor(status, withStatusClassifier(classifyStatus)), ).resolves.toEqual({ kind, effect: "NOT_APPLIED" }); expect(classifyStatus).toHaveBeenCalledWith(status); }); const throwingClassifier = (): unknown => { throw new Error("package defect"); }; const unknownAnswer = (): unknown => "APPLIED_CONFIRMED"; it.each([ ["no classifier", undefined], ["a throwing classifier", throwingClassifier], ["an unknown answer", unknownAnswer], ] as const)("keeps MAYBE_APPLIED for %s", async (_label, classifyStatus) => { for (const status of [401, 403, 429]) { await expect( effectFor(status, withStatusClassifier(classifyStatus)), ).resolves.toMatchObject({ effect: "MAYBE_APPLIED" }); } }); }); /** * Q-6.3-7. A retried command's final effect joins what earlier attempts already * established, and an answer that says the command may already be applied is * not replayed. */ describe("command effect across retries", () => { const idempotentCommand: InstalledHttpContract = { ...createInstalled, contract: { ...createInstalled.contract, retrySemantics: "IDEMPOTENT" as const, }, frontend: { ...createInstalled.frontend, retryBudget: 1 as const }, }; async function runThenReject(first: () => Promise) { const fetcher = vi .fn() .mockImplementationOnce(first) .mockImplementation(async () => // The fixture classifier reads a 400 problem as NOT_APPLIED. Response.json( { type: "about:blank", title: "rejected", status: 400 }, { status: 400 }, ), ); const executor = createContractHttpExecutor({ baseUrl: "https://api.example/", maxRetryAttempts: 1, attachCredentials: () => ({ kind: "READY", headers: {} }), fetcher, sleep: async () => {}, random: () => 0, }); const outcome = await executor.execute( idempotentCommand, { name: "created" }, { routeId: ROUTE_ID, scope, intent: mutationIntent({ idempotencyKey: null }), }, ); return { outcome, attempts: fetcher.mock.calls.length }; } it("keeps MAYBE_APPLIED when the retry after a lost response is rejected", async () => { await expect( runThenReject(async () => { throw new TypeError("connection reset"); }), ).resolves.toMatchObject({ attempts: 2, outcome: { kind: "PROBLEM", effect: "MAYBE_APPLIED" }, }); }); it("keeps MAYBE_APPLIED when the retry after a rate limit is rejected", async () => { await expect( runThenReject(async () => new Response(null, { status: 429 })), ).resolves.toMatchObject({ attempts: 2, outcome: { kind: "PROBLEM", effect: "MAYBE_APPLIED" }, }); }); it("does not replay a command whose gateway failure may already be applied", async () => { await expect( runThenReject(async () => new Response("", { status: 504 })), ).resolves.toMatchObject({ attempts: 1, outcome: { kind: "CONTRACT_VIOLATION", metadata: { status: 504 }, effect: "MAYBE_APPLIED", }, }); }); });