@copilotkit/aimock 1.46.0 → 1.47.0

package/dist/response/lifecycle.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.cjs","names":["responseGoneReason","createInterruptionSignal"],"sources":["../../src/response/lifecycle.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport type { Fixture, JournalEntry } from \"../types.js\";\nimport type { WebSocketConnection } from \"../ws-framing.js\";\nimport { createInterruptionSignal, type InterruptionControl } from \"../interruption.js\";\nimport { responseGoneReason } from \"../chaos.js\";\n\n/** The journal `interruptReason` for a client that left before the reply finished. */\nexport const CLIENT_ABORTED = \"client aborted\";\n\n/**\n * The journal `interruptReason` for a response aimock tore down itself: the\n * chaos `disconnect` action or a server-side `destroy`. It is the name the\n * chaos journal entry records (`chaosAction: \"disconnect\"`), so a teardown\n * aimock caused is never blamed on the client.\n */\nexport const AIMOCK_DISCONNECTED = \"disconnect\";\n\n/**\n * Which side stopped a delivery first: the client, the fixture's own\n * interruption, or aimock tearing the response down (`\"server\"`).\n */\nexport type InterruptCause = \"client\" | \"fixture\" | \"server\";\n\n/**\n * One delivery's stop signal. It merges the fixture interruption\n * (`truncateAfterChunks` / `disconnectAfterMs`) with the client going away\n * and with aimock tearing the response down (`\"server\"`).\n * The first cause wins: a later cause never reclassifies it.\n */\nexport interface DeliveryLifecycle {\n  /** Aborts on the first cause: fixture, client, or server. */\n  readonly signal: AbortSignal;\n  /** The cause that aborted `signal`, or `undefined` while it has not aborted. */\n  cause(): InterruptCause | undefined;\n  /**\n   * The fixture's reason, {@link CLIENT_ABORTED}, {@link AIMOCK_DISCONNECTED},\n   * or `undefined` while running.\n   */\n  reason(): string | undefined;\n  /** Forwards a sent chunk to the fixture interruption (counts toward `truncateAfterChunks`). */\n  tick(): void;\n  /** Removes the close and fixture-abort listeners and clears the fixture's `disconnectAfterMs` timer. */\n  dispose(): void;\n}\n\n/** The part of an EventEmitter a close source may expose. Test doubles may carry less. */\ninterface CloseSource {\n  once?: (event: \"close\", listener: () => void) => unknown;\n  off?: (event: \"close\", listener: () => void) => unknown;\n  removeListener?: (event: \"close\", listener: () => void) => unknown;\n}\n\n/**\n * Subscribe to `close`, guarded the same way as `awaitChaosLatency`: a partial\n * test double without `once` is not subscribed, and only a listener that was\n * added is ever removed, through a remover that exists.\n */\nfunction subscribeClose(source: CloseSource, onClose: () => void): (() => void) | undefined {\n  if (typeof source.once !== \"function\") return undefined;\n  source.once(\"close\", onClose);\n  if (typeof source.off === \"function\") return () => source.off?.(\"close\", onClose);\n  if (typeof source.removeListener === \"function\")\n    return () => source.removeListener?.(\"close\", onClose);\n  return undefined;\n}\n\nfunction createLifecycle(\n  interruption: InterruptionControl | null,\n  goneAtStart: InterruptCause | undefined,\n  subscribe: (onGone: (cause: InterruptCause) => void) => (() => void) | undefined,\n): DeliveryLifecycle {\n  const controller = new AbortController();\n  let firstCause: InterruptCause | undefined;\n  const abortWith = (cause: InterruptCause): void => {\n    if (controller.signal.aborted) return;\n    firstCause = cause;\n    controller.abort();\n  };\n  const onFixtureAbort = (): void => abortWith(\"fixture\");\n  interruption?.signal.addEventListener(\"abort\", onFixtureAbort, { once: true });\n  let unsubscribe: (() => void) | undefined;\n  if (goneAtStart !== undefined) abortWith(goneAtStart);\n  else unsubscribe = subscribe(abortWith);\n  return {\n    signal: controller.signal,\n    cause: () => firstCause,\n    reason: () => {\n      if (firstCause === \"fixture\") return interruption?.reason();\n      if (firstCause === \"client\") return CLIENT_ABORTED;\n      if (firstCause === \"server\") return AIMOCK_DISCONNECTED;\n      return undefined;\n    },\n    tick: () => {\n      interruption?.tick();\n    },\n    dispose: () => {\n      unsubscribe?.();\n      unsubscribe = undefined;\n      interruption?.signal.removeEventListener(\"abort\", onFixtureAbort);\n      interruption?.cleanup();\n    },\n  };\n}\n\n/** The request socket fields the teardown rule and the status-line rule read. */\nexport interface PeerSocket {\n  readonly errored?: Error | null;\n  readonly writableEnded?: boolean;\n  readonly bytesWritten?: number;\n}\n\n/** Where a response's request socket can be read from. Test doubles may carry neither. */\ninterface SocketOwner {\n  readonly req?: { readonly socket?: PeerSocket | null };\n  readonly socket?: PeerSocket | null;\n}\n\n/** The request socket of `res`, or `undefined` when it carries none. */\nexport function requestSocket(res: http.ServerResponse): PeerSocket | undefined {\n  const owner: SocketOwner = res;\n  return owner.req?.socket ?? owner.socket ?? undefined;\n}\n\n/**\n * THE client hang-up rule, shared by the delivery lifecycle and the proxy\n * relay: the client's socket closed or reset.\n *\n * - A reset, or a write into a socket the peer closed, leaves `errored` set\n *   (ECONNRESET / EPIPE).\n * - aimock's server keeps Node's default `httpAllowHalfOpen: false`, so a\n *   client FIN makes Node end our write side: the socket is `writableEnded`\n *   while the response is not. That is the evidence the client closed.\n *\n * A FIN alone (`readableEnded` with neither of those) is not a hang-up: it is\n * what the socket shows when aimock tore the response down before Node\n * answered the FIN. A real client FIN that Node has not answered yet looks the\n * same, so this rule also classifies it as not a hang-up. aimock's own\n * `destroy()` leaves neither signal.\n */\nexport function closedByClient(socket: PeerSocket): boolean {\n  return (socket.errored ?? null) !== null || socket.writableEnded === true;\n}\n\n/**\n * Who tore down a response that is gone without having ended. After the fact\n * `res.destroyed` reads the same either way, so this reads the evidence:\n *\n * - a chaos `disconnect` marked the response before destroying it: aimock;\n * - the request socket meets {@link closedByClient}: the client;\n * - neither: aimock destroyed it server-side.\n *\n * `socket` defaults to the response's request socket. With no socket to read\n * (a partial test double) the client attribution is kept.\n */\nexport function teardownCause(\n  res: http.ServerResponse,\n  socket: PeerSocket | null | undefined = requestSocket(res),\n): \"client\" | \"server\" {\n  if (responseGoneReason(res) === \"chaos-disconnected\") return \"server\";\n  if (!socket) return \"client\";\n  return closedByClient(socket) ? \"client\" : \"server\";\n}\n\n/**\n * The request socket's `bytesWritten` when each delivery started, so the\n * status-line rule counts only this response's bytes on a keep-alive socket.\n */\nconst deliveryStartBytes = new WeakMap<http.ServerResponse, number>();\n\n/**\n * Record where this response's bytes start on its socket. A response whose\n * head was already committed when the delivery started is not recorded:\n * {@link statusLineSent} keeps the `headersSent` rule for it.\n */\nexport function noteDeliveryStart(res: http.ServerResponse): void {\n  if (deliveryStartBytes.has(res) || res.headersSent) return;\n  const bytes = requestSocket(res)?.bytesWritten;\n  if (typeof bytes === \"number\") deliveryStartBytes.set(res, bytes);\n}\n\n/**\n * Whether this response's status line reached the client's socket: a byte of\n * it was handed to the socket after {@link noteDeliveryStart}. `headersSent`\n * is not that test: `writeHead` sets it before any byte is written. With no\n * recorded start, or no socket to read, `headersSent` is the fallback.\n */\nexport function statusLineSent(res: http.ServerResponse): boolean {\n  const start = deliveryStartBytes.get(res);\n  const bytes = requestSocket(res)?.bytesWritten;\n  if (start === undefined || typeof bytes !== \"number\") return res.headersSent;\n  return bytes > start;\n}\n\n/** The journal `interruptReason` for {@link teardownCause}. */\nexport function teardownReason(res: http.ServerResponse): string {\n  return teardownCause(res) === \"client\" ? CLIENT_ABORTED : AIMOCK_DISCONNECTED;\n}\n\n/**\n * HTTP delivery lifecycle. A `close` before `res.writableFinished` aborts it,\n * and {@link teardownCause} decides whose teardown it was: the client\n * (`\"client\"`) or aimock itself (`\"server\"`). A response that is already gone\n * at construction aborts at once with the same attribution. A chaos\n * `disconnect` destroys without ending, so no `writableEnded` check stops a\n * writer for it. Only an already-ended response does not abort: the frame\n * loop exits on its `writableEnded` check. The fixture interruption is\n * created only when `streaming` is true (it is streaming-only).\n */\nexport function httpLifecycle(\n  res: http.ServerResponse,\n  fixture: Fixture | null,\n  opts: { streaming: boolean },\n): DeliveryLifecycle {\n  const interruption = opts.streaming && fixture ? createInterruptionSignal(fixture) : null;\n  const gone = responseGoneReason(res);\n  const goneAtStart = gone === null || gone === \"already-ended\" ? undefined : teardownCause(res);\n  return createLifecycle(interruption, goneAtStart, (onGone) =>\n    subscribeClose(res, () => {\n      if (!res.writableFinished) onGone(teardownCause(res));\n    }),\n  );\n}\n\n/**\n * Per watched connection: whether its `close` event has fired. Only sockets\n * watched while open are recorded, so an entry is evidence, not a guess.\n */\nconst wsCloseEmitted = new WeakMap<WebSocketConnection, boolean>();\n\n/**\n * Start recording when `ws` emits `close`, so {@link wsClosedCause} can tell\n * aimock's own close from the client's. Each WS transport calls it when the\n * connection opens. Idempotent, and a no-op once closed.\n */\nexport function watchWsClose(ws: WebSocketConnection): void {\n  if (ws.isClosed || wsCloseEmitted.has(ws)) return;\n  const source: CloseSource = ws;\n  if (typeof source.once !== \"function\") return;\n  wsCloseEmitted.set(ws, false);\n  source.once(\"close\", () => wsCloseEmitted.set(ws, true));\n}\n\n/**\n * Who closed a socket that reads `isClosed`, or `undefined` while it is open.\n *\n * `WebSocketConnection` marks itself closed and emits `close` in the same step\n * for a client close frame, a lost connection, and `destroy()`. Only aimock's\n * own `close()` (a write or buffer limit, a bad frame, a strict miss, shutdown)\n * marks it closed at once and emits `close` about 100ms later. So a socket\n * watched while open ({@link watchWsClose}) that is closed with no `close` yet\n * was closed by aimock (`\"server\"`). Any other closed socket reads as the\n * client leaving, as before.\n */\nexport function wsClosedCause(ws: WebSocketConnection): \"client\" | \"server\" | undefined {\n  if (!ws.isClosed) return undefined;\n  return wsCloseEmitted.get(ws) === false ? \"server\" : \"client\";\n}\n\n/**\n * WebSocket turn lifecycle. A WS turn is always a stream, so it always owns\n * the fixture interruption. A `close` means the client left. A socket already\n * closed at construction aborts at once with {@link wsClosedCause}. Callers\n * never create their own interruption object.\n */\nexport function wsLifecycle(ws: WebSocketConnection, fixture: Fixture | null): DeliveryLifecycle {\n  const interruption = fixture ? createInterruptionSignal(fixture) : null;\n  return createLifecycle(interruption, wsClosedCause(ws), (onGone) =>\n    subscribeClose(ws, () => onGone(\"client\")),\n  );\n}\n\n/**\n * Journal a WS turn that stopped because its lifecycle aborted or its socket\n * closed. This is the closed-socket rule every WS transport uses: the\n * lifecycle's reason when it has one, else the closed socket's cause\n * ({@link wsClosedCause}): {@link AIMOCK_DISCONNECTED} for aimock's own close,\n * {@link CLIENT_ABORTED} for the client. A turn with no lifecycle (it never\n * waits) passes none.\n */\nexport function markWsTurnStopped(\n  entry: JournalEntry,\n  ws: WebSocketConnection,\n  lifecycle?: DeliveryLifecycle,\n): void {\n  const cause = wsClosedCause(ws);\n  const socketReason =\n    cause === \"server\" ? AIMOCK_DISCONNECTED : cause === \"client\" ? CLIENT_ABORTED : undefined;\n  markInterrupted(entry, lifecycle?.reason() ?? socketReason);\n}\n\n/**\n * Mark a journal entry interrupted. The reason is set only when the entry has\n * none, so a later `undefined` never erases an earlier reason. The status is\n * never changed: the entry keeps the status it was journaled with.\n */\nexport function markInterrupted(entry: JournalEntry, reason: string | undefined): void {\n  entry.response.interrupted = true;\n  if (entry.response.interruptReason === undefined && reason !== undefined) {\n    entry.response.interruptReason = reason;\n  }\n}\n"],"mappings":"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"}

