@alwaysmeticulous/backend-recorder-workerd 2.325.0 → 2.326.0

package/dist/index.d.ts

@@ -1,28 +1,26 @@
-import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
+import { SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_URL_ENV_KEY, SidecarFetcher, SidecarTransport } from "./sidecar-transport.js";
+import { MeticulousExecutionContext, WithMeticulousOptions } from "./with-meticulous.js";
+import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
 import { MAX_BODY_CAPTURE_SIZE, readBodyWithCap, readRequestBodyWithCap } from "./body-capture.js";
 import { headersToRecord } from "./outbound-capture.js";
 import { STR_REDACTED, redactRequestBody } from "./redact-body.js";
+import { MeticulousPagesFunction, MeticulousPagesFunctionContext, withMeticulousPagesFunction } from "./pages-function.js";
 import { KvCaptureFields, KvCaptureOutcome, serializeKvArgs, serializeKvCaptureFields } from "./kv-capture.js";
+import { deserializeCapturedError, serializeCapturedError } from "./error-capture.js";
+import { MAX_POSTGRES_JS_RESULT_SIZE, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, PostgresJsQueryLike, PostgresJsRowMode, isSupportedPostgresJsQuery, postgresJsCommandOf, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult } from "./postgres/capture.js";
+import { withMeticulousPostgres } from "./postgres/with-meticulous-postgres.js";
+import { CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR } from "./spans/attributes.js";
+import { HrTime, ReadableSpan, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, SerializedSpanBase, SpanStatus, hrTimeToMs, msToHrTime } from "./spans/readable-span.js";
+import { serializeSpan } from "./spans/serialize-span.js";
+import { SpanBuilder, randomHex } from "./spans/span-builder.js";
+import { redactUrlCredentials } from "./spans/url-redaction.js";
+import { HeaderReader, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, buildServerTimingSessionEntry, isProvisionalSessionIdCandidate, mintProvisionalSessionId } from "./provisional-session-id.js";
 
 //#region src/index.d.ts
-/** Structural subset of workerd's ExecutionContext — avoids a @cloudflare/workers-types dependency. */
-interface MeticulousExecutionContext {
-  waitUntil(promise: Promise<unknown>): void;
-}
 /** Structural subset of an ES-module Worker handler (`export default {...}`). */
 interface MeticulousWorkerHandler<Env = never> {
   fetch(request: Request, env: Env, ctx: MeticulousExecutionContext): Response | Promise<Response>;
 }
-interface WithMeticulousOptions {
-  /** Overrides the sidecar origin; defaults to the METICULOUS_SIDECAR_URL var/binding. */
-  sidecarUrl?: string;
-  /**
-   * Binding names to leave unrecorded, on top of the defaults (`ASSETS`,
-   * `__STATIC_CONTENT`). Use this for a binding whose traffic is high-volume or binary.
-   * Applies to KV namespaces as well as `fetch`-shaped bindings.
-   */
-  skipBindings?: readonly string[];
-}
 /**
  * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP
  * behaviour:
@@ -31,33 +29,58 @@ interface WithMeticulousOptions {
  *     async fetch(request, env, ctx) { ... },
  *   });
  *
- * **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`
- * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests, outgoing `fetch`
- * calls, calls through `fetch`-shaped bindings and KV namespace operations are reported to
- * the sidecar as capture events, without affecting the app.
- *
- * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by
- * the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are
- * then served from the recording instead of reaching the real service — and a call the
- * recording does not cover fails, rather than quietly becoming live traffic; put a
- * `meticulous-passthrough: true` header on a request that must stay real. The clock is frozen
- * at the recorded session's end so recorded credentials are still valid, and `Math.random` /
- * `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are the same
- * in every replay of that session. Workerd
- * cannot read container environment variables, which is why per-replay config arrives as a
- * request header; the shim validates it and only honours a loopback / docker-gateway /
- * private-network `http:` origin.
- *
- * Replay takes precedence over recording when both are configured. A stale
- * `METICULOUS_SIDECAR_URL` baked into an image's `.dev.vars` is far more likely than a
- * spurious replay header (nothing but the replay runner emits it), and letting the env win
- * would silently record a replay instead of mocking it.
+ * For a Cloudflare Pages project, whose worker exports `onRequest` instead, use
+ * {@link withMeticulousPagesFunction} — same behaviour, different handler shape.
+ *
+ * **Recording** activates on either a `METICULOUS_SIDECAR` service binding (how a **deployed**
+ * Worker records: the binding points at a Meticulous recorder sidecar Worker in the same account)
+ * or a `METICULOUS_SIDECAR_URL` var (how `wrangler dev` records against a local sidecar process),
+ * or the matching `options`. Inbound requests, outgoing `fetch` calls, calls through
+ * `fetch`-shaped bindings, KV namespace operations and — with `withMeticulousPostgres` — postgres.js
+ * queries are reported to the sidecar, batched into one report per request, without affecting the
+ * app. A binding beats a var if both are configured: only the binding can have been added to
+ * *this* deployment's wrangler configuration deliberately, whereas a stale `.dev.vars` travels
+ * with an image.
+ *
+ * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by the
+ * Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are then
+ * served from the recording instead of reaching the real service — and a call the recording does
+ * not cover fails, rather than quietly becoming live traffic; put a `meticulous-passthrough: true`
+ * header on a request that must stay real. The clock is frozen at the recorded session's end so
+ * recorded credentials are still valid, and `Math.random` / `crypto.randomUUID` /
+ * `crypto.getRandomValues` are seeded so ids the app mints are the same in every replay of that
+ * session. Workerd cannot read container environment variables, which is why per-replay config
+ * arrives as a request header; the shim validates it and only honours a loopback /
+ * docker-gateway / private-network `http:` origin.
+ *
+ * Replay takes precedence over recording when both are configured. A stale sidecar var baked into
+ * an image is far more likely than a spurious replay header (nothing but the replay runner emits
+ * one), and letting the env win would silently record a replay instead of mocking it.
  *
  * With neither configured the wrapper is a complete pass-through, so it is safe to keep in
- * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A
- * capture failure or unreachable sidecar never affects the app.
+ * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A capture
+ * failure or unreachable sidecar never affects the app.
  */
 declare const withMeticulous: <H extends MeticulousWorkerHandler<never>>(handler: H, options?: WithMeticulousOptions) => H;
