@alwaysmeticulous/backend-recorder-workerd 2.324.0 → 2.326.0

package/dist/postgres/with-meticulous-postgres.js

@@ -0,0 +1,152 @@
+
+!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]="7437e682-9879-55d9-aa51-34f2920d26d3")}catch(e){}}();
+import { requestCaptureContext } from "../context.js";
+import { warnOnce } from "../log.js";
+import { MAX_POSTGRES_JS_RESULT_SIZE, isSupportedPostgresJsQuery, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult } from "./capture.js";
+//#region src/postgres/with-meticulous-postgres.ts
+/**
+* Records postgres.js queries a deployed Worker makes — typically over Hyperdrive, which is the
+* only way a Worker reaches Postgres.
+*
+* There is no seam to patch automatically here. The Node recorder can hook Node's module loader
+* to patch `postgres/{src,cjs/src,cf/src}/query.js`, but a Worker is a single bundle: `postgres`
+* was inlined at build time and never passes through a loader. So the app hands us its client:
+*
+*   const sql = withMeticulousPostgres(postgres(env.HYPERDRIVE.connectionString));
+*
+* Every postgres.js query funnels through one internal method, `Query.prototype.handle`, and this
+* reaches that shared prototype *through the instance* — via a throwaway query, which is free
+* because postgres.js queries are lazy and nothing executes until awaited. One call therefore also
+* covers read-replica clients and any other client in the isolate.
+*
+* Apply it **outermost** if something else also wraps the client (Sentry's
+* `instrumentPostgresJsSql`, a logging proxy): those wrappers return a proxy whose `handle` is
+* still the shared prototype's, so ordering does not change what is captured — but keeping ours
+* outermost matches the Node recorder's contract and stays correct if that ever changes.
+*
+* Record-only, deliberately. A Worker recording is replayed against the app running under Node,
+* where `@alwaysmeticulous/backend-recorder-js` serves these queries from its own mock store —
+* which is why the captured attributes here are exactly the ones that store reads. Outside a
+* recorded request this is a complete pass-through, so it is safe to leave in deployed code.
+*
+* Returns the client unchanged; the patch is on the prototype.
+*/
+const withMeticulousPostgres = (sql) => {
+	try {
+		const prototype = findQueryPrototype(sql);
+		if (prototype === void 0) {
+			warnOnce("postgres-wrapper-unsupported", "withMeticulousPostgres could not reach postgres.js' Query prototype — queries will not be recorded.");
+			return sql;
+		}
+		patchHandle(prototype);
+	} catch (error) {
+		warnOnce("postgres-wrapper-failed", "withMeticulousPostgres failed — queries will not be recorded.", error);
+	}
+	return sql;
+};
+const HANDLE_PATCHED = Symbol.for("meticulous.workerd.postgresJsPatched");
+/**
+* The `Query` prototype, reached by building a query and reading its prototype.
+*
+* `sql.unsafe` is used rather than a tagged template because it takes the text as a plain
+* argument: no interpolation, and postgres.js does not touch a connection until the query is
+* awaited, which nothing here does. The query is discarded.
+*/
+const findQueryPrototype = (sql) => {
+	const unsafe = sql?.unsafe;
+	if (typeof unsafe !== "function") return;
+	const probe = unsafe.call(sql, "select 1");
+	if (probe === null || typeof probe !== "object") return;
+	const prototype = Object.getPrototypeOf(probe);
+	if (prototype === null) return;
+	const descriptor = Object.getOwnPropertyDescriptor(prototype, "handle");
+	return descriptor !== void 0 && typeof descriptor.value === "function" && descriptor.configurable === true ? prototype : void 0;
+};
+const patchHandle = (prototype) => {
+	const original = Object.getOwnPropertyDescriptor(prototype, "handle")?.value;
+	if (original === void 0 || original[HANDLE_PATCHED] === true) return;
+	const patched = function() {
+		if (this.executed || !isSupportedPostgresJsQuery(this)) return original.call(this);
+		const ctx = requestCaptureContext.getStore();
+		if (!ctx || ctx.mode !== "record") return original.call(this);
+		try {
+			captureQuery(ctx, this);
+		} catch (error) {
+			warnOnce("postgres-capture", "Failed to capture a postgres.js query.", error);
+		}
+		return original.call(this);
+	};
+	Object.defineProperty(patched, HANDLE_PATCHED, {
+		value: true,
+		enumerable: false,
+		configurable: true
+	});
+	Object.defineProperty(prototype, "handle", {
+		value: patched,
+		writable: true,
+		enumerable: false,
+		configurable: true
+	});
+};
+/**
+* Wraps the query's own `resolve`/`reject` so the outcome is captured without the query being
+* awaited here — the same trick the Node instrumentation uses, and the only place a query's input
+* and its result are both visible.
+*/
+const captureQuery = (ctx, query) => {
+	const queryText = reconstructQueryText(query.strings);
+	if (queryText === void 0) return;
+	const startTimeMs = Date.now();
+	const base = {
+		kind: "postgres",
+		requestId: ctx.requestId,
+		...ctx.frontendSessionId !== void 0 ? { frontendSessionId: ctx.frontendSessionId } : {},
+		traceId: ctx.traceId,
+		serverSpanId: ctx.serverSpanId,
+		queryText,
+		params: serializePostgresJsArgs(query.args),
+		rowMode: resolveRowMode(query.isRaw),
+		startTimeMs
+	};
+	const report = (outcome) => {
+		try {
+			ctx.buffer.add({
+				...base,
+				...outcome,
+				endTimeMs: Date.now()
+			});
+		} catch (error) {
+			warnOnce("postgres-report", "Failed to report a postgres.js query.", error);
+		}
+	};
+	const originalResolve = query.resolve;
+	const originalReject = query.reject;
+	query.resolve = (result) => {
+		let json;
+		try {
+			json = serializePostgresJsResult(result);
+		} catch {
+			json = void 0;
+		}
+		report(json === void 0 ? {} : { result: {
+			body: json.length > 262144 ? json.slice(0, MAX_POSTGRES_JS_RESULT_SIZE) : json,
+			truncated: json.length > MAX_POSTGRES_JS_RESULT_SIZE
+		} });
+		return originalResolve.call(query, result);
+	};
+	query.reject = (error) => {
+		let errorJson;
+		try {
+			errorJson = serializePostgresJsError(error);
+		} catch {
+			errorJson = void 0;
+		}
+		report(errorJson === void 0 ? {} : { errorJson });
+		return originalReject.call(query, error);
+	};
+};
+//#endregion
+export { withMeticulousPostgres };
+
+//# sourceMappingURL=with-meticulous-postgres.js.map
+//# debugId=7437e682-9879-55d9-aa51-34f2920d26d3

