@copilotkit/aimock 1.46.0 → 1.47.0

package/dist/response/deliver.js

@@ -0,0 +1,143 @@
+import { httpSink, runFrameLoop } from "./frame-loop.js";
+import { delay } from "../sse-writer.js";
+import { responseGoneReason } from "../chaos.js";
+import { AIMOCK_DISCONNECTED, closedByClient, httpLifecycle, markInterrupted, noteDeliveryStart, requestSocket, statusLineSent, teardownReason } from "./lifecycle.js";
+import { extendRecordedTimings, nonStreamingDelayMs, nonStreamingRecordedTimings, nonStreamingTimingEnabled } from "./timing.js";
+
+//#region src/response/deliver.ts
+/**
+* Journal a delivery that ended early. The reason is always set: the
+* lifecycle's first cause when it fired, else {@link teardownReason} for the
+* response that is gone. When no byte of the response reached the socket
+* ({@link statusLineSent}), the status is 0, the rule the server and the
+* chaos `disconnect` apply to a torn socket. A fixture interruption
+* (`disconnectAfterMs`, `truncateAfterChunks`) keeps the status it was
+* journaled with, as base recorded it.
+*/
+function journalTeardown(entry, res, lifecycle) {
+	markInterrupted(entry, lifecycle?.reason() ?? teardownReason(res));
+	if (lifecycle?.cause() !== "fixture" && !statusLineSent(res)) entry.response.status = 0;
+}
+/**
+* Whether the response was torn down: the lifecycle fired, the response is
+* destroyed or chaos disconnected it, or the client closed the socket.
+*/
+function tornDown(res, lifecycle) {
+	const socket = requestSocket(res);
+	const gone = responseGoneReason(res);
+	return lifecycle?.reason() !== void 0 || gone === "client-gone" || gone === "chaos-disconnected" || !res.writableEnded && !!socket && closedByClient(socket);
+}
+/**
+* Journal a response that something else on aimock's side already answered
+* (head committed or body ended) as aimock's teardown, with the status the
+* client actually got.
+*/
+function journalAnsweredElsewhere(entry, res) {
+	markInterrupted(entry, AIMOCK_DISCONNECTED);
+	entry.response.status = statusLineSent(res) ? res.statusCode : 0;
+}
+/**
+* Whether `deliverJson` can no longer write its reply, journaling why when it
+* cannot. Torn down ({@link tornDown}): {@link journalTeardown}. Already
+* answered by something else on aimock's side (head committed or body
+* ended): writing again would throw `ERR_HTTP_HEADERS_SENT`, so it is
+* journaled by {@link journalAnsweredElsewhere}, and a body that never ended
+* is destroyed so the client does not hang.
+*/
+function journalUnwritable(entry, res, lifecycle) {
+	if (tornDown(res, lifecycle)) {
+		journalTeardown(entry, res, lifecycle);
+		return true;
+	}
+	if (res.headersSent || res.writableEnded) {
+		journalAnsweredElsewhere(entry, res);
+		if (!res.writableEnded) res.destroy();
+		return true;
+	}
+	return false;
+}
+/**
+* Deliver one streamed reply and journal how it ended. Builds the HTTP
+* lifecycle (client close + fixture interruption) and runs the frame loop on
+* it. When the loop stops early it destroys `res` (if it has not ended) and
+* marks the entry with the first cause's reason (or, when no cause fired, who
+* tore the response down). A response other code already answered (head
+* committed before the stream, or body ended) is journaled as
+* {@link deliverJson} journals it. It disposes the lifecycle on every path.
+*/
+async function deliverStream(res, entry, fixture, codec, frames, timing, opts) {
+	noteDeliveryStart(res);
+	const headSentBefore = res.headersSent;
+	const lifecycle = httpLifecycle(res, fixture, { streaming: true });
+	try {
+		if (!await runFrameLoop(httpSink(res), frames, codec, timing, {
+			lifecycle,
+			onChunkSent: lifecycle.tick,
+			status: opts?.status,
+			headers: opts?.headers
+		})) {
+			const answeredElsewhere = (headSentBefore || res.writableEnded) && !tornDown(res, lifecycle);
+			if (!res.writableEnded) res.destroy();
+			if (answeredElsewhere) journalAnsweredElsewhere(entry, res);
+			else journalTeardown(entry, res, lifecycle);
+		}
+	} finally {
+		lifecycle.dispose();
+	}
+}
+/**
+* Deliver one non-streaming JSON reply. The body is a thunk.
+*
+* On both paths it first checks {@link journalUnwritable}, before any wait. A
+* response that can no longer take the reply (torn down, or already answered)
+* is not written, the thunk is never called, and the entry is marked
+* interrupted. An already-answered response whose body never ended is
+* destroyed, so the client does not hang.
+*
+* With non-streaming timing off (the default) it then runs
+* `JSON.stringify(body())`, then `writeHead`, then `end`: the body is built
+* before anything is written, so a builder that throws leaves the response
+* unwritten.
+*
+* With timing on, it waits the non-streaming delay on the client's close
+* signal, checks {@link journalUnwritable} again (the response can be torn
+* down or answered during the wait), then runs the thunk, so a `created`
+* timestamp reflects the write time.
+*
+* Rejects with a `RangeError` when `chunkSize` is a number below 1: that is
+* a programming error, and the delay math divides by it. No user input reaches
+* it, because every caller clamps with `Math.max(1, ...)`. A user value that
+* is not a number clamps to `NaN`: the reply is still served, with a zero
+* wait when timing is on.
+*/
+async function deliverJson(res, entry, fixture, body, opts) {
+	if (opts.chunkSize < 1) throw new RangeError(`deliverJson: chunkSize must be >= 1, got ${opts.chunkSize}`);
+	const write = () => {
+		const text = JSON.stringify(body());
+		res.writeHead(opts.status ?? 200, {
+			"Content-Type": "application/json",
+			...opts.headers
+		});
+		res.end(text);
+	};
+	noteDeliveryStart(res);
+	if (journalUnwritable(entry, res, void 0)) return;
+	if (!nonStreamingTimingEnabled(fixture, opts.surface)) {
+		write();
+		return;
+	}
+	const lifecycle = httpLifecycle(res, fixture, { streaming: false });
+	try {
+		const fixtureTimings = nonStreamingRecordedTimings(fixture, opts.surface, opts.recordedTimings);
+		const recordedTimings = opts.duplicateId ? extendRecordedTimings(fixtureTimings, Math.max(1, Math.ceil(opts.payloadLength / opts.chunkSize)), true) : fixtureTimings;
+		await delay(nonStreamingDelayMs(fixture, opts.payloadLength, opts.chunkSize, recordedTimings, opts.replaySpeed), lifecycle.signal);
+		if (journalUnwritable(entry, res, lifecycle)) return;
+		write();
+	} finally {
+		lifecycle.dispose();
+	}
+}
+
+//#endregion
+export { deliverJson, deliverStream };
+//# sourceMappingURL=deliver.js.map

