@alwaysmeticulous/backend-recorder-workerd 2.308.0 → 2.319.0

package/dist/sidecar-client.js

@@ -1,6 +1,15 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="81b6dfa3-bea2-53e3-a6be-f23b3b050e4c")}catch(e){}}();
 import { warnOnce } from "./log.js";
-import { SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION_HEADER } from "./protocol.js";
+import { SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
 //#region src/sidecar-client.ts
+/**
+* Replay calls sit in the request path, unlike record mode's fire-and-forget reporting, so
+* they must be bounded: without a timeout a wedged sidecar would hang every outbound fetch
+* the app makes, and therefore the whole replay, with nothing to look at.
+*/
+const SESSION_INFO_TIMEOUT_MS = 1e4;
+const LOOKUP_TIMEOUT_MS = 5e3;
 /** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */
 const postCaptureEvents = async (fetchFn, sidecarUrl, events) => {
 	try {
@@ -19,7 +28,80 @@ const postCaptureEvents = async (fetchFn, sidecarUrl, events) => {
 		warnOnce("sidecar-unreachable", "Could not reach the Meticulous backend recorder sidecar — backend session events are not being recorded.", error);
 	}
 };
+/**
+* Asks whether the sidecar holds mocks for a session, and at what instant to freeze the
+* clock while serving it.
+*
+* A 404 is how a record-only sidecar answers, so it counts as a settled `unavailable` and
+* the shim degrades to pass-through against an older sidecar rather than failing.
+*/
+const getReplaySessionInfo = async (fetchFn, sidecarUrl, frontendSessionId) => {
+	const url = `${sidecarUrl}${SIDECAR_REPLAY_SESSION_PATH}?sessionId=${encodeURIComponent(frontendSessionId)}`;
+	try {
+		const response = await fetchFn(url, {
+			headers: { [SIDECAR_PROTOCOL_VERSION_HEADER]: "1" },
+			signal: timeoutSignal(SESSION_INFO_TIMEOUT_MS)
+		});
+		if (!response.ok) {
+			await response.arrayBuffer().catch(() => void 0);
+			if (response.status >= 500) {
+				warnOnce("replay-session-unreachable", `Meticulous replay sidecar failed the replay session handshake (HTTP ${response.status}) — will retry on the next request.`);
+				return { outcome: "unreachable" };
+			}
+			warnOnce("replay-session-unavailable", `Meticulous replay sidecar did not recognise the replay session route (HTTP ${response.status}) — outbound calls will not be mocked.`);
+			return { outcome: "unavailable" };
+		}
+		const info = await response.json();
+		if (info.found !== true) {
+			warnOnce("replay-session-unknown", "Meticulous replay sidecar holds no mocks for this session — outbound calls will not be mocked.");
+			return { outcome: "unavailable" };
+		}
+		return {
+			outcome: "found",
+			clockAnchorMs: typeof info.clockAnchorMs === "number" ? info.clockAnchorMs : void 0
+		};
+	} catch (error) {
+		warnOnce("replay-session-unreachable", "Could not reach the Meticulous replay sidecar — will retry on the next request.", error);
+		return { outcome: "unreachable" };
+	}
+};
+/**
+* Looks up a recorded response for one outbound call. Never rejects; returns undefined when
+* the sidecar could not be consulted, which callers treat the same as a miss (let the real
+* call through).
+*/
+const postOutboundFetchLookup = async (fetchFn, sidecarUrl, payload) => {
+	try {
+		const response = await fetchFn(`${sidecarUrl}${SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				[SIDECAR_PROTOCOL_VERSION_HEADER]: "1"
+			},
+			body: JSON.stringify(payload),
+			signal: timeoutSignal(LOOKUP_TIMEOUT_MS)
+		});
+		if (!response.ok) {
+			warnOnce("replay-lookup-rejected", `Meticulous replay sidecar rejected a mock lookup (HTTP ${response.status}).`);
+			await response.arrayBuffer().catch(() => void 0);
+			return;
+		}
+		return await response.json();
+	} catch (error) {
+		warnOnce("replay-lookup-unreachable", "Could not reach the Meticulous replay sidecar for a mock lookup — letting the real call through.", error);
+		return;
+	}
+};
+/** AbortSignal.timeout, or undefined where it is unavailable. */
+const timeoutSignal = (ms) => {
+	try {
+		return AbortSignal.timeout(ms);
+	} catch {
+		return;
+	}
+};
 //#endregion
-export { postCaptureEvents };
+export { getReplaySessionInfo, postCaptureEvents, postOutboundFetchLookup };
 
-//# sourceMappingURL=sidecar-client.js.map
+//# sourceMappingURL=sidecar-client.js.map
+//# debugId=81b6dfa3-bea2-53e3-a6be-f23b3b050e4c

package/dist/sidecar-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-client.js","names":[],"sources":["../src/sidecar-client.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport {\n  type CaptureEvent,\n  type CaptureEventsPayload,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n} from \"./protocol\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n/** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */\nexport const postCaptureEvents = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  events: CaptureEvent[],\n): Promise<void> => {\n  try {\n    const payload: CaptureEventsPayload = { events };\n    const response = await fetchFn(`${sidecarUrl}${SIDECAR_EVENTS_PATH}`, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n      },\n      body: JSON.stringify(payload),\n    });\n    if (!response.ok) {\n      warnOnce(\n        \"sidecar-rejected\",\n        `Meticulous sidecar rejected capture events (HTTP ${response.status}).`,\n      );\n    }\n    await response.arrayBuffer().catch(() => undefined);\n  } catch (error) {\n    warnOnce(\n      \"sidecar-unreachable\",\n      \"Could not reach the Meticulous backend recorder sidecar — backend session events are not being recorded.\",\n      error,\n    );\n  }\n};\n"],"mappings":";;;;AAYA,MAAa,oBAAoB,OAC/B,SACA,YACA,WACkB;AAClB,KAAI;EACF,MAAM,UAAgC,EAAE,QAAQ;EAChD,MAAM,WAAW,MAAM,QAAQ,GAAG,aAAa,uBAAuB;GACpE,QAAQ;GACR,SAAS;IACP,gBAAgB;KACf,kCAAA;IACF;GACD,MAAM,KAAK,UAAU,QAAQ;GAC9B,CAAC;AACF,MAAI,CAAC,SAAS,GACZ,UACE,oBACA,oDAAoD,SAAS,OAAO,IACrE;AAEH,QAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;UAC5C,OAAO;AACd,WACE,uBACA,4GACA,MACD"}
+{"version":3,"file":"sidecar-client.js","sources":["../src/sidecar-client.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport {\n  type CaptureEvent,\n  type CaptureEventsPayload,\n  type OutboundFetchLookupRequest,\n  type OutboundFetchLookupResponse,\n  type ReplaySessionInfoResponse,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n  SIDECAR_REPLAY_OUTBOUND_FETCH_PATH,\n  SIDECAR_REPLAY_SESSION_PATH,\n} from \"./protocol\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n/**\n * Replay calls sit in the request path, unlike record mode's fire-and-forget reporting, so\n * they must be bounded: without a timeout a wedged sidecar would hang every outbound fetch\n * the app makes, and therefore the whole replay, with nothing to look at.\n */\nconst SESSION_INFO_TIMEOUT_MS = 10_000;\nconst LOOKUP_TIMEOUT_MS = 5_000;\n\n/** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */\nexport const postCaptureEvents = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  events: CaptureEvent[],\n): Promise<void> => {\n  try {\n    const payload: CaptureEventsPayload = { events };\n    const response = await fetchFn(`${sidecarUrl}${SIDECAR_EVENTS_PATH}`, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n      },\n      body: JSON.stringify(payload),\n    });\n    if (!response.ok) {\n      warnOnce(\n        \"sidecar-rejected\",\n        `Meticulous sidecar rejected capture events (HTTP ${response.status}).`,\n      );\n    }\n    await response.arrayBuffer().catch(() => undefined);\n  } catch (error) {\n    warnOnce(\n      \"sidecar-unreachable\",\n      \"Could not reach the Meticulous backend recorder sidecar — backend session events are not being recorded.\",\n      error,\n    );\n  }\n};\n\n/**\n * Outcome of the session handshake.\n *\n * `unavailable` and `unreachable` both mean \"do not replay\", but they are kept apart\n * because only the first is a settled answer. The caller caches per isolate, and caching a\n * one-off network blip would disable mocking for the rest of the session — silently sending\n * every later outbound call to the real service.\n */\nexport type ReplaySessionInfoResult =\n  /** The sidecar holds mocks for this session. */\n  | { outcome: \"found\"; clockAnchorMs: number | undefined }\n  /** The sidecar answered and will never serve this session: no mocks, or no such route. */\n  | { outcome: \"unavailable\" }\n  /** Could not get an answer — timeout, transport error, 5xx. May succeed later. */\n  | { outcome: \"unreachable\" };\n\n/**\n * Asks whether the sidecar holds mocks for a session, and at what instant to freeze the\n * clock while serving it.\n *\n * A 404 is how a record-only sidecar answers, so it counts as a settled `unavailable` and\n * the shim degrades to pass-through against an older sidecar rather than failing.\n */\nexport const getReplaySessionInfo = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<ReplaySessionInfoResult> => {\n  const url = `${sidecarUrl}${SIDECAR_REPLAY_SESSION_PATH}?sessionId=${encodeURIComponent(\n    frontendSessionId,\n  )}`;\n  try {\n    const response = await fetchFn(url, {\n      headers: {\n        [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n      },\n      signal: timeoutSignal(SESSION_INFO_TIMEOUT_MS),\n    });\n    if (!response.ok) {\n      await response.arrayBuffer().catch(() => undefined);\n      // 4xx is the sidecar telling us something definitive — no such route (a record-only\n      // sidecar), or a protocol version it will not speak. Retrying cannot change either.\n      // 5xx may well be a sidecar still finding its feet, so leave it retryable.\n      if (response.status >= 500) {\n        warnOnce(\n          \"replay-session-unreachable\",\n          `Meticulous replay sidecar failed the replay session handshake (HTTP ${response.status}) — will retry on the next request.`,\n        );\n        return { outcome: \"unreachable\" };\n      }\n      warnOnce(\n        \"replay-session-unavailable\",\n        `Meticulous replay sidecar did not recognise the replay session route (HTTP ${response.status}) — outbound calls will not be mocked.`,\n      );\n      return { outcome: \"unavailable\" };\n    }\n    const info = (await response.json()) as ReplaySessionInfoResponse;\n    if (info.found !== true) {\n      warnOnce(\n        \"replay-session-unknown\",\n        \"Meticulous replay sidecar holds no mocks for this session — outbound calls will not be mocked.\",\n      );\n      return { outcome: \"unavailable\" };\n    }\n    return {\n      outcome: \"found\",\n      clockAnchorMs:\n        typeof info.clockAnchorMs === \"number\" ? info.clockAnchorMs : undefined,\n    };\n  } catch (error) {\n    warnOnce(\n      \"replay-session-unreachable\",\n      \"Could not reach the Meticulous replay sidecar — will retry on the next request.\",\n      error,\n    );\n    return { outcome: \"unreachable\" };\n  }\n};\n\n/**\n * Looks up a recorded response for one outbound call. Never rejects; returns undefined when\n * the sidecar could not be consulted, which callers treat the same as a miss (let the real\n * call through).\n */\nexport const postOutboundFetchLookup = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  payload: OutboundFetchLookupRequest,\n): Promise<OutboundFetchLookupResponse | undefined> => {\n  try {\n    const response = await fetchFn(\n      `${sidecarUrl}${SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}`,\n      {\n        method: \"POST\",\n        headers: {\n          \"content-type\": \"application/json\",\n          [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n        },\n        body: JSON.stringify(payload),\n        signal: timeoutSignal(LOOKUP_TIMEOUT_MS),\n      },\n    );\n    if (!response.ok) {\n      warnOnce(\n        \"replay-lookup-rejected\",\n        `Meticulous replay sidecar rejected a mock lookup (HTTP ${response.status}).`,\n      );\n      await response.arrayBuffer().catch(() => undefined);\n      return undefined;\n    }\n    return (await response.json()) as OutboundFetchLookupResponse;\n  } catch (error) {\n    warnOnce(\n      \"replay-lookup-unreachable\",\n      \"Could not reach the Meticulous replay sidecar for a mock lookup — letting the real call through.\",\n      error,\n    );\n    return undefined;\n  }\n};\n\n/** AbortSignal.timeout, or undefined where it is unavailable. */\nconst timeoutSignal = (ms: number): AbortSignal | undefined => {\n  try {\n    return AbortSignal.timeout(ms);\n  } catch {\n    return undefined;\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;AAqBA,MAAM,0BAA0B;AAChC,MAAM,oBAAoB;;AAG1B,MAAa,oBAAoB,OAC/B,SACA,YACA,WACkB;AAClB,KAAI;EACF,MAAM,UAAgC,EAAE,QAAQ;EAChD,MAAM,WAAW,MAAM,QAAQ,GAAG,aAAa,uBAAuB;GACpE,QAAQ;GACR,SAAS;IACP,gBAAgB;KACf,kCAAA;IACF;GACD,MAAM,KAAK,UAAU,QAAQ;GAC9B,CAAC;AACF,MAAI,CAAC,SAAS,GACZ,UACE,oBACA,oDAAoD,SAAS,OAAO,IACrE;AAEH,QAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;UAC5C,OAAO;AACd,WACE,uBACA,4GACA,MACD;;;;;;;;;;AA2BL,MAAa,uBAAuB,OAClC,SACA,YACA,sBACqC;CACrC,MAAM,MAAM,GAAG,aAAa,4BAA4B,aAAa,mBACnE,kBACD;AACD,KAAI;EACF,MAAM,WAAW,MAAM,QAAQ,KAAK;GAClC,SAAS,GACN,kCAAA,KACF;GACD,QAAQ,cAAc,wBAAwB;GAC/C,CAAC;AACF,MAAI,CAAC,SAAS,IAAI;AAChB,SAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;AAInD,OAAI,SAAS,UAAU,KAAK;AAC1B,aACE,8BACA,uEAAuE,SAAS,OAAO,qCACxF;AACD,WAAO,EAAE,SAAS,eAAe;;AAEnC,YACE,8BACA,8EAA8E,SAAS,OAAO,wCAC/F;AACD,UAAO,EAAE,SAAS,eAAe;;EAEnC,MAAM,OAAQ,MAAM,SAAS,MAAM;AACnC,MAAI,KAAK,UAAU,MAAM;AACvB,YACE,0BACA,iGACD;AACD,UAAO,EAAE,SAAS,eAAe;;AAEnC,SAAO;GACL,SAAS;GACT,eACE,OAAO,KAAK,kBAAkB,WAAW,KAAK,gBAAgB,KAAA;GACjE;UACM,OAAO;AACd,WACE,8BACA,mFACA,MACD;AACD,SAAO,EAAE,SAAS,eAAe;;;;;;;;AASrC,MAAa,0BAA0B,OACrC,SACA,YACA,YACqD;AACrD,KAAI;EACF,MAAM,WAAW,MAAM,QACrB,GAAG,aAAa,sCAChB;GACE,QAAQ;GACR,SAAS;IACP,gBAAgB;KACf,kCAAA;IACF;GACD,MAAM,KAAK,UAAU,QAAQ;GAC7B,QAAQ,cAAc,kBAAkB;GACzC,CACF;AACD,MAAI,CAAC,SAAS,IAAI;AAChB,YACE,0BACA,0DAA0D,SAAS,OAAO,IAC3E;AACD,SAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;AACnD;;AAEF,SAAQ,MAAM,SAAS,MAAM;UACtB,OAAO;AACd,WACE,6BACA,oGACA,MACD;AACD;;;;AAKJ,MAAM,iBAAiB,OAAwC;AAC7D,KAAI;AACF,SAAO,YAAY,QAAQ,GAAG;SACxB;AACN","debugId":"81b6dfa3-bea2-53e3-a6be-f23b3b050e4c"}

package/dist/virtual-clock.js

@@ -0,0 +1,122 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ef892b9a-fcab-5f5d-baed-592098a17dd5")}catch(e){}}();
+import { requestCaptureContext } from "./context.js";
+import { warnOnce } from "./log.js";
+//#region src/virtual-clock.ts
+/**
+* Freezes the worker's wall clock at the replayed session's last recorded activity.
+*
+* Without this, replay fails even when every outbound call is mocked correctly: credentials
+* minted during the recording (Firebase session cookies, OAuth access tokens) carry
+* short expiries, so by replay time the app rejects its own recorded credentials as stale.
+* Anchoring at the *end* of the recording means everything minted mid-session is already
+* issued but not yet expired.
+*
+* Ported from the Node backend recorder's replay clock, with two differences:
+*   - the anchor comes from the request context rather than a session→anchor map, because
+*     workerd's AsyncLocalStorage propagates reliably from the inbound handler. The Node
+*     version needs a process-wide "most recently seen session" fallback, which can
+*     resolve the wrong session on a replica serving several at once;
+*   - the busy-wait breaker schedules on `setTimeout` — workerd has no `setImmediate`.
+*
+* Only `Date` is patched, matching the Node implementation's scope (no `Intl`, no
+* `Temporal`, no timer virtualisation).
+*/
+const OriginalDate = globalThis.Date;
+const BREAK_AFTER = 2e4;
+let lastLoopBreakBaseMs = 0;
+let sameKeyCount = 0;
+let loopBreakResetScheduled = false;
+const applyLoopBreak = (baseMs) => {
+	if (!loopBreakResetScheduled) {
+		loopBreakResetScheduled = true;
+		try {
+			setTimeout(() => {
+				sameKeyCount = 0;
+				loopBreakResetScheduled = false;
+			}, 0);
+		} catch {
+			loopBreakResetScheduled = false;
+		}
+	}
+	if (baseMs === lastLoopBreakBaseMs) sameKeyCount++;
+	else {
+		lastLoopBreakBaseMs = baseMs;
+		sameKeyCount = 0;
+	}
+	return sameKeyCount <= BREAK_AFTER ? baseMs : baseMs + (sameKeyCount - BREAK_AFTER);
+};
+/**
+* The virtual "now" for the request currently executing, or null when it is not a replay or
+* carries no anchor — in which case callers use the real clock. Reads outside any request
+* (module evaluation, background work) always get the real clock.
+*/
+const resolveVirtualNow = () => {
+	const ctx = requestCaptureContext.getStore();
+	if (ctx === void 0 || ctx.mode !== "replay") return null;
+	return ctx.clockAnchorMs === void 0 ? null : applyLoopBreak(ctx.clockAnchorMs);
+};
+/**
+* What `Date.now()` reports. A standalone function rather than only a class static, so the
+* callable shim below can reuse it without referencing an unbound method — it touches no
+* `this`, so there is nothing to lose.
+*/
+const virtualDateNow = () => {
+	const virtualNow = resolveVirtualNow();
+	return virtualNow === null ? OriginalDate.now() : virtualNow;
+};
+var VirtualDateClass = class extends OriginalDate {
+	constructor(...args) {
+		if (args.length > 0) {
+			super(...args);
+			return;
+		}
+		const virtualNow = resolveVirtualNow();
+		if (virtualNow === null) {
+			super();
+			return;
+		}
+		super(virtualNow);
+	}
+	static now() {
+		return virtualDateNow();
+	}
+};
+function VirtualDate(...args) {
+	if (!(this instanceof VirtualDate)) return new VirtualDateClass().toString();
+	return new VirtualDateClass(...args);
+}
+VirtualDate.now = virtualDateNow;
+VirtualDate.parse = OriginalDate.parse;
+VirtualDate.UTC = OriginalDate.UTC;
+Object.defineProperty(VirtualDate, "prototype", {
+	value: VirtualDateClass.prototype,
+	writable: false,
+	configurable: false
+});
+VirtualDateClass.prototype.constructor = VirtualDate;
+let installed = false;
+/**
+* Replaces the global `Date` with the per-request virtual clock. Idempotent, and a no-op
+* failure: a worker that will not let its `Date` be replaced still replays, just without
+* clock virtualisation.
+*
+* Called lazily from the replay branch of the request wrapper rather than at module scope:
+* record mode and deployed production workers then pay nothing, and the package declares no
+* `sideEffects`, so a module-scope side effect could legitimately be tree-shaken away by a
+* customer's bundler.
+*/
+const installVirtualClock = () => {
+	if (installed) return;
+	installed = true;
+	try {
+		globalThis.Date = VirtualDate;
+	} catch (error) {
+		warnOnce("virtual-clock", "Could not install the Meticulous replay clock — recorded credentials may be treated as expired.", error);
+	}
+};
+//#endregion
+export { installVirtualClock };
+
+//# sourceMappingURL=virtual-clock.js.map
+//# debugId=ef892b9a-fcab-5f5d-baed-592098a17dd5

package/dist/virtual-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-clock.js","sources":["../src/virtual-clock.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport { warnOnce } from \"./log\";\n\n/**\n * Freezes the worker's wall clock at the replayed session's last recorded activity.\n *\n * Without this, replay fails even when every outbound call is mocked correctly: credentials\n * minted during the recording (Firebase session cookies, OAuth access tokens) carry\n * short expiries, so by replay time the app rejects its own recorded credentials as stale.\n * Anchoring at the *end* of the recording means everything minted mid-session is already\n * issued but not yet expired.\n *\n * Ported from the Node backend recorder's replay clock, with two differences:\n *   - the anchor comes from the request context rather than a session→anchor map, because\n *     workerd's AsyncLocalStorage propagates reliably from the inbound handler. The Node\n *     version needs a process-wide \"most recently seen session\" fallback, which can\n *     resolve the wrong session on a replica serving several at once;\n *   - the busy-wait breaker schedules on `setTimeout` — workerd has no `setImmediate`.\n *\n * Only `Date` is patched, matching the Node implementation's scope (no `Intl`, no\n * `Temporal`, no timer virtualisation).\n */\n\nconst OriginalDate = globalThis.Date;\n\n/** Real wall clock, immune to the patch below. */\nexport const nativeDateNow = (): number => OriginalDate.now();\n\n// ---------------------------------------------------------------------------\n// Busy-wait loop breaker\n// ---------------------------------------------------------------------------\n\n// A frozen clock makes `while (Date.now() < deadline) {}` spin forever. Count reads that\n// return the same frozen value and, past the threshold, nudge the result forward 1ms per\n// extra read until the loop's deadline is met. The nudge is a pure function of the repeat\n// count, so a base and head replay break an identical loop identically.\nconst BREAK_AFTER = 20_000;\n\nlet lastLoopBreakBaseMs = 0;\nlet sameKeyCount = 0;\nlet loopBreakResetScheduled = false;\n\nconst applyLoopBreak = (baseMs: number): number => {\n  // Reset at the end of the current macrotask. A synchronous busy-wait blocks the loop so\n  // this cannot fire, letting the counter accumulate until it breaks the spin; once the\n  // turn yields, the reset runs and the next turn starts fresh.\n  if (!loopBreakResetScheduled) {\n    loopBreakResetScheduled = true;\n    try {\n      setTimeout(() => {\n        sameKeyCount = 0;\n        loopBreakResetScheduled = false;\n      }, 0);\n    } catch {\n      // Timers throw outside a request context in workerd. Nothing to reset in that case,\n      // since clock reads there fall through to the real clock anyway.\n      loopBreakResetScheduled = false;\n    }\n  }\n\n  if (baseMs === lastLoopBreakBaseMs) {\n    sameKeyCount++;\n  } else {\n    lastLoopBreakBaseMs = baseMs;\n    sameKeyCount = 0;\n  }\n  return sameKeyCount <= BREAK_AFTER\n    ? baseMs\n    : baseMs + (sameKeyCount - BREAK_AFTER);\n};\n\n// ---------------------------------------------------------------------------\n// Resolver\n// ---------------------------------------------------------------------------\n\n/**\n * The virtual \"now\" for the request currently executing, or null when it is not a replay or\n * carries no anchor — in which case callers use the real clock. Reads outside any request\n * (module evaluation, background work) always get the real clock.\n */\nconst resolveVirtualNow = (): number | null => {\n  const ctx = requestCaptureContext.getStore();\n  if (ctx === undefined || ctx.mode !== \"replay\") {\n    return null;\n  }\n  return ctx.clockAnchorMs === undefined\n    ? null\n    : applyLoopBreak(ctx.clockAnchorMs);\n};\n\n// ---------------------------------------------------------------------------\n// Date shim\n// ---------------------------------------------------------------------------\n\n/**\n * What `Date.now()` reports. A standalone function rather than only a class static, so the\n * callable shim below can reuse it without referencing an unbound method — it touches no\n * `this`, so there is nothing to lose.\n */\nconst virtualDateNow = (): number => {\n  const virtualNow = resolveVirtualNow();\n  return virtualNow === null ? OriginalDate.now() : virtualNow;\n};\n\n// `Date` is heavily overloaded; capture args loosely and forward every explicit form\n// unchanged. Only the zero-arg form reads \"now\" and is virtualized.\nclass VirtualDateClass extends OriginalDate {\n  constructor(...args: unknown[]) {\n    if (args.length > 0) {\n      super(...(args as ConstructorParameters<typeof OriginalDate>));\n      return;\n    }\n    const virtualNow = resolveVirtualNow();\n    if (virtualNow === null) {\n      super();\n      return;\n    }\n    super(virtualNow);\n  }\n\n  static override now(): number {\n    return virtualDateNow();\n  }\n}\n\n// Classes cannot be called without `new`, but native `Date()` can be (returning a string),\n// so wrap the class in a plain function supporting both.\nfunction VirtualDate(this: unknown, ...args: unknown[]): Date | string {\n  if (!(this instanceof VirtualDate)) {\n    return new VirtualDateClass().toString();\n  }\n  return new VirtualDateClass(...args);\n}\n\nVirtualDate.now = virtualDateNow;\nVirtualDate.parse = OriginalDate.parse;\nVirtualDate.UTC = OriginalDate.UTC;\n\n// Share the prototype so `new Date() instanceof Date` holds and every Date.prototype\n// method resolves on instances.\nObject.defineProperty(VirtualDate, \"prototype\", {\n  value: VirtualDateClass.prototype,\n  writable: false,\n  configurable: false,\n});\n(VirtualDateClass.prototype as { constructor: unknown }).constructor =\n  VirtualDate;\n\n// ---------------------------------------------------------------------------\n// Install\n// ---------------------------------------------------------------------------\n\nlet installed = false;\n\n/**\n * Replaces the global `Date` with the per-request virtual clock. Idempotent, and a no-op\n * failure: a worker that will not let its `Date` be replaced still replays, just without\n * clock virtualisation.\n *\n * Called lazily from the replay branch of the request wrapper rather than at module scope:\n * record mode and deployed production workers then pay nothing, and the package declares no\n * `sideEffects`, so a module-scope side effect could legitimately be tree-shaken away by a\n * customer's bundler.\n */\nexport const installVirtualClock = (): void => {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  try {\n    globalThis.Date = VirtualDate as unknown as DateConstructor;\n  } catch (error) {\n    warnOnce(\n      \"virtual-clock\",\n      \"Could not install the Meticulous replay clock — recorded credentials may be treated as expired.\",\n      error,\n    );\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAM,eAAe,WAAW;AAahC,MAAM,cAAc;AAEpB,IAAI,sBAAsB;AAC1B,IAAI,eAAe;AACnB,IAAI,0BAA0B;AAE9B,MAAM,kBAAkB,WAA2B;AAIjD,KAAI,CAAC,yBAAyB;AAC5B,4BAA0B;AAC1B,MAAI;AACF,oBAAiB;AACf,mBAAe;AACf,8BAA0B;MACzB,EAAE;UACC;AAGN,6BAA0B;;;AAI9B,KAAI,WAAW,oBACb;MACK;AACL,wBAAsB;AACtB,iBAAe;;AAEjB,QAAO,gBAAgB,cACnB,SACA,UAAU,eAAe;;;;;;;AAY/B,MAAM,0BAAyC;CAC7C,MAAM,MAAM,sBAAsB,UAAU;AAC5C,KAAI,QAAQ,KAAA,KAAa,IAAI,SAAS,SACpC,QAAO;AAET,QAAO,IAAI,kBAAkB,KAAA,IACzB,OACA,eAAe,IAAI,cAAc;;;;;;;AAYvC,MAAM,uBAA+B;CACnC,MAAM,aAAa,mBAAmB;AACtC,QAAO,eAAe,OAAO,aAAa,KAAK,GAAG;;AAKpD,IAAM,mBAAN,cAA+B,aAAa;CAC1C,YAAY,GAAG,MAAiB;AAC9B,MAAI,KAAK,SAAS,GAAG;AACnB,SAAM,GAAI,KAAoD;AAC9D;;EAEF,MAAM,aAAa,mBAAmB;AACtC,MAAI,eAAe,MAAM;AACvB,UAAO;AACP;;AAEF,QAAM,WAAW;;CAGnB,OAAgB,MAAc;AAC5B,SAAO,gBAAgB;;;AAM3B,SAAS,YAA2B,GAAG,MAAgC;AACrE,KAAI,EAAE,gBAAgB,aACpB,QAAO,IAAI,kBAAkB,CAAC,UAAU;AAE1C,QAAO,IAAI,iBAAiB,GAAG,KAAK;;AAGtC,YAAY,MAAM;AAClB,YAAY,QAAQ,aAAa;AACjC,YAAY,MAAM,aAAa;AAI/B,OAAO,eAAe,aAAa,aAAa;CAC9C,OAAO,iBAAiB;CACxB,UAAU;CACV,cAAc;CACf,CAAC;AACF,iBAAkB,UAAuC,cACvD;AAMF,IAAI,YAAY;;;;;;;;;;;AAYhB,MAAa,4BAAkC;AAC7C,KAAI,UACF;AAEF,aAAY;AACZ,KAAI;AACF,aAAW,OAAO;UACX,OAAO;AACd,WACE,iBACA,mGACA,MACD","debugId":"ef892b9a-fcab-5f5d-baed-592098a17dd5"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/backend-recorder-workerd",
-  "version": "2.308.0",
+  "version": "2.319.0",
   "type": "module",
   "description": "Meticulous backend recorder shim for Cloudflare Workers (workerd). Reports inbound and outbound HTTP capture events to a local Meticulous recorder sidecar during development recording.",
   "license": "ISC",
@@ -20,21 +20,10 @@
     "workerd",
     "recorder"
   ],
-  "scripts": {
-    "clean": "rimraf dist tsconfig.tsbuildinfo",
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "format": "prettier --write src",
-    "lint": "oxlint --type-aware src",
-    "lint:commit": "eslint --cache $(git diff --relative --name-only --diff-filter=ACMRTUXB master | grep  -E \"(.js$|.ts$|.tsx$)\")",
-    "lint:fix": "oxlint --type-aware src --fix",
-    "depcheck": "depcheck --ignore-patterns=dist",
-    "test": "vitest run --passWithNoTests"
-  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsdown": "^0.21.7",
-    "vitest": "catalog:"
+    "vitest": "^4.1.7"
   },
   "author": {
     "name": "The Meticulous Team",
@@ -52,5 +41,16 @@
   },
   "bugs": {
     "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
+  },
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "format": "prettier --write src",
+    "lint": "oxlint --type-aware src",
+    "lint:commit": "eslint --cache $(git diff --relative --name-only --diff-filter=ACMRTUXB master | grep  -E \"(.js$|.ts$|.tsx$)\")",
+    "lint:fix": "oxlint --type-aware src --fix",
+    "depcheck": "depcheck --ignore-patterns=dist",
+    "test": "vitest run --passWithNoTests"
   }
-}
+}