package/dist/postgres/with-meticulous-postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-meticulous-postgres.js","sources":["../../src/postgres/with-meticulous-postgres.ts"],"sourcesContent":["import { type RequestCaptureContext, requestCaptureContext } from \"../context\";\nimport { warnOnce } from \"../log\";\nimport type { PostgresQueryEvent } from \"../protocol\";\nimport {\n  isSupportedPostgresJsQuery,\n  MAX_POSTGRES_JS_RESULT_SIZE,\n  type PostgresJsQueryLike,\n  reconstructQueryText,\n  resolveRowMode,\n  serializePostgresJsArgs,\n  serializePostgresJsError,\n  serializePostgresJsResult,\n} from \"./capture\";\n\n/**\n * Records postgres.js queries a deployed Worker makes — typically over Hyperdrive, which is the\n * only way a Worker reaches Postgres.\n *\n * There is no seam to patch automatically here. The Node recorder can hook Node's module loader\n * to patch `postgres/{src,cjs/src,cf/src}/query.js`, but a Worker is a single bundle: `postgres`\n * was inlined at build time and never passes through a loader. So the app hands us its client:\n *\n *   const sql = withMeticulousPostgres(postgres(env.HYPERDRIVE.connectionString));\n *\n * Every postgres.js query funnels through one internal method, `Query.prototype.handle`, and this\n * reaches that shared prototype *through the instance* — via a throwaway query, which is free\n * because postgres.js queries are lazy and nothing executes until awaited. One call therefore also\n * covers read-replica clients and any other client in the isolate.\n *\n * Apply it **outermost** if something else also wraps the client (Sentry's\n * `instrumentPostgresJsSql`, a logging proxy): those wrappers return a proxy whose `handle` is\n * still the shared prototype's, so ordering does not change what is captured — but keeping ours\n * outermost matches the Node recorder's contract and stays correct if that ever changes.\n *\n * Record-only, deliberately. A Worker recording is replayed against the app running under Node,\n * where `@alwaysmeticulous/backend-recorder-js` serves these queries from its own mock store —\n * which is why the captured attributes here are exactly the ones that store reads. Outside a\n * recorded request this is a complete pass-through, so it is safe to leave in deployed code.\n *\n * Returns the client unchanged; the patch is on the prototype.\n */\nexport const withMeticulousPostgres = <Sql>(sql: Sql): Sql => {\n  try {\n    const prototype = findQueryPrototype(sql);\n    if (prototype === undefined) {\n      warnOnce(\n        \"postgres-wrapper-unsupported\",\n        \"withMeticulousPostgres could not reach postgres.js' Query prototype — queries will not be recorded.\",\n      );\n      return sql;\n    }\n    patchHandle(prototype);\n  } catch (error) {\n    warnOnce(\n      \"postgres-wrapper-failed\",\n      \"withMeticulousPostgres failed — queries will not be recorded.\",\n      error,\n    );\n  }\n  return sql;\n};\n\n// Symbol.for so a second copy of the shim (e.g. bundled twice) still detects the patch.\nconst HANDLE_PATCHED = Symbol.for(\"meticulous.workerd.postgresJsPatched\");\n\ntype HandleFn = (this: PostgresJsQueryLike) => unknown;\n\n/**\n * The `Query` prototype, reached by building a query and reading its prototype.\n *\n * `sql.unsafe` is used rather than a tagged template because it takes the text as a plain\n * argument: no interpolation, and postgres.js does not touch a connection until the query is\n * awaited, which nothing here does. The query is discarded.\n */\nconst findQueryPrototype = (sql: unknown): object | undefined => {\n  const unsafe = (sql as { unsafe?: unknown } | null)?.unsafe;\n  if (typeof unsafe !== \"function\") {\n    return undefined;\n  }\n  const probe: unknown = (unsafe as (text: string) => unknown).call(\n    sql,\n    \"select 1\",\n  );\n  if (probe === null || typeof probe !== \"object\") {\n    return undefined;\n  }\n  const prototype = Object.getPrototypeOf(probe) as object | null;\n  if (prototype === null) {\n    return undefined;\n  }\n  const descriptor = Object.getOwnPropertyDescriptor(prototype, \"handle\");\n  return descriptor !== undefined &&\n    typeof descriptor.value === \"function\" &&\n    descriptor.configurable === true\n    ? prototype\n    : undefined;\n};\n\nconst patchHandle = (prototype: object): void => {\n  const descriptor = Object.getOwnPropertyDescriptor(prototype, \"handle\");\n  const original = descriptor?.value as HandleFn | undefined;\n  if (\n    original === undefined ||\n    (original as unknown as Record<symbol, unknown>)[HANDLE_PATCHED] === true\n  ) {\n    return;\n  }\n\n  const patched = function (this: PostgresJsQueryLike): unknown {\n    // `handle` is reachable from then/catch/finally/execute, so it can be called more than once\n    // for one query; postgres.js itself no-ops on the repeats via `executed`. Bail before\n    // instrumenting so a query is never captured twice.\n    if (this.executed || !isSupportedPostgresJsQuery(this)) {\n      return original.call(this);\n    }\n    const ctx = requestCaptureContext.getStore();\n    if (!ctx || ctx.mode !== \"record\") {\n      return original.call(this);\n    }\n    try {\n      captureQuery(ctx, this);\n    } catch (error) {\n      warnOnce(\n        \"postgres-capture\",\n        \"Failed to capture a postgres.js query.\",\n        error,\n      );\n    }\n    return original.call(this);\n  };\n  Object.defineProperty(patched, HANDLE_PATCHED, {\n    value: true,\n    enumerable: false,\n    configurable: true,\n  });\n  Object.defineProperty(prototype, \"handle\", {\n    value: patched,\n    writable: true,\n    enumerable: false,\n    configurable: true,\n  });\n};\n\n/**\n * Wraps the query's own `resolve`/`reject` so the outcome is captured without the query being\n * awaited here — the same trick the Node instrumentation uses, and the only place a query's input\n * and its result are both visible.\n */\nconst captureQuery = (\n  ctx: RequestCaptureContext,\n  query: PostgresJsQueryLike,\n): void => {\n  const queryText = reconstructQueryText(query.strings);\n  if (queryText === undefined) {\n    return;\n  }\n  const startTimeMs = Date.now();\n  const base = {\n    kind: \"postgres\" as const,\n    requestId: ctx.requestId,\n    ...(ctx.frontendSessionId !== undefined\n      ? { frontendSessionId: ctx.frontendSessionId }\n      : {}),\n    traceId: ctx.traceId,\n    serverSpanId: ctx.serverSpanId,\n    queryText,\n    params: serializePostgresJsArgs(query.args),\n    rowMode: resolveRowMode(query.isRaw),\n    startTimeMs,\n  };\n\n  const report = (outcome: Partial<PostgresQueryEvent>): void => {\n    try {\n      ctx.buffer.add({ ...base, ...outcome, endTimeMs: Date.now() });\n    } catch (error) {\n      warnOnce(\n        \"postgres-report\",\n        \"Failed to report a postgres.js query.\",\n        error,\n      );\n    }\n  };\n\n  const originalResolve = query.resolve;\n  const originalReject = query.reject;\n  query.resolve = (result: unknown) => {\n    // A result that cannot be serialized is simply not captured → it misses during replay and\n    // errors hermetically, rather than serving something wrong.\n    let json: string | undefined;\n    try {\n      json = serializePostgresJsResult(result);\n    } catch {\n      json = undefined;\n    }\n    report(\n      json === undefined\n        ? {}\n        : {\n            result: {\n              body:\n                json.length > MAX_POSTGRES_JS_RESULT_SIZE\n                  ? json.slice(0, MAX_POSTGRES_JS_RESULT_SIZE)\n                  : json,\n              truncated: json.length > MAX_POSTGRES_JS_RESULT_SIZE,\n            },\n          },\n    );\n    return originalResolve.call(query, result);\n  };\n  query.reject = (error: unknown) => {\n    let errorJson: string | undefined;\n    try {\n      errorJson = serializePostgresJsError(error);\n    } catch {\n      errorJson = undefined;\n    }\n    report(errorJson === undefined ? {} : { errorJson });\n    return originalReject.call(query, error);\n  };\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,0BAA+B,QAAkB;AAC5D,KAAI;EACF,MAAM,YAAY,mBAAmB,IAAI;AACzC,MAAI,cAAc,KAAA,GAAW;AAC3B,YACE,gCACA,sGACD;AACD,UAAO;;AAET,cAAY,UAAU;UACf,OAAO;AACd,WACE,2BACA,iEACA,MACD;;AAEH,QAAO;;AAIT,MAAM,iBAAiB,OAAO,IAAI,uCAAuC;;;;;;;;AAWzE,MAAM,sBAAsB,QAAqC;CAC/D,MAAM,SAAU,KAAqC;AACrD,KAAI,OAAO,WAAW,WACpB;CAEF,MAAM,QAAkB,OAAqC,KAC3D,KACA,WACD;AACD,KAAI,UAAU,QAAQ,OAAO,UAAU,SACrC;CAEF,MAAM,YAAY,OAAO,eAAe,MAAM;AAC9C,KAAI,cAAc,KAChB;CAEF,MAAM,aAAa,OAAO,yBAAyB,WAAW,SAAS;AACvE,QAAO,eAAe,KAAA,KACpB,OAAO,WAAW,UAAU,cAC5B,WAAW,iBAAiB,OAC1B,YACA,KAAA;;AAGN,MAAM,eAAe,cAA4B;CAE/C,MAAM,WADa,OAAO,yBAAyB,WAAW,SACnC,EAAE;AAC7B,KACE,aAAa,KAAA,KACZ,SAAgD,oBAAoB,KAErE;CAGF,MAAM,UAAU,WAA8C;AAI5D,MAAI,KAAK,YAAY,CAAC,2BAA2B,KAAK,CACpD,QAAO,SAAS,KAAK,KAAK;EAE5B,MAAM,MAAM,sBAAsB,UAAU;AAC5C,MAAI,CAAC,OAAO,IAAI,SAAS,SACvB,QAAO,SAAS,KAAK,KAAK;AAE5B,MAAI;AACF,gBAAa,KAAK,KAAK;WAChB,OAAO;AACd,YACE,oBACA,0CACA,MACD;;AAEH,SAAO,SAAS,KAAK,KAAK;;AAE5B,QAAO,eAAe,SAAS,gBAAgB;EAC7C,OAAO;EACP,YAAY;EACZ,cAAc;EACf,CAAC;AACF,QAAO,eAAe,WAAW,UAAU;EACzC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;EACf,CAAC;;;;;;;AAQJ,MAAM,gBACJ,KACA,UACS;CACT,MAAM,YAAY,qBAAqB,MAAM,QAAQ;AACrD,KAAI,cAAc,KAAA,EAChB;CAEF,MAAM,cAAc,KAAK,KAAK;CAC9B,MAAM,OAAO;EACX,MAAM;EACN,WAAW,IAAI;EACf,GAAI,IAAI,sBAAsB,KAAA,IAC1B,EAAE,mBAAmB,IAAI,mBAAmB,GAC5C,EAAE;EACN,SAAS,IAAI;EACb,cAAc,IAAI;EAClB;EACA,QAAQ,wBAAwB,MAAM,KAAK;EAC3C,SAAS,eAAe,MAAM,MAAM;EACpC;EACD;CAED,MAAM,UAAU,YAA+C;AAC7D,MAAI;AACF,OAAI,OAAO,IAAI;IAAE,GAAG;IAAM,GAAG;IAAS,WAAW,KAAK,KAAK;IAAE,CAAC;WACvD,OAAO;AACd,YACE,mBACA,yCACA,MACD;;;CAIL,MAAM,kBAAkB,MAAM;CAC9B,MAAM,iBAAiB,MAAM;AAC7B,OAAM,WAAW,WAAoB;EAGnC,IAAI;AACJ,MAAI;AACF,UAAO,0BAA0B,OAAO;UAClC;AACN,UAAO,KAAA;;AAET,SACE,SAAS,KAAA,IACL,EAAE,GACF,EACE,QAAQ;GACN,MACE,KAAK,SAAA,SACD,KAAK,MAAM,GAAG,4BAA4B,GAC1C;GACN,WAAW,KAAK,SAAS;GAC1B,EACF,CACN;AACD,SAAO,gBAAgB,KAAK,OAAO,OAAO;;AAE5C,OAAM,UAAU,UAAmB;EACjC,IAAI;AACJ,MAAI;AACF,eAAY,yBAAyB,MAAM;UACrC;AACN,eAAY,KAAA;;AAEd,SAAO,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW,CAAC;AACpD,SAAO,eAAe,KAAK,OAAO,MAAM","debugId":"7437e682-9879-55d9-aa51-34f2920d26d3"}

