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

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 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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"}
+{"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\n/**\n * Whether this process tree runs the change-streamer, as opposed to connecting\n * to one that another task runs.\n */\nexport function runsChangeStreamer(config: ZeroConfig): boolean {\n  const {mode, uri} = config.changeStreamer;\n  return mode === 'dedicated' && uri === undefined;\n}\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    sqliteChangeLogColdReadPercent,\n    sqliteChangeLogComparePercent,\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    Number.isSafeInteger(sqliteChangeLogColdReadPercent) &&\n      sqliteChangeLogColdReadPercent >= 0 &&\n      sqliteChangeLogColdReadPercent <= 100,\n    '--change-streamer-sqlite-change-log-cold-read-percent must be an integer between 0 and 100',\n  );\n  // This setting has no mode restriction. Comparison starts in `compare` mode.\n  assert(\n    Number.isSafeInteger(sqliteChangeLogComparePercent) &&\n      sqliteChangeLogComparePercent >= 0 &&\n      sqliteChangeLogComparePercent <= 100,\n    '--change-streamer-sqlite-change-log-compare-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  assert(\n    sqliteChangeLogMode === 'serve' || sqliteChangeLogColdReadPercent === 0,\n    '--change-streamer-sqlite-change-log-cold-read-percent must be 0 unless --change-streamer-sqlite-change-log-mode=serve',\n  );\n  // The cold gate only admits a task to the read gate; it never serves one on\n  // its own. A nonzero cold percentage with a zero read percentage is a\n  // silent no-op, which is the shape of a rollout that looks enabled and\n  // serves nothing.\n  assert(\n    sqliteChangeLogReadPercent > 0 || sqliteChangeLogColdReadPercent === 0,\n    '--change-streamer-sqlite-change-log-cold-read-percent must be 0 when --change-streamer-sqlite-change-log-read-percent is 0',\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-v5 to be specified',\n  );\n  assert(\n    !config.litestream.backupURL ||\n      !config.litestream.backupUsingV5 ||\n      config.litestream.vfsQueryExecutable,\n    '--litestream-backup-using-v5 requires --litestream-vfs-query-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[];
         };