+/**
+ * The Meticulous session id of the request currently being served, or `undefined` if this
+ * call cannot be tied to one — including whenever the wrapper is a pass-through.
+ *
+ * Exposed so a server-rendering worker can put the id into the HTML it is about to return,
+ * typically as `data-session-id` on the recorder's own `<script>` tag. That is the exact,
+ * cache-proof alternative to the `Server-Timing` header the shim publishes automatically;
+ * doing both is fine, since the recorder prefers the rendered value. It is also how the id
+ * reaches another process — a document navigation has no inbound header for the app to
+ * forward, so a worker that fans out to its own services has to pass this on as
+ * `x-meticulous-session-id` itself.
+ *
+ * During a replay this returns the replayed session's id, which is the same value the render
+ * being replayed was given when it was recorded (the page adopted the minted id, so that is
+ * what the recording is stored under, and it is what the replay runner injects back). An app
+ * that renders the id therefore renders the same bytes both times, rather than the id turning
+ * every server-rendered page into a diff.
+ */
+declare const getMeticulousSessionId: () => string | undefined;
 //#endregion
-export { type BindingRequestEvent, CAPTURED_HEADERS, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, FRONTEND_SESSION_ID_HEADER, type InboundRequestEvent, type KvCaptureFields, type KvCaptureOutcome, type KvOmittedReason, type KvOperation, type KvOperationEvent, MAX_BODY_CAPTURE_SIZE, METICULOUS_PASSTHROUGH_HEADER, MeticulousExecutionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, type ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, STR_REDACTED, WithMeticulousOptions, headersToRecord, readBodyWithCap, readRequestBodyWithCap, redactRequestBody, serializeKvArgs, serializeKvCaptureFields, withMeticulous };
+export { type BindingRequestEvent, CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, type HeaderReader, type HrTime, type InboundRequestEvent, type KvCaptureFields, type KvCaptureOutcome, type KvOmittedReason, type KvOperation, type KvOperationEvent, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, type MeticulousExecutionContext, type MeticulousPagesFunction, type MeticulousPagesFunctionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, type PostgresJsQueryLike, type PostgresJsRowMode, type PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, type ReadableSpan, type ReplaySessionInfoResponse, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, type SerializedSpanBase, type SidecarFetcher, type SidecarTransport, SpanBuilder, type SpanStatus, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, type WithMeticulousOptions, buildServerTimingSessionEntry, deserializeCapturedError, getMeticulousSessionId, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,23 @@
 
-!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]="fc6d90d7-9399-56bc-9c2a-5135d61580c8")}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]="f420c8b0-634e-586e-b9bf-34d3afde7944")}catch(e){}}();
+import { SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_URL_ENV_KEY } from "./sidecar-transport.js";
 import { requestCaptureContext } from "./context.js";
-import { warnOnce } from "./log.js";
 import { STR_REDACTED, redactRequestBody } from "./redact-body.js";
 import { MAX_BODY_CAPTURE_SIZE, readBodyWithCap, readRequestBodyWithCap } from "./body-capture.js";