package/dist/protocol.d.ts

@@ -4,7 +4,7 @@
  * recorder sidecar. The sidecar imports these types (type-only), so this file
  * is the single source of truth for the shape of capture events.
  */
-declare const SIDECAR_PROTOCOL_VERSION = "1";
+declare const SIDECAR_PROTOCOL_VERSION = "2";
 /** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */
 declare const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
 /**
@@ -12,6 +12,8 @@ declare const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-v
  * under recording; its value ties backend spans to the frontend session.
  */
 declare const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
+/** Header identifying one replay attempt of a recorded frontend session. */
+declare const REPLAY_ID_HEADER = "x-meticulous-replay-id";
 /**
  * A request carrying this header set to `"true"` is never served from the recording and
  * never fails on a miss — it goes to the real network. Use it for a call that must be live
@@ -42,9 +44,12 @@ declare const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-u
 /**
  * The only headers persisted on capture events. Everything else — notably
  * authorization, cookie/set-cookie, and API-key headers — is dropped at
- * capture time, before it ever leaves the worker. Mirrors the Node backend
- * recorder, which persists only content-type plus the Meticulous session
- * header.
+ * capture time, before it ever leaves the worker.
+ *
+ * The Node backend recorder persists the same two, plus the inbound request's
+ * `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list
+ * has not followed it there, so a workerd recording of an authenticated server
+ * render still carries no session cookie.
  */
 declare const CAPTURED_HEADERS: readonly ["content-type", "x-meticulous-session-id"];
 interface CapturedBody {
@@ -53,11 +58,33 @@ interface CapturedBody {
   /** True when the body exceeded the capture cap or the read was cut short. */
   truncated: boolean;
 }
-interface BaseRequestEvent {
+/**
+ * The fields every capture event carries to say which request, session and trace it belongs to.
+ */
+interface CorrelatedEvent {
   /** Correlates outbound events to the inbound request being handled. */
   requestId: string;
   /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */
   frontendSessionId?: string;
+  /**
+   * Trace the request's spans belong to (32 hex chars), minted by the shim.
+   *
+   * The shim mints it, rather than the sidecar deriving it from {@link requestId}, so span
+   * assembly is stateless: a sidecar that had to remember `requestId → traceId` would give a
+   * request's SERVER span and its CLIENT children different traces whenever it lost that memory
+   * between two batches — which, for a Worker-hosted sidecar, an eviction can do at any moment.
+   *
+   * Optional so a sidecar keeps working against a shim that predates this field, in which case
+   * it falls back to its own per-`requestId` map.
+   */
+  traceId?: string;
+  /**
+   * Span id of the request's SERVER span (16 hex chars), also minted by the shim: it is the
+   * parent of every CLIENT span the request produced, and the inbound event's own span id.
+   */
+  serverSpanId?: string;
+}
+interface BaseRequestEvent extends CorrelatedEvent {
   method: string;
   /** Full URL including query string. */
   url: string;
@@ -76,6 +103,19 @@ interface BaseRequestEvent {
  */
 interface InboundRequestEvent extends BaseRequestEvent {
   kind: "inbound";
+  /**
+   * Where {@link BaseRequestEvent.frontendSessionId} came from. Absent means the browser
+   * minted it and sent it on the request, which is the normal case. `"backend"` means the
+   * shim minted it for a document navigation the browser could not tag, and the page may or
+   * may not have gone on to adopt it — a distinction ingestion needs, because an unadopted
+   * backend-minted id names a session that will never exist and must be treated as unstamped.
+   * The sidecar turns it into `meticulous.session_id_origin`.
+   *
+   * Optional, and therefore compatible with an older sidecar (which ignores it) — which is
+   * why adding it does not bump {@link SIDECAR_PROTOCOL_VERSION}, a strict-equality check
+   * whose bump would instead make this shim unusable against one.
+   */
+  sessionIdOrigin?: "backend";
 }
 /**
  * An outgoing `fetch` call made while handling an inbound request (becomes a
@@ -123,11 +163,8 @@ type KvOmittedReason = "binary" | "stream";
  * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single
  * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.
  */
-interface KvOperationEvent {
+interface KvOperationEvent extends CorrelatedEvent {
   kind: "kv";
-  /** Correlates the operation to the inbound request being handled. */
-  requestId: string;
-  frontendSessionId?: string;
   /**
    * The `env` key the KV namespace was found under. Always present, unlike on a binding
    * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one
@@ -164,7 +201,34 @@ interface KvOperationEvent {
   /** Set when the operation threw. */
   error?: string;
 }
-type CaptureEvent = InboundRequestEvent | OutboundRequestEvent | BindingRequestEvent | KvOperationEvent;
+/**
+ * One postgres.js query made while handling an inbound request (becomes a CLIENT span).
+ *
+ * Deliberately carries the same fields the Node recorder puts on a postgres.js span rather than
+ * anything Worker-specific: `PostgresJsMockStore` builds its match key from those attributes at
+ * load time, so a query recorded here replays through the existing Node mock path unchanged.
+ * See `postgres/capture.ts` for the serialization, which both surfaces share.
+ */
+interface PostgresQueryEvent extends CorrelatedEvent {
+  kind: "postgres";
+  /** SQL rebuilt from the tagged template's chunks, with `$1`, `$2`… placeholders. */
+  queryText: string;
+  /** JSON of the interpolated values, from `serializePostgresJsArgs`. */
+  params: string;
+  /** `""`, `"raw"` or `"values"` — the row shape the query asked for. */
+  rowMode: string;
+  /** JSON of the resolved `Result`, capped at {@link MAX_POSTGRES_JS_RESULT_SIZE}. */
+  result?: CapturedBody;
+  /**
+   * JSON of the rejection, from `serializePostgresJsError`. Set instead of {@link result}, and
+   * distinct from the transport-level `error` string on the HTTP-shaped events: this one is a
+   * recorded outcome the replay reproduces, not a note that capture failed.
+   */
+  errorJson?: string;
+  startTimeMs: number;
+  endTimeMs: number;
+}
+type CaptureEvent = InboundRequestEvent | OutboundRequestEvent | BindingRequestEvent | KvOperationEvent | PostgresQueryEvent;
 interface CaptureEventsPayload {
   events: CaptureEvent[];
 }
@@ -183,6 +247,7 @@ interface ReplaySessionInfoResponse {
 /** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */
 interface OutboundFetchLookupRequest {
   frontendSessionId: string;
+  replayId: string;
   method: string;
   /** Full URL including query string. */
   url: string;
@@ -221,5 +286,5 @@ type OutboundFetchLookupResponse = {
   outcome: "passthrough";
 };
 //#endregion
-export { 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 };
+export { 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 };
 //# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -5,8 +5,8 @@
 * is the single source of truth for the shape of capture events.
 */
 
-!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]="40d02ddc-000e-5f33-972c-1fa95ad7e2ea")}catch(e){}}();
-const SIDECAR_PROTOCOL_VERSION = "1";
+!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]="36a20e1c-cf70-5563-a474-2863eaacfbe8")}catch(e){}}();
+const SIDECAR_PROTOCOL_VERSION = "2";
 /** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */
 const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
 /**
@@ -14,6 +14,8 @@ const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
 * under recording; its value ties backend spans to the frontend session.
 */
 const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