+        pgPartialIndexTriggers: {
+            type: v.Type<boolean>;
+            hidden: boolean;
+        };
         pgStreamInboundTimeoutMs: {
             type: v.Optional<number>;
             desc: string[];
@@ -282,9 +286,11 @@ export declare const zeroOptions: {
             type: v.Optional<string>;
             desc: string[];
         };
+        /** @deprecated */
         maxConns: {
             type: v.Type<number>;
-            desc: string[];
+            deprecated: string[];
+            hidden: boolean;
         };
         statementTimeoutMs: {
             type: v.Type<number>;
@@ -434,6 +440,16 @@ export declare const zeroOptions: {
             desc: string[];
             hidden: boolean;
         };
+        sqliteChangeLogColdReadPercent: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
+        sqliteChangeLogComparePercent: {
+            type: v.Type<number>;
+            desc: string[];
+            hidden: boolean;
+        };
         sqliteChangeLogRetentionMs: {
             type: v.Type<number>;
             desc: string[];
@@ -536,15 +552,15 @@ export declare const zeroOptions: {
             type: v.Type<string>;
             desc: string[];
         };
-        vfsExtensionPath: {
-            type: v.Type<string>;
+        vfsQueryExecutable: {
+            type: v.Optional<string>;
             desc: string[];
         };
-        vfsProbeIntervalMs: {
+        vfsPollIntervalMs: {
             type: v.Type<number>;
             desc: string[];
         };
-        vfsProbeTimeoutMs: {
+        vfsPollTimeoutMs: {
             type: v.Type<number>;
             desc: string[];
         };
@@ -577,21 +593,34 @@ export declare const zeroOptions: {
         };
         minCheckpointPageCount: {
             type: v.Optional<number>;
-            desc: string[];
+            deprecated: string[];
+            hidden: boolean;
         };
         maxCheckpointPageCount: {
             type: v.Optional<number>;
             desc: string[];
         };
+        forceCheckpointThresholdMB: {
+            type: v.Type<number>;
+            desc: string[];
+        };
+        maxWalSizeMB: {
+            type: v.Type<number>;
+            desc: string[];
+        };
         incrementalBackupIntervalMinutes: {
             type: v.Type<number>;
             desc: string[];
         };
+        snapshotBackupIntervalHours: {
+            type: v.Type<number>;
+            desc: string[];
+        };
         incrementalBackupIntervalSeconds: {
             type: v.Type<number>;
             desc: string[];
         };
-        snapshotBackupIntervalHours: {
+        snapshotBackupIntervalHoursV5: {
             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;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"zero-config.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/config/zero-config.ts"],"names":[],"mappings":"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"}

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

@@ -274,6 +274,10 @@ var zeroOptions = {
 				`(Note that this option has no effect for Postgres versions before 17.)`
 			]
 		},
+		pgPartialIndexTriggers: {
+			type: valita_exports.boolean().default(false),
+			hidden: true
+		},
 		pgStreamInboundTimeoutMs: {
 			type: valita_exports.number().optional(),
 			desc: [
@@ -413,21 +417,19 @@ var zeroOptions = {
 				`the upstream database. If unspecified, the {bold upstream-db} will be used.`
 			]
 		},
+		/** @deprecated */
 		maxConns: {
 			type: valita_exports.number().default(5),
-			desc: [
-				`The maximum number of connections to open to the change database.`,
-				`This is used by the {bold change-streamer} for catching up`,
-				`{bold zero-cache} replication subscriptions.`
-			]
+			deprecated: [`Connections to the change db are created dynamically for subscriber catchup. Ensure`, `that the database supports sufficient connections for at least 5 + numViewSyncers.`],
+			hidden: true
 		},
 		statementTimeoutMs: {
-			type: valita_exports.number().default(2e4),
+			type: valita_exports.number().default(3e4),
 			desc: [
-				`Fail change-log transactions if a statement response from postgres is not received within`,
-				`the specified timeout. This differs from a postgres {bold statement_timeout} in that`,
-				`it is implemented to handle a pathological case in which Postgres does not return a`,
-				`response but otherwise believes the transaction to be idle.`
+				`Fail change-log db operations that make no progress within the specified timeout. This`,
+				`differs from a postgres {bold statement_timeout} in that it is implemented to handle a`,
+				`pathological case in which Postgres does not return a response but otherwise believes the`,
+				`connection to be idle (e.g. a half-open connection).`
 			],
 			hidden: true
 		},
@@ -549,6 +551,23 @@ var zeroOptions = {
 			desc: [`The stable percentage of eligible catchup subscriptions served from SQLite.`],
 			hidden: true
 		},
+		sqliteChangeLogColdReadPercent: {
+			type: valita_exports.number().default(0),
+			desc: [
+				`The stable percentage of eligible catchup subscriptions served from a`,
+				`SQLite change log that is younger than its retention window, i.e. one`,
+				`seeded less than {bold --change-streamer-sqlite-change-log-retention-ms}`,
+				`ago. Selection uses the same hash as`,
+				`{bold --change-streamer-sqlite-change-log-read-percent}, so a task that`,
+				`serves cold is always one that would serve warm.`
+			],
+			hidden: true
+		},
+		sqliteChangeLogComparePercent: {
+			type: valita_exports.number().default(1),
+			desc: [`The stable percentage of committed transactions whose catchup output is`, `compared between the Postgres and SQLite change logs in {bold compare} mode.`],
+			hidden: true
+		},
 		sqliteChangeLogRetentionMs: {
 			type: valita_exports.number().default(6e4),
 			desc: [`The minimum time window retained in the SQLite change log.`],
@@ -600,7 +619,7 @@ var zeroOptions = {
 			]
 		},
 		flowControlConsensusTimeoutProportion: {
-			type: valita_exports.number().default(2),
+			type: valita_exports.number().default(4),
 			desc: [
 				`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`,
@@ -614,7 +633,7 @@ var zeroOptions = {
 				``,
 				`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`,
+				`additional 5.0ms, etc. The default value of 4.0 allows for a subscriber to be 5x 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.`,
 				``,
@@ -774,7 +793,8 @@ var zeroOptions = {
 			desc: [
 				`Backs up the replica using Litestream v0.5.x and monitors cleanup`,
 				`watermarks by reading the backup through the Litestream SQLite VFS.`,
-				`This requires {bold ZERO_LITESTREAM_RESTORE_USING_V5}.`
+				`This requires {bold ZERO_LITESTREAM_RESTORE_USING_V5} and`,
+				`{bold ZERO_LITESTREAM_VFS_QUERY_EXECUTABLE}`
 			]
 		},
 		configPath: {
@@ -801,11 +821,11 @@ var zeroOptions = {
 				`* {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.`]
+		vfsQueryExecutable: {
+			type: valita_exports.string().optional(),
+			desc: [`Path to the rocicorp vfs-query executable that runs the VFS-based`, `polling of backup watermark. This is required when backing up with V5.`]
 		},
-		vfsProbeIntervalMs: {
+		vfsPollIntervalMs: {
 			type: valita_exports.number().default(15 * 1e3),
 			desc: [
 				`Interval in milliseconds litestream vfs extension polls the backup store (e.g. s3)`,
@@ -815,9 +835,9 @@ var zeroOptions = {
 				`change-streamer to ack the upstream change-source (e.g. replication slot).`
 			]
 		},
-		vfsProbeTimeoutMs: {
-			type: valita_exports.number().default(30 * 1e3),
-			desc: [`Timeout in milliseconds for requests to the Litestream VFS backup`, `watermark reader worker.`]
+		vfsPollTimeoutMs: {
+			type: valita_exports.number().default(10 * 1e3),
+			desc: [`Timeout in milliseconds for requests to the Litestream VFS poller.`]
 		},
 		vfsLogFile: {
 			type: valita_exports.string().optional(),
@@ -856,26 +876,18 @@ var zeroOptions = {
 		checkpointThresholdMB: {
 			type: valita_exports.number().default(40),
 			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 (v3). Smaller thresholds`,
-				`may improve read performance, at the expense of creating more files to download`,
-				`when restoring the replica from the backup.`,
+				`The size of the WAL file at which litestream performs background, best-effort (PASSIVE)`,
+				`SQLite checkpoints to apply the writes in the WAL to the main database file. Checkpoints`,
+				`result in new WAL (v3) or LTS (v5) files that are then backed up asynchronously.`,
 				``,
-				`This setting is only relevant when replicating with litestream v3, and is ignored`,
-				`when replicating with litestream v5.`
+				`Note that these PASSIVE checkpoints are skipped if a write is in progress, so high writes rates`,
+				`can precipitate runaway wal growth. Also see {bold ZERO_LITESTREAM_FORCE_CHECKPOINT_THRESHOLD_MB}`
 			]
 		},
 		minCheckpointPageCount: {
 			type: valita_exports.number().optional(),
-			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).`,
-				``,
-				`This setting is only relevant when replicating with litestream v3, and is ignored`,
-				`when replicating with litestream v5.`
-			]
+			deprecated: [`Use {bold ZERO_CHECKPOINT_THRESHOLD_MB}`],
+			hidden: true
 		},
 		maxCheckpointPageCount: {
 			type: valita_exports.number().optional(),
@@ -888,8 +900,47 @@ var zeroOptions = {
 				`when replicating with litestream v5.`
 			]
 		},
+		forceCheckpointThresholdMB: {
+			type: valita_exports.number().default(256),
+			desc: [
+				`The size of the WAL file at which to pause writes and explicitly initiate a`,
+				`local litestream sync. This is a safeguard for the situation in which litestream's`,
+				`background checkpoints continually defer to incoming writes (i.e. high write load).`,
+				``,
+				`If the WAL size reaches the forced checkpoint threshold, writes pause for an`,
+				`an explicit litestream checkpoint, providing a flow-control mechanism to ensure timely`,
+				`backups and prevent runaway wal growth.`,
+				``,
+				`Note that these checkpoints {italic can} be skipped if litestream is performing a`,
+				`snapshot at the time (though snapshots are disabled by default). For such configurations,`,
+				`the {bold ZERO_LITESTREAM_MAX_WAL_SIZE_MB} provides an emergency break to prevent`,
+				`exceeding available disk space.`,
+				``,
+				`Set this to 0 to disable and instead rely on the litestream's default {bold truncate-page-n}`,
+				`emergency break.`,
+				``,
+				`This feature is only enabled with {bold ZERO_LITESTREAM_BACKUP_USING_V5}.`
+			]
+		},
+		maxWalSizeMB: {
+			type: valita_exports.number().default(10240),
+			desc: [
+				`A fail-safe that pauses writes once the un-checkpointed WAL reaches this size,`,
+				`resuming when litestream manages to checkpoint it. This bounds WAL growth (and`,
+				`ultimately disk usage) whenever litestream cannot checkpoint — e.g. while it holds`,
+				`the checkpoint lock for an in-progress snapshot — and serves as an alternative to`,
+				`litestream's {bold truncate-page-n} emergency checkpoint, which would otherwise block`,
+				`writes for a second "bounary" snapshot.`,
+				``,
+				`Size this generously relative to available disk; it should rarely be hit, as`,
+				`{bold ZERO_LITESTREAM_FORCE_CHECKPOINT_THRESHOLD_MB} keeps the WAL far smaller in`,
+				`normal operation. Set to {bold 0} to disable.`,
+				``,
+				`This feature is only enabled with {bold ZERO_LITESTREAM_BACKUP_USING_V5}.`
+			]
+		},
 		incrementalBackupIntervalMinutes: {
-			type: valita_exports.number().default(5),
+			type: valita_exports.number().default(15),
 			desc: [
 				`The interval between incremental v3 backups of the replica. Shorter intervals`,
 				`reduce the amount of change history that needs to be replayed when catching`,
@@ -901,6 +952,20 @@ var zeroOptions = {
 				`frequency, use {bold ZERO_LITESTREAM_INCREMENTAL_BACKUP_INTERVAL_SECONDS}.`
 			]
 		},
+		snapshotBackupIntervalHours: {
+			type: valita_exports.number().default(12),
+			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).`,
+				``,
+				`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_SNAPSHOT_BACKUP_INTERVAL_HOURS_V5}.`
+			]
+		},
 		incrementalBackupIntervalSeconds: {
 			type: valita_exports.number().default(15),
 			desc: [
@@ -916,18 +981,28 @@ var zeroOptions = {
 				`{bold ZERO_LITESTREAM_INCREMENTAL_BACKUP_INTERVAL_MINUTES}.`
 			]
 		},
-		snapshotBackupIntervalHours: {
-			type: valita_exports.number().default(4),
+		snapshotBackupIntervalHoursV5: {
+			type: valita_exports.number().default(720),
 			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).`,
+				`The interval between snapshot backups of the replica when`,
+				`{bold ZERO_LITESTREAM_BACKUP_USING_V5} is enabled.`,
+				``,
+				`By default, snapshots are effectively disabled (i.e. every 30 days)`,
+				`because v5 compaction fulfills the role that snapshots played in v3`,
+				`(i.e. because of litestream v5 compaction, restores will generally involve`,
+				`O(db-size) bytes.`,
 				``,
-				`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.`
+				`Snapshots are disabled by default because they hold a read-lock on`,
+				`the database and prevent wal checkpoints, introducing the risk of large wal`,
+				`files for large databases with a high write rate.`,
+				``,
+				`If configuring the zero-cache to actually perform v5 snapshots, the`,
+				`{bold ZERO_LITESTREAM_MAX_WAL_SIZE_MB} option can be used to pause replication`,
+				`if the wal reaches a certain size and cannot be checkpointed because of an`,
+				`in-progress snapshot.`,
+				``,
+				`This option only applies to litestream v5 backups. For v3 backups, use`,
+				`{bold ZERO_LITESTREAM_SNAPSHOT_BACKUP_INTERVAL_HOURS}.`
 			]
 		},
 		restoreParallelism: {