@rocicorp/zero 1.10.0-canary.0 → 1.10.0-canary.2

package/out/zero-cache/src/services/litestream/metrics.js

@@ -1,7 +1,7 @@
 import { LONG_DURATION_HISTOGRAM_BOUNDARIES_S, getOrCreateCounter, getOrCreateHistogram } from "../../observability/metrics.js";
 //#region ../zero-cache/src/services/litestream/metrics.ts
-function litestreamRestoreMetricAttrs(config, role, backupURL = config.litestream.backupURL) {
-	const { executable, executableV5, restoreUsingV5 } = config.litestream;
+function litestreamRestoreMetricAttrs(config, role, backupURL = config.backupURL) {
+	const { executable, executableV5, restoreUsingV5 } = config;
 	const selectedExecutable = (restoreUsingV5 ? executableV5 : executable) ?? executable;
 	return {
 		role,
@@ -13,8 +13,8 @@ function litestreamRestoreMetricAttrs(config, role, backupURL = config.litestrea
 function litestreamBackupMetricAttrs(config) {
 	return {
 		role: "replication_manager",
-		backup_scheme: litestreamBackupScheme(config.litestream.backupURL),
-		litestream: config.litestream.executableV5 !== void 0 && config.litestream.executable === config.litestream.executableV5 ? "v5" : "legacy"
+		backup_scheme: litestreamBackupScheme(config.backupURL),
+		litestream: config.executableV5 !== void 0 && config.executable === config.executableV5 ? "v5" : "legacy"
 	};
 }
 function litestreamBackupProcessMetricAttrs(config) {
@@ -41,8 +41,8 @@ function litestreamBackupScheme(backupURL) {
 }
 function litestreamMultipartMetricAttrs(config) {
 	return {
-		multipart_concurrency: config.litestream.multipartConcurrency,
-		multipart_size_mib: Math.round(config.litestream.multipartSize / 1024 / 1024)
+		multipart_concurrency: config.multipartConcurrency,
+		multipart_size_mib: Math.round(config.multipartSize / 1024 / 1024)
 	};
 }
 function litestreamRestoreRuns() {
@@ -63,9 +63,6 @@ function litestreamBackupProcessRuns() {
 function litestreamRestoreDuration() {
 	return litestreamDurationHistogram("litestream.restore.duration", "Wall-clock duration of a litestream restore run, labeled by result.");
 }
-function litestreamRestoreWaitDuration() {
-	return litestreamDurationHistogram("litestream.restore.wait_duration", "Time spent waiting for the replication-manager snapshot status before restoring.");
-}
 function litestreamRestoreProcessDuration() {
 	return litestreamDurationHistogram("litestream.restore.process_duration", "Wall-clock duration of the litestream restore subprocess.");
 }
@@ -92,6 +89,6 @@ function litestreamDurationHistogram(name, description) {
 	});
 }
 //#endregion
-export { litestreamBackupListDuration, litestreamBackupMetricAttrs, litestreamBackupProcessDuration, litestreamBackupProcessMetricAttrs, litestreamBackupProcessRuns, litestreamBackupVerificationDuration, litestreamMonitorMetricAttrs, litestreamRestoreAttempts, litestreamRestoreDuration, litestreamRestoreMetricAttrs, litestreamRestoreProcessDuration, litestreamRestoreRuns, litestreamRestoreValidationDuration, litestreamRestoreWaitDuration, litestreamRestoredDbBytes, litestreamSnapshotReservationDuration };
+export { litestreamBackupListDuration, litestreamBackupMetricAttrs, litestreamBackupProcessDuration, litestreamBackupProcessMetricAttrs, litestreamBackupProcessRuns, litestreamBackupVerificationDuration, litestreamMonitorMetricAttrs, litestreamRestoreAttempts, litestreamRestoreDuration, litestreamRestoreMetricAttrs, litestreamRestoreProcessDuration, litestreamRestoreRuns, litestreamRestoreValidationDuration, litestreamRestoredDbBytes, litestreamSnapshotReservationDuration };
 
 //# sourceMappingURL=metrics.js.map

package/out/zero-cache/src/services/litestream/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../../zero-cache/src/services/litestream/metrics.ts"],"sourcesContent":["import type {ZeroConfig} from '../../config/zero-config.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateHistogram,\n  LONG_DURATION_HISTOGRAM_BOUNDARIES_S,\n} from '../../observability/metrics.ts';\n\nexport type LitestreamRole = 'replication_manager' | 'view_syncer';\nexport type LitestreamVersion = 'legacy' | 'v5';\n\nexport type LitestreamMetricAttrs = {\n  role: LitestreamRole;\n  backup_scheme: string;\n  litestream: LitestreamVersion;\n};\n\ntype LitestreamMultipartMetricAttrs = {\n  multipart_concurrency: number;\n  multipart_size_mib: number;\n};\n\nexport function litestreamRestoreMetricAttrs(\n  config: ZeroConfig,\n  role: LitestreamRole,\n  backupURL = config.litestream.backupURL,\n): LitestreamMetricAttrs & LitestreamMultipartMetricAttrs {\n  const {executable, executableV5, restoreUsingV5} = config.litestream;\n  const selectedExecutable =\n    (restoreUsingV5 ? executableV5 : executable) ?? executable;\n  return {\n    role,\n    backup_scheme: litestreamBackupScheme(backupURL),\n    litestream:\n      executableV5 !== undefined && selectedExecutable === executableV5\n        ? 'v5'\n        : 'legacy',\n    ...litestreamMultipartMetricAttrs(config),\n  };\n}\n\nexport function litestreamBackupMetricAttrs(\n  config: ZeroConfig,\n): LitestreamMetricAttrs {\n  return {\n    role: 'replication_manager',\n    backup_scheme: litestreamBackupScheme(config.litestream.backupURL),\n    litestream:\n      config.litestream.executableV5 !== undefined &&\n      config.litestream.executable === config.litestream.executableV5\n        ? 'v5'\n        : 'legacy',\n  };\n}\n\nexport function litestreamBackupProcessMetricAttrs(\n  config: ZeroConfig,\n): LitestreamMetricAttrs & LitestreamMultipartMetricAttrs {\n  return {\n    ...litestreamBackupMetricAttrs(config),\n    ...litestreamMultipartMetricAttrs(config),\n  };\n}\n\nexport function litestreamMonitorMetricAttrs(\n  backupURL: string,\n  litestream: LitestreamVersion,\n  role: LitestreamRole,\n): LitestreamMetricAttrs {\n  return {\n    role,\n    backup_scheme: litestreamBackupScheme(backupURL),\n    litestream,\n  };\n}\n\nfunction litestreamBackupScheme(backupURL: string | undefined): string {\n  if (!backupURL) {\n    return 'unknown';\n  }\n  try {\n    const protocol = new URL(backupURL).protocol;\n    return protocol.endsWith(':') ? protocol.slice(0, -1) : protocol;\n  } catch {\n    return 'unknown';\n  }\n}\n\nfunction litestreamMultipartMetricAttrs(\n  config: ZeroConfig,\n): LitestreamMultipartMetricAttrs {\n  return {\n    multipart_concurrency: config.litestream.multipartConcurrency,\n    multipart_size_mib: Math.round(\n      config.litestream.multipartSize / 1024 / 1024,\n    ),\n  };\n}\n\nexport function litestreamRestoreRuns() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.restore.runs',\n    'Litestream restore runs, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreAttempts() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.restore.attempts',\n    'Litestream restore subprocess attempts, labeled by result.',\n  );\n}\n\nexport function litestreamRestoredDbBytes() {\n  return getOrCreateCounter('replica', 'litestream.restore.db_bytes', {\n    description:\n      'SQLite database bytes restored by successful litestream restores.',\n    unit: 'bytes',\n  });\n}\n\nexport function litestreamBackupProcessRuns() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.backup.process_runs',\n    'Litestream backup process exits, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.duration',\n    'Wall-clock duration of a litestream restore run, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreWaitDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.wait_duration',\n    'Time spent waiting for the replication-manager snapshot status before restoring.',\n  );\n}\n\nexport function litestreamRestoreProcessDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.process_duration',\n    'Wall-clock duration of the litestream restore subprocess.',\n  );\n}\n\nexport function litestreamRestoreValidationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.validation_duration',\n    'Time spent validating a restored replica database.',\n  );\n}\n\nexport function litestreamBackupProcessDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.process_duration',\n    'Runtime duration of the litestream backup subprocess before it exits.',\n  );\n}\n\nexport function litestreamBackupListDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.list_duration',\n    'Duration of litestream backup destination listing commands.',\n  );\n}\n\nexport function litestreamBackupVerificationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.verification_duration',\n    'Duration of verifying the actual backup state in the backup destination.',\n  );\n}\n\nexport function litestreamSnapshotReservationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.snapshot.reservation_duration',\n    'Duration of a snapshot reservation while a view-syncer restores and subscribes.',\n  );\n}\n\nfunction litestreamDurationHistogram(name: string, description: string) {\n  return getOrCreateHistogram('replica', name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LONG_DURATION_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n"],"mappings":";;AAqBA,SAAgB,6BACd,QACA,MACA,YAAY,OAAO,WAAW,WAC0B;CACxD,MAAM,EAAC,YAAY,cAAc,mBAAkB,OAAO;CAC1D,MAAM,sBACH,iBAAiB,eAAe,eAAe;CAClD,OAAO;EACL;EACA,eAAe,uBAAuB,SAAS;EAC/C,YACE,iBAAiB,KAAA,KAAa,uBAAuB,eACjD,OACA;EACN,GAAG,+BAA+B,MAAM;CAC1C;AACF;AAEA,SAAgB,4BACd,QACuB;CACvB,OAAO;EACL,MAAM;EACN,eAAe,uBAAuB,OAAO,WAAW,SAAS;EACjE,YACE,OAAO,WAAW,iBAAiB,KAAA,KACnC,OAAO,WAAW,eAAe,OAAO,WAAW,eAC/C,OACA;CACR;AACF;AAEA,SAAgB,mCACd,QACwD;CACxD,OAAO;EACL,GAAG,4BAA4B,MAAM;EACrC,GAAG,+BAA+B,MAAM;CAC1C;AACF;AAEA,SAAgB,6BACd,WACA,YACA,MACuB;CACvB,OAAO;EACL;EACA,eAAe,uBAAuB,SAAS;EAC/C;CACF;AACF;AAEA,SAAS,uBAAuB,WAAuC;CACrE,IAAI,CAAC,WACH,OAAO;CAET,IAAI;EACF,MAAM,WAAW,IAAI,IAAI,SAAS,EAAE;EACpC,OAAO,SAAS,SAAS,GAAG,IAAI,SAAS,MAAM,GAAG,EAAE,IAAI;CAC1D,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,+BACP,QACgC;CAChC,OAAO;EACL,uBAAuB,OAAO,WAAW;EACzC,oBAAoB,KAAK,MACvB,OAAO,WAAW,gBAAgB,OAAO,IAC3C;CACF;AACF;AAEA,SAAgB,wBAAwB;CACtC,OAAO,mBACL,WACA,2BACA,6CACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,mBACL,WACA,+BACA,4DACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,mBAAmB,WAAW,+BAA+B;EAClE,aACE;EACF,MAAM;CACR,CAAC;AACH;AAEA,SAAgB,8BAA8B;CAC5C,OAAO,mBACL,WACA,kCACA,qDACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,4BACL,+BACA,qEACF;AACF;AAEA,SAAgB,gCAAgC;CAC9C,OAAO,4BACL,oCACA,kFACF;AACF;AAEA,SAAgB,mCAAmC;CACjD,OAAO,4BACL,uCACA,2DACF;AACF;AAEA,SAAgB,sCAAsC;CACpD,OAAO,4BACL,0CACA,oDACF;AACF;AAEA,SAAgB,kCAAkC;CAChD,OAAO,4BACL,sCACA,uEACF;AACF;AAEA,SAAgB,+BAA+B;CAC7C,OAAO,4BACL,mCACA,6DACF;AACF;AAEA,SAAgB,uCAAuC;CACrD,OAAO,4BACL,2CACA,0EACF;AACF;AAEA,SAAgB,wCAAwC;CACtD,OAAO,4BACL,4CACA,iFACF;AACF;AAEA,SAAS,4BAA4B,MAAc,aAAqB;CACtE,OAAO,qBAAqB,WAAW,MAAM;EAC3C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH"}
+{"version":3,"file":"metrics.js","names":[],"sources":["../../../../../../zero-cache/src/services/litestream/metrics.ts"],"sourcesContent":["import type {LitestreamConfig} from '../../config/normalize.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateHistogram,\n  LONG_DURATION_HISTOGRAM_BOUNDARIES_S,\n} from '../../observability/metrics.ts';\n\nexport type LitestreamRole = 'replication_manager' | 'view_syncer';\nexport type LitestreamVersion = 'legacy' | 'v5';\n\nexport type LitestreamMetricAttrs = {\n  role: LitestreamRole;\n  backup_scheme: string;\n  litestream: LitestreamVersion;\n};\n\ntype LitestreamMultipartMetricAttrs = {\n  multipart_concurrency: number;\n  multipart_size_mib: number;\n};\n\nexport function litestreamRestoreMetricAttrs(\n  config: LitestreamConfig,\n  role: LitestreamRole,\n  backupURL = config.backupURL,\n): LitestreamMetricAttrs & LitestreamMultipartMetricAttrs {\n  const {executable, executableV5, restoreUsingV5} = config;\n  const selectedExecutable =\n    (restoreUsingV5 ? executableV5 : executable) ?? executable;\n  return {\n    role,\n    backup_scheme: litestreamBackupScheme(backupURL),\n    litestream:\n      executableV5 !== undefined && selectedExecutable === executableV5\n        ? 'v5'\n        : 'legacy',\n    ...litestreamMultipartMetricAttrs(config),\n  };\n}\n\nexport function litestreamBackupMetricAttrs(\n  config: LitestreamConfig,\n): LitestreamMetricAttrs {\n  return {\n    role: 'replication_manager',\n    backup_scheme: litestreamBackupScheme(config.backupURL),\n    litestream:\n      config.executableV5 !== undefined &&\n      config.executable === config.executableV5\n        ? 'v5'\n        : 'legacy',\n  };\n}\n\nexport function litestreamBackupProcessMetricAttrs(\n  config: LitestreamConfig,\n): LitestreamMetricAttrs & LitestreamMultipartMetricAttrs {\n  return {\n    ...litestreamBackupMetricAttrs(config),\n    ...litestreamMultipartMetricAttrs(config),\n  };\n}\n\nexport function litestreamMonitorMetricAttrs(\n  backupURL: string,\n  litestream: LitestreamVersion,\n  role: LitestreamRole,\n): LitestreamMetricAttrs {\n  return {\n    role,\n    backup_scheme: litestreamBackupScheme(backupURL),\n    litestream,\n  };\n}\n\nfunction litestreamBackupScheme(backupURL: string | undefined): string {\n  if (!backupURL) {\n    return 'unknown';\n  }\n  try {\n    const protocol = new URL(backupURL).protocol;\n    return protocol.endsWith(':') ? protocol.slice(0, -1) : protocol;\n  } catch {\n    return 'unknown';\n  }\n}\n\nfunction litestreamMultipartMetricAttrs(\n  config: LitestreamConfig,\n): LitestreamMultipartMetricAttrs {\n  return {\n    multipart_concurrency: config.multipartConcurrency,\n    multipart_size_mib: Math.round(config.multipartSize / 1024 / 1024),\n  };\n}\n\nexport function litestreamRestoreRuns() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.restore.runs',\n    'Litestream restore runs, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreAttempts() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.restore.attempts',\n    'Litestream restore subprocess attempts, labeled by result.',\n  );\n}\n\nexport function litestreamRestoredDbBytes() {\n  return getOrCreateCounter('replica', 'litestream.restore.db_bytes', {\n    description:\n      'SQLite database bytes restored by successful litestream restores.',\n    unit: 'bytes',\n  });\n}\n\nexport function litestreamBackupProcessRuns() {\n  return getOrCreateCounter(\n    'replica',\n    'litestream.backup.process_runs',\n    'Litestream backup process exits, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.duration',\n    'Wall-clock duration of a litestream restore run, labeled by result.',\n  );\n}\n\nexport function litestreamRestoreWaitDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.wait_duration',\n    'Time spent waiting for the replication-manager snapshot status before restoring.',\n  );\n}\n\nexport function litestreamRestoreProcessDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.process_duration',\n    'Wall-clock duration of the litestream restore subprocess.',\n  );\n}\n\nexport function litestreamRestoreValidationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.restore.validation_duration',\n    'Time spent validating a restored replica database.',\n  );\n}\n\nexport function litestreamBackupProcessDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.process_duration',\n    'Runtime duration of the litestream backup subprocess before it exits.',\n  );\n}\n\nexport function litestreamBackupListDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.list_duration',\n    'Duration of litestream backup destination listing commands.',\n  );\n}\n\nexport function litestreamBackupVerificationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.backup.verification_duration',\n    'Duration of verifying the actual backup state in the backup destination.',\n  );\n}\n\nexport function litestreamSnapshotReservationDuration() {\n  return litestreamDurationHistogram(\n    'litestream.snapshot.reservation_duration',\n    'Duration of a snapshot reservation while a view-syncer restores and subscribes.',\n  );\n}\n\nfunction litestreamDurationHistogram(name: string, description: string) {\n  return getOrCreateHistogram('replica', name, {\n    description,\n    unit: 's',\n    bucketBoundaries: LONG_DURATION_HISTOGRAM_BOUNDARIES_S,\n  });\n}\n"],"mappings":";;AAqBA,SAAgB,6BACd,QACA,MACA,YAAY,OAAO,WACqC;CACxD,MAAM,EAAC,YAAY,cAAc,mBAAkB;CACnD,MAAM,sBACH,iBAAiB,eAAe,eAAe;CAClD,OAAO;EACL;EACA,eAAe,uBAAuB,SAAS;EAC/C,YACE,iBAAiB,KAAA,KAAa,uBAAuB,eACjD,OACA;EACN,GAAG,+BAA+B,MAAM;CAC1C;AACF;AAEA,SAAgB,4BACd,QACuB;CACvB,OAAO;EACL,MAAM;EACN,eAAe,uBAAuB,OAAO,SAAS;EACtD,YACE,OAAO,iBAAiB,KAAA,KACxB,OAAO,eAAe,OAAO,eACzB,OACA;CACR;AACF;AAEA,SAAgB,mCACd,QACwD;CACxD,OAAO;EACL,GAAG,4BAA4B,MAAM;EACrC,GAAG,+BAA+B,MAAM;CAC1C;AACF;AAEA,SAAgB,6BACd,WACA,YACA,MACuB;CACvB,OAAO;EACL;EACA,eAAe,uBAAuB,SAAS;EAC/C;CACF;AACF;AAEA,SAAS,uBAAuB,WAAuC;CACrE,IAAI,CAAC,WACH,OAAO;CAET,IAAI;EACF,MAAM,WAAW,IAAI,IAAI,SAAS,EAAE;EACpC,OAAO,SAAS,SAAS,GAAG,IAAI,SAAS,MAAM,GAAG,EAAE,IAAI;CAC1D,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,+BACP,QACgC;CAChC,OAAO;EACL,uBAAuB,OAAO;EAC9B,oBAAoB,KAAK,MAAM,OAAO,gBAAgB,OAAO,IAAI;CACnE;AACF;AAEA,SAAgB,wBAAwB;CACtC,OAAO,mBACL,WACA,2BACA,6CACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,mBACL,WACA,+BACA,4DACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,mBAAmB,WAAW,+BAA+B;EAClE,aACE;EACF,MAAM;CACR,CAAC;AACH;AAEA,SAAgB,8BAA8B;CAC5C,OAAO,mBACL,WACA,kCACA,qDACF;AACF;AAEA,SAAgB,4BAA4B;CAC1C,OAAO,4BACL,+BACA,qEACF;AACF;AASA,SAAgB,mCAAmC;CACjD,OAAO,4BACL,uCACA,2DACF;AACF;AAEA,SAAgB,sCAAsC;CACpD,OAAO,4BACL,0CACA,oDACF;AACF;AAEA,SAAgB,kCAAkC;CAChD,OAAO,4BACL,sCACA,uEACF;AACF;AAEA,SAAgB,+BAA+B;CAC7C,OAAO,4BACL,mCACA,6DACF;AACF;AAEA,SAAgB,uCAAuC;CACrD,OAAO,4BACL,2CACA,0EACF;AACF;AAEA,SAAgB,wCAAwC;CACtD,OAAO,4BACL,4CACA,iFACF;AACF;AAEA,SAAS,4BAA4B,MAAc,aAAqB;CACtE,OAAO,qBAAqB,WAAW,MAAM;EAC3C;EACA,MAAM;EACN,kBAAkB;CACpB,CAAC;AACH"}

