@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.21

package/out/zero-cache/src/services/change-source/pg/schema/shard.js

@@ -5,6 +5,7 @@ import { appSchema, check, upstreamSchema } from "../../../../types/shards.js";
 import { id } from "../../../../types/sql.js";
 import { getPublicationInfo, publishedSchema } from "./published.js";
 import { createEventFunctionStatements, createEventTriggerStatements } from "./ddl.js";
+import { replicaStageSchema } from "./replica-stage-enum.js";
 import { validate } from "./validation.js";
 import postgres from "postgres";
 import { PG_INSUFFICIENT_PRIVILEGE } from "@drdgvhbh/postgres-error-codes";
@@ -121,10 +122,6 @@ function shardSetup(shardConfig, metadataPublication) {
   ${getClientsTableDefinition(shard)}
   ${getMutationsTableDefinition(shard)}
 
-  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};
-  CREATE PUBLICATION ${id(metadataPublication)}
-    FOR TABLE ${app}."permissions", TABLE ${shard}."clients", ${shard}."mutations";
-
   CREATE TABLE ${shard}."${SHARD_CONFIG_TABLE}" (
     "publications"  TEXT[] NOT NULL,
     "ddlDetection"  BOOL NOT NULL,
@@ -147,14 +144,23 @@ function shardSetup(shardConfig, metadataPublication) {
     "id"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),
     "rank"               BIGSERIAL,
     "slot"               TEXT NOT NULL,
-    "version"            TEXT NOT NULL,
-    "generation"         TEXT,  -- to replace version, NULL-able in the interim
+    "version"            TEXT,  -- replaced by generation, slated for deletion
+    "epoch"              INT4 DEFAULT 0,
+    "generation"         TEXT NOT NULL,
+    "stage"              INT4 DEFAULT 0,
     "backupPath"         TEXT,  -- subpath within the litestream backup URL
     "backupV5"           BOOL DEFAULT false,
     "initialSchema"      JSON,  -- set after initial sync
     "initialSyncContext" JSON,
     "subscriberContext"  JSON
   );
+
+  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};
+  CREATE PUBLICATION ${id(metadataPublication)}
+    FOR TABLE ${app}."permissions", 
+        TABLE ${shard}."clients", 
+              ${shard}."mutations", 
+              ${shard}."replicas" (id);  -- advance the LSN/version with new replicas
   `;
 }
 function dropShard(appID, shardID) {
@@ -174,8 +180,9 @@ var replicaInfoSchema = valita_exports.object({
 	id: valita_exports.string(),
 	rank: valita_exports.bigint(),
 	slot: valita_exports.string(),
-	version: valita_exports.string(),
-	generation: valita_exports.string().nullable(),
+	epoch: valita_exports.number(),
+	generation: valita_exports.string(),
+	stage: replicaStageSchema,
 	backupPath: valita_exports.string().nullable(),
 	backupV5: valita_exports.boolean()
 });
@@ -184,24 +191,12 @@ var fullReplicaRowSchema = replicaInfoSchema.extend({
 	initialSyncContext: jsonObjectSchema.nullable(),
 	subscriberContext: jsonObjectSchema.nullable()
 });
-var replicaSchema = internalShardConfigSchema.extend(fullReplicaRowSchema.shape).map((replica) => {
-	const { version, generation, ...r } = replica;
-	return {
-		...r,
-		generation: generation ?? version
-	};
-});
+var replicaSchema = internalShardConfigSchema.extend(fullReplicaRowSchema.shape);
 var replicationSlotStateSchema = valita_exports.object({
 	active: valita_exports.boolean(),
-	confirmedFlushLsn: valita_exports.string().nullable()
-});
-var replicaStateSchema = replicaInfoSchema.extend(replicationSlotStateSchema.shape).map((replica) => {
-	const { version, generation, ...r } = replica;
-	return {
-		...r,
-		generation: generation ?? version
-	};
+	confirmedFlushLsn: valita_exports.string()
 });
+var replicaStateSchema = replicaInfoSchema.extend(replicationSlotStateSchema.shape);
 function triggerSetup(shard) {
 	const schema = id(upstreamSchema(shard));
 	return createEventTriggerStatements(shard) + `UPDATE ${schema}."shardConfig" SET "ddlDetection" = true;`;
@@ -212,22 +207,23 @@ function triggerSetup(shard) {
 * to ensure that the slot does not get dropped by concurrent cleanup
 * logic.
 *
-* Once initial sync is complete, {@link initReplica} should be called to
+* Once initial sync is complete, {@link initInitialSyncReplica} should be called to
 * make the replica usable for incremental sync.
 */
-async function createReplica(sql, shard, id, slot, replicaVersion, { backupPath, backupV5 }) {
+async function createReplica(sql, shard, id, slot, epoch, replicaVersion, { backupPath, backupV5 }, stage) {
 	const schema = upstreamSchema(shard);
 	const values = {
 		id,
 		slot,
-		version: replicaVersion,
+		epoch,
 		generation: replicaVersion,
 		backupPath,
-		backupV5
+		backupV5,
+		stage
 	};
 	await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;
 }
-async function initReplica(sql, shard, id, { tables, indexes }, initialSyncContext) {
+async function initInitialSyncReplica(sql, shard, id, { tables, indexes }, initialSyncContext) {
 	const schema = upstreamSchema(shard);
 	const values = {
 		initialSchema: {
@@ -238,6 +234,18 @@ async function initReplica(sql, shard, id, { tables, indexes }, initialSyncConte
 	};
 	await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;
 }
+async function initRestoreReplica(sql, shard, { sourceID, destID }) {
+	const schema = upstreamSchema(shard);
+	await sql`
+    UPDATE ${sql(schema)}.replicas dest 
+      SET "generation"         = source."generation",
+          "initialSchema"      = source."initialSchema",
+          "initialSyncContext" = source."initialSyncContext"
+      FROM ${sql(schema)}.replicas source
+      WHERE source.id = ${sourceID} AND dest.id = ${destID};
+  `;
+	return getReplicaState(sql, shard, destID);
+}
 /**
 * Gets at the given version and optional ID. If no ID is specified, gets
 * the latest (i.e. highest rank) replica with that version.
@@ -249,8 +257,9 @@ async function getReplicaAtVersion(lc, sql, shard, replicaVersion, id = null, co
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
       replicas."initialSchema",
@@ -259,13 +268,13 @@ async function getReplicaAtVersion(lc, sql, shard, replicaVersion, id = null, co
       "shardConfig"."publications",
       "shardConfig"."ddlDetection"
     FROM ${schema}.replicas JOIN ${schema}."shardConfig" ON true
-      WHERE version = ${replicaVersion} AND "initialSyncContext" IS NOT NULL
+      WHERE generation = ${replicaVersion} AND "initialSyncContext" IS NOT NULL
       AND id = COALESCE(${id}, id)
       ORDER BY rank DESC LIMIT 1;
   `;
 	if (result.length === 0) {
 		const allReplicas = await sql`
-      SELECT id, slot, version, "initialSyncContext", "subscriberContext" 
+      SELECT id, slot, generation, "initialSyncContext", "subscriberContext" 
         FROM ${schema}.replicas`;
 		lc.info?.(`Replica ${id}@${replicaVersion}` + (context ? `(context: ${stringify(context)}) ` : "") + `not found in: ${stringify(allReplicas)}`);
 		return null;
@@ -278,27 +287,84 @@ async function getActiveReplicas(lc, sql, shard) {
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
       slots."active",
       slots."confirmed_flush_lsn" as "confirmedFlushLsn"
     FROM ${sql(upstreamSchema(shard))}.replicas JOIN pg_replication_slots slots ON slot = slot_name
       WHERE "initialSyncContext" IS NOT NULL
+        -- Exclude replicas whose slot has been invalidated (e.g. for exceeding
+        -- max_slot_wal_keep_size). Such a replica can never be resumed, and
+        -- restoring it just results in an AutoResetSignal on every attempt.
+        AND slots.restart_lsn IS NOT NULL
+        AND slots.wal_status IS DISTINCT FROM 'lost'
       ORDER BY generation DESC, confirmed_flush_lsn DESC;
   `, valita_exports.array(replicaStateSchema), "passthrough");
 	lc.info?.(`current replicas`, { replicas });
 	return replicas;
 }
+/**
+* Returns candidates for restoring a new replica from. These include
+* all replicas in the newest `generation` of the given `epoch`, in order
+* of earliest available backup:
+* - An active InitialSync replica, which will be the only replica in
+*   its generation by definition. Orphaned/inactive initial syncs are skipped.
+* - Replicas in the Replicate stage, active first.
+* - Replicas in the Restore stage, potentially available for resumption
+*   as a last resort.
+*/
+async function getRestoreCandidates(lc, sql, shard, epoch) {
+	const schema = sql(upstreamSchema(shard));
+	const replicas = parse(await sql`
+    SELECT
+      replicas."id",
+      replicas."rank",
+      replicas."slot",
+      replicas."epoch",
+      replicas."generation",
+      replicas."stage",
+      replicas."backupPath",
+      replicas."backupV5",
+      slots."active",
+      slots."confirmed_flush_lsn" as "confirmedFlushLsn"
+    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name
+
+      -- coalesce on the newest generation in the epoch
+      WHERE generation = (
+        SELECT MAX(r.generation)
+          FROM ${schema}.replicas r
+          JOIN pg_replication_slots s ON r.slot = s.slot_name
+         WHERE r."epoch" = ${epoch} AND r."backupV5"
+           -- ignore orphaned InitialSyncs, which cannot be restored from
+           AND (s."active" OR r."stage" != ${0})
+           AND s.restart_lsn IS NOT NULL
+           AND s.wal_status IS DISTINCT FROM 'lost'
+      )
+           AND "epoch" = ${epoch} AND "backupV5"
+           AND (slots.active OR "stage" != ${0})
+           AND slots.restart_lsn IS NOT NULL
+           AND slots.wal_status IS DISTINCT FROM 'lost'
+
+      ORDER BY 
+        stage ASC,                 -- ordered by backup availalibility
+        active DESC,               -- prefer active slots (fork over resume)
+        confirmed_flush_lsn DESC;  -- prefer replicas further ahead
+  `, valita_exports.array(replicaStateSchema), "passthrough");
+	lc.info?.(`current replicas at epoch ${epoch}`, { replicas });
+	return replicas;
+}
 async function getReplicaState(sql, shard, id) {
 	const results = await sql`
     SELECT
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
       slots."active",
@@ -395,6 +461,6 @@ function replicaIdentitiesForTablesWithoutPrimaryKeys(pubs) {
 	} };
 }
 //#endregion