package/dist/response/lifecycle.js

@@ -0,0 +1,211 @@
+import { responseGoneReason } from "../chaos.js";
+import { createInterruptionSignal } from "../interruption.js";
+
+//#region src/response/lifecycle.ts
+/** The journal `interruptReason` for a client that left before the reply finished. */
+const CLIENT_ABORTED = "client aborted";
+/**
+* The journal `interruptReason` for a response aimock tore down itself: the
+* chaos `disconnect` action or a server-side `destroy`. It is the name the
+* chaos journal entry records (`chaosAction: "disconnect"`), so a teardown
+* aimock caused is never blamed on the client.
+*/
+const AIMOCK_DISCONNECTED = "disconnect";
+/**
+* Subscribe to `close`, guarded the same way as `awaitChaosLatency`: a partial
+* test double without `once` is not subscribed, and only a listener that was
+* added is ever removed, through a remover that exists.
+*/
+function subscribeClose(source, onClose) {
+	if (typeof source.once !== "function") return void 0;
+	source.once("close", onClose);
+	if (typeof source.off === "function") return () => source.off?.("close", onClose);
+	if (typeof source.removeListener === "function") return () => source.removeListener?.("close", onClose);
+}
+function createLifecycle(interruption, goneAtStart, subscribe) {
+	const controller = new AbortController();
+	let firstCause;
+	const abortWith = (cause) => {
+		if (controller.signal.aborted) return;
+		firstCause = cause;
+		controller.abort();
+	};
+	const onFixtureAbort = () => abortWith("fixture");
+	interruption?.signal.addEventListener("abort", onFixtureAbort, { once: true });
+	let unsubscribe;
+	if (goneAtStart !== void 0) abortWith(goneAtStart);
+	else unsubscribe = subscribe(abortWith);
+	return {
+		signal: controller.signal,
+		cause: () => firstCause,
+		reason: () => {
+			if (firstCause === "fixture") return interruption?.reason();
+			if (firstCause === "client") return CLIENT_ABORTED;
+			if (firstCause === "server") return AIMOCK_DISCONNECTED;
+		},
+		tick: () => {
+			interruption?.tick();
+		},
+		dispose: () => {
+			unsubscribe?.();
+			unsubscribe = void 0;
+			interruption?.signal.removeEventListener("abort", onFixtureAbort);
+			interruption?.cleanup();
+		}
+	};
+}
+/** The request socket of `res`, or `undefined` when it carries none. */
+function requestSocket(res) {
+	const owner = res;
+	return owner.req?.socket ?? owner.socket ?? void 0;
+}
+/**
+* THE client hang-up rule, shared by the delivery lifecycle and the proxy
+* relay: the client's socket closed or reset.
+*
+* - A reset, or a write into a socket the peer closed, leaves `errored` set
+*   (ECONNRESET / EPIPE).
+* - aimock's server keeps Node's default `httpAllowHalfOpen: false`, so a
+*   client FIN makes Node end our write side: the socket is `writableEnded`
+*   while the response is not. That is the evidence the client closed.
+*
+* A FIN alone (`readableEnded` with neither of those) is not a hang-up: it is
+* what the socket shows when aimock tore the response down before Node
+* answered the FIN. A real client FIN that Node has not answered yet looks the
+* same, so this rule also classifies it as not a hang-up. aimock's own
+* `destroy()` leaves neither signal.
+*/
+function closedByClient(socket) {
+	return (socket.errored ?? null) !== null || socket.writableEnded === true;
+}
+/**
+* Who tore down a response that is gone without having ended. After the fact
+* `res.destroyed` reads the same either way, so this reads the evidence:
+*
+* - a chaos `disconnect` marked the response before destroying it: aimock;
+* - the request socket meets {@link closedByClient}: the client;
+* - neither: aimock destroyed it server-side.
+*
+* `socket` defaults to the response's request socket. With no socket to read
+* (a partial test double) the client attribution is kept.
+*/
+function teardownCause(res, socket = requestSocket(res)) {
+	if (responseGoneReason(res) === "chaos-disconnected") return "server";
+	if (!socket) return "client";
+	return closedByClient(socket) ? "client" : "server";
+}
+/**
+* The request socket's `bytesWritten` when each delivery started, so the
+* status-line rule counts only this response's bytes on a keep-alive socket.
+*/
+const deliveryStartBytes = /* @__PURE__ */ new WeakMap();
+/**
+* Record where this response's bytes start on its socket. A response whose
+* head was already committed when the delivery started is not recorded:
+* {@link statusLineSent} keeps the `headersSent` rule for it.
+*/
+function noteDeliveryStart(res) {
+	if (deliveryStartBytes.has(res) || res.headersSent) return;
+	const bytes = requestSocket(res)?.bytesWritten;
+	if (typeof bytes === "number") deliveryStartBytes.set(res, bytes);
+}
+/**
+* Whether this response's status line reached the client's socket: a byte of
+* it was handed to the socket after {@link noteDeliveryStart}. `headersSent`
+* is not that test: `writeHead` sets it before any byte is written. With no
+* recorded start, or no socket to read, `headersSent` is the fallback.
+*/
+function statusLineSent(res) {
+	const start = deliveryStartBytes.get(res);
+	const bytes = requestSocket(res)?.bytesWritten;
+	if (start === void 0 || typeof bytes !== "number") return res.headersSent;
+	return bytes > start;
+}
+/** The journal `interruptReason` for {@link teardownCause}. */
+function teardownReason(res) {
+	return teardownCause(res) === "client" ? CLIENT_ABORTED : AIMOCK_DISCONNECTED;
+}
+/**
+* HTTP delivery lifecycle. A `close` before `res.writableFinished` aborts it,
+* and {@link teardownCause} decides whose teardown it was: the client
+* (`"client"`) or aimock itself (`"server"`). A response that is already gone
+* at construction aborts at once with the same attribution. A chaos
+* `disconnect` destroys without ending, so no `writableEnded` check stops a
+* writer for it. Only an already-ended response does not abort: the frame
+* loop exits on its `writableEnded` check. The fixture interruption is
+* created only when `streaming` is true (it is streaming-only).
+*/
+function httpLifecycle(res, fixture, opts) {
+	const interruption = opts.streaming && fixture ? createInterruptionSignal(fixture) : null;
+	const gone = responseGoneReason(res);
+	return createLifecycle(interruption, gone === null || gone === "already-ended" ? void 0 : teardownCause(res), (onGone) => subscribeClose(res, () => {
+		if (!res.writableFinished) onGone(teardownCause(res));
+	}));
+}
+/**
+* Per watched connection: whether its `close` event has fired. Only sockets
+* watched while open are recorded, so an entry is evidence, not a guess.
+*/
+const wsCloseEmitted = /* @__PURE__ */ new WeakMap();
+/**
+* Start recording when `ws` emits `close`, so {@link wsClosedCause} can tell
+* aimock's own close from the client's. Each WS transport calls it when the
+* connection opens. Idempotent, and a no-op once closed.
+*/
+function watchWsClose(ws) {
+	if (ws.isClosed || wsCloseEmitted.has(ws)) return;
+	const source = ws;
+	if (typeof source.once !== "function") return;
+	wsCloseEmitted.set(ws, false);
+	source.once("close", () => wsCloseEmitted.set(ws, true));
+}
+/**
+* Who closed a socket that reads `isClosed`, or `undefined` while it is open.
+*
+* `WebSocketConnection` marks itself closed and emits `close` in the same step
+* for a client close frame, a lost connection, and `destroy()`. Only aimock's
+* own `close()` (a write or buffer limit, a bad frame, a strict miss, shutdown)
+* marks it closed at once and emits `close` about 100ms later. So a socket
+* watched while open ({@link watchWsClose}) that is closed with no `close` yet
+* was closed by aimock (`"server"`). Any other closed socket reads as the
+* client leaving, as before.
+*/
+function wsClosedCause(ws) {
+	if (!ws.isClosed) return void 0;
+	return wsCloseEmitted.get(ws) === false ? "server" : "client";
+}
+/**
+* WebSocket turn lifecycle. A WS turn is always a stream, so it always owns
+* the fixture interruption. A `close` means the client left. A socket already
+* closed at construction aborts at once with {@link wsClosedCause}. Callers
+* never create their own interruption object.
+*/
+function wsLifecycle(ws, fixture) {
+	return createLifecycle(fixture ? createInterruptionSignal(fixture) : null, wsClosedCause(ws), (onGone) => subscribeClose(ws, () => onGone("client")));
+}
+/**
+* Journal a WS turn that stopped because its lifecycle aborted or its socket
+* closed. This is the closed-socket rule every WS transport uses: the
+* lifecycle's reason when it has one, else the closed socket's cause
+* ({@link wsClosedCause}): {@link AIMOCK_DISCONNECTED} for aimock's own close,
+* {@link CLIENT_ABORTED} for the client. A turn with no lifecycle (it never
+* waits) passes none.
+*/
+function markWsTurnStopped(entry, ws, lifecycle) {
+	const cause = wsClosedCause(ws);
+	const socketReason = cause === "server" ? AIMOCK_DISCONNECTED : cause === "client" ? CLIENT_ABORTED : void 0;
+	markInterrupted(entry, lifecycle?.reason() ?? socketReason);
+}
+/**
+* Mark a journal entry interrupted. The reason is set only when the entry has
+* none, so a later `undefined` never erases an earlier reason. The status is
+* never changed: the entry keeps the status it was journaled with.
+*/
+function markInterrupted(entry, reason) {
+	entry.response.interrupted = true;
+	if (entry.response.interruptReason === void 0 && reason !== void 0) entry.response.interruptReason = reason;
+}
+
+//#endregion
+export { AIMOCK_DISCONNECTED, CLIENT_ABORTED, closedByClient, httpLifecycle, markInterrupted, markWsTurnStopped, noteDeliveryStart, requestSocket, statusLineSent, teardownCause, teardownReason, watchWsClose, wsLifecycle };
+//# sourceMappingURL=lifecycle.js.map

