fix(http): classify every terminal wait through terminalOutcomeFor (Q-6.3-6)
The executor decided the terminal outcome of an ended wait in six places
(credentials, lease, dispatch, transport backoff, admission, retry
backoff). The two backoff copies only checked the caller, so a scope
fence during a retry sleep ended as TRANSPORT_FAILURE{TIMEOUT} and the
user saw "timed out, retry" after logging out.
All six sites now call one terminalOutcomeFor(phase) helper: the caller
cancels, the deadline times out, a scope fence during a wait is
ABORTED_BY_SCOPE and during admission stays the SCOPE_FENCED violation.
Verified: a new owner x phase table in http-execution-v3.test.ts pins
the 16 existing combinations and failed RED only for the two backoff
scope-fence cases (TIMEOUT instead of ABORTED_BY_SCOPE). All lane gates
pass except the known removal-fixture test (missing artifacts/).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
042427c887
commit
4c7737361a
@@ -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<WireOutput, Problem> => {
|
||||
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<WireOutput, Problem>
|
||||
| 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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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<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",
|
||||
});
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user