package/out/zero-cache/src/services/litestream/vfs-watermark-poller.d.ts

@@ -0,0 +1,57 @@
+import type { LogContext, LogLevel } from '@rocicorp/logger';
+import { type Worker } from '../../types/processes.ts';
+import type { Service } from '../service.ts';
+type LoadableDatabase = {
+    loadExtension(path: string): unknown;
+    close(): void;
+};
+type QueryDatabase = {
+    prepare(sql: string): {
+        get<T>(): T;
+    };
+    close(): void;
+};
+export type BackupWatermarkUpdate = [
+    'backupWatermarkUpdate',
+    {
+        watermark: string;
+        writeTimeMs: number;
+        backupTimeMs: number;
+    }
+];
+export type VfsBackupWatermarkPollerEnvOptions = {
+    readonly backupURL: string;
+    readonly remotePollIntervalMs: number;
+    readonly endpoint?: string | undefined;
+    readonly region?: string | undefined;
+    readonly logLevel?: LogLevel | undefined;
+    readonly logFile?: string | undefined;
+};
+export type VfsBackupWatermarkPollerOptions = {
+    readonly localDbFile: string;
+    readonly backupURL: string;
+    readonly endpoint?: string | undefined;
+    readonly region?: string | undefined;
+    readonly extensionPath: string;
+    readonly remotePollIntervalMs: number;
+};
+type VfsBackupWatermarkPollerDeps = {
+    readonly loaderFactory?: (() => LoadableDatabase) | undefined;
+    readonly databaseFactory?: ((lc: LogContext, uri: string) => QueryDatabase) | undefined;
+};
+export declare function buildLitestreamVfsReplicaURL({ backupURL, endpoint, region, }: {
+    readonly backupURL: string;
+    readonly endpoint?: string | undefined;
+    readonly region?: string | undefined;
+}): string;
+export declare function getVfsEnv(options: VfsBackupWatermarkPollerEnvOptions): NodeJS.ProcessEnv;
+export declare class VfsBackupWatermarkPoller implements Service {
+    #private;
+    readonly id = "backup-watermark-poller";
+    constructor(lc: LogContext, parent: Worker, options: VfsBackupWatermarkPollerOptions, deps?: VfsBackupWatermarkPollerDeps);
+    checkWatermarks(): void;
+    run(): Promise<void>;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=vfs-watermark-poller.d.ts.map

package/out/zero-cache/src/services/litestream/vfs-watermark-poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs-watermark-poller.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/litestream/vfs-watermark-poller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAE,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAK3D,OAAO,EAAC,KAAK,MAAM,EAAC,MAAM,0BAA0B,CAAC;AAErD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,eAAe,CAAC;AAI3C,KAAK,gBAAgB,GAAG;IACtB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;KAAC,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAeF,MAAM,MAAM,qBAAqB,GAAG;IAClC,uBAAuB;IACvB;QACE,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB;CACF,CAAC;AAUF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC,CAAC;AAEF,KAAK,4BAA4B,GAAG;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,gBAAgB,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,eAAe,CAAC,EACrB,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC,GAChD,SAAS,CAAC;CACf,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,EAC3C,SAAS,EACT,QAAQ,EACR,MAAM,GACP,EAAE;IACD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,GAAG,MAAM,CAiBT;AAED,wBAAgB,SAAS,CACvB,OAAO,EAAE,kCAAkC,GAC1C,MAAM,CAAC,UAAU,CAWnB;AAKD,qBAAa,wBAAyB,YAAW,OAAO;;IACtD,QAAQ,CAAC,EAAE,6BAA6B;gBAatC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,+BAA+B,EACxC,IAAI,GAAE,4BAAiC;IAgEzC,eAAe;IAiDT,GAAG;IAkBT,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAItB"}

package/out/zero-cache/src/services/litestream/vfs-watermark-poller.js

@@ -0,0 +1,137 @@
+import { promiseVoid } from "../../../../shared/src/resolved-promises.js";
+import { parse, valita_exports } from "../../../../shared/src/valita.js";
+import "../../types/processes.js";
+import { Database } from "../../../../zqlite/src/db.js";
+import { RunningState } from "../running-state.js";
+import SQLite3Database from "@rocicorp/zero-sqlite3";
+//#region ../zero-cache/src/services/litestream/vfs-watermark-poller.ts
+var DEFAULT_VFS_LOG_LEVEL = "info";
+var watermarkRowSchema = valita_exports.object({
+	watermark: valita_exports.string(),
+	writeTimeMs: valita_exports.number()
+});
+var watermarkQuerySchema = watermarkRowSchema.extend({ backupTime: valita_exports.string() });
+function buildLitestreamVfsReplicaURL({ backupURL, endpoint, region }) {
+	if (endpoint === void 0 && region === void 0) return backupURL;
+	const url = new URL(backupURL);
+	if (url.protocol !== "s3:") return backupURL;
+	if (endpoint !== void 0 && !url.searchParams.has("endpoint")) url.searchParams.set("endpoint", endpoint);
+	if (region !== void 0 && !url.searchParams.has("region")) url.searchParams.set("region", region);
+	return url.toString();
+}
+function getVfsEnv(options) {
+	return {
+		LITESTREAM_REPLICA_URL: buildLitestreamVfsReplicaURL(options),
+		LITESTREAM_LOG_LEVEL: options.logLevel ?? DEFAULT_VFS_LOG_LEVEL,
+		LITESTREAM_LOG_FILE: options.logFile,
+		LITESTREAM_POLL_INTERVAL: `${options.remotePollIntervalMs}ms`
+	};
+}
+var MIN_CHECK_INTERVAL_MS = 1e3;
+var MAX_CHECK_INTERVAL_MS = 6e4;
+var VfsBackupWatermarkPoller = class {
+	id = "backup-watermark-poller";
+	#runningState = new RunningState(this.id);
+	#lc;
+	#parent;
+	#loader;
+	#localDb;
+	#openRemote;
+	#remoteDb = null;
+	#lastRemoteWatermark = null;
+	constructor(lc, parent, options, deps = {}) {
+		lc = lc.withContext("component", "vfs-watermark-poller");
+		this.#lc = lc;
+		this.#parent = parent;
+		const { databaseFactory } = deps;
+		const openDb = (url, type, schema) => {
+			try {
+				const db = databaseFactory ? databaseFactory(lc, url) : new Database(lc, url, { readonly: true });
+				const stmt = db.prepare(type === "local" ? `
+          SELECT stateVersion AS watermark, writeTimeMs FROM "_zero.replicationState"` : `
+          SELECT stateVersion AS watermark, writeTimeMs, litestream_time() as backupTime FROM "_zero.replicationState"`);
+				return {
+					getWatermark: () => parse(stmt.get(), schema),
+					close: () => db.close()
+				};
+			} catch (e) {
+				lc.error?.(`error opening ${url}`, e);
+				throw e;
+			}
+		};
+		this.#localDb = openDb(options.localDbFile, "local", watermarkRowSchema);
+		const loaderFactory = deps.loaderFactory ?? (() => new SQLite3Database(":memory:"));
+		const remoteDbURL = `file:zero-backup.db?${new URLSearchParams({
+			vfs: "litestream",
+			mode: "ro",
+			replica_url: buildLitestreamVfsReplicaURL(options),
+			poll_interval: `${options.remotePollIntervalMs}ms`
+		}).toString()}`;
+		lc.info?.(`Loading VFS ${remoteDbURL} at ${options.extensionPath}`);
+		this.#loader = loaderFactory();
+		this.#loader.loadExtension(options.extensionPath);
+		this.#openRemote = () => openDb(remoteDbURL, "remote", watermarkQuerySchema);
+	}
+	checkWatermarks() {
+		const local = this.#localDb.getWatermark();
+		if (local.watermark !== this.#lastRemoteWatermark?.watermark) {
+			if (!this.#remoteDb) {
+				if (this.#lastRemoteWatermark) this.#lc.debug?.(`local and remote watermarks differ. resuming backup polling`, {
+					local,
+					remote: this.#lastRemoteWatermark
+				});
+				this.#remoteDb = this.#openRemote();
+			}
+			const remote = this.#remoteDb.getWatermark();
+			if (remote.watermark !== this.#lastRemoteWatermark?.watermark) {
+				this.#lc.debug?.(`backup watermark advanced from ${this.#lastRemoteWatermark?.watermark} to ${remote.watermark}`, {
+					local,
+					remote
+				});
+				this.#lastRemoteWatermark = remote;
+				const { watermark, writeTimeMs, backupTime } = remote;
+				const backupTimeMs = new Date(backupTime).getTime();
+				this.#parent.send(["backupWatermarkUpdate", {
+					watermark,
+					writeTimeMs,
+					backupTimeMs
+				}]);
+			}
+		}
+		if (local.watermark === this.#lastRemoteWatermark?.watermark) {
+			if (this.#remoteDb) {
+				this.#lc.debug?.(`local and remote watermarks match. pausing backup polling`, {
+					local,
+					remote: this.#lastRemoteWatermark
+				});
+				this.#remoteDb.close();
+				this.#remoteDb = null;
+			}
+		}
+	}
+	async run() {
+		this.#lc.info?.(`starting backup polling`);
+		let interval = MIN_CHECK_INTERVAL_MS;
+		while (this.#runningState.shouldRun()) {
+			try {
+				this.checkWatermarks();
+				interval = MIN_CHECK_INTERVAL_MS;
+			} catch (e) {
+				this.#lc.warn?.(`error checking local and remote watermarks`, e);
+				interval = Math.min(MAX_CHECK_INTERVAL_MS, interval * 2);
+			}
+			await this.#runningState.sleep(interval);
+		}
+		this.#remoteDb?.close();
+		this.#localDb.close();
+		this.#loader.close();
+	}
+	stop() {
+		this.#runningState.stop(this.#lc);
+		return promiseVoid;
+	}
+};
+//#endregion
+export { VfsBackupWatermarkPoller, getVfsEnv };
+
+//# sourceMappingURL=vfs-watermark-poller.js.map