package/dist/response/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","names":[],"sources":["../../src/response/lifecycle.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport type { Fixture, JournalEntry } from \"../types.js\";\nimport type { WebSocketConnection } from \"../ws-framing.js\";\nimport { createInterruptionSignal, type InterruptionControl } from \"../interruption.js\";\nimport { responseGoneReason } from \"../chaos.js\";\n\n/** The journal `interruptReason` for a client that left before the reply finished. */\nexport const CLIENT_ABORTED = \"client aborted\";\n\n/**\n * The journal `interruptReason` for a response aimock tore down itself: the\n * chaos `disconnect` action or a server-side `destroy`. It is the name the\n * chaos journal entry records (`chaosAction: \"disconnect\"`), so a teardown\n * aimock caused is never blamed on the client.\n */\nexport const AIMOCK_DISCONNECTED = \"disconnect\";\n\n/**\n * Which side stopped a delivery first: the client, the fixture's own\n * interruption, or aimock tearing the response down (`\"server\"`).\n */\nexport type InterruptCause = \"client\" | \"fixture\" | \"server\";\n\n/**\n * One delivery's stop signal. It merges the fixture interruption\n * (`truncateAfterChunks` / `disconnectAfterMs`) with the client going away\n * and with aimock tearing the response down (`\"server\"`).\n * The first cause wins: a later cause never reclassifies it.\n */\nexport interface DeliveryLifecycle {\n  /** Aborts on the first cause: fixture, client, or server. */\n  readonly signal: AbortSignal;\n  /** The cause that aborted `signal`, or `undefined` while it has not aborted. */\n  cause(): InterruptCause | undefined;\n  /**\n   * The fixture's reason, {@link CLIENT_ABORTED}, {@link AIMOCK_DISCONNECTED},\n   * or `undefined` while running.\n   */\n  reason(): string | undefined;\n  /** Forwards a sent chunk to the fixture interruption (counts toward `truncateAfterChunks`). */\n  tick(): void;\n  /** Removes the close and fixture-abort listeners and clears the fixture's `disconnectAfterMs` timer. */\n  dispose(): void;\n}\n\n/** The part of an EventEmitter a close source may expose. Test doubles may carry less. */\ninterface CloseSource {\n  once?: (event: \"close\", listener: () => void) => unknown;\n  off?: (event: \"close\", listener: () => void) => unknown;\n  removeListener?: (event: \"close\", listener: () => void) => unknown;\n}\n\n/**\n * Subscribe to `close`, guarded the same way as `awaitChaosLatency`: a partial\n * test double without `once` is not subscribed, and only a listener that was\n * added is ever removed, through a remover that exists.\n */\nfunction subscribeClose(source: CloseSource, onClose: () => void): (() => void) | undefined {\n  if (typeof source.once !== \"function\") return undefined;\n  source.once(\"close\", onClose);\n  if (typeof source.off === \"function\") return () => source.off?.(\"close\", onClose);\n  if (typeof source.removeListener === \"function\")\n    return () => source.removeListener?.(\"close\", onClose);\n  return undefined;\n}\n\nfunction createLifecycle(\n  interruption: InterruptionControl | null,\n  goneAtStart: InterruptCause | undefined,\n  subscribe: (onGone: (cause: InterruptCause) => void) => (() => void) | undefined,\n): DeliveryLifecycle {\n  const controller = new AbortController();\n  let firstCause: InterruptCause | undefined;\n  const abortWith = (cause: InterruptCause): void => {\n    if (controller.signal.aborted) return;\n    firstCause = cause;\n    controller.abort();\n  };\n  const onFixtureAbort = (): void => abortWith(\"fixture\");\n  interruption?.signal.addEventListener(\"abort\", onFixtureAbort, { once: true });\n  let unsubscribe: (() => void) | undefined;\n  if (goneAtStart !== undefined) abortWith(goneAtStart);\n  else unsubscribe = subscribe(abortWith);\n  return {\n    signal: controller.signal,\n    cause: () => firstCause,\n    reason: () => {\n      if (firstCause === \"fixture\") return interruption?.reason();\n      if (firstCause === \"client\") return CLIENT_ABORTED;\n      if (firstCause === \"server\") return AIMOCK_DISCONNECTED;\n      return undefined;\n    },\n    tick: () => {\n      interruption?.tick();\n    },\n    dispose: () => {\n      unsubscribe?.();\n      unsubscribe = undefined;\n      interruption?.signal.removeEventListener(\"abort\", onFixtureAbort);\n      interruption?.cleanup();\n    },\n  };\n}\n\n/** The request socket fields the teardown rule and the status-line rule read. */\nexport interface PeerSocket {\n  readonly errored?: Error | null;\n  readonly writableEnded?: boolean;\n  readonly bytesWritten?: number;\n}\n\n/** Where a response's request socket can be read from. Test doubles may carry neither. */\ninterface SocketOwner {\n  readonly req?: { readonly socket?: PeerSocket | null };\n  readonly socket?: PeerSocket | null;\n}\n\n/** The request socket of `res`, or `undefined` when it carries none. */\nexport function requestSocket(res: http.ServerResponse): PeerSocket | undefined {\n  const owner: SocketOwner = res;\n  return owner.req?.socket ?? owner.socket ?? undefined;\n}\n\n/**\n * THE client hang-up rule, shared by the delivery lifecycle and the proxy\n * relay: the client's socket closed or reset.\n *\n * - A reset, or a write into a socket the peer closed, leaves `errored` set\n *   (ECONNRESET / EPIPE).\n * - aimock's server keeps Node's default `httpAllowHalfOpen: false`, so a\n *   client FIN makes Node end our write side: the socket is `writableEnded`\n *   while the response is not. That is the evidence the client closed.\n *\n * A FIN alone (`readableEnded` with neither of those) is not a hang-up: it is\n * what the socket shows when aimock tore the response down before Node\n * answered the FIN. A real client FIN that Node has not answered yet looks the\n * same, so this rule also classifies it as not a hang-up. aimock's own\n * `destroy()` leaves neither signal.\n */\nexport function closedByClient(socket: PeerSocket): boolean {\n  return (socket.errored ?? null) !== null || socket.writableEnded === true;\n}\n\n/**\n * Who tore down a response that is gone without having ended. After the fact\n * `res.destroyed` reads the same either way, so this reads the evidence:\n *\n * - a chaos `disconnect` marked the response before destroying it: aimock;\n * - the request socket meets {@link closedByClient}: the client;\n * - neither: aimock destroyed it server-side.\n *\n * `socket` defaults to the response's request socket. With no socket to read\n * (a partial test double) the client attribution is kept.\n */\nexport function teardownCause(\n  res: http.ServerResponse,\n  socket: PeerSocket | null | undefined = requestSocket(res),\n): \"client\" | \"server\" {\n  if (responseGoneReason(res) === \"chaos-disconnected\") return \"server\";\n  if (!socket) return \"client\";\n  return closedByClient(socket) ? \"client\" : \"server\";\n}\n\n/**\n * The request socket's `bytesWritten` when each delivery started, so the\n * status-line rule counts only this response's bytes on a keep-alive socket.\n */\nconst deliveryStartBytes = new WeakMap<http.ServerResponse, number>();\n\n/**\n * Record where this response's bytes start on its socket. A response whose\n * head was already committed when the delivery started is not recorded:\n * {@link statusLineSent} keeps the `headersSent` rule for it.\n */\nexport function noteDeliveryStart(res: http.ServerResponse): void {\n  if (deliveryStartBytes.has(res) || res.headersSent) return;\n  const bytes = requestSocket(res)?.bytesWritten;\n  if (typeof bytes === \"number\") deliveryStartBytes.set(res, bytes);\n}\n\n/**\n * Whether this response's status line reached the client's socket: a byte of\n * it was handed to the socket after {@link noteDeliveryStart}. `headersSent`\n * is not that test: `writeHead` sets it before any byte is written. With no\n * recorded start, or no socket to read, `headersSent` is the fallback.\n */\nexport function statusLineSent(res: http.ServerResponse): boolean {\n  const start = deliveryStartBytes.get(res);\n  const bytes = requestSocket(res)?.bytesWritten;\n  if (start === undefined || typeof bytes !== \"number\") return res.headersSent;\n  return bytes > start;\n}\n\n/** The journal `interruptReason` for {@link teardownCause}. */\nexport function teardownReason(res: http.ServerResponse): string {\n  return teardownCause(res) === \"client\" ? CLIENT_ABORTED : AIMOCK_DISCONNECTED;\n}\n\n/**\n * HTTP delivery lifecycle. A `close` before `res.writableFinished` aborts it,\n * and {@link teardownCause} decides whose teardown it was: the client\n * (`\"client\"`) or aimock itself (`\"server\"`). A response that is already gone\n * at construction aborts at once with the same attribution. A chaos\n * `disconnect` destroys without ending, so no `writableEnded` check stops a\n * writer for it. Only an already-ended response does not abort: the frame\n * loop exits on its `writableEnded` check. The fixture interruption is\n * created only when `streaming` is true (it is streaming-only).\n */\nexport function httpLifecycle(\n  res: http.ServerResponse,\n  fixture: Fixture | null,\n  opts: { streaming: boolean },\n): DeliveryLifecycle {\n  const interruption = opts.streaming && fixture ? createInterruptionSignal(fixture) : null;\n  const gone = responseGoneReason(res);\n  const goneAtStart = gone === null || gone === \"already-ended\" ? undefined : teardownCause(res);\n  return createLifecycle(interruption, goneAtStart, (onGone) =>\n    subscribeClose(res, () => {\n      if (!res.writableFinished) onGone(teardownCause(res));\n    }),\n  );\n}\n\n/**\n * Per watched connection: whether its `close` event has fired. Only sockets\n * watched while open are recorded, so an entry is evidence, not a guess.\n */\nconst wsCloseEmitted = new WeakMap<WebSocketConnection, boolean>();\n\n/**\n * Start recording when `ws` emits `close`, so {@link wsClosedCause} can tell\n * aimock's own close from the client's. Each WS transport calls it when the\n * connection opens. Idempotent, and a no-op once closed.\n */\nexport function watchWsClose(ws: WebSocketConnection): void {\n  if (ws.isClosed || wsCloseEmitted.has(ws)) return;\n  const source: CloseSource = ws;\n  if (typeof source.once !== \"function\") return;\n  wsCloseEmitted.set(ws, false);\n  source.once(\"close\", () => wsCloseEmitted.set(ws, true));\n}\n\n/**\n * Who closed a socket that reads `isClosed`, or `undefined` while it is open.\n *\n * `WebSocketConnection` marks itself closed and emits `close` in the same step\n * for a client close frame, a lost connection, and `destroy()`. Only aimock's\n * own `close()` (a write or buffer limit, a bad frame, a strict miss, shutdown)\n * marks it closed at once and emits `close` about 100ms later. So a socket\n * watched while open ({@link watchWsClose}) that is closed with no `close` yet\n * was closed by aimock (`\"server\"`). Any other closed socket reads as the\n * client leaving, as before.\n */\nexport function wsClosedCause(ws: WebSocketConnection): \"client\" | \"server\" | undefined {\n  if (!ws.isClosed) return undefined;\n  return wsCloseEmitted.get(ws) === false ? \"server\" : \"client\";\n}\n\n/**\n * WebSocket turn lifecycle. A WS turn is always a stream, so it always owns\n * the fixture interruption. A `close` means the client left. A socket already\n * closed at construction aborts at once with {@link wsClosedCause}. Callers\n * never create their own interruption object.\n */\nexport function wsLifecycle(ws: WebSocketConnection, fixture: Fixture | null): DeliveryLifecycle {\n  const interruption = fixture ? createInterruptionSignal(fixture) : null;\n  return createLifecycle(interruption, wsClosedCause(ws), (onGone) =>\n    subscribeClose(ws, () => onGone(\"client\")),\n  );\n}\n\n/**\n * Journal a WS turn that stopped because its lifecycle aborted or its socket\n * closed. This is the closed-socket rule every WS transport uses: the\n * lifecycle's reason when it has one, else the closed socket's cause\n * ({@link wsClosedCause}): {@link AIMOCK_DISCONNECTED} for aimock's own close,\n * {@link CLIENT_ABORTED} for the client. A turn with no lifecycle (it never\n * waits) passes none.\n */\nexport function markWsTurnStopped(\n  entry: JournalEntry,\n  ws: WebSocketConnection,\n  lifecycle?: DeliveryLifecycle,\n): void {\n  const cause = wsClosedCause(ws);\n  const socketReason =\n    cause === \"server\" ? AIMOCK_DISCONNECTED : cause === \"client\" ? CLIENT_ABORTED : undefined;\n  markInterrupted(entry, lifecycle?.reason() ?? socketReason);\n}\n\n/**\n * Mark a journal entry interrupted. The reason is set only when the entry has\n * none, so a later `undefined` never erases an earlier reason. The status is\n * never changed: the entry keeps the status it was journaled with.\n */\nexport function markInterrupted(entry: JournalEntry, reason: string | undefined): void {\n  entry.response.interrupted = true;\n  if (entry.response.interruptReason === undefined && reason !== undefined) {\n    entry.response.interruptReason = reason;\n  }\n}\n"],"mappings":"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"}