-export { SHARD_CONFIG_TABLE, createReplica, dropShard, ensureGlobalTables, getActiveReplicas, getInternalShardConfig, getMutationsTableDefinition, getReplicaAtVersion, getReplicaState, initReplica, internalPublicationPrefix, legacyReplicationSlot, metadataPublicationName, replicaIdentitiesForTablesWithoutPrimaryKeys, replicationSlotExpression, replicationSlotPrefix, setupTablesAndReplication, setupTriggers, validatePublications };
+export { SHARD_CONFIG_TABLE, createReplica, dropShard, ensureGlobalTables, getActiveReplicas, getInternalShardConfig, getMutationsTableDefinition, getReplicaAtVersion, getReplicaState, getRestoreCandidates, initInitialSyncReplica, initRestoreReplica, internalPublicationPrefix, legacyReplicationSlot, metadataPublicationName, replicaIdentitiesForTablesWithoutPrimaryKeys, replicationSlotExpression, replicationSlotPrefix, setupTablesAndReplication, setupTriggers, validatePublications };
 
 //# sourceMappingURL=shard.js.map

package/out/zero-cache/src/services/change-source/pg/schema/shard.js.map

@@ -1 +1 @@
-{"version":3,"file":"shard.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"sourcesContent":["import {PG_INSUFFICIENT_PRIVILEGE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {literal} from 'pg-format';\nimport postgres from 'postgres';\nimport {assert} from '../../../../../../shared/src/asserts.ts';\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../../shared/src/valita.ts';\nimport {Default} from '../../../../db/postgres-replica-identity-enum.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../../../types/pg.ts';\nimport type {AppID, ShardConfig, ShardID} from '../../../../types/shards.ts';\nimport {appSchema, check, upstreamSchema} from '../../../../types/shards.ts';\nimport {id} from '../../../../types/sql.ts';\nimport {\n  createEventFunctionStatements,\n  createEventTriggerStatements,\n} from './ddl.ts';\nimport {\n  getPublicationInfo,\n  publishedSchema,\n  type PublicationInfo,\n  type PublishedSchema,\n} from './published.ts';\nimport {validate} from './validation.ts';\n\n/**\n * PostgreSQL unquoted identifiers must start with a letter or underscore\n * and contain only letters, digits, and underscores.\n */\nconst VALID_PUBLICATION_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\n/**\n * Validates that a publication name is a valid PostgreSQL identifier.\n * This provides defense-in-depth against SQL injection when publication\n * names are used in replication commands.\n */\nexport function validatePublicationName(name: string): void {\n  if (!VALID_PUBLICATION_NAME.test(name)) {\n    throw new Error(\n      `Invalid publication name \"${name}\". Publication names must start with a letter or underscore ` +\n        `and contain only letters, digits, and underscores.`,\n    );\n  }\n  if (name.length > 63) {\n    throw new Error(\n      `Publication name \"${name}\" exceeds PostgreSQL's 63-character identifier limit.`,\n    );\n  }\n}\n\nexport function internalPublicationPrefix({appID}: AppID) {\n  return `_${appID}_`;\n}\n\nexport function legacyReplicationSlot({appID, shardNum}: ShardID) {\n  return `${appID}_${shardNum}`;\n}\n\nexport function replicationSlotPrefix(shard: ShardID) {\n  const {appID, shardNum} = check(shard);\n  return `${appID}_${shardNum}_`;\n}\n\n/**\n * An expression used to match replication slots in the shard\n * in a Postgres `LIKE` operator.\n */\nexport function replicationSlotExpression(shard: ShardID) {\n  // Underscores have a special meaning in LIKE values\n  // so they have to be escaped.\n  return `${replicationSlotPrefix(shard)}%`.replaceAll('_', '\\\\_');\n}\n\nfunction defaultPublicationName(appID: string, shardID: string | number) {\n  return `_${appID}_public_${shardID}`;\n}\n\nexport function metadataPublicationName(\n  appID: string,\n  shardID: string | number,\n) {\n  return `_${appID}_metadata_${shardID}`;\n}\n\n// The GLOBAL_SETUP must be idempotent as it can be run multiple times for different shards.\nfunction globalSetup(appID: AppID): string {\n  const app = id(appSchema(appID));\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${app};\n\n  CREATE TABLE IF NOT EXISTS ${app}.permissions (\n    \"permissions\" JSONB,\n    \"hash\"        TEXT,\n\n    -- Ensure that there is only a single row in the table.\n    -- Application code can be agnostic to this column, and\n    -- simply invoke UPDATE statements on the version columns.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  CREATE OR REPLACE FUNCTION ${app}.set_permissions_hash()\n  RETURNS TRIGGER AS $$\n  BEGIN\n      NEW.hash = md5(NEW.permissions::text);\n      RETURN NEW;\n  END;\n  $$ LANGUAGE plpgsql;\n\n  CREATE OR REPLACE TRIGGER on_set_permissions \n    BEFORE INSERT OR UPDATE ON ${app}.permissions\n    FOR EACH ROW\n    EXECUTE FUNCTION ${app}.set_permissions_hash();\n\n  INSERT INTO ${app}.permissions (permissions) VALUES (NULL) ON CONFLICT DO NOTHING;\n`;\n}\n\nexport async function ensureGlobalTables(db: PostgresDB, appID: AppID) {\n  await db.unsafe(globalSetup(appID));\n}\n\nexport function getClientsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"clients\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"lastMutationID\" BIGINT NOT NULL,\n    \"userID\"         TEXT,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\")\n  );`;\n}\n\n/**\n * Tracks the results of mutations.\n * 1. It is an error for the same mutation ID to be used twice.\n * 2. The result is JSONB to allow for arbitrary results.\n *\n * The tables must be cleaned up as the clients\n * receive the mutation responses and as clients are removed.\n */\nexport function getMutationsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"mutations\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"mutationID\"     BIGINT NOT NULL,\n    \"result\"         JSON NOT NULL,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\", \"mutationID\")\n  );`;\n}\n\nexport const SHARD_CONFIG_TABLE = 'shardConfig';\n\nexport function shardSetup(\n  shardConfig: ShardConfig,\n  metadataPublication: string,\n): string {\n  const app = id(appSchema(shardConfig));\n  const shard = id(upstreamSchema(shardConfig));\n\n  const pubs = shardConfig.publications.toSorted();\n  assert(\n    pubs.includes(metadataPublication),\n    () => `Publications must include ${metadataPublication}`,\n  );\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${shard};\n\n  ${getClientsTableDefinition(shard)}\n  ${getMutationsTableDefinition(shard)}\n\n  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n  CREATE PUBLICATION ${id(metadataPublication)}\n    FOR TABLE ${app}.\"permissions\", TABLE ${shard}.\"clients\", ${shard}.\"mutations\";\n\n  CREATE TABLE ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n    \"publications\"  TEXT[] NOT NULL,\n    \"ddlDetection\"  BOOL NOT NULL,\n\n    -- Ensure that there is only a single row in the table.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  INSERT INTO ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n      \"publications\",\n      \"ddlDetection\" \n    ) VALUES (\n      ARRAY[${literal(pubs)}], \n      false  -- set in SAVEPOINT with triggerSetup() statements\n    );\n\n  CREATE TABLE ${shard}.replicas (\n    -- The DEFAULT exists purely for backwards compatibility support.\n    -- New code always specifies a value based on Date.now().\n    \"id\"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),\n    \"rank\"               BIGSERIAL,\n    \"slot\"               TEXT NOT NULL,\n    \"version\"            TEXT NOT NULL,\n    \"generation\"         TEXT,  -- to replace version, NULL-able in the interim\n    \"backupPath\"         TEXT,  -- subpath within the litestream backup URL\n    \"backupV5\"           BOOL DEFAULT false,\n    \"initialSchema\"      JSON,  -- set after initial sync\n    \"initialSyncContext\" JSON,\n    \"subscriberContext\"  JSON\n  );\n  `;\n}\n\nexport function dropShard(appID: string, shardID: string | number): string {\n  const schema = `${appID}_${shardID}`;\n  const metadataPublication = metadataPublicationName(appID, shardID);\n  const defaultPublication = defaultPublicationName(appID, shardID);\n\n  // DROP SCHEMA ... CASCADE does not drop dependent PUBLICATIONS,\n  // so PUBLICATIONs must be dropped explicitly.\n  return /*sql*/ `\n    DROP PUBLICATION IF EXISTS ${id(defaultPublication)};\n    DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n    DROP SCHEMA IF EXISTS ${id(schema)} CASCADE;\n  `;\n}\n\nconst internalShardConfigSchema = v.object({\n  publications: v.array(v.string()),\n  ddlDetection: v.boolean(),\n});\n\nexport type InternalShardConfig = v.Infer<typeof internalShardConfigSchema>;\n\nconst replicaInfoSchema = v.object({\n  id: v.string(),\n  rank: v.bigint(),\n  slot: v.string(),\n  version: v.string(),\n  generation: v.string().nullable(),\n  backupPath: v.string().nullable(),\n  backupV5: v.boolean(),\n});\n\nconst fullReplicaRowSchema = replicaInfoSchema.extend({\n  initialSchema: publishedSchema,\n  initialSyncContext: jsonObjectSchema.nullable(),\n  subscriberContext: jsonObjectSchema.nullable(),\n});\n\nconst replicaSchema = internalShardConfigSchema\n  .extend(fullReplicaRowSchema.shape)\n  .map(replica => {\n    const {version, generation, ...r} = replica;\n    return {...r, generation: generation ?? version};\n  });\n\nexport type Replica = v.Infer<typeof replicaSchema>;\n\nconst replicationSlotStateSchema = v.object({\n  active: v.boolean(),\n  confirmedFlushLsn: v.string().nullable(),\n});\n\nconst replicaStateSchema = replicaInfoSchema\n  .extend(replicationSlotStateSchema.shape)\n  .map(replica => {\n    const {version, generation, ...r} = replica;\n    return {...r, generation: generation ?? version};\n  });\n\nexport type ReplicaState = v.Infer<typeof replicaStateSchema>;\n\n// triggerSetup is run separately in a sub-transaction (i.e. SAVEPOINT) so\n// that a failure (e.g. due to lack of superuser permissions) can be handled\n// by continuing in a degraded mode (ddlDetection = false).\nfunction triggerSetup(shard: ShardConfig): string {\n  const schema = id(upstreamSchema(shard));\n  return (\n    createEventTriggerStatements(shard) +\n    /*sql*/ `UPDATE ${schema}.\"shardConfig\" SET \"ddlDetection\" = true;`\n  );\n}\n\nexport type BackupOptions = {\n  backupPath: string | null;\n  backupV5: boolean;\n};\n\n/**\n * Creates a new replica to mark it as the owner of a specified `slot`.\n * This should be done with an advisory lock for replica/slot management\n * to ensure that the slot does not get dropped by concurrent cleanup\n * logic.\n *\n * Once initial sync is complete, {@link initReplica} should be called to\n * make the replica usable for incremental sync.\n */\nexport async function createReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  slot: string,\n  replicaVersion: string,\n  {backupPath, backupV5}: BackupOptions,\n) {\n  const schema = upstreamSchema(shard);\n  const values: Partial<v.Infer<typeof fullReplicaRowSchema>> = {\n    id,\n    slot,\n    version: replicaVersion,\n    generation: replicaVersion,\n    backupPath,\n    backupV5,\n  };\n  await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;\n}\n\n// Called in initial-sync to store the exact schema that was initially synced.\nexport async function initReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  {tables, indexes}: PublishedSchema,\n  initialSyncContext: JSONObject,\n) {\n  const schema = upstreamSchema(shard);\n  const synced: PublishedSchema = {tables, indexes};\n  const values = {initialSchema: synced, initialSyncContext};\n  await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;\n}\n\n/**\n * Gets at the given version and optional ID. If no ID is specified, gets\n * the latest (i.e. highest rank) replica with that version.\n */\nexport async function getReplicaAtVersion(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n  replicaVersion: string,\n  id: string | null = null,\n  context?: JSONObject,\n): Promise<Replica | null> {\n  const schema = sql(upstreamSchema(shard));\n  const result = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"initialSchema\",\n      replicas.\"initialSyncContext\",\n      replicas.\"subscriberContext\",\n      \"shardConfig\".\"publications\",\n      \"shardConfig\".\"ddlDetection\"\n    FROM ${schema}.replicas JOIN ${schema}.\"shardConfig\" ON true\n      WHERE version = ${replicaVersion} AND \"initialSyncContext\" IS NOT NULL\n      AND id = COALESCE(${id}, id)\n      ORDER BY rank DESC LIMIT 1;\n  `;\n  if (result.length === 0) {\n    // log out all the replicas and the joined shardConfig\n    const allReplicas = await sql`\n      SELECT id, slot, version, \"initialSyncContext\", \"subscriberContext\" \n        FROM ${schema}.replicas`;\n    lc.info?.(\n      `Replica ${id}@${replicaVersion}` +\n        (context ? `(context: ${stringify(context)}) ` : '') +\n        `not found in: ${stringify(allReplicas)}`,\n    );\n    return null;\n  }\n  return v.parse(result[0], replicaSchema, 'passthrough');\n}\n\nexport async function getActiveReplicas(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"initialSyncContext\" IS NOT NULL\n      ORDER BY generation DESC, confirmed_flush_lsn DESC;\n  `;\n  const replicas = v.parse(results, v.array(replicaStateSchema), 'passthrough');\n  lc.info?.(`current replicas`, {replicas});\n  return replicas;\n}\n\nexport async function getReplicaState(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n): Promise<ReplicaState | null> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"id\" = ${id};\n  `;\n  return results.length\n    ? v.parse(results[0], replicaStateSchema, 'passthrough')\n    : null;\n}\n\nexport async function getInternalShardConfig(\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<InternalShardConfig> {\n  const result = await sql`\n    SELECT \"publications\", \"ddlDetection\"\n      FROM ${sql(upstreamSchema(shard))}.\"shardConfig\";\n  `;\n  assert(\n    result.length === 1,\n    () => `Expected exactly one shardConfig row, got ${result.length}`,\n  );\n  return v.parse(result[0], internalShardConfigSchema, 'passthrough');\n}\n\n/**\n * Sets up and returns all publications (including internal ones) for\n * the given shard.\n */\nexport async function setupTablesAndReplication(\n  lc: LogContext,\n  sql: PostgresTransaction,\n  requested: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const {publications} = requested;\n  // Validate requested publications.\n  for (const pub of publications) {\n    validatePublicationName(pub);\n    if (pub.startsWith('_')) {\n      throw new Error(\n        `Publication names starting with \"_\" are reserved for internal use.\\n` +\n          `Please use a different name for publication \"${pub}\".`,\n      );\n    }\n  }\n  const allPublications: string[] = [];\n\n  // Setup application publications.\n  if (publications.length) {\n    const results = await sql<{pubname: string}[]>`\n    SELECT pubname from pg_publication WHERE pubname IN ${sql(\n      publications,\n    )}`.values();\n\n    if (results.length !== publications.length) {\n      throw new Error(\n        `Unknown or invalid publications. Specified: [${publications}]. Found: [${results.flat()}]`,\n      );\n    }\n    allPublications.push(...publications);\n  } else {\n    const defaultPublication = defaultPublicationName(\n      requested.appID,\n      requested.shardNum,\n    );\n    await sql`\n      DROP PUBLICATION IF EXISTS ${sql(defaultPublication)}`;\n    await sql`\n      CREATE PUBLICATION ${sql(defaultPublication)} \n        FOR TABLES IN SCHEMA public\n        WITH (publish_via_partition_root = true)`;\n    allPublications.push(defaultPublication);\n  }\n\n  const metadataPublication = metadataPublicationName(\n    requested.appID,\n    requested.shardNum,\n  );\n  allPublications.push(metadataPublication);\n\n  const shard = {...requested, publications: allPublications};\n\n  // Setup the global tables and shard tables / publications.\n  await sql.unsafe(globalSetup(shard) + shardSetup(shard, metadataPublication));\n\n  const pubs = await getPublicationInfo(sql, allPublications);\n  await replicaIdentitiesForTablesWithoutPrimaryKeys(pubs)?.apply(lc, sql);\n\n  await setupTriggers(lc, sql, shard, includePartialIndexes);\n}\n\nexport async function setupTriggers(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  shard: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const schema = upstreamSchema(shard);\n  const [{ddlDetection}] = await tx<InternalShardConfig[]> /*sql*/ `\n    SELECT \"ddlDetection\" FROM ${tx(schema)}.\"shardConfig\"`;\n\n  // The functions invoked by event triggers are installed even if\n  // event triggers are not supported/allowed by the db provider.\n  // This allows users to manually invoke the update_schemas() function\n  // as a workaround.\n  await tx.unsafe(createEventFunctionStatements(shard, includePartialIndexes));\n  try {\n    await tx.savepoint(sub => sub.unsafe(triggerSetup(shard)));\n  } catch (e) {\n    if (ddlDetection) {\n      // If ddlDetection has already been enabled, subsequent failures to\n      // upgrade the trigger should be propagated rather than swallowed.\n      throw e;\n    }\n    if (\n      !(\n        e instanceof postgres.PostgresError &&\n        e.code === PG_INSUFFICIENT_PRIVILEGE\n      )\n    ) {\n      throw e;\n    }\n    // If triggerSetup() fails, replication continues in ddlDetection=false mode.\n    lc.warn?.(\n      `Unable to create event triggers for schema change detection:\\n\\n` +\n        `\"${e.hint ?? e.message}\"\\n\\n` +\n        `Proceeding in degraded mode: schema changes will halt replication,\\n` +\n        `requiring the replica to be reset (manually or with --auto-reset).`,\n    );\n  }\n}\n\nexport function validatePublications(\n  lc: LogContext,\n  published: PublicationInfo,\n) {\n  // Verify that all publications export the proper events.\n  published.publications.forEach(pub => {\n    if (\n      !pub.pubinsert ||\n      !pub.pubupdate ||\n      !pub.pubdelete ||\n      !pub.pubtruncate\n    ) {\n      // TODO: Make APIError?\n      throw new Error(\n        `PUBLICATION ${pub.pubname} must publish insert, update, delete, and truncate`,\n      );\n    }\n  });\n\n  published.tables.forEach(table => validate(lc, table));\n}\n\ntype ReplicaIdentities = {\n  apply(lc: LogContext, db: PostgresDB): Promise<void>;\n};\n\nexport function replicaIdentitiesForTablesWithoutPrimaryKeys(\n  pubs: PublishedSchema,\n): ReplicaIdentities | undefined {\n  const replicaIdentities: {\n    schema: string;\n    tableName: string;\n    indexName: string;\n  }[] = [];\n  for (const table of pubs.tables) {\n    if (!table.primaryKey?.length && table.replicaIdentity === Default) {\n      // Look for an index that can serve as the REPLICA IDENTITY USING INDEX. It must be:\n      // - UNIQUE\n      // - NOT NULL columns\n      // - not deferrable (i.e. isImmediate)\n      // - not partial\n      //\n      // https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY\n      const {schema, name: tableName} = table;\n      for (const {columns, name: indexName} of pubs.indexes.filter(\n        idx =>\n          idx.schema === schema &&\n          idx.tableName === tableName &&\n          idx.unique &&\n          idx.isImmediate &&\n          idx.predicate === undefined,\n      )) {\n        if (Object.keys(columns).some(col => !table.columns[col].notNull)) {\n          continue; // Only indexes with all NOT NULL columns are suitable.\n        }\n        replicaIdentities.push({schema, tableName, indexName});\n        break;\n      }\n    }\n  }\n\n  if (replicaIdentities.length === 0) {\n    return undefined;\n  }\n  return {\n    apply: async (lc: LogContext, sql: PostgresDB) => {\n      for (const {schema, tableName, indexName} of replicaIdentities) {\n        lc.info?.(\n          `setting \"${indexName}\" as the REPLICA IDENTITY for \"${tableName}\"`,\n        );\n        await sql`\n        ALTER TABLE ${sql(schema)}.${sql(tableName)} \n          REPLICA IDENTITY USING INDEX ${sql(indexName)}`;\n      }\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"shard.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"sourcesContent":["import {PG_INSUFFICIENT_PRIVILEGE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {literal} from 'pg-format';\nimport postgres from 'postgres';\nimport {assert} from '../../../../../../shared/src/asserts.ts';\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../../shared/src/valita.ts';\nimport {Default} from '../../../../db/postgres-replica-identity-enum.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../../../types/pg.ts';\nimport type {AppID, ShardConfig, ShardID} from '../../../../types/shards.ts';\nimport {appSchema, check, upstreamSchema} from '../../../../types/shards.ts';\nimport {id} from '../../../../types/sql.ts';\nimport {\n  createEventFunctionStatements,\n  createEventTriggerStatements,\n} from './ddl.ts';\nimport {\n  getPublicationInfo,\n  publishedSchema,\n  type PublicationInfo,\n  type PublishedSchema,\n} from './published.ts';\nimport {\n  InitialSync,\n  replicaStageSchema,\n  type ReplicaStage,\n} from './replica-stage-enum.ts';\nimport {validate} from './validation.ts';\n\n/**\n * PostgreSQL unquoted identifiers must start with a letter or underscore\n * and contain only letters, digits, and underscores.\n */\nconst VALID_PUBLICATION_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\n/**\n * Validates that a publication name is a valid PostgreSQL identifier.\n * This provides defense-in-depth against SQL injection when publication\n * names are used in replication commands.\n */\nexport function validatePublicationName(name: string): void {\n  if (!VALID_PUBLICATION_NAME.test(name)) {\n    throw new Error(\n      `Invalid publication name \"${name}\". Publication names must start with a letter or underscore ` +\n        `and contain only letters, digits, and underscores.`,\n    );\n  }\n  if (name.length > 63) {\n    throw new Error(\n      `Publication name \"${name}\" exceeds PostgreSQL's 63-character identifier limit.`,\n    );\n  }\n}\n\nexport function internalPublicationPrefix({appID}: AppID) {\n  return `_${appID}_`;\n}\n\nexport function legacyReplicationSlot({appID, shardNum}: ShardID) {\n  return `${appID}_${shardNum}`;\n}\n\nexport function replicationSlotPrefix(shard: ShardID) {\n  const {appID, shardNum} = check(shard);\n  return `${appID}_${shardNum}_`;\n}\n\n/**\n * An expression used to match replication slots in the shard\n * in a Postgres `LIKE` operator.\n */\nexport function replicationSlotExpression(shard: ShardID) {\n  // Underscores have a special meaning in LIKE values\n  // so they have to be escaped.\n  return `${replicationSlotPrefix(shard)}%`.replaceAll('_', '\\\\_');\n}\n\nfunction defaultPublicationName(appID: string, shardID: string | number) {\n  return `_${appID}_public_${shardID}`;\n}\n\nexport function metadataPublicationName(\n  appID: string,\n  shardID: string | number,\n) {\n  return `_${appID}_metadata_${shardID}`;\n}\n\n// The GLOBAL_SETUP must be idempotent as it can be run multiple times for different shards.\nfunction globalSetup(appID: AppID): string {\n  const app = id(appSchema(appID));\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${app};\n\n  CREATE TABLE IF NOT EXISTS ${app}.permissions (\n    \"permissions\" JSONB,\n    \"hash\"        TEXT,\n\n    -- Ensure that there is only a single row in the table.\n    -- Application code can be agnostic to this column, and\n    -- simply invoke UPDATE statements on the version columns.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  CREATE OR REPLACE FUNCTION ${app}.set_permissions_hash()\n  RETURNS TRIGGER AS $$\n  BEGIN\n      NEW.hash = md5(NEW.permissions::text);\n      RETURN NEW;\n  END;\n  $$ LANGUAGE plpgsql;\n\n  CREATE OR REPLACE TRIGGER on_set_permissions \n    BEFORE INSERT OR UPDATE ON ${app}.permissions\n    FOR EACH ROW\n    EXECUTE FUNCTION ${app}.set_permissions_hash();\n\n  INSERT INTO ${app}.permissions (permissions) VALUES (NULL) ON CONFLICT DO NOTHING;\n`;\n}\n\nexport async function ensureGlobalTables(db: PostgresDB, appID: AppID) {\n  await db.unsafe(globalSetup(appID));\n}\n\nexport function getClientsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"clients\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"lastMutationID\" BIGINT NOT NULL,\n    \"userID\"         TEXT,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\")\n  );`;\n}\n\n/**\n * Tracks the results of mutations.\n * 1. It is an error for the same mutation ID to be used twice.\n * 2. The result is JSONB to allow for arbitrary results.\n *\n * The tables must be cleaned up as the clients\n * receive the mutation responses and as clients are removed.\n */\nexport function getMutationsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"mutations\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"mutationID\"     BIGINT NOT NULL,\n    \"result\"         JSON NOT NULL,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\", \"mutationID\")\n  );`;\n}\n\nexport const SHARD_CONFIG_TABLE = 'shardConfig';\n\nexport function shardSetup(\n  shardConfig: ShardConfig,\n  metadataPublication: string,\n): string {\n  const app = id(appSchema(shardConfig));\n  const shard = id(upstreamSchema(shardConfig));\n\n  const pubs = shardConfig.publications.toSorted();\n  assert(\n    pubs.includes(metadataPublication),\n    () => `Publications must include ${metadataPublication}`,\n  );\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${shard};\n\n  ${getClientsTableDefinition(shard)}\n  ${getMutationsTableDefinition(shard)}\n\n  CREATE TABLE ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n    \"publications\"  TEXT[] NOT NULL,\n    \"ddlDetection\"  BOOL NOT NULL,\n\n    -- Ensure that there is only a single row in the table.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  INSERT INTO ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n      \"publications\",\n      \"ddlDetection\" \n    ) VALUES (\n      ARRAY[${literal(pubs)}], \n      false  -- set in SAVEPOINT with triggerSetup() statements\n    );\n\n  CREATE TABLE ${shard}.replicas (\n    -- The DEFAULT exists purely for backwards compatibility support.\n    -- New code always specifies a value based on Date.now().\n    \"id\"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),\n    \"rank\"               BIGSERIAL,\n    \"slot\"               TEXT NOT NULL,\n    \"version\"            TEXT,  -- replaced by generation, slated for deletion\n    \"epoch\"              INT4 DEFAULT 0,\n    \"generation\"         TEXT NOT NULL,\n    \"stage\"              INT4 DEFAULT ${InitialSync},\n    \"backupPath\"         TEXT,  -- subpath within the litestream backup URL\n    \"backupV5\"           BOOL DEFAULT false,\n    \"initialSchema\"      JSON,  -- set after initial sync\n    \"initialSyncContext\" JSON,\n    \"subscriberContext\"  JSON\n  );\n\n  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n  CREATE PUBLICATION ${id(metadataPublication)}\n    FOR TABLE ${app}.\"permissions\", \n        TABLE ${shard}.\"clients\", \n              ${shard}.\"mutations\", \n              ${shard}.\"replicas\" (id);  -- advance the LSN/version with new replicas\n  `;\n}\n\nexport function dropShard(appID: string, shardID: string | number): string {\n  const schema = `${appID}_${shardID}`;\n  const metadataPublication = metadataPublicationName(appID, shardID);\n  const defaultPublication = defaultPublicationName(appID, shardID);\n\n  // DROP SCHEMA ... CASCADE does not drop dependent PUBLICATIONS,\n  // so PUBLICATIONs must be dropped explicitly.\n  return /*sql*/ `\n    DROP PUBLICATION IF EXISTS ${id(defaultPublication)};\n    DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n    DROP SCHEMA IF EXISTS ${id(schema)} CASCADE;\n  `;\n}\n\nconst internalShardConfigSchema = v.object({\n  publications: v.array(v.string()),\n  ddlDetection: v.boolean(),\n});\n\nexport type InternalShardConfig = v.Infer<typeof internalShardConfigSchema>;\n\nconst replicaInfoSchema = v.object({\n  id: v.string(),\n  rank: v.bigint(),\n  slot: v.string(),\n  epoch: v.number(),\n  generation: v.string(),\n  stage: replicaStageSchema,\n  backupPath: v.string().nullable(),\n  backupV5: v.boolean(),\n});\n\nconst fullReplicaRowSchema = replicaInfoSchema.extend({\n  initialSchema: publishedSchema,\n  initialSyncContext: jsonObjectSchema.nullable(),\n  subscriberContext: jsonObjectSchema.nullable(),\n});\n\nconst replicaSchema = internalShardConfigSchema.extend(\n  fullReplicaRowSchema.shape,\n);\n\nexport type Replica = v.Infer<typeof replicaSchema>;\n\nconst replicationSlotStateSchema = v.object({\n  active: v.boolean(),\n  confirmedFlushLsn: v.string(),\n});\n\nconst replicaStateSchema = replicaInfoSchema.extend(\n  replicationSlotStateSchema.shape,\n);\n\nexport type ReplicaState = v.Infer<typeof replicaStateSchema>;\n\n// triggerSetup is run separately in a sub-transaction (i.e. SAVEPOINT) so\n// that a failure (e.g. due to lack of superuser permissions) can be handled\n// by continuing in a degraded mode (ddlDetection = false).\nfunction triggerSetup(shard: ShardConfig): string {\n  const schema = id(upstreamSchema(shard));\n  return (\n    createEventTriggerStatements(shard) +\n    /*sql*/ `UPDATE ${schema}.\"shardConfig\" SET \"ddlDetection\" = true;`\n  );\n}\n\nexport type BackupOptions = {\n  backupPath: string | null;\n  backupV5: boolean;\n};\n\n/**\n * Creates a new replica to mark it as the owner of a specified `slot`.\n * This should be done with an advisory lock for replica/slot management\n * to ensure that the slot does not get dropped by concurrent cleanup\n * logic.\n *\n * Once initial sync is complete, {@link initInitialSyncReplica} should be called to\n * make the replica usable for incremental sync.\n */\nexport async function createReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  slot: string,\n  epoch: number,\n  replicaVersion: string,\n  {backupPath, backupV5}: BackupOptions,\n  stage: ReplicaStage,\n) {\n  const schema = upstreamSchema(shard);\n  const values: Partial<v.Infer<typeof fullReplicaRowSchema>> = {\n    id,\n    slot,\n    epoch,\n    generation: replicaVersion,\n    backupPath,\n    backupV5,\n    stage,\n  };\n  await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;\n}\n\n// Called in initial-sync to store the exact schema that was initially synced.\nexport async function initInitialSyncReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  {tables, indexes}: PublishedSchema,\n  initialSyncContext: JSONObject,\n) {\n  const schema = upstreamSchema(shard);\n  const synced: PublishedSchema = {tables, indexes};\n  const values = {initialSchema: synced, initialSyncContext};\n  await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;\n}\n\n// Called to initialize a Restore replica (`destID`) with the generation\n// and initial sync context of the `sourceID` replica.\nexport async function initRestoreReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  {sourceID, destID}: {sourceID: string; destID: string},\n): Promise<ReplicaState | null> {\n  const schema = upstreamSchema(shard);\n  await sql`\n    UPDATE ${sql(schema)}.replicas dest \n      SET \"generation\"         = source.\"generation\",\n          \"initialSchema\"      = source.\"initialSchema\",\n          \"initialSyncContext\" = source.\"initialSyncContext\"\n      FROM ${sql(schema)}.replicas source\n      WHERE source.id = ${sourceID} AND dest.id = ${destID};\n  `;\n  return getReplicaState(sql, shard, destID);\n}\n\n/**\n * Gets at the given version and optional ID. If no ID is specified, gets\n * the latest (i.e. highest rank) replica with that version.\n */\nexport async function getReplicaAtVersion(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n  replicaVersion: string,\n  id: string | null = null,\n  context?: JSONObject,\n): Promise<Replica | null> {\n  const schema = sql(upstreamSchema(shard));\n  const result = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"initialSchema\",\n      replicas.\"initialSyncContext\",\n      replicas.\"subscriberContext\",\n      \"shardConfig\".\"publications\",\n      \"shardConfig\".\"ddlDetection\"\n    FROM ${schema}.replicas JOIN ${schema}.\"shardConfig\" ON true\n      WHERE generation = ${replicaVersion} AND \"initialSyncContext\" IS NOT NULL\n      AND id = COALESCE(${id}, id)\n      ORDER BY rank DESC LIMIT 1;\n  `;\n  if (result.length === 0) {\n    // log out all the replicas and the joined shardConfig\n    const allReplicas = await sql`\n      SELECT id, slot, generation, \"initialSyncContext\", \"subscriberContext\" \n        FROM ${schema}.replicas`;\n    lc.info?.(\n      `Replica ${id}@${replicaVersion}` +\n        (context ? `(context: ${stringify(context)}) ` : '') +\n        `not found in: ${stringify(allReplicas)}`,\n    );\n    return null;\n  }\n  return v.parse(result[0], replicaSchema, 'passthrough');\n}\n\nexport async function getActiveReplicas(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"initialSyncContext\" IS NOT NULL\n        -- Exclude replicas whose slot has been invalidated (e.g. for exceeding\n        -- max_slot_wal_keep_size). Such a replica can never be resumed, and\n        -- restoring it just results in an AutoResetSignal on every attempt.\n        AND slots.restart_lsn IS NOT NULL\n        AND slots.wal_status IS DISTINCT FROM 'lost'\n      ORDER BY generation DESC, confirmed_flush_lsn DESC;\n  `;\n  const replicas = v.parse(results, v.array(replicaStateSchema), 'passthrough');\n  lc.info?.(`current replicas`, {replicas});\n  return replicas;\n}\n\n/**\n * Returns candidates for restoring a new replica from. These include\n * all replicas in the newest `generation` of the given `epoch`, in order\n * of earliest available backup:\n * - An active InitialSync replica, which will be the only replica in\n *   its generation by definition. Orphaned/inactive initial syncs are skipped.\n * - Replicas in the Replicate stage, active first.\n * - Replicas in the Restore stage, potentially available for resumption\n *   as a last resort.\n */\nexport async function getRestoreCandidates(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n  epoch: number,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n\n      -- coalesce on the newest generation in the epoch\n      WHERE generation = (\n        SELECT MAX(r.generation)\n          FROM ${schema}.replicas r\n          JOIN pg_replication_slots s ON r.slot = s.slot_name\n         WHERE r.\"epoch\" = ${epoch} AND r.\"backupV5\"\n           -- ignore orphaned InitialSyncs, which cannot be restored from\n           AND (s.\"active\" OR r.\"stage\" != ${InitialSync})\n           AND s.restart_lsn IS NOT NULL\n           AND s.wal_status IS DISTINCT FROM 'lost'\n      )\n           AND \"epoch\" = ${epoch} AND \"backupV5\"\n           AND (slots.active OR \"stage\" != ${InitialSync})\n           AND slots.restart_lsn IS NOT NULL\n           AND slots.wal_status IS DISTINCT FROM 'lost'\n\n      ORDER BY \n        stage ASC,                 -- ordered by backup availalibility\n        active DESC,               -- prefer active slots (fork over resume)\n        confirmed_flush_lsn DESC;  -- prefer replicas further ahead\n  `;\n  const replicas = v.parse(results, v.array(replicaStateSchema), 'passthrough');\n  lc.info?.(`current replicas at epoch ${epoch}`, {replicas});\n  return replicas;\n}\n\nexport async function getReplicaState(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n): Promise<ReplicaState | null> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"id\" = ${id};\n  `;\n  return results.length\n    ? v.parse(results[0], replicaStateSchema, 'passthrough')\n    : null;\n}\n\nexport async function getInternalShardConfig(\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<InternalShardConfig> {\n  const result = await sql`\n    SELECT \"publications\", \"ddlDetection\"\n      FROM ${sql(upstreamSchema(shard))}.\"shardConfig\";\n  `;\n  assert(\n    result.length === 1,\n    () => `Expected exactly one shardConfig row, got ${result.length}`,\n  );\n  return v.parse(result[0], internalShardConfigSchema, 'passthrough');\n}\n\n/**\n * Sets up and returns all publications (including internal ones) for\n * the given shard.\n */\nexport async function setupTablesAndReplication(\n  lc: LogContext,\n  sql: PostgresTransaction,\n  requested: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const {publications} = requested;\n  // Validate requested publications.\n  for (const pub of publications) {\n    validatePublicationName(pub);\n    if (pub.startsWith('_')) {\n      throw new Error(\n        `Publication names starting with \"_\" are reserved for internal use.\\n` +\n          `Please use a different name for publication \"${pub}\".`,\n      );\n    }\n  }\n  const allPublications: string[] = [];\n\n  // Setup application publications.\n  if (publications.length) {\n    const results = await sql<{pubname: string}[]>`\n    SELECT pubname from pg_publication WHERE pubname IN ${sql(\n      publications,\n    )}`.values();\n\n    if (results.length !== publications.length) {\n      throw new Error(\n        `Unknown or invalid publications. Specified: [${publications}]. Found: [${results.flat()}]`,\n      );\n    }\n    allPublications.push(...publications);\n  } else {\n    const defaultPublication = defaultPublicationName(\n      requested.appID,\n      requested.shardNum,\n    );\n    await sql`\n      DROP PUBLICATION IF EXISTS ${sql(defaultPublication)}`;\n    await sql`\n      CREATE PUBLICATION ${sql(defaultPublication)} \n        FOR TABLES IN SCHEMA public\n        WITH (publish_via_partition_root = true)`;\n    allPublications.push(defaultPublication);\n  }\n\n  const metadataPublication = metadataPublicationName(\n    requested.appID,\n    requested.shardNum,\n  );\n  allPublications.push(metadataPublication);\n\n  const shard = {...requested, publications: allPublications};\n\n  // Setup the global tables and shard tables / publications.\n  await sql.unsafe(globalSetup(shard) + shardSetup(shard, metadataPublication));\n\n  const pubs = await getPublicationInfo(sql, allPublications);\n  await replicaIdentitiesForTablesWithoutPrimaryKeys(pubs)?.apply(lc, sql);\n\n  await setupTriggers(lc, sql, shard, includePartialIndexes);\n}\n\nexport async function setupTriggers(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  shard: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const schema = upstreamSchema(shard);\n  const [{ddlDetection}] = await tx<InternalShardConfig[]> /*sql*/ `\n    SELECT \"ddlDetection\" FROM ${tx(schema)}.\"shardConfig\"`;\n\n  // The functions invoked by event triggers are installed even if\n  // event triggers are not supported/allowed by the db provider.\n  // This allows users to manually invoke the update_schemas() function\n  // as a workaround.\n  await tx.unsafe(createEventFunctionStatements(shard, includePartialIndexes));\n  try {\n    await tx.savepoint(sub => sub.unsafe(triggerSetup(shard)));\n  } catch (e) {\n    if (ddlDetection) {\n      // If ddlDetection has already been enabled, subsequent failures to\n      // upgrade the trigger should be propagated rather than swallowed.\n      throw e;\n    }\n    if (\n      !(\n        e instanceof postgres.PostgresError &&\n        e.code === PG_INSUFFICIENT_PRIVILEGE\n      )\n    ) {\n      throw e;\n    }\n    // If triggerSetup() fails, replication continues in ddlDetection=false mode.\n    lc.warn?.(\n      `Unable to create event triggers for schema change detection:\\n\\n` +\n        `\"${e.hint ?? e.message}\"\\n\\n` +\n        `Proceeding in degraded mode: schema changes will halt replication,\\n` +\n        `requiring the replica to be reset (manually or with --auto-reset).`,\n    );\n  }\n}\n\nexport function validatePublications(\n  lc: LogContext,\n  published: PublicationInfo,\n) {\n  // Verify that all publications export the proper events.\n  published.publications.forEach(pub => {\n    if (\n      !pub.pubinsert ||\n      !pub.pubupdate ||\n      !pub.pubdelete ||\n      !pub.pubtruncate\n    ) {\n      // TODO: Make APIError?\n      throw new Error(\n        `PUBLICATION ${pub.pubname} must publish insert, update, delete, and truncate`,\n      );\n    }\n  });\n\n  published.tables.forEach(table => validate(lc, table));\n}\n\ntype ReplicaIdentities = {\n  apply(lc: LogContext, db: PostgresDB): Promise<void>;\n};\n\nexport function replicaIdentitiesForTablesWithoutPrimaryKeys(\n  pubs: PublishedSchema,\n): ReplicaIdentities | undefined {\n  const replicaIdentities: {\n    schema: string;\n    tableName: string;\n    indexName: string;\n  }[] = [];\n  for (const table of pubs.tables) {\n    if (!table.primaryKey?.length && table.replicaIdentity === Default) {\n      // Look for an index that can serve as the REPLICA IDENTITY USING INDEX. It must be:\n      // - UNIQUE\n      // - NOT NULL columns\n      // - not deferrable (i.e. isImmediate)\n      // - not partial\n      //\n      // https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY\n      const {schema, name: tableName} = table;\n      for (const {columns, name: indexName} of pubs.indexes.filter(\n        idx =>\n          idx.schema === schema &&\n          idx.tableName === tableName &&\n          idx.unique &&\n          idx.isImmediate &&\n          idx.predicate === undefined,\n      )) {\n        if (Object.keys(columns).some(col => !table.columns[col].notNull)) {\n          continue; // Only indexes with all NOT NULL columns are suitable.\n        }\n        replicaIdentities.push({schema, tableName, indexName});\n        break;\n      }\n    }\n  }\n\n  if (replicaIdentities.length === 0) {\n    return undefined;\n  }\n  return {\n    apply: async (lc: LogContext, sql: PostgresDB) => {\n      for (const {schema, tableName, indexName} of replicaIdentities) {\n        lc.info?.(\n          `setting \"${indexName}\" as the REPLICA IDENTITY for \"${tableName}\"`,\n        );\n        await sql`\n        ALTER TABLE ${sql(schema)}.${sql(tableName)} \n          REPLICA IDENTITY USING INDEX ${sql(indexName)}`;\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/change-source/protocol/backfill-progress.d.ts

@@ -0,0 +1,68 @@
+import type { BackfillProgressMark, BackfillRequest } from './current.ts';
+/**
+ * The result of applying a backfill message to a column's tracked progress.
+ * If `accept` is true, `progress` is the column's new progress.
+ */
+export type AcceptResult = {
+    accept: true;
+    progress: BackfillProgressMark | undefined;
+} | {
+    accept: false;
+};
+/**
+ * Applies the continuity policy of `backfill` (and `backfill-completed`)
+ * messages to a column's `own` tracked progress, where `undefined` means that
+ * the column has not received any backfill data (i.e. it needs a backfill
+ * from scratch).
+ *
+ * * Messages without `progressMarks` are from pre-v8 replication-managers
+ *   and are accepted unconditionally (i.e. the legacy behavior), with no
+ *   change to the tracked progress.
+ * * A message without a `previous` mark starts a backfill from scratch (or on
+ *   a new timeline), and is always accepted.
+ * * Otherwise, the message is only accepted if it is on the same timeline as
+ *   `own`, and continues from a position at or before `own` (i.e. it does not
+ *   create a gap).
+ *
+ * `current` is unset for `backfill-completed` messages, which do not advance
+ * the progress.
+ */
+export declare function acceptBackfill(own: BackfillProgressMark | undefined, marks: {
+    previous?: BackfillProgressMark | undefined;
+    current?: BackfillProgressMark;
+} | undefined): AcceptResult;
+/**
+ * Returns whether a stream whose progress (for a column) is at `stream`
+ * will deliver all of the data needed by a subscriber whose progress (for the
+ * same column) is at `subscriber`. A `stream` progress of `undefined` indicates
+ * a backfill that will start from scratch, which covers all subscribers.
+ */
+export declare function covers(stream: BackfillProgressMark | undefined, subscriber: BackfillProgressMark | undefined): boolean;
+/**
+ * Returns the position from which a backfill for the `req` must start
+ * in order to satisfy the progress of all of its columns, i.e. the earliest
+ * progress mark, or `undefined` (i.e. from scratch) if any column has no
+ * progress or if the columns are on different timelines.
+ */
+export declare function resumePoint(req: BackfillRequest): BackfillProgressMark | undefined;
+/**
+ * Returns a copy of the `req` with the progress of every column set to
+ * the request's {@link resumePoint}, i.e. the position from which the
+ * backfill of the request will actually start.
+ */
+export declare function withResumePoint(req: BackfillRequest): BackfillRequest;
+/**
+ * Merges two BackfillRequests for the same table into one that satisfies
+ * both. Both requests are expected to reflect the same (current) upstream
+ * schema. For columns in both requests, the earlier progress mark is chosen,
+ * or no progress mark (i.e. from scratch) if they are on different timelines.
+ * If a column's backfill IDs differ (which is unexpected), the ID of `req1`
+ * is chosen, and the column is backfilled from scratch.
+ */
+export declare function getTableSuperset(req1: BackfillRequest, req2: BackfillRequest): BackfillRequest;
+/**
+ * Merges the BackfillRequests of multiple parties (e.g. subscribers) into
+ * one request per table, using {@link getTableSuperset}.
+ */
+export declare function getSuperset(...requestSets: Iterable<BackfillRequest>[]): BackfillRequest[];
+//# sourceMappingURL=backfill-progress.d.ts.map

package/out/zero-cache/src/services/change-source/protocol/backfill-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-progress.d.ts","sourceRoot":"","sources":["../../../../../../../zero-cache/src/services/change-source/protocol/backfill-progress.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EAEhB,MAAM,cAAc,CAAC;AAyBtB;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,CAAA;CAAC,GAC1D;IAAC,MAAM,EAAE,KAAK,CAAA;CAAC,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,KAAK,EACD;IACE,QAAQ,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC5C,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC,GACD,SAAS,GACZ,YAAY,CAyBd;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,UAAU,EAAE,oBAAoB,GAAG,SAAS,GAC3C,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,eAAe,GACnB,oBAAoB,GAAG,SAAS,CAelC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAWrE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,eAAe,GACpB,eAAe,CA4BjB;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,WAAW,EAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,GAC1C,eAAe,EAAE,CAUnB"}

package/out/zero-cache/src/services/change-source/protocol/backfill-progress.js

@@ -0,0 +1,141 @@
+import { deepEqual } from "../../../../../shared/src/json.js";
+//#region ../zero-cache/src/services/change-source/protocol/backfill-progress.ts
+/**
+* Whether two progress marks are on the same timeline, and are thus comparable.
+*/
+function sameTimeline(a, b) {
+	return a.timeline === b.timeline;
+}
+/** Returns the earlier of two marks on the same timeline. */
+function earlier(a, b) {
+	return b.progressMark < a.progressMark ? b : a;
+}
+/** Returns the later of two marks on the same timeline. */
+function later(a, b) {
+	return b.progressMark > a.progressMark ? b : a;
+}
+/**
+* Applies the continuity policy of `backfill` (and `backfill-completed`)
+* messages to a column's `own` tracked progress, where `undefined` means that
+* the column has not received any backfill data (i.e. it needs a backfill
+* from scratch).
+*
+* * Messages without `progressMarks` are from pre-v8 replication-managers
+*   and are accepted unconditionally (i.e. the legacy behavior), with no
+*   change to the tracked progress.
+* * A message without a `previous` mark starts a backfill from scratch (or on
+*   a new timeline), and is always accepted.
+* * Otherwise, the message is only accepted if it is on the same timeline as
+*   `own`, and continues from a position at or before `own` (i.e. it does not
+*   create a gap).
+*
+* `current` is unset for `backfill-completed` messages, which do not advance
+* the progress.
+*/
+function acceptBackfill(own, marks) {
+	if (marks === void 0) return {
+		accept: true,
+		progress: own
+	};
+	const { previous, current } = marks;
+	if (previous === void 0) return {
+		accept: true,
+		progress: current
+	};
+	if (own === void 0 || !sameTimeline(own, previous) || previous.progressMark > own.progressMark) return { accept: false };
+	return {
+		accept: true,
+		progress: current === void 0 ? own : sameTimeline(own, current) ? later(own, current) : current
+	};
+}
+/**
+* Returns whether a stream whose progress (for a column) is at `stream`
+* will deliver all of the data needed by a subscriber whose progress (for the
+* same column) is at `subscriber`. A `stream` progress of `undefined` indicates
+* a backfill that will start from scratch, which covers all subscribers.
+*/
+function covers(stream, subscriber) {
+	return stream === void 0 || subscriber !== void 0 && sameTimeline(stream, subscriber) && stream.progressMark <= subscriber.progressMark;
+}
+/**
+* Returns the position from which a backfill for the `req` must start
+* in order to satisfy the progress of all of its columns, i.e. the earliest
+* progress mark, or `undefined` (i.e. from scratch) if any column has no
+* progress or if the columns are on different timelines.
+*/
+function resumePoint(req) {
+	let point;
+	for (const { progress } of Object.values(req.columns)) {
+		if (progress === void 0) return;
+		if (point === void 0) point = progress;
+		else if (!sameTimeline(point, progress)) return;
+		else point = earlier(point, progress);
+	}
+	return point;
+}
+/**
+* Returns a copy of the `req` with the progress of every column set to
+* the request's {@link resumePoint}, i.e. the position from which the
+* backfill of the request will actually start.
+*/
+function withResumePoint(req) {
+	const progress = resumePoint(req);
+	return {
+		table: req.table,
+		columns: Object.fromEntries(Object.entries(req.columns).map(([col, { id }]) => [col, progress === void 0 ? { id } : {
+			id,
+			progress
+		}]))
+	};
+}
+/**
+* Merges two BackfillRequests for the same table into one that satisfies
+* both. Both requests are expected to reflect the same (current) upstream
+* schema. For columns in both requests, the earlier progress mark is chosen,
+* or no progress mark (i.e. from scratch) if they are on different timelines.
+* If a column's backfill IDs differ (which is unexpected), the ID of `req1`
+* is chosen, and the column is backfilled from scratch.
+*/
+function getTableSuperset(req1, req2) {
+	const columns = { ...req1.columns };
+	for (const [name, col] of Object.entries(req2.columns)) {
+		const exists = columns[name];
+		if (!exists) {
+			columns[name] = col;
+			continue;
+		}
+		const { id, progress } = exists;
+		if (progress === void 0 || col.progress === void 0 || !sameTimeline(progress, col.progress) || !deepEqual(id, col.id)) columns[name] = { id };
+		else columns[name] = {
+			id,
+			progress: earlier(progress, col.progress)
+		};
+	}
+	return {
+		table: {
+			...req1.table,
+			metadata: req1.table.metadata ?? req2.table.metadata
+		},
+		columns
+	};
+}
+function tableKey({ schema, name }) {
+	return JSON.stringify([schema, name]);
+}
+/**
+* Merges the BackfillRequests of multiple parties (e.g. subscribers) into
+* one request per table, using {@link getTableSuperset}.
+*/
+function getSuperset(...requestSets) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const requests of requestSets) for (const req of requests) {
+		const key = tableKey(req.table);
+		const existing = merged.get(key);
+		merged.set(key, existing ? getTableSuperset(existing, req) : req);
+	}
+	return [...merged.values()];
+}
+//#endregion
+export { acceptBackfill, covers, getSuperset, resumePoint, withResumePoint };
+
+//# sourceMappingURL=backfill-progress.js.map

