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

package/out/zero-cache/src/config/normalize.js

@@ -14,9 +14,18 @@ function assertNormalized(config) {
 	assert(config.taskID, "missing --task-id");
 	assert(config.changeStreamer.port, "missing --change-streamer-port");
 	assert(config.changeStreamer.address, "missing --change-streamer-address");
+	const { sqliteChangeLogMode, sqliteChangeLogReadPercent, sqliteChangeLogRetentionMs, sqliteChangeLogReadBatchRows, sqliteChangeLogPurgeBatchRows, sqliteChangeLogBarrierTimeoutMs } = config.changeStreamer;
+	assert(Number.isSafeInteger(sqliteChangeLogReadPercent) && sqliteChangeLogReadPercent >= 0 && sqliteChangeLogReadPercent <= 100, "--change-streamer-sqlite-change-log-read-percent must be an integer between 0 and 100");
+	assert(sqliteChangeLogMode === "serve" || sqliteChangeLogReadPercent === 0, "--change-streamer-sqlite-change-log-read-percent must be 0 unless --change-streamer-sqlite-change-log-mode=serve");
+	for (const [flag, value] of [
+		["retention-ms", sqliteChangeLogRetentionMs],
+		["read-batch-rows", sqliteChangeLogReadBatchRows],
+		["purge-batch-rows", sqliteChangeLogPurgeBatchRows],
+		["barrier-timeout-ms", sqliteChangeLogBarrierTimeoutMs]
+	]) assert(Number.isSafeInteger(value) && value > 0, `--change-streamer-sqlite-change-log-${flag} must be a positive integer`);
 	assert(config.litestream.port, "missing --litestream-port");
 	assert(!config.litestream.backupUsingV5 || config.litestream.restoreUsingV5, "--litestream-backup-using-v5 requires --litestream-restore-using-v5");
-	assert(!config.litestream.backupUsingV5 || config.litestream.executableV5 !== void 0 && config.litestream.executable === config.litestream.executableV5, "--litestream-backup-using-v5 requires --litestream-executable to be flipped to the v5 binary (--litestream-executable must equal --litestream-executable-v5)");
+	assert(!config.litestream.backupURL || config.litestream.executableV5 || !(config.litestream.restoreUsingV5 || config.litestream.backupUsingV5), "--litestream-restore-using-v5 and --litestream-backup-using-v5 require --litestream-executable to be specified");
 	assert(config.change.db, "missing --change-db");
 	assert(config.cvr.db, "missing --cvr-db");
 	assertNotUndefined(config.numSyncWorkers, "missing --num-sync-workers");

package/out/zero-cache/src/config/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","names":[],"sources":["../../../../../zero-cache/src/config/normalize.ts"],"sourcesContent":["import {availableParallelism} from 'node:os';\nimport type {LogContext} from '@rocicorp/logger';\nimport {nanoid} from 'nanoid';\nimport {assert, assertNotUndefined} from '../../../shared/src/asserts.ts';\nimport {getHostIp} from './network.ts';\nimport type {ZeroConfig} from './zero-config.ts';\n\n/** {@link ZeroConfig} with defaults set per option documentation. */\nexport type NormalizedZeroConfig = ZeroConfig & {\n  taskID: string;\n  changeStreamer: {\n    port: number;\n    address: string;\n  };\n  change: {\n    db: string;\n  };\n  cvr: {\n    db: string;\n  };\n  litestream: {\n    port: number;\n  };\n  numSyncWorkers: number;\n};\n\nexport function isDevelopmentMode(): boolean {\n  return process.env.NODE_ENV === 'development';\n}\n\nfunction isRunningInECS(): boolean {\n  // https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-environment-variables.html\n  return process.env.ECS_CONTAINER_METADATA_URI_V4 !== undefined;\n}\n\nconst DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS = 20_000;\n\nexport function assertNormalized(\n  config: ZeroConfig,\n): asserts config is NormalizedZeroConfig {\n  assert(config.taskID, 'missing --task-id');\n  assert(config.changeStreamer.port, 'missing --change-streamer-port');\n  assert(config.changeStreamer.address, 'missing --change-streamer-address');\n  assert(config.litestream.port, 'missing --litestream-port');\n  assert(\n    !config.litestream.backupUsingV5 || config.litestream.restoreUsingV5,\n    '--litestream-backup-using-v5 requires --litestream-restore-using-v5',\n  );\n  // The `litestream replicate` process always runs --litestream-executable, so\n  // enabling v5 backups (which write the LTX format read by the VFS monitor)\n  // requires --litestream-executable itself to have been flipped to the v5\n  // binary. Restoring is verified separately via --litestream-restore-using-v5,\n  // which is the prerequisite step that must roll out *before* the executable\n  // is flipped (so every replica can restore both WAL and LTX formats).\n  assert(\n    !config.litestream.backupUsingV5 ||\n      (config.litestream.executableV5 !== undefined &&\n        config.litestream.executable === config.litestream.executableV5),\n    '--litestream-backup-using-v5 requires --litestream-executable to be ' +\n      'flipped to the v5 binary (--litestream-executable must equal ' +\n      '--litestream-executable-v5)',\n  );\n  assert(config.change.db, 'missing --change-db');\n  assert(config.cvr.db, 'missing --cvr-db');\n  assertNotUndefined(config.numSyncWorkers, 'missing --num-sync-workers');\n\n  if (!isDevelopmentMode()) {\n    assert(\n      config.adminPassword,\n      'missing --admin-password: required in production mode',\n    );\n  }\n}\n\n/**\n * Normalizes the parsed `config` by setting defaults from the environment\n * or from other options as documented. When defaults are applied, the\n * corresponding `env` variable is updated so that the settings are propagated\n * to spawned child workers. Child workers can then call\n * {@link assertNormalized} to verify that the expected defaults have been set.\n */\nexport function normalizeZeroConfig(\n  lc: LogContext,\n  config: ZeroConfig,\n  env: NodeJS.ProcessEnv,\n  defaultTaskID?: string,\n): NormalizedZeroConfig {\n  if (!config.taskID) {\n    const taskID = defaultTaskID ?? nanoid();\n    config.taskID = taskID;\n    env['ZERO_TASK_ID'] = taskID;\n  }\n  if (!config.changeStreamer.port) {\n    const port = config.port + 1;\n    config.changeStreamer.port = port;\n    env['ZERO_CHANGE_STREAMER_PORT'] = String(port);\n  }\n  if (!config.litestream.port) {\n    const port = config.port + 2;\n    config.litestream.port = port;\n    env['ZERO_LITESTREAM_PORT'] = String(port);\n  }\n  if (config.numSyncWorkers === undefined) {\n    // Reserve 1 core for the replicator. The change-streamer is not CPU heavy.\n    const numSyncers = Math.max(1, availableParallelism() - 1);\n    config.numSyncWorkers = numSyncers;\n    env['ZERO_NUM_SYNC_WORKERS'] = String(numSyncers);\n  }\n\n  const hostIP = getHostIp(\n    lc,\n    config.changeStreamer.discoveryInterfacePreferences,\n  );\n  if (!config.changeStreamer.address) {\n    const {port} = config.changeStreamer;\n    const address = `${hostIP}:${port}`;\n    config.changeStreamer.address = address;\n    env['ZERO_CHANGE_STREAMER_ADDRESS'] = address;\n  }\n\n  if (!config.change.db) {\n    config.change.db = config.upstream.db;\n    env['ZERO_CHANGE_DB'] = config.upstream.db;\n  }\n\n  if (!config.cvr.db) {\n    config.cvr.db = config.upstream.db;\n    env['ZERO_CVR_DB'] = config.upstream.db;\n  }\n\n  if (!config.keepaliveTimeoutMs && isRunningInECS()) {\n    config.keepaliveTimeoutMs = DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS;\n    env['ZERO_KEEPALIVE_TIMEOUT_MS'] = String(DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS);\n  }\n\n  lc.info?.(`runtime env: taskID=${config.taskID}, hostIP=${hostIP}`);\n\n  return {\n    ...config,\n    taskID: config.taskID,\n\n    changeStreamer: {\n      ...config.changeStreamer,\n      port: config.changeStreamer.port,\n      address: config.changeStreamer.address,\n    },\n\n    litestream: {\n      ...config.litestream,\n      port: config.litestream.port,\n    },\n\n    change: {\n      ...config.change,\n      db: config.change.db,\n    },\n\n    cvr: {\n      ...config.cvr,\n      db: config.cvr.db,\n    },\n\n    numSyncWorkers: config.numSyncWorkers,\n  };\n}\n"],"mappings":";;;;;AA0BA,SAAgB,oBAA6B;CAC3C,OAAA,QAAA,IAAA,aAAgC;AAClC;AAEA,SAAS,iBAA0B;CAEjC,OAAO,QAAQ,IAAI,kCAAkC,KAAA;AACvD;AAEA,IAAM,mCAAmC;AAEzC,SAAgB,iBACd,QACwC;CACxC,OAAO,OAAO,QAAQ,mBAAmB;CACzC,OAAO,OAAO,eAAe,MAAM,gCAAgC;CACnE,OAAO,OAAO,eAAe,SAAS,mCAAmC;CACzE,OAAO,OAAO,WAAW,MAAM,2BAA2B;CAC1D,OACE,CAAC,OAAO,WAAW,iBAAiB,OAAO,WAAW,gBACtD,qEACF;CAOA,OACE,CAAC,OAAO,WAAW,iBAChB,OAAO,WAAW,iBAAiB,KAAA,KAClC,OAAO,WAAW,eAAe,OAAO,WAAW,cACvD,8JAGF;CACA,OAAO,OAAO,OAAO,IAAI,qBAAqB;CAC9C,OAAO,OAAO,IAAI,IAAI,kBAAkB;CACxC,mBAAmB,OAAO,gBAAgB,4BAA4B;CAEtE,IAAI,CAAC,kBAAkB,GACrB,OACE,OAAO,eACP,uDACF;AAEJ;;;;;;;;AASA,SAAgB,oBACd,IACA,QACA,KACA,eACsB;CACtB,IAAI,CAAC,OAAO,QAAQ;EAClB,MAAM,SAAS,iBAAiB,OAAO;EACvC,OAAO,SAAS;EAChB,IAAI,kBAAkB;CACxB;CACA,IAAI,CAAC,OAAO,eAAe,MAAM;EAC/B,MAAM,OAAO,OAAO,OAAO;EAC3B,OAAO,eAAe,OAAO;EAC7B,IAAI,+BAA+B,OAAO,IAAI;CAChD;CACA,IAAI,CAAC,OAAO,WAAW,MAAM;EAC3B,MAAM,OAAO,OAAO,OAAO;EAC3B,OAAO,WAAW,OAAO;EACzB,IAAI,0BAA0B,OAAO,IAAI;CAC3C;CACA,IAAI,OAAO,mBAAmB,KAAA,GAAW;EAEvC,MAAM,aAAa,KAAK,IAAI,GAAG,qBAAqB,IAAI,CAAC;EACzD,OAAO,iBAAiB;EACxB,IAAI,2BAA2B,OAAO,UAAU;CAClD;CAEA,MAAM,SAAS,UACb,IACA,OAAO,eAAe,6BACxB;CACA,IAAI,CAAC,OAAO,eAAe,SAAS;EAClC,MAAM,EAAC,SAAQ,OAAO;EACtB,MAAM,UAAU,GAAG,OAAO,GAAG;EAC7B,OAAO,eAAe,UAAU;EAChC,IAAI,kCAAkC;CACxC;CAEA,IAAI,CAAC,OAAO,OAAO,IAAI;EACrB,OAAO,OAAO,KAAK,OAAO,SAAS;EACnC,IAAI,oBAAoB,OAAO,SAAS;CAC1C;CAEA,IAAI,CAAC,OAAO,IAAI,IAAI;EAClB,OAAO,IAAI,KAAK,OAAO,SAAS;EAChC,IAAI,iBAAiB,OAAO,SAAS;CACvC;CAEA,IAAI,CAAC,OAAO,sBAAsB,eAAe,GAAG;EAClD,OAAO,qBAAqB;EAC5B,IAAI,+BAA+B,OAAO,gCAAgC;CAC5E;CAEA,GAAG,OAAO,uBAAuB,OAAO,OAAO,WAAW,QAAQ;CAElE,OAAO;EACL,GAAG;EACH,QAAQ,OAAO;EAEf,gBAAgB;GACd,GAAG,OAAO;GACV,MAAM,OAAO,eAAe;GAC5B,SAAS,OAAO,eAAe;EACjC;EAEA,YAAY;GACV,GAAG,OAAO;GACV,MAAM,OAAO,WAAW;EAC1B;EAEA,QAAQ;GACN,GAAG,OAAO;GACV,IAAI,OAAO,OAAO;EACpB;EAEA,KAAK;GACH,GAAG,OAAO;GACV,IAAI,OAAO,IAAI;EACjB;EAEA,gBAAgB,OAAO;CACzB;AACF"}
+{"version":3,"file":"normalize.js","names":[],"sources":["../../../../../zero-cache/src/config/normalize.ts"],"sourcesContent":["import {availableParallelism} from 'node:os';\nimport type {LogContext} from '@rocicorp/logger';\nimport {nanoid} from 'nanoid';\nimport {assert, assertNotUndefined} from '../../../shared/src/asserts.ts';\nimport {getHostIp} from './network.ts';\nimport type {ZeroConfig} from './zero-config.ts';\n\n/** {@link ZeroConfig} with defaults set per option documentation. */\nexport type NormalizedZeroConfig = ZeroConfig & {\n  taskID: string;\n  changeStreamer: {\n    port: number;\n    address: string;\n  };\n  change: {\n    db: string;\n  };\n  cvr: {\n    db: string;\n  };\n  litestream: {\n    port: number;\n  };\n  numSyncWorkers: number;\n};\n\nexport type LitestreamConfig = NormalizedZeroConfig['litestream'];\n\nexport function isDevelopmentMode(): boolean {\n  return process.env.NODE_ENV === 'development';\n}\n\nfunction isRunningInECS(): boolean {\n  // https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-environment-variables.html\n  return process.env.ECS_CONTAINER_METADATA_URI_V4 !== undefined;\n}\n\nconst DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS = 20_000;\n\nexport function assertNormalized(\n  config: ZeroConfig,\n): asserts config is NormalizedZeroConfig {\n  assert(config.taskID, 'missing --task-id');\n  assert(config.changeStreamer.port, 'missing --change-streamer-port');\n  assert(config.changeStreamer.address, 'missing --change-streamer-address');\n  const {\n    sqliteChangeLogMode,\n    sqliteChangeLogReadPercent,\n    sqliteChangeLogRetentionMs,\n    sqliteChangeLogReadBatchRows,\n    sqliteChangeLogPurgeBatchRows,\n    sqliteChangeLogBarrierTimeoutMs,\n  } = config.changeStreamer;\n  assert(\n    Number.isSafeInteger(sqliteChangeLogReadPercent) &&\n      sqliteChangeLogReadPercent >= 0 &&\n      sqliteChangeLogReadPercent <= 100,\n    '--change-streamer-sqlite-change-log-read-percent must be an integer between 0 and 100',\n  );\n  assert(\n    sqliteChangeLogMode === 'serve' || sqliteChangeLogReadPercent === 0,\n    '--change-streamer-sqlite-change-log-read-percent must be 0 unless --change-streamer-sqlite-change-log-mode=serve',\n  );\n  for (const [flag, value] of [\n    ['retention-ms', sqliteChangeLogRetentionMs],\n    ['read-batch-rows', sqliteChangeLogReadBatchRows],\n    ['purge-batch-rows', sqliteChangeLogPurgeBatchRows],\n    ['barrier-timeout-ms', sqliteChangeLogBarrierTimeoutMs],\n  ] as const) {\n    assert(\n      Number.isSafeInteger(value) && value > 0,\n      `--change-streamer-sqlite-change-log-${flag} must be a positive integer`,\n    );\n  }\n  assert(config.litestream.port, 'missing --litestream-port');\n  assert(\n    !config.litestream.backupUsingV5 || config.litestream.restoreUsingV5,\n    '--litestream-backup-using-v5 requires --litestream-restore-using-v5',\n  );\n  assert(\n    !config.litestream.backupURL ||\n      config.litestream.executableV5 ||\n      !(config.litestream.restoreUsingV5 || config.litestream.backupUsingV5),\n    '--litestream-restore-using-v5 and --litestream-backup-using-v5 ' +\n      'require --litestream-executable to be specified',\n  );\n  assert(config.change.db, 'missing --change-db');\n  assert(config.cvr.db, 'missing --cvr-db');\n  assertNotUndefined(config.numSyncWorkers, 'missing --num-sync-workers');\n\n  if (!isDevelopmentMode()) {\n    assert(\n      config.adminPassword,\n      'missing --admin-password: required in production mode',\n    );\n  }\n}\n\n/**\n * Normalizes the parsed `config` by setting defaults from the environment\n * or from other options as documented. When defaults are applied, the\n * corresponding `env` variable is updated so that the settings are propagated\n * to spawned child workers. Child workers can then call\n * {@link assertNormalized} to verify that the expected defaults have been set.\n */\nexport function normalizeZeroConfig(\n  lc: LogContext,\n  config: ZeroConfig,\n  env: NodeJS.ProcessEnv,\n  defaultTaskID?: string,\n): NormalizedZeroConfig {\n  if (!config.taskID) {\n    const taskID = defaultTaskID ?? nanoid();\n    config.taskID = taskID;\n    env['ZERO_TASK_ID'] = taskID;\n  }\n  if (!config.changeStreamer.port) {\n    const port = config.port + 1;\n    config.changeStreamer.port = port;\n    env['ZERO_CHANGE_STREAMER_PORT'] = String(port);\n  }\n  if (!config.litestream.port) {\n    const port = config.port + 2;\n    config.litestream.port = port;\n    env['ZERO_LITESTREAM_PORT'] = String(port);\n  }\n  if (config.numSyncWorkers === undefined) {\n    // Reserve 1 core for the replicator. The change-streamer is not CPU heavy.\n    const numSyncers = Math.max(1, availableParallelism() - 1);\n    config.numSyncWorkers = numSyncers;\n    env['ZERO_NUM_SYNC_WORKERS'] = String(numSyncers);\n  }\n\n  const hostIP = getHostIp(\n    lc,\n    config.changeStreamer.discoveryInterfacePreferences,\n  );\n  if (!config.changeStreamer.address) {\n    const {port} = config.changeStreamer;\n    const address = `${hostIP}:${port}`;\n    config.changeStreamer.address = address;\n    env['ZERO_CHANGE_STREAMER_ADDRESS'] = address;\n  }\n\n  if (!config.change.db) {\n    config.change.db = config.upstream.db;\n    env['ZERO_CHANGE_DB'] = config.upstream.db;\n  }\n\n  if (!config.cvr.db) {\n    config.cvr.db = config.upstream.db;\n    env['ZERO_CVR_DB'] = config.upstream.db;\n  }\n\n  if (!config.keepaliveTimeoutMs && isRunningInECS()) {\n    config.keepaliveTimeoutMs = DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS;\n    env['ZERO_KEEPALIVE_TIMEOUT_MS'] = String(DEFAULT_ECS_KEEPALIVE_TIMEOUT_MS);\n  }\n\n  lc.info?.(`runtime env: taskID=${config.taskID}, hostIP=${hostIP}`);\n\n  return {\n    ...config,\n    taskID: config.taskID,\n\n    changeStreamer: {\n      ...config.changeStreamer,\n      port: config.changeStreamer.port,\n      address: config.changeStreamer.address,\n    },\n\n    litestream: {\n      ...config.litestream,\n      port: config.litestream.port,\n    },\n\n    change: {\n      ...config.change,\n      db: config.change.db,\n    },\n\n    cvr: {\n      ...config.cvr,\n      db: config.cvr.db,\n    },\n\n    numSyncWorkers: config.numSyncWorkers,\n  };\n}\n"],"mappings":"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"}

package/out/zero-cache/src/config/zero-config.d.ts

@@ -111,6 +111,10 @@ export declare const zeroOptions: {
             type: v.Optional<boolean>;
             desc: string[];
         };
+        pgStreamInboundTimeoutMs: {
+            type: v.Optional<number>;
+            desc: string[];
+        };
     };
     /** @deprecated */
     push: {
@@ -256,6 +260,11 @@ export declare const zeroOptions: {
         type: v.Optional<boolean>;
         desc: string[];
     };
+    sqliteCorruptionChecks: {
+        type: v.Type<boolean>;
+        desc: string[];
+        hidden: boolean;
+    };
     enableQueryPlanner: {
         type: v.Type<boolean>;
         desc: string[];
@@ -415,11 +424,45 @@ export declare const zeroOptions: {
             type: v.Type<number>;
             desc: string[];
         };
+        sqliteChangeLogMode: {
+            type: v.Type<"off" | "write" | "compare" | "serve">;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogReadPercent: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogRetentionMs: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogReadBatchRows: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogPurgeBatchRows: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogBarrierTimeoutMs: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
         backPressureLimitHeapProportion: {
             type: v.Type<number>;
             desc: string[];
         };
-        flowControlConsensusPaddingSeconds: {
+        flowControlConsensusTimeoutProportion: {
+            type: v.Type<number>;
+            desc: string[];
+        };
+        flowControlSlowSubscriberGracePeriodSeconds: {
             type: v.Type<number>;
             desc: string[];
         };
@@ -489,6 +532,10 @@ export declare const zeroOptions: {
             type: v.Type<string>;
             desc: string[];
         };
+        configPathV5: {
+            type: v.Type<string>;
+            desc: string[];
+        };
         vfsExtensionPath: {
             type: v.Type<string>;
             desc: string[];
@@ -540,6 +587,10 @@ export declare const zeroOptions: {
             type: v.Type<number>;
             desc: string[];
         };
+        incrementalBackupIntervalSeconds: {
+            type: v.Type<number>;
+            desc: string[];
+        };
         snapshotBackupIntervalHours: {
             type: v.Type<number>;
             desc: string[];

package/out/zero-cache/src/config/zero-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zero-config.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/config/zero-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAUnD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAC,SAAS,EAAC,MAAM,kCAAkC,CAAC;AAEhE,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,eAAO,MAAM,UAAU;;;;;;;;;CA+CtB,CAAC;AAEF,eAAO,MAAM,YAAY;;;;;;;;;;CAwBxB,CAAC;AAEF,QAAA,MAAM,cAAc;;;;;;;;;CAmBnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE3D,QAAA,MAAM,oBAAoB;;;;;;;;;CAczB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE5D,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DhB,CAAC;AA0HF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,UAAU,EACV,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CACrD,CAAC;AAKF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;IAsDtB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAGlB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2OhB,kBAAkB;;;;;;QASlB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAucpB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAIpD,wBAAgB,aAAa,CAC3B,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAM,GAC7C,UAAU,CAaZ;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAM,GAC7C,oBAAoB,CAItB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,GAAG,SAAS,GACpD,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,eAAe,CAAC,EACnD,QAAQ,EAAE,MAAM,GAAG,SAAS,WAwC7B;AAYD,wBAAgB,kBAAkB,SAEjC"}
+{"version":3,"file":"zero-config.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/config/zero-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAUnD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAC,SAAS,EAAC,MAAM,kCAAkC,CAAC;AAEhE,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,eAAO,MAAM,UAAU;;;;;;;;;CA+CtB,CAAC;AAEF,eAAO,MAAM,YAAY;;;;;;;;;;CAwBxB,CAAC;AAEF,QAAA,MAAM,cAAc;;;;;;;;;CAmBnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE3D,QAAA,MAAM,oBAAoB;;;;;;;;;CAczB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE5D,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DhB,CAAC;AA0HF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,UAAU,EACV,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CACrD,CAAC;AAKF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA4EtB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAGlB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAoPhB,kBAAkB;;;;;;QASlB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8kBpB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAIpD,wBAAgB,aAAa,CAC3B,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAM,GAC7C,UAAU,CAaZ;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAM,GAC7C,oBAAoB,CAItB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,GAAG,SAAS,GACpD,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,eAAe,CAAC,EACnD,QAAQ,EAAE,MAAM,GAAG,SAAS,WAwC7B;AAYD,wBAAgB,kBAAkB,SAEjC"}

package/out/zero-cache/src/config/zero-config.js

@@ -273,6 +273,27 @@ var zeroOptions = {
 				``,
 				`(Note that this option has no effect for Postgres versions before 17.)`
 			]
+		},
+		pgStreamInboundTimeoutMs: {
+			type: valita_exports.number().optional(),
+			desc: [
+				`The time (in milliseconds) without any inbound message from the upstream`,
+				`wal sender after which the replication stream is considered unresponsive`,
+				`and torn down to force a reconnect.`,
+				``,
+				`Defaults to 2x the server's {bold wal_sender_timeout}. That suits idle`,
+				`streams, but a busy wal sender can be legitimately silent for longer —`,
+				`e.g. while decoding through WAL from unpublished tables, or assembling a`,
+				`large transaction that is only sent at commit. If the server's`,
+				`{bold wal_sender_timeout} is aggressive (some managed environments`,
+				`default it as low as 5 seconds), the resulting teardown aborts and`,
+				`replays the in-flight transaction, which can prevent replication from`,
+				`ever catching up on a large backlog. Set this option to widen the`,
+				`client-side threshold without changing the server setting.`,
+				``,
+				`(This option has no effect when {bold wal_sender_timeout} is 0, which`,
+				`disables inbound liveness detection entirely.)`
+			]
 		}
 	},
 	/** @deprecated */
@@ -347,6 +368,11 @@ var zeroOptions = {
 			`This is useful for debugging and performance tuning.`
 		]
 	},
+	sqliteCorruptionChecks: {
+		type: valita_exports.boolean().default(false),
+		desc: [`Run SQLite quick_check and integrity_check when corruption is detected.`, `These checks scan the replica and can take a long time on large databases.`],
+		hidden: true
+	},
 	enableQueryPlanner: {
 		type: valita_exports.boolean().default(true),
 		desc: [
@@ -513,6 +539,43 @@ var zeroOptions = {
 				`immediately, since the incoming request indicates that the task is registered as a target.`
 			]
 		},
+		sqliteChangeLogMode: {
+			type: literalUnion("off", "write", "compare", "serve").default("off"),
+			desc: [`Controls the staged SQLite change-log rollout. Modes are cumulative:`, `{bold off}, {bold write}, {bold compare}, and {bold serve}.`],
+			hidden: true
+		},
+		sqliteChangeLogReadPercent: {
+			type: valita_exports.number().default(0),
+			desc: [`The stable percentage of eligible catchup subscriptions served from SQLite.`],
+			hidden: true
+		},
+		sqliteChangeLogRetentionMs: {
+			type: valita_exports.number().default(6e4),
+			desc: [`The minimum time window retained in the SQLite change log.`],
+			hidden: true
+		},
+		sqliteChangeLogReadBatchRows: {
+			type: valita_exports.number().default(1e3),
+			desc: [`The target number of rows in each SQLite catchup read batch.`],
+			hidden: true
+		},
+		sqliteChangeLogPurgeBatchRows: {
+			type: valita_exports.number().default(1e3),
+			desc: [`The target number of rows in each SQLite purge batch.`],
+			hidden: true
+		},
+		sqliteChangeLogBarrierTimeoutMs: {
+			type: valita_exports.number().default(3e5),
+			desc: [
+				`The maximum wait for the SQLite required-head barrier. This is a`,
+				`backstop for a wedged replica on an idle shard, where waiting costs`,
+				`nothing and would otherwise go unnoticed. A shard with traffic is`,
+				`bounded well before this by the subscriber's backlog reaching its`,
+				`high water mark, which is the point at which waiting starts holding`,
+				`up replication.`
+			],
+			hidden: true
+		},
 		backPressureLimitHeapProportion: {
 			type: valita_exports.number().default(.04),
 			desc: [
@@ -536,22 +599,58 @@ var zeroOptions = {
 				`throughput.`
 			]
 		},
-		flowControlConsensusPaddingSeconds: {
-			type: valita_exports.number().default(1),
+		flowControlConsensusTimeoutProportion: {
+			type: valita_exports.number().default(2),
 			desc: [
-				`During periodic flow control checks (every 64kb), the amount of time to wait after the`,
-				`majority of subscribers have acked, after which replication will continue even if`,
-				`some subscribers have yet to ack. (Note that this is not a timeout for the {italic entire} send,`,
-				`but a timeout that starts {italic after} the majority of receivers have acked.)`,
+				`During periodic flow control checks (every 64kb), the amount of time to wait after the majority`,
+				`of subscribers have acked, proportional to that interval, after which replication will continue`,
+				`even if some subscribers have yet to ack.`,
 				``,
 				`This allows a bounded amount of time for backlogged subscribers to catch up on each flush`,
 				`without forcing all subscribers to wait for the entire backlog to be processed. It is also`,
 				`useful for mitigating the effect of unresponsive subscribers due to severed websocket`,
-				`connections (until liveness checks disconnect them).`,
+				`connections or pathological zombie situations (until liveness checks or laggard detection`,
+				`disconnects them).`,
+				``,
+				`For example, if the majority of subscribers ack a message in 2.5ms, a padding proportion of`,
+				`1.0 instructs replication to continue after an additional 2.5ms; for a proportion of 2.0, an`,
+				`additional 5.0ms, etc. The default value of 2.0 allows for a subscriber to be 3x slower than the`,
+				`majority in the steady state, while similarly bounding the extent to which a temporarily lagging`,
+				`subscriber (e.g. due to catchup) slows down the fleet.`,
+				``,
+				`Note that subscribers that continually exceed the timeout will eventually be disconnected and`,
+				`instructed to shutdown in order to protect the healthy subscribers. It is thus important that`,
+				`the proportion account for expected variance in processing speed across subscribers.`,
 				``,
 				`Set this to a negative number to disable early flow control releases. (Not recommended, but`,
 				`available as an emergency measure.)`
 			]
+		},
+		flowControlSlowSubscriberGracePeriodSeconds: {
+			type: valita_exports.number().default(30),
+			desc: [
+				`The period of time after which a lagging subscriber is disconnected and instructed to`,
+				`restart. A subscriber is considered lagging if it {italic continuously} (1) exceeds the`,
+				`consensus timeout and (2) fails to exceed the change rate of healthy subscribers. These`,
+				`conditions distinguish expected, temporary periods of slowness from pathological`,
+				`scenarios, such as zombie tasks, in which the subscriber is unlikely to recover.`,
+				``,
+				`In particular, the second condition excludes subscribers that are performing initial`,
+				`catchup, as the rate of change for catchup must eventually exceed the rate of upstream`,
+				`changes. Note, however, that catchup rate can be legitimately slow during (rare) expensive`,
+				`operations such as index creation.`,
+				``,
+				`Thus, this grace period caps the amount of time that a lagging subscriber degrades overall`,
+				`throughput, but should be long enough to allow for legitimate intervals of slowness.`,
+				``,
+				`Note that in the pathological case where a catchup operation exceeds this grace period,`,
+				`the system will eventually recover after the next backup/restore cycle, as the expensive`,
+				`operation (e.g. index creation) will have been applied to the restored replica and no longer`,
+				`executed during catchup.`,
+				``,
+				`Set this to 0 or a negative number to disable laggard detection. (Not recommended, but`,
+				`available as an emergency measure.)`
+			]
 		}
 	},
 	taskID: {
@@ -663,8 +762,12 @@ var zeroOptions = {
 			]
 		},
 		restoreUsingV5: {
-			type: valita_exports.boolean().default(false),
-			desc: [`Restores the backup using the {bold ZERO_LITESTREAM_EXECUTABLE_V5} if specified.`]
+			type: valita_exports.boolean().default(true),
+			desc: [
+				`Restores the backup using the {bold ZERO_LITESTREAM_EXECUTABLE_V5} if specified.`,
+				`This provides a recovery path if rolling back from {bold ZERO_LITESTREAM_BACKUP_USING_V5}`,
+				`as v5 restores from both v3 and v5 backups (whichever is more recent).`
+			]
 		},
 		backupUsingV5: {
 			type: valita_exports.boolean().default(false),
@@ -686,16 +789,30 @@ var zeroOptions = {
 				`* {bold ZERO_LOG_FORMAT} for the log type`
 			]
 		},
+		configPathV5: {
+			type: valita_exports.string().default("./src/services/litestream/config-v5.yml"),
+			desc: [
+				`Path to the litestream v5 yaml config file. zero-cache will run this with its`,
+				`environment variables, which can be referenced in the file via $\\{ENV\\}`,
+				`substitution, for example:`,
+				`* {bold ZERO_REPLICA_FILE} for the db path`,
+				`* {bold ZERO_LITESTREAM_BACKUP_LOCATION} for the db replica url`,
+				`* {bold ZERO_LITESTREAM_LOG_LEVEL} for the log level`,
+				`* {bold ZERO_LOG_FORMAT} for the log type`
+			]
+		},
 		vfsExtensionPath: {
 			type: valita_exports.string().default("/usr/local/lib/litestream-vfs.so"),
 			desc: [`Path to the Litestream v0.5.x SQLite VFS loadable extension used by`, `the backup watermark reader to query the backup directly.`]
 		},
 		vfsProbeIntervalMs: {
-			type: valita_exports.number().default(30 * 1e3),
+			type: valita_exports.number().default(15 * 1e3),
 			desc: [
-				`Interval in milliseconds at which the standalone backup watermark reader`,
-				`logs the watermark when it is run without a parent worker. The integrated`,
-				`backup monitor requests watermarks on demand.`
+				`Interval in milliseconds litestream vfs extension polls the backup store (e.g. s3)`,
+				`to determine the most recent backup.`,
+				``,
+				`This, in turn, influences how quickly new backups are confirmed, allowing the`,
+				`change-streamer to ack the upstream change-source (e.g. replication slot).`
 			]
 		},
 		vfsProbeTimeoutMs: {
@@ -741,9 +858,12 @@ var zeroOptions = {
 			desc: [
 				`The size of the WAL file at which to perform an SQlite checkpoint to apply`,
 				`the writes in the WAL to the main database file. Each checkpoint creates`,
-				`a new WAL segment file that will be backed up by litestream. Smaller thresholds`,
+				`a new WAL segment file that will be backed up by litestream (v3). Smaller thresholds`,
 				`may improve read performance, at the expense of creating more files to download`,
-				`when restoring the replica from the backup.`
+				`when restoring the replica from the backup.`,
+				``,
+				`This setting is only relevant when replicating with litestream v3, and is ignored`,
+				`when replicating with litestream v5.`
 			]
 		},
 		minCheckpointPageCount: {
@@ -751,7 +871,10 @@ var zeroOptions = {
 			desc: [
 				`The WAL page count at which SQLite attempts a PASSIVE checkpoint, which`,
 				`transfers pages to the main database file without blocking writers.`,
-				`Defaults to {bold checkpointThresholdMB * 250} (since SQLite page size is 4KB).`
+				`Defaults to {bold checkpointThresholdMB * 250} (since SQLite page size is 4KB).`,
+				``,
+				`This setting is only relevant when replicating with litestream v3, and is ignored`,
+				`when replicating with litestream v5.`
 			]
 		},
 		maxCheckpointPageCount: {
@@ -759,26 +882,52 @@ var zeroOptions = {
 			desc: [
 				`The WAL page count at which SQLite performs a RESTART checkpoint, which`,
 				`blocks writers until complete. Defaults to {bold minCheckpointPageCount * 10}.`,
-				`Set to {bold 0} to disable RESTART checkpoints entirely.`
+				`Set to {bold 0} to disable RESTART checkpoints entirely.`,
+				``,
+				`This setting is only relevant when replicating with litestream v3, and is ignored`,
+				`when replicating with litestream v5.`
 			]
 		},
 		incrementalBackupIntervalMinutes: {
-			type: valita_exports.number().default(15),
+			type: valita_exports.number().default(5),
 			desc: [
-				`The interval between incremental backups of the replica. Shorter intervals`,
+				`The interval between incremental v3 backups of the replica. Shorter intervals`,
 				`reduce the amount of change history that needs to be replayed when catching`,
 				`up a new view-syncer, at the expense of increasing the number of files needed`,
-				`to download for the initial litestream restore.`
+				`to download for the initial litestream restore.`,
+				``,
+				`This option only applies to litestream v3 backups and will be deprecated/removed`,
+				`once the zero-cache is transitioned to litestream v5. For configuring v5 backup`,
+				`frequency, use {bold ZERO_LITESTREAM_INCREMENTAL_BACKUP_INTERVAL_SECONDS}.`
+			]
+		},
+		incrementalBackupIntervalSeconds: {
+			type: valita_exports.number().default(15),
+			desc: [
+				`The interval between incremental v5 backups of the replica. With litestream v5`,
+				`the upstream change source is not ACKed until the corresponding changes have been`,
+				`applied to the replica and backed up by litestream. As such, shorter intervals`,
+				`incur a higher number of backup storage writes and files managed (e.g. in s3),`,
+				`while longer intervals result requiring a larger buffer for changes upstream `,
+				`(e.g. per-replication slot wal records). The default value of 15 seconds targets`,
+				`an s3 API cost of ~$1/month (not counting storage costs).`,
+				``,
+				`This option only applies to litestream v5 backups. For v3 backups, use`,
+				`{bold ZERO_LITESTREAM_INCREMENTAL_BACKUP_INTERVAL_MINUTES}.`
 			]
 		},
 		snapshotBackupIntervalHours: {
-			type: valita_exports.number().default(12),
+			type: valita_exports.number().default(4),
 			desc: [
 				`The interval between snapshot backups of the replica. Snapshot backups`,
 				`make a full copy of the database to a new litestream generation. This`,
 				`improves restore time at the expense of bandwidth. Applications with a`,
 				`large database and low write rate can increase this interval to reduce`,
-				`network usage for backups (litestream defaults to 24 hours).`
+				`network usage for backups (litestream defaults to 24 hours).`,
+				``,
+				`This setting is applied when replicating with either litestream v3 or v5.`,
+				`Note, however, that snapshots are generally not needed to improve restore time`,
+				`with v5, and so a longer interval (e.g. the litestream default of 24h) is fine.`
 			]
 		},
 		restoreParallelism: {