Files
clean-architecture-frontend…/tests/unit/http-execution-v3.test.ts
T
DongHyeonkaandClaude Opus 5.5 f0a6495989 fix(http): never let request id generation block a V3 request (03-03)
crypto.randomUUID exists only in secure contexts. If it throws, the request
now goes out without x-correlation-id instead of ending as a runtime failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:56:22 +09:00

1317 lines
41 KiB
TypeScript

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<unknown, unknown, unknown> =
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<unknown, unknown, unknown> =
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<unknown, unknown, unknown> {
return {
...installed,
contract: {
...installed.contract,
responseBody: overrides.responseBody ?? installed.contract.responseBody,
},
frontend: {
...installed.frontend,
totalDeadlineMs: overrides.deadlineMs ?? installed.frontend.totalDeadlineMs,
},
};
}
async function flushMicrotasks(): Promise<void> {
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<boolean> {
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<string | null> = [];
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<string | null> = [];
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<unknown, unknown, unknown> = {
...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<Response>((_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<Uint8Array>({
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", "<html>Bad Gateway</html>"],
[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<never>(() => {});
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<Uint8Array>({
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<unknown, unknown, unknown> = {
...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<typeof fetch>((_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<typeof fetch>(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<typeof fetch>(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<typeof fetch>(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<unknown, unknown, unknown> {
return {
...createInstalled,
contract: {
...createInstalled.contract,
commandEffect: {
...createInstalled.contract.commandEffect!,
...(classifyStatus === undefined ? {} : { classifyStatus }),
} as NonNullable<typeof createInstalled.contract.commandEffect>,
},
};
}
async function effectFor(
status: number,
contract: InstalledHttpContract<unknown, unknown, unknown>,
) {
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<unknown, unknown, unknown> = {
...createInstalled,
contract: {
...createInstalled.contract,
retrySemantics: "IDEMPOTENT" as const,
},
frontend: { ...createInstalled.frontend, retryBudget: 1 as const },
};
async function runThenReject(first: () => Promise<Response>) {
const fetcher = vi
.fn<typeof fetch>()
.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",
},
});
});
});