package/dist/response/deliver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.js","names":[],"sources":["../../src/response/deliver.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport type { Fixture, JournalEntry, RecordedTimings } from \"../types.js\";\nimport { delay } from \"../sse-writer.js\";\nimport { httpSink, runFrameLoop, type FrameCodec, type FrameTiming } from \"./frame-loop.js\";\nimport { responseGoneReason } from \"../chaos.js\";\nimport {\n  AIMOCK_DISCONNECTED,\n  closedByClient,\n  httpLifecycle,\n  markInterrupted,\n  noteDeliveryStart,\n  statusLineSent,\n  teardownReason,\n  requestSocket,\n  type DeliveryLifecycle,\n} from \"./lifecycle.js\";\nimport {\n  extendRecordedTimings,\n  nonStreamingDelayMs,\n  nonStreamingRecordedTimings,\n  nonStreamingTimingEnabled,\n  type NonStreamingSurface,\n} from \"./timing.js\";\n\n/** The lifecycle fields the teardown journal reads. */\ntype TeardownSource = Pick<DeliveryLifecycle, \"cause\" | \"reason\">;\n\n/**\n * Journal a delivery that ended early. The reason is always set: the\n * lifecycle's first cause when it fired, else {@link teardownReason} for the\n * response that is gone. When no byte of the response reached the socket\n * ({@link statusLineSent}), the status is 0, the rule the server and the\n * chaos `disconnect` apply to a torn socket. A fixture interruption\n * (`disconnectAfterMs`, `truncateAfterChunks`) keeps the status it was\n * journaled with, as base recorded it.\n */\nfunction journalTeardown(\n  entry: JournalEntry,\n  res: http.ServerResponse,\n  lifecycle: TeardownSource | undefined,\n): void {\n  markInterrupted(entry, lifecycle?.reason() ?? teardownReason(res));\n  if (lifecycle?.cause() !== \"fixture\" && !statusLineSent(res)) entry.response.status = 0;\n}\n\n/**\n * Whether the response was torn down: the lifecycle fired, the response is\n * destroyed or chaos disconnected it, or the client closed the socket.\n */\nfunction tornDown(res: http.ServerResponse, lifecycle: TeardownSource | undefined): boolean {\n  const socket = requestSocket(res);\n  const gone = responseGoneReason(res);\n  return (\n    lifecycle?.reason() !== undefined ||\n    gone === \"client-gone\" ||\n    gone === \"chaos-disconnected\" ||\n    (!res.writableEnded && !!socket && closedByClient(socket))\n  );\n}\n\n/**\n * Journal a response that something else on aimock's side already answered\n * (head committed or body ended) as aimock's teardown, with the status the\n * client actually got.\n */\nfunction journalAnsweredElsewhere(entry: JournalEntry, res: http.ServerResponse): void {\n  markInterrupted(entry, AIMOCK_DISCONNECTED);\n  entry.response.status = statusLineSent(res) ? res.statusCode : 0;\n}\n\n/**\n * Whether `deliverJson` can no longer write its reply, journaling why when it\n * cannot. Torn down ({@link tornDown}): {@link journalTeardown}. Already\n * answered by something else on aimock's side (head committed or body\n * ended): writing again would throw `ERR_HTTP_HEADERS_SENT`, so it is\n * journaled by {@link journalAnsweredElsewhere}, and a body that never ended\n * is destroyed so the client does not hang.\n */\nfunction journalUnwritable(\n  entry: JournalEntry,\n  res: http.ServerResponse,\n  lifecycle: TeardownSource | undefined,\n): boolean {\n  if (tornDown(res, lifecycle)) {\n    journalTeardown(entry, res, lifecycle);\n    return true;\n  }\n  if (res.headersSent || res.writableEnded) {\n    journalAnsweredElsewhere(entry, res);\n    if (!res.writableEnded) res.destroy();\n    return true;\n  }\n  return false;\n}\n\n/**\n * Deliver one streamed reply and journal how it ended. Builds the HTTP\n * lifecycle (client close + fixture interruption) and runs the frame loop on\n * it. When the loop stops early it destroys `res` (if it has not ended) and\n * marks the entry with the first cause's reason (or, when no cause fired, who\n * tore the response down). A response other code already answered (head\n * committed before the stream, or body ended) is journaled as\n * {@link deliverJson} journals it. It disposes the lifecycle on every path.\n */\nexport async function deliverStream<F>(\n  res: http.ServerResponse,\n  entry: JournalEntry,\n  fixture: Fixture,\n  codec: FrameCodec<F>,\n  frames: readonly F[],\n  timing: FrameTiming,\n  opts?: {\n    status?: number; // When set, sent with `writeHead` before the first frame (issue #549).\n    headers?: Record<string, string>; // Merged over the codec's headers (issue #549).\n  },\n): Promise<void> {\n  noteDeliveryStart(res);\n  const headSentBefore = res.headersSent;\n  const lifecycle = httpLifecycle(res, fixture, { streaming: true });\n  try {\n    const completed = await runFrameLoop(httpSink(res), frames, codec, timing, {\n      lifecycle,\n      onChunkSent: lifecycle.tick,\n      status: opts?.status,\n      headers: opts?.headers,\n    });\n    if (!completed) {\n      // Read before the destroy below, which makes any response look torn down.\n      const answeredElsewhere = (headSentBefore || res.writableEnded) && !tornDown(res, lifecycle);\n      if (!res.writableEnded) res.destroy();\n      if (answeredElsewhere) journalAnsweredElsewhere(entry, res);\n      else journalTeardown(entry, res, lifecycle);\n    }\n  } finally {\n    lifecycle.dispose();\n  }\n}\n\nexport interface DeliverJsonOptions {\n  /**\n   * Passed to `nonStreamingTimingEnabled` and `nonStreamingRecordedTimings`:\n   * OpenAI chat, or any other provider.\n   */\n  surface: NonStreamingSurface;\n  status?: number; // The response status, 200 when unset (issue #549).\n  headers?: Record<string, string>; // Merged over the JSON `Content-Type` header (issue #549).\n  /** The served payload length the wait is sized from. */\n  payloadLength: number;\n  /**\n   * The wait is sized in chunks of this many characters. Callers pass\n   * `Math.max(1, <fixture or server chunkSize>)`: 1 or more, or `NaN` for a\n   * non-numeric value. `NaN` gives a zero wait.\n   */\n  chunkSize: number;\n  recordedTimings?: RecordedTimings;\n  /** A K4 duplicate-id plan: extend the recorded gaps before sizing the wait. */\n  duplicateId?: boolean;\n  replaySpeed?: number;\n}\n\n/**\n * Deliver one non-streaming JSON reply. The body is a thunk.\n *\n * On both paths it first checks {@link journalUnwritable}, before any wait. A\n * response that can no longer take the reply (torn down, or already answered)\n * is not written, the thunk is never called, and the entry is marked\n * interrupted. An already-answered response whose body never ended is\n * destroyed, so the client does not hang.\n *\n * With non-streaming timing off (the default) it then runs\n * `JSON.stringify(body())`, then `writeHead`, then `end`: the body is built\n * before anything is written, so a builder that throws leaves the response\n * unwritten.\n *\n * With timing on, it waits the non-streaming delay on the client's close\n * signal, checks {@link journalUnwritable} again (the response can be torn\n * down or answered during the wait), then runs the thunk, so a `created`\n * timestamp reflects the write time.\n *\n * Rejects with a `RangeError` when `chunkSize` is a number below 1: that is\n * a programming error, and the delay math divides by it. No user input reaches\n * it, because every caller clamps with `Math.max(1, ...)`. A user value that\n * is not a number clamps to `NaN`: the reply is still served, with a zero\n * wait when timing is on.\n */\nexport async function deliverJson(\n  res: http.ServerResponse,\n  entry: JournalEntry,\n  fixture: Fixture,\n  body: () => unknown,\n  opts: DeliverJsonOptions,\n): Promise<void> {\n  if (opts.chunkSize < 1) {\n    throw new RangeError(`deliverJson: chunkSize must be >= 1, got ${opts.chunkSize}`);\n  }\n  const write = (): void => {\n    const text = JSON.stringify(body());\n    res.writeHead(opts.status ?? 200, { \"Content-Type\": \"application/json\", ...opts.headers });\n    res.end(text);\n  };\n  noteDeliveryStart(res);\n  // Checked before the lifecycle and the wait on both paths: a response that\n  // cannot take the reply is journaled at once, with no wait.\n  if (journalUnwritable(entry, res, undefined)) return;\n  if (!nonStreamingTimingEnabled(fixture, opts.surface)) {\n    write();\n    return;\n  }\n  const lifecycle = httpLifecycle(res, fixture, { streaming: false });\n  try {\n    const fixtureTimings = nonStreamingRecordedTimings(fixture, opts.surface, opts.recordedTimings);\n    const recordedTimings = opts.duplicateId\n      ? extendRecordedTimings(\n          fixtureTimings,\n          Math.max(1, Math.ceil(opts.payloadLength / opts.chunkSize)),\n          true,\n        )\n      : fixtureTimings;\n    await delay(\n      nonStreamingDelayMs(\n        fixture,\n        opts.payloadLength,\n        opts.chunkSize,\n        recordedTimings,\n        opts.replaySpeed,\n      ),\n      lifecycle.signal,\n    );\n    if (journalUnwritable(entry, res, lifecycle)) return;\n    write();\n  } finally {\n    lifecycle.dispose();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoCA,SAAS,gBACP,OACA,KACA,WACM;AACN,iBAAgB,OAAO,WAAW,QAAQ,IAAI,eAAe,IAAI,CAAC;AAClE,KAAI,WAAW,OAAO,KAAK,aAAa,CAAC,eAAe,IAAI,CAAE,OAAM,SAAS,SAAS;;;;;;AAOxF,SAAS,SAAS,KAA0B,WAAgD;CAC1F,MAAM,SAAS,cAAc,IAAI;CACjC,MAAM,OAAO,mBAAmB,IAAI;AACpC,QACE,WAAW,QAAQ,KAAK,UACxB,SAAS,iBACT,SAAS,wBACR,CAAC,IAAI,iBAAiB,CAAC,CAAC,UAAU,eAAe,OAAO;;;;;;;AAS7D,SAAS,yBAAyB,OAAqB,KAAgC;AACrF,iBAAgB,OAAO,oBAAoB;AAC3C,OAAM,SAAS,SAAS,eAAe,IAAI,GAAG,IAAI,aAAa;;;;;;;;;;AAWjE,SAAS,kBACP,OACA,KACA,WACS;AACT,KAAI,SAAS,KAAK,UAAU,EAAE;AAC5B,kBAAgB,OAAO,KAAK,UAAU;AACtC,SAAO;;AAET,KAAI,IAAI,eAAe,IAAI,eAAe;AACxC,2BAAyB,OAAO,IAAI;AACpC,MAAI,CAAC,IAAI,cAAe,KAAI,SAAS;AACrC,SAAO;;AAET,QAAO;;;;;;;;;;;AAYT,eAAsB,cACpB,KACA,OACA,SACA,OACA,QACA,QACA,MAIe;AACf,mBAAkB,IAAI;CACtB,MAAM,iBAAiB,IAAI;CAC3B,MAAM,YAAY,cAAc,KAAK,SAAS,EAAE,WAAW,MAAM,CAAC;AAClE,KAAI;AAOF,MAAI,CANc,MAAM,aAAa,SAAS,IAAI,EAAE,QAAQ,OAAO,QAAQ;GACzE;GACA,aAAa,UAAU;GACvB,QAAQ,MAAM;GACd,SAAS,MAAM;GAChB,CAAC,EACc;GAEd,MAAM,qBAAqB,kBAAkB,IAAI,kBAAkB,CAAC,SAAS,KAAK,UAAU;AAC5F,OAAI,CAAC,IAAI,cAAe,KAAI,SAAS;AACrC,OAAI,kBAAmB,0BAAyB,OAAO,IAAI;OACtD,iBAAgB,OAAO,KAAK,UAAU;;WAErC;AACR,YAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDvB,eAAsB,YACpB,KACA,OACA,SACA,MACA,MACe;AACf,KAAI,KAAK,YAAY,EACnB,OAAM,IAAI,WAAW,4CAA4C,KAAK,YAAY;CAEpF,MAAM,cAAoB;EACxB,MAAM,OAAO,KAAK,UAAU,MAAM,CAAC;AACnC,MAAI,UAAU,KAAK,UAAU,KAAK;GAAE,gBAAgB;GAAoB,GAAG,KAAK;GAAS,CAAC;AAC1F,MAAI,IAAI,KAAK;;AAEf,mBAAkB,IAAI;AAGtB,KAAI,kBAAkB,OAAO,KAAK,OAAU,CAAE;AAC9C,KAAI,CAAC,0BAA0B,SAAS,KAAK,QAAQ,EAAE;AACrD,SAAO;AACP;;CAEF,MAAM,YAAY,cAAc,KAAK,SAAS,EAAE,WAAW,OAAO,CAAC;AACnE,KAAI;EACF,MAAM,iBAAiB,4BAA4B,SAAS,KAAK,SAAS,KAAK,gBAAgB;EAC/F,MAAM,kBAAkB,KAAK,cACzB,sBACE,gBACA,KAAK,IAAI,GAAG,KAAK,KAAK,KAAK,gBAAgB,KAAK,UAAU,CAAC,EAC3D,KACD,GACD;AACJ,QAAM,MACJ,oBACE,SACA,KAAK,eACL,KAAK,WACL,iBACA,KAAK,YACN,EACD,UAAU,OACX;AACD,MAAI,kBAAkB,OAAO,KAAK,UAAU,CAAE;AAC9C,SAAO;WACC;AACR,YAAU,SAAS"}