package/dist/response/proxy.cjs

@@ -0,0 +1,71 @@
+const require_lifecycle = require('./lifecycle.cjs');
+
+//#region src/response/proxy.ts
+/**
+* Responses torn down before they finished, judged at entry, on `close`, and
+* when the relay returns. Reading `res.writableFinished` only when journaling
+* is too late: on Node 20 and 22 a relay that calls `end()` on a destroyed
+* response makes it read `true` (Node 24+ keeps it `false`).
+*/
+const tornDownBeforeFinish = /* @__PURE__ */ new WeakSet();
+/**
+* Run a proxy relay while watching for a client hang-up.
+*
+* WHO killed a mid-flight stream decides what the journal says, and after the
+* fact the two look identical: `req.aborted`, `req.destroyed` and
+* `res.destroyed` all read the same whether the peer hung up or the recorder
+* tore the response down. So the hang-up is decided when the request socket
+* actually closes before the response ended, by the same rule the delivery
+* lifecycle uses ({@link teardownCause}): the client's socket closed or reset.
+* A FIN alone is not a hang-up. A response already gone when this is entered
+* is judged by that rule too, so a response aimock destroyed is not blamed on
+* the client. The listener is attached before `run` and removed after it: a
+* keep-alive socket outlives this request.
+*/
+async function withHangUpDetection(req, res, run) {
+	const socket = req.socket;
+	require_lifecycle.noteDeliveryStart(res);
+	const clientCaused = () => !res.writableEnded && require_lifecycle.teardownCause(res, socket) === "client";
+	let clientHungUp = (res.destroyed || socket?.destroyed === true) && clientCaused();
+	const noteSocketClose = () => {
+		if (clientCaused()) clientHungUp = true;
+	};
+	const noteTearDown = () => {
+		if (res.destroyed && !res.writableFinished) tornDownBeforeFinish.add(res);
+	};
+	noteTearDown();
+	socket?.on("close", noteSocketClose);
+	res.on("close", noteTearDown);
+	try {
+		return {
+			outcome: await run(),
+			clientHungUp
+		};
+	} finally {
+		noteTearDown();
+		socket?.off("close", noteSocketClose);
+		res.off("close", noteTearDown);
+	}
+}
+/**
+* The journal fields for a proxied response. A stream torn down before it
+* finished (destroyed, even when the relay called `end()` on it afterwards)
+* is marked interrupted and names the side that killed it: a client hang-up
+* is normal caller behaviour, an upstream/recorder tear-down is a fault worth
+* chasing. When no byte of the response reached the socket
+* ({@link statusLineSent}) the status is 0: the client never got a status
+* line. A response that finished, or was never torn down, gets no fields.
+*/
+function proxyInterruption(res, clientHungUp) {
+	if (!(res.destroyed && (tornDownBeforeFinish.has(res) || !res.writableFinished))) return {};
+	return {
+		...require_lifecycle.statusLineSent(res) ? {} : { status: 0 },
+		interrupted: true,
+		interruptReason: clientHungUp ? require_lifecycle.CLIENT_ABORTED : "proxy stream destroyed"
+	};
+}
+
+//#endregion
+exports.proxyInterruption = proxyInterruption;
+exports.withHangUpDetection = withHangUpDetection;
+//# sourceMappingURL=proxy.cjs.map