package/out/zero-cache/src/services/change-source/protocol/backfill-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-progress.js","names":[],"sources":["../../../../../../../zero-cache/src/services/change-source/protocol/backfill-progress.ts"],"sourcesContent":["import {deepEqual} from '../../../../../shared/src/json.ts';\nimport type {\n  BackfillProgressMark,\n  BackfillRequest,\n  Identifier,\n} from './current.ts';\n\n/**\n * Whether two progress marks are on the same timeline, and are thus comparable.\n */\nfunction sameTimeline(a: BackfillProgressMark, b: BackfillProgressMark) {\n  return a.timeline === b.timeline;\n}\n\n/** Returns the earlier of two marks on the same timeline. */\nfunction earlier(\n  a: BackfillProgressMark,\n  b: BackfillProgressMark,\n): BackfillProgressMark {\n  return b.progressMark < a.progressMark ? b : a;\n}\n\n/** Returns the later of two marks on the same timeline. */\nfunction later(\n  a: BackfillProgressMark,\n  b: BackfillProgressMark,\n): BackfillProgressMark {\n  return b.progressMark > a.progressMark ? b : a;\n}\n\n/**\n * The result of applying a backfill message to a column's tracked progress.\n * If `accept` is true, `progress` is the column's new progress.\n */\nexport type AcceptResult =\n  | {accept: true; progress: BackfillProgressMark | undefined}\n  | {accept: false};\n\n/**\n * Applies the continuity policy of `backfill` (and `backfill-completed`)\n * messages to a column's `own` tracked progress, where `undefined` means that\n * the column has not received any backfill data (i.e. it needs a backfill\n * from scratch).\n *\n * * Messages without `progressMarks` are from pre-v8 replication-managers\n *   and are accepted unconditionally (i.e. the legacy behavior), with no\n *   change to the tracked progress.\n * * A message without a `previous` mark starts a backfill from scratch (or on\n *   a new timeline), and is always accepted.\n * * Otherwise, the message is only accepted if it is on the same timeline as\n *   `own`, and continues from a position at or before `own` (i.e. it does not\n *   create a gap).\n *\n * `current` is unset for `backfill-completed` messages, which do not advance\n * the progress.\n */\nexport function acceptBackfill(\n  own: BackfillProgressMark | undefined,\n  marks:\n    | {\n        previous?: BackfillProgressMark | undefined;\n        current?: BackfillProgressMark;\n      }\n    | undefined,\n): AcceptResult {\n  if (marks === undefined) {\n    return {accept: true, progress: own}; // legacy (pre-v8)\n  }\n  const {previous, current} = marks;\n  // Starting from scratch is always accepted, as there can be no gap.\n  if (previous === undefined) {\n    return {accept: true, progress: current};\n  }\n  if (\n    own === undefined ||\n    !sameTimeline(own, previous) ||\n    previous.progressMark > own.progressMark\n  ) {\n    return {accept: false};\n  }\n  return {\n    accept: true,\n    progress:\n      current === undefined\n        ? own\n        : sameTimeline(own, current)\n          ? later(own, current)\n          : current,\n  };\n}\n\n/**\n * Returns whether a stream whose progress (for a column) is at `stream`\n * will deliver all of the data needed by a subscriber whose progress (for the\n * same column) is at `subscriber`. A `stream` progress of `undefined` indicates\n * a backfill that will start from scratch, which covers all subscribers.\n */\nexport function covers(\n  stream: BackfillProgressMark | undefined,\n  subscriber: BackfillProgressMark | undefined,\n): boolean {\n  return (\n    stream === undefined ||\n    (subscriber !== undefined &&\n      sameTimeline(stream, subscriber) &&\n      stream.progressMark <= subscriber.progressMark)\n  );\n}\n\n/**\n * Returns the position from which a backfill for the `req` must start\n * in order to satisfy the progress of all of its columns, i.e. the earliest\n * progress mark, or `undefined` (i.e. from scratch) if any column has no\n * progress or if the columns are on different timelines.\n */\nexport function resumePoint(\n  req: BackfillRequest,\n): BackfillProgressMark | undefined {\n  let point: BackfillProgressMark | undefined;\n  for (const {progress} of Object.values(req.columns)) {\n    if (progress === undefined) {\n      return undefined;\n    }\n    if (point === undefined) {\n      point = progress;\n    } else if (!sameTimeline(point, progress)) {\n      return undefined;\n    } else {\n      point = earlier(point, progress);\n    }\n  }\n  return point;\n}\n\n/**\n * Returns a copy of the `req` with the progress of every column set to\n * the request's {@link resumePoint}, i.e. the position from which the\n * backfill of the request will actually start.\n */\nexport function withResumePoint(req: BackfillRequest): BackfillRequest {\n  const progress = resumePoint(req);\n  return {\n    table: req.table,\n    columns: Object.fromEntries(\n      Object.entries(req.columns).map(([col, {id}]) => [\n        col,\n        progress === undefined ? {id} : {id, progress},\n      ]),\n    ),\n  };\n}\n\n/**\n * Merges two BackfillRequests for the same table into one that satisfies\n * both. Both requests are expected to reflect the same (current) upstream\n * schema. For columns in both requests, the earlier progress mark is chosen,\n * or no progress mark (i.e. from scratch) if they are on different timelines.\n * If a column's backfill IDs differ (which is unexpected), the ID of `req1`\n * is chosen, and the column is backfilled from scratch.\n */\nexport function getTableSuperset(\n  req1: BackfillRequest,\n  req2: BackfillRequest,\n): BackfillRequest {\n  const columns = {...req1.columns};\n  for (const [name, col] of Object.entries(req2.columns)) {\n    const exists = columns[name];\n    if (!exists) {\n      columns[name] = col;\n      continue;\n    }\n    const {id, progress} = exists;\n    if (\n      progress === undefined ||\n      col.progress === undefined ||\n      !sameTimeline(progress, col.progress) ||\n      !deepEqual(id, col.id)\n    ) {\n      // Different timelines (or IDs). Start from scratch.\n      columns[name] = {id};\n    } else {\n      columns[name] = {id, progress: earlier(progress, col.progress)};\n    }\n  }\n  return {\n    table: {\n      ...req1.table,\n      metadata: req1.table.metadata ?? req2.table.metadata,\n    },\n    columns,\n  };\n}\n\nfunction tableKey({schema, name}: Identifier) {\n  return JSON.stringify([schema, name]);\n}\n\n/**\n * Merges the BackfillRequests of multiple parties (e.g. subscribers) into\n * one request per table, using {@link getTableSuperset}.\n */\nexport function getSuperset(\n  ...requestSets: Iterable<BackfillRequest>[]\n): BackfillRequest[] {\n  const merged = new Map<string, BackfillRequest>();\n  for (const requests of requestSets) {\n    for (const req of requests) {\n      const key = tableKey(req.table);\n      const existing = merged.get(key);\n      merged.set(key, existing ? getTableSuperset(existing, req) : req);\n    }\n  }\n  return [...merged.values()];\n}\n"],"mappings":";;;;;AAUA,SAAS,aAAa,GAAyB,GAAyB;CACtE,OAAO,EAAE,aAAa,EAAE;AAC1B;;AAGA,SAAS,QACP,GACA,GACsB;CACtB,OAAO,EAAE,eAAe,EAAE,eAAe,IAAI;AAC/C;;AAGA,SAAS,MACP,GACA,GACsB;CACtB,OAAO,EAAE,eAAe,EAAE,eAAe,IAAI;AAC/C;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,eACd,KACA,OAMc;CACd,IAAI,UAAU,KAAA,GACZ,OAAO;EAAC,QAAQ;EAAM,UAAU;CAAG;CAErC,MAAM,EAAC,UAAU,YAAW;CAE5B,IAAI,aAAa,KAAA,GACf,OAAO;EAAC,QAAQ;EAAM,UAAU;CAAO;CAEzC,IACE,QAAQ,KAAA,KACR,CAAC,aAAa,KAAK,QAAQ,KAC3B,SAAS,eAAe,IAAI,cAE5B,OAAO,EAAC,QAAQ,MAAK;CAEvB,OAAO;EACL,QAAQ;EACR,UACE,YAAY,KAAA,IACR,MACA,aAAa,KAAK,OAAO,IACvB,MAAM,KAAK,OAAO,IAClB;CACV;AACF;;;;;;;AAQA,SAAgB,OACd,QACA,YACS;CACT,OACE,WAAW,KAAA,KACV,eAAe,KAAA,KACd,aAAa,QAAQ,UAAU,KAC/B,OAAO,gBAAgB,WAAW;AAExC;;;;;;;AAQA,SAAgB,YACd,KACkC;CAClC,IAAI;CACJ,KAAK,MAAM,EAAC,cAAa,OAAO,OAAO,IAAI,OAAO,GAAG;EACnD,IAAI,aAAa,KAAA,GACf;EAEF,IAAI,UAAU,KAAA,GACZ,QAAQ;OACH,IAAI,CAAC,aAAa,OAAO,QAAQ,GACtC;OAEA,QAAQ,QAAQ,OAAO,QAAQ;CAEnC;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,gBAAgB,KAAuC;CACrE,MAAM,WAAW,YAAY,GAAG;CAChC,OAAO;EACL,OAAO,IAAI;EACX,SAAS,OAAO,YACd,OAAO,QAAQ,IAAI,OAAO,EAAE,KAAK,CAAC,KAAK,EAAC,UAAS,CAC/C,KACA,aAAa,KAAA,IAAY,EAAC,GAAE,IAAI;GAAC;GAAI;EAAQ,CAC/C,CAAC,CACH;CACF;AACF;;;;;;;;;AAUA,SAAgB,iBACd,MACA,MACiB;CACjB,MAAM,UAAU,EAAC,GAAG,KAAK,QAAO;CAChC,KAAK,MAAM,CAAC,MAAM,QAAQ,OAAO,QAAQ,KAAK,OAAO,GAAG;EACtD,MAAM,SAAS,QAAQ;EACvB,IAAI,CAAC,QAAQ;GACX,QAAQ,QAAQ;GAChB;EACF;EACA,MAAM,EAAC,IAAI,aAAY;EACvB,IACE,aAAa,KAAA,KACb,IAAI,aAAa,KAAA,KACjB,CAAC,aAAa,UAAU,IAAI,QAAQ,KACpC,CAAC,UAAU,IAAI,IAAI,EAAE,GAGrB,QAAQ,QAAQ,EAAC,GAAE;OAEnB,QAAQ,QAAQ;GAAC;GAAI,UAAU,QAAQ,UAAU,IAAI,QAAQ;EAAC;CAElE;CACA,OAAO;EACL,OAAO;GACL,GAAG,KAAK;GACR,UAAU,KAAK,MAAM,YAAY,KAAK,MAAM;EAC9C;EACA;CACF;AACF;AAEA,SAAS,SAAS,EAAC,QAAQ,QAAmB;CAC5C,OAAO,KAAK,UAAU,CAAC,QAAQ,IAAI,CAAC;AACtC;;;;;AAMA,SAAgB,YACd,GAAG,aACgB;CACnB,MAAM,yBAAS,IAAI,IAA6B;CAChD,KAAK,MAAM,YAAY,aACrB,KAAK,MAAM,OAAO,UAAU;EAC1B,MAAM,MAAM,SAAS,IAAI,KAAK;EAC9B,MAAM,WAAW,OAAO,IAAI,GAAG;EAC/B,OAAO,IAAI,KAAK,WAAW,iBAAiB,UAAU,GAAG,IAAI,GAAG;CAClE;CAEF,OAAO,CAAC,GAAG,OAAO,OAAO,CAAC;AAC5B"}