+/** Header identifying one replay attempt of a recorded frontend session. */
+const REPLAY_ID_HEADER = "x-meticulous-replay-id";
 /**
 * A request carrying this header set to `"true"` is never served from the recording and
 * never fails on a miss — it goes to the real network. Use it for a call that must be live
@@ -44,13 +46,16 @@ const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-url";
 /**
 * The only headers persisted on capture events. Everything else — notably
 * authorization, cookie/set-cookie, and API-key headers — is dropped at
-* capture time, before it ever leaves the worker. Mirrors the Node backend
-* recorder, which persists only content-type plus the Meticulous session
-* header.
+* capture time, before it ever leaves the worker.
+*
+* The Node backend recorder persists the same two, plus the inbound request's
+* `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list
+* has not followed it there, so a workerd recording of an authenticated server
+* render still carries no session cookie.
 */
 const CAPTURED_HEADERS = ["content-type", FRONTEND_SESSION_ID_HEADER];
 //#endregion
-export { 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 };
+export { 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 };
 
 //# sourceMappingURL=protocol.js.map
-//# debugId=40d02ddc-000e-5f33-972c-1fa95ad7e2ea
+//# debugId=36a20e1c-cf70-5563-a474-2863eaacfbe8

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Wire protocol between the in-worker shim and the Meticulous backend\n * recorder sidecar. The sidecar imports these types (type-only), so this file\n * is the single source of truth for the shape of capture events.\n */\n\nexport const SIDECAR_PROTOCOL_VERSION = \"1\";\n\n/** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */\nexport const SIDECAR_PROTOCOL_VERSION_HEADER =\n  \"x-meticulous-sidecar-protocol-version\";\n\n/**\n * Header the Meticulous frontend recorder stamps on requests made by the app\n * under recording; its value ties backend spans to the frontend session.\n */\nexport const FRONTEND_SESSION_ID_HEADER = \"x-meticulous-session-id\";\n\n/**\n * A request carrying this header set to `\"true\"` is never served from the recording and\n * never fails on a miss — it goes to the real network. Use it for a call that must be live\n * during replay (a health probe, telemetry, a resource the recording cannot cover).\n *\n * Same convention and value as the frontend network stubbing and the Node backend recorder\n * (`METICULOUS_PASSTHROUGH_HEADER` in `@alwaysmeticulous/backend-recorder-js`); the value\n * must stay in step with both.\n */\nexport const METICULOUS_PASSTHROUGH_HEADER = \"meticulous-passthrough\";\n\nexport const SIDECAR_EVENTS_PATH = \"/v1/events\";\n\n/**\n * Replay routes. A sidecar started in record mode answers 404 on both, which the shim\n * treats as \"replay unavailable\" and falls back to plain pass-through — so a new shim\n * keeps working against an older, record-only sidecar.\n */\nexport const SIDECAR_REPLAY_SESSION_PATH = \"/v1/replay/session\";\nexport const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = \"/v1/replay/outbound-fetch\";\n\n/**\n * Header carrying the replay sidecar's origin, injected by the Meticulous replay runner\n * on requests to the app under test. Workerd cannot see container environment variables,\n * so an inbound header is the only way per-replay config can reach the shim.\n *\n * The shim validates the value before using it and only honours a loopback /\n * `host.docker.internal` / private-network `http:` origin — see `replay-sidecar-url.ts`.\n */\nexport const REPLAY_SIDECAR_URL_HEADER =\n  \"x-meticulous-backend-replay-sidecar-url\";\n\n/**\n * The only headers persisted on capture events. Everything else — notably\n * authorization, cookie/set-cookie, and API-key headers — is dropped at\n * capture time, before it ever leaves the worker. Mirrors the Node backend\n * recorder, which persists only content-type plus the Meticulous session\n * header.\n */\nexport const CAPTURED_HEADERS = [\n  \"content-type\",\n  FRONTEND_SESSION_ID_HEADER,\n] as const;\n\nexport interface CapturedBody {\n  /** UTF-8 decoded body, truncated to the capture cap. */\n  body: string;\n  /** True when the body exceeded the capture cap or the read was cut short. */\n  truncated: boolean;\n}\n\ninterface BaseRequestEvent {\n  /** Correlates outbound events to the inbound request being handled. */\n  requestId: string;\n  /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */\n  frontendSessionId?: string;\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /** Lower-cased header name → values. */\n  requestHeaders: Record<string, string[]>;\n  responseHeaders?: Record<string, string[]>;\n  statusCode?: number;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the request failed before a response was produced. */\n  error?: string;\n}\n\n/**\n * The worker's own inbound request (becomes a SERVER span). Bodies are not\n * captured, matching the Node backend recorder's SERVER-span contract.\n */\nexport interface InboundRequestEvent extends BaseRequestEvent {\n  kind: \"inbound\";\n}\n\n/**\n * An outgoing `fetch` call made while handling an inbound request (becomes a\n * CLIENT span).\n */\nexport interface OutboundRequestEvent extends BaseRequestEvent {\n  kind: \"outbound\";\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/**\n * A `fetch` through a Cloudflare binding — a service binding, an assets binding, or a\n * Durable Object stub — made while handling an inbound request (becomes a CLIENT span).\n *\n * Request/Response-shaped like {@link OutboundRequestEvent}, but a distinct kind because the\n * call never leaves the isolate and its URL is whatever the caller invented. Keeping the two\n * apart means a binding call and real egress can never be confused for one another when\n * these spans are eventually mocked.\n */\nexport interface BindingRequestEvent extends BaseRequestEvent {\n  kind: \"binding\";\n  /**\n   * The `env` key the binding was found under. Absent when the instance was never seen on\n   * `env` — most commonly a Durable Object stub, which `namespace.get()` produces rather\n   * than being a binding in its own right.\n   */\n  bindingName?: string;\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/** KV namespace methods the shim records. */\nexport type KvOperation = \"get\" | \"getWithMetadata\" | \"put\" | \"delete\" | \"list\";\n\n/**\n * Why a KV value is absent from an event: workerd handed it over in a form that cannot be\n * persisted as text. A `\"stream\"` value must not even be read — consuming it would take the\n * bytes away from the app — and binary values are skipped deliberately, since KV blobs are\n * large and would both bloat the recording and be mangled by UTF-8 capture.\n */\nexport type KvOmittedReason = \"binary\" | \"stream\";\n\n/**\n * An operation on a Cloudflare KV namespace binding, made while handling an inbound request\n * (becomes a CLIENT span).\n *\n * KV is not HTTP: there is no method, URL or status code, so this event shares nothing with\n * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single\n * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.\n */\nexport interface KvOperationEvent {\n  kind: \"kv\";\n  /** Correlates the operation to the inbound request being handled. */\n  requestId: string;\n  frontendSessionId?: string;\n  /**\n   * The `env` key the KV namespace was found under. Always present, unlike on a binding\n   * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one\n   * that was never seen on `env` is not recorded at all.\n   */\n  bindingName: string;\n  operation: KvOperation;\n  /**\n   * The key operated on, when it is a single string. Absent for `list` (which spans keys) and\n   * for a bulk `get` (which takes an array) — both keep their arguments in {@link args}.\n   */\n  key?: string;\n  /**\n   * JSON of the call's arguments: the read `type`, the `put` options, the `list` selector.\n   * A `put` value appears as `null` here — it is captured in {@link value} instead, so that\n   * redaction applies to it.\n   */\n  args?: CapturedBody;\n  /** JSON of the value a `put` wrote, with secret-looking fields redacted. */\n  value?: CapturedBody;\n  /**\n   * JSON of what the operation returned: the value for `get`, `{value, metadata}` for\n   * `getWithMetadata`, the key page for `list`. Absent for `put`/`delete`, which return\n   * nothing, and for a value that could not be captured (see {@link omitted}).\n   */\n  result?: CapturedBody;\n  /**\n   * Why the operation's value is missing. Refers to the written value for `put` and to the\n   * read value otherwise — a `put` has no result, so this is never ambiguous.\n   */\n  omitted?: KvOmittedReason;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the operation threw. */\n  error?: string;\n}\n\nexport type CaptureEvent =\n  | InboundRequestEvent\n  | OutboundRequestEvent\n  | BindingRequestEvent\n  | KvOperationEvent;\n\nexport interface CaptureEventsPayload {\n  events: CaptureEvent[];\n}\n\n/**\n * Answer to `GET {SIDECAR_REPLAY_SESSION_PATH}?sessionId=<id>`: whether the sidecar holds\n * mocks for a session, and the virtual clock anchor to freeze `Date` at while serving it.\n */\nexport interface ReplaySessionInfoResponse {\n  found: boolean;\n  /**\n   * Epoch ms of the session's last recorded activity. The worker freezes its clock here so\n   * that credentials minted during the recording are already issued but not yet expired.\n   */\n  clockAnchorMs?: number;\n}\n\n/** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */\nexport interface OutboundFetchLookupRequest {\n  frontendSessionId: string;\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /**\n   * Request body as captured by `readBodyWithCap`. The sidecar hashes this itself, so the\n   * hash it compares against a recording is derived from byte-identical input on both the\n   * record and replay sides.\n   */\n  requestBody?: CapturedBody;\n}\n\n/**\n * A recorded response to serve, a miss the caller must fail, or an instruction to let the\n * real call through. An unrecognised `outcome` must be treated as `passthrough`, so an older\n * shim keeps working against a newer sidecar.\n */\nexport type OutboundFetchLookupResponse =\n  | {\n      outcome: \"mock\";\n      statusCode: number;\n      body: string;\n      headers: Record<string, string>;\n    }\n  /**\n   * The store was consulted and holds nothing for this call. Replay is hermetic, so the\n   * shim fails the request rather than letting it reach the real service — matching the\n   * Node backend recorder's http/undici mocks.\n   */\n  | { outcome: \"no-mock\" }\n  /**\n   * The call cannot be looked up at all (an unparseable URL), so there is no miss to report.\n   * Also what an older sidecar answers on a miss, in which case the shim degrades to the\n   * pre-`no-mock` fail-open behaviour rather than breaking the app.\n   */\n  | { outcome: \"passthrough\" };\n"],"names":[],"mappings":";;;;;;;;AAMA,MAAa,2BAA2B;;AAGxC,MAAa,kCACX;;;;;AAMF,MAAa,6BAA6B;;;;;;;;;;AAW1C,MAAa,gCAAgC;AAE7C,MAAa,sBAAsB;;;;;;AAOnC,MAAa,8BAA8B;AAC3C,MAAa,qCAAqC;;;;;;;;;AAUlD,MAAa,4BACX;;;;;;;;AASF,MAAa,mBAAmB,CAC9B,gBACA,2BACD","debugId":"40d02ddc-000e-5f33-972c-1fa95ad7e2ea"}
+{"version":3,"file":"protocol.js","sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Wire protocol between the in-worker shim and the Meticulous backend\n * recorder sidecar. The sidecar imports these types (type-only), so this file\n * is the single source of truth for the shape of capture events.\n */\n\nexport const SIDECAR_PROTOCOL_VERSION = \"2\";\n\n/** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */\nexport const SIDECAR_PROTOCOL_VERSION_HEADER =\n  \"x-meticulous-sidecar-protocol-version\";\n\n/**\n * Header the Meticulous frontend recorder stamps on requests made by the app\n * under recording; its value ties backend spans to the frontend session.\n */\nexport const FRONTEND_SESSION_ID_HEADER = \"x-meticulous-session-id\";\n\n/** Header identifying one replay attempt of a recorded frontend session. */\nexport const REPLAY_ID_HEADER = \"x-meticulous-replay-id\";\n\n/**\n * A request carrying this header set to `\"true\"` is never served from the recording and\n * never fails on a miss — it goes to the real network. Use it for a call that must be live\n * during replay (a health probe, telemetry, a resource the recording cannot cover).\n *\n * Same convention and value as the frontend network stubbing and the Node backend recorder\n * (`METICULOUS_PASSTHROUGH_HEADER` in `@alwaysmeticulous/backend-recorder-js`); the value\n * must stay in step with both.\n */\nexport const METICULOUS_PASSTHROUGH_HEADER = \"meticulous-passthrough\";\n\nexport const SIDECAR_EVENTS_PATH = \"/v1/events\";\n\n/**\n * Replay routes. A sidecar started in record mode answers 404 on both, which the shim\n * treats as \"replay unavailable\" and falls back to plain pass-through — so a new shim\n * keeps working against an older, record-only sidecar.\n */\nexport const SIDECAR_REPLAY_SESSION_PATH = \"/v1/replay/session\";\nexport const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = \"/v1/replay/outbound-fetch\";\n\n/**\n * Header carrying the replay sidecar's origin, injected by the Meticulous replay runner\n * on requests to the app under test. Workerd cannot see container environment variables,\n * so an inbound header is the only way per-replay config can reach the shim.\n *\n * The shim validates the value before using it and only honours a loopback /\n * `host.docker.internal` / private-network `http:` origin — see `replay-sidecar-url.ts`.\n */\nexport const REPLAY_SIDECAR_URL_HEADER =\n  \"x-meticulous-backend-replay-sidecar-url\";\n\n/**\n * The only headers persisted on capture events. Everything else — notably\n * authorization, cookie/set-cookie, and API-key headers — is dropped at\n * capture time, before it ever leaves the worker.\n *\n * The Node backend recorder persists the same two, plus the inbound request's\n * `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list\n * has not followed it there, so a workerd recording of an authenticated server\n * render still carries no session cookie.\n */\nexport const CAPTURED_HEADERS = [\n  \"content-type\",\n  FRONTEND_SESSION_ID_HEADER,\n] as const;\n\nexport interface CapturedBody {\n  /** UTF-8 decoded body, truncated to the capture cap. */\n  body: string;\n  /** True when the body exceeded the capture cap or the read was cut short. */\n  truncated: boolean;\n}\n\n/**\n * The fields every capture event carries to say which request, session and trace it belongs to.\n */\ninterface CorrelatedEvent {\n  /** Correlates outbound events to the inbound request being handled. */\n  requestId: string;\n  /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */\n  frontendSessionId?: string;\n  /**\n   * Trace the request's spans belong to (32 hex chars), minted by the shim.\n   *\n   * The shim mints it, rather than the sidecar deriving it from {@link requestId}, so span\n   * assembly is stateless: a sidecar that had to remember `requestId → traceId` would give a\n   * request's SERVER span and its CLIENT children different traces whenever it lost that memory\n   * between two batches — which, for a Worker-hosted sidecar, an eviction can do at any moment.\n   *\n   * Optional so a sidecar keeps working against a shim that predates this field, in which case\n   * it falls back to its own per-`requestId` map.\n   */\n  traceId?: string;\n  /**\n   * Span id of the request's SERVER span (16 hex chars), also minted by the shim: it is the\n   * parent of every CLIENT span the request produced, and the inbound event's own span id.\n   */\n  serverSpanId?: string;\n}\n\ninterface BaseRequestEvent extends CorrelatedEvent {\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /** Lower-cased header name → values. */\n  requestHeaders: Record<string, string[]>;\n  responseHeaders?: Record<string, string[]>;\n  statusCode?: number;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the request failed before a response was produced. */\n  error?: string;\n}\n\n/**\n * The worker's own inbound request (becomes a SERVER span). Bodies are not\n * captured, matching the Node backend recorder's SERVER-span contract.\n */\nexport interface InboundRequestEvent extends BaseRequestEvent {\n  kind: \"inbound\";\n  /**\n   * Where {@link BaseRequestEvent.frontendSessionId} came from. Absent means the browser\n   * minted it and sent it on the request, which is the normal case. `\"backend\"` means the\n   * shim minted it for a document navigation the browser could not tag, and the page may or\n   * may not have gone on to adopt it — a distinction ingestion needs, because an unadopted\n   * backend-minted id names a session that will never exist and must be treated as unstamped.\n   * The sidecar turns it into `meticulous.session_id_origin`.\n   *\n   * Optional, and therefore compatible with an older sidecar (which ignores it) — which is\n   * why adding it does not bump {@link SIDECAR_PROTOCOL_VERSION}, a strict-equality check\n   * whose bump would instead make this shim unusable against one.\n   */\n  sessionIdOrigin?: \"backend\";\n}\n\n/**\n * An outgoing `fetch` call made while handling an inbound request (becomes a\n * CLIENT span).\n */\nexport interface OutboundRequestEvent extends BaseRequestEvent {\n  kind: \"outbound\";\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/**\n * A `fetch` through a Cloudflare binding — a service binding, an assets binding, or a\n * Durable Object stub — made while handling an inbound request (becomes a CLIENT span).\n *\n * Request/Response-shaped like {@link OutboundRequestEvent}, but a distinct kind because the\n * call never leaves the isolate and its URL is whatever the caller invented. Keeping the two\n * apart means a binding call and real egress can never be confused for one another when\n * these spans are eventually mocked.\n */\nexport interface BindingRequestEvent extends BaseRequestEvent {\n  kind: \"binding\";\n  /**\n   * The `env` key the binding was found under. Absent when the instance was never seen on\n   * `env` — most commonly a Durable Object stub, which `namespace.get()` produces rather\n   * than being a binding in its own right.\n   */\n  bindingName?: string;\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/** KV namespace methods the shim records. */\nexport type KvOperation = \"get\" | \"getWithMetadata\" | \"put\" | \"delete\" | \"list\";\n\n/**\n * Why a KV value is absent from an event: workerd handed it over in a form that cannot be\n * persisted as text. A `\"stream\"` value must not even be read — consuming it would take the\n * bytes away from the app — and binary values are skipped deliberately, since KV blobs are\n * large and would both bloat the recording and be mangled by UTF-8 capture.\n */\nexport type KvOmittedReason = \"binary\" | \"stream\";\n\n/**\n * An operation on a Cloudflare KV namespace binding, made while handling an inbound request\n * (becomes a CLIENT span).\n *\n * KV is not HTTP: there is no method, URL or status code, so this event shares nothing with\n * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single\n * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.\n */\nexport interface KvOperationEvent extends CorrelatedEvent {\n  kind: \"kv\";\n  /**\n   * The `env` key the KV namespace was found under. Always present, unlike on a binding\n   * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one\n   * that was never seen on `env` is not recorded at all.\n   */\n  bindingName: string;\n  operation: KvOperation;\n  /**\n   * The key operated on, when it is a single string. Absent for `list` (which spans keys) and\n   * for a bulk `get` (which takes an array) — both keep their arguments in {@link args}.\n   */\n  key?: string;\n  /**\n   * JSON of the call's arguments: the read `type`, the `put` options, the `list` selector.\n   * A `put` value appears as `null` here — it is captured in {@link value} instead, so that\n   * redaction applies to it.\n   */\n  args?: CapturedBody;\n  /** JSON of the value a `put` wrote, with secret-looking fields redacted. */\n  value?: CapturedBody;\n  /**\n   * JSON of what the operation returned: the value for `get`, `{value, metadata}` for\n   * `getWithMetadata`, the key page for `list`. Absent for `put`/`delete`, which return\n   * nothing, and for a value that could not be captured (see {@link omitted}).\n   */\n  result?: CapturedBody;\n  /**\n   * Why the operation's value is missing. Refers to the written value for `put` and to the\n   * read value otherwise — a `put` has no result, so this is never ambiguous.\n   */\n  omitted?: KvOmittedReason;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the operation threw. */\n  error?: string;\n}\n\n/**\n * One postgres.js query made while handling an inbound request (becomes a CLIENT span).\n *\n * Deliberately carries the same fields the Node recorder puts on a postgres.js span rather than\n * anything Worker-specific: `PostgresJsMockStore` builds its match key from those attributes at\n * load time, so a query recorded here replays through the existing Node mock path unchanged.\n * See `postgres/capture.ts` for the serialization, which both surfaces share.\n */\nexport interface PostgresQueryEvent extends CorrelatedEvent {\n  kind: \"postgres\";\n  /** SQL rebuilt from the tagged template's chunks, with `$1`, `$2`… placeholders. */\n  queryText: string;\n  /** JSON of the interpolated values, from `serializePostgresJsArgs`. */\n  params: string;\n  /** `\"\"`, `\"raw\"` or `\"values\"` — the row shape the query asked for. */\n  rowMode: string;\n  /** JSON of the resolved `Result`, capped at {@link MAX_POSTGRES_JS_RESULT_SIZE}. */\n  result?: CapturedBody;\n  /**\n   * JSON of the rejection, from `serializePostgresJsError`. Set instead of {@link result}, and\n   * distinct from the transport-level `error` string on the HTTP-shaped events: this one is a\n   * recorded outcome the replay reproduces, not a note that capture failed.\n   */\n  errorJson?: string;\n  startTimeMs: number;\n  endTimeMs: number;\n}\n\nexport type CaptureEvent =\n  | InboundRequestEvent\n  | OutboundRequestEvent\n  | BindingRequestEvent\n  | KvOperationEvent\n  | PostgresQueryEvent;\n\nexport interface CaptureEventsPayload {\n  events: CaptureEvent[];\n}\n\n/**\n * Answer to `GET {SIDECAR_REPLAY_SESSION_PATH}?sessionId=<id>`: whether the sidecar holds\n * mocks for a session, and the virtual clock anchor to freeze `Date` at while serving it.\n */\nexport interface ReplaySessionInfoResponse {\n  found: boolean;\n  /**\n   * Epoch ms of the session's last recorded activity. The worker freezes its clock here so\n   * that credentials minted during the recording are already issued but not yet expired.\n   */\n  clockAnchorMs?: number;\n}\n\n/** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */\nexport interface OutboundFetchLookupRequest {\n  frontendSessionId: string;\n  replayId: string;\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /**\n   * Request body as captured by `readBodyWithCap`. The sidecar hashes this itself, so the\n   * hash it compares against a recording is derived from byte-identical input on both the\n   * record and replay sides.\n   */\n  requestBody?: CapturedBody;\n}\n\n/**\n * A recorded response to serve, a miss the caller must fail, or an instruction to let the\n * real call through. An unrecognised `outcome` must be treated as `passthrough`, so an older\n * shim keeps working against a newer sidecar.\n */\nexport type OutboundFetchLookupResponse =\n  | {\n      outcome: \"mock\";\n      statusCode: number;\n      body: string;\n      headers: Record<string, string>;\n    }\n  /**\n   * The store was consulted and holds nothing for this call. Replay is hermetic, so the\n   * shim fails the request rather than letting it reach the real service — matching the\n   * Node backend recorder's http/undici mocks.\n   */\n  | { outcome: \"no-mock\" }\n  /**\n   * The call cannot be looked up at all (an unparseable URL), so there is no miss to report.\n   * Also what an older sidecar answers on a miss, in which case the shim degrades to the\n   * pre-`no-mock` fail-open behaviour rather than breaking the app.\n   */\n  | { outcome: \"passthrough\" };\n"],"names":[],"mappings":";;;;;;;;AAMA,MAAa,2BAA2B;;AAGxC,MAAa,kCACX;;;;;AAMF,MAAa,6BAA6B;;AAG1C,MAAa,mBAAmB;;;;;;;;;;AAWhC,MAAa,gCAAgC;AAE7C,MAAa,sBAAsB;;;;;;AAOnC,MAAa,8BAA8B;AAC3C,MAAa,qCAAqC;;;;;;;;;AAUlD,MAAa,4BACX;;;;;;;;;;;AAYF,MAAa,mBAAmB,CAC9B,gBACA,2BACD","debugId":"36a20e1c-cf70-5563-a474-2863eaacfbe8"}

