diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 992c8aa2..9bfaf7ec 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -582,6 +582,31 @@ export function createContractHttpExecutor( return outcome; }; + /** + * Q-6.3-6. The one classifier for a wait that a terminal owner ended. The + * caller cancels and the deadline times out. A scope fence during a `WAIT` + * (credentials, lease, dispatch, backoff) aborts the transport; during + * `ADMISSION` the response headers prove the request reached the server, + * so a stale generation stays the `SCOPE_FENCED` contract violation. + */ + const terminalOutcomeFor = ( + phase: "WAIT" | "ADMISSION", + ): HttpExecutionOutcome => { + switch (terminalCancellation) { + case "CALLER": + return finish(cancelled(abandonedCertainty()), "CANCELLED"); + case "SCOPE_FENCE": + return phase === "ADMISSION" + ? finish(scopeFenced(abandonedCertainty()), "SCOPE_FENCED") + : finish( + abandonedTransportFailure("ABORTED_BY_SCOPE"), + "SCOPE_FENCED", + ); + default: + return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT"); + } + }; + try { // §7.7. The installed registry is the only source of a profile. Composition @@ -684,20 +709,7 @@ export function createContractHttpExecutor( "AUTH_INTEGRATION_FAILURE", ); } - if (patchResult === ABORTED) { - if (terminalCancellation === "SCOPE_FENCE") { - return finish( - abandonedTransportFailure("ABORTED_BY_SCOPE"), - "SCOPE_FENCED", - ); - } - return terminalCancellation === "CALLER" - ? finish(cancelled("NOT_STARTED"), "CANCELLED") - : finish( - abandonedTransportFailure("TIMEOUT"), - "TIMEOUT", - ); - } + if (patchResult === ABORTED) return terminalOutcomeFor("WAIT"); // NS-01. The whole answer is decoded once, inside the auth boundary, before // any field is used. Reading `kind` and `headers` off the raw object left // the decode outside that boundary: a throwing getter escaped into the @@ -818,16 +830,7 @@ export function createContractHttpExecutor( "TRAFFIC_BUDGET_EXCEEDED", ); } - if (terminalCancellation === "CALLER") { - return finish(cancelled(abandonedCertainty()), "CANCELLED"); - } - if (terminalCancellation === "SCOPE_FENCE") { - return finish( - abandonedTransportFailure("ABORTED_BY_SCOPE"), - "SCOPE_FENCED", - ); - } - return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT"); + return terminalOutcomeFor("WAIT"); } try { const controller = new AbortController(); @@ -919,22 +922,10 @@ export function createContractHttpExecutor( } else { clearTimeout(deadlineTimer); lifetimeController.signal.removeEventListener("abort", forwardLifetime); - const owner = terminalCancellation; - if (owner === "CALLER") { - return finish( - cancelled(abandonedCertainty()), - "CANCELLED", - ); + if (terminalCancellation !== null) { + return terminalOutcomeFor("WAIT"); } - if (owner === "SCOPE_FENCE") { - return finish( - abandonedTransportFailure("ABORTED_BY_SCOPE"), - "SCOPE_FENCED", - ); - } - const kind = owner === "DEADLINE" ? "TIMEOUT" : "NETWORK_FAILURE"; if ( - owner === null && canRetryTransport(contract.retrySemantics, attemptState) && retryIndex < retryCeiling && remaining() > 0 @@ -946,23 +937,13 @@ export function createContractHttpExecutor( sleep(delay, lifetimeController.signal), lifetimeController.signal, ); - if (slept === ABORTED) { - return terminalCancellation === "CALLER" - ? finish( - cancelled(abandonedCertainty()), - "CANCELLED", - ) - : finish( - abandonedTransportFailure("TIMEOUT"), - "TIMEOUT", - ); - } + if (slept === ABORTED) return terminalOutcomeFor("WAIT"); continue; } } return finish( - abandonedTransportFailure(kind), - kind, + abandonedTransportFailure("NETWORK_FAILURE"), + "NETWORK_FAILURE", ); } @@ -983,42 +964,22 @@ export function createContractHttpExecutor( controller.signal, () => cancelResponseBody(response), ); - // LIVE-04. Once response headers are in hand the request demonstrably - // reached the server, so a terminal owner that lands during admission - // keeps the dispatched classification: a stale generation stays the - // `SCOPE_FENCED` contract violation it has always been, and only the - // deadline and the caller reclassify the outcome. - const abandonAdmission = (): - | HttpExecutionOutcome - | null => { - switch (terminalCancellation) { - case "DEADLINE": - return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT"); - case "CALLER": - return finish(cancelled(abandonedCertainty()), "CANCELLED"); - case "SCOPE_FENCE": - return finish( - scopeFenced(abandonedCertainty()), - "SCOPE_FENCED", - ); - default: - return null; - } - }; + // LIVE-04. A terminal owner that lands during admission wins over the + // admitted answer. if (admission.kind !== "VALUE") { cancelResponseBody(response); - return ( - abandonAdmission() ?? - finish( - abandonedTransportFailure("NETWORK_FAILURE"), - "NETWORK_FAILURE", - ) - ); + return terminalCancellation === null + ? finish( + abandonedTransportFailure("NETWORK_FAILURE"), + "NETWORK_FAILURE", + ) + : terminalOutcomeFor("ADMISSION"); } const outcome = admission.value; attemptState = "SETTLED"; - const abandoned = abandonAdmission(); - if (abandoned) return abandoned; + if (terminalCancellation !== null) { + return terminalOutcomeFor("ADMISSION"); + } if ( outcome.retryHint && retryIndex < retryCeiling && @@ -1036,17 +997,7 @@ export function createContractHttpExecutor( sleep(delay, lifetimeController.signal), lifetimeController.signal, ); - if (slept === ABORTED) { - return terminalCancellation === "CALLER" - ? finish( - cancelled(abandonedCertainty()), - "CANCELLED", - ) - : finish( - abandonedTransportFailure("TIMEOUT"), - "TIMEOUT", - ); - } + if (slept === ABORTED) return terminalOutcomeFor("WAIT"); continue; } } diff --git a/tests/unit/http-execution-v3.test.ts b/tests/unit/http-execution-v3.test.ts index 85df28f7..0072910b 100644 --- a/tests/unit/http-execution-v3.test.ts +++ b/tests/unit/http-execution-v3.test.ts @@ -10,6 +10,10 @@ import { } 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, @@ -842,3 +846,148 @@ describe("gateway failures without a usable problem body", () => { }, ); }); + +/** + * 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", + }); + }, + ); +});