package/out/zero-cache/src/services/litestream/vfs-watermark-poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs-watermark-poller.js","names":["#runningState","#lc","#parent","#loader","#localDb","#openRemote","#lastRemoteWatermark","#remoteDb"],"sources":["../../../../../../zero-cache/src/services/litestream/vfs-watermark-poller.ts"],"sourcesContent":["import type {LogContext, LogLevel} from '@rocicorp/logger';\nimport Sqlite3Database from '@rocicorp/zero-sqlite3';\nimport {promiseVoid} from '../../../../shared/src/resolved-promises.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {type Worker} from '../../types/processes.ts';\nimport {RunningState} from '../running-state.ts';\nimport type {Service} from '../service.ts';\n\nconst DEFAULT_VFS_LOG_LEVEL = 'info';\n\ntype LoadableDatabase = {\n  loadExtension(path: string): unknown;\n  close(): void;\n};\n\ntype QueryDatabase = {\n  prepare(sql: string): {get<T>(): T};\n  close(): void;\n};\n\nconst watermarkRowSchema = v.object({\n  watermark: v.string(),\n  writeTimeMs: v.number(),\n});\n\nconst watermarkQuerySchema = watermarkRowSchema.extend({\n  backupTime: v.string(),\n});\n\ntype WatermarkQueryResult = v.Infer<typeof watermarkQuerySchema>;\n\ntype WatermarkRow = v.Infer<typeof watermarkRowSchema>;\n\nexport type BackupWatermarkUpdate = [\n  'backupWatermarkUpdate',\n  {\n    watermark: string;\n    writeTimeMs: number;\n    backupTimeMs: number;\n  },\n];\n\ntype WatermarkReader<Result extends WatermarkRow> = {\n  getWatermark(): Result;\n  close(): void;\n};\n\n// Values that must be passed via the ENV to the original process (worker).\n// Some of these will be configurable via the db URI once\n// https://github.com/benbjohnson/litestream/issues/1150 is released.\nexport type VfsBackupWatermarkPollerEnvOptions = {\n  readonly backupURL: string;\n  readonly remotePollIntervalMs: number;\n  readonly endpoint?: string | undefined;\n  readonly region?: string | undefined;\n\n  readonly logLevel?: LogLevel | undefined;\n  readonly logFile?: string | undefined;\n};\n\nexport type VfsBackupWatermarkPollerOptions = {\n  readonly localDbFile: string;\n  readonly backupURL: string;\n  readonly endpoint?: string | undefined;\n  readonly region?: string | undefined;\n\n  readonly extensionPath: string;\n  readonly remotePollIntervalMs: number;\n};\n\ntype VfsBackupWatermarkPollerDeps = {\n  readonly loaderFactory?: (() => LoadableDatabase) | undefined;\n  readonly databaseFactory?:\n    | ((lc: LogContext, uri: string) => QueryDatabase)\n    | undefined;\n};\n\nexport function buildLitestreamVfsReplicaURL({\n  backupURL,\n  endpoint,\n  region,\n}: {\n  readonly backupURL: string;\n  readonly endpoint?: string | undefined;\n  readonly region?: string | undefined;\n}): string {\n  if (endpoint === undefined && region === undefined) {\n    return backupURL;\n  }\n\n  const url = new URL(backupURL);\n  if (url.protocol !== 's3:') {\n    return backupURL;\n  }\n\n  if (endpoint !== undefined && !url.searchParams.has('endpoint')) {\n    url.searchParams.set('endpoint', endpoint);\n  }\n  if (region !== undefined && !url.searchParams.has('region')) {\n    url.searchParams.set('region', region);\n  }\n  return url.toString();\n}\n\nexport function getVfsEnv(\n  options: VfsBackupWatermarkPollerEnvOptions,\n): NodeJS.ProcessEnv {\n  return {\n    LITESTREAM_REPLICA_URL: buildLitestreamVfsReplicaURL(options),\n    LITESTREAM_LOG_LEVEL: options.logLevel ?? DEFAULT_VFS_LOG_LEVEL,\n    LITESTREAM_LOG_FILE: options.logFile,\n\n    // Supported by the rocicorp fork: https://github.com/rocicorp/litestream/pull/20\n    // TODO: Remove and use official build when\n    // https://github.com/benbjohnson/litestream/pull/1157 is released.\n    LITESTREAM_POLL_INTERVAL: `${options.remotePollIntervalMs}ms`,\n  };\n}\n\nconst MIN_CHECK_INTERVAL_MS = 1_000;\nconst MAX_CHECK_INTERVAL_MS = 60_000;\n\nexport class VfsBackupWatermarkPoller implements Service {\n  readonly id = 'backup-watermark-poller';\n  readonly #runningState = new RunningState(this.id);\n  readonly #lc: LogContext;\n  readonly #parent: Worker;\n  readonly #loader: LoadableDatabase;\n\n  readonly #localDb: WatermarkReader<WatermarkRow>;\n  readonly #openRemote: () => WatermarkReader<WatermarkQueryResult>;\n\n  #remoteDb: WatermarkReader<WatermarkQueryResult> | null = null;\n  #lastRemoteWatermark: WatermarkQueryResult | null = null;\n\n  constructor(\n    lc: LogContext,\n    parent: Worker,\n    options: VfsBackupWatermarkPollerOptions,\n    deps: VfsBackupWatermarkPollerDeps = {},\n  ) {\n    lc = lc.withContext('component', 'vfs-watermark-poller');\n    this.#lc = lc;\n    this.#parent = parent;\n\n    const {databaseFactory} = deps;\n    const openDb = <Result extends WatermarkRow>(\n      url: string,\n      type: 'local' | 'remote',\n      schema: v.Type<Result>,\n    ) => {\n      try {\n        const db = databaseFactory\n          ? databaseFactory(lc, url)\n          : new Database(lc, url, {readonly: true});\n        const stmt = db.prepare(\n          type === 'local'\n            ? /*sql*/ `\n          SELECT stateVersion AS watermark, writeTimeMs FROM \"_zero.replicationState\"`\n            : /*sql*/ `\n          SELECT stateVersion AS watermark, writeTimeMs, litestream_time() as backupTime FROM \"_zero.replicationState\"`,\n        );\n        return {\n          getWatermark: () => v.parse(stmt.get(), schema),\n          close: () => db.close(),\n        } satisfies WatermarkReader<Result>;\n      } catch (e) {\n        lc.error?.(`error opening ${url}`, e);\n        throw e;\n      }\n    };\n\n    // Open the local (non-VFS) connection before loading the litestream VFS\n    // extension. Loading the extension registers a process-global\n    // `sqlite3_auto_extension` hook that SQLite invokes on every connection\n    // opened *afterward* in this process (even ones that don't reference\n    // `vfs=litestream`), and a signature bug in that hook currently causes\n    // it to fail such connections. Opening #localDb first sidesteps it,\n    // since already-open connections aren't affected by the hook.\n    this.#localDb = openDb(options.localDbFile, 'local', watermarkRowSchema);\n\n    const loaderFactory =\n      deps.loaderFactory ?? (() => new Sqlite3Database(':memory:'));\n\n    const dbParams = new URLSearchParams({\n      vfs: 'litestream',\n      mode: 'ro',\n      // Support forthcoming in https://github.com/benbjohnson/litestream/issues/1150\n      replica_url: buildLitestreamVfsReplicaURL(options),\n      poll_interval: `${options.remotePollIntervalMs}ms`,\n    });\n    // Note: the filename is arbitrary and only referenced in debug logs.\n    const remoteDbURL = `file:zero-backup.db?${dbParams.toString()}`;\n\n    lc.info?.(`Loading VFS ${remoteDbURL} at ${options.extensionPath}`);\n    this.#loader = loaderFactory();\n    this.#loader.loadExtension(options.extensionPath);\n\n    this.#openRemote = () =>\n      openDb(remoteDbURL, 'remote', watermarkQuerySchema);\n  }\n\n  // public for testing\n  checkWatermarks() {\n    const local = this.#localDb.getWatermark();\n    if (local.watermark !== this.#lastRemoteWatermark?.watermark) {\n      if (!this.#remoteDb) {\n        if (this.#lastRemoteWatermark) {\n          this.#lc.debug?.(\n            `local and remote watermarks differ. resuming backup polling`,\n            {local, remote: this.#lastRemoteWatermark},\n          );\n        }\n        this.#remoteDb = this.#openRemote();\n      }\n      const remote = this.#remoteDb.getWatermark();\n      if (remote.watermark !== this.#lastRemoteWatermark?.watermark) {\n        this.#lc.debug?.(\n          `backup watermark advanced from ${this.#lastRemoteWatermark?.watermark} to ${remote.watermark}`,\n          {local, remote},\n        );\n        this.#lastRemoteWatermark = remote;\n        const {watermark, writeTimeMs, backupTime} = remote;\n        // Note: litestream_time() returns \"latest\" if no LTX files were\n        // loaded:\n        //\n        // https://github.com/benbjohnson/litestream/blob/6d61ef5d007756d62e473daee4c760ac395a55c6/vfs.go#L2448\n        //\n        // but in that case the watermark query would have failed, so it\n        // follows that litestream_time() should always return a valid\n        // timestamp if the watermark query itself succeeded.\n        const backupTimeMs = new Date(backupTime).getTime();\n        this.#parent.send<BackupWatermarkUpdate>([\n          'backupWatermarkUpdate',\n          {watermark, writeTimeMs, backupTimeMs},\n        ]);\n      }\n    }\n    // Note: This is not an `else`, as we specifically want to re-check\n    // this.#lastRemoteWatermark\n    if (local.watermark === this.#lastRemoteWatermark?.watermark) {\n      if (this.#remoteDb) {\n        this.#lc.debug?.(\n          `local and remote watermarks match. pausing backup polling`,\n          {local, remote: this.#lastRemoteWatermark},\n        );\n        this.#remoteDb.close();\n        this.#remoteDb = null;\n      }\n    }\n  }\n\n  async run() {\n    this.#lc.info?.(`starting backup polling`);\n    let interval = MIN_CHECK_INTERVAL_MS;\n    while (this.#runningState.shouldRun()) {\n      try {\n        this.checkWatermarks();\n        interval = MIN_CHECK_INTERVAL_MS;\n      } catch (e) {\n        this.#lc.warn?.(`error checking local and remote watermarks`, e);\n        interval = Math.min(MAX_CHECK_INTERVAL_MS, interval * 2);\n      }\n      await this.#runningState.sleep(interval);\n    }\n    this.#remoteDb?.close();\n    this.#localDb.close();\n    this.#loader.close();\n  }\n\n  stop(): Promise<void> {\n    this.#runningState.stop(this.#lc);\n    return promiseVoid;\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/mutagen/mutagen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutagen.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/mutagen/mutagen.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutagen.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/mutagen/mutagen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,MAAM,CAAC;AACrC,OAAO,QAAQ,MAAM,UAAU,CAAC;AAGhC,OAAO,EAAC,SAAS,EAAC,MAAM,6CAA6C,CAAC;AAOtE,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEb,KAAK,QAAQ,EACd,MAAM,2CAA2C,CAAC;AAKnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,4CAA4C,CAAC;AAEhF,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,6BAA6B,CAAC;AAK5D,OAAO,KAAK,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAiB,KAAK,OAAO,EAAC,MAAM,uBAAuB,CAAC;AAEnE,OAAO,KAAK,EAAC,iBAAiB,EAAE,OAAO,EAAC,MAAM,eAAe,CAAC;AAK9D,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,mBAAmB;IAC9D,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,WAAW,OAAQ,SAAQ,iBAAiB;IAChD,eAAe,CACb,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,qBAAqB,EAAE,OAAO,GAC7B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACvC;AAED,qBAAa,cAAe,YAAW,OAAO,EAAE,OAAO;;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAkBlB,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,UAAU,EAClB,iBAAiB,EAAE,eAAe;IA0BpC,GAAG;IAKH,KAAK;IAQL,OAAO,IAAI,OAAO;IAIlB,eAAe,CACb,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,qBAAqB,UAAQ,GAC5B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAuBrC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAStB;AAID,wBAAsB,eAAe,CACnC,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,QAAQ,EAClB,eAAe,EAAE,eAAe,EAChC,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc;AACtD,qBAAqB,UAAQ,GAC5B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAqIpC;AAED,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,mBAAmB,EACvB,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,eAAe,iBA8D5B;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,cAAc,EAC3B,MAAM,EAAE,QAAQ,GACf,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAKvC;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,cAAc,EAC3B,GAAG,EAAE,QAAQ,GACZ,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAOvC"}