package/dist/provisional-session-id.d.ts

@@ -0,0 +1,58 @@
+//#region src/provisional-session-id.d.ts
+/**
+ * A session id the *backend* mints, for the one request that can never carry one from the
+ * browser: a top-level document navigation. Browsers cannot add custom headers to a
+ * navigation, and on the session-starting navigation the frontend has not minted an id yet
+ * (it does so only once the HTML has arrived and the snippet has run) — so the server-side
+ * render's spans are recorded against no session and nothing about that traffic can be
+ * replayed exactly.
+ *
+ * Everything here is runtime-agnostic on purpose. Both backend recorders mint the same ids
+ * by the same rule and publish them under the same `Server-Timing` metric, and all three are
+ * wire contracts with the page, so there is exactly one implementation — the same reason
+ * kv-capture.ts lives here rather than being written twice. The Node recorder imports these
+ * from the package entry; see `provisional-session-id.ts` in
+ * `@alwaysmeticulous/backend-recorder-js` for the `http.IncomingMessage` adapter, and
+ * `publish-session-id.ts` next door for the workerd one.
+ */
+/**
+ * Reads one request header by its lower-cased name. Both `IncomingMessage.headers[name]`
+ * (after the caller flattens Node's `string | string[]`) and `Headers.get(name)` satisfy it,
+ * which is what lets the rules below be shared.
+ */
+type HeaderReader = (name: string) => string | null | undefined;
+declare const SERVER_TIMING_HEADER = "server-timing";
+/**
+ * The `Server-Timing` metric name carrying a backend-minted session id to the page. A wire
+ * contract with the frontend recorder, which matches on it case-insensitively when reading
+ * `PerformanceNavigationTiming.serverTiming` (see `resolve-session-id.ts` in
+ * packages/recorder). Must be a valid HTTP token — no `.` or `:`, which is why it is not the
+ * dotted span-attribute name.
+ */
+declare const SERVER_TIMING_SESSION_METRIC = "metsession";
+/**
+ * `Server-Timing` is the one response header a document's own JavaScript can read back, and
+ * the navigation entry persists for the document's lifetime — so unlike a header-sniffing
+ * approach this works no matter how late the snippet loads.
+ */
+declare const buildServerTimingSessionEntry: (sessionId: string) => string;
+/**
+ * Mints an id in exactly the frontend recorder's format: `<ISO timestamp>_<nanoid>` (see
+ * `createConfig` in packages/recorder). The format is a wire contract, not cosmetic —
+ * ingestion parses the ISO prefix back out to anchor the inferred-attachment window
+ * (`parseTimestampFromFrontendSessionId` in lambda-upload-sessions), and the page uses it to
+ * reject an id stale enough to have come from a cache.
+ */
+declare const mintProvisionalSessionId: () => string;
+/**
+ * Whether to mint for this inbound request. Deliberately narrow: an id nothing adopts is
+ * worse than no id at all, because a span stamped with a session that never materialises is
+ * excluded from the time-window fallback that would otherwise have caught it. So we mint only
+ * for what is plausibly a browser navigating to a page.
+ *
+ * The caller decides separately whether minting is enabled at all.
+ */
+declare const isProvisionalSessionIdCandidate: (method: string, getHeader: HeaderReader) => boolean;
+//#endregion
+export { HeaderReader, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, buildServerTimingSessionEntry, isProvisionalSessionIdCandidate, mintProvisionalSessionId };
+//# sourceMappingURL=provisional-session-id.d.ts.map