package/dist/response/proxy.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.cjs","names":["teardownCause","statusLineSent","CLIENT_ABORTED"],"sources":["../../src/response/proxy.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport { CLIENT_ABORTED, noteDeliveryStart, statusLineSent, teardownCause } from \"./lifecycle.js\";\n\n/**\n * Responses torn down before they finished, judged at entry, on `close`, and\n * when the relay returns. Reading `res.writableFinished` only when journaling\n * is too late: on Node 20 and 22 a relay that calls `end()` on a destroyed\n * response makes it read `true` (Node 24+ keeps it `false`).\n */\nconst tornDownBeforeFinish = new WeakSet<http.ServerResponse>();\n\n/**\n * Run a proxy relay while watching for a client hang-up.\n *\n * WHO killed a mid-flight stream decides what the journal says, and after the\n * fact the two look identical: `req.aborted`, `req.destroyed` and\n * `res.destroyed` all read the same whether the peer hung up or the recorder\n * tore the response down. So the hang-up is decided when the request socket\n * actually closes before the response ended, by the same rule the delivery\n * lifecycle uses ({@link teardownCause}): the client's socket closed or reset.\n * A FIN alone is not a hang-up. A response already gone when this is entered\n * is judged by that rule too, so a response aimock destroyed is not blamed on\n * the client. The listener is attached before `run` and removed after it: a\n * keep-alive socket outlives this request.\n */\nexport async function withHangUpDetection<T>(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  run: () => Promise<T>,\n): Promise<{ outcome: T; clientHungUp: boolean }> {\n  const socket = req.socket;\n  noteDeliveryStart(res);\n  const clientCaused = (): boolean => !res.writableEnded && teardownCause(res, socket) === \"client\";\n  let clientHungUp = (res.destroyed || socket?.destroyed === true) && clientCaused();\n  const noteSocketClose = (): void => {\n    if (clientCaused()) clientHungUp = true;\n  };\n  const noteTearDown = (): void => {\n    if (res.destroyed && !res.writableFinished) tornDownBeforeFinish.add(res);\n  };\n  noteTearDown();\n  socket?.on(\"close\", noteSocketClose);\n  res.on(\"close\", noteTearDown);\n  try {\n    const outcome = await run();\n    return { outcome, clientHungUp };\n  } finally {\n    // The relay may have destroyed the response in its last tick, before\n    // `close` is emitted.\n    noteTearDown();\n    socket?.off(\"close\", noteSocketClose);\n    res.off(\"close\", noteTearDown);\n  }\n}\n\n/**\n * The journal fields for a proxied response. A stream torn down before it\n * finished (destroyed, even when the relay called `end()` on it afterwards)\n * is marked interrupted and names the side that killed it: a client hang-up\n * is normal caller behaviour, an upstream/recorder tear-down is a fault worth\n * chasing. When no byte of the response reached the socket\n * ({@link statusLineSent}) the status is 0: the client never got a status\n * line. A response that finished, or was never torn down, gets no fields.\n */\nexport function proxyInterruption(\n  res: http.ServerResponse,\n  clientHungUp: boolean,\n): { status?: 0; interrupted?: true; interruptReason?: string } {\n  const tornDown = res.destroyed && (tornDownBeforeFinish.has(res) || !res.writableFinished);\n  if (!tornDown) return {};\n  return {\n    ...(statusLineSent(res) ? {} : { status: 0 as const }),\n    interrupted: true,\n    interruptReason: clientHungUp ? CLIENT_ABORTED : \"proxy stream destroyed\",\n  };\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,uCAAuB,IAAI,SAA8B;;;;;;;;;;;;;;;AAgB/D,eAAsB,oBACpB,KACA,KACA,KACgD;CAChD,MAAM,SAAS,IAAI;AACnB,qCAAkB,IAAI;CACtB,MAAM,qBAA8B,CAAC,IAAI,iBAAiBA,gCAAc,KAAK,OAAO,KAAK;CACzF,IAAI,gBAAgB,IAAI,aAAa,QAAQ,cAAc,SAAS,cAAc;CAClF,MAAM,wBAA8B;AAClC,MAAI,cAAc,CAAE,gBAAe;;CAErC,MAAM,qBAA2B;AAC/B,MAAI,IAAI,aAAa,CAAC,IAAI,iBAAkB,sBAAqB,IAAI,IAAI;;AAE3E,eAAc;AACd,SAAQ,GAAG,SAAS,gBAAgB;AACpC,KAAI,GAAG,SAAS,aAAa;AAC7B,KAAI;AAEF,SAAO;GAAE,SADO,MAAM,KAAK;GACT;GAAc;WACxB;AAGR,gBAAc;AACd,UAAQ,IAAI,SAAS,gBAAgB;AACrC,MAAI,IAAI,SAAS,aAAa;;;;;;;;;;;;AAalC,SAAgB,kBACd,KACA,cAC8D;AAE9D,KAAI,EADa,IAAI,cAAc,qBAAqB,IAAI,IAAI,IAAI,CAAC,IAAI,mBAC1D,QAAO,EAAE;AACxB,QAAO;EACL,GAAIC,iCAAe,IAAI,GAAG,EAAE,GAAG,EAAE,QAAQ,GAAY;EACrD,aAAa;EACb,iBAAiB,eAAeC,mCAAiB;EAClD"}

