@alwaysmeticulous/backend-recorder-workerd 2.326.0 → 2.327.0

package/dist/virtual-random.js

@@ -1,10 +1,10 @@
 
-!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]="3821aa29-b3ba-551f-957d-45a05bdc02bf")}catch(e){}}();
+!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]="0b356a44-c057-5a04-b105-f150b4aab2af")}catch(e){}}();
 import { requestCaptureContext } from "./context.js";
 import { warnOnce } from "./log.js";
 //#region src/virtual-random.ts
 /**
-* Per-session randomness virtualization for replay mode.
+* Per-request randomness virtualization for replay mode.
 *
 * Mocking every outbound `fetch` is not enough to make a replay deterministic: a Worker that
 * mints an id (`crypto.randomUUID()` for a guest id, `getRandomValues` for a token) produces
@@ -21,8 +21,16 @@ import { warnOnce } from "./log.js";
 * the browser replayer's `mockOutRandomNumberGeneration`, including its butterfly-effect
 * containment: a separate sequence per call stack, seeded from a per-call-site counter, so a
 * change in one part of the app does not shift the numbers another part gets, and a shared
-* helper called from two places does not return the same value twice. Two differences from
-* the Node version, both forced by the runtime:
+* helper called from two places does not return the same value twice. Sequences are scoped
+* to the inbound request, not the whole replay: two concurrent requests of the same session
+* that race to the same call site would otherwise consume one shared stream in arrival
+* order, and a Fisher-Yates shuffle (or any other draw) would then differ between replays.
+* Each request starts its sequences over from the same session-scoped seed. Each call site
+* on a request returns {@link UNATTRIBUTED_DRAW} for the first {@link FIXED_DRAWS_BEFORE_PRNG}
+* draws and only then starts the PRNG, so a shuffle is identical across concurrent requests
+* and a `while (Math.random() < 0.5)` loop still terminates.
+*
+* Two differences from the Node version, both forced by the runtime:
 *
 *   - the session comes from the request context rather than a session resolver with a
 *     process-wide fallback, because workerd's AsyncLocalStorage propagates reliably from the
@@ -47,12 +55,28 @@ const nativeGetRandomValues = globalThis.crypto?.getRandomValues?.bind(globalThi
 const FRAMES_TO_APP = 3;
 /** How much of the stack identifies a sequence. Ten frames tells call paths apart cheaply. */
 const STACK_FRAMES = 10;
-/** Stack captures per session, after which sequences are keyed by call site alone. */
+/** Stack captures per request, after which sequences are keyed by call site alone. */
 const MAX_STACK_CAPTURES = 1e4;
-/** Bounds the state a stream of unrecognised session ids can accumulate in one isolate. */
-const MAX_TRACKED_SESSIONS = 50;
 const UNKNOWN_CALL_SITE = "unknown";
-const stateBySession = /* @__PURE__ */ new Map();
+/**
+* What a draw returns before its call site's PRNG starts, and what unattributed draws
+* return. Leading digits of pi, so the value is recognisably ours in a diff or a log.
+*/
+const UNATTRIBUTED_DRAW = .3142;
+/**
+* Draws at one call site on one request that return {@link UNATTRIBUTED_DRAW} before the
+* seeded PRNG starts. Large enough that a shuffle stays constant, small enough that
+* `while (Math.random() < 0.5)` still exits.
+*/
+const FIXED_DRAWS_BEFORE_PRNG = 1e3;
+const drawUnattributed = () => UNATTRIBUTED_DRAW;
+/**
+* Held on the inbound request object, so two concurrent requests of one replay cannot share
+* a generator. The seed below stays session-scoped: base and head are different replays of
+* the same recording and must draw identical numbers, and two requests of that recording
+* must draw the same first values rather than racing to consume one stream.
+*/
+const stateByRequest = /* @__PURE__ */ new WeakMap();
 /**
 * Alea, the same algorithm the browser replayer gets from `seedrandom`. Inlined because this
 * package is published to npm and ships no runtime dependencies — a customer's Worker bundle
@@ -92,10 +116,10 @@ const createSeededRandom = (seed) => {
 		return s2;
 	};
 };
-const getCallStack = () => {
+const getCallStack = (frameCount = STACK_FRAMES) => {
 	const originalLimit = Error.stackTraceLimit;
 	try {
-		Error.stackTraceLimit = FRAMES_TO_APP + STACK_FRAMES;
+		Error.stackTraceLimit = FRAMES_TO_APP + frameCount;
 		const stack = (/* @__PURE__ */ new Error()).stack;
 		if (stack == null) return {
 			stack: UNKNOWN_CALL_SITE,
@@ -115,22 +139,24 @@ const getCallStack = () => {
 		Error.stackTraceLimit = originalLimit;
 	}
 };