package/dist/response/frame-loop.cjs

@@ -0,0 +1,102 @@
+const require_sse_writer = require('../sse-writer.cjs');
+
+//#region src/response/frame-loop.ts
+/** An HTTP response as a frame sink. Gone means destroyed. */
+function httpSink(res) {
+	return {
+		gone: () => res.destroyed,
+		writableEnded: () => res.writableEnded,
+		headersSent: () => res.headersSent,
+		write: (chunk) => {
+			res.write(chunk);
+		},
+		end: () => {
+			res.end();
+		},
+		setHeader: (name, value) => {
+			res.setHeader(name, value);
+		},
+		writeHead: (status, headers) => {
+			res.writeHead(status, headers);
+		}
+	};
+}
+/** A WebSocket connection as a frame sink. Gone means closed; it never ends. */
+function wsSink(ws) {
+	return {
+		gone: () => ws.isClosed,
+		writableEnded: () => false,
+		write: (chunk) => {
+			ws.send(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+		},
+		end: () => {}
+	};
+}
+/**
+* The shared streaming loop. Per frame, in order: gone check (with
+* `checkGoneBeforeDelay`) → `calculateDelay` → `delay(d, signal)` → abort
+* check → gone check (with `checkGoneBeforeDelay`) → `writableEnded` (return
+* `true`) → write → advance the index and tick (counting frames only) → abort
+* re-check. After the last frame the trailer and `end()` run if the response
+* has not ended. Returns `false` when stopped by an abort, or by a gone sink
+* (with a lifecycle or `checkGoneBeforeDelay`), including an abort before the
+* first frame or with no frames, and `true` otherwise. Rejects with a
+* `TypeError` when given both a lifecycle and a signal, or a status for a sink
+* without `writeHead`.
+*
+* With a lifecycle, a response that other code already answered is not a
+* completed delivery: an ended response (at entry or at the `writableEnded`
+* check) returns `false`, and so does a head already committed at entry,
+* which `setHeader`/`writeHead` would reject with `ERR_HTTP_HEADERS_SENT`.
+* Without a lifecycle (the exported writers) an ended response still returns
+* `true`, as base did.
+*/
+async function runFrameLoop(sink, frames, codec, timing, opts = {}) {
+	const { lifecycle } = opts;
+	if (lifecycle !== void 0 && opts.signal !== void 0) throw new TypeError("runFrameLoop: pass a lifecycle or a signal, not both");
+	const signal = lifecycle?.signal ?? opts.signal;
+	const stopped = () => signal?.aborted === true || lifecycle !== void 0 && sink.gone();
+	const endedIsCompleted = lifecycle === void 0;
+	if (sink.writableEnded()) return endedIsCompleted;
+	if (lifecycle && sink.gone()) return false;
+	if (lifecycle && sink.headersSent?.() === true) return false;
+	const headers = opts.headers === void 0 ? codec.headers : {
+		...codec.headers,
+		...opts.headers
+	};
+	if (opts.status !== void 0 || codec.writeHeadImmediately) {
+		if (!sink.writeHead) throw new TypeError("runFrameLoop: a status was requested but the sink has no writeHead");
+		sink.writeHead(opts.status ?? 200, headers);
+	} else if (sink.setHeader) for (const [name, value] of Object.entries(headers)) sink.setHeader(name, value);
+	if (codec.prelude && !sink.writableEnded()) {
+		const prelude = codec.prelude();
+		if (prelude !== void 0) sink.write(prelude);
+	}
+	let chunkIndex = 0;
+	for (const frame of frames) {
+		if (codec.checkGoneBeforeDelay && sink.gone()) return false;
+		const chunkDelay = require_sse_writer.calculateDelay(chunkIndex, timing.streamingProfile, timing.latency ?? 0, timing.recordedTimings, timing.replaySpeed);
+		if (chunkDelay > 0) await require_sse_writer.delay(chunkDelay, signal);
+		if (stopped()) return false;
+		if (codec.checkGoneBeforeDelay && sink.gone()) return false;
+		if (sink.writableEnded()) return endedIsCompleted;
+		sink.write(codec.encode(frame));
+		if (codec.counts?.(frame) !== false) {
+			chunkIndex++;
+			opts.onChunkSent?.();
+		}
+		if (stopped()) return false;
+	}
+	if (stopped()) return false;
+	if (!sink.writableEnded()) {
+		for (const part of codec.trailer?.(false) ?? []) sink.write(part);
+		sink.end();
+	}
+	return true;
+}
+
+//#endregion
+exports.httpSink = httpSink;
+exports.runFrameLoop = runFrameLoop;
+exports.wsSink = wsSink;
+//# sourceMappingURL=frame-loop.cjs.map

package/dist/response/frame-loop.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-loop.cjs","names":["calculateDelay","delay"],"sources":["../../src/response/frame-loop.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport type { RecordedTimings, StreamingProfile } from \"../types.js\";\nimport type { WebSocketConnection } from \"../ws-framing.js\";\nimport { calculateDelay, delay } from \"../sse-writer.js\";\nimport type { DeliveryLifecycle } from \"./lifecycle.js\";\n\n/**\n * How one wire frames a stream. The frame loop is the same for every wire;\n * only these parts differ.\n */\nexport interface FrameCodec<F> {\n  /** Response headers, set before the first write (skipped if the response already ended). */\n  headers: Record<string, string>;\n  /** Written once before the first frame, when it returns a value (the OpenRouter keepalive in `sseCodec`). */\n  prelude?: () => string | Buffer | undefined;\n  /** The bytes for one frame. */\n  encode(frame: F): string | Buffer;\n  /**\n   * Whether a frame advances the chunk index and the fixture tick (default\n   * true). A frame that does not count still pays the delay at the current\n   * index.\n   */\n  counts?(frame: F): boolean;\n  /**\n   * Written after the last frame, before `end()`, when the response has not\n   * ended. Only a completed delivery reaches it: an aborted one returns `false`\n   * with no trailer and no `end()`, so `aborted` is always `false` here.\n   */\n  trailer?(aborted: boolean): Array<string | Buffer>;\n  /** Send the head with `writeHead` up front instead of `setHeader`. */\n  writeHeadImmediately?: boolean;\n  /**\n   * Check `sink.gone()` before each delay as well as after it, with or\n   * without a lifecycle, and return `false` when gone.\n   */\n  checkGoneBeforeDelay?: boolean;\n}\n\n/**\n * Where frames go: an HTTP response or a WebSocket connection. A sink with no\n * HTTP head (WebSocket) omits `setHeader` and `writeHead`; asking such a sink\n * for a status (`status` or `writeHeadImmediately`) is a programming error.\n */\nexport interface FrameSink {\n  gone(): boolean;\n  writableEnded(): boolean;\n  write(chunk: string | Buffer): void;\n  end(): void;\n  /** Whether the head was already committed (HTTP only). */\n  headersSent?(): boolean;\n  setHeader?(name: string, value: string): void;\n  writeHead?(status: number, headers: Record<string, string>): void;\n}\n\n/** Per-frame delay inputs, passed straight to `calculateDelay`. */\nexport interface FrameTiming {\n  latency?: number;\n  streamingProfile?: StreamingProfile;\n  recordedTimings?: RecordedTimings;\n  replaySpeed?: number;\n}\n\ninterface FrameLoopCommonOptions {\n  onChunkSent?: () => void;\n  /** When given, `writeHead(status, headers)` is sent before the first frame. */\n  status?: number;\n  /** Extra headers, merged over the codec's headers. */\n  headers?: Record<string, string>;\n}\n\n/**\n * The stop source is a `lifecycle` or a bare `signal`, never both: passing both\n * is a programming error and rejects with a `TypeError`.\n */\nexport type FrameLoopOptions = FrameLoopCommonOptions &\n  (\n    | {\n        /**\n         * Its signal stops the loop and `sink.gone()` is checked next to every\n         * abort check.\n         */\n        lifecycle: DeliveryLifecycle;\n        signal?: never;\n      }\n    | {\n        lifecycle?: never;\n        /**\n         * Without a lifecycle, `signal` stops the loop, and a gone sink stops it\n         * only when the codec sets `checkGoneBeforeDelay`.\n         */\n        signal?: AbortSignal;\n      }\n  );\n\n/** An HTTP response as a frame sink. Gone means destroyed. */\nexport function httpSink(res: http.ServerResponse): FrameSink {\n  return {\n    gone: () => res.destroyed,\n    writableEnded: () => res.writableEnded,\n    headersSent: () => res.headersSent,\n    write: (chunk) => {\n      res.write(chunk);\n    },\n    end: () => {\n      res.end();\n    },\n    setHeader: (name, value) => {\n      res.setHeader(name, value);\n    },\n    writeHead: (status, headers) => {\n      res.writeHead(status, headers);\n    },\n  };\n}\n\n/** A WebSocket connection as a frame sink. Gone means closed; it never ends. */\nexport function wsSink(ws: WebSocketConnection): FrameSink {\n  return {\n    gone: () => ws.isClosed,\n    writableEnded: () => false,\n    write: (chunk) => {\n      ws.send(typeof chunk === \"string\" ? chunk : chunk.toString(\"utf8\"));\n    },\n    end: () => {},\n  };\n}\n\n/**\n * The shared streaming loop. Per frame, in order: gone check (with\n * `checkGoneBeforeDelay`) → `calculateDelay` → `delay(d, signal)` → abort\n * check → gone check (with `checkGoneBeforeDelay`) → `writableEnded` (return\n * `true`) → write → advance the index and tick (counting frames only) → abort\n * re-check. After the last frame the trailer and `end()` run if the response\n * has not ended. Returns `false` when stopped by an abort, or by a gone sink\n * (with a lifecycle or `checkGoneBeforeDelay`), including an abort before the\n * first frame or with no frames, and `true` otherwise. Rejects with a\n * `TypeError` when given both a lifecycle and a signal, or a status for a sink\n * without `writeHead`.\n *\n * With a lifecycle, a response that other code already answered is not a\n * completed delivery: an ended response (at entry or at the `writableEnded`\n * check) returns `false`, and so does a head already committed at entry,\n * which `setHeader`/`writeHead` would reject with `ERR_HTTP_HEADERS_SENT`.\n * Without a lifecycle (the exported writers) an ended response still returns\n * `true`, as base did.\n */\nexport async function runFrameLoop<F>(\n  sink: FrameSink,\n  frames: readonly F[],\n  codec: FrameCodec<F>,\n  timing: FrameTiming,\n  opts: FrameLoopOptions = {},\n): Promise<boolean> {\n  const { lifecycle } = opts;\n  if (lifecycle !== undefined && opts.signal !== undefined) {\n    throw new TypeError(\"runFrameLoop: pass a lifecycle or a signal, not both\");\n  }\n  const signal = lifecycle?.signal ?? opts.signal;\n  const stopped = (): boolean =>\n    signal?.aborted === true || (lifecycle !== undefined && sink.gone());\n\n  // With a lifecycle, a response that other code answered is not a completed delivery.\n  const endedIsCompleted = lifecycle === undefined;\n  if (sink.writableEnded()) return endedIsCompleted;\n  if (lifecycle && sink.gone()) return false;\n  if (lifecycle && sink.headersSent?.() === true) return false;\n\n  const headers =\n    opts.headers === undefined ? codec.headers : { ...codec.headers, ...opts.headers };\n  if (opts.status !== undefined || codec.writeHeadImmediately) {\n    if (!sink.writeHead) {\n      throw new TypeError(\"runFrameLoop: a status was requested but the sink has no writeHead\");\n    }\n    sink.writeHead(opts.status ?? 200, headers);\n  } else if (sink.setHeader) {\n    for (const [name, value] of Object.entries(headers)) sink.setHeader(name, value);\n  }\n\n  if (codec.prelude && !sink.writableEnded()) {\n    const prelude = codec.prelude();\n    if (prelude !== undefined) sink.write(prelude);\n  }\n\n  let chunkIndex = 0;\n  for (const frame of frames) {\n    if (codec.checkGoneBeforeDelay && sink.gone()) return false;\n    const chunkDelay = calculateDelay(\n      chunkIndex,\n      timing.streamingProfile,\n      timing.latency ?? 0,\n      timing.recordedTimings,\n      timing.replaySpeed,\n    );\n    if (chunkDelay > 0) await delay(chunkDelay, signal);\n    if (stopped()) return false;\n    if (codec.checkGoneBeforeDelay && sink.gone()) return false;\n    if (sink.writableEnded()) return endedIsCompleted;\n    sink.write(codec.encode(frame));\n    if (codec.counts?.(frame) !== false) {\n      chunkIndex++;\n      opts.onChunkSent?.();\n    }\n    if (stopped()) return false;\n  }\n\n  // An abort the loop never observed (no frames) still stops the delivery.\n  if (stopped()) return false;\n  if (!sink.writableEnded()) {\n    for (const part of codec.trailer?.(false) ?? []) sink.write(part);\n    sink.end();\n  }\n  return true;\n}\n"],"mappings":";;;;AA+FA,SAAgB,SAAS,KAAqC;AAC5D,QAAO;EACL,YAAY,IAAI;EAChB,qBAAqB,IAAI;EACzB,mBAAmB,IAAI;EACvB,QAAQ,UAAU;AAChB,OAAI,MAAM,MAAM;;EAElB,WAAW;AACT,OAAI,KAAK;;EAEX,YAAY,MAAM,UAAU;AAC1B,OAAI,UAAU,MAAM,MAAM;;EAE5B,YAAY,QAAQ,YAAY;AAC9B,OAAI,UAAU,QAAQ,QAAQ;;EAEjC;;;AAIH,SAAgB,OAAO,IAAoC;AACzD,QAAO;EACL,YAAY,GAAG;EACf,qBAAqB;EACrB,QAAQ,UAAU;AAChB,MAAG,KAAK,OAAO,UAAU,WAAW,QAAQ,MAAM,SAAS,OAAO,CAAC;;EAErE,WAAW;EACZ;;;;;;;;;;;;;;;;;;;;;AAsBH,eAAsB,aACpB,MACA,QACA,OACA,QACA,OAAyB,EAAE,EACT;CAClB,MAAM,EAAE,cAAc;AACtB,KAAI,cAAc,UAAa,KAAK,WAAW,OAC7C,OAAM,IAAI,UAAU,uDAAuD;CAE7E,MAAM,SAAS,WAAW,UAAU,KAAK;CACzC,MAAM,gBACJ,QAAQ,YAAY,QAAS,cAAc,UAAa,KAAK,MAAM;CAGrE,MAAM,mBAAmB,cAAc;AACvC,KAAI,KAAK,eAAe,CAAE,QAAO;AACjC,KAAI,aAAa,KAAK,MAAM,CAAE,QAAO;AACrC,KAAI,aAAa,KAAK,eAAe,KAAK,KAAM,QAAO;CAEvD,MAAM,UACJ,KAAK,YAAY,SAAY,MAAM,UAAU;EAAE,GAAG,MAAM;EAAS,GAAG,KAAK;EAAS;AACpF,KAAI,KAAK,WAAW,UAAa,MAAM,sBAAsB;AAC3D,MAAI,CAAC,KAAK,UACR,OAAM,IAAI,UAAU,qEAAqE;AAE3F,OAAK,UAAU,KAAK,UAAU,KAAK,QAAQ;YAClC,KAAK,UACd,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,CAAE,MAAK,UAAU,MAAM,MAAM;AAGlF,KAAI,MAAM,WAAW,CAAC,KAAK,eAAe,EAAE;EAC1C,MAAM,UAAU,MAAM,SAAS;AAC/B,MAAI,YAAY,OAAW,MAAK,MAAM,QAAQ;;CAGhD,IAAI,aAAa;AACjB,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,MAAM,wBAAwB,KAAK,MAAM,CAAE,QAAO;EACtD,MAAM,aAAaA,kCACjB,YACA,OAAO,kBACP,OAAO,WAAW,GAClB,OAAO,iBACP,OAAO,YACR;AACD,MAAI,aAAa,EAAG,OAAMC,yBAAM,YAAY,OAAO;AACnD,MAAI,SAAS,CAAE,QAAO;AACtB,MAAI,MAAM,wBAAwB,KAAK,MAAM,CAAE,QAAO;AACtD,MAAI,KAAK,eAAe,CAAE,QAAO;AACjC,OAAK,MAAM,MAAM,OAAO,MAAM,CAAC;AAC/B,MAAI,MAAM,SAAS,MAAM,KAAK,OAAO;AACnC;AACA,QAAK,eAAe;;AAEtB,MAAI,SAAS,CAAE,QAAO;;AAIxB,KAAI,SAAS,CAAE,QAAO;AACtB,KAAI,CAAC,KAAK,eAAe,EAAE;AACzB,OAAK,MAAM,QAAQ,MAAM,UAAU,MAAM,IAAI,EAAE,CAAE,MAAK,MAAM,KAAK;AACjE,OAAK,KAAK;;AAEZ,QAAO"}