package/dist/provisional-session-id.js

@@ -0,0 +1,75 @@
+
+!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]="6222100c-04df-5fc9-b0f6-dcdf8a7b87ab")}catch(e){}}();
+import "./protocol.js";
+//#region src/provisional-session-id.ts
+const SERVER_TIMING_HEADER = "server-timing";
+/**
+* The `Server-Timing` metric name carrying a backend-minted session id to the page. A wire
+* contract with the frontend recorder, which matches on it case-insensitively when reading
+* `PerformanceNavigationTiming.serverTiming` (see `resolve-session-id.ts` in
+* packages/recorder). Must be a valid HTTP token — no `.` or `:`, which is why it is not the
+* dotted span-attribute name.
+*/
+const SERVER_TIMING_SESSION_METRIC = "metsession";
+/**
+* `Server-Timing` is the one response header a document's own JavaScript can read back, and
+* the navigation entry persists for the document's lifetime — so unlike a header-sniffing
+* approach this works no matter how late the snippet loads.
+*/
+const buildServerTimingSessionEntry = (sessionId) => `${SERVER_TIMING_SESSION_METRIC};desc="${sessionId}"`;
+/**
+* nanoid's default alphabet and length, reproduced rather than imported: this package carries
+* no runtime dependencies, and an id that did not look like every other session id would be a
+* gratuitous difference in S3 keys and URLs. 64 characters divides 256 exactly, so masking a
+* random byte with 63 is uniform — which is how nanoid itself generates them.
+*/
+const ID_ALPHABET = "ModuleSymbhasOwnPr-0123456789ABCDEFGHNRVfgctiUvz_KqYTJkLxpZXIjQW";
+const ID_LENGTH = 21;
+/**
+* Mints an id in exactly the frontend recorder's format: `<ISO timestamp>_<nanoid>` (see
+* `createConfig` in packages/recorder). The format is a wire contract, not cosmetic —
+* ingestion parses the ISO prefix back out to anchor the inferred-attachment window
+* (`parseTimestampFromFrontendSessionId` in lambda-upload-sessions), and the page uses it to
+* reject an id stale enough to have come from a cache.
+*/
+const mintProvisionalSessionId = () => {
+	const bytes = new Uint8Array(ID_LENGTH);
+	crypto.getRandomValues(bytes);
+	let suffix = "";
+	for (const byte of bytes) suffix += ID_ALPHABET[byte & 63];
+	return `${(/* @__PURE__ */ new Date()).toISOString()}_${suffix}`;
+};
+/**
+* Whether to mint for this inbound request. Deliberately narrow: an id nothing adopts is
+* worse than no id at all, because a span stamped with a session that never materialises is
+* excluded from the time-window fallback that would otherwise have caught it. So we mint only
+* for what is plausibly a browser navigating to a page.
+*
+* The caller decides separately whether minting is enabled at all.
+*/
+const isProvisionalSessionIdCandidate = (method, getHeader) => {
+	if (getHeader("x-meticulous-session-id") != null) return false;
+	const normalizedMethod = method.toUpperCase();
+	if (normalizedMethod !== "GET" && normalizedMethod !== "HEAD") return false;
+	return isDocumentNavigation(getHeader);
+};
+/**
+* `Sec-Fetch-Dest` is the exact signal and every current browser sends it: `document` for a
+* navigation, `empty` for an in-page fetch (so a Next.js RSC navigation, which is a fetch, is
+* correctly excluded), `iframe` for a subframe — excluded too, since the top frame owns the
+* session and an iframe recorder reports into it.
+*
+* Absent, the caller is an older browser or not a browser at all (curl, a health check, a
+* crawler), and `Accept` is the only hint left.
+*/
+const isDocumentNavigation = (getHeader) => {
+	const dest = getHeader("sec-fetch-dest");
+	if (typeof dest === "string") return dest === "document";
+	const accept = getHeader("accept");
+	return typeof accept === "string" && accept.includes("text/html");
+};
+//#endregion
+export { SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, buildServerTimingSessionEntry, isProvisionalSessionIdCandidate, mintProvisionalSessionId };
+
+//# sourceMappingURL=provisional-session-id.js.map
+//# debugId=6222100c-04df-5fc9-b0f6-dcdf8a7b87ab