package/dist/response/proxy.js

@@ -0,0 +1,70 @@
+import { CLIENT_ABORTED, noteDeliveryStart, statusLineSent, teardownCause } from "./lifecycle.js";
+
+//#region src/response/proxy.ts
+/**
+* Responses torn down before they finished, judged at entry, on `close`, and
+* when the relay returns. Reading `res.writableFinished` only when journaling
+* is too late: on Node 20 and 22 a relay that calls `end()` on a destroyed
+* response makes it read `true` (Node 24+ keeps it `false`).
+*/
+const tornDownBeforeFinish = /* @__PURE__ */ new WeakSet();
+/**
+* Run a proxy relay while watching for a client hang-up.
+*
+* WHO killed a mid-flight stream decides what the journal says, and after the
+* fact the two look identical: `req.aborted`, `req.destroyed` and
+* `res.destroyed` all read the same whether the peer hung up or the recorder
+* tore the response down. So the hang-up is decided when the request socket
+* actually closes before the response ended, by the same rule the delivery
+* lifecycle uses ({@link teardownCause}): the client's socket closed or reset.
+* A FIN alone is not a hang-up. A response already gone when this is entered
+* is judged by that rule too, so a response aimock destroyed is not blamed on
+* the client. The listener is attached before `run` and removed after it: a
+* keep-alive socket outlives this request.
+*/
+async function withHangUpDetection(req, res, run) {
+	const socket = req.socket;
+	noteDeliveryStart(res);
+	const clientCaused = () => !res.writableEnded && teardownCause(res, socket) === "client";
+	let clientHungUp = (res.destroyed || socket?.destroyed === true) && clientCaused();
+	const noteSocketClose = () => {
+		if (clientCaused()) clientHungUp = true;
+	};
+	const noteTearDown = () => {
+		if (res.destroyed && !res.writableFinished) tornDownBeforeFinish.add(res);
+	};
+	noteTearDown();
+	socket?.on("close", noteSocketClose);
+	res.on("close", noteTearDown);
+	try {
+		return {
+			outcome: await run(),
+			clientHungUp
+		};
+	} finally {
+		noteTearDown();
+		socket?.off("close", noteSocketClose);
+		res.off("close", noteTearDown);
+	}
+}
+/**
+* The journal fields for a proxied response. A stream torn down before it
+* finished (destroyed, even when the relay called `end()` on it afterwards)
+* is marked interrupted and names the side that killed it: a client hang-up
+* is normal caller behaviour, an upstream/recorder tear-down is a fault worth
+* chasing. When no byte of the response reached the socket
+* ({@link statusLineSent}) the status is 0: the client never got a status
+* line. A response that finished, or was never torn down, gets no fields.
+*/
+function proxyInterruption(res, clientHungUp) {
+	if (!(res.destroyed && (tornDownBeforeFinish.has(res) || !res.writableFinished))) return {};
+	return {
+		...statusLineSent(res) ? {} : { status: 0 },
+		interrupted: true,
+		interruptReason: clientHungUp ? CLIENT_ABORTED : "proxy stream destroyed"
+	};
+}
+
+//#endregion
+export { proxyInterruption, withHangUpDetection };
+//# sourceMappingURL=proxy.js.map

