문제 §10.8의 마지막 검사(src/adapters/http/http-execution-v3.ts:1493-1499, 검증을 통과한 성공 응답이라도 scope가 이미 현재가 아니면 SCOPE_FENCED) 를 false로 바꿔도 네 라운드째 모든 테스트가 통과한다(변이 L01). 지금 scope fence 테스트는 scope signal도 abort해서, abort 경로가 먼저 답하고 이 검사까지 오지 않는다. 고른 방법과 버린 대안 - tests/unit/http-execution-v3.test.ts에 경우 둘(조회·명령)을 더한다. fetch 안에서 scope의 isCurrent만 false로 바꾸고 signal은 abort하지 않는다. JSON 성공 경로에서 dispatch 뒤 scope를 보는 곳은 이 검사 하나라서, 검사를 지우면 SUCCESS가 나와 테스트가 실패한다. - 기대값: CONTRACT_VIOLATION/SCOPE_FENCED, 조회는 NOT_APPLICABLE, 명령은 MAYBE_APPLIED(보냈으니 적용됐을 수 있다). - 기존 abort 테스트를 바꾸는 안은 버렸다. 그 테스트는 abort가 먼저 이기는 경로를 지킨다. 위험·한계 - 테스트만 더했다. 실행기 코드는 그대로다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts - 변이 L01(:1494 조건을 false로)을 넣으면 "discards a valid read/command success that arrives after its scope stopped being current" 2건이 실패해야 한다. Refs: 0929/10-04
1423 lines
45 KiB
TypeScript
1423 lines
45 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",
|
|
});
|
|
});
|
|
|
|
// 0929/10-04. §10.8's last check: a valid success body for a scope that went
|
|
// stale while the request was out is discarded. The scope here only stops
|
|
// being current; its signal never aborts, so no earlier cancellation path
|
|
// answers first (the test above aborts it and never reaches this check).
|
|
it.each([
|
|
["read", "NOT_APPLICABLE"],
|
|
["command", "MAYBE_APPLIED"],
|
|
] as const)(
|
|
"discards a valid %s success that arrives after its scope stopped being current",
|
|
async (kind, effect) => {
|
|
let current = true;
|
|
const staleScope = Object.freeze({
|
|
...scope,
|
|
signal: new AbortController().signal,
|
|
isCurrent: () => current,
|
|
});
|
|
const executor = createContractHttpExecutor({
|
|
baseUrl: "https://api.example/",
|
|
maxRetryAttempts: 0,
|
|
attachCredentials: () => ({ kind: "READY", headers: {} }),
|
|
fetcher: vi.fn(async () => {
|
|
current = false;
|
|
return kind === "read"
|
|
? Response.json([{ id: "a", name: "A" }])
|
|
: Response.json({ id: "created", name: "Created" }, { status: 201 });
|
|
}),
|
|
});
|
|
|
|
const outcome =
|
|
kind === "read"
|
|
? await executor.execute(installed, { limit: 20 }, {
|
|
routeId: ROUTE_ID,
|
|
scope: staleScope,
|
|
})
|
|
: await executor.execute(createInstalled, { name: "created" }, {
|
|
routeId: ROUTE_ID,
|
|
scope: staleScope,
|
|
intent: mutationIntent({ intentId: "intent-3", idempotencyKey: "key-3" }),
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
kind: "CONTRACT_VIOLATION",
|
|
violation: { kind: "SCOPE_FENCED" },
|
|
effect,
|
|
});
|
|
},
|
|
);
|
|
|
|
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" });
|
|
});
|
|
|
|
// 1103/10-04 ②, 1105/10-02. A signal is shared by many requests (a screen,
|
|
// a session scope, one interaction that sends several requests). Every abort
|
|
// listener an execution adds to the caller's, the interaction's and the
|
|
// scope's signal is removed when it ends, however it ends.
|
|
it.each(["an answer", "a caller abort", "an interaction cancel"] as const)(
|
|
"removes the listeners it added to the caller, interaction and scope signals after %s",
|
|
async (ending) => {
|
|
const caller = new AbortController();
|
|
const scopeLifetime = new AbortController();
|
|
const interaction = createExecutionContext({
|
|
interactionId: "listener-cleanup",
|
|
deadlineMs: 10_000,
|
|
traffic: {
|
|
maxPhysicalRequests: 4,
|
|
maxRetries: 2,
|
|
maxConcurrentRequests: 1,
|
|
},
|
|
});
|
|
const watched = [
|
|
caller.signal,
|
|
interaction.cancellation.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,
|
|
execution: interaction,
|
|
});
|
|
if (ending === "a caller abort") caller.abort();
|
|
if (ending === "an interaction cancel") interaction.cancellation.cancel();
|
|
|
|
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<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",
|
|
},
|
|
});
|
|
});
|
|
});
|