@rocicorp/zero 1.11.0-canary.0 → 1.11.0-canary.10

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

@@ -274,6 +274,57 @@ var zeroOptions = {
 				`(Note that this option has no effect for Postgres versions before 17.)`
 			]
 		},
+		pgReplicationSlotPerReplica: {
+			type: valita_exports.boolean().default(false),
+			desc: [`Allocates a dedicated replication slot per replication-manager, allowing multiple tasks`, `to run in tandem for high-availability.`],
+			hidden: true
+		},
+		pgHighAvailabilityReplication: {
+			type: valita_exports.boolean().optional(),
+			desc: [
+				`Runs replication-managers in high-availability mode, allowing multiple tasks to`,
+				`run concurrently, each using their own replication slot and maintaining a local`,
+				`change-log in sqlite.`,
+				``,
+				`In this configuration, the PG change-streamer db is not used or maintained. Consequently`,
+				`after running servers in high-availability mode, rolling back to a legacy singleton-mode task`,
+				`will trigger a resync in order to re-intialize the PG change-streamer db.`
+			],
+			hidden: true
+		},
+		pgResumeOrphanedSlotGracePeriodMs: {
+			type: valita_exports.number().default(2e4),
+			desc: [
+				`The grace period to wait before taking over an inactive replication slot, "resuming"`,
+				`the replica. With high availability replication, a new replica is generally "forked"`,
+				`from a running, active replica. Resumption happens as a last resort when no there are no`,
+				`active replicas, as it carries the risk of stealing the slot from a task that is attempting`,
+				`to reconnect to its slot.`,
+				``,
+				`In local development, where it is often expected for slots to be inactive, it is reasonable to set`,
+				`this to value to 0.`
+			],
+			hidden: true
+		},
+		pgReplicationEpoch: {
+			type: valita_exports.number().default(0),
+			desc: [
+				`Replication managers sharing the same epoch attempt to converge on a single`,
+				`generation (i.e. the result of an initial-sync); if multiple tasks are started`,
+				`simultaneously, they coordinate with each other such that one performs the`,
+				`initial-sync while the others wait for it.`,
+				``,
+				`Incrementing the epoch is the way to reliably force a resync; a replication manager`,
+				`on a new epoch will ignore any replicas on other epochs.`,
+				``,
+				`Note that changing the {bold ZERO_LITESTREAM_BACKUP_URL} generally achieves a resync`,
+				`as well, but with high available replication managers, changing only the backup url can`,
+				`lead to confusion if an old replication manager is performing initial sync, causing the`,
+				`new replication manager to wait for it. Incrementing the replication epoch is recommended`,
+				`instead.`
+			],
+			hidden: true
+		},
 		pgPartialIndexTriggers: {
 			type: valita_exports.boolean().default(false),
 			hidden: true
@@ -346,9 +397,12 @@ var zeroOptions = {
 			hidden: true
 		},
 		garbageCollectionInactivityThresholdHours: {
-			type: valita_exports.number().default(48),
+			type: valita_exports.number().default(168),
 			desc: [
 				`The duration after which an inactive CVR is eligible for garbage collection.`,
+				`Purging a CVR forces the next connection from that client group to`,
+				`re-sync from scratch, so this should comfortably exceed how long a`,
+				`typical user goes between sessions.`,
 				`Note that garbage collection is an incremental, periodic process which does not`,
 				`necessarily purge all eligible CVRs immediately.`
 			]
@@ -416,6 +470,30 @@ var zeroOptions = {
 			`the cost of reduced throughput.`
 		]
 	},
+	viewSyncerHydrationBudgetMs: {
+		type: valita_exports.number().assert((value) => Number.isSafeInteger(value) && value >= 0, "must be a nonnegative integer").default(0),
+		desc: [
+			`The soft time budget in milliseconds for hydrating inactive queries`,
+			`during a view-syncer hydration pass. Active and internal queries always`,
+			`finish, and time spent in custom-query transform round trips is not`,
+			`charged to the budget. An inactive query not reached before the budget`,
+			`is spent is evicted: its CVR record and the remaining TTL that would`,
+			`have kept it warm are both dropped. A value of 0 disables`,
+			`hydration-budget eviction.`
+		]
+	},
+	viewSyncerQueryHydrationTimeoutMs: {
+		type: valita_exports.number().assert((value) => Number.isSafeInteger(value) && value >= 0, "must be a nonnegative integer").default(0),
+		desc: [
+			`The maximum processing time in milliseconds that a view-syncer spends`,
+			`hydrating a single client query. Time spent yielding to other work is`,
+			`not counted. A query whose hydration exceeds this limit is aborted and`,
+			`removed from the client's view, and affected clients receive an error`,
+			`for the query. The query is then rejected without being run again for`,
+			`a cooldown period, after which a retry is allowed. Internal queries are`,
+			`never aborted. A value of 0 disables the limit.`
+		]
+	},
 	change: {
 		db: {
 			type: valita_exports.string().optional(),
@@ -554,6 +632,15 @@ var zeroOptions = {
 			desc: [`Controls the staged SQLite change-log rollout. Modes are cumulative:`, `{bold off}, {bold write}, {bold compare}, and {bold serve}.`],
 			hidden: true
 		},
+		pgChangeLogEnabled: {
+			type: valita_exports.boolean().default(true),
+			desc: [
+				`Whether the legacy Postgres change log remains authoritative for`,
+				`stream initialization, persistence, catchup, and upstream ACKs.`,
+				`Disabling it requires SQLite serve mode at 100 percent and a v5 backup.`
+			],
+			hidden: true
+		},
 		sqliteChangeLogReadPercent: {
 			type: valita_exports.number().default(0),
 			desc: [`The stable percentage of eligible catchup subscriptions served from SQLite.`],
@@ -627,7 +714,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`,
@@ -641,7 +728,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.`,
 				``,
@@ -884,26 +971,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(),
@@ -916,8 +995,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`,
@@ -929,6 +1047,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: [
@@ -944,18 +1076,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.`,
+				``,
+				`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.`,
 				``,
-				`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.`
+				`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: {