-import { getOriginalFetch } from "./original-fetch.js";
-import { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, METICULOUS_PASSTHROUGH_HEADER, REPLAY_SIDECAR_URL_HEADER, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
-import { getReplaySessionInfo, postCaptureEvents } from "./sidecar-client.js";
+import { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, METICULOUS_PASSTHROUGH_HEADER, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
 import { headersToRecord } from "./outbound-capture.js";
-import { installBindingPatch } from "./binding-patch.js";
-import { installFetchPatch } from "./fetch-patch.js";
 import { serializeKvArgs, serializeKvCaptureFields } from "./kv-capture.js";
-import { installKvPatch } from "./kv-patch.js";
-import { parseReplaySidecarUrl } from "./replay-sidecar-url.js";
-import { installVirtualClock } from "./virtual-clock.js";
-import { installVirtualRandom } from "./virtual-random.js";
+import { SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, buildServerTimingSessionEntry, isProvisionalSessionIdCandidate, mintProvisionalSessionId } from "./provisional-session-id.js";
+import { deserializeCapturedError, serializeCapturedError } from "./error-capture.js";
+import { MAX_POSTGRES_JS_RESULT_SIZE, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, isSupportedPostgresJsQuery, postgresJsCommandOf, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult } from "./postgres/capture.js";
+import { CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR } from "./spans/attributes.js";
+import { SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, hrTimeToMs, msToHrTime } from "./spans/readable-span.js";
+import { redactUrlCredentials } from "./spans/url-redaction.js";
+import { SpanBuilder, randomHex } from "./spans/span-builder.js";
+import { runWithMeticulous } from "./with-meticulous.js";
+import { withMeticulousPagesFunction } from "./pages-function.js";
+import { withMeticulousPostgres } from "./postgres/with-meticulous-postgres.js";
+import { serializeSpan } from "./spans/serialize-span.js";
 //#region src/index.ts
 /**
 * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP
@@ -24,188 +27,71 @@ import { installVirtualRandom } from "./virtual-random.js";
 *     async fetch(request, env, ctx) { ... },
 *   });
 *
-* **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`
-* or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests, outgoing `fetch`
-* calls, calls through `fetch`-shaped bindings and KV namespace operations are reported to
-* the sidecar as capture events, without affecting the app.
+* For a Cloudflare Pages project, whose worker exports `onRequest` instead, use
+* {@link withMeticulousPagesFunction} — same behaviour, different handler shape.
 *
-* **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by
-* the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are
-* then served from the recording instead of reaching the real service — and a call the
-* recording does not cover fails, rather than quietly becoming live traffic; put a
-* `meticulous-passthrough: true` header on a request that must stay real. The clock is frozen
-* at the recorded session's end so recorded credentials are still valid, and `Math.random` /
-* `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are the same
-* in every replay of that session. Workerd
-* cannot read container environment variables, which is why per-replay config arrives as a
-* request header; the shim validates it and only honours a loopback / docker-gateway /
-* private-network `http:` origin.
+* **Recording** activates on either a `METICULOUS_SIDECAR` service binding (how a **deployed**
+* Worker records: the binding points at a Meticulous recorder sidecar Worker in the same account)
+* or a `METICULOUS_SIDECAR_URL` var (how `wrangler dev` records against a local sidecar process),
+* or the matching `options`. Inbound requests, outgoing `fetch` calls, calls through
+* `fetch`-shaped bindings, KV namespace operations and — with `withMeticulousPostgres` — postgres.js
+* queries are reported to the sidecar, batched into one report per request, without affecting the
+* app. A binding beats a var if both are configured: only the binding can have been added to
+* *this* deployment's wrangler configuration deliberately, whereas a stale `.dev.vars` travels
+* with an image.
 *
-* Replay takes precedence over recording when both are configured. A stale
-* `METICULOUS_SIDECAR_URL` baked into an image's `.dev.vars` is far more likely than a
-* spurious replay header (nothing but the replay runner emits it), and letting the env win
-* would silently record a replay instead of mocking it.
+* **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by the
+* Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are then
+* served from the recording instead of reaching the real service — and a call the recording does
+* not cover fails, rather than quietly becoming live traffic; put a `meticulous-passthrough: true`
+* header on a request that must stay real. The clock is frozen at the recorded session's end so
+* recorded credentials are still valid, and `Math.random` / `crypto.randomUUID` /
+* `crypto.getRandomValues` are seeded so ids the app mints are the same in every replay of that
+* session. Workerd cannot read container environment variables, which is why per-replay config
+* arrives as a request header; the shim validates it and only honours a loopback /
+* docker-gateway / private-network `http:` origin.
+*
+* Replay takes precedence over recording when both are configured. A stale sidecar var baked into
+* an image is far more likely than a spurious replay header (nothing but the replay runner emits
+* one), and letting the env win would silently record a replay instead of mocking it.
 *
 * With neither configured the wrapper is a complete pass-through, so it is safe to keep in
-* deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A
-* capture failure or unreachable sidecar never affects the app.
+* deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A capture
+* failure or unreachable sidecar never affects the app.
 */
 const withMeticulous = (handler, options) => {
-	const wrappedFetch = async (request, env, ctx) => {
-		const invokeHandler = () => handler.fetch(request, env, ctx);
-		let sidecarUrl;
-		let replayContext;
-		try {
-			replayContext = await resolveReplayContext(request, ctx);
-			sidecarUrl = replayContext === void 0 ? resolveSidecarUrl(options, env) : void 0;
-			if (replayContext !== void 0 || sidecarUrl !== void 0) installFetchPatch();
-			if (sidecarUrl !== void 0) {
-				installBindingPatch(env, { skipBindings: options?.skipBindings });
-				installKvPatch(env, { skipBindings: options?.skipBindings });
-			}
-		} catch (error) {
-			warnOnce("shim-init", "Failed to initialize the Meticulous backend recorder shim — recording disabled.", error);
-			replayContext = void 0;
-			sidecarUrl = void 0;
-		}
-		if (replayContext !== void 0) {
-			installVirtualClock();
-			installVirtualRandom();
-			return requestCaptureContext.run(replayContext, invokeHandler);
-		}
-		if (sidecarUrl === void 0) return invokeHandler();
-		const captureCtx = buildCaptureContext(request, sidecarUrl, ctx);
-		const startTimeMs = Date.now();
-		let requestHeaders = {};
-		let method = "GET";
-		let url = "";
-		try {
-			requestHeaders = headersToRecord(request.headers);
-			method = request.method;
-			url = request.url;
-		} catch (error) {
-			warnOnce("inbound-capture", "Failed to capture the inbound request.", error);
-		}
-		const reportInbound = (outcome) => {
-			try {
-				const event = {
-					kind: "inbound",
-					requestId: captureCtx.requestId,
-					...captureCtx.frontendSessionId !== void 0 ? { frontendSessionId: captureCtx.frontendSessionId } : {},
-					method,
-					url,
-					requestHeaders,
-					startTimeMs,
-					endTimeMs: Date.now(),
-					...outcome
-				};
-				captureCtx.waitUntil(postCaptureEvents(getOriginalFetch(), sidecarUrl, [event]));
-			} catch (error) {
-				warnOnce("inbound-report", "Failed to report the inbound request.", error);
-			}
-		};
-		let response;
-		try {
-			response = await requestCaptureContext.run(captureCtx, invokeHandler);
-		} catch (error) {
-			reportInbound({ error: String(error) });
-			throw error;
-		}
-		try {
-			reportInbound({
-				statusCode: response.status,
-				responseHeaders: headersToRecord(response.headers)
-			});
-		} catch (error) {
-			warnOnce("inbound-report", "Failed to report the inbound request.", error);
-		}
-		return response;
-	};
+	const wrappedFetch = (request, env, ctx) => runWithMeticulous({
+		request,
+		env,
+		ctx,
+		invokeHandler: () => handler.fetch(request, env, ctx)
+	}, options);
 	return {
 		...handler,
 		fetch: wrappedFetch
 	};
 };
 /**
-* Whether this request should be replayed, and the context to serve it under.
+* The Meticulous session id of the request currently being served, or `undefined` if this
+* call cannot be tied to one — including whenever the wrapper is a pass-through.
+*
+* Exposed so a server-rendering worker can put the id into the HTML it is about to return,
+* typically as `data-session-id` on the recorder's own `<script>` tag. That is the exact,
+* cache-proof alternative to the `Server-Timing` header the shim publishes automatically;
+* doing both is fine, since the recorder prefers the rendered value. It is also how the id
+* reaches another process — a document navigation has no inbound header for the app to
+* forward, so a worker that fans out to its own services has to pass this on as
+* `x-meticulous-session-id` itself.
 *
-* Both the session id and a usable sidecar URL must be present: mocks are indexed per
-* session, so replay without a session id could only miss. The sidecar is consulted once
-* per (sidecar, session) per isolate to confirm it holds mocks and to learn the clock
-* anchor — a sidecar that does not recognise the session, or the route, means replay is
-* unavailable and the request runs normally.
+* During a replay this returns the replayed session's id, which is the same value the render
+* being replayed was given when it was recorded (the page adopted the minted id, so that is
+* what the recording is stored under, and it is what the replay runner injects back). An app
+* that renders the id therefore renders the same bytes both times, rather than the id turning
+* every server-rendered page into a diff.
 */
-const resolveReplayContext = async (request, ctx) => {
-	let sidecarUrl;
-	let frontendSessionId;
-	try {
-		sidecarUrl = parseReplaySidecarUrl(request.headers.get(REPLAY_SIDECAR_URL_HEADER));
-		frontendSessionId = request.headers.get("x-meticulous-session-id") ?? void 0;
-	} catch {
-		return;
-	}
-	if (sidecarUrl === void 0 || frontendSessionId === void 0) return;
-	const info = await getCachedReplaySessionInfo(sidecarUrl, frontendSessionId);
-	if (info === null) return;
-	return {
-		mode: "replay",
-		requestId: crypto.randomUUID(),
-		frontendSessionId,
-		sidecarUrl,
-		clockAnchorMs: info.clockAnchorMs,
-		waitUntil: buildWaitUntil(ctx)
-	};
-};
-const MAX_CACHED_SESSIONS = 50;
-const replaySessionInfoCache = /* @__PURE__ */ new Map();
-const getCachedReplaySessionInfo = (sidecarUrl, frontendSessionId) => {
-	const key = `${sidecarUrl}\u0000${frontendSessionId}`;
-	const cached = replaySessionInfoCache.get(key);
-	if (cached !== void 0) return cached;
-	const pending = getReplaySessionInfo(getOriginalFetch(), sidecarUrl, frontendSessionId).then((result) => {
-		if (result.outcome === "unreachable") {
-			replaySessionInfoCache.delete(key);
-			return null;
-		}
-		return result.outcome === "found" ? { clockAnchorMs: result.clockAnchorMs } : null;
-	});
-	if (replaySessionInfoCache.size >= MAX_CACHED_SESSIONS) {
-		const oldest = replaySessionInfoCache.keys().next();
-		if (!oldest.done) replaySessionInfoCache.delete(oldest.value);
-	}
-	replaySessionInfoCache.set(key, pending);
-	return pending;
-};
-const resolveSidecarUrl = (options, env) => {
-	const fromEnv = env !== null && typeof env === "object" ? env["METICULOUS_SIDECAR_URL"] : void 0;
-	const raw = options?.sidecarUrl ?? fromEnv;
-	if (typeof raw !== "string" || raw.length === 0) return;
-	return raw.replace(/\/+$/, "");
-};
-const buildCaptureContext = (request, sidecarUrl, ctx) => {
-	let frontendSessionId;
-	try {
-		frontendSessionId = request.headers.get("x-meticulous-session-id") ?? void 0;
-	} catch {
-		frontendSessionId = void 0;
-	}
-	return {
-		mode: "record",
-		requestId: crypto.randomUUID(),
-		frontendSessionId,
-		sidecarUrl,
-		waitUntil: buildWaitUntil(ctx)
-	};
-};
-const buildWaitUntil = (ctx) => (promise) => {
-	try {
-		ctx.waitUntil(promise);
-	} catch (error) {
-		warnOnce("wait-until", "ctx.waitUntil failed — capture events may be lost.", error);
-	}
-};
+const getMeticulousSessionId = () => requestCaptureContext.getStore()?.frontendSessionId;
 //#endregion
-export { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, MAX_BODY_CAPTURE_SIZE, METICULOUS_PASSTHROUGH_HEADER, REPLAY_SIDECAR_URL_HEADER, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, STR_REDACTED, headersToRecord, readBodyWithCap, readRequestBodyWithCap, redactRequestBody, serializeKvArgs, serializeKvCaptureFields, withMeticulous };
+export { CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, SpanBuilder, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, buildServerTimingSessionEntry, deserializeCapturedError, getMeticulousSessionId, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
 
 //# sourceMappingURL=index.js.map
-//# debugId=fc6d90d7-9399-56bc-9c2a-5135d61580c8
+//# debugId=f420c8b0-634e-586e-b9bf-34d3afde7944

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { installBindingPatch } from \"./binding-patch\";\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_SIDECAR_URL_HEADER,\n} from \"./protocol\";\nimport { parseReplaySidecarUrl } from \"./replay-sidecar-url\";\nimport { getReplaySessionInfo, postCaptureEvents } from \"./sidecar-client\";\nimport { installVirtualClock } from \"./virtual-clock\";\nimport { installVirtualRandom } from \"./virtual-random\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  InboundRequestEvent,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  METICULOUS_PASSTHROUGH_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\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\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\n/**\n * Exported for the Node recorder's `withMeticulousCloudflareEnv`, which records the same KV\n * operations from a process whose bindings come from wrangler's `getPlatformProxy`. Both\n * surfaces must produce identical fields, so the contract has exactly one implementation.\n */\nexport {\n  type KvCaptureFields,\n  type KvCaptureOutcome,\n  serializeKvArgs,\n  serializeKvCaptureFields,\n} from \"./kv-capture\";\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\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\nexport interface WithMeticulousOptions {\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`,\n   * `__STATIC_CONTENT`). Use this for a binding whose traffic is high-volume or binary.\n   * Applies to KV namespaces as well as `fetch`-shaped bindings.\n   */\n  skipBindings?: readonly string[];\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`\n * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests, outgoing `fetch`\n * calls, calls through `fetch`-shaped bindings and KV namespace operations are reported to\n * the sidecar as capture events, without affecting the app.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by\n * the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are\n * then served from the recording instead of reaching the real service — and a call the\n * recording does not cover fails, rather than quietly becoming live traffic; put a\n * `meticulous-passthrough: true` header on a request that must stay real. The clock is frozen\n * at the recorded session's end so recorded credentials are still valid, and `Math.random` /\n * `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are the same\n * in every replay of that session. Workerd\n * cannot read container environment variables, which is why per-replay config arrives as a\n * request header; the shim validates it and only honours a loopback / docker-gateway /\n * private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale\n * `METICULOUS_SIDECAR_URL` baked into an image's `.dev.vars` is far more likely than a\n * spurious replay header (nothing but the replay runner emits it), and letting the env win\n * would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A\n * capture failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = async (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> => {\n    const invokeHandler = () => handler.fetch(request, env as never, ctx);\n\n    let sidecarUrl: string | undefined;\n    let replayContext: RequestReplayContext | undefined;\n    try {\n      replayContext = await resolveReplayContext(request, ctx);\n      sidecarUrl =\n        replayContext === undefined\n          ? resolveSidecarUrl(options, env)\n          : undefined;\n      if (replayContext !== undefined || sidecarUrl !== undefined) {\n        installFetchPatch();\n      }\n      if (sidecarUrl !== undefined) {\n        // Lazily, inside the request path, and never at module scope: the package declares\n        // no `sideEffects` and is built with `platform: \"neutral\"`, so a module-scope side\n        // effect can legitimately be tree-shaken by a customer's bundler. Re-run per\n        // request because `env` is 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\n        // only route them into the capture tee, which POSTs to an events route a replay\n        // sidecar 404s.\n        installBindingPatch(env, { skipBindings: options?.skipBindings });\n        installKvPatch(env, { skipBindings: options?.skipBindings });\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      sidecarUrl = undefined;\n    }\n\n    if (replayContext !== undefined) {\n      // Install the clock before any app code runs, so a module that reads Date.now() at\n      // call time (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\n      // request id) otherwise differs between a base and a head replay, and every rendered\n      // page carrying it diffs forever.\n      installVirtualRandom();\n      // No inbound reporting in replay mode: there is no exporter behind the replay\n      // sidecar, and the events route 404s there.\n      return requestCaptureContext.run(replayContext, invokeHandler);\n    }\n\n    if (sidecarUrl === undefined) {\n      return invokeHandler();\n    }\n\n    const captureCtx = buildCaptureContext(request, sidecarUrl, ctx);\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          method,\n          url,\n          requestHeaders,\n          startTimeMs,\n          endTimeMs: Date.now(),\n          ...outcome,\n        };\n        captureCtx.waitUntil(\n          postCaptureEvents(getOriginalFetch(), sidecarUrl, [event]),\n        );\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      throw error;\n    }\n\n    try {\n      reportInbound({\n        statusCode: response.status,\n        responseHeaders: headersToRecord(response.headers),\n      });\n    } catch (error) {\n      warnOnce(\n        \"inbound-report\",\n        \"Failed to report the inbound request.\",\n        error,\n      );\n    }\n    return response;\n  };\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript\n  // cannot verify a spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * Whether this request should be replayed, and the context to serve it under.\n *\n * Both the session id and a usable sidecar URL must be present: mocks are indexed per\n * session, so replay without a session id could only miss. The sidecar is consulted once\n * per (sidecar, session) per isolate to confirm it holds mocks and to learn the clock\n * anchor — a sidecar that does not recognise the session, or the route, means replay is\n * 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  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  } catch {\n    return undefined;\n  }\n  if (sidecarUrl === undefined || frontendSessionId === undefined) {\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    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 resolveSidecarUrl = (\n  options: WithMeticulousOptions | undefined,\n  env: unknown,\n): string | undefined => {\n  const fromEnv =\n    env !== null && typeof env === \"object\"\n      ? (env as Record<string, unknown>)[\"METICULOUS_SIDECAR_URL\"]\n      : undefined;\n  const raw = options?.sidecarUrl ?? fromEnv;\n  if (typeof raw !== \"string\" || raw.length === 0) {\n    return undefined;\n  }\n  return raw.replace(/\\/+$/, \"\");\n};\n\nconst buildCaptureContext = (\n  request: Request,\n  sidecarUrl: string,\n  ctx: MeticulousExecutionContext,\n): RequestCaptureContext => {\n  let frontendSessionId: string | undefined;\n  try {\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n  } catch {\n    frontendSessionId = undefined;\n  }\n  return {\n    mode: \"record\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    sidecarUrl,\n    waitUntil: buildWaitUntil(ctx),\n  };\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":"fc6d90d7-9399-56bc-9c2a-5135d61580c8"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport {\n  type MeticulousExecutionContext,\n  runWithMeticulous,\n  type WithMeticulousOptions,\n} from \"./with-meticulous\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  InboundRequestEvent,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  PostgresQueryEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  METICULOUS_PASSTHROUGH_HEADER,\n  REPLAY_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\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\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\nexport type { MeticulousExecutionContext, WithMeticulousOptions };\nexport {\n  type MeticulousPagesFunction,\n  type MeticulousPagesFunctionContext,\n  withMeticulousPagesFunction,\n} from \"./pages-function\";\nexport {\n  SIDECAR_BINDING_ENV_KEY,\n  SIDECAR_BINDING_ORIGIN,\n  SIDECAR_URL_ENV_KEY,\n  type SidecarFetcher,\n  type SidecarTransport,\n} from \"./sidecar-transport\";\n/**\n * Exported for the Node recorder's `withMeticulousCloudflareEnv`, which records the same KV\n * operations from a process whose bindings come from wrangler's `getPlatformProxy`. Both surfaces\n * must produce identical fields, so the contract has exactly one implementation.\n */\nexport {\n  type KvCaptureFields,\n  type KvCaptureOutcome,\n  serializeKvArgs,\n  serializeKvCaptureFields,\n} from \"./kv-capture\";\n/**\n * Exported for the same reason: the Node recorder re-exports these so a postgres.js query, a\n * captured error and a built span are byte-identical whichever surface produced them. A\n * Worker-hosted sidecar needs them too, and cannot load the Node bundle.\n */\nexport {\n  deserializeCapturedError,\n  serializeCapturedError,\n} from \"./error-capture\";\nexport {\n  isSupportedPostgresJsQuery,\n  MAX_POSTGRES_JS_RESULT_SIZE,\n  POSTGRES_JS_ERROR_ATTR,\n  POSTGRES_JS_QUERY_PARAMS_ATTR,\n  POSTGRES_JS_QUERY_TEXT_ATTR,\n  POSTGRES_JS_RESULT_ATTR,\n  POSTGRES_JS_RESULT_TRUNCATED_ATTR,\n  POSTGRES_JS_ROW_MODE_ATTR,\n  postgresJsCommandOf,\n  type PostgresJsQueryLike,\n  type PostgresJsRowMode,\n  reconstructQueryText,\n  resolveRowMode,\n  serializePostgresJsArgs,\n  serializePostgresJsError,\n  serializePostgresJsResult,\n} from \"./postgres/capture\";\nexport { withMeticulousPostgres } from \"./postgres/with-meticulous-postgres\";\nexport * from \"./spans/attributes\";\nexport {\n  hrTimeToMs,\n  msToHrTime,\n  type HrTime,\n  type ReadableSpan,\n  type SerializedSpanBase,\n  SPAN_KIND_CLIENT,\n  SPAN_KIND_INTERNAL,\n  SPAN_KIND_SERVER,\n  SPAN_STATUS_ERROR,\n  SPAN_STATUS_OK,\n  SPAN_STATUS_UNSET,\n  type SpanStatus,\n} from \"./spans/readable-span\";\nexport { serializeSpan } from \"./spans/serialize-span\";\nexport { randomHex, SpanBuilder } from \"./spans/span-builder\";\nexport { redactUrlCredentials } from \"./spans/url-redaction\";\n/**\n * Exported for the Node recorder, whose own `provisional-session-id.ts` adapts these to\n * `http.IncomingMessage` / `http.ServerResponse`. The mint format, the rule for which requests\n * get an id and the `Server-Timing` metric are all wire contracts with the page, so — as with\n * the KV capture fields above — they have exactly one implementation.\n */\nexport {\n  type HeaderReader,\n  SERVER_TIMING_HEADER,\n  SERVER_TIMING_SESSION_METRIC,\n  buildServerTimingSessionEntry,\n  isProvisionalSessionIdCandidate,\n  mintProvisionalSessionId,\n} from \"./provisional-session-id\";\n\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * For a Cloudflare Pages project, whose worker exports `onRequest` instead, use\n * {@link withMeticulousPagesFunction} — same behaviour, different handler shape.\n *\n * **Recording** activates on either a `METICULOUS_SIDECAR` service binding (how a **deployed**\n * Worker records: the binding points at a Meticulous recorder sidecar Worker in the same account)\n * or a `METICULOUS_SIDECAR_URL` var (how `wrangler dev` records against a local sidecar process),\n * or the matching `options`. Inbound requests, outgoing `fetch` calls, calls through\n * `fetch`-shaped bindings, KV namespace operations and — with `withMeticulousPostgres` — postgres.js\n * queries are reported to the sidecar, batched into one report per request, without affecting the\n * app. A binding beats a var if both are configured: only the binding can have been added to\n * *this* deployment's wrangler configuration deliberately, whereas a stale `.dev.vars` travels\n * with an image.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by the\n * Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are then\n * served from the recording instead of reaching the real service — and a call the recording does\n * not cover fails, rather than quietly becoming live traffic; put a `meticulous-passthrough: true`\n * header on a request that must stay real. The clock is frozen at the recorded session's end so\n * recorded credentials are still valid, and `Math.random` / `crypto.randomUUID` /\n * `crypto.getRandomValues` are seeded so ids the app mints are the same in every replay of that\n * session. Workerd cannot read container environment variables, which is why per-replay config\n * arrives as a request header; the shim validates it and only honours a loopback /\n * docker-gateway / private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale sidecar var baked into\n * an image is far more likely than a spurious replay header (nothing but the replay runner emits\n * one), and letting the env win would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A capture\n * failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> =>\n    runWithMeticulous(\n      {\n        request,\n        env,\n        ctx,\n        invokeHandler: () => handler.fetch(request, env as never, ctx),\n      },\n      options,\n    );\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript cannot verify a\n  // spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * The Meticulous session id of the request currently being served, or `undefined` if this\n * call cannot be tied to one — including whenever the wrapper is a pass-through.\n *\n * Exposed so a server-rendering worker can put the id into the HTML it is about to return,\n * typically as `data-session-id` on the recorder's own `<script>` tag. That is the exact,\n * cache-proof alternative to the `Server-Timing` header the shim publishes automatically;\n * doing both is fine, since the recorder prefers the rendered value. It is also how the id\n * reaches another process — a document navigation has no inbound header for the app to\n * forward, so a worker that fans out to its own services has to pass this on as\n * `x-meticulous-session-id` itself.\n *\n * During a replay this returns the replayed session's id, which is the same value the render\n * being replayed was given when it was recorded (the page adopted the minted id, so that is\n * what the recording is stored under, and it is what the replay runner injects back). An app\n * that renders the id therefore renders the same bytes both times, rather than the id turning\n * every server-rendered page into a diff.\n */\nexport const getMeticulousSessionId = (): string | undefined =>\n  requestCaptureContext.getStore()?.frontendSessionId;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+KA,MAAa,kBACX,SACA,YACM;CACN,MAAM,gBACJ,SACA,KACA,QAEA,kBACE;EACE;EACA;EACA;EACA,qBAAqB,QAAQ,MAAM,SAAS,KAAc,IAAI;EAC/D,EACD,QACD;AAIH,QAAO;EAAE,GAAG;EAAS,OAAO;EAAc;;;;;;;;;;;;;;;;;;;;AAqB5C,MAAa,+BACX,sBAAsB,UAAU,EAAE","debugId":"f420c8b0-634e-586e-b9bf-34d3afde7944"}

package/dist/kv-patch.js

@@ -1,9 +1,7 @@
 
-!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]="b871e5bd-a858-5783-9618-2ec0bd2a52bf")}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]="303b51b3-97aa-5dde-9000-ea94bcd5a2de")}catch(e){}}();
 import { requestCaptureContext } from "./context.js";
 import { warnOnce } from "./log.js";
