@rocicorp/zero 1.7.0 → 1.8.0-canary.0

package/out/zero-cache/src/types/processes.d.ts

@@ -15,6 +15,8 @@ export declare const MESSAGE_TYPES: {
     readonly subscribe: "subscribe";
     readonly notify: "notify";
     readonly ready: "ready";
+    readonly backupWatermarkRequest: "backupWatermarkRequest";
+    readonly backupWatermarkResponse: "backupWatermarkResponse";
 };
 export type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];
 export interface Sender {
@@ -47,11 +49,34 @@ export interface Worker extends Subprocess, Receiver {
 export declare const parentWorker: Worker | null;
 export declare function singleProcessMode(): boolean;
 export declare function setSingleProcessMode(enabled?: boolean): void;
+/**
+ * Determines whether a module loaded as a worker process entry point should
+ * start its worker.
+ *
+ * Most workers are launched via {@link childWorker}, which in single-process
+ * mode runs them in-process (no real fork) by invoking their exported
+ * `runWorker` directly; those entry points must therefore *not* self-start in
+ * single-process mode, or they would run twice.
+ *
+ * A worker launched via {@link forkChildWorker}, however, is *always* a real
+ * forked OS process — even in single-process mode — and it inherits the
+ * parent's `SINGLE_PROCESS` env. So {@link singleProcessMode} alone would
+ * wrongly suppress its startup, leaving the parent to spin re-forking a child
+ * that immediately exits. Such a forked child has a non-null
+ * {@link parentWorker} (`process.send` is defined), which is the signal to
+ * start regardless. A standalone direct launch (no parent, not single-process)
+ * also starts.
+ *
+ * @param parent The entry point's {@link parentWorker} (non-null iff forked).
+ * @param isSingleProcessMode The result of {@link singleProcessMode}.
+ */
+export declare function shouldStartWorker(parent: Worker | null, isSingleProcessMode: boolean): boolean;
 /**
  *
  * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL
  */
 export declare function childWorker(moduleUrl: URL, env?: NodeJS.ProcessEnv, ...args: string[]): Worker;
+export declare function forkChildWorker(moduleUrl: URL, env?: NodeJS.ProcessEnv, ...args: string[]): Worker;
 /**
  * Creates two connected `Worker` instances such that messages sent to one
  * via the {@link Worker.send()} method are received by the other's

package/out/zero-cache/src/types/processes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/processes.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,YAAY,MAAM,aAAa,CAAC;AAIvC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX,MAAM,MAAM,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,OAAO,aAAa,EAAE,OAAO,CAAC,CAAC;AAwCrE,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,EACV,UAAU,CAAC,EAAE,UAAU,EACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GACvC,OAAO,CAAC;IAEX,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,UAAW,SAAQ,MAAM,EAAE,YAAY;IACtD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C;;;;OAIG;IACH,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACtC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;IAER;;;;OAIG;IACH,eAAe,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACxC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;CACT;AAED,MAAM,WAAW,MAAO,SAAQ,UAAU,EAAE,QAAQ;CAAG;AAkCvD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,GAAG,IAE5B,CAAC;AAIT,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,OAAc,GAAG,IAAI,CAElE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,GAAG,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CA6BR;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BhD"}
+{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/processes.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,YAAY,MAAM,aAAa,CAAC;AAIvC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;CAQhB,CAAC;AAEX,MAAM,MAAM,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,OAAO,aAAa,EAAE,OAAO,CAAC,CAAC;AAwCrE,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,EACV,UAAU,CAAC,EAAE,UAAU,EACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GACvC,OAAO,CAAC;IAEX,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,UAAW,SAAQ,MAAM,EAAE,YAAY;IACtD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C;;;;OAIG;IACH,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACtC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;IAER;;;;OAIG;IACH,eAAe,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACxC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;CACT;AAED,MAAM,WAAW,MAAO,SAAQ,UAAU,EAAE,QAAQ;CAAG;AAkCvD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,GAAG,IAE5B,CAAC;AAIT,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,OAAc,GAAG,IAAI,CAElE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,mBAAmB,EAAE,OAAO,GAC3B,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,GAAG,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAoBR;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,GAAG,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAER;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BhD"}

package/out/zero-cache/src/types/processes.js

@@ -53,11 +53,35 @@ function singleProcessMode() {
 	return singleProcessOverride || (process.env[SINGLE_PROCESS] ?? "0") !== "0";
 }
 /**
+* Determines whether a module loaded as a worker process entry point should
+* start its worker.
+*
+* Most workers are launched via {@link childWorker}, which in single-process
+* mode runs them in-process (no real fork) by invoking their exported
+* `runWorker` directly; those entry points must therefore *not* self-start in
+* single-process mode, or they would run twice.
+*
+* A worker launched via {@link forkChildWorker}, however, is *always* a real
+* forked OS process — even in single-process mode — and it inherits the
+* parent's `SINGLE_PROCESS` env. So {@link singleProcessMode} alone would
+* wrongly suppress its startup, leaving the parent to spin re-forking a child
+* that immediately exits. Such a forked child has a non-null
+* {@link parentWorker} (`process.send` is defined), which is the signal to
+* start regardless. A standalone direct launch (no parent, not single-process)
+* also starts.
+*
+* @param parent The entry point's {@link parentWorker} (non-null iff forked).
+* @param isSingleProcessMode The result of {@link singleProcessMode}.
+*/
+function shouldStartWorker(parent, isSingleProcessMode) {
+	return parent !== null || !isSingleProcessMode;
+}
+/**
 *
 * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL
 */
 function childWorker(moduleUrl, env, ...args) {
-	args.push(...process.argv.slice(2));
+	args = workerArgs(args);
 	if (singleProcessMode()) {
 		const [parent, child] = inProcChannel();
 		import(moduleUrl.href).then(async ({ default: runWorker }) => {
@@ -72,6 +96,15 @@ function childWorker(moduleUrl, env, ...args) {
 		}).catch((err) => child.emit("error", err));
 		return child;
 	}
+	return forkChildWorkerWithArgs(moduleUrl, env, args);
+}
+function forkChildWorker(moduleUrl, env, ...args) {
+	return forkChildWorkerWithArgs(moduleUrl, env, workerArgs(args));
+}
+function workerArgs(args) {
+	return [...args, ...process.argv.slice(2)];
+}
+function forkChildWorkerWithArgs(moduleUrl, env, args) {
 	return wrap(fork(moduleUrl, args, {
 		detached: platform() !== "win32",
 		serialization: "advanced",
@@ -107,6 +140,6 @@ function inProcChannel() {
 	}))];
 }
 //#endregion
-export { childWorker, parentWorker, singleProcessMode };
+export { childWorker, forkChildWorker, parentWorker, shouldStartWorker, singleProcessMode };
 
 //# sourceMappingURL=processes.js.map

package/out/zero-cache/src/types/processes.js.map

@@ -1 +1 @@
-{"version":3,"file":"processes.js","names":[],"sources":["../../../../../zero-cache/src/types/processes.ts"],"sourcesContent":["import {\n  type ChildProcess,\n  fork,\n  type SendHandle,\n  type Serializable,\n} from 'node:child_process';\nimport EventEmitter from 'node:events';\nimport {platform} from 'node:os';\nimport {pid} from 'node:process';\n\n/**\n * Central registry of message type names, which are used to identify\n * the payload in {@link Message} objects sent between processes. The\n * payloads themselves are implementation specific and defined in each\n * component; only the type name is reserved here to avoid collisions.\n *\n * Receiving logic can call {@link getMessage()} with the name of\n * the message of interest to filter messages to those of interest.\n */\nexport const MESSAGE_TYPES = {\n  handoff: 'handoff',\n  status: 'status',\n  subscribe: 'subscribe',\n  notify: 'notify',\n  ready: 'ready',\n} as const;\n\nexport type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];\n\nfunction getMessage<M extends Message<unknown>>(\n  type: M[0],\n  data: unknown,\n): M[1] | null {\n  if (Array.isArray(data) && data.length === 2 && data[0] === type) {\n    return data[1] as M[1];\n  }\n  return null;\n}\n\nfunction onMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  return e.on('message', (data, sendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      handler(msg, sendHandle);\n    }\n  });\n}\n\nfunction onceMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  const listener = (data: unknown, sendHandle: SendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      e.off('message', listener);\n      handler(msg, sendHandle);\n    }\n  };\n  return e.on('message', listener);\n}\n\nexport interface Sender {\n  send<M extends Message<unknown>>(\n    message: M,\n    sendHandle?: SendHandle,\n    callback?: (error: Error | null) => void,\n  ): boolean;\n\n  kill(signal?: NodeJS.Signals): void;\n}\n\nexport interface Subprocess extends Sender, EventEmitter {\n  pid?: number | undefined;\n}\n\nexport interface Receiver extends EventEmitter {\n  /**\n   * The receiving side of {@link Sender.send()} that is a wrapper around\n   * {@link on}('message', ...) that invokes the `handler` for messages of\n   * the specified `type`.\n   */\n  onMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n\n  /**\n   * The receiving side of {@link Sender.send()} that behaves like\n   * {@link once}('message', ...) that invokes the `handler` for the next\n   * message of the specified `type` and then unsubscribes.\n   */\n  onceMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n}\n\nexport interface Worker extends Subprocess, Receiver {}\n\n/**\n * Adds the {@link Receiver.onMessageType()} and {@link Receiver.onceMessageType()}\n * methods to convert the given `EventEmitter` to a `Receiver`.\n */\nfunction wrap<P extends EventEmitter>(proc: P): P & Receiver {\n  return new Proxy(proc, {\n    get(target: P, prop: string | symbol, receiver: unknown) {\n      switch (prop) {\n        case 'onMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onMessageType(target, type, handler);\n            return receiver; // this\n          };\n        case 'onceMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onceMessageType(target, type, handler);\n            return receiver; // this\n          };\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as P & Receiver;\n}\n\ntype Proc = Pick<ChildProcess, 'send' | 'kill' | 'pid'> & EventEmitter;\n\n/**\n * The parentWorker for forked processes, or `null` if the process was not forked.\n * (Analogous to the `parentPort: MessagePort | null` of the `\"workers\"` library).\n */\nexport const parentWorker: Worker | null = process.send\n  ? wrap(process as Proc)\n  : null;\n\nconst SINGLE_PROCESS = 'SINGLE_PROCESS';\nlet singleProcessOverride = false;\nexport function singleProcessMode(): boolean {\n  return singleProcessOverride || (process.env[SINGLE_PROCESS] ?? '0') !== '0';\n}\n\nexport function setSingleProcessMode(enabled: boolean = true): void {\n  singleProcessOverride = enabled;\n}\n\n/**\n *\n * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL\n */\nexport function childWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  args.push(...process.argv.slice(2));\n\n  if (singleProcessMode()) {\n    const [parent, child] = inProcChannel();\n    import(moduleUrl.href)\n      .then(async ({default: runWorker}) => {\n        try {\n          await runWorker(parent, env ?? process.env, ...args);\n          child.emit('close', 0);\n          return;\n        } catch (err) {\n          child.emit('error', err);\n          child.emit('close', -1);\n        }\n      })\n      .catch(err => child.emit('error', err));\n    return child;\n  }\n  const child = fork(moduleUrl, args, {\n    // For production / non-windows, set `detached` to `true` so that SIGINT is\n    // not automatically propagated and graceful shutdown happens as intended.\n    // For Win32, detached: true causes all subprocesses to open in separate\n    // terminals and breaks inter-process kill signals, so set it to false.\n    detached: platform() !== 'win32',\n    serialization: 'advanced', // use structured clone for IPC\n    env,\n  });\n  return wrap(child);\n}\n\n/**\n * Creates two connected `Worker` instances such that messages sent to one\n * via the {@link Worker.send()} method are received by the other's\n * `on('message', ...)` handler.\n *\n * This is analogous to the two `MessagePort`s of a `MessageChannel`, and\n * is useful for executing code written for inter-process communication\n * in a single process.\n */\nexport function inProcChannel(): [Worker, Worker] {\n  const worker1 = new EventEmitter();\n  const worker2 = new EventEmitter();\n\n  const sendTo =\n    (dest: EventEmitter) =>\n    (\n      message: Serializable,\n      sendHandle?: SendHandle,\n      callback?: (error: Error | null) => void,\n    ) => {\n      dest.emit('message', message, sendHandle);\n      if (callback) {\n        callback(null);\n      }\n      return true;\n    };\n\n  const kill =\n    (dest: EventEmitter) =>\n    (signal: NodeJS.Signals = 'SIGTERM') =>\n      dest.emit(signal, signal);\n\n  return [\n    wrap(\n      Object.assign(worker1, {send: sendTo(worker2), kill: kill(worker2), pid}),\n    ),\n    wrap(\n      Object.assign(worker2, {send: sendTo(worker1), kill: kill(worker1), pid}),\n    ),\n  ];\n}\n"],"mappings":";;;;;AA6BA,SAAS,WACP,MACA,MACa;CACb,IAAI,MAAM,QAAQ,IAAI,KAAK,KAAK,WAAW,KAAK,KAAK,OAAO,MAC1D,OAAO,KAAK;CAEd,OAAO;AACT;AAEA,SAAS,cACP,GACA,MACA,SACA;CACA,OAAO,EAAE,GAAG,YAAY,MAAM,eAAe;EAC3C,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KACF,QAAQ,KAAK,UAAU;CAE3B,CAAC;AACH;AAEA,SAAS,gBACP,GACA,MACA,SACA;CACA,MAAM,YAAY,MAAe,eAA2B;EAC1D,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KAAK;GACP,EAAE,IAAI,WAAW,QAAQ;GACzB,QAAQ,KAAK,UAAU;EACzB;CACF;CACA,OAAO,EAAE,GAAG,WAAW,QAAQ;AACjC;;;;;AA4CA,SAAS,KAA6B,MAAuB;CAC3D,OAAO,IAAI,MAAM,MAAM,EACrB,IAAI,QAAW,MAAuB,UAAmB;EACvD,QAAQ,MAAR;GACE,KAAK,iBACH,QACE,MACA,YACG;IACH,cAAc,QAAQ,MAAM,OAAO;IACnC,OAAO;GACT;GACF,KAAK,mBACH,QACE,MACA,YACG;IACH,gBAAgB,QAAQ,MAAM,OAAO;IACrC,OAAO;GACT;EACJ;EACA,OAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;CAC3C,EACF,CAAC;AACH;;;;;AAQA,IAAa,eAA8B,QAAQ,OAC/C,KAAK,OAAe,IACpB;AAEJ,IAAM,iBAAiB;AACvB,IAAI,wBAAwB;AAC5B,SAAgB,oBAA6B;CAC3C,OAAO,0BAA0B,QAAQ,IAAI,mBAAmB,SAAS;AAC3E;;;;;AAUA,SAAgB,YACd,WACA,KACA,GAAG,MACK;CACR,KAAK,KAAK,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC;CAElC,IAAI,kBAAkB,GAAG;EACvB,MAAM,CAAC,QAAQ,SAAS,cAAc;EACtC,OAAO,UAAU,MACd,KAAK,OAAO,EAAC,SAAS,gBAAe;GACpC,IAAI;IACF,MAAM,UAAU,QAAQ,OAAO,QAAQ,KAAK,GAAG,IAAI;IACnD,MAAM,KAAK,SAAS,CAAC;IACrB;GACF,SAAS,KAAK;IACZ,MAAM,KAAK,SAAS,GAAG;IACvB,MAAM,KAAK,SAAS,EAAE;GACxB;EACF,CAAC,EACA,OAAM,QAAO,MAAM,KAAK,SAAS,GAAG,CAAC;EACxC,OAAO;CACT;CAUA,OAAO,KATO,KAAK,WAAW,MAAM;EAKlC,UAAU,SAAS,MAAM;EACzB,eAAe;EACf;CACF,CACY,CAAK;AACnB;;;;;;;;;;AAWA,SAAgB,gBAAkC;CAChD,MAAM,UAAU,IAAI,aAAa;CACjC,MAAM,UAAU,IAAI,aAAa;CAEjC,MAAM,UACH,UAEC,SACA,YACA,aACG;EACH,KAAK,KAAK,WAAW,SAAS,UAAU;EACxC,IAAI,UACF,SAAS,IAAI;EAEf,OAAO;CACT;CAEF,MAAM,QACH,UACA,SAAyB,cACxB,KAAK,KAAK,QAAQ,MAAM;CAE5B,OAAO,CACL,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,GACA,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,CACF;AACF"}
+{"version":3,"file":"processes.js","names":[],"sources":["../../../../../zero-cache/src/types/processes.ts"],"sourcesContent":["import {\n  type ChildProcess,\n  fork,\n  type SendHandle,\n  type Serializable,\n} from 'node:child_process';\nimport EventEmitter from 'node:events';\nimport {platform} from 'node:os';\nimport {pid} from 'node:process';\n\n/**\n * Central registry of message type names, which are used to identify\n * the payload in {@link Message} objects sent between processes. The\n * payloads themselves are implementation specific and defined in each\n * component; only the type name is reserved here to avoid collisions.\n *\n * Receiving logic can call {@link getMessage()} with the name of\n * the message of interest to filter messages to those of interest.\n */\nexport const MESSAGE_TYPES = {\n  handoff: 'handoff',\n  status: 'status',\n  subscribe: 'subscribe',\n  notify: 'notify',\n  ready: 'ready',\n  backupWatermarkRequest: 'backupWatermarkRequest',\n  backupWatermarkResponse: 'backupWatermarkResponse',\n} as const;\n\nexport type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];\n\nfunction getMessage<M extends Message<unknown>>(\n  type: M[0],\n  data: unknown,\n): M[1] | null {\n  if (Array.isArray(data) && data.length === 2 && data[0] === type) {\n    return data[1] as M[1];\n  }\n  return null;\n}\n\nfunction onMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  return e.on('message', (data, sendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      handler(msg, sendHandle);\n    }\n  });\n}\n\nfunction onceMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  const listener = (data: unknown, sendHandle: SendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      e.off('message', listener);\n      handler(msg, sendHandle);\n    }\n  };\n  return e.on('message', listener);\n}\n\nexport interface Sender {\n  send<M extends Message<unknown>>(\n    message: M,\n    sendHandle?: SendHandle,\n    callback?: (error: Error | null) => void,\n  ): boolean;\n\n  kill(signal?: NodeJS.Signals): void;\n}\n\nexport interface Subprocess extends Sender, EventEmitter {\n  pid?: number | undefined;\n}\n\nexport interface Receiver extends EventEmitter {\n  /**\n   * The receiving side of {@link Sender.send()} that is a wrapper around\n   * {@link on}('message', ...) that invokes the `handler` for messages of\n   * the specified `type`.\n   */\n  onMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n\n  /**\n   * The receiving side of {@link Sender.send()} that behaves like\n   * {@link once}('message', ...) that invokes the `handler` for the next\n   * message of the specified `type` and then unsubscribes.\n   */\n  onceMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n}\n\nexport interface Worker extends Subprocess, Receiver {}\n\n/**\n * Adds the {@link Receiver.onMessageType()} and {@link Receiver.onceMessageType()}\n * methods to convert the given `EventEmitter` to a `Receiver`.\n */\nfunction wrap<P extends EventEmitter>(proc: P): P & Receiver {\n  return new Proxy(proc, {\n    get(target: P, prop: string | symbol, receiver: unknown) {\n      switch (prop) {\n        case 'onMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onMessageType(target, type, handler);\n            return receiver; // this\n          };\n        case 'onceMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onceMessageType(target, type, handler);\n            return receiver; // this\n          };\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as P & Receiver;\n}\n\ntype Proc = Pick<ChildProcess, 'send' | 'kill' | 'pid'> & EventEmitter;\n\n/**\n * The parentWorker for forked processes, or `null` if the process was not forked.\n * (Analogous to the `parentPort: MessagePort | null` of the `\"workers\"` library).\n */\nexport const parentWorker: Worker | null = process.send\n  ? wrap(process as Proc)\n  : null;\n\nconst SINGLE_PROCESS = 'SINGLE_PROCESS';\nlet singleProcessOverride = false;\nexport function singleProcessMode(): boolean {\n  return singleProcessOverride || (process.env[SINGLE_PROCESS] ?? '0') !== '0';\n}\n\nexport function setSingleProcessMode(enabled: boolean = true): void {\n  singleProcessOverride = enabled;\n}\n\n/**\n * Determines whether a module loaded as a worker process entry point should\n * start its worker.\n *\n * Most workers are launched via {@link childWorker}, which in single-process\n * mode runs them in-process (no real fork) by invoking their exported\n * `runWorker` directly; those entry points must therefore *not* self-start in\n * single-process mode, or they would run twice.\n *\n * A worker launched via {@link forkChildWorker}, however, is *always* a real\n * forked OS process — even in single-process mode — and it inherits the\n * parent's `SINGLE_PROCESS` env. So {@link singleProcessMode} alone would\n * wrongly suppress its startup, leaving the parent to spin re-forking a child\n * that immediately exits. Such a forked child has a non-null\n * {@link parentWorker} (`process.send` is defined), which is the signal to\n * start regardless. A standalone direct launch (no parent, not single-process)\n * also starts.\n *\n * @param parent The entry point's {@link parentWorker} (non-null iff forked).\n * @param isSingleProcessMode The result of {@link singleProcessMode}.\n */\nexport function shouldStartWorker(\n  parent: Worker | null,\n  isSingleProcessMode: boolean,\n): boolean {\n  return parent !== null || !isSingleProcessMode;\n}\n\n/**\n *\n * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL\n */\nexport function childWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  args = workerArgs(args);\n\n  if (singleProcessMode()) {\n    const [parent, child] = inProcChannel();\n    import(moduleUrl.href)\n      .then(async ({default: runWorker}) => {\n        try {\n          await runWorker(parent, env ?? process.env, ...args);\n          child.emit('close', 0);\n          return;\n        } catch (err) {\n          child.emit('error', err);\n          child.emit('close', -1);\n        }\n      })\n      .catch(err => child.emit('error', err));\n    return child;\n  }\n  return forkChildWorkerWithArgs(moduleUrl, env, args);\n}\n\nexport function forkChildWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  return forkChildWorkerWithArgs(moduleUrl, env, workerArgs(args));\n}\n\nfunction workerArgs(args: string[]): string[] {\n  return [...args, ...process.argv.slice(2)];\n}\n\nfunction forkChildWorkerWithArgs(\n  moduleUrl: URL,\n  env: NodeJS.ProcessEnv | undefined,\n  args: string[],\n): Worker {\n  const child = fork(moduleUrl, args, {\n    // For production / non-windows, set `detached` to `true` so that SIGINT is\n    // not automatically propagated and graceful shutdown happens as intended.\n    // For Win32, detached: true causes all subprocesses to open in separate\n    // terminals and breaks inter-process kill signals, so set it to false.\n    detached: platform() !== 'win32',\n    serialization: 'advanced', // use structured clone for IPC\n    env,\n  });\n  return wrap(child);\n}\n\n/**\n * Creates two connected `Worker` instances such that messages sent to one\n * via the {@link Worker.send()} method are received by the other's\n * `on('message', ...)` handler.\n *\n * This is analogous to the two `MessagePort`s of a `MessageChannel`, and\n * is useful for executing code written for inter-process communication\n * in a single process.\n */\nexport function inProcChannel(): [Worker, Worker] {\n  const worker1 = new EventEmitter();\n  const worker2 = new EventEmitter();\n\n  const sendTo =\n    (dest: EventEmitter) =>\n    (\n      message: Serializable,\n      sendHandle?: SendHandle,\n      callback?: (error: Error | null) => void,\n    ) => {\n      dest.emit('message', message, sendHandle);\n      if (callback) {\n        callback(null);\n      }\n      return true;\n    };\n\n  const kill =\n    (dest: EventEmitter) =>\n    (signal: NodeJS.Signals = 'SIGTERM') =>\n      dest.emit(signal, signal);\n\n  return [\n    wrap(\n      Object.assign(worker1, {send: sendTo(worker2), kill: kill(worker2), pid}),\n    ),\n    wrap(\n      Object.assign(worker2, {send: sendTo(worker1), kill: kill(worker1), pid}),\n    ),\n  ];\n}\n"],"mappings":";;;;;AA+BA,SAAS,WACP,MACA,MACa;CACb,IAAI,MAAM,QAAQ,IAAI,KAAK,KAAK,WAAW,KAAK,KAAK,OAAO,MAC1D,OAAO,KAAK;CAEd,OAAO;AACT;AAEA,SAAS,cACP,GACA,MACA,SACA;CACA,OAAO,EAAE,GAAG,YAAY,MAAM,eAAe;EAC3C,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KACF,QAAQ,KAAK,UAAU;CAE3B,CAAC;AACH;AAEA,SAAS,gBACP,GACA,MACA,SACA;CACA,MAAM,YAAY,MAAe,eAA2B;EAC1D,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KAAK;GACP,EAAE,IAAI,WAAW,QAAQ;GACzB,QAAQ,KAAK,UAAU;EACzB;CACF;CACA,OAAO,EAAE,GAAG,WAAW,QAAQ;AACjC;;;;;AA4CA,SAAS,KAA6B,MAAuB;CAC3D,OAAO,IAAI,MAAM,MAAM,EACrB,IAAI,QAAW,MAAuB,UAAmB;EACvD,QAAQ,MAAR;GACE,KAAK,iBACH,QACE,MACA,YACG;IACH,cAAc,QAAQ,MAAM,OAAO;IACnC,OAAO;GACT;GACF,KAAK,mBACH,QACE,MACA,YACG;IACH,gBAAgB,QAAQ,MAAM,OAAO;IACrC,OAAO;GACT;EACJ;EACA,OAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;CAC3C,EACF,CAAC;AACH;;;;;AAQA,IAAa,eAA8B,QAAQ,OAC/C,KAAK,OAAe,IACpB;AAEJ,IAAM,iBAAiB;AACvB,IAAI,wBAAwB;AAC5B,SAAgB,oBAA6B;CAC3C,OAAO,0BAA0B,QAAQ,IAAI,mBAAmB,SAAS;AAC3E;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,kBACd,QACA,qBACS;CACT,OAAO,WAAW,QAAQ,CAAC;AAC7B;;;;;AAMA,SAAgB,YACd,WACA,KACA,GAAG,MACK;CACR,OAAO,WAAW,IAAI;CAEtB,IAAI,kBAAkB,GAAG;EACvB,MAAM,CAAC,QAAQ,SAAS,cAAc;EACtC,OAAO,UAAU,MACd,KAAK,OAAO,EAAC,SAAS,gBAAe;GACpC,IAAI;IACF,MAAM,UAAU,QAAQ,OAAO,QAAQ,KAAK,GAAG,IAAI;IACnD,MAAM,KAAK,SAAS,CAAC;IACrB;GACF,SAAS,KAAK;IACZ,MAAM,KAAK,SAAS,GAAG;IACvB,MAAM,KAAK,SAAS,EAAE;GACxB;EACF,CAAC,EACA,OAAM,QAAO,MAAM,KAAK,SAAS,GAAG,CAAC;EACxC,OAAO;CACT;CACA,OAAO,wBAAwB,WAAW,KAAK,IAAI;AACrD;AAEA,SAAgB,gBACd,WACA,KACA,GAAG,MACK;CACR,OAAO,wBAAwB,WAAW,KAAK,WAAW,IAAI,CAAC;AACjE;AAEA,SAAS,WAAW,MAA0B;CAC5C,OAAO,CAAC,GAAG,MAAM,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC;AAC3C;AAEA,SAAS,wBACP,WACA,KACA,MACQ;CAUR,OAAO,KATO,KAAK,WAAW,MAAM;EAKlC,UAAU,SAAS,MAAM;EACzB,eAAe;EACf;CACF,CACY,CAAK;AACnB;;;;;;;;;;AAWA,SAAgB,gBAAkC;CAChD,MAAM,UAAU,IAAI,aAAa;CACjC,MAAM,UAAU,IAAI,aAAa;CAEjC,MAAM,UACH,UAEC,SACA,YACA,aACG;EACH,KAAK,KAAK,WAAW,SAAS,UAAU;EACxC,IAAI,UACF,SAAS,IAAI;EAEf,OAAO;CACT;CAEF,MAAM,QACH,UACA,SAAyB,cACxB,KAAK,KAAK,QAAQ,MAAM;CAE5B,OAAO,CACL,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,GACA,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,CACF;AACF"}

package/out/zero-cache/src/workers/connect-params.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingHttpHeaders } from 'node:http2';
+import type { IncomingHttpHeaders } from 'node:http';
 import { type InitConnectionMessage } from '../../../zero-protocol/src/connect.ts';
 export type ConnectParams = {
     readonly protocolVersion: number;
@@ -15,6 +15,7 @@ export type ConnectParams = {
     readonly initConnectionMsg: InitConnectionMessage | undefined;
     readonly httpCookie: string | undefined;
     readonly origin: string | undefined;
+    readonly requestHeaders?: Readonly<Record<string, string>> | undefined;
 };
 export declare function getConnectParams(protocolVersion: number, url: URL, headers: IncomingHttpHeaders): {
     params: ConnectParams;

package/out/zero-cache/src/workers/connect-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect-params.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/connect-params.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,YAAY,CAAC;AAEpD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,uCAAuC,CAAC;AAG/C,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,mBAAmB,GAE1B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CA0CJ"}
+{"version":3,"file":"connect-params.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/connect-params.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,WAAW,CAAC;AAEnD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,uCAAuC,CAAC;AAG/C,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CACxE,CAAC;AAoBF,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,mBAAmB,GAE1B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CA2CJ"}

package/out/zero-cache/src/workers/connect-params.js

@@ -2,6 +2,19 @@ import { must } from "../../../shared/src/must.js";
 import { decodeSecProtocols } from "../../../zero-protocol/src/connect.js";
 import { URLParams } from "../types/url-params.js";
 //#region ../zero-cache/src/workers/connect-params.ts
+/**
+* Normalizes Node's {@link IncomingHttpHeaders} (whose values are
+* `string | string[] | undefined`) into a plain `Record<string, string>`,
+* joining array values with `, ` and dropping `undefined` values.
+*/
+function normalizeHeaders(headers) {
+	const normalized = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value === void 0) continue;
+		normalized[key] = Array.isArray(value) ? value.join(", ") : value;
+	}
+	return normalized;
+}
 function getConnectParams(protocolVersion, url, headers) {
 	const params = new URLParams(url);
 	try {
@@ -30,7 +43,8 @@ function getConnectParams(protocolVersion, url, headers) {
 				auth: authToken,
 				userID,
 				httpCookie: headers.cookie,
-				origin: headers.origin
+				origin: headers.origin,
+				requestHeaders: normalizeHeaders(headers)
 			},
 			error: null
 		};

package/out/zero-cache/src/workers/connect-params.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect-params.js","names":[],"sources":["../../../../../zero-cache/src/workers/connect-params.ts"],"sourcesContent":["import type {IncomingHttpHeaders} from 'node:http2';\nimport {must} from '../../../shared/src/must.ts';\nimport {\n  decodeSecProtocols,\n  type InitConnectionMessage,\n} from '../../../zero-protocol/src/connect.ts';\nimport {URLParams} from '../types/url-params.ts';\n\nexport type ConnectParams = {\n  readonly protocolVersion: number;\n  readonly clientID: string;\n  readonly clientGroupID: string;\n  readonly profileID: string | null;\n  readonly baseCookie: string | null;\n  readonly timestamp: number;\n  readonly lmID: number;\n  readonly wsID: string;\n  readonly debugPerf: boolean;\n  readonly auth: string | undefined;\n  readonly userID: string | undefined;\n  readonly initConnectionMsg: InitConnectionMessage | undefined;\n  readonly httpCookie: string | undefined;\n  readonly origin: string | undefined;\n};\n\nexport function getConnectParams(\n  protocolVersion: number,\n  url: URL,\n  headers: IncomingHttpHeaders,\n):\n  | {\n      params: ConnectParams;\n      error: null;\n    }\n  | {\n      params: null;\n      error: string;\n    } {\n  const params = new URLParams(url);\n\n  try {\n    const clientID = params.get('clientID', true);\n    const clientGroupID = params.get('clientGroupID', true);\n    const profileID = params.get('profileID', false);\n    const baseCookie = params.get('baseCookie', false);\n    const timestamp = params.getInteger('ts', true);\n    const lmID = params.getInteger('lmid', true);\n    const wsID = params.get('wsid', false) ?? '';\n    const userID = params.get('userID', false) ?? undefined;\n    const debugPerf = params.getBoolean('debugPerf');\n    const {initConnectionMessage, authToken} = decodeSecProtocols(\n      must(headers['sec-websocket-protocol']),\n    );\n\n    return {\n      params: {\n        protocolVersion,\n        clientID,\n        clientGroupID,\n        profileID,\n        baseCookie,\n        timestamp,\n        lmID,\n        wsID,\n        debugPerf,\n        initConnectionMsg: initConnectionMessage,\n        auth: authToken,\n        userID,\n        httpCookie: headers.cookie,\n        origin: headers.origin,\n      },\n      error: null,\n    };\n  } catch (e) {\n    return {\n      params: null,\n      error: e instanceof Error ? e.message : String(e),\n    };\n  }\n}\n"],"mappings":";;;;AAyBA,SAAgB,iBACd,iBACA,KACA,SASI;CACJ,MAAM,SAAS,IAAI,UAAU,GAAG;CAEhC,IAAI;EACF,MAAM,WAAW,OAAO,IAAI,YAAY,IAAI;EAC5C,MAAM,gBAAgB,OAAO,IAAI,iBAAiB,IAAI;EACtD,MAAM,YAAY,OAAO,IAAI,aAAa,KAAK;EAC/C,MAAM,aAAa,OAAO,IAAI,cAAc,KAAK;EACjD,MAAM,YAAY,OAAO,WAAW,MAAM,IAAI;EAC9C,MAAM,OAAO,OAAO,WAAW,QAAQ,IAAI;EAC3C,MAAM,OAAO,OAAO,IAAI,QAAQ,KAAK,KAAK;EAC1C,MAAM,SAAS,OAAO,IAAI,UAAU,KAAK,KAAK,KAAA;EAC9C,MAAM,YAAY,OAAO,WAAW,WAAW;EAC/C,MAAM,EAAC,uBAAuB,cAAa,mBACzC,KAAK,QAAQ,yBAAyB,CACxC;EAEA,OAAO;GACL,QAAQ;IACN;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,mBAAmB;IACnB,MAAM;IACN;IACA,YAAY,QAAQ;IACpB,QAAQ,QAAQ;GAClB;GACA,OAAO;EACT;CACF,SAAS,GAAG;EACV,OAAO;GACL,QAAQ;GACR,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;EAClD;CACF;AACF"}
+{"version":3,"file":"connect-params.js","names":[],"sources":["../../../../../zero-cache/src/workers/connect-params.ts"],"sourcesContent":["import type {IncomingHttpHeaders} from 'node:http';\nimport {must} from '../../../shared/src/must.ts';\nimport {\n  decodeSecProtocols,\n  type InitConnectionMessage,\n} from '../../../zero-protocol/src/connect.ts';\nimport {URLParams} from '../types/url-params.ts';\n\nexport type ConnectParams = {\n  readonly protocolVersion: number;\n  readonly clientID: string;\n  readonly clientGroupID: string;\n  readonly profileID: string | null;\n  readonly baseCookie: string | null;\n  readonly timestamp: number;\n  readonly lmID: number;\n  readonly wsID: string;\n  readonly debugPerf: boolean;\n  readonly auth: string | undefined;\n  readonly userID: string | undefined;\n  readonly initConnectionMsg: InitConnectionMessage | undefined;\n  readonly httpCookie: string | undefined;\n  readonly origin: string | undefined;\n  readonly requestHeaders?: Readonly<Record<string, string>> | undefined;\n};\n\n/**\n * Normalizes Node's {@link IncomingHttpHeaders} (whose values are\n * `string | string[] | undefined`) into a plain `Record<string, string>`,\n * joining array values with `, ` and dropping `undefined` values.\n */\nfunction normalizeHeaders(\n  headers: IncomingHttpHeaders,\n): Record<string, string> {\n  const normalized: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (value === undefined) {\n      continue;\n    }\n    normalized[key] = Array.isArray(value) ? value.join(', ') : value;\n  }\n  return normalized;\n}\n\nexport function getConnectParams(\n  protocolVersion: number,\n  url: URL,\n  headers: IncomingHttpHeaders,\n):\n  | {\n      params: ConnectParams;\n      error: null;\n    }\n  | {\n      params: null;\n      error: string;\n    } {\n  const params = new URLParams(url);\n\n  try {\n    const clientID = params.get('clientID', true);\n    const clientGroupID = params.get('clientGroupID', true);\n    const profileID = params.get('profileID', false);\n    const baseCookie = params.get('baseCookie', false);\n    const timestamp = params.getInteger('ts', true);\n    const lmID = params.getInteger('lmid', true);\n    const wsID = params.get('wsid', false) ?? '';\n    const userID = params.get('userID', false) ?? undefined;\n    const debugPerf = params.getBoolean('debugPerf');\n    const {initConnectionMessage, authToken} = decodeSecProtocols(\n      must(headers['sec-websocket-protocol']),\n    );\n\n    return {\n      params: {\n        protocolVersion,\n        clientID,\n        clientGroupID,\n        profileID,\n        baseCookie,\n        timestamp,\n        lmID,\n        wsID,\n        debugPerf,\n        initConnectionMsg: initConnectionMessage,\n        auth: authToken,\n        userID,\n        httpCookie: headers.cookie,\n        origin: headers.origin,\n        requestHeaders: normalizeHeaders(headers),\n      },\n      error: null,\n    };\n  } catch (e) {\n    return {\n      params: null,\n      error: e instanceof Error ? e.message : String(e),\n    };\n  }\n}\n"],"mappings":";;;;;;;;;AA+BA,SAAS,iBACP,SACwB;CACxB,MAAM,aAAqC,CAAC;CAC5C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAAG;EAClD,IAAI,UAAU,KAAA,GACZ;EAEF,WAAW,OAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,IAAI,IAAI;CAC9D;CACA,OAAO;AACT;AAEA,SAAgB,iBACd,iBACA,KACA,SASI;CACJ,MAAM,SAAS,IAAI,UAAU,GAAG;CAEhC,IAAI;EACF,MAAM,WAAW,OAAO,IAAI,YAAY,IAAI;EAC5C,MAAM,gBAAgB,OAAO,IAAI,iBAAiB,IAAI;EACtD,MAAM,YAAY,OAAO,IAAI,aAAa,KAAK;EAC/C,MAAM,aAAa,OAAO,IAAI,cAAc,KAAK;EACjD,MAAM,YAAY,OAAO,WAAW,MAAM,IAAI;EAC9C,MAAM,OAAO,OAAO,WAAW,QAAQ,IAAI;EAC3C,MAAM,OAAO,OAAO,IAAI,QAAQ,KAAK,KAAK;EAC1C,MAAM,SAAS,OAAO,IAAI,UAAU,KAAK,KAAK,KAAA;EAC9C,MAAM,YAAY,OAAO,WAAW,WAAW;EAC/C,MAAM,EAAC,uBAAuB,cAAa,mBACzC,KAAK,QAAQ,yBAAyB,CACxC;EAEA,OAAO;GACL,QAAQ;IACN;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,mBAAmB;IACnB,MAAM;IACN;IACA,YAAY,QAAQ;IACpB,QAAQ,QAAQ;IAChB,gBAAgB,iBAAiB,OAAO;GAC1C;GACA,OAAO;EACT;CACF,SAAS,GAAG;EACV,OAAO;GACL,QAAQ;GACR,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;EAClD;CACF;AACF"}

package/out/zero-cache/src/workers/replicator.d.ts

@@ -2,7 +2,7 @@ import type { LogContext } from '@rocicorp/logger';
 import * as v from '../../../shared/src/valita.ts';
 import type { ReplicaOptions } from '../config/zero-config.ts';
 import { Notifier } from '../services/replicator/notifier.ts';
-import type { ReplicaStateNotifier, Replicator } from '../services/replicator/replicator.ts';
+import type { ReplicaState, ReplicaStateNotifier, Replicator } from '../services/replicator/replicator.ts';
 import { type PragmaConfig } from '../services/replicator/write-worker-client.ts';
 import type { Worker } from '../types/processes.ts';
 export declare const replicaFileModeSchema: v.Type<"backup" | "serving" | "serving-copy">;
@@ -26,6 +26,6 @@ export declare function handleSubscriptionsFrom(lc: LogContext, subscriber: Work
  * This does not send the initial subscription message. Use {@link subscribeTo}
  * to initiate the subscription.
  */
-export declare function createNotifierFrom(_lc: LogContext, source: Worker): Notifier;
+export declare function createNotifierFrom(_lc: LogContext, source: Worker, onNotify?: (state: ReplicaState) => void): Notifier;
 export declare function subscribeTo(_lc: LogContext, source: Worker): void;
 //# sourceMappingURL=replicator.d.ts.map

package/out/zero-cache/src/workers/replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replicator.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/replicator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAC,QAAQ,EAAC,MAAM,oCAAoC,CAAC;AAC5D,OAAO,KAAK,EAEV,oBAAoB,EACpB,UAAU,EACX,MAAM,sCAAsC,CAAC;AAK9C,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAElD,eAAO,MAAM,qBAAqB,+CAIjC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAErC,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,UAEzE;AA0FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,CAMnE;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,eAAe,EACrB,cAAc,EAAE,cAAc;UAhGd,MAAM;aAAW,OAAO;GA+HzC;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,QAGf;AAID,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,oBAAoB,QA8B/B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAM5E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,QAE1D"}
+{"version":3,"file":"replicator.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/replicator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAC,QAAQ,EAAC,MAAM,oCAAoC,CAAC;AAC5D,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,UAAU,EACX,MAAM,sCAAsC,CAAC;AAK9C,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAElD,eAAO,MAAM,qBAAqB,+CAIjC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAErC,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,UAEzE;AA0FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,CAMnE;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,eAAe,EACrB,cAAc,EAAE,cAAc;UAhGd,MAAM;aAAW,OAAO;GA+HzC;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,QAGf;AAID,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,oBAAoB,QA8B/B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GACvC,QAAQ,CAOV;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,QAE1D"}

package/out/zero-cache/src/workers/replicator.js

@@ -120,9 +120,12 @@ function handleSubscriptionsFrom(lc, subscriber, notifier) {
 * This does not send the initial subscription message. Use {@link subscribeTo}
 * to initiate the subscription.
 */
-function createNotifierFrom(_lc, source) {
+function createNotifierFrom(_lc, source, onNotify) {
 	const notifier = new Notifier();
-	source.onMessageType("notify", (msg) => notifier.notifySubscribers(msg));
+	source.onMessageType("notify", (msg) => {
+		onNotify?.(msg);
+		notifier.notifySubscribers(msg);
+	});
 	return notifier;
 }
 function subscribeTo(_lc, source) {

package/out/zero-cache/src/workers/replicator.js.map

@@ -1 +1 @@
-{"version":3,"file":"replicator.js","names":[],"sources":["../../../../../zero-cache/src/workers/replicator.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {sleep} from '../../../shared/src/sleep.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {Database} from '../../../zqlite/src/db.ts';\nimport type {ReplicaOptions} from '../config/zero-config.ts';\nimport {deleteLiteDB} from '../db/delete-lite-db.ts';\nimport {upgradeReplica} from '../services/change-source/common/replica-schema.ts';\nimport {Notifier} from '../services/replicator/notifier.ts';\nimport type {\n  ReplicaState,\n  ReplicaStateNotifier,\n  Replicator,\n} from '../services/replicator/replicator.ts';\nimport {\n  getAscendingEvents,\n  recordEvent,\n} from '../services/replicator/schema/replication-state.ts';\nimport {\n  applyPragmas,\n  type PragmaConfig,\n} from '../services/replicator/write-worker-client.ts';\nimport type {Worker} from '../types/processes.ts';\n\nexport const replicaFileModeSchema = v.literalUnion(\n  'serving',\n  'serving-copy',\n  'backup',\n);\n\nexport type ReplicaFileMode = v.Infer<typeof replicaFileModeSchema>;\n\nexport type WalMode = 'wal' | 'wal2';\n\nexport function replicaFileName(replicaFile: string, mode: ReplicaFileMode) {\n  return mode === 'serving-copy' ? `${replicaFile}-serving-copy` : replicaFile;\n}\n\nconst MILLIS_PER_HOUR = 1000 * 60 * 60;\nconst MB = 1024 * 1024;\n\nasync function prepare(\n  lc: LogContext,\n  {file, vacuumIntervalHours}: ReplicaOptions,\n  walMode: WalMode,\n  mode: ReplicaFileMode,\n): Promise<{file: string; walMode: WalMode}> {\n  const replica = new Database(lc, file);\n\n  // Perform any upgrades to the replica in case the backup is an\n  // earlier version.\n  await upgradeReplica(lc, `${mode}-replica`, file);\n\n  // Start by folding any (e.g. restored) WAL(2) files into the main db.\n  await setJournalMode(lc, replica, 'delete');\n\n  const [{page_size: pageSize}] = replica.pragma<{page_size: number}>(\n    'page_size',\n  );\n  const [{page_count: pageCount}] = replica.pragma<{page_count: number}>(\n    'page_count',\n  );\n  const [{freelist_count: freelistCount}] = replica.pragma<{\n    freelist_count: number;\n  }>('freelist_count');\n\n  const dbSize = ((pageCount * pageSize) / MB).toFixed(2);\n  const freelistSize = ((freelistCount * pageSize) / MB).toFixed(2);\n\n  // TODO: Consider adding a freelist size or ratio based vacuum trigger.\n  lc.info?.(`Size of db ${file}: ${dbSize} MB (${freelistSize} MB freeable)`);\n\n  // Check for the VACUUM threshold.\n  const events = getAscendingEvents(replica);\n  lc.debug?.(`Runtime events for db ${file}`, {events});\n  if (vacuumIntervalHours !== undefined) {\n    const millisSinceLastEvent =\n      Date.now() - (events.at(-1)?.timestamp.getTime() ?? 0);\n    if (millisSinceLastEvent / MILLIS_PER_HOUR > vacuumIntervalHours) {\n      lc.info?.(`Performing maintenance cleanup on ${file}`);\n      const t0 = performance.now();\n      replica.unsafeMode(true);\n      replica.pragma('journal_mode = OFF');\n      replica.exec('VACUUM');\n      recordEvent(replica, 'vacuum');\n      replica.unsafeMode(false);\n      const t1 = performance.now();\n      lc.info?.(`VACUUM completed (${t1 - t0} ms)`);\n    }\n  }\n\n  await setJournalMode(lc, replica, walMode);\n\n  const pragmas = getPragmaConfig(mode);\n  applyPragmas(replica, pragmas);\n\n  replica.pragma('optimize = 0x10002');\n  lc.info?.(`optimized ${file}`);\n  replica.close();\n  return {file, walMode};\n}\n\n// Setting the journal_mode requires an exclusive lock on the replica.\n// Add resilience against random replica reads (for stats, etc.) by\n// retrying if the database is locked. Note that the busy_timeout doesn't\n// work here.\nasync function setJournalMode(\n  lc: LogContext,\n  replica: Database,\n  mode: 'delete' | 'wal' | 'wal2',\n) {\n  lc.info?.(`setting ${replica.name} to ${mode} mode`);\n  let err: unknown;\n  for (let i = 0; i < 5; i++) {\n    try {\n      replica.pragma(`journal_mode = ${mode}`);\n      return;\n    } catch (e) {\n      lc.warn?.(`error setting journal_mode to ${mode} (attempt ${i + 1})`, e);\n      err = e;\n    }\n    await sleep(500);\n  }\n  throw err;\n}\n\n/**\n * Returns the PragmaConfig for a given replica file mode.\n * This is used by both the main thread (setupReplica) and\n * the write worker thread to apply the same pragma settings.\n */\nexport function getPragmaConfig(mode: ReplicaFileMode): PragmaConfig {\n  return {\n    busyTimeout: 30000,\n    analysisLimit: 1000,\n    walAutocheckpoint: mode === 'backup' ? 0 : undefined,\n  };\n}\n\nexport function setupReplica(\n  lc: LogContext,\n  mode: ReplicaFileMode,\n  replicaOptions: ReplicaOptions,\n) {\n  lc.info?.(`setting up ${mode} replica`);\n\n  switch (mode) {\n    case 'backup':\n      return prepare(lc, replicaOptions, 'wal', mode);\n\n    case 'serving-copy': {\n      // In 'serving-copy' mode, the original file is being used for 'backup'\n      // mode, so we make a copy for servicing sync requests.\n      const {file} = replicaOptions;\n      const copyLocation = replicaFileName(file, mode);\n      deleteLiteDB(copyLocation);\n\n      const start = Date.now();\n      lc.info?.(`copying ${file} to ${copyLocation}`);\n      const replica = new Database(lc, file);\n      replica.prepare(`VACUUM INTO ?`).run(copyLocation);\n      replica.close();\n      lc.info?.(`finished copy (${Date.now() - start} ms)`);\n\n      return prepare(lc, {...replicaOptions, file: copyLocation}, 'wal2', mode);\n    }\n\n    case 'serving':\n      return prepare(lc, replicaOptions, 'wal2', mode);\n\n    default:\n      throw new Error(`Invalid ReplicaMode ${mode}`);\n  }\n}\n\nexport function setUpMessageHandlers(\n  lc: LogContext,\n  replicator: Replicator,\n  parent: Worker,\n) {\n  handleSubscriptionsFrom(lc, parent, replicator);\n}\n\ntype Notification = ['notify', ReplicaState];\n\nexport function handleSubscriptionsFrom(\n  lc: LogContext,\n  subscriber: Worker,\n  notifier: ReplicaStateNotifier,\n) {\n  subscriber.onMessageType('subscribe', async () => {\n    const subscription = notifier.subscribe();\n\n    subscriber.on('close', () => {\n      lc.debug?.(`closing replication subscription from ${subscriber.pid}`);\n      subscription.cancel();\n    });\n\n    for await (const msg of subscription) {\n      try {\n        subscriber.send<Notification>(['notify', msg]);\n      } catch (e) {\n        const log =\n          e instanceof Error &&\n          'code' in e &&\n          // This can happen in a race condition if the subscribing process\n          // is closed before the 'close' message is processed.\n          e.code === 'ERR_IPC_CHANNEL_CLOSED'\n            ? 'warn'\n            : 'error';\n\n        lc[log]?.(\n          `error sending replicator notification to ${subscriber.pid}: ${String(e)}`,\n          e,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Creates a Notifier to relay notifications the notifier of another Worker.\n * This does not send the initial subscription message. Use {@link subscribeTo}\n * to initiate the subscription.\n */\nexport function createNotifierFrom(_lc: LogContext, source: Worker): Notifier {\n  const notifier = new Notifier();\n  source.onMessageType<Notification>('notify', msg =>\n    notifier.notifySubscribers(msg),\n  );\n  return notifier;\n}\n\nexport function subscribeTo(_lc: LogContext, source: Worker) {\n  source.send(['subscribe', {}]);\n}\n"],"mappings":"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"}
+{"version":3,"file":"replicator.js","names":[],"sources":["../../../../../zero-cache/src/workers/replicator.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {sleep} from '../../../shared/src/sleep.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {Database} from '../../../zqlite/src/db.ts';\nimport type {ReplicaOptions} from '../config/zero-config.ts';\nimport {deleteLiteDB} from '../db/delete-lite-db.ts';\nimport {upgradeReplica} from '../services/change-source/common/replica-schema.ts';\nimport {Notifier} from '../services/replicator/notifier.ts';\nimport type {\n  ReplicaState,\n  ReplicaStateNotifier,\n  Replicator,\n} from '../services/replicator/replicator.ts';\nimport {\n  getAscendingEvents,\n  recordEvent,\n} from '../services/replicator/schema/replication-state.ts';\nimport {\n  applyPragmas,\n  type PragmaConfig,\n} from '../services/replicator/write-worker-client.ts';\nimport type {Worker} from '../types/processes.ts';\n\nexport const replicaFileModeSchema = v.literalUnion(\n  'serving',\n  'serving-copy',\n  'backup',\n);\n\nexport type ReplicaFileMode = v.Infer<typeof replicaFileModeSchema>;\n\nexport type WalMode = 'wal' | 'wal2';\n\nexport function replicaFileName(replicaFile: string, mode: ReplicaFileMode) {\n  return mode === 'serving-copy' ? `${replicaFile}-serving-copy` : replicaFile;\n}\n\nconst MILLIS_PER_HOUR = 1000 * 60 * 60;\nconst MB = 1024 * 1024;\n\nasync function prepare(\n  lc: LogContext,\n  {file, vacuumIntervalHours}: ReplicaOptions,\n  walMode: WalMode,\n  mode: ReplicaFileMode,\n): Promise<{file: string; walMode: WalMode}> {\n  const replica = new Database(lc, file);\n\n  // Perform any upgrades to the replica in case the backup is an\n  // earlier version.\n  await upgradeReplica(lc, `${mode}-replica`, file);\n\n  // Start by folding any (e.g. restored) WAL(2) files into the main db.\n  await setJournalMode(lc, replica, 'delete');\n\n  const [{page_size: pageSize}] = replica.pragma<{page_size: number}>(\n    'page_size',\n  );\n  const [{page_count: pageCount}] = replica.pragma<{page_count: number}>(\n    'page_count',\n  );\n  const [{freelist_count: freelistCount}] = replica.pragma<{\n    freelist_count: number;\n  }>('freelist_count');\n\n  const dbSize = ((pageCount * pageSize) / MB).toFixed(2);\n  const freelistSize = ((freelistCount * pageSize) / MB).toFixed(2);\n\n  // TODO: Consider adding a freelist size or ratio based vacuum trigger.\n  lc.info?.(`Size of db ${file}: ${dbSize} MB (${freelistSize} MB freeable)`);\n\n  // Check for the VACUUM threshold.\n  const events = getAscendingEvents(replica);\n  lc.debug?.(`Runtime events for db ${file}`, {events});\n  if (vacuumIntervalHours !== undefined) {\n    const millisSinceLastEvent =\n      Date.now() - (events.at(-1)?.timestamp.getTime() ?? 0);\n    if (millisSinceLastEvent / MILLIS_PER_HOUR > vacuumIntervalHours) {\n      lc.info?.(`Performing maintenance cleanup on ${file}`);\n      const t0 = performance.now();\n      replica.unsafeMode(true);\n      replica.pragma('journal_mode = OFF');\n      replica.exec('VACUUM');\n      recordEvent(replica, 'vacuum');\n      replica.unsafeMode(false);\n      const t1 = performance.now();\n      lc.info?.(`VACUUM completed (${t1 - t0} ms)`);\n    }\n  }\n\n  await setJournalMode(lc, replica, walMode);\n\n  const pragmas = getPragmaConfig(mode);\n  applyPragmas(replica, pragmas);\n\n  replica.pragma('optimize = 0x10002');\n  lc.info?.(`optimized ${file}`);\n  replica.close();\n  return {file, walMode};\n}\n\n// Setting the journal_mode requires an exclusive lock on the replica.\n// Add resilience against random replica reads (for stats, etc.) by\n// retrying if the database is locked. Note that the busy_timeout doesn't\n// work here.\nasync function setJournalMode(\n  lc: LogContext,\n  replica: Database,\n  mode: 'delete' | 'wal' | 'wal2',\n) {\n  lc.info?.(`setting ${replica.name} to ${mode} mode`);\n  let err: unknown;\n  for (let i = 0; i < 5; i++) {\n    try {\n      replica.pragma(`journal_mode = ${mode}`);\n      return;\n    } catch (e) {\n      lc.warn?.(`error setting journal_mode to ${mode} (attempt ${i + 1})`, e);\n      err = e;\n    }\n    await sleep(500);\n  }\n  throw err;\n}\n\n/**\n * Returns the PragmaConfig for a given replica file mode.\n * This is used by both the main thread (setupReplica) and\n * the write worker thread to apply the same pragma settings.\n */\nexport function getPragmaConfig(mode: ReplicaFileMode): PragmaConfig {\n  return {\n    busyTimeout: 30000,\n    analysisLimit: 1000,\n    walAutocheckpoint: mode === 'backup' ? 0 : undefined,\n  };\n}\n\nexport function setupReplica(\n  lc: LogContext,\n  mode: ReplicaFileMode,\n  replicaOptions: ReplicaOptions,\n) {\n  lc.info?.(`setting up ${mode} replica`);\n\n  switch (mode) {\n    case 'backup':\n      return prepare(lc, replicaOptions, 'wal', mode);\n\n    case 'serving-copy': {\n      // In 'serving-copy' mode, the original file is being used for 'backup'\n      // mode, so we make a copy for servicing sync requests.\n      const {file} = replicaOptions;\n      const copyLocation = replicaFileName(file, mode);\n      deleteLiteDB(copyLocation);\n\n      const start = Date.now();\n      lc.info?.(`copying ${file} to ${copyLocation}`);\n      const replica = new Database(lc, file);\n      replica.prepare(`VACUUM INTO ?`).run(copyLocation);\n      replica.close();\n      lc.info?.(`finished copy (${Date.now() - start} ms)`);\n\n      return prepare(lc, {...replicaOptions, file: copyLocation}, 'wal2', mode);\n    }\n\n    case 'serving':\n      return prepare(lc, replicaOptions, 'wal2', mode);\n\n    default:\n      throw new Error(`Invalid ReplicaMode ${mode}`);\n  }\n}\n\nexport function setUpMessageHandlers(\n  lc: LogContext,\n  replicator: Replicator,\n  parent: Worker,\n) {\n  handleSubscriptionsFrom(lc, parent, replicator);\n}\n\ntype Notification = ['notify', ReplicaState];\n\nexport function handleSubscriptionsFrom(\n  lc: LogContext,\n  subscriber: Worker,\n  notifier: ReplicaStateNotifier,\n) {\n  subscriber.onMessageType('subscribe', async () => {\n    const subscription = notifier.subscribe();\n\n    subscriber.on('close', () => {\n      lc.debug?.(`closing replication subscription from ${subscriber.pid}`);\n      subscription.cancel();\n    });\n\n    for await (const msg of subscription) {\n      try {\n        subscriber.send<Notification>(['notify', msg]);\n      } catch (e) {\n        const log =\n          e instanceof Error &&\n          'code' in e &&\n          // This can happen in a race condition if the subscribing process\n          // is closed before the 'close' message is processed.\n          e.code === 'ERR_IPC_CHANNEL_CLOSED'\n            ? 'warn'\n            : 'error';\n\n        lc[log]?.(\n          `error sending replicator notification to ${subscriber.pid}: ${String(e)}`,\n          e,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Creates a Notifier to relay notifications the notifier of another Worker.\n * This does not send the initial subscription message. Use {@link subscribeTo}\n * to initiate the subscription.\n */\nexport function createNotifierFrom(\n  _lc: LogContext,\n  source: Worker,\n  onNotify?: (state: ReplicaState) => void,\n): Notifier {\n  const notifier = new Notifier();\n  source.onMessageType<Notification>('notify', msg => {\n    onNotify?.(msg);\n    void notifier.notifySubscribers(msg);\n  });\n  return notifier;\n}\n\nexport function subscribeTo(_lc: LogContext, source: Worker) {\n  source.send(['subscribe', {}]);\n}\n"],"mappings":"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"}

package/out/zero-cache/src/workers/syncer.d.ts

@@ -14,6 +14,23 @@ import type { Subscription } from '../types/subscription.ts';
 export type SyncerWorkerData = {
     replicatorPort: MessagePort;
 };
+export type ReplicaReadyState = {
+    readonly watermark: string;
+    readonly replicaReadyTimeMs: number;
+};
+export type ServingLagViewSyncer = Pick<ViewSyncer, 'createdAtMs' | 'servedVersion'>;
+export type ServingLagStats = {
+    readonly activeClientGroups: number;
+    readonly laggingClientGroups: number;
+    readonly minMs: number;
+    readonly p50Ms: number;
+    readonly p75Ms: number;
+    readonly p99Ms: number;
+    readonly maxMs: number;
+};
+export declare const MAX_REPLICA_READY_STATES = 10000;
+export declare function computeServingLagStatsMs(now: number, replicaReadyStates: ReplicaReadyState[], viewSyncers: Iterable<ServingLagViewSyncer>): ServingLagStats;
+export declare function computeMaxServingLagMs(now: number, replicaReadyStates: ReplicaReadyState[], viewSyncers: Iterable<ServingLagViewSyncer>): number;
 /**
  * The Syncer worker receives websocket handoffs for "/sync" connections
  * from the Dispatcher in the main thread, and creates websocket

package/out/zero-cache/src/workers/syncer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"syncer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/syncer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAUjD,OAAO,EAAyB,KAAK,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAOzD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,gCAAgC,CAAC;AAC5D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,+BAA+B,CAAC;AAC1D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sCAAsC,CAAC;AAEvE,OAAO,KAAK,EACV,oBAAoB,EACpB,OAAO,EACP,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAC,wBAAwB,EAAC,MAAM,uDAAuD,CAAC;AACpG,OAAO,EAAC,gBAAgB,EAAC,MAAM,8CAA8C,CAAC;AAC9E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AACvE,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAO3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,EAAE,WAAW,CAAC;CAC7B,CAAC;AA4BF;;;;;;GAMG;AACH,qBAAa,MAAO,YAAW,gBAAgB;;IAC7C,QAAQ,CAAC,EAAE,SAAmB;gBAc5B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,UAAU,EAClB,iBAAiB,EAAE,CACjB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,YAAY,CAAC,YAAY,CAAC,EAC/B,gBAAgB,EAAE,gBAAgB,KAC/B,UAAU,GAAG,oBAAoB,EACtC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,GAAG,SAAS,EAC/D,aAAa,EACT,CAAC,CACC,EAAE,EAAE,MAAM,EACV,kBAAkB,EAAE,wBAAwB,KACzC,MAAM,GAAG,OAAO,CAAC,GACtB,SAAS,EACb,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,iBAAiB,GAAG,SAAS;IA6OlD,GAAG;IAIH;;;;;OAKG;IACG,KAAK;IAqBX,IAAI;CAKL"}
+{"version":3,"file":"syncer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/workers/syncer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAUjD,OAAO,EAAyB,KAAK,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAOzD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,gCAAgC,CAAC;AAC5D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,+BAA+B,CAAC;AAC1D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sCAAsC,CAAC;AAEvE,OAAO,KAAK,EACV,oBAAoB,EACpB,OAAO,EACP,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAC,wBAAwB,EAAC,MAAM,uDAAuD,CAAC;AACpG,OAAO,EAAC,gBAAgB,EAAC,MAAM,8CAA8C,CAAC;AAC9E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AACvE,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAO3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,EAAE,WAAW,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,UAAU,EACV,aAAa,GAAG,eAAe,CAChC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAS,CAAC;AA8F/C,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,iBAAiB,EAAE,EACvC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAC1C,eAAe,CAsCjB;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,iBAAiB,EAAE,EACvC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAC1C,MAAM,CAER;AA4BD;;;;;;GAMG;AACH,qBAAa,MAAO,YAAW,gBAAgB;;IAC7C,QAAQ,CAAC,EAAE,SAAmB;gBAiB5B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,UAAU,EAClB,iBAAiB,EAAE,CACjB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,YAAY,CAAC,YAAY,CAAC,EAC/B,gBAAgB,EAAE,gBAAgB,KAC/B,UAAU,GAAG,oBAAoB,EACtC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,GAAG,SAAS,EAC/D,aAAa,EACT,CAAC,CACC,EAAE,EAAE,MAAM,EACV,kBAAkB,EAAE,wBAAwB,KACzC,MAAM,GAAG,OAAO,CAAC,GACtB,SAAS,EACb,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,iBAAiB,GAAG,SAAS;IA2TlD,GAAG;IAIH;;;;;OAKG;IACG,KAAK;IAqBX,IAAI;CAKL"}

package/out/zero-cache/src/workers/syncer.js

@@ -17,6 +17,71 @@ import { resolver } from "@rocicorp/resolver";
 import { WebSocketServer } from "ws";
 import { pid } from "node:process";
 //#region ../zero-cache/src/workers/syncer.ts
+var MAX_REPLICA_READY_STATES = 1e4;
+function boundReplicaReadyStates(replicaReadyStates) {
+	if (replicaReadyStates.length > 1e4) replicaReadyStates.splice(0, replicaReadyStates.length - MAX_REPLICA_READY_STATES);
+}
+function pruneReplicaReadyStates(replicaReadyStates, firstNeededIndex) {
+	if (firstNeededIndex > 0) replicaReadyStates.splice(0, firstNeededIndex);
+	boundReplicaReadyStates(replicaReadyStates);
+}
+function lowerBoundReplicaReadyTimeMs(replicaReadyStates, replicaReadyTimeMs) {
+	let low = 0;
+	let high = replicaReadyStates.length;
+	while (low < high) {
+		const mid = low + Math.floor((high - low) / 2);
+		if (replicaReadyStates[mid].replicaReadyTimeMs < replicaReadyTimeMs) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
+function upperBoundWatermark(replicaReadyStates, watermark) {
+	let low = 0;
+	let high = replicaReadyStates.length;
+	while (low < high) {
+		const mid = low + Math.floor((high - low) / 2);
+		if (replicaReadyStates[mid].watermark <= watermark) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
+function findFirstUnservedIndex(replicaReadyStates, viewSyncer) {
+	const firstReadyAfterCreation = lowerBoundReplicaReadyTimeMs(replicaReadyStates, viewSyncer.createdAtMs);
+	const firstAfterServedVersion = viewSyncer.servedVersion === null ? 0 : upperBoundWatermark(replicaReadyStates, viewSyncer.servedVersion);
+	const firstUnservedIndex = Math.max(firstReadyAfterCreation, firstAfterServedVersion);
+	return firstUnservedIndex < replicaReadyStates.length ? firstUnservedIndex : -1;
+}
+function percentileNearestRank(sortedValues, percentile) {
+	if (sortedValues.length === 0) return 0;
+	return sortedValues[Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(percentile / 100 * sortedValues.length) - 1))];
+}
+function computeServingLagStatsMs(now, replicaReadyStates, viewSyncers) {
+	const lags = [];
+	let laggingClientGroups = 0;
+	let firstNeededIndex = replicaReadyStates.length;
+	for (const viewSyncer of viewSyncers) {
+		const firstUnservedIndex = findFirstUnservedIndex(replicaReadyStates, viewSyncer);
+		if (firstUnservedIndex === -1) {
+			lags.push(0);
+			continue;
+		}
+		firstNeededIndex = Math.min(firstNeededIndex, firstUnservedIndex);
+		const lagMs = Math.max(0, now - replicaReadyStates[firstUnservedIndex].replicaReadyTimeMs);
+		lags.push(lagMs);
+		if (lagMs > 0) laggingClientGroups++;
+	}
+	pruneReplicaReadyStates(replicaReadyStates, firstNeededIndex);
+	lags.sort((a, b) => a - b);
+	return {
+		activeClientGroups: lags.length,
+		laggingClientGroups,
+		minMs: lags[0] ?? 0,
+		p50Ms: percentileNearestRank(lags, 50),
+		p75Ms: percentileNearestRank(lags, 75),
+		p99Ms: percentileNearestRank(lags, 99),
+		maxMs: lags.at(-1) ?? 0
+	};
+}
 function getWebSocketServerOptions(config) {
 	const options = {
 		noServer: true,
@@ -52,10 +117,13 @@ var Syncer = class {
 	#stopped = resolver();
 	#config;
 	#validateLegacyJWT;
+	#replicaReadyStates = [];
+	#servingLagStatsCache;
+	#servingLagStatsCacheClearQueued = false;
 	constructor(lc, config, viewSyncerFactory, mutagenFactory, pusherFactory, parent, validateLegacyJWT) {
 		this.#config = config;
 		this.#validateLegacyJWT = validateLegacyJWT;
-		const notifier = createNotifierFrom(lc, parent);
+		const notifier = createNotifierFrom(lc, parent, (state) => this.#recordReplicaReadyState(state));
 		subscribeTo(lc, parent);
 		this.#lc = lc;
 		this.#viewSyncers = new ServiceRunner(lc, (id) => viewSyncerFactory(id, notifier.subscribe(), this.#drainCoordinator), (v) => v.keepalive());
@@ -76,6 +144,53 @@ var Syncer = class {
 			for (const vs of this.#viewSyncers.getServices()) total += vs.rowCount;
 			result.observe(total);
 		});
+		getOrCreateGauge("sync", "serving-lag", {
+			description: "Maximum time active ViewSyncer client groups have had unserved replica changes. A change is served after IVM advancement, CVR flush, and pokeEnd.",
+			unit: "millisecond"
+		}).addCallback((result) => {
+			result.observe(this.#computeServingLagStats().maxMs);
+		});
+		getOrCreateGauge("sync", "serving-lag-stats", {
+			description: "Distribution of time active ViewSyncer client groups have had unserved replica changes. A change is served after IVM advancement, CVR flush, and pokeEnd.",
+			unit: "millisecond"
+		}).addCallback((result) => {
+			const stats = this.#computeServingLagStats();
+			result.observe(stats.minMs, { stat: "min" });
+			result.observe(stats.p50Ms, { stat: "p50" });
+			result.observe(stats.p75Ms, { stat: "p75" });
+			result.observe(stats.p99Ms, { stat: "p99" });
+			result.observe(stats.maxMs, { stat: "max" });
+		});
+		getOrCreateGauge("sync", "serving-lagging-client-groups", "Number of active client groups with unserved replica changes").addCallback((result) => {
+			result.observe(this.#computeServingLagStats().laggingClientGroups);
+		});
+	}
+	#computeServingLagStats() {
+		if (this.#servingLagStatsCache) return this.#servingLagStatsCache;
+		const stats = computeServingLagStatsMs(Date.now(), this.#replicaReadyStates, this.#viewSyncers.getServices());
+		this.#servingLagStatsCache = stats;
+		if (!this.#servingLagStatsCacheClearQueued) {
+			this.#servingLagStatsCacheClearQueued = true;
+			queueMicrotask(() => {
+				this.#servingLagStatsCache = void 0;
+				this.#servingLagStatsCacheClearQueued = false;
+			});
+		}
+		return stats;
+	}
+	#recordReplicaReadyState(state) {
+		if (state.watermark === void 0 || state.replicaReadyTimeMs === void 0) return;
+		const last = this.#replicaReadyStates.at(-1);
+		if (last && last.watermark >= state.watermark) return;
+		this.#replicaReadyStates.push({
+			watermark: state.watermark,
+			replicaReadyTimeMs: state.replicaReadyTimeMs
+		});
+		if (this.#viewSyncers.size === 0) {
+			this.#replicaReadyStates.length = 0;
+			return;
+		}
+		boundReplicaReadyStates(this.#replicaReadyStates);
 	}
 	#createConnection = async (ws, params) => {
 		this.#lc.debug?.("creating connection", params.clientGroupID, params.clientID);