-const getSessionState = () => {
+const stillInFixedDrawPhase = (state, callSite) => {
+	const n = (state.drawsByCallSite.get(callSite) ?? 0) + 1;
+	state.drawsByCallSite.set(callSite, n);
+	return n <= FIXED_DRAWS_BEFORE_PRNG;
+};
+const getRequestState = () => {
 	const ctx = requestCaptureContext.getStore();
 	if (ctx === void 0 || ctx.mode !== "replay") return;
-	const existing = stateBySession.get(ctx.frontendSessionId);
+	const existing = stateByRequest.get(ctx);
 	if (existing !== void 0) return existing;
-	if (stateBySession.size >= MAX_TRACKED_SESSIONS) {
-		const oldest = stateBySession.keys().next();
-		if (!oldest.done) stateBySession.delete(oldest.value);
-	}
 	const created = {
 		frontendSessionId: ctx.frontendSessionId,
 		generatorBySequenceKey: /* @__PURE__ */ new Map(),
 		nextCallerIdByCallSite: /* @__PURE__ */ new Map(),
+		drawsByCallSite: /* @__PURE__ */ new Map(),
 		stackCaptures: 0
 	};
-	stateBySession.set(ctx.frontendSessionId, created);
+	stateByRequest.set(ctx, created);
 	return created;
 };
 /**
@@ -153,8 +179,9 @@ const getSessionState = () => {
 * avoid.
 */
 const openSequence = () => {
-	const state = getSessionState();
+	const state = getRequestState();
 	if (state === void 0) return;
+	if (stillInFixedDrawPhase(state, getCallStack(1).site)) return drawUnattributed;
 	let sequenceKey = UNKNOWN_CALL_SITE;
 	let callSite = UNKNOWN_CALL_SITE;
 	if (state.stackCaptures < MAX_STACK_CAPTURES) {
@@ -192,7 +219,7 @@ const fillBytes = (view, draw) => {
 };
 let installed = false;
 /**
-* Replaces the worker's sources of randomness with per-session seeded generators. Idempotent,
+* Replaces the worker's sources of randomness with per-request seeded generators. Idempotent,
 * and a no-op failure: a worker that will not let them be replaced still replays, just
 * without randomness virtualisation.
 *
@@ -235,4 +262,4 @@ const installVirtualRandom = () => {
 export { installVirtualRandom };
 
 //# sourceMappingURL=virtual-random.js.map
-//# debugId=3821aa29-b3ba-551f-957d-45a05bdc02bf
+//# debugId=0b356a44-c057-5a04-b105-f150b4aab2af

package/dist/virtual-random.js.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-random.js","sources":["../src/virtual-random.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport { warnOnce } from \"./log\";\n\n/**\n * Per-session randomness virtualization for replay mode.\n *\n * Mocking every outbound `fetch` is not enough to make a replay deterministic: a Worker that\n * mints an id (`crypto.randomUUID()` for a guest id, `getRandomValues` for a token) produces\n * a different value in the base replay than in the head replay, so the rendered HTML differs\n * and any screenshot showing that value diffs forever. This replaces the worker's sources of\n * randomness with seeded generators while serving a replayed request, so two replays of the\n * same recorded session render identically.\n *\n * Deliberately a *generator*, not a recording: like the browser replayer we do not capture\n * the numbers the original session produced, we produce fresh ones from a fixed seed. The\n * app still sees plausible random values, and two replays see the same ones.\n *\n * Ported from the Node backend recorder's `replay/virtual-random.ts`, which in turn mirrors\n * the browser replayer's `mockOutRandomNumberGeneration`, including its butterfly-effect\n * containment: a separate sequence per call stack, seeded from a per-call-site counter, so a\n * change in one part of the app does not shift the numbers another part gets, and a shared\n * helper called from two places does not return the same value twice. Two differences from\n * the Node version, both forced by the runtime:\n *\n *   - the session comes from the request context rather than a session resolver with a\n *     process-wide fallback, because workerd's AsyncLocalStorage propagates reliably from the\n *     inbound handler;\n *   - only the globals workerd actually has are patched — there is no `node:crypto` module to\n *     mutate.\n *\n * Reads outside a replayed request — module evaluation, a recording, a deployed production\n * worker — fall through to the native generators untouched.\n */\n\nconst nativeMathRandom = Math.random.bind(Math);\nconst nativeRandomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);\nconst nativeGetRandomValues = globalThis.crypto?.getRandomValues?.bind(\n  globalThis.crypto,\n);\n\n/**\n * Frames of the stack that belong to this module and must be skipped to reach the app's call\n * site, counted from the `new Error()` inside {@link getCallStack}.\n *\n * Getting this wrong degrades gracefully rather than breaking: a call site that resolves to\n * one of our own frames merges sequences that should have been separate, which costs\n * butterfly-effect isolation but is still perfectly deterministic.\n */\nconst FRAMES_TO_APP = 3; // getCallStack ← openSequence ← patched global ← app\n\n/** How much of the stack identifies a sequence. Ten frames tells call paths apart cheaply. */\nconst STACK_FRAMES = 10;\n\n/** Stack captures per session, after which sequences are keyed by call site alone. */\nconst MAX_STACK_CAPTURES = 10_000;\n\n/** Bounds the state a stream of unrecognised session ids can accumulate in one isolate. */\nconst MAX_TRACKED_SESSIONS = 50;\n\nconst UNKNOWN_CALL_SITE = \"unknown\";\n\ninterface SessionRandomState {\n  frontendSessionId: string;\n  generatorBySequenceKey: Map<string, () => number>;\n  nextCallerIdByCallSite: Map<string, number>;\n  stackCaptures: number;\n}\n\nconst stateBySession = new Map<string, SessionRandomState>();\n\n// ---------------------------------------------------------------------------\n// Seeded PRNG (Alea)\n// ---------------------------------------------------------------------------\n\n/**\n * Alea, the same algorithm the browser replayer gets from `seedrandom`. Inlined because this\n * package is published to npm and ships no runtime dependencies — a customer's Worker bundle\n * should not grow for this.\n */\nexport const createSeededRandom = (seed: string): (() => number) => {\n  let n = 0xefc8249d;\n  const mash = (data: string): number => {\n    for (let i = 0; i < data.length; i++) {\n      n += data.charCodeAt(i);\n      let h = 0.02519603282416938 * n;\n      n = h >>> 0;\n      h -= n;\n      h *= n;\n      n = h >>> 0;\n      h -= n;\n      n += h * 0x100000000;\n    }\n    return (n >>> 0) * 2.3283064365386963e-10;\n  };\n\n  let s0 = mash(\" \");\n  let s1 = mash(\" \");\n  let s2 = mash(\" \");\n  let c = 1;\n  s0 -= mash(seed);\n  if (s0 < 0) {\n    s0 += 1;\n  }\n  s1 -= mash(seed);\n  if (s1 < 0) {\n    s1 += 1;\n  }\n  s2 -= mash(seed);\n  if (s2 < 0) {\n    s2 += 1;\n  }\n\n  return () => {\n    const t = 2091639 * s0 + c * 2.3283064365386963e-10;\n    s0 = s1;\n    s1 = s2;\n    c = t | 0;\n    s2 = t - c;\n    return s2;\n  };\n};\n\n// ---------------------------------------------------------------------------\n// Sequence resolution\n// ---------------------------------------------------------------------------\n\nconst getCallStack = (): { stack: string; site: string } => {\n  const originalLimit = Error.stackTraceLimit;\n  try {\n    Error.stackTraceLimit = FRAMES_TO_APP + STACK_FRAMES;\n    const stack = new Error().stack;\n    if (stack == null) {\n      return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n    }\n    // Line 0 is the \"Error\" header; frame lines follow, innermost first, and the first\n    // FRAMES_TO_APP of them are ours.\n    const lines = stack.split(\"\\n\").slice(FRAMES_TO_APP + 1);\n    return {\n      stack: lines.join(\"\\n\") || UNKNOWN_CALL_SITE,\n      site: lines[0] ?? UNKNOWN_CALL_SITE,\n    };\n  } catch {\n    return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n  } finally {\n    Error.stackTraceLimit = originalLimit;\n  }\n};\n\nconst getSessionState = (): SessionRandomState | undefined => {\n  const ctx = requestCaptureContext.getStore();\n  if (ctx === undefined || ctx.mode !== \"replay\") {\n    return undefined;\n  }\n  const existing = stateBySession.get(ctx.frontendSessionId);\n  if (existing !== undefined) {\n    return existing;\n  }\n  if (stateBySession.size >= MAX_TRACKED_SESSIONS) {\n    const oldest = stateBySession.keys().next();\n    if (!oldest.done) {\n      stateBySession.delete(oldest.value);\n    }\n  }\n  const created: SessionRandomState = {\n    frontendSessionId: ctx.frontendSessionId,\n    generatorBySequenceKey: new Map(),\n    nextCallerIdByCallSite: new Map(),\n    stackCaptures: 0,\n  };\n  stateBySession.set(ctx.frontendSessionId, created);\n  return created;\n};\n\n/**\n * The generator for the sequence the current call belongs to, or undefined outside a\n * replayed request.\n *\n * Sequences are keyed by the whole call stack, so a second call down the same path continues\n * the same sequence and gets a different value. The *seed* comes from a counter kept per\n * immediate call site, which is what keeps a shared id helper honest: two call paths through\n * the same `generateId()` share a call site, so they are seeded 0 and 1 and return different\n * ids.\n *\n * Note what the seed deliberately does NOT contain: any part of the stack. Base and head are\n * different builds of the app, so the same logical call site has a different string in each —\n * a seed built from it would change on every rebuild. The consequence, which the browser\n * replayer shares, is that two *distinct* call sites each seen for the first time both seed at\n * 0 and hand out the same first value. That is the accepted trade: an alternative that\n * separated them (say, an ordinal per call site) would shift every later site's values as soon\n * as a PR added one randomness call, which is the butterfly effect this whole scheme exists to\n * avoid.\n */\nconst openSequence = (): (() => number) | undefined => {\n  const state = getSessionState();\n  if (state === undefined) {\n    return undefined;\n  }\n\n  let sequenceKey = UNKNOWN_CALL_SITE;\n  let callSite = UNKNOWN_CALL_SITE;\n  if (state.stackCaptures < MAX_STACK_CAPTURES) {\n    state.stackCaptures++;\n    const captured = getCallStack();\n    sequenceKey = captured.stack;\n    callSite = captured.site;\n  }\n\n  const existing = state.generatorBySequenceKey.get(sequenceKey);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const callerId = state.nextCallerIdByCallSite.get(callSite) ?? 0;\n  // Seeded from the counter only — never from the call-site or stack string itself. Those embed\n  // bundle filenames and line numbers, which differ between the base build and the head build\n  // of the very same code, so putting one in the seed would reseed every sequence on any\n  // rebuild and bring back exactly the diffs this exists to remove. The strings are grouping\n  // keys, nothing more.\n  const generator = createSeededRandom(\n    `meticulous-random-${state.frontendSessionId}-${callerId}`,\n  );\n  state.generatorBySequenceKey.set(sequenceKey, generator);\n  state.nextCallerIdByCallSite.set(callSite, callerId + 1);\n  return generator;\n};\n\n// ---------------------------------------------------------------------------\n// Derived primitives\n// ---------------------------------------------------------------------------\n\nconst HEX = \"0123456789abcdef\";\n/** The two bits of a v4 UUID's variant field are fixed, leaving these four values. */\nconst VARIANT = \"89ab\";\n\nconst buildUuid = (draw: () => number): string => {\n  let uuid = \"\";\n  for (let i = 0; i < 36; i++) {\n    if (i === 8 || i === 13 || i === 18 || i === 23) {\n      uuid += \"-\";\n    } else if (i === 14) {\n      uuid += \"4\";\n    } else if (i === 19) {\n      uuid += VARIANT[Math.floor(draw() * VARIANT.length)];\n    } else {\n      uuid += HEX[Math.floor(draw() * HEX.length)];\n    }\n  }\n  return uuid;\n};\n\n/**\n * Fills the view's bytes rather than its elements, so every typed array — including the\n * BigInt ones, whose elements cannot be assigned a number — is handled by one path.\n */\nconst fillBytes = (view: ArrayBufferView, draw: () => number): void => {\n  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Math.floor(draw() * 256);\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Install\n// ---------------------------------------------------------------------------\n\nlet installed = false;\n\n/**\n * Replaces the worker's sources of randomness with per-session seeded generators. Idempotent,\n * and a no-op failure: a worker that will not let them be replaced still replays, just\n * without randomness virtualisation.\n *\n * Called lazily from the replay branch of the request wrapper rather than at module scope,\n * for the same reasons as the virtual clock: record mode and deployed production workers then\n * pay nothing, and the package declares no `sideEffects`, so a module-scope side effect could\n * legitimately be tree-shaken away by a customer's bundler.\n */\nexport const installVirtualRandom = (): void => {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  try {\n    Math.random = () => openSequence()?.() ?? nativeMathRandom();\n\n    if (globalThis.crypto != null) {\n      Object.defineProperty(globalThis.crypto, \"randomUUID\", {\n        value: (): string => {\n          const draw = openSequence();\n          if (draw !== undefined) {\n            return buildUuid(draw);\n          }\n          return nativeRandomUUID?.() ?? buildUuid(nativeMathRandom);\n        },\n        configurable: true,\n        writable: true,\n      });\n\n      Object.defineProperty(globalThis.crypto, \"getRandomValues\", {\n        value: <T extends ArrayBufferView>(array: T): T => {\n          const draw = openSequence();\n          if (draw === undefined) {\n            return nativeGetRandomValues?.(array) ?? array;\n          }\n          fillBytes(array, draw);\n          return array;\n        },\n        configurable: true,\n        writable: true,\n      });\n    }\n  } catch (error) {\n    warnOnce(\n      \"virtual-random\",\n      \"Could not install the Meticulous replay random-number generators — ids minted by the app will differ between replays.\",\n      error,\n    );\n  }\n};\n"],"names":[],"mappings":"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","debugId":"3821aa29-b3ba-551f-957d-45a05bdc02bf"}
+{"version":3,"file":"virtual-random.js","sources":["../src/virtual-random.ts"],"sourcesContent":["import { requestCaptureContext, type RequestReplayContext } from \"./context\";\nimport { warnOnce } from \"./log\";\n\n/**\n * Per-request randomness virtualization for replay mode.\n *\n * Mocking every outbound `fetch` is not enough to make a replay deterministic: a Worker that\n * mints an id (`crypto.randomUUID()` for a guest id, `getRandomValues` for a token) produces\n * a different value in the base replay than in the head replay, so the rendered HTML differs\n * and any screenshot showing that value diffs forever. This replaces the worker's sources of\n * randomness with seeded generators while serving a replayed request, so two replays of the\n * same recorded session render identically.\n *\n * Deliberately a *generator*, not a recording: like the browser replayer we do not capture\n * the numbers the original session produced, we produce fresh ones from a fixed seed. The\n * app still sees plausible random values, and two replays see the same ones.\n *\n * Ported from the Node backend recorder's `replay/virtual-random.ts`, which in turn mirrors\n * the browser replayer's `mockOutRandomNumberGeneration`, including its butterfly-effect\n * containment: a separate sequence per call stack, seeded from a per-call-site counter, so a\n * change in one part of the app does not shift the numbers another part gets, and a shared\n * helper called from two places does not return the same value twice. Sequences are scoped\n * to the inbound request, not the whole replay: two concurrent requests of the same session\n * that race to the same call site would otherwise consume one shared stream in arrival\n * order, and a Fisher-Yates shuffle (or any other draw) would then differ between replays.\n * Each request starts its sequences over from the same session-scoped seed. Each call site\n * on a request returns {@link UNATTRIBUTED_DRAW} for the first {@link FIXED_DRAWS_BEFORE_PRNG}\n * draws and only then starts the PRNG, so a shuffle is identical across concurrent requests\n * and a `while (Math.random() < 0.5)` loop still terminates.\n *\n * Two differences from the Node version, both forced by the runtime:\n *\n *   - the session comes from the request context rather than a session resolver with a\n *     process-wide fallback, because workerd's AsyncLocalStorage propagates reliably from the\n *     inbound handler;\n *   - only the globals workerd actually has are patched — there is no `node:crypto` module to\n *     mutate.\n *\n * Reads outside a replayed request — module evaluation, a recording, a deployed production\n * worker — fall through to the native generators untouched.\n */\n\nconst nativeMathRandom = Math.random.bind(Math);\nconst nativeRandomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);\nconst nativeGetRandomValues = globalThis.crypto?.getRandomValues?.bind(\n  globalThis.crypto,\n);\n\n/**\n * Frames of the stack that belong to this module and must be skipped to reach the app's call\n * site, counted from the `new Error()` inside {@link getCallStack}.\n *\n * Getting this wrong degrades gracefully rather than breaking: a call site that resolves to\n * one of our own frames merges sequences that should have been separate, which costs\n * butterfly-effect isolation but is still perfectly deterministic.\n */\nconst FRAMES_TO_APP = 3; // getCallStack ← openSequence ← patched global ← app\n\n/** How much of the stack identifies a sequence. Ten frames tells call paths apart cheaply. */\nconst STACK_FRAMES = 10;\n\n/** Stack captures per request, after which sequences are keyed by call site alone. */\nconst MAX_STACK_CAPTURES = 10_000;\n\nconst UNKNOWN_CALL_SITE = \"unknown\";\n\n/**\n * What a draw returns before its call site's PRNG starts, and what unattributed draws\n * return. Leading digits of pi, so the value is recognisably ours in a diff or a log.\n */\nexport const UNATTRIBUTED_DRAW = 0.3142;\n\n/**\n * Draws at one call site on one request that return {@link UNATTRIBUTED_DRAW} before the\n * seeded PRNG starts. Large enough that a shuffle stays constant, small enough that\n * `while (Math.random() < 0.5)` still exits.\n */\nexport const FIXED_DRAWS_BEFORE_PRNG = 1_000;\n\nconst drawUnattributed = (): number => UNATTRIBUTED_DRAW;\n\ninterface RequestRandomState {\n  frontendSessionId: string;\n  generatorBySequenceKey: Map<string, () => number>;\n  nextCallerIdByCallSite: Map<string, number>;\n  drawsByCallSite: Map<string, number>;\n  stackCaptures: number;\n}\n\n/**\n * Held on the inbound request object, so two concurrent requests of one replay cannot share\n * a generator. The seed below stays session-scoped: base and head are different replays of\n * the same recording and must draw identical numbers, and two requests of that recording\n * must draw the same first values rather than racing to consume one stream.\n */\nconst stateByRequest = new WeakMap<RequestReplayContext, RequestRandomState>();\n\n// ---------------------------------------------------------------------------\n// Seeded PRNG (Alea)\n// ---------------------------------------------------------------------------\n\n/**\n * Alea, the same algorithm the browser replayer gets from `seedrandom`. Inlined because this\n * package is published to npm and ships no runtime dependencies — a customer's Worker bundle\n * should not grow for this.\n */\nexport const createSeededRandom = (seed: string): (() => number) => {\n  let n = 0xefc8249d;\n  const mash = (data: string): number => {\n    for (let i = 0; i < data.length; i++) {\n      n += data.charCodeAt(i);\n      let h = 0.02519603282416938 * n;\n      n = h >>> 0;\n      h -= n;\n      h *= n;\n      n = h >>> 0;\n      h -= n;\n      n += h * 0x100000000;\n    }\n    return (n >>> 0) * 2.3283064365386963e-10;\n  };\n\n  let s0 = mash(\" \");\n  let s1 = mash(\" \");\n  let s2 = mash(\" \");\n  let c = 1;\n  s0 -= mash(seed);\n  if (s0 < 0) {\n    s0 += 1;\n  }\n  s1 -= mash(seed);\n  if (s1 < 0) {\n    s1 += 1;\n  }\n  s2 -= mash(seed);\n  if (s2 < 0) {\n    s2 += 1;\n  }\n\n  return () => {\n    const t = 2091639 * s0 + c * 2.3283064365386963e-10;\n    s0 = s1;\n    s1 = s2;\n    c = t | 0;\n    s2 = t - c;\n    return s2;\n  };\n};\n\n// ---------------------------------------------------------------------------\n// Sequence resolution\n// ---------------------------------------------------------------------------\n\nconst getCallStack = (\n  frameCount: number = STACK_FRAMES,\n): { stack: string; site: string } => {\n  const originalLimit = Error.stackTraceLimit;\n  try {\n    Error.stackTraceLimit = FRAMES_TO_APP + frameCount;\n    const stack = new Error().stack;\n    if (stack == null) {\n      return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n    }\n    // Line 0 is the \"Error\" header; frame lines follow, innermost first, and the first\n    // FRAMES_TO_APP of them are ours.\n    const lines = stack.split(\"\\n\").slice(FRAMES_TO_APP + 1);\n    return {\n      stack: lines.join(\"\\n\") || UNKNOWN_CALL_SITE,\n      site: lines[0] ?? UNKNOWN_CALL_SITE,\n    };\n  } catch {\n    return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n  } finally {\n    Error.stackTraceLimit = originalLimit;\n  }\n};\n\nconst stillInFixedDrawPhase = (\n  state: RequestRandomState,\n  callSite: string,\n): boolean => {\n  const n = (state.drawsByCallSite.get(callSite) ?? 0) + 1;\n  state.drawsByCallSite.set(callSite, n);\n  return n <= FIXED_DRAWS_BEFORE_PRNG;\n};\n\nconst getRequestState = (): RequestRandomState | undefined => {\n  const ctx = requestCaptureContext.getStore();\n  if (ctx === undefined || ctx.mode !== \"replay\") {\n    return undefined;\n  }\n  const existing = stateByRequest.get(ctx);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const created: RequestRandomState = {\n    frontendSessionId: ctx.frontendSessionId,\n    generatorBySequenceKey: new Map(),\n    nextCallerIdByCallSite: new Map(),\n    drawsByCallSite: new Map(),\n    stackCaptures: 0,\n  };\n  stateByRequest.set(ctx, created);\n  return created;\n};\n\n/**\n * The generator for the sequence the current call belongs to, or undefined outside a\n * replayed request.\n *\n * Sequences are keyed by the whole call stack, so a second call down the same path continues\n * the same sequence and gets a different value. The *seed* comes from a counter kept per\n * immediate call site, which is what keeps a shared id helper honest: two call paths through\n * the same `generateId()` share a call site, so they are seeded 0 and 1 and return different\n * ids.\n *\n * Note what the seed deliberately does NOT contain: any part of the stack. Base and head are\n * different builds of the app, so the same logical call site has a different string in each —\n * a seed built from it would change on every rebuild. The consequence, which the browser\n * replayer shares, is that two *distinct* call sites each seen for the first time both seed at\n * 0 and hand out the same first value. That is the accepted trade: an alternative that\n * separated them (say, an ordinal per call site) would shift every later site's values as soon\n * as a PR added one randomness call, which is the butterfly effect this whole scheme exists to\n * avoid.\n */\nconst openSequence = (): (() => number) | undefined => {\n  const state = getRequestState();\n  if (state === undefined) {\n    return undefined;\n  }\n\n  // Called directly so FRAMES_TO_APP still lands on the app. A wrapper here would make\n  // every Math.random share one call site and one fixed-draw budget.\n  if (stillInFixedDrawPhase(state, getCallStack(1).site)) {\n    return drawUnattributed;\n  }\n\n  let sequenceKey = UNKNOWN_CALL_SITE;\n  let callSite = UNKNOWN_CALL_SITE;\n  if (state.stackCaptures < MAX_STACK_CAPTURES) {\n    state.stackCaptures++;\n    const captured = getCallStack();\n    sequenceKey = captured.stack;\n    callSite = captured.site;\n  }\n\n  const existing = state.generatorBySequenceKey.get(sequenceKey);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const callerId = state.nextCallerIdByCallSite.get(callSite) ?? 0;\n  // Seeded from the counter only — never from the call-site or stack string itself. Those embed\n  // bundle filenames and line numbers, which differ between the base build and the head build\n  // of the very same code, so putting one in the seed would reseed every sequence on any\n  // rebuild and bring back exactly the diffs this exists to remove. The strings are grouping\n  // keys, nothing more.\n  const generator = createSeededRandom(\n    `meticulous-random-${state.frontendSessionId}-${callerId}`,\n  );\n  state.generatorBySequenceKey.set(sequenceKey, generator);\n  state.nextCallerIdByCallSite.set(callSite, callerId + 1);\n  return generator;\n};\n\n// ---------------------------------------------------------------------------\n// Derived primitives\n// ---------------------------------------------------------------------------\n\nconst HEX = \"0123456789abcdef\";\n/** The two bits of a v4 UUID's variant field are fixed, leaving these four values. */\nconst VARIANT = \"89ab\";\n\nconst buildUuid = (draw: () => number): string => {\n  let uuid = \"\";\n  for (let i = 0; i < 36; i++) {\n    if (i === 8 || i === 13 || i === 18 || i === 23) {\n      uuid += \"-\";\n    } else if (i === 14) {\n      uuid += \"4\";\n    } else if (i === 19) {\n      uuid += VARIANT[Math.floor(draw() * VARIANT.length)];\n    } else {\n      uuid += HEX[Math.floor(draw() * HEX.length)];\n    }\n  }\n  return uuid;\n};\n\n/**\n * Fills the view's bytes rather than its elements, so every typed array — including the\n * BigInt ones, whose elements cannot be assigned a number — is handled by one path.\n */\nconst fillBytes = (view: ArrayBufferView, draw: () => number): void => {\n  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Math.floor(draw() * 256);\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Install\n// ---------------------------------------------------------------------------\n\nlet installed = false;\n\n/**\n * Replaces the worker's sources of randomness with per-request seeded generators. Idempotent,\n * and a no-op failure: a worker that will not let them be replaced still replays, just\n * without randomness virtualisation.\n *\n * Called lazily from the replay branch of the request wrapper rather than at module scope,\n * for the same reasons as the virtual clock: record mode and deployed production workers then\n * pay nothing, and the package declares no `sideEffects`, so a module-scope side effect could\n * legitimately be tree-shaken away by a customer's bundler.\n */\nexport const installVirtualRandom = (): void => {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  try {\n    Math.random = () => openSequence()?.() ?? nativeMathRandom();\n\n    if (globalThis.crypto != null) {\n      Object.defineProperty(globalThis.crypto, \"randomUUID\", {\n        value: (): string => {\n          const draw = openSequence();\n          if (draw !== undefined) {\n            return buildUuid(draw);\n          }\n          return nativeRandomUUID?.() ?? buildUuid(nativeMathRandom);\n        },\n        configurable: true,\n        writable: true,\n      });\n\n      Object.defineProperty(globalThis.crypto, \"getRandomValues\", {\n        value: <T extends ArrayBufferView>(array: T): T => {\n          const draw = openSequence();\n          if (draw === undefined) {\n            return nativeGetRandomValues?.(array) ?? array;\n          }\n          fillBytes(array, draw);\n          return array;\n        },\n        configurable: true,\n        writable: true,\n      });\n    }\n  } catch (error) {\n    warnOnce(\n      \"virtual-random\",\n      \"Could not install the Meticulous replay random-number generators — ids minted by the app will differ between replays.\",\n      error,\n    );\n  }\n};\n"],"names":[],"mappings":"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","debugId":"0b356a44-c057-5a04-b105-f150b4aab2af"}

package/dist/with-meticulous.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-meticulous.js","sources":["../src/with-meticulous.ts"],"sourcesContent":["import { installBindingPatch } from \"./binding-patch\";\nimport { CaptureBuffer } from \"./capture-buffer\";\nimport {\n  type RequestCaptureContext,\n  type RequestReplayContext,\n  requestCaptureContext,\n} from \"./context\";\nimport { installFetchPatch } from \"./fetch-patch\";\nimport { installKvPatch } from \"./kv-patch\";\nimport { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport { headersToRecord } from \"./outbound-capture\";\nimport {\n  FRONTEND_SESSION_ID_HEADER,\n  type InboundRequestEvent,\n  REPLAY_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n} from \"./protocol\";\nimport {\n  isProvisionalSessionIdCandidate,\n  mintProvisionalSessionId,\n} from \"./provisional-session-id\";\nimport { publishSessionIdOnResponse } from \"./publish-session-id\";\nimport { parseReplaySidecarUrl } from \"./replay-sidecar-url\";\nimport { getReplaySessionInfo } from \"./sidecar-client\";\nimport {\n  resolveSidecarTransport,\n  type SidecarFetcher,\n  type SidecarTransport,\n} from \"./sidecar-transport\";\nimport { randomHex } from \"./spans/span-builder\";\nimport { installVirtualClock } from \"./virtual-clock\";\nimport { installVirtualRandom } from \"./virtual-random\";\n\n/** Structural subset of workerd's ExecutionContext — avoids a @cloudflare/workers-types dependency. */\nexport interface MeticulousExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\nexport interface WithMeticulousOptions {\n  /**\n   * Overrides the sidecar service binding; defaults to the `METICULOUS_SIDECAR` binding on\n   * `env`. This is how a **deployed** Worker records — see {@link SidecarTransport}.\n   */\n  sidecarBinding?: SidecarFetcher;\n  /** Overrides the sidecar origin; defaults to the METICULOUS_SIDECAR_URL var/binding. */\n  sidecarUrl?: string;\n  /**\n   * Binding names to leave unrecorded, on top of the defaults (`ASSETS`, `__STATIC_CONTENT`,\n   * `METICULOUS_SIDECAR`). Use this for a binding whose traffic is high-volume or binary. Applies\n   * to KV namespaces as well as `fetch`-shaped bindings.\n   */\n  skipBindings?: readonly string[];\n  /**\n   * Whether to mint a session id for a document navigation that carries none, so the\n   * server-side render is recorded under the same session as the page it produces. On by\n   * default; set `false` (or the `METICULOUS_BACKEND_PROVISIONAL_SESSION_IDS` var to\n   * `\"false\"`) to opt out. See provisional-session-id.ts.\n   */\n  mintProvisionalSessionIds?: boolean;\n}\n\n/** What the mode-agnostic core needs from whichever handler shape wraps it. */\nexport interface MeticulousInvocation {\n  request: Request;\n  env: unknown;\n  ctx: MeticulousExecutionContext;\n  invokeHandler: () => Response | Promise<Response>;\n}\n\n/**\n * Records, or replays, one inbound request. Shared by `withMeticulous` (an ES-module Worker's\n * `fetch`) and `withMeticulousPagesFunction` (a Pages Functions `onRequest`), which differ only\n * in how they get at the request, the env and `waitUntil`.\n */\nexport const runWithMeticulous = async (\n  { request, env, ctx, invokeHandler }: MeticulousInvocation,\n  options: WithMeticulousOptions | undefined,\n): Promise<Response> => {\n  let transport: SidecarTransport | undefined;\n  let replayContext: RequestReplayContext | undefined;\n  try {\n    replayContext = await resolveReplayContext(request, ctx);\n    transport =\n      replayContext === undefined\n        ? resolveSidecarTransport(options, env)\n        : undefined;\n    if (replayContext !== undefined || transport !== undefined) {\n      installFetchPatch();\n    }\n    if (transport !== undefined) {\n      // Lazily, inside the request path, and never at module scope: the package declares no\n      // `sideEffects` and is built with `platform: \"neutral\"`, so a module-scope side effect can\n      // legitimately be tree-shaken by a customer's bundler. Re-run per request because `env` is\n      // the only handle on the binding instances.\n      //\n      // Record mode only. Binding and KV calls are recorded as their own technologies\n      // (`workerd-binding`, `workerd-kv`) and the replay sidecar's store holds only\n      // `workerd-fetch` spans, so there is nothing to serve them from — and patching would only\n      // route them into the capture tee, which POSTs to an events route a replay sidecar 404s.\n      //\n      // `skipInstances` keeps the sidecar's own binding out of the recording by identity rather\n      // than by name, so it holds however the customer named it or passed it in.\n      const patchOptions = {\n        ...(options?.skipBindings !== undefined\n          ? { skipBindings: options.skipBindings }\n          : {}),\n        ...(transport.kind === \"binding\"\n          ? { skipInstances: [transport.instance] }\n          : {}),\n      };\n      installBindingPatch(env, patchOptions);\n      installKvPatch(env, patchOptions);\n    }\n  } catch (error) {\n    warnOnce(\n      \"shim-init\",\n      \"Failed to initialize the Meticulous backend recorder shim — recording disabled.\",\n      error,\n    );\n    replayContext = undefined;\n    transport = undefined;\n  }\n\n  if (replayContext !== undefined) {\n    // Install the clock before any app code runs, so a module that reads Date.now() at call time\n    // (the firebase auth libraries do) sees the session's frozen instant.\n    installVirtualClock();\n    // Likewise the random generators: an id the app mints during SSR (a guest id, a request id)\n    // otherwise differs between a base and a head replay, and every rendered page carrying it\n    // diffs forever.\n    installVirtualRandom();\n    // No inbound reporting in replay mode: there is no exporter behind the replay sidecar, and\n    // the events route 404s there.\n    return requestCaptureContext.run(replayContext, invokeHandler);\n  }\n\n  if (transport === undefined) {\n    return invokeHandler();\n  }\n\n  const captureCtx = buildCaptureContext(\n    request,\n    transport,\n    ctx,\n    resolveMintProvisionalSessionIds(options, env),\n  );\n  const mintedSessionId =\n    captureCtx.sessionIdOrigin === \"backend\"\n      ? captureCtx.frontendSessionId\n      : undefined;\n  const startTimeMs = Date.now();\n  let requestHeaders: Record<string, string[]> = {};\n  let method = \"GET\";\n  let url = \"\";\n  try {\n    requestHeaders = headersToRecord(request.headers);\n    method = request.method;\n    url = request.url;\n  } catch (error) {\n    warnOnce(\n      \"inbound-capture\",\n      \"Failed to capture the inbound request.\",\n      error,\n    );\n  }\n\n  const reportInbound = (\n    outcome:\n      | { statusCode: number; responseHeaders: Record<string, string[]> }\n      | { error: string },\n  ): void => {\n    try {\n      const event: InboundRequestEvent = {\n        kind: \"inbound\",\n        requestId: captureCtx.requestId,\n        ...(captureCtx.frontendSessionId !== undefined\n          ? { frontendSessionId: captureCtx.frontendSessionId }\n          : {}),\n        ...(captureCtx.sessionIdOrigin !== undefined\n          ? { sessionIdOrigin: captureCtx.sessionIdOrigin }\n          : {}),\n        traceId: captureCtx.traceId,\n        serverSpanId: captureCtx.serverSpanId,\n        method,\n        url,\n        requestHeaders,\n        startTimeMs,\n        endTimeMs: Date.now(),\n        ...outcome,\n      };\n      captureCtx.buffer.add(event);\n    } catch (error) {\n      warnOnce(\n        \"inbound-report\",\n        \"Failed to report the inbound request.\",\n        error,\n      );\n    }\n  };\n\n  let response: Response;\n  try {\n    response = await requestCaptureContext.run(captureCtx, invokeHandler);\n  } catch (error) {\n    reportInbound({ error: String(error) });\n    closeBuffer(captureCtx);\n    throw error;\n  }\n\n  // Ahead of reporting, so what we record as the response headers is what the browser is\n  // actually served.\n  if (mintedSessionId !== undefined) {\n    response = publishSessionIdOnResponse(response, mintedSessionId);\n  }\n\n  try {\n    reportInbound({\n      statusCode: response.status,\n      responseHeaders: headersToRecord(response.headers),\n    });\n  } catch (error) {\n    warnOnce(\"inbound-report\", \"Failed to report the inbound request.\", error);\n  }\n  closeBuffer(captureCtx);\n  return response;\n};\n\n/**\n * Hands the request's single report to `waitUntil`. `close()` drains the outstanding body reads\n * first, which is why there is one `waitUntil` per request rather than one per captured call.\n */\nconst closeBuffer = (ctx: RequestCaptureContext): void => {\n  try {\n    ctx.waitUntil(ctx.buffer.close());\n  } catch (error) {\n    warnOnce(\n      \"buffer-close\",\n      \"ctx.waitUntil failed — capture events may be lost.\",\n      error,\n    );\n  }\n};\n\n/**\n * Whether this request should be replayed, and the context to serve it under.\n *\n * Both replay identity ids and a usable sidecar URL must be present: mocks are indexed per session\n * and consumed per replay. The sidecar is consulted once per (sidecar, session) per isolate to\n * confirm it holds mocks and to learn the clock anchor — a sidecar that does not recognise the\n * session, or the route, means replay is unavailable and the request runs normally.\n */\nconst resolveReplayContext = async (\n  request: Request,\n  ctx: MeticulousExecutionContext,\n): Promise<RequestReplayContext | undefined> => {\n  let sidecarUrl: string | undefined;\n  let frontendSessionId: string | undefined;\n  let replayId: string | undefined;\n  try {\n    sidecarUrl = parseReplaySidecarUrl(\n      request.headers.get(REPLAY_SIDECAR_URL_HEADER),\n    );\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n    replayId = request.headers.get(REPLAY_ID_HEADER) ?? undefined;\n  } catch {\n    return undefined;\n  }\n  if (\n    sidecarUrl === undefined ||\n    frontendSessionId === undefined ||\n    replayId === undefined\n  ) {\n    return undefined;\n  }\n\n  const info = await getCachedReplaySessionInfo(sidecarUrl, frontendSessionId);\n  if (info === null) {\n    return undefined;\n  }\n\n  return {\n    mode: \"replay\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    replayId,\n    sidecarUrl,\n    clockAnchorMs: info.clockAnchorMs,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\n// Caches the promise, not the result, so concurrent first requests share one round trip.\n// Bounded so a stream of unrecognised session ids cannot grow it without limit.\nconst MAX_CACHED_SESSIONS = 50;\nconst replaySessionInfoCache = new Map<\n  string,\n  Promise<{ clockAnchorMs: number | undefined } | null>\n>();\n\nconst getCachedReplaySessionInfo = (\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<{ clockAnchorMs: number | undefined } | null> => {\n  const key = `${sidecarUrl}\u0000${frontendSessionId}`;\n  const cached = replaySessionInfoCache.get(key);\n  if (cached !== undefined) {\n    return cached;\n  }\n  const pending = getReplaySessionInfo(\n    getOriginalFetch(),\n    sidecarUrl,\n    frontendSessionId,\n  ).then((result) => {\n    if (result.outcome === \"unreachable\") {\n      // Only settled answers are worth keeping. Caching a timeout or transport blip would\n      // disable mocking for this session for the life of the isolate, quietly sending every\n      // later outbound call to the real service — the failure this path exists to prevent.\n      // Dropping the entry costs one extra handshake and lets the next request recover.\n      replaySessionInfoCache.delete(key);\n      return null;\n    }\n    return result.outcome === \"found\"\n      ? { clockAnchorMs: result.clockAnchorMs }\n      : null;\n  });\n  if (replaySessionInfoCache.size >= MAX_CACHED_SESSIONS) {\n    const oldest = replaySessionInfoCache.keys().next();\n    if (!oldest.done) {\n      replaySessionInfoCache.delete(oldest.value);\n    }\n  }\n  replaySessionInfoCache.set(key, pending);\n  return pending;\n};\n\nconst buildCaptureContext = (\n  request: Request,\n  transport: SidecarTransport,\n  ctx: MeticulousExecutionContext,\n  mintProvisionalSessionIds: boolean,\n): RequestCaptureContext => {\n  let frontendSessionId: string | undefined;\n  let sessionIdOrigin: \"backend\" | undefined;\n  try {\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n    // A top-level document navigation cannot carry the header, so for one we mint the id\n    // ourselves and hand it to the page on the response — otherwise the server-side render this\n    // request is about is recorded against no session at all. Every outbound, binding, KV and\n    // postgres event reads the id back off this context, so putting it here attributes the whole\n    // request. See provisional-session-id.ts.\n    if (\n      mintProvisionalSessionIds &&\n      frontendSessionId === undefined &&\n      isProvisionalSessionIdCandidate(request.method, (name) =>\n        request.headers.get(name),\n      )\n    ) {\n      frontendSessionId = mintProvisionalSessionId();\n      sessionIdOrigin = \"backend\";\n    }\n  } catch {\n    frontendSessionId = undefined;\n    sessionIdOrigin = undefined;\n  }\n  const waitUntil = buildWaitUntil(ctx);\n  return {\n    mode: \"record\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    ...(sessionIdOrigin !== undefined ? { sessionIdOrigin } : {}),\n    transport,\n    buffer: new CaptureBuffer(transport, waitUntil),\n    traceId: randomHex(16),\n    serverSpanId: randomHex(8),\n    waitUntil,\n  };\n};\n\n/**\n * On by default: the render it attributes — the page's very first — is otherwise recorded\n * against no session at all, and the only thing that reaches a replay for those spans is\n * ingestion's time-window guess.\n *\n * Opting out is a worker var rather than a host environment variable for the same reason the\n * sidecar URL is: workerd cannot see the host's environment.\n */\nconst resolveMintProvisionalSessionIds = (\n  options: WithMeticulousOptions | undefined,\n  env: unknown,\n): boolean => {\n  if (options?.mintProvisionalSessionIds !== undefined) {\n    return options.mintProvisionalSessionIds;\n  }\n  const fromEnv =\n    env !== null && typeof env === \"object\"\n      ? (env as Record<string, unknown>)[\n          \"METICULOUS_BACKEND_PROVISIONAL_SESSION_IDS\"\n        ]\n      : undefined;\n  return fromEnv !== \"false\";\n};\n\nconst buildWaitUntil =\n  (ctx: MeticulousExecutionContext) =>\n  (promise: Promise<unknown>): void => {\n    try {\n      ctx.waitUntil(promise);\n    } catch (error) {\n      warnOnce(\n        \"wait-until\",\n        \"ctx.waitUntil failed — capture events may be lost.\",\n        error,\n      );\n    }\n  };\n"],"names":[],"mappings":"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","debugId":"ba3c57b0-dd6d-539f-8d4f-5cfae6c9afe1"}
+{"version":3,"file":"with-meticulous.js","sources":["../src/with-meticulous.ts"],"sourcesContent":["import { installBindingPatch } from \"./binding-patch\";\nimport { CaptureBuffer } from \"./capture-buffer\";\nimport {\n  type RequestCaptureContext,\n  type RequestReplayContext,\n  requestCaptureContext,\n} from \"./context\";\nimport { installFetchPatch } from \"./fetch-patch\";\nimport { installKvPatch } from \"./kv-patch\";\nimport { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport { headersToRecord } from \"./outbound-capture\";\nimport {\n  FRONTEND_SESSION_ID_HEADER,\n  type InboundRequestEvent,\n  REPLAY_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n} from \"./protocol\";\nimport {\n  isProvisionalSessionIdCandidate,\n  mintProvisionalSessionId,\n} from \"./provisional-session-id\";\nimport { publishSessionIdOnResponse } from \"./publish-session-id\";\nimport { parseReplaySidecarUrl } from \"./replay-sidecar-url\";\nimport { getReplaySessionInfo } from \"./sidecar-client\";\nimport {\n  resolveSidecarTransport,\n  type SidecarFetcher,\n  type SidecarTransport,\n} from \"./sidecar-transport\";\nimport { randomHex } from \"./spans/span-builder\";\nimport { installVirtualClock } from \"./virtual-clock\";\nimport { installVirtualRandom } from \"./virtual-random\";\n\n/** Structural subset of workerd's ExecutionContext — avoids a @cloudflare/workers-types dependency. */\nexport interface MeticulousExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\nexport interface WithMeticulousOptions {\n  /**\n   * Overrides the sidecar service binding; defaults to the `METICULOUS_SIDECAR` binding on\n   * `env`. This is how a **deployed** Worker records — see {@link SidecarTransport}.\n   */\n  sidecarBinding?: SidecarFetcher;\n  /** Overrides the sidecar origin; defaults to the METICULOUS_SIDECAR_URL var/binding. */\n  sidecarUrl?: string;\n  /**\n   * Binding names to leave unrecorded, on top of the defaults (`ASSETS`, `__STATIC_CONTENT`,\n   * `METICULOUS_SIDECAR`). Use this for a binding whose traffic is high-volume or binary. Applies\n   * to KV namespaces as well as `fetch`-shaped bindings.\n   */\n  skipBindings?: readonly string[];\n  /**\n   * Whether to mint a session id for a document navigation that carries none, so the\n   * server-side render is recorded under the same session as the page it produces. On by\n   * default; set `false` (or the `METICULOUS_BACKEND_PROVISIONAL_SESSION_IDS` var to\n   * `\"false\"`) to opt out. See provisional-session-id.ts.\n   */\n  mintProvisionalSessionIds?: boolean;\n}\n\n/** What the mode-agnostic core needs from whichever handler shape wraps it. */\nexport interface MeticulousInvocation {\n  request: Request;\n  env: unknown;\n  ctx: MeticulousExecutionContext;\n  invokeHandler: () => Response | Promise<Response>;\n}\n\n/**\n * Records, or replays, one inbound request. Shared by `withMeticulous` (an ES-module Worker's\n * `fetch`) and `withMeticulousPagesFunction` (a Pages Functions `onRequest`), which differ only\n * in how they get at the request, the env and `waitUntil`.\n */\nexport const runWithMeticulous = async (\n  { request, env, ctx, invokeHandler }: MeticulousInvocation,\n  options: WithMeticulousOptions | undefined,\n): Promise<Response> => {\n  let transport: SidecarTransport | undefined;\n  let replayContext: RequestReplayContext | undefined;\n  try {\n    replayContext = await resolveReplayContext(request, ctx);\n    transport =\n      replayContext === undefined\n        ? resolveSidecarTransport(options, env)\n        : undefined;\n    if (replayContext !== undefined || transport !== undefined) {\n      installFetchPatch();\n    }\n    if (transport !== undefined) {\n      // Lazily, inside the request path, and never at module scope: the package declares no\n      // `sideEffects` and is built with `platform: \"neutral\"`, so a module-scope side effect can\n      // legitimately be tree-shaken by a customer's bundler. Re-run per request because `env` is\n      // the only handle on the binding instances.\n      //\n      // Record mode only. Binding and KV calls are recorded as their own technologies\n      // (`workerd-binding`, `workerd-kv`) and the replay sidecar's store holds only\n      // `workerd-fetch` spans, so there is nothing to serve them from — and patching would only\n      // route them into the capture tee, which POSTs to an events route a replay sidecar 404s.\n      //\n      // `skipInstances` keeps the sidecar's own binding out of the recording by identity rather\n      // than by name, so it holds however the customer named it or passed it in.\n      const patchOptions = {\n        ...(options?.skipBindings !== undefined\n          ? { skipBindings: options.skipBindings }\n          : {}),\n        ...(transport.kind === \"binding\"\n          ? { skipInstances: [transport.instance] }\n          : {}),\n      };\n      installBindingPatch(env, patchOptions);\n      installKvPatch(env, patchOptions);\n    }\n  } catch (error) {\n    warnOnce(\n      \"shim-init\",\n      \"Failed to initialize the Meticulous backend recorder shim — recording disabled.\",\n      error,\n    );\n    replayContext = undefined;\n    transport = undefined;\n  }\n\n  if (replayContext !== undefined) {\n    // Install the clock before any app code runs, so a module that reads Date.now() at call time\n    // (the firebase auth libraries do) sees the session's frozen instant.\n    installVirtualClock();\n    // Likewise the random generators: an id the app mints during SSR (a guest id, a request id)\n    // otherwise differs between a base and a head replay, and every rendered page carrying it\n    // diffs forever.\n    installVirtualRandom();\n    // No inbound reporting in replay mode: there is no exporter behind the replay sidecar, and\n    // the events route 404s there.\n    return requestCaptureContext.run(replayContext, invokeHandler);\n  }\n\n  if (transport === undefined) {\n    return invokeHandler();\n  }\n\n  const captureCtx = buildCaptureContext(\n    request,\n    transport,\n    ctx,\n    resolveMintProvisionalSessionIds(options, env),\n  );\n  const mintedSessionId =\n    captureCtx.sessionIdOrigin === \"backend\"\n      ? captureCtx.frontendSessionId\n      : undefined;\n  const startTimeMs = Date.now();\n  let requestHeaders: Record<string, string[]> = {};\n  let method = \"GET\";\n  let url = \"\";\n  try {\n    requestHeaders = headersToRecord(request.headers);\n    method = request.method;\n    url = request.url;\n  } catch (error) {\n    warnOnce(\n      \"inbound-capture\",\n      \"Failed to capture the inbound request.\",\n      error,\n    );\n  }\n\n  const reportInbound = (\n    outcome:\n      | { statusCode: number; responseHeaders: Record<string, string[]> }\n      | { error: string },\n  ): void => {\n    try {\n      const event: InboundRequestEvent = {\n        kind: \"inbound\",\n        requestId: captureCtx.requestId,\n        ...(captureCtx.frontendSessionId !== undefined\n          ? { frontendSessionId: captureCtx.frontendSessionId }\n          : {}),\n        ...(captureCtx.sessionIdOrigin !== undefined\n          ? { sessionIdOrigin: captureCtx.sessionIdOrigin }\n          : {}),\n        traceId: captureCtx.traceId,\n        serverSpanId: captureCtx.serverSpanId,\n        method,\n        url,\n        requestHeaders,\n        startTimeMs,\n        endTimeMs: Date.now(),\n        ...outcome,\n      };\n      captureCtx.buffer.add(event);\n    } catch (error) {\n      warnOnce(\n        \"inbound-report\",\n        \"Failed to report the inbound request.\",\n        error,\n      );\n    }\n  };\n\n  let response: Response;\n  try {\n    response = await requestCaptureContext.run(captureCtx, invokeHandler);\n  } catch (error) {\n    reportInbound({ error: String(error) });\n    closeBuffer(captureCtx);\n    throw error;\n  }\n\n  // Ahead of reporting, so what we record as the response headers is what the browser is\n  // actually served.\n  if (mintedSessionId !== undefined) {\n    response = publishSessionIdOnResponse(response, mintedSessionId);\n  }\n\n  try {\n    reportInbound({\n      statusCode: response.status,\n      responseHeaders: headersToRecord(response.headers),\n    });\n  } catch (error) {\n    warnOnce(\"inbound-report\", \"Failed to report the inbound request.\", error);\n  }\n  closeBuffer(captureCtx);\n  return response;\n};\n\n/**\n * Hands the request's single report to `waitUntil`. `close()` drains the outstanding body reads\n * first, which is why there is one `waitUntil` per request rather than one per captured call.\n */\nconst closeBuffer = (ctx: RequestCaptureContext): void => {\n  try {\n    ctx.waitUntil(ctx.buffer.close());\n  } catch (error) {\n    warnOnce(\n      \"buffer-close\",\n      \"ctx.waitUntil failed — capture events may be lost.\",\n      error,\n    );\n  }\n};\n\n/**\n * Whether this request should be replayed, and the context to serve it under.\n *\n * Both replay identity ids and a usable sidecar URL must be present: mocks are indexed per session\n * and consumed per replay. The sidecar is consulted once per (sidecar, session) per isolate to\n * confirm it holds mocks and to learn the clock anchor — a sidecar that does not recognise the\n * session, or the route, means replay is unavailable and the request runs normally.\n */\nconst resolveReplayContext = async (\n  request: Request,\n  ctx: MeticulousExecutionContext,\n): Promise<RequestReplayContext | undefined> => {\n  let sidecarUrl: string | undefined;\n  let frontendSessionId: string | undefined;\n  let replayId: string | undefined;\n  try {\n    sidecarUrl = parseReplaySidecarUrl(\n      request.headers.get(REPLAY_SIDECAR_URL_HEADER),\n    );\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n    replayId = request.headers.get(REPLAY_ID_HEADER) ?? undefined;\n  } catch {\n    return undefined;\n  }\n  if (\n    sidecarUrl === undefined ||\n    frontendSessionId === undefined ||\n    replayId === undefined\n  ) {\n    return undefined;\n  }\n\n  const info = await getCachedReplaySessionInfo(sidecarUrl, frontendSessionId);\n  if (info === null) {\n    return undefined;\n  }\n\n  return {\n    mode: \"replay\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    replayId,\n    sidecarUrl,\n    clockAnchorMs: info.clockAnchorMs,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\n// Caches the promise, not the result, so concurrent first requests share one round trip.\n// Bounded so a stream of unrecognised session ids cannot grow it without limit.\nconst MAX_CACHED_SESSIONS = 50;\nconst replaySessionInfoCache = new Map<\n  string,\n  Promise<{ clockAnchorMs: number | undefined } | null>\n>();\n\nconst getCachedReplaySessionInfo = (\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<{ clockAnchorMs: number | undefined } | null> => {\n  const key = `${sidecarUrl}\u0000${frontendSessionId}`;\n  const cached = replaySessionInfoCache.get(key);\n  if (cached !== undefined) {\n    return cached;\n  }\n  const pending = getReplaySessionInfo(\n    getOriginalFetch(),\n    sidecarUrl,\n    frontendSessionId,\n  ).then((result) => {\n    if (result.outcome === \"unreachable\") {\n      // Only settled answers are worth keeping. Caching a timeout or transport blip would\n      // disable mocking for this session for the life of the isolate, quietly sending every\n      // later outbound call to the real service — the failure this path exists to prevent.\n      // Dropping the entry costs one extra handshake and lets the next request recover.\n      replaySessionInfoCache.delete(key);\n      return null;\n    }\n    return result.outcome === \"found\"\n      ? { clockAnchorMs: result.clockAnchorMs }\n      : null;\n  });\n  if (replaySessionInfoCache.size >= MAX_CACHED_SESSIONS) {\n    const oldest = replaySessionInfoCache.keys().next();\n    if (!oldest.done) {\n      replaySessionInfoCache.delete(oldest.value);\n    }\n  }\n  replaySessionInfoCache.set(key, pending);\n  return pending;\n};\n\nconst buildCaptureContext = (\n  request: Request,\n  transport: SidecarTransport,\n  ctx: MeticulousExecutionContext,\n  mintProvisionalSessionIds: boolean,\n): RequestCaptureContext => {\n  let frontendSessionId: string | undefined;\n  let sessionIdOrigin: \"backend\" | undefined;\n  try {\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n    // A top-level document navigation cannot carry the header, so for one we mint the id\n    // ourselves and hand it to the page on the response — otherwise the server-side render this\n    // request is about is recorded against no session at all. Every outbound, binding, KV and\n    // postgres event reads the id back off this context, so putting it here attributes the whole\n    // request. See provisional-session-id.ts.\n    if (\n      mintProvisionalSessionIds &&\n      frontendSessionId === undefined &&\n      isProvisionalSessionIdCandidate(request.method, (name) =>\n        request.headers.get(name),\n      )\n    ) {\n      frontendSessionId = mintProvisionalSessionId();\n      sessionIdOrigin = \"backend\";\n    }\n  } catch {\n    frontendSessionId = undefined;\n    sessionIdOrigin = undefined;\n  }\n  const waitUntil = buildWaitUntil(ctx);\n  return {\n    mode: \"record\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    ...(sessionIdOrigin !== undefined ? { sessionIdOrigin } : {}),\n    transport,\n    buffer: new CaptureBuffer(transport, waitUntil),\n    traceId: randomHex(16),\n    serverSpanId: randomHex(8),\n    waitUntil,\n  };\n};\n\n/**\n * On by default: the render it attributes — the page's very first — is otherwise recorded\n * against no session at all, and the only thing that reaches a replay for those spans is\n * ingestion's time-window guess.\n *\n * Opting out is a worker var rather than a host environment variable for the same reason the\n * sidecar URL is: workerd cannot see the host's environment.\n */\nconst resolveMintProvisionalSessionIds = (\n  options: WithMeticulousOptions | undefined,\n  env: unknown,\n): boolean => {\n  if (options?.mintProvisionalSessionIds !== undefined) {\n    return options.mintProvisionalSessionIds;\n  }\n  const fromEnv =\n    env !== null && typeof env === \"object\"\n      ? (env as Record<string, unknown>)[\n          \"METICULOUS_BACKEND_PROVISIONAL_SESSION_IDS\"\n        ]\n      : undefined;\n  return fromEnv !== \"false\";\n};\n\nconst buildWaitUntil =\n  (ctx: MeticulousExecutionContext) =>\n  (promise: Promise<unknown>): void => {\n    try {\n      ctx.waitUntil(promise);\n    } catch (error) {\n      warnOnce(\n        \"wait-until\",\n        \"ctx.waitUntil failed — capture events may be lost.\",\n        error,\n      );\n    }\n  };\n"],"names":[],"mappings":"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","debugId":"368123ce-5f9f-5b9d-84b5-9dd72fe3f35d"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/backend-recorder-workerd",
-  "version": "2.326.0",
+  "version": "2.327.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",