package/out/zero-cache/src/services/mutagen/mutagen.js

@@ -156,7 +156,10 @@ async function processMutationWithTx(lc, tx, authData, shard, clientGroupID, mut
 	await Promise.all(tasks.map((task) => task()));
 }
 function getInsertSQL(tx, create) {
-	return tx`INSERT INTO ${tx(create.tableName)} ${tx(create.value)}`;
+	return tx`
+    INSERT INTO ${tx(create.tableName)} ${tx(create.value)}
+    ON CONFLICT (${tx(create.primaryKey)}) DO NOTHING
+  `;
 }
 function getUpsertSQL(tx, set) {
 	const { tableName, primaryKey, value } = set;

package/out/zero-cache/src/services/mutagen/mutagen.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutagen.js","names":["#lc","#upstream","#shard","#stopped","#replica","#writeAuthorizer","#limiter","#crudMutations","#isStopped","#refCount"],"sources":["../../../../../../zero-cache/src/services/mutagen/mutagen.ts"],"sourcesContent":["import {PG_SERIALIZATION_FAILURE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport type {JWTPayload} from 'jose';\nimport postgres from 'postgres';\nimport {assert, unreachable} from '../../../../shared/src/asserts.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport {ErrorKind} from '../../../../zero-protocol/src/error-kind.ts';\nimport {ErrorOrigin} from '../../../../zero-protocol/src/error-origin.ts';\nimport {\n  isProtocolError,\n  ProtocolError,\n} from '../../../../zero-protocol/src/error.ts';\nimport * as MutationType from '../../../../zero-protocol/src/mutation-type-enum.ts';\nimport {\n  type CRUDMutation,\n  type DeleteOp,\n  type InsertOp,\n  type Mutation,\n  type UpdateOp,\n  type UpsertOp,\n} from '../../../../zero-protocol/src/mutation.ts';\nimport {\n  primaryKeyValueSchema,\n  type PrimaryKeyValue,\n} from '../../../../zero-protocol/src/primary-key.ts';\nimport type {DatabaseStorage} from '../../../../zqlite/src/database-storage.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {\n  WriteAuthorizerImpl,\n  type WriteAuthorizer,\n} from '../../auth/write-authorizer.ts';\nimport {type ZeroConfig} from '../../config/zero-config.ts';\nimport * as Mode from '../../db/mode-enum.ts';\nimport {runTx} from '../../db/run-transaction.ts';\nimport {getOrCreateCounter} from '../../observability/metrics.ts';\nimport {recordMutation} from '../../server/anonymous-otel-start.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../types/pg.ts';\nimport {upstreamSchema, type ShardID} from '../../types/shards.ts';\nimport {SlidingWindowLimiter} from '../limiter/sliding-window-limiter.ts';\nimport type {RefCountedService, Service} from '../service.ts';\nimport {MutationAlreadyProcessedError} from './error.ts';\n\n// An error encountered processing a mutation.\n// Returned back to application for display to user.\nexport type MutationError = [\n  kind: ErrorKind.MutationFailed | ErrorKind.MutationRateLimited,\n  desc: string,\n];\n\nexport interface Mutagen extends RefCountedService {\n  processMutation(\n    mutation: Mutation,\n    authData: JWTPayload | undefined,\n    customMutatorsEnabled: boolean,\n  ): Promise<MutationError | undefined>;\n}\n\nexport class MutagenService implements Mutagen, Service {\n  readonly id: string;\n  readonly #lc: LogContext;\n  readonly #upstream: PostgresDB;\n  readonly #shard: ShardID;\n  readonly #stopped = resolver();\n  readonly #replica: Database;\n  readonly #writeAuthorizer: WriteAuthorizerImpl;\n  readonly #limiter: SlidingWindowLimiter | undefined;\n  #refCount = 0;\n  #isStopped = false;\n\n  readonly #crudMutations = getOrCreateCounter(\n    'mutation',\n    'crud',\n    'Number of CRUD mutations processed',\n  );\n\n  constructor(\n    lc: LogContext,\n    shard: ShardID,\n    clientGroupID: string,\n    upstream: PostgresDB,\n    config: ZeroConfig,\n    writeAuthzStorage: DatabaseStorage,\n  ) {\n    this.id = clientGroupID;\n    this.#lc = lc;\n    this.#upstream = upstream;\n    this.#shard = shard;\n    this.#replica = new Database(this.#lc, config.replica.file, {\n      fileMustExist: true,\n    });\n    this.#writeAuthorizer = new WriteAuthorizerImpl(\n      this.#lc,\n      config,\n      this.#replica,\n      shard.appID,\n      clientGroupID,\n      writeAuthzStorage,\n    );\n\n    if (config.perUserMutationLimit.max !== undefined) {\n      this.#limiter = new SlidingWindowLimiter(\n        config.perUserMutationLimit.windowMs,\n        config.perUserMutationLimit.max,\n      );\n    }\n  }\n\n  ref() {\n    assert(!this.#isStopped, 'MutagenService is already stopped');\n    ++this.#refCount;\n  }\n\n  unref() {\n    assert(!this.#isStopped, 'MutagenService is already stopped');\n    --this.#refCount;\n    if (this.#refCount <= 0) {\n      void this.stop();\n    }\n  }\n\n  hasRefs(): boolean {\n    return this.#refCount > 0;\n  }\n\n  processMutation(\n    mutation: Mutation,\n    authData: JWTPayload | undefined,\n    customMutatorsEnabled = false,\n  ): Promise<MutationError | undefined> {\n    if (this.#limiter?.canDo() === false) {\n      return Promise.resolve([\n        ErrorKind.MutationRateLimited,\n        'Rate limit exceeded',\n      ]);\n    }\n    this.#crudMutations.add(1, {\n      clientGroupID: this.id,\n    });\n    return processMutation(\n      this.#lc,\n      authData,\n      this.#upstream,\n      this.#shard,\n      this.id,\n      mutation,\n      this.#writeAuthorizer,\n      undefined,\n      customMutatorsEnabled,\n    );\n  }\n\n  run(): Promise<void> {\n    return this.#stopped.promise;\n  }\n\n  stop(): Promise<void> {\n    if (this.#isStopped) {\n      return this.#stopped.promise;\n    }\n    this.#writeAuthorizer.destroy();\n    this.#isStopped = true;\n    this.#stopped.resolve();\n    return this.#stopped.promise;\n  }\n}\n\nconst MAX_SERIALIZATION_ATTEMPTS = 10;\n\nexport async function processMutation(\n  lc: LogContext,\n  authData: JWTPayload | undefined,\n  db: PostgresDB,\n  shard: ShardID,\n  clientGroupID: string,\n  mutation: Mutation,\n  writeAuthorizer: WriteAuthorizer,\n  onTxStart?: () => void | Promise<void>, // for testing\n  customMutatorsEnabled = false,\n): Promise<MutationError | undefined> {\n  assert(\n    mutation.type === MutationType.CRUD,\n    'Only CRUD mutations are supported',\n  );\n  lc = lc.withContext('mutationID', mutation.id);\n  lc = lc.withContext('processMutation');\n  lc.debug?.('Process mutation start', mutation);\n\n  // Record mutation processing attempt for telemetry (regardless of success/failure)\n  recordMutation('crud');\n\n  let result: MutationError | undefined;\n\n  const start = Date.now();\n  try {\n    // Mutations can fail for a variety of reasons:\n    //\n    // - application error\n    // - network/db error\n    // - zero bug\n    //\n    // For application errors what we want is to re-run the mutation in\n    // \"error mode\", which skips the actual mutation and just updates the\n    // lastMutationID. Then return the error to the app.\n    //\n    // However, it's hard to tell the difference between application errors\n    // and the other types.\n    //\n    // A reasonable policy ends up being to just retry every mutation once\n    // in error mode. If the error mode mutation succeeds then we assume it\n    // was an application error and return the error to the app. Otherwise,\n    // we know it was something internal and we log it.\n    //\n    // This is not 100% correct - there are theoretical cases where we\n    // return an internal error to the app that shouldn't have been. But it\n    // would have to be a crazy coincidence: we'd have to have a network\n    // error on the first attempt that resolves by the second attempt.\n    //\n    // One might ask why not try/catch just the calls to the mutators and\n    // consider those application errors. That is actually what we do in\n    // Replicache:\n    //\n    // https://github.com/rocicorp/todo-row-versioning/blob/9a0a79dc2d2de32c4fac61b5d1634bd9a9e66b7c/server/src/push.ts#L131\n    //\n    // We don't do it here because:\n    //\n    // 1. It's still not perfect. It's hard to isolate SQL errors in\n    //    mutators due to app developer mistakes from SQL errors due to\n    //    Zero mistakes.\n    // 2. It's not possible to do this with the pg library we're using in\n    //    Zero anyway: https://github.com/porsager/postgres/issues/455.\n    //\n    // Personally I think this simple retry policy is nice.\n    let errorMode = false;\n    for (let i = 0; i < MAX_SERIALIZATION_ATTEMPTS; i++) {\n      try {\n        await runTx(\n          db,\n          async tx => {\n            // Simulates a concurrent request for testing. In production this is a noop.\n            const done = onTxStart?.();\n            try {\n              return await processMutationWithTx(\n                lc,\n                tx,\n                authData,\n                shard,\n                clientGroupID,\n                mutation,\n                errorMode,\n                writeAuthorizer,\n              );\n            } finally {\n              await done;\n            }\n          },\n          {mode: Mode.SERIALIZABLE},\n        );\n        if (errorMode) {\n          lc.debug?.('Ran mutation successfully in error mode');\n        }\n        break;\n      } catch (e) {\n        if (e instanceof MutationAlreadyProcessedError) {\n          lc.debug?.(e.message);\n          // Don't double-count already processed mutations, but they were counted above\n          return undefined;\n        }\n        if (\n          isProtocolError(e) &&\n          !errorMode &&\n          e.kind === ErrorKind.InvalidPush &&\n          customMutatorsEnabled &&\n          i < 2\n        ) {\n          // We're temporarily supporting custom mutators AND CRUD mutators at the same time.\n          // This can create a lot of OOO mutation errors since we do not know when the API server\n          // has applied a custom mutation before moving on to process CRUD mutations.\n          // The temporary workaround (since CRUD is being deprecated) is to retry the mutation\n          // after a small delay. Users are not expected to be running both CRUD and Custom mutators.\n          // They should migrate completely to custom mutators.\n          lc.info?.(\n            'Both CRUD and Custom mutators are being used at once. This is supported for now but IS NOT RECOMMENDED. Migrate completely to custom mutators.',\n            e,\n          );\n          await new Promise(resolve => setTimeout(resolve, 100));\n          continue;\n        }\n        if (isProtocolError(e) || errorMode) {\n          lc.error?.('Process mutation error', e);\n          throw e;\n        }\n        if (\n          e instanceof postgres.PostgresError &&\n          e.code === PG_SERIALIZATION_FAILURE\n        ) {\n          lc.info?.(`attempt ${i + 1}: ${String(e)}`, e);\n          continue; // Retry up to MAX_SERIALIZATION_ATTEMPTS.\n        }\n        result = [ErrorKind.MutationFailed, String(e)];\n        if (errorMode) {\n          break;\n        }\n        lc.error?.('Got error running mutation, re-running in error mode', e);\n        errorMode = true;\n        i--;\n      }\n    }\n  } finally {\n    lc.debug?.('Process mutation complete in', Date.now() - start);\n  }\n  return result;\n}\n\nexport async function processMutationWithTx(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  authData: JWTPayload | undefined,\n  shard: ShardID,\n  clientGroupID: string,\n  mutation: CRUDMutation,\n  errorMode: boolean,\n  authorizer: WriteAuthorizer,\n) {\n  const tasks: (() => Promise<unknown>)[] = [];\n\n  async function execute(stmt: postgres.PendingQuery<postgres.Row[]>) {\n    try {\n      return await stmt.execute();\n    } finally {\n      const q = stmt as unknown as Query;\n      lc.debug?.(`${q.string}: ${JSON.stringify(q.parameters)}`);\n    }\n  }\n\n  authorizer.reloadPermissions();\n\n  if (!errorMode) {\n    const {ops} = mutation.args[0];\n\n    // Validate all table names before processing\n    authorizer.validateTableNames(ops);\n\n    const normalizedOps = authorizer.normalizeOps(ops);\n    const [canPre, canPost] = await Promise.all([\n      authorizer.canPreMutation(authData, normalizedOps),\n      authorizer.canPostMutation(authData, normalizedOps),\n    ]);\n    if (canPre && canPost) {\n      for (const op of ops) {\n        switch (op.op) {\n          case 'insert':\n            tasks.push(() => execute(getInsertSQL(tx, op)));\n            break;\n          case 'upsert':\n            tasks.push(() => execute(getUpsertSQL(tx, op)));\n            break;\n          case 'update':\n            tasks.push(() => execute(getUpdateSQL(tx, op)));\n            break;\n          case 'delete':\n            tasks.push(() => execute(getDeleteSQL(tx, op)));\n            break;\n          default:\n            unreachable(op);\n        }\n      }\n    }\n  }\n\n  // Confirm the mutation even though it may have been blocked by the authorizer.\n  // Authorizer blocking a mutation is not an error but the correct result of the mutation.\n  tasks.unshift(() =>\n    checkSchemaVersionAndIncrementLastMutationID(\n      tx,\n      shard,\n      clientGroupID,\n      mutation.clientID,\n      mutation.id,\n    ),\n  );\n\n  // Note: An error thrown from any Promise aborts the entire transaction.\n  await Promise.all(tasks.map(task => task()));\n}\n\nexport function getInsertSQL(\n  tx: postgres.TransactionSql,\n  create: InsertOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  return tx`INSERT INTO ${tx(create.tableName)} ${tx(create.value)}`;\n}\n\nexport function getUpsertSQL(\n  tx: postgres.TransactionSql,\n  set: UpsertOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const {tableName, primaryKey, value} = set;\n  return tx`\n    INSERT INTO ${tx(tableName)} ${tx(value)}\n    ON CONFLICT (${tx(primaryKey)})\n    DO UPDATE SET ${tx(value)}\n  `;\n}\n\nfunction getUpdateSQL(\n  tx: postgres.TransactionSql,\n  update: UpdateOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const table = update.tableName;\n  const {primaryKey, value} = update;\n  const id: Record<string, PrimaryKeyValue> = {};\n  for (const key of primaryKey) {\n    id[key] = v.parse(value[key], primaryKeyValueSchema);\n  }\n  return tx`UPDATE ${tx(table)} SET ${tx(value)} WHERE ${Object.entries(\n    id,\n  ).flatMap(([key, value], i) =>\n    i ? [tx`AND`, tx`${tx(key)} = ${value}`] : tx`${tx(key)} = ${value}`,\n  )}`;\n}\n\nfunction getDeleteSQL(\n  tx: postgres.TransactionSql,\n  deleteOp: DeleteOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const {tableName, primaryKey, value} = deleteOp;\n\n  const conditions = [];\n  for (const key of primaryKey) {\n    if (conditions.length > 0) {\n      conditions.push(tx`AND`);\n    }\n    conditions.push(tx`${tx(key)} = ${value[key]}`);\n  }\n\n  return tx`DELETE FROM ${tx(tableName)} WHERE ${conditions}`;\n}\n\nasync function checkSchemaVersionAndIncrementLastMutationID(\n  tx: PostgresTransaction,\n  shard: ShardID,\n  clientGroupID: string,\n  clientID: string,\n  receivedMutationID: number,\n) {\n  const [{lastMutationID}] = await tx<{lastMutationID: bigint}[]>`\n    INSERT INTO ${tx(upstreamSchema(shard))}.clients \n      as current (\"clientGroupID\", \"clientID\", \"lastMutationID\")\n          VALUES (${clientGroupID}, ${clientID}, ${1})\n      ON CONFLICT (\"clientGroupID\", \"clientID\")\n      DO UPDATE SET \"lastMutationID\" = current.\"lastMutationID\" + 1\n      RETURNING \"lastMutationID\"\n  `;\n\n  // ABORT if the resulting lastMutationID is not equal to the receivedMutationID.\n  if (receivedMutationID < lastMutationID) {\n    throw new MutationAlreadyProcessedError(\n      clientID,\n      receivedMutationID,\n      lastMutationID,\n    );\n  } else if (receivedMutationID > lastMutationID) {\n    throw new ProtocolError({\n      kind: ErrorKind.InvalidPush,\n      message: `Push contains unexpected mutation id ${receivedMutationID} for client ${clientID}. Expected mutation id ${lastMutationID.toString()}.`,\n      origin: ErrorOrigin.ZeroCache,\n    });\n  }\n}\n\n// The slice of information from the Query object in Postgres.js that gets logged for debugging.\n// https://github.com/porsager/postgres/blob/f58cd4f3affd3e8ce8f53e42799672d86cd2c70b/src/connection.js#L219\ntype Query = {string: string; parameters: object[]};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA0DA,IAAa,iBAAb,MAAwD;CACtD;CACA;CACA;CACA;CACA,WAAoB,SAAS;CAC7B;CACA;CACA;CACA,YAAY;CACZ,aAAa;CAEb,iBAA0B,mBACxB,YACA,QACA,oCACF;CAEA,YACE,IACA,OACA,eACA,UACA,QACA,mBACA;EACA,KAAK,KAAK;EACV,KAAKA,MAAM;EACX,KAAKC,YAAY;EACjB,KAAKC,SAAS;EACd,KAAKE,WAAW,IAAI,SAAS,KAAKJ,KAAK,OAAO,QAAQ,MAAM,EAC1D,eAAe,KACjB,CAAC;EACD,KAAKK,mBAAmB,IAAI,oBAC1B,KAAKL,KACL,QACA,KAAKI,UACL,MAAM,OACN,eACA,iBACF;EAEA,IAAI,OAAO,qBAAqB,QAAQ,KAAA,GACtC,KAAKE,WAAW,IAAI,qBAClB,OAAO,qBAAqB,UAC5B,OAAO,qBAAqB,GAC9B;CAEJ;CAEA,MAAM;EACJ,OAAO,CAAC,KAAKE,YAAY,mCAAmC;EAC5D,EAAE,KAAKC;CACT;CAEA,QAAQ;EACN,OAAO,CAAC,KAAKD,YAAY,mCAAmC;EAC5D,EAAE,KAAKC;EACP,IAAI,KAAKA,aAAa,GACpB,KAAU,KAAK;CAEnB;CAEA,UAAmB;EACjB,OAAO,KAAKA,YAAY;CAC1B;CAEA,gBACE,UACA,UACA,wBAAwB,OACY;EACpC,IAAI,KAAKH,UAAU,MAAM,MAAM,OAC7B,OAAO,QAAQ,QAAQ,CACrB,qBACA,qBACF,CAAC;EAEH,KAAKC,eAAe,IAAI,GAAG,EACzB,eAAe,KAAK,GACtB,CAAC;EACD,OAAO,gBACL,KAAKP,KACL,UACA,KAAKC,WACL,KAAKC,QACL,KAAK,IACL,UACA,KAAKG,kBACL,KAAA,GACA,qBACF;CACF;CAEA,MAAqB;EACnB,OAAO,KAAKF,SAAS;CACvB;CAEA,OAAsB;EACpB,IAAI,KAAKK,YACP,OAAO,KAAKL,SAAS;EAEvB,KAAKE,iBAAiB,QAAQ;EAC9B,KAAKG,aAAa;EAClB,KAAKL,SAAS,QAAQ;EACtB,OAAO,KAAKA,SAAS;CACvB;AACF;AAEA,IAAM,6BAA6B;AAEnC,eAAsB,gBACpB,IACA,UACA,IACA,OACA,eACA,UACA,iBACA,WACA,wBAAwB,OACY;CACpC,OACE,SAAS,SAAS,MAClB,mCACF;CACA,KAAK,GAAG,YAAY,cAAc,SAAS,EAAE;CAC7C,KAAK,GAAG,YAAY,iBAAiB;CACrC,GAAG,QAAQ,0BAA0B,QAAQ;CAG7C,eAAe,MAAM;CAErB,IAAI;CAEJ,MAAM,QAAQ,KAAK,IAAI;CACvB,IAAI;EAuCF,IAAI,YAAY;EAChB,KAAK,IAAI,IAAI,GAAG,IAAI,4BAA4B,KAC9C,IAAI;GACF,MAAM,MACJ,IACA,OAAM,OAAM;IAEV,MAAM,OAAO,YAAY;IACzB,IAAI;KACF,OAAO,MAAM,sBACX,IACA,IACA,UACA,OACA,eACA,UACA,WACA,eACF;IACF,UAAU;KACR,MAAM;IACR;GACF,GACA,EAAC,MAAM,aAAiB,CAC1B;GACA,IAAI,WACF,GAAG,QAAQ,yCAAyC;GAEtD;EACF,SAAS,GAAG;GACV,IAAI,aAAa,+BAA+B;IAC9C,GAAG,QAAQ,EAAE,OAAO;IAEpB;GACF;GACA,IACE,gBAAgB,CAAC,KACjB,CAAC,aACD,EAAE,SAAS,iBACX,yBACA,IAAI,GACJ;IAOA,GAAG,OACD,kJACA,CACF;IACA,MAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,GAAG,CAAC;IACrD;GACF;GACA,IAAI,gBAAgB,CAAC,KAAK,WAAW;IACnC,GAAG,QAAQ,0BAA0B,CAAC;IACtC,MAAM;GACR;GACA,IACE,aAAa,SAAS,iBACtB,EAAE,SAAS,0BACX;IACA,GAAG,OAAO,WAAW,IAAI,EAAE,IAAI,OAAO,CAAC,KAAK,CAAC;IAC7C;GACF;GACA,SAAS,CAAC,gBAA0B,OAAO,CAAC,CAAC;GAC7C,IAAI,WACF;GAEF,GAAG,QAAQ,wDAAwD,CAAC;GACpE,YAAY;GACZ;EACF;CAEJ,UAAU;EACR,GAAG,QAAQ,gCAAgC,KAAK,IAAI,IAAI,KAAK;CAC/D;CACA,OAAO;AACT;AAEA,eAAsB,sBACpB,IACA,IACA,UACA,OACA,eACA,UACA,WACA,YACA;CACA,MAAM,QAAoC,CAAC;CAE3C,eAAe,QAAQ,MAA6C;EAClE,IAAI;GACF,OAAO,MAAM,KAAK,QAAQ;EAC5B,UAAU;GACR,MAAM,IAAI;GACV,GAAG,QAAQ,GAAG,EAAE,OAAO,IAAI,KAAK,UAAU,EAAE,UAAU,GAAG;EAC3D;CACF;CAEA,WAAW,kBAAkB;CAE7B,IAAI,CAAC,WAAW;EACd,MAAM,EAAC,QAAO,SAAS,KAAK;EAG5B,WAAW,mBAAmB,GAAG;EAEjC,MAAM,gBAAgB,WAAW,aAAa,GAAG;EACjD,MAAM,CAAC,QAAQ,WAAW,MAAM,QAAQ,IAAI,CAC1C,WAAW,eAAe,UAAU,aAAa,GACjD,WAAW,gBAAgB,UAAU,aAAa,CACpD,CAAC;EACD,IAAI,UAAU,SACZ,KAAK,MAAM,MAAM,KACf,QAAQ,GAAG,IAAX;GACE,KAAK;IACH,MAAM,WAAW,QAAQ,aAAa,IAAI,EAAE,CAAC,CAAC;IAC9C;GACF,KAAK;IACH,MAAM,WAAW,QAAQ,aAAa,IAAI,EAAE,CAAC,CAAC;IAC9C;GACF,KAAK;IACH,MAAM,WAAW,QAAQ,aAAa,IAAI,EAAE,CAAC,CAAC;IAC9C;GACF,KAAK;IACH,MAAM,WAAW,QAAQ,aAAa,IAAI,EAAE,CAAC,CAAC;IAC9C;GACF,SACE,YAAY,EAAE;EAClB;CAGN;CAIA,MAAM,cACJ,6CACE,IACA,OACA,eACA,SAAS,UACT,SAAS,EACX,CACF;CAGA,MAAM,QAAQ,IAAI,MAAM,KAAI,SAAQ,KAAK,CAAC,CAAC;AAC7C;AAEA,SAAgB,aACd,IACA,QACuC;CACvC,OAAO,EAAE,eAAe,GAAG,OAAO,SAAS,EAAE,GAAG,GAAG,OAAO,KAAK;AACjE;AAEA,SAAgB,aACd,IACA,KACuC;CACvC,MAAM,EAAC,WAAW,YAAY,UAAS;CACvC,OAAO,EAAE;kBACO,GAAG,SAAS,EAAE,GAAG,GAAG,KAAK,EAAE;mBAC1B,GAAG,UAAU,EAAE;oBACd,GAAG,KAAK,EAAE;;AAE9B;AAEA,SAAS,aACP,IACA,QACuC;CACvC,MAAM,QAAQ,OAAO;CACrB,MAAM,EAAC,YAAY,UAAS;CAC5B,MAAM,KAAsC,CAAC;CAC7C,KAAK,MAAM,OAAO,YAChB,GAAG,OAAO,MAAQ,MAAM,MAAM,qBAAqB;CAErD,OAAO,EAAE,UAAU,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK,EAAE,SAAS,OAAO,QAC5D,EACF,EAAE,SAAS,CAAC,KAAK,QAAQ,MACvB,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,OAAO,IAAI,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,OAC/D;AACF;AAEA,SAAS,aACP,IACA,UACuC;CACvC,MAAM,EAAC,WAAW,YAAY,UAAS;CAEvC,MAAM,aAAa,CAAC;CACpB,KAAK,MAAM,OAAO,YAAY;EAC5B,IAAI,WAAW,SAAS,GACtB,WAAW,KAAK,EAAE,KAAK;EAEzB,WAAW,KAAK,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,MAAM,MAAM;CAChD;CAEA,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,SAAS;AACjD;AAEA,eAAe,6CACb,IACA,OACA,eACA,UACA,oBACA;CACA,MAAM,CAAC,EAAC,oBAAmB,MAAM,EAA8B;kBAC/C,GAAG,eAAe,KAAK,CAAC,EAAE;;oBAExB,cAAc,IAAI,SAAS,IAAI,EAAE;;;;;CAOnD,IAAI,qBAAqB,gBACvB,MAAM,IAAI,8BACR,UACA,oBACA,cACF;MACK,IAAI,qBAAqB,gBAC9B,MAAM,IAAI,cAAc;EACtB,MAAM;EACN,SAAS,wCAAwC,mBAAmB,cAAc,SAAS,yBAAyB,eAAe,SAAS,EAAE;EAC9I,QAAQ;CACV,CAAC;AAEL"}
+{"version":3,"file":"mutagen.js","names":["#lc","#upstream","#shard","#stopped","#replica","#writeAuthorizer","#limiter","#crudMutations","#isStopped","#refCount"],"sources":["../../../../../../zero-cache/src/services/mutagen/mutagen.ts"],"sourcesContent":["import {PG_SERIALIZATION_FAILURE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport type {JWTPayload} from 'jose';\nimport postgres from 'postgres';\nimport {assert, unreachable} from '../../../../shared/src/asserts.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport {ErrorKind} from '../../../../zero-protocol/src/error-kind.ts';\nimport {ErrorOrigin} from '../../../../zero-protocol/src/error-origin.ts';\nimport {\n  isProtocolError,\n  ProtocolError,\n} from '../../../../zero-protocol/src/error.ts';\nimport * as MutationType from '../../../../zero-protocol/src/mutation-type-enum.ts';\nimport {\n  type CRUDMutation,\n  type DeleteOp,\n  type InsertOp,\n  type Mutation,\n  type UpdateOp,\n  type UpsertOp,\n} from '../../../../zero-protocol/src/mutation.ts';\nimport {\n  primaryKeyValueSchema,\n  type PrimaryKeyValue,\n} from '../../../../zero-protocol/src/primary-key.ts';\nimport type {DatabaseStorage} from '../../../../zqlite/src/database-storage.ts';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {\n  WriteAuthorizerImpl,\n  type WriteAuthorizer,\n} from '../../auth/write-authorizer.ts';\nimport {type ZeroConfig} from '../../config/zero-config.ts';\nimport * as Mode from '../../db/mode-enum.ts';\nimport {runTx} from '../../db/run-transaction.ts';\nimport {getOrCreateCounter} from '../../observability/metrics.ts';\nimport {recordMutation} from '../../server/anonymous-otel-start.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../types/pg.ts';\nimport {upstreamSchema, type ShardID} from '../../types/shards.ts';\nimport {SlidingWindowLimiter} from '../limiter/sliding-window-limiter.ts';\nimport type {RefCountedService, Service} from '../service.ts';\nimport {MutationAlreadyProcessedError} from './error.ts';\n\n// An error encountered processing a mutation.\n// Returned back to application for display to user.\nexport type MutationError = [\n  kind: ErrorKind.MutationFailed | ErrorKind.MutationRateLimited,\n  desc: string,\n];\n\nexport interface Mutagen extends RefCountedService {\n  processMutation(\n    mutation: Mutation,\n    authData: JWTPayload | undefined,\n    customMutatorsEnabled: boolean,\n  ): Promise<MutationError | undefined>;\n}\n\nexport class MutagenService implements Mutagen, Service {\n  readonly id: string;\n  readonly #lc: LogContext;\n  readonly #upstream: PostgresDB;\n  readonly #shard: ShardID;\n  readonly #stopped = resolver();\n  readonly #replica: Database;\n  readonly #writeAuthorizer: WriteAuthorizerImpl;\n  readonly #limiter: SlidingWindowLimiter | undefined;\n  #refCount = 0;\n  #isStopped = false;\n\n  readonly #crudMutations = getOrCreateCounter(\n    'mutation',\n    'crud',\n    'Number of CRUD mutations processed',\n  );\n\n  constructor(\n    lc: LogContext,\n    shard: ShardID,\n    clientGroupID: string,\n    upstream: PostgresDB,\n    config: ZeroConfig,\n    writeAuthzStorage: DatabaseStorage,\n  ) {\n    this.id = clientGroupID;\n    this.#lc = lc;\n    this.#upstream = upstream;\n    this.#shard = shard;\n    this.#replica = new Database(this.#lc, config.replica.file, {\n      fileMustExist: true,\n    });\n    this.#writeAuthorizer = new WriteAuthorizerImpl(\n      this.#lc,\n      config,\n      this.#replica,\n      shard.appID,\n      clientGroupID,\n      writeAuthzStorage,\n    );\n\n    if (config.perUserMutationLimit.max !== undefined) {\n      this.#limiter = new SlidingWindowLimiter(\n        config.perUserMutationLimit.windowMs,\n        config.perUserMutationLimit.max,\n      );\n    }\n  }\n\n  ref() {\n    assert(!this.#isStopped, 'MutagenService is already stopped');\n    ++this.#refCount;\n  }\n\n  unref() {\n    assert(!this.#isStopped, 'MutagenService is already stopped');\n    --this.#refCount;\n    if (this.#refCount <= 0) {\n      void this.stop();\n    }\n  }\n\n  hasRefs(): boolean {\n    return this.#refCount > 0;\n  }\n\n  processMutation(\n    mutation: Mutation,\n    authData: JWTPayload | undefined,\n    customMutatorsEnabled = false,\n  ): Promise<MutationError | undefined> {\n    if (this.#limiter?.canDo() === false) {\n      return Promise.resolve([\n        ErrorKind.MutationRateLimited,\n        'Rate limit exceeded',\n      ]);\n    }\n    this.#crudMutations.add(1, {\n      clientGroupID: this.id,\n    });\n    return processMutation(\n      this.#lc,\n      authData,\n      this.#upstream,\n      this.#shard,\n      this.id,\n      mutation,\n      this.#writeAuthorizer,\n      undefined,\n      customMutatorsEnabled,\n    );\n  }\n\n  run(): Promise<void> {\n    return this.#stopped.promise;\n  }\n\n  stop(): Promise<void> {\n    if (this.#isStopped) {\n      return this.#stopped.promise;\n    }\n    this.#writeAuthorizer.destroy();\n    this.#isStopped = true;\n    this.#stopped.resolve();\n    return this.#stopped.promise;\n  }\n}\n\nconst MAX_SERIALIZATION_ATTEMPTS = 10;\n\nexport async function processMutation(\n  lc: LogContext,\n  authData: JWTPayload | undefined,\n  db: PostgresDB,\n  shard: ShardID,\n  clientGroupID: string,\n  mutation: Mutation,\n  writeAuthorizer: WriteAuthorizer,\n  onTxStart?: () => void | Promise<void>, // for testing\n  customMutatorsEnabled = false,\n): Promise<MutationError | undefined> {\n  assert(\n    mutation.type === MutationType.CRUD,\n    'Only CRUD mutations are supported',\n  );\n  lc = lc.withContext('mutationID', mutation.id);\n  lc = lc.withContext('processMutation');\n  lc.debug?.('Process mutation start', mutation);\n\n  // Record mutation processing attempt for telemetry (regardless of success/failure)\n  recordMutation('crud');\n\n  let result: MutationError | undefined;\n\n  const start = Date.now();\n  try {\n    // Mutations can fail for a variety of reasons:\n    //\n    // - application error\n    // - network/db error\n    // - zero bug\n    //\n    // For application errors what we want is to re-run the mutation in\n    // \"error mode\", which skips the actual mutation and just updates the\n    // lastMutationID. Then return the error to the app.\n    //\n    // However, it's hard to tell the difference between application errors\n    // and the other types.\n    //\n    // A reasonable policy ends up being to just retry every mutation once\n    // in error mode. If the error mode mutation succeeds then we assume it\n    // was an application error and return the error to the app. Otherwise,\n    // we know it was something internal and we log it.\n    //\n    // This is not 100% correct - there are theoretical cases where we\n    // return an internal error to the app that shouldn't have been. But it\n    // would have to be a crazy coincidence: we'd have to have a network\n    // error on the first attempt that resolves by the second attempt.\n    //\n    // One might ask why not try/catch just the calls to the mutators and\n    // consider those application errors. That is actually what we do in\n    // Replicache:\n    //\n    // https://github.com/rocicorp/todo-row-versioning/blob/9a0a79dc2d2de32c4fac61b5d1634bd9a9e66b7c/server/src/push.ts#L131\n    //\n    // We don't do it here because:\n    //\n    // 1. It's still not perfect. It's hard to isolate SQL errors in\n    //    mutators due to app developer mistakes from SQL errors due to\n    //    Zero mistakes.\n    // 2. It's not possible to do this with the pg library we're using in\n    //    Zero anyway: https://github.com/porsager/postgres/issues/455.\n    //\n    // Personally I think this simple retry policy is nice.\n    let errorMode = false;\n    for (let i = 0; i < MAX_SERIALIZATION_ATTEMPTS; i++) {\n      try {\n        await runTx(\n          db,\n          async tx => {\n            // Simulates a concurrent request for testing. In production this is a noop.\n            const done = onTxStart?.();\n            try {\n              return await processMutationWithTx(\n                lc,\n                tx,\n                authData,\n                shard,\n                clientGroupID,\n                mutation,\n                errorMode,\n                writeAuthorizer,\n              );\n            } finally {\n              await done;\n            }\n          },\n          {mode: Mode.SERIALIZABLE},\n        );\n        if (errorMode) {\n          lc.debug?.('Ran mutation successfully in error mode');\n        }\n        break;\n      } catch (e) {\n        if (e instanceof MutationAlreadyProcessedError) {\n          lc.debug?.(e.message);\n          // Don't double-count already processed mutations, but they were counted above\n          return undefined;\n        }\n        if (\n          isProtocolError(e) &&\n          !errorMode &&\n          e.kind === ErrorKind.InvalidPush &&\n          customMutatorsEnabled &&\n          i < 2\n        ) {\n          // We're temporarily supporting custom mutators AND CRUD mutators at the same time.\n          // This can create a lot of OOO mutation errors since we do not know when the API server\n          // has applied a custom mutation before moving on to process CRUD mutations.\n          // The temporary workaround (since CRUD is being deprecated) is to retry the mutation\n          // after a small delay. Users are not expected to be running both CRUD and Custom mutators.\n          // They should migrate completely to custom mutators.\n          lc.info?.(\n            'Both CRUD and Custom mutators are being used at once. This is supported for now but IS NOT RECOMMENDED. Migrate completely to custom mutators.',\n            e,\n          );\n          await new Promise(resolve => setTimeout(resolve, 100));\n          continue;\n        }\n        if (isProtocolError(e) || errorMode) {\n          lc.error?.('Process mutation error', e);\n          throw e;\n        }\n        if (\n          e instanceof postgres.PostgresError &&\n          e.code === PG_SERIALIZATION_FAILURE\n        ) {\n          lc.info?.(`attempt ${i + 1}: ${String(e)}`, e);\n          continue; // Retry up to MAX_SERIALIZATION_ATTEMPTS.\n        }\n        result = [ErrorKind.MutationFailed, String(e)];\n        if (errorMode) {\n          break;\n        }\n        lc.error?.('Got error running mutation, re-running in error mode', e);\n        errorMode = true;\n        i--;\n      }\n    }\n  } finally {\n    lc.debug?.('Process mutation complete in', Date.now() - start);\n  }\n  return result;\n}\n\nexport async function processMutationWithTx(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  authData: JWTPayload | undefined,\n  shard: ShardID,\n  clientGroupID: string,\n  mutation: CRUDMutation,\n  errorMode: boolean,\n  authorizer: WriteAuthorizer,\n) {\n  const tasks: (() => Promise<unknown>)[] = [];\n\n  async function execute(stmt: postgres.PendingQuery<postgres.Row[]>) {\n    try {\n      return await stmt.execute();\n    } finally {\n      const q = stmt as unknown as Query;\n      lc.debug?.(`${q.string}: ${JSON.stringify(q.parameters)}`);\n    }\n  }\n\n  authorizer.reloadPermissions();\n\n  if (!errorMode) {\n    const {ops} = mutation.args[0];\n\n    // Validate all table names before processing\n    authorizer.validateTableNames(ops);\n\n    const normalizedOps = authorizer.normalizeOps(ops);\n    const [canPre, canPost] = await Promise.all([\n      authorizer.canPreMutation(authData, normalizedOps),\n      authorizer.canPostMutation(authData, normalizedOps),\n    ]);\n    if (canPre && canPost) {\n      for (const op of ops) {\n        switch (op.op) {\n          case 'insert':\n            tasks.push(() => execute(getInsertSQL(tx, op)));\n            break;\n          case 'upsert':\n            tasks.push(() => execute(getUpsertSQL(tx, op)));\n            break;\n          case 'update':\n            tasks.push(() => execute(getUpdateSQL(tx, op)));\n            break;\n          case 'delete':\n            tasks.push(() => execute(getDeleteSQL(tx, op)));\n            break;\n          default:\n            unreachable(op);\n        }\n      }\n    }\n  }\n\n  // Confirm the mutation even though it may have been blocked by the authorizer.\n  // Authorizer blocking a mutation is not an error but the correct result of the mutation.\n  tasks.unshift(() =>\n    checkSchemaVersionAndIncrementLastMutationID(\n      tx,\n      shard,\n      clientGroupID,\n      mutation.clientID,\n      mutation.id,\n    ),\n  );\n\n  // Note: An error thrown from any Promise aborts the entire transaction.\n  await Promise.all(tasks.map(task => task()));\n}\n\nexport function getInsertSQL(\n  tx: postgres.TransactionSql,\n  create: InsertOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  return tx`\n    INSERT INTO ${tx(create.tableName)} ${tx(create.value)}\n    ON CONFLICT (${tx(create.primaryKey)}) DO NOTHING\n  `;\n}\n\nexport function getUpsertSQL(\n  tx: postgres.TransactionSql,\n  set: UpsertOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const {tableName, primaryKey, value} = set;\n  return tx`\n    INSERT INTO ${tx(tableName)} ${tx(value)}\n    ON CONFLICT (${tx(primaryKey)})\n    DO UPDATE SET ${tx(value)}\n  `;\n}\n\nfunction getUpdateSQL(\n  tx: postgres.TransactionSql,\n  update: UpdateOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const table = update.tableName;\n  const {primaryKey, value} = update;\n  const id: Record<string, PrimaryKeyValue> = {};\n  for (const key of primaryKey) {\n    id[key] = v.parse(value[key], primaryKeyValueSchema);\n  }\n  return tx`UPDATE ${tx(table)} SET ${tx(value)} WHERE ${Object.entries(\n    id,\n  ).flatMap(([key, value], i) =>\n    i ? [tx`AND`, tx`${tx(key)} = ${value}`] : tx`${tx(key)} = ${value}`,\n  )}`;\n}\n\nfunction getDeleteSQL(\n  tx: postgres.TransactionSql,\n  deleteOp: DeleteOp,\n): postgres.PendingQuery<postgres.Row[]> {\n  const {tableName, primaryKey, value} = deleteOp;\n\n  const conditions = [];\n  for (const key of primaryKey) {\n    if (conditions.length > 0) {\n      conditions.push(tx`AND`);\n    }\n    conditions.push(tx`${tx(key)} = ${value[key]}`);\n  }\n\n  return tx`DELETE FROM ${tx(tableName)} WHERE ${conditions}`;\n}\n\nasync function checkSchemaVersionAndIncrementLastMutationID(\n  tx: PostgresTransaction,\n  shard: ShardID,\n  clientGroupID: string,\n  clientID: string,\n  receivedMutationID: number,\n) {\n  const [{lastMutationID}] = await tx<{lastMutationID: bigint}[]>`\n    INSERT INTO ${tx(upstreamSchema(shard))}.clients \n      as current (\"clientGroupID\", \"clientID\", \"lastMutationID\")\n          VALUES (${clientGroupID}, ${clientID}, ${1})\n      ON CONFLICT (\"clientGroupID\", \"clientID\")\n      DO UPDATE SET \"lastMutationID\" = current.\"lastMutationID\" + 1\n      RETURNING \"lastMutationID\"\n  `;\n\n  // ABORT if the resulting lastMutationID is not equal to the receivedMutationID.\n  if (receivedMutationID < lastMutationID) {\n    throw new MutationAlreadyProcessedError(\n      clientID,\n      receivedMutationID,\n      lastMutationID,\n    );\n  } else if (receivedMutationID > lastMutationID) {\n    throw new ProtocolError({\n      kind: ErrorKind.InvalidPush,\n      message: `Push contains unexpected mutation id ${receivedMutationID} for client ${clientID}. Expected mutation id ${lastMutationID.toString()}.`,\n      origin: ErrorOrigin.ZeroCache,\n    });\n  }\n}\n\n// The slice of information from the Query object in Postgres.js that gets logged for debugging.\n// https://github.com/porsager/postgres/blob/f58cd4f3affd3e8ce8f53e42799672d86cd2c70b/src/connection.js#L219\ntype Query = {string: string; parameters: object[]};\n"],"mappings":"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"}

package/out/zero-cache/src/services/replicator/change-log-cookies.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The change log's *second* job.
+ *
+ * A change log is a buffer **and** a cookie jar. The buffer catches a
+ * reconnecting subscriber up to the head; the cookie jar holds the backfill
+ * progress state that the change-streamer hands the change-source on every
+ * `startStream`, so that the change source never has to persist backfill state
+ * upstream. See `change-log-db.ts` for the buffer.
+ *
+ * There are two cookies, mirroring the two `cdc` tables the Postgres change log
+ * has always carried (`change-streamer/schema/tables.ts`):
+ *
+ * - **table metadata**, the most current {@link TableMetadata} of a table, which
+ *   a {@link BackfillRequest} has to carry; and
+ * - **backfilling columns**, the opaque {@link BackfillID} of every column whose
+ *   backfill has not completed.
+ *
+ * Both are a *fold over the change stream*: the cookie set is only meaningful
+ * paired with the watermark it was folded up to. {@link cookieOps} is that fold,
+ * expressed transport-free so that the Postgres change log and the SQLite change
+ * log cannot drift from each other — they must agree on all eight transitions
+ * forever, and the failure mode if they disagree is a backfill that is silently
+ * never re-requested. The two interpreters are {@link ChangeLogCookieWriter}
+ * here and `Storer.#trackBackfillMetadata()` in
+ * `change-streamer/storer.ts`.
+ *
+ * The tables live in the change-log database rather than in the replica: the
+ * replicator is a subscriber *downstream* of the change-streamer's write loop,
+ * so its state version trails the log's head, and pairing its cookies with the
+ * log's resume watermark would lose every backfill that completed in between.
+ * The replica's own copies (`_zero.tableMetadata`, `_zero.column_metadata`) are
+ * the *seed* source; these are the *working* set.
+ */
+import type { Database } from '../../../../zqlite/src/db.ts';
+import type { BackfillID, Identifier, SchemaChange, TableMetadata } from '../change-source/protocol/current/data.ts';
+import { type BackfillRequest } from '../change-source/protocol/current/upstream.ts';
+export declare const CHANGE_LOG_TABLE_METADATA_TABLE = "_zero.changeLogTableMetadata";
+export declare const CHANGE_LOG_BACKFILLING_TABLE = "_zero.changeLogBackfilling";
+export declare const CREATE_CHANGE_LOG_COOKIE_SCHEMA = "\n  CREATE TABLE \"_zero.changeLogTableMetadata\" (\n    \"schema\"   TEXT NOT NULL,\n    \"table\"    TEXT NOT NULL,\n    \"metadata\" TEXT NOT NULL,\n    PRIMARY KEY (\"schema\", \"table\")\n  );\n\n  CREATE TABLE \"_zero.changeLogBackfilling\" (\n    \"schema\"   TEXT NOT NULL,\n    \"table\"    TEXT NOT NULL,\n    \"column\"   TEXT NOT NULL,\n    \"backfill\" TEXT NOT NULL,\n    PRIMARY KEY (\"schema\", \"table\", \"column\")\n  );\n";
+export declare const DROP_CHANGE_LOG_COOKIE_TABLES = "\n  DROP TABLE IF EXISTS \"_zero.changeLogTableMetadata\";\n  DROP TABLE IF EXISTS \"_zero.changeLogBackfilling\";\n";
+export type TableMetadataCookie = {
+    readonly schema: string;
+    readonly table: string;
+    readonly metadata: TableMetadata;
+};
+export type BackfillCookie = {
+    readonly schema: string;
+    readonly table: string;
+    readonly column: string;
+    readonly backfill: BackfillID;
+};
+/**
+ * The whole cookie set, as of the log's head. Both lists are ordered by their
+ * primary key so that two stores' sets can be compared directly.
+ */
+export type CookieSet = {
+    readonly tableMetadata: readonly TableMetadataCookie[];
+    readonly backfilling: readonly BackfillCookie[];
+};
+export declare const EMPTY_COOKIE_SET: CookieSet;
+/**
+ * A transport-free description of a cookie mutation. This is the whole of what
+ * a {@link SchemaChange} means to the cookie jar; everything else about the
+ * change belongs to the buffer.
+ */
+export type CookieOp = {
+    op: 'upsert-metadata';
+    table: Identifier;
+    metadata: TableMetadata;
+} | {
+    op: 'upsert-backfill';
+    table: Identifier;
+    column: string;
+    backfill: BackfillID;
+} | {
+    op: 'rename-table';
+    old: Identifier;
+    new: Identifier;
+} | {
+    op: 'drop-table';
+    table: Identifier;
+} | {
+    op: 'rename-column';
+    table: Identifier;
+    old: string;
+    new: string;
+} | {
+    op: 'drop-column';
+    table: Identifier;
+    column: string;
+} | {
+    op: 'complete-backfill';
+    table: Identifier;
+    columns: readonly string[];
+};
+export type CookieOpTag = CookieOp['op'];
+/**
+ * The fold, and the only place either store decides what a schema change means
+ * for the cookie set. Both interpreters are mechanical translations of what this
+ * returns, in the order it returns them.
+ *
+ * Changes that carry no cookie state — index changes, and the `create-table` /
+ * `add-column` variants whose optional `metadata` and `backfill` fields are
+ * absent — produce no ops.
+ */
+export declare function cookieOps(change: SchemaChange): CookieOp[];
+/**
+ * The SQLite interpreter of {@link cookieOps}, over prepared statements on the
+ * change-log database.
+ *
+ * The statements run inside the log's transaction, in stream order, at the point
+ * the schema change is appended (see `ChangeLogStreamWriter`). That is what
+ * makes the cookie set atomic with the head — a crash cannot leave cookies ahead
+ * of or behind the rows they were folded from — and what makes an aborted
+ * transaction discard its cookies with its rows, for free.
+ *
+ * Statements are prepared against the tables as they exist now, so an instance
+ * does not survive a reconcile that drops and recreates them.
+ */
+export declare class ChangeLogCookieWriter {
+    #private;
+    constructor(db: Database);
+    /** Applies the change's cookie ops, returning the ops that were applied. */
+    apply(change: SchemaChange): CookieOp[];
+}
+/**
+ * The in-memory interpreter of {@link cookieOps}: the third one, and the only
+ * one that is not a store.
+ *
+ * A replica-derived cookie set is a snapshot at the replica's state version,
+ * which trails the change log's head, so it cannot be compared with a
+ * Postgres-derived set directly. This carries it forward over the schema changes
+ * the log holds in between, which turns "the two stores disagree, but they are
+ * also at different positions" into an exact equality — and makes a
+ * disagreement between any two of the three interpreters visible as an
+ * inequality that neither store would have noticed on its own.
+ *
+ * `changes` must be the log's schema changes over `(from, to]` in stream order.
+ * Anything else produces a set that belongs to no watermark.
+ */
+export declare function foldCookies(cookies: CookieSet, changes: Iterable<SchemaChange>): CookieSet;
+/**
+ * Returns one {@link BackfillRequest} for each table with an active backfill.
+ * Each request contains the stored table metadata, if available.
+ */
+export declare function backfillRequestsFrom(cookies: CookieSet): BackfillRequest[];
+/**
+ * Reads the whole cookie set, ordered by primary key. This is what a
+ * change-streamer would hand `startStream`, and what the Postgres-derived and
+ * replica-derived sets are compared against.
+ */
+export declare function readCookies(db: Database): CookieSet;
+/**
+ * Replaces the cookie set wholesale.
+ *
+ * The cookies are unversioned point-in-time state, so a reconciliation that
+ * moves the head invalidates them: truncating the stream above `W` does not roll
+ * the cookie set back to `W`, and the truncated transactions can contain
+ * `create-table`, `add-column`, and `backfill-completed`. The caller must run
+ * this in the same transaction as the reconciliation that invalidated them.
+ */
+export declare function replaceCookies(db: Database, cookies: CookieSet): void;
+/** Retained cookie rows, by table. Both are normally zero. */
+export type CookieRowCounts = {
+    readonly tableMetadata: number;
+    readonly backfilling: number;
+};
+export declare function readCookieRowCounts(db: Database): CookieRowCounts;
+//# sourceMappingURL=change-log-cookies.d.ts.map

package/out/zero-cache/src/services/replicator/change-log-cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-log-cookies.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/replicator/change-log-cookies.ts"],"names":[],"mappings":"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"}