package/dist/response/frame-loop.js

@@ -0,0 +1,100 @@
+import { calculateDelay, delay } from "../sse-writer.js";
+
+//#region src/response/frame-loop.ts
+/** An HTTP response as a frame sink. Gone means destroyed. */
+function httpSink(res) {
+	return {
+		gone: () => res.destroyed,
+		writableEnded: () => res.writableEnded,
+		headersSent: () => res.headersSent,
+		write: (chunk) => {
+			res.write(chunk);
+		},
+		end: () => {
+			res.end();
+		},
+		setHeader: (name, value) => {
+			res.setHeader(name, value);
+		},
+		writeHead: (status, headers) => {
+			res.writeHead(status, headers);
+		}
+	};
+}
+/** A WebSocket connection as a frame sink. Gone means closed; it never ends. */
+function wsSink(ws) {
+	return {
+		gone: () => ws.isClosed,
+		writableEnded: () => false,
+		write: (chunk) => {
+			ws.send(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+		},
+		end: () => {}
+	};
+}
+/**
+* The shared streaming loop. Per frame, in order: gone check (with
+* `checkGoneBeforeDelay`) → `calculateDelay` → `delay(d, signal)` → abort
+* check → gone check (with `checkGoneBeforeDelay`) → `writableEnded` (return
+* `true`) → write → advance the index and tick (counting frames only) → abort
+* re-check. After the last frame the trailer and `end()` run if the response
+* has not ended. Returns `false` when stopped by an abort, or by a gone sink
+* (with a lifecycle or `checkGoneBeforeDelay`), including an abort before the
+* first frame or with no frames, and `true` otherwise. Rejects with a
+* `TypeError` when given both a lifecycle and a signal, or a status for a sink
+* without `writeHead`.
+*
+* With a lifecycle, a response that other code already answered is not a
+* completed delivery: an ended response (at entry or at the `writableEnded`
+* check) returns `false`, and so does a head already committed at entry,
+* which `setHeader`/`writeHead` would reject with `ERR_HTTP_HEADERS_SENT`.
+* Without a lifecycle (the exported writers) an ended response still returns
+* `true`, as base did.
+*/
+async function runFrameLoop(sink, frames, codec, timing, opts = {}) {
+	const { lifecycle } = opts;
+	if (lifecycle !== void 0 && opts.signal !== void 0) throw new TypeError("runFrameLoop: pass a lifecycle or a signal, not both");
+	const signal = lifecycle?.signal ?? opts.signal;
+	const stopped = () => signal?.aborted === true || lifecycle !== void 0 && sink.gone();
+	const endedIsCompleted = lifecycle === void 0;
+	if (sink.writableEnded()) return endedIsCompleted;
+	if (lifecycle && sink.gone()) return false;
+	if (lifecycle && sink.headersSent?.() === true) return false;
+	const headers = opts.headers === void 0 ? codec.headers : {
+		...codec.headers,
+		...opts.headers
+	};
+	if (opts.status !== void 0 || codec.writeHeadImmediately) {
+		if (!sink.writeHead) throw new TypeError("runFrameLoop: a status was requested but the sink has no writeHead");
+		sink.writeHead(opts.status ?? 200, headers);
+	} else if (sink.setHeader) for (const [name, value] of Object.entries(headers)) sink.setHeader(name, value);
+	if (codec.prelude && !sink.writableEnded()) {
+		const prelude = codec.prelude();
+		if (prelude !== void 0) sink.write(prelude);
+	}
+	let chunkIndex = 0;
+	for (const frame of frames) {
+		if (codec.checkGoneBeforeDelay && sink.gone()) return false;
+		const chunkDelay = calculateDelay(chunkIndex, timing.streamingProfile, timing.latency ?? 0, timing.recordedTimings, timing.replaySpeed);
+		if (chunkDelay > 0) await delay(chunkDelay, signal);
+		if (stopped()) return false;
+		if (codec.checkGoneBeforeDelay && sink.gone()) return false;
+		if (sink.writableEnded()) return endedIsCompleted;
+		sink.write(codec.encode(frame));
+		if (codec.counts?.(frame) !== false) {
+			chunkIndex++;
+			opts.onChunkSent?.();
+		}
+		if (stopped()) return false;
+	}
+	if (stopped()) return false;
+	if (!sink.writableEnded()) {
+		for (const part of codec.trailer?.(false) ?? []) sink.write(part);
+		sink.end();
+	}
+	return true;
+}
+
+//#endregion
+export { httpSink, runFrameLoop, wsSink };
+//# sourceMappingURL=frame-loop.js.map

package/dist/response/frame-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-loop.js","names":[],"sources":["../../src/response/frame-loop.ts"],"sourcesContent":["import type * as http from \"node:http\";\nimport type { RecordedTimings, StreamingProfile } from \"../types.js\";\nimport type { WebSocketConnection } from \"../ws-framing.js\";\nimport { calculateDelay, delay } from \"../sse-writer.js\";\nimport type { DeliveryLifecycle } from \"./lifecycle.js\";\n\n/**\n * How one wire frames a stream. The frame loop is the same for every wire;\n * only these parts differ.\n */\nexport interface FrameCodec<F> {\n  /** Response headers, set before the first write (skipped if the response already ended). */\n  headers: Record<string, string>;\n  /** Written once before the first frame, when it returns a value (the OpenRouter keepalive in `sseCodec`). */\n  prelude?: () => string | Buffer | undefined;\n  /** The bytes for one frame. */\n  encode(frame: F): string | Buffer;\n  /**\n   * Whether a frame advances the chunk index and the fixture tick (default\n   * true). A frame that does not count still pays the delay at the current\n   * index.\n   */\n  counts?(frame: F): boolean;\n  /**\n   * Written after the last frame, before `end()`, when the response has not\n   * ended. Only a completed delivery reaches it: an aborted one returns `false`\n   * with no trailer and no `end()`, so `aborted` is always `false` here.\n   */\n  trailer?(aborted: boolean): Array<string | Buffer>;\n  /** Send the head with `writeHead` up front instead of `setHeader`. */\n  writeHeadImmediately?: boolean;\n  /**\n   * Check `sink.gone()` before each delay as well as after it, with or\n   * without a lifecycle, and return `false` when gone.\n   */\n  checkGoneBeforeDelay?: boolean;\n}\n\n/**\n * Where frames go: an HTTP response or a WebSocket connection. A sink with no\n * HTTP head (WebSocket) omits `setHeader` and `writeHead`; asking such a sink\n * for a status (`status` or `writeHeadImmediately`) is a programming error.\n */\nexport interface FrameSink {\n  gone(): boolean;\n  writableEnded(): boolean;\n  write(chunk: string | Buffer): void;\n  end(): void;\n  /** Whether the head was already committed (HTTP only). */\n  headersSent?(): boolean;\n  setHeader?(name: string, value: string): void;\n  writeHead?(status: number, headers: Record<string, string>): void;\n}\n\n/** Per-frame delay inputs, passed straight to `calculateDelay`. */\nexport interface FrameTiming {\n  latency?: number;\n  streamingProfile?: StreamingProfile;\n  recordedTimings?: RecordedTimings;\n  replaySpeed?: number;\n}\n\ninterface FrameLoopCommonOptions {\n  onChunkSent?: () => void;\n  /** When given, `writeHead(status, headers)` is sent before the first frame. */\n  status?: number;\n  /** Extra headers, merged over the codec's headers. */\n  headers?: Record<string, string>;\n}\n\n/**\n * The stop source is a `lifecycle` or a bare `signal`, never both: passing both\n * is a programming error and rejects with a `TypeError`.\n */\nexport type FrameLoopOptions = FrameLoopCommonOptions &\n  (\n    | {\n        /**\n         * Its signal stops the loop and `sink.gone()` is checked next to every\n         * abort check.\n         */\n        lifecycle: DeliveryLifecycle;\n        signal?: never;\n      }\n    | {\n        lifecycle?: never;\n        /**\n         * Without a lifecycle, `signal` stops the loop, and a gone sink stops it\n         * only when the codec sets `checkGoneBeforeDelay`.\n         */\n        signal?: AbortSignal;\n      }\n  );\n\n/** An HTTP response as a frame sink. Gone means destroyed. */\nexport function httpSink(res: http.ServerResponse): FrameSink {\n  return {\n    gone: () => res.destroyed,\n    writableEnded: () => res.writableEnded,\n    headersSent: () => res.headersSent,\n    write: (chunk) => {\n      res.write(chunk);\n    },\n    end: () => {\n      res.end();\n    },\n    setHeader: (name, value) => {\n      res.setHeader(name, value);\n    },\n    writeHead: (status, headers) => {\n      res.writeHead(status, headers);\n    },\n  };\n}\n\n/** A WebSocket connection as a frame sink. Gone means closed; it never ends. */\nexport function wsSink(ws: WebSocketConnection): FrameSink {\n  return {\n    gone: () => ws.isClosed,\n    writableEnded: () => false,\n    write: (chunk) => {\n      ws.send(typeof chunk === \"string\" ? chunk : chunk.toString(\"utf8\"));\n    },\n    end: () => {},\n  };\n}\n\n/**\n * The shared streaming loop. Per frame, in order: gone check (with\n * `checkGoneBeforeDelay`) → `calculateDelay` → `delay(d, signal)` → abort\n * check → gone check (with `checkGoneBeforeDelay`) → `writableEnded` (return\n * `true`) → write → advance the index and tick (counting frames only) → abort\n * re-check. After the last frame the trailer and `end()` run if the response\n * has not ended. Returns `false` when stopped by an abort, or by a gone sink\n * (with a lifecycle or `checkGoneBeforeDelay`), including an abort before the\n * first frame or with no frames, and `true` otherwise. Rejects with a\n * `TypeError` when given both a lifecycle and a signal, or a status for a sink\n * without `writeHead`.\n *\n * With a lifecycle, a response that other code already answered is not a\n * completed delivery: an ended response (at entry or at the `writableEnded`\n * check) returns `false`, and so does a head already committed at entry,\n * which `setHeader`/`writeHead` would reject with `ERR_HTTP_HEADERS_SENT`.\n * Without a lifecycle (the exported writers) an ended response still returns\n * `true`, as base did.\n */\nexport async function runFrameLoop<F>(\n  sink: FrameSink,\n  frames: readonly F[],\n  codec: FrameCodec<F>,\n  timing: FrameTiming,\n  opts: FrameLoopOptions = {},\n): Promise<boolean> {\n  const { lifecycle } = opts;\n  if (lifecycle !== undefined && opts.signal !== undefined) {\n    throw new TypeError(\"runFrameLoop: pass a lifecycle or a signal, not both\");\n  }\n  const signal = lifecycle?.signal ?? opts.signal;\n  const stopped = (): boolean =>\n    signal?.aborted === true || (lifecycle !== undefined && sink.gone());\n\n  // With a lifecycle, a response that other code answered is not a completed delivery.\n  const endedIsCompleted = lifecycle === undefined;\n  if (sink.writableEnded()) return endedIsCompleted;\n  if (lifecycle && sink.gone()) return false;\n  if (lifecycle && sink.headersSent?.() === true) return false;\n\n  const headers =\n    opts.headers === undefined ? codec.headers : { ...codec.headers, ...opts.headers };\n  if (opts.status !== undefined || codec.writeHeadImmediately) {\n    if (!sink.writeHead) {\n      throw new TypeError(\"runFrameLoop: a status was requested but the sink has no writeHead\");\n    }\n    sink.writeHead(opts.status ?? 200, headers);\n  } else if (sink.setHeader) {\n    for (const [name, value] of Object.entries(headers)) sink.setHeader(name, value);\n  }\n\n  if (codec.prelude && !sink.writableEnded()) {\n    const prelude = codec.prelude();\n    if (prelude !== undefined) sink.write(prelude);\n  }\n\n  let chunkIndex = 0;\n  for (const frame of frames) {\n    if (codec.checkGoneBeforeDelay && sink.gone()) return false;\n    const chunkDelay = calculateDelay(\n      chunkIndex,\n      timing.streamingProfile,\n      timing.latency ?? 0,\n      timing.recordedTimings,\n      timing.replaySpeed,\n    );\n    if (chunkDelay > 0) await delay(chunkDelay, signal);\n    if (stopped()) return false;\n    if (codec.checkGoneBeforeDelay && sink.gone()) return false;\n    if (sink.writableEnded()) return endedIsCompleted;\n    sink.write(codec.encode(frame));\n    if (codec.counts?.(frame) !== false) {\n      chunkIndex++;\n      opts.onChunkSent?.();\n    }\n    if (stopped()) return false;\n  }\n\n  // An abort the loop never observed (no frames) still stops the delivery.\n  if (stopped()) return false;\n  if (!sink.writableEnded()) {\n    for (const part of codec.trailer?.(false) ?? []) sink.write(part);\n    sink.end();\n  }\n  return true;\n}\n"],"mappings":";;;;AA+FA,SAAgB,SAAS,KAAqC;AAC5D,QAAO;EACL,YAAY,IAAI;EAChB,qBAAqB,IAAI;EACzB,mBAAmB,IAAI;EACvB,QAAQ,UAAU;AAChB,OAAI,MAAM,MAAM;;EAElB,WAAW;AACT,OAAI,KAAK;;EAEX,YAAY,MAAM,UAAU;AAC1B,OAAI,UAAU,MAAM,MAAM;;EAE5B,YAAY,QAAQ,YAAY;AAC9B,OAAI,UAAU,QAAQ,QAAQ;;EAEjC;;;AAIH,SAAgB,OAAO,IAAoC;AACzD,QAAO;EACL,YAAY,GAAG;EACf,qBAAqB;EACrB,QAAQ,UAAU;AAChB,MAAG,KAAK,OAAO,UAAU,WAAW,QAAQ,MAAM,SAAS,OAAO,CAAC;;EAErE,WAAW;EACZ;;;;;;;;;;;;;;;;;;;;;AAsBH,eAAsB,aACpB,MACA,QACA,OACA,QACA,OAAyB,EAAE,EACT;CAClB,MAAM,EAAE,cAAc;AACtB,KAAI,cAAc,UAAa,KAAK,WAAW,OAC7C,OAAM,IAAI,UAAU,uDAAuD;CAE7E,MAAM,SAAS,WAAW,UAAU,KAAK;CACzC,MAAM,gBACJ,QAAQ,YAAY,QAAS,cAAc,UAAa,KAAK,MAAM;CAGrE,MAAM,mBAAmB,cAAc;AACvC,KAAI,KAAK,eAAe,CAAE,QAAO;AACjC,KAAI,aAAa,KAAK,MAAM,CAAE,QAAO;AACrC,KAAI,aAAa,KAAK,eAAe,KAAK,KAAM,QAAO;CAEvD,MAAM,UACJ,KAAK,YAAY,SAAY,MAAM,UAAU;EAAE,GAAG,MAAM;EAAS,GAAG,KAAK;EAAS;AACpF,KAAI,KAAK,WAAW,UAAa,MAAM,sBAAsB;AAC3D,MAAI,CAAC,KAAK,UACR,OAAM,IAAI,UAAU,qEAAqE;AAE3F,OAAK,UAAU,KAAK,UAAU,KAAK,QAAQ;YAClC,KAAK,UACd,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,CAAE,MAAK,UAAU,MAAM,MAAM;AAGlF,KAAI,MAAM,WAAW,CAAC,KAAK,eAAe,EAAE;EAC1C,MAAM,UAAU,MAAM,SAAS;AAC/B,MAAI,YAAY,OAAW,MAAK,MAAM,QAAQ;;CAGhD,IAAI,aAAa;AACjB,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,MAAM,wBAAwB,KAAK,MAAM,CAAE,QAAO;EACtD,MAAM,aAAa,eACjB,YACA,OAAO,kBACP,OAAO,WAAW,GAClB,OAAO,iBACP,OAAO,YACR;AACD,MAAI,aAAa,EAAG,OAAM,MAAM,YAAY,OAAO;AACnD,MAAI,SAAS,CAAE,QAAO;AACtB,MAAI,MAAM,wBAAwB,KAAK,MAAM,CAAE,QAAO;AACtD,MAAI,KAAK,eAAe,CAAE,QAAO;AACjC,OAAK,MAAM,MAAM,OAAO,MAAM,CAAC;AAC/B,MAAI,MAAM,SAAS,MAAM,KAAK,OAAO;AACnC;AACA,QAAK,eAAe;;AAEtB,MAAI,SAAS,CAAE,QAAO;;AAIxB,KAAI,SAAS,CAAE,QAAO;AACtB,KAAI,CAAC,KAAK,eAAe,EAAE;AACzB,OAAK,MAAM,QAAQ,MAAM,UAAU,MAAM,IAAI,EAAE,CAAE,MAAK,MAAM,KAAK;AACjE,OAAK,KAAK;;AAEZ,QAAO"}

package/dist/response/lifecycle.cjs

@@ -0,0 +1,223 @@
+const require_chaos = require('../chaos.cjs');
+const require_interruption = require('../interruption.cjs');
+
+//#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 (require_chaos.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 ? require_interruption.createInterruptionSignal(fixture) : null;
+	const gone = require_chaos.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 ? require_interruption.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
+exports.AIMOCK_DISCONNECTED = AIMOCK_DISCONNECTED;
+exports.CLIENT_ABORTED = CLIENT_ABORTED;
+exports.closedByClient = closedByClient;
+exports.httpLifecycle = httpLifecycle;
+exports.markInterrupted = markInterrupted;
+exports.markWsTurnStopped = markWsTurnStopped;
+exports.noteDeliveryStart = noteDeliveryStart;
+exports.requestSocket = requestSocket;
+exports.statusLineSent = statusLineSent;
+exports.teardownCause = teardownCause;
+exports.teardownReason = teardownReason;
+exports.watchWsClose = watchWsClose;
+exports.wsLifecycle = wsLifecycle;
+//# sourceMappingURL=lifecycle.cjs.map