package/dist/provisional-session-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisional-session-id.js","sources":["../src/provisional-session-id.ts"],"sourcesContent":["import { FRONTEND_SESSION_ID_HEADER } from \"./protocol\";\n\n/**\n * A session id the *backend* mints, for the one request that can never carry one from the\n * browser: a top-level document navigation. Browsers cannot add custom headers to a\n * navigation, and on the session-starting navigation the frontend has not minted an id yet\n * (it does so only once the HTML has arrived and the snippet has run) — so the server-side\n * render's spans are recorded against no session and nothing about that traffic can be\n * replayed exactly.\n *\n * Everything here is runtime-agnostic on purpose. Both backend recorders mint the same ids\n * by the same rule and publish them under the same `Server-Timing` metric, and all three are\n * wire contracts with the page, so there is exactly one implementation — the same reason\n * kv-capture.ts lives here rather than being written twice. The Node recorder imports these\n * from the package entry; see `provisional-session-id.ts` in\n * `@alwaysmeticulous/backend-recorder-js` for the `http.IncomingMessage` adapter, and\n * `publish-session-id.ts` next door for the workerd one.\n */\n\n/**\n * Reads one request header by its lower-cased name. Both `IncomingMessage.headers[name]`\n * (after the caller flattens Node's `string | string[]`) and `Headers.get(name)` satisfy it,\n * which is what lets the rules below be shared.\n */\nexport type HeaderReader = (name: string) => string | null | undefined;\n\nexport const SERVER_TIMING_HEADER = \"server-timing\";\n\n/**\n * The `Server-Timing` metric name carrying a backend-minted session id to the page. A wire\n * contract with the frontend recorder, which matches on it case-insensitively when reading\n * `PerformanceNavigationTiming.serverTiming` (see `resolve-session-id.ts` in\n * packages/recorder). Must be a valid HTTP token — no `.` or `:`, which is why it is not the\n * dotted span-attribute name.\n */\nexport const SERVER_TIMING_SESSION_METRIC = \"metsession\";\n\n/**\n * `Server-Timing` is the one response header a document's own JavaScript can read back, and\n * the navigation entry persists for the document's lifetime — so unlike a header-sniffing\n * approach this works no matter how late the snippet loads.\n */\nexport const buildServerTimingSessionEntry = (sessionId: string): string =>\n  `${SERVER_TIMING_SESSION_METRIC};desc=\"${sessionId}\"`;\n\n/**\n * nanoid's default alphabet and length, reproduced rather than imported: this package carries\n * no runtime dependencies, and an id that did not look like every other session id would be a\n * gratuitous difference in S3 keys and URLs. 64 characters divides 256 exactly, so masking a\n * random byte with 63 is uniform — which is how nanoid itself generates them.\n */\nconst ID_ALPHABET =\n  \"ModuleSymbhasOwnPr-0123456789ABCDEFGHNRVfgctiUvz_KqYTJkLxpZXIjQW\";\nconst ID_LENGTH = 21;\n\n/**\n * Mints an id in exactly the frontend recorder's format: `<ISO timestamp>_<nanoid>` (see\n * `createConfig` in packages/recorder). The format is a wire contract, not cosmetic —\n * ingestion parses the ISO prefix back out to anchor the inferred-attachment window\n * (`parseTimestampFromFrontendSessionId` in lambda-upload-sessions), and the page uses it to\n * reject an id stale enough to have come from a cache.\n */\nexport const mintProvisionalSessionId = (): string => {\n  const bytes = new Uint8Array(ID_LENGTH);\n  crypto.getRandomValues(bytes);\n  let suffix = \"\";\n  for (const byte of bytes) {\n    suffix += ID_ALPHABET[byte & 63];\n  }\n  return `${new Date().toISOString()}_${suffix}`;\n};\n\n/**\n * Whether to mint for this inbound request. Deliberately narrow: an id nothing adopts is\n * worse than no id at all, because a span stamped with a session that never materialises is\n * excluded from the time-window fallback that would otherwise have caught it. So we mint only\n * for what is plausibly a browser navigating to a page.\n *\n * The caller decides separately whether minting is enabled at all.\n */\nexport const isProvisionalSessionIdCandidate = (\n  method: string,\n  getHeader: HeaderReader,\n): boolean => {\n  // A request that already names its session needs nothing from us.\n  if (getHeader(FRONTEND_SESSION_ID_HEADER) != null) {\n    return false;\n  }\n  const normalizedMethod = method.toUpperCase();\n  if (normalizedMethod !== \"GET\" && normalizedMethod !== \"HEAD\") {\n    return false;\n  }\n  return isDocumentNavigation(getHeader);\n};\n\n/**\n * `Sec-Fetch-Dest` is the exact signal and every current browser sends it: `document` for a\n * navigation, `empty` for an in-page fetch (so a Next.js RSC navigation, which is a fetch, is\n * correctly excluded), `iframe` for a subframe — excluded too, since the top frame owns the\n * session and an iframe recorder reports into it.\n *\n * Absent, the caller is an older browser or not a browser at all (curl, a health check, a\n * crawler), and `Accept` is the only hint left.\n */\nconst isDocumentNavigation = (getHeader: HeaderReader): boolean => {\n  const dest = getHeader(\"sec-fetch-dest\");\n  if (typeof dest === \"string\") {\n    return dest === \"document\";\n  }\n  const accept = getHeader(\"accept\");\n  return typeof accept === \"string\" && accept.includes(\"text/html\");\n};\n"],"names":[],"mappings":";;;;AA0BA,MAAa,uBAAuB;;;;;;;;AASpC,MAAa,+BAA+B;;;;;;AAO5C,MAAa,iCAAiC,cAC5C,GAAG,6BAA6B,SAAS,UAAU;;;;;;;AAQrD,MAAM,cACJ;AACF,MAAM,YAAY;;;;;;;;AASlB,MAAa,iCAAyC;CACpD,MAAM,QAAQ,IAAI,WAAW,UAAU;AACvC,QAAO,gBAAgB,MAAM;CAC7B,IAAI,SAAS;AACb,MAAK,MAAM,QAAQ,MACjB,WAAU,YAAY,OAAO;AAE/B,QAAO,oBAAG,IAAI,MAAM,EAAC,aAAa,CAAC,GAAG;;;;;;;;;;AAWxC,MAAa,mCACX,QACA,cACY;AAEZ,KAAI,UAAA,0BAAqC,IAAI,KAC3C,QAAO;CAET,MAAM,mBAAmB,OAAO,aAAa;AAC7C,KAAI,qBAAqB,SAAS,qBAAqB,OACrD,QAAO;AAET,QAAO,qBAAqB,UAAU;;;;;;;;;;;AAYxC,MAAM,wBAAwB,cAAqC;CACjE,MAAM,OAAO,UAAU,iBAAiB;AACxC,KAAI,OAAO,SAAS,SAClB,QAAO,SAAS;CAElB,MAAM,SAAS,UAAU,SAAS;AAClC,QAAO,OAAO,WAAW,YAAY,OAAO,SAAS,YAAY","debugId":"6222100c-04df-5fc9-b0f6-dcdf8a7b87ab"}