package/dist/response/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","names":[],"sources":["../../src/response/proxy.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport { CLIENT_ABORTED, noteDeliveryStart, statusLineSent, teardownCause } from \"./lifecycle.js\";\n\n/**\n * Responses torn down before they finished, judged at entry, on `close`, and\n * when the relay returns. Reading `res.writableFinished` only when journaling\n * is too late: on Node 20 and 22 a relay that calls `end()` on a destroyed\n * response makes it read `true` (Node 24+ keeps it `false`).\n */\nconst tornDownBeforeFinish = new WeakSet<http.ServerResponse>();\n\n/**\n * Run a proxy relay while watching for a client hang-up.\n *\n * WHO killed a mid-flight stream decides what the journal says, and after the\n * fact the two look identical: `req.aborted`, `req.destroyed` and\n * `res.destroyed` all read the same whether the peer hung up or the recorder\n * tore the response down. So the hang-up is decided when the request socket\n * actually closes before the response ended, by the same rule the delivery\n * lifecycle uses ({@link teardownCause}): the client's socket closed or reset.\n * A FIN alone is not a hang-up. A response already gone when this is entered\n * is judged by that rule too, so a response aimock destroyed is not blamed on\n * the client. The listener is attached before `run` and removed after it: a\n * keep-alive socket outlives this request.\n */\nexport async function withHangUpDetection<T>(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  run: () => Promise<T>,\n): Promise<{ outcome: T; clientHungUp: boolean }> {\n  const socket = req.socket;\n  noteDeliveryStart(res);\n  const clientCaused = (): boolean => !res.writableEnded && teardownCause(res, socket) === \"client\";\n  let clientHungUp = (res.destroyed || socket?.destroyed === true) && clientCaused();\n  const noteSocketClose = (): void => {\n    if (clientCaused()) clientHungUp = true;\n  };\n  const noteTearDown = (): void => {\n    if (res.destroyed && !res.writableFinished) tornDownBeforeFinish.add(res);\n  };\n  noteTearDown();\n  socket?.on(\"close\", noteSocketClose);\n  res.on(\"close\", noteTearDown);\n  try {\n    const outcome = await run();\n    return { outcome, clientHungUp };\n  } finally {\n    // The relay may have destroyed the response in its last tick, before\n    // `close` is emitted.\n    noteTearDown();\n    socket?.off(\"close\", noteSocketClose);\n    res.off(\"close\", noteTearDown);\n  }\n}\n\n/**\n * The journal fields for a proxied response. A stream torn down before it\n * finished (destroyed, even when the relay called `end()` on it afterwards)\n * is marked interrupted and names the side that killed it: a client hang-up\n * is normal caller behaviour, an upstream/recorder tear-down is a fault worth\n * chasing. When no byte of the response reached the socket\n * ({@link statusLineSent}) the status is 0: the client never got a status\n * line. A response that finished, or was never torn down, gets no fields.\n */\nexport function proxyInterruption(\n  res: http.ServerResponse,\n  clientHungUp: boolean,\n): { status?: 0; interrupted?: true; interruptReason?: string } {\n  const tornDown = res.destroyed && (tornDownBeforeFinish.has(res) || !res.writableFinished);\n  if (!tornDown) return {};\n  return {\n    ...(statusLineSent(res) ? {} : { status: 0 as const }),\n    interrupted: true,\n    interruptReason: clientHungUp ? CLIENT_ABORTED : \"proxy stream destroyed\",\n  };\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,uCAAuB,IAAI,SAA8B;;;;;;;;;;;;;;;AAgB/D,eAAsB,oBACpB,KACA,KACA,KACgD;CAChD,MAAM,SAAS,IAAI;AACnB,mBAAkB,IAAI;CACtB,MAAM,qBAA8B,CAAC,IAAI,iBAAiB,cAAc,KAAK,OAAO,KAAK;CACzF,IAAI,gBAAgB,IAAI,aAAa,QAAQ,cAAc,SAAS,cAAc;CAClF,MAAM,wBAA8B;AAClC,MAAI,cAAc,CAAE,gBAAe;;CAErC,MAAM,qBAA2B;AAC/B,MAAI,IAAI,aAAa,CAAC,IAAI,iBAAkB,sBAAqB,IAAI,IAAI;;AAE3E,eAAc;AACd,SAAQ,GAAG,SAAS,gBAAgB;AACpC,KAAI,GAAG,SAAS,aAAa;AAC7B,KAAI;AAEF,SAAO;GAAE,SADO,MAAM,KAAK;GACT;GAAc;WACxB;AAGR,gBAAc;AACd,UAAQ,IAAI,SAAS,gBAAgB;AACrC,MAAI,IAAI,SAAS,aAAa;;;;;;;;;;;;AAalC,SAAgB,kBACd,KACA,cAC8D;AAE9D,KAAI,EADa,IAAI,cAAc,qBAAqB,IAAI,IAAI,IAAI,CAAC,IAAI,mBAC1D,QAAO,EAAE;AACxB,QAAO;EACL,GAAI,eAAe,IAAI,GAAG,EAAE,GAAG,EAAE,QAAQ,GAAY;EACrD,aAAa;EACb,iBAAiB,eAAe,iBAAiB;EAClD"}