-import { getOriginalFetch } from "./original-fetch.js";
-import { postCaptureEvents } from "./sidecar-client.js";
 import { serializeKvCaptureFields } from "./kv-capture.js";
 //#region src/kv-patch.ts
 /**
@@ -57,7 +55,7 @@ const kvBindingNames = /* @__PURE__ */ new WeakMap();
 */
 const installKvPatch = (env, options) => {
 	try {
-		for (const { name, value, skip } of kvBindings(env, options?.skipBindings)) {
+		for (const { name, value, skip } of kvBindings(env, options?.skipBindings, options?.skipInstances)) {
 			patchKvMethods(value);
 			if (!skip) kvBindingNames.set(value, name);
 		}
@@ -65,14 +63,15 @@ const installKvPatch = (env, options) => {
 		warnOnce("kv-patch-install", "Failed to install the Meticulous KV patch — KV operations will not be recorded.", error);
 	}
 };
-const kvBindings = (env, skipBindings) => {
+const kvBindings = (env, skipBindings, skipInstances) => {
 	if (env === null || typeof env !== "object") return [];
 	const skipped = new Set(skipBindings ?? []);
+	const skippedInstances = new Set(skipInstances ?? []);
 	const found = [];
 	for (const [name, value] of Object.entries(env)) if (isKvNamespaceLike(value)) found.push({
 		name,
 		value,
-		skip: skipped.has(name)
+		skip: skipped.has(name) || skippedInstances.has(value)
 	});
 	return found;
 };
@@ -164,8 +163,7 @@ const captureKvOperation = async (ctx, operation, bindingName, args, invoke) =>
 };
 const report = (ctx, operation, bindingName, args, startTimeMs, outcome) => {
 	try {
-		const event = buildKvEvent(ctx, operation, bindingName, args, startTimeMs, outcome);
-		ctx.waitUntil(postCaptureEvents(getOriginalFetch(), ctx.sidecarUrl, [event]));
+		ctx.buffer.add(buildKvEvent(ctx, operation, bindingName, args, startTimeMs, outcome));
 	} catch (error) {
 		warnOnce("kv-report", "Failed to report a KV operation.", error);
 	}
@@ -174,6 +172,8 @@ const buildKvEvent = (ctx, operation, bindingName, args, startTimeMs, outcome) =
 	kind: "kv",
 	requestId: ctx.requestId,
 	...ctx.frontendSessionId !== void 0 ? { frontendSessionId: ctx.frontendSessionId } : {},
+	traceId: ctx.traceId,
+	serverSpanId: ctx.serverSpanId,
 	bindingName,
 	operation,
 	...serializeKvCaptureFields(operation, args, outcome),
@@ -185,4 +185,4 @@ const buildKvEvent = (ctx, operation, bindingName, args, startTimeMs, outcome) =
 export { installKvPatch };
 
 //# sourceMappingURL=kv-patch.js.map
-//# debugId=b871e5bd-a858-5783-9618-2ec0bd2a52bf
+//# debugId=303b51b3-97aa-5dde-9000-ea94bcd5a2de