package/dist/publish-session-id.js

@@ -0,0 +1,41 @@
+
+!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]="f69367d2-e59d-5650-b0fe-e117c8ca00ac")}catch(e){}}();
+import { warnOnce } from "./log.js";
+import { hasWebSocket } from "./outbound-capture.js";
+import { SERVER_TIMING_HEADER, buildServerTimingSessionEntry } from "./provisional-session-id.js";
+//#region src/publish-session-id.ts
+/**
+* Publishes a backend-minted session id to the page on the response it is about to receive,
+* so the frontend recorder adopts it instead of minting its own and the whole page load —
+* server-side render included — ends up under one session id.
+*
+* Returns the response to send, which is not always the one passed in: a `Response` handed
+* back by `fetch` or by an assets binding has immutable headers, and the only way to add one
+* is to rebuild around the same body. Best-effort throughout — a recorder must never break
+* the customer's app, so anything unexpected returns the original response unchanged.
+*
+* Unlike the Node recorder there is no `headersSent` race to lose: workerd flushes the
+* response only once the handler has returned it to us, so even a streaming SSR body still
+* has its headers in front of it at this point.
+*/
+const publishSessionIdOnResponse = (response, sessionId) => {
+	const entry = buildServerTimingSessionEntry(sessionId);
+	try {
+		response.headers.append(SERVER_TIMING_HEADER, entry);
+		return response;
+	} catch {}
+	try {
+		if (hasWebSocket(response) || response.status === 101) return response;
+		const rebuilt = new Response(response.body, response);
+		rebuilt.headers.append(SERVER_TIMING_HEADER, entry);
+		return rebuilt;
+	} catch (error) {
+		warnOnce("publish-session-id", "Failed to publish the backend-minted session id on the response.", error);
+		return response;
+	}
+};
+//#endregion
+export { publishSessionIdOnResponse };
+
+//# sourceMappingURL=publish-session-id.js.map
+//# debugId=f69367d2-e59d-5650-b0fe-e117c8ca00ac

package/dist/publish-session-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-session-id.js","sources":["../src/publish-session-id.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport { hasWebSocket } from \"./outbound-capture\";\nimport {\n  SERVER_TIMING_HEADER,\n  buildServerTimingSessionEntry,\n} from \"./provisional-session-id\";\n\n/**\n * Publishes a backend-minted session id to the page on the response it is about to receive,\n * so the frontend recorder adopts it instead of minting its own and the whole page load —\n * server-side render included — ends up under one session id.\n *\n * Returns the response to send, which is not always the one passed in: a `Response` handed\n * back by `fetch` or by an assets binding has immutable headers, and the only way to add one\n * is to rebuild around the same body. Best-effort throughout — a recorder must never break\n * the customer's app, so anything unexpected returns the original response unchanged.\n *\n * Unlike the Node recorder there is no `headersSent` race to lose: workerd flushes the\n * response only once the handler has returned it to us, so even a streaming SSR body still\n * has its headers in front of it at this point.\n */\nexport const publishSessionIdOnResponse = (\n  response: Response,\n  sessionId: string,\n): Response => {\n  const entry = buildServerTimingSessionEntry(sessionId);\n\n  try {\n    // Appends rather than replaces: apps publish their own server timings, and clobbering\n    // them would be a visible regression in their tooling.\n    response.headers.append(SERVER_TIMING_HEADER, entry);\n    return response;\n  } catch {\n    // Immutable headers. Fall through and rebuild.\n  }\n\n  try {\n    // A WebSocket upgrade carries the socket rather than a body and cannot survive being\n    // rebuilt; it is never a document navigation either, so there is nothing to publish to.\n    if (hasWebSocket(response) || response.status === 101) {\n      return response;\n    }\n    const rebuilt = new Response(response.body, response);\n    rebuilt.headers.append(SERVER_TIMING_HEADER, entry);\n    return rebuilt;\n  } catch (error) {\n    warnOnce(\n      \"publish-session-id\",\n      \"Failed to publish the backend-minted session id on the response.\",\n      error,\n    );\n    return response;\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,8BACX,UACA,cACa;CACb,MAAM,QAAQ,8BAA8B,UAAU;AAEtD,KAAI;AAGF,WAAS,QAAQ,OAAO,sBAAsB,MAAM;AACpD,SAAO;SACD;AAIR,KAAI;AAGF,MAAI,aAAa,SAAS,IAAI,SAAS,WAAW,IAChD,QAAO;EAET,MAAM,UAAU,IAAI,SAAS,SAAS,MAAM,SAAS;AACrD,UAAQ,QAAQ,OAAO,sBAAsB,MAAM;AACnD,SAAO;UACA,OAAO;AACd,WACE,sBACA,oEACA,MACD;AACD,SAAO","debugId":"f69367d2-e59d-5650-b0fe-e117c8ca00ac"}