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" }); }); 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", }); }, ); }); /** * 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", }, }); }); });