@rocicorp/zero 1.9.0-head-ef892a12-20260713 → 1.9.0

package/out/zero-cache/src/services/change-source/pg/logical-replication/stream.js

@@ -12,7 +12,7 @@ import postgres from "postgres";
 import { PG_ADMIN_SHUTDOWN, PG_OBJECT_IN_USE, PG_OBJECT_NOT_IN_PREREQUISITE_STATE } from "@drdgvhbh/postgres-error-codes";
 //#region ../zero-cache/src/services/change-source/pg/logical-replication/stream.ts
 var DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE = 5;
-async function subscribe(lc, db, slot, publications, lsn, retriesIfReplicationSlotActive = DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE, applicationName = "zero-replicator") {
+async function subscribe(lc, db, slot, publications, lsn, retriesIfReplicationSlotActive = DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE, applicationName = "zero-replicator", inboundTimeoutOverrideMs) {
 	const session = postgres(defu({
 		max: 1,
 		["fetch_types"]: false,
@@ -26,28 +26,33 @@ async function subscribe(lc, db, slot, publications, lsn, retriesIfReplicationSl
 	const [{ walSenderTimeoutMs }] = await session`SELECT EXTRACT(EPOCH FROM (setting || unit)::interval) * 1000 
         AS "walSenderTimeoutMs" FROM pg_settings
         WHERE name = 'wal_sender_timeout'`.simple();
-	const manualKeepaliveTimeout = Math.floor(walSenderTimeoutMs * .75);
-	lc.info?.(`wal_sender_timeout: ${walSenderTimeoutMs}ms. Ensuring manual keepalives at least every ${manualKeepaliveTimeout}ms`);
+	const { enabled: livenessEnabled, manualKeepaliveTimeout, inboundTimeoutMs, timerIntervalMs } = computeLivenessTimings(walSenderTimeoutMs, inboundTimeoutOverrideMs);
+	lc.info?.(livenessEnabled ? `wal_sender_timeout: ${walSenderTimeoutMs}ms. Ensuring manual keepalives at least every ${manualKeepaliveTimeout}ms. Inbound timeout: ${inboundTimeoutMs}ms` + (inboundTimeoutMs === walSenderTimeoutMs * 2 ? "" : " (configured override)") : "wal_sender_timeout is disabled (0); skipping manual keepalives and inbound liveness detection.");
 	const [readable, writable] = await startReplicationStream(lc, session, slot, publications, lsn, retriesIfReplicationSlotActive + 1);
 	let lastAckTime = Date.now();
 	function sendAck(lsn) {
 		writable.write(makeAck(lsn));
 		lastAckTime = Date.now();
 	}
-	const inboundTimeoutMs = walSenderTimeoutMs * 2;
 	let lastReceivedTime = Date.now();
-	const livenessTimer = setInterval(() => {
+	const livenessTimer = livenessEnabled ? setInterval(() => {
 		const now = Date.now();
 		if (now - lastAckTime > manualKeepaliveTimeout) {
 			sendAck(0n);
 			lc.debug?.(`sent manual keepalive`);
 		}
 		const sinceLastReceived = now - lastReceivedTime;
-		if (sinceLastReceived > inboundTimeoutMs && !readable.destroyed) {
-			lc.warn?.(`no message received from ${db.options.host} in ${sinceLastReceived}ms (> 2x wal_sender_timeout ${walSenderTimeoutMs}ms). Destroying replication stream to force reconnect.`);
+		const { resetWindow, timedOut } = evaluateInboundLiveness({
+			sinceLastReceived,
+			inboundTimeoutMs,
+			queued: messages.queued
+		});
+		if (resetWindow) lastReceivedTime = now;
+		else if (timedOut && !readable.destroyed) {
+			lc.warn?.(`no message received from ${db.options.host} in ${sinceLastReceived}ms (> inbound timeout ${inboundTimeoutMs}ms). Destroying replication stream to force reconnect.`);
 			readable.destroy(/* @__PURE__ */ new Error(`replication stream inbound timeout after ${sinceLastReceived}ms`));
 		}
-	}, manualKeepaliveTimeout / 5);
+	}, timerIntervalMs) : void 0;
 	let destroyed = false;
 	const parser = new PgoutputParser(await getTypeParsers(db, { returnJsonAsString: true }));
 	const messages = Subscription.create({ cleanup: () => {
@@ -73,6 +78,81 @@ async function subscribe(lc, db, slot, publications, lsn, retriesIfReplicationSl
 	};
 }
 /**
+* Derives the timings for the replication liveness timer from the server's
+* `wal_sender_timeout` (in milliseconds).
+*
+* Postgres treats `wal_sender_timeout = 0` as "disabled": it will neither
+* terminate an idle wal sender nor emit the periodic keepalives it otherwise
+* sends at roughly `wal_sender_timeout / 2`. Every timing below is derived from
+* that interval, so a disabled timeout disables the liveness machinery entirely
+* (`enabled: false`). Otherwise the derived thresholds would all collapse to 0,
+* inverting the intended meaning: the inbound watchdog would fire on the very
+* first tick and destroy the stream, while the timer itself would busy-spin at
+* a 0ms interval — together producing a continuous reconnect storm.
+*
+* An `inboundTimeoutOverrideMs` (when positive) replaces the default
+* `2x wal_sender_timeout` inbound threshold. The two timeouts protect
+* different parties with asymmetric false-positive costs: `wal_sender_timeout`
+* is the server reaping dead clients (a false positive there costs a cheap
+* reconnect), while the inbound watchdog tears down the stream and replays the
+* in-flight transaction — expensive, and self-defeating when the wal sender is
+* legitimately silent for long stretches (e.g. decoding through WAL from
+* unpublished tables, or assembling a large transaction that pgoutput only
+* sends at commit). Operators who don't own the server setting (e.g. managed
+* or operator-provisioned Postgres with an aggressive cluster-wide
+* `wal_sender_timeout`) can widen the client-side fuse independently.
+*
+* The override has no effect when `wal_sender_timeout` is disabled (0): the
+* server then sends no periodic keepalives, so inbound silence is normal even
+* on an idle healthy connection and any silence-based watchdog would
+* false-positive.
+*
+* https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT
+*/
+function computeLivenessTimings(walSenderTimeoutMs, inboundTimeoutOverrideMs) {
+	if (!(walSenderTimeoutMs > 0)) return {
+		enabled: false,
+		manualKeepaliveTimeout: 0,
+		inboundTimeoutMs: 0,
+		timerIntervalMs: 0
+	};
+	const manualKeepaliveTimeout = Math.floor(walSenderTimeoutMs * .75);
+	return {
+		enabled: true,
+		manualKeepaliveTimeout,
+		inboundTimeoutMs: inboundTimeoutOverrideMs !== void 0 && inboundTimeoutOverrideMs > 0 ? inboundTimeoutOverrideMs : walSenderTimeoutMs * 2,
+		timerIntervalMs: manualKeepaliveTimeout / 5
+	};
+}
+/**
+* Pure decision for the inbound-liveness watchdog, given the time since the
+* last inbound message, the timeout threshold, and the number of messages
+* currently queued downstream (see {@link SourceWithPendingQueue.queued}).
+*
+* A non-empty downstream queue means we have received data we haven't yet
+* consumed: the reason we aren't receiving *more* is our own back-pressure, not
+* upstream silence. In that case we `resetWindow` (treat the backlog as
+* liveness evidence) rather than counting the stall against the connection.
+* This both suppresses false timeouts during back-pressure and — crucially —
+* keeps `lastReceivedTime` fresh so the drain transition (queue emptying after
+* a long stall) doesn't fire the watchdog against a stale timestamp on the very
+* next tick.
+*
+* Only when the queue is empty (consumption has caught up, so reading — and
+* thus keepalives — should be flowing again) does an over-threshold gap
+* indicate a genuinely dead inbound half.
+*/
+function evaluateInboundLiveness({ sinceLastReceived, inboundTimeoutMs, queued }) {
+	if (queued > 0) return {
+		resetWindow: true,
+		timedOut: false
+	};
+	return {
+		resetWindow: false,
+		timedOut: sinceLastReceived > inboundTimeoutMs
+	};
+}
+/**
 * Formats publication names for the START_REPLICATION command.
 * The replication protocol expects format: publication_names 'pub1,pub2'
 * Each name is escaped to handle any quotes that may have passed validation.

package/out/zero-cache/src/services/change-source/pg/logical-replication/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/logical-replication/stream.ts"],"sourcesContent":["import {\n  PG_ADMIN_SHUTDOWN,\n  PG_OBJECT_IN_USE,\n  PG_OBJECT_NOT_IN_PREREQUISITE_STATE,\n} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {defu} from 'defu';\nimport postgres, {type Options, type PostgresType} from 'postgres';\nimport {sleep} from '../../../../../../shared/src/sleep.ts';\nimport {getTypeParsers} from '../../../../db/pg-type-parser.ts';\nimport {type PostgresDB} from '../../../../types/pg.ts';\nimport {id, lit} from '../../../../types/sql.ts';\nimport {pipe, type Sink, type Source} from '../../../../types/streams.ts';\nimport {Subscription} from '../../../../types/subscription.ts';\nimport {AutoResetSignal} from '../../../change-streamer/schema/tables.ts';\nimport {fromBigInt} from '../lsn.ts';\nimport {PgoutputParser} from './pgoutput-parser.ts';\nimport type {Message} from './pgoutput.types.ts';\n\nconst DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE = 5;\n\nexport type StreamMessage = [\n  lsn: bigint,\n  Message | {tag: 'keepalive'; shouldRespond: boolean},\n];\n\n// Expose the `queued` variable of the Subscription to allow\n// the change-source to determine if there are more messages\n// immediately available.\ntype SourceWithPendingQueue<T> = Source<T> & {\n  queued: number;\n};\n\nexport async function subscribe(\n  lc: LogContext,\n  db: PostgresDB,\n  slot: string,\n  publications: string[],\n  lsn: bigint,\n  retriesIfReplicationSlotActive = DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE,\n  applicationName = 'zero-replicator',\n): Promise<{\n  messages: SourceWithPendingQueue<StreamMessage>;\n  acks: Sink<bigint>;\n}> {\n  const session = postgres(\n    defu(\n      {\n        max: 1,\n        ['fetch_types']: false, // Necessary for the streaming protocol\n        ['idle_timeout']: null,\n        ['max_lifetime']: null as unknown as number,\n        connection: {\n          ['application_name']: applicationName,\n          replication: 'database', // https://www.postgresql.org/docs/current/protocol-replication.html\n        },\n      },\n      // ParsedOptions are technically compatible with Options, but happen\n      // to not be typed that way. The postgres.js author does an equivalent\n      // merge of ParsedOptions and Options here:\n      // https://github.com/porsager/postgres/blob/089214e85c23c90cf142d47fb30bd03f42874984/src/subscribe.js#L13\n      db.options as unknown as Options<Record<string, PostgresType>>,\n    ),\n  );\n\n  // Postgres will send keepalives before timing out a wal_sender. It is possible that\n  // these keepalives are not received if there is back-pressure in the replication\n  // stream. To keep the connection alive, explicitly send keepalives if none have been\n  // sent within the last 75% of the wal_sender_timeout.\n  //\n  // https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT\n  const [{walSenderTimeoutMs}] = await session<\n    {walSenderTimeoutMs: number}[]\n  >`SELECT EXTRACT(EPOCH FROM (setting || unit)::interval) * 1000 \n        AS \"walSenderTimeoutMs\" FROM pg_settings\n        WHERE name = 'wal_sender_timeout'`.simple();\n  const manualKeepaliveTimeout = Math.floor(walSenderTimeoutMs * 0.75);\n  lc.info?.(\n    `wal_sender_timeout: ${walSenderTimeoutMs}ms. ` +\n      `Ensuring manual keepalives at least every ${manualKeepaliveTimeout}ms`,\n  );\n\n  const [readable, writable] = await startReplicationStream(\n    lc,\n    session,\n    slot,\n    publications,\n    lsn,\n    retriesIfReplicationSlotActive + 1,\n  );\n\n  let lastAckTime = Date.now();\n  function sendAck(lsn: bigint) {\n    writable.write(makeAck(lsn));\n    lastAckTime = Date.now();\n  }\n\n  // Postgres promises to send a keepalive at roughly wal_sender_timeout / 2.\n  // If we go long enough without receiving anything (data or keepalive), the\n  // inbound half of the connection is silently dead — our outbound acks keep\n  // flowing into the void, neither side errors, and the change-source sits\n  // there forever. Tear down the readable to force a reconnect.\n  //\n  // The threshold is 2x wal_sender_timeout — i.e. two consecutive keepalives\n  // missed — to avoid spurious reconnects from a single delayed keepalive\n  // (PG scheduling jitter under load, our own event-loop stalls, etc.).\n  const inboundTimeoutMs = walSenderTimeoutMs * 2;\n  let lastReceivedTime = Date.now();\n\n  const livenessTimer = setInterval(() => {\n    const now = Date.now();\n    if (now - lastAckTime > manualKeepaliveTimeout) {\n      sendAck(0n);\n      lc.debug?.(`sent manual keepalive`);\n    }\n    const sinceLastReceived = now - lastReceivedTime;\n    if (sinceLastReceived > inboundTimeoutMs && !readable.destroyed) {\n      lc.warn?.(\n        `no message received from ${db.options.host} in ${sinceLastReceived}ms ` +\n          `(> 2x wal_sender_timeout ${walSenderTimeoutMs}ms). Destroying ` +\n          `replication stream to force reconnect.`,\n      );\n      readable.destroy(\n        new Error(\n          `replication stream inbound timeout after ${sinceLastReceived}ms`,\n        ),\n      );\n    }\n  }, manualKeepaliveTimeout / 5);\n\n  let destroyed = false;\n  const typeParsers = await getTypeParsers(db, {returnJsonAsString: true});\n  const parser = new PgoutputParser(typeParsers);\n  const messages = Subscription.create<StreamMessage>({\n    cleanup: () => {\n      destroyed = true;\n      readable.destroyed || readable.destroy();\n      clearInterval(livenessTimer);\n      return session.end();\n    },\n  });\n\n  readable.once(\n    'close',\n    () =>\n      // Only log a warning if the stream was not manually closed.\n      destroyed || lc.warn?.(`replication stream closed by ${db.options.host}`),\n  );\n  readable.once(\n    'error',\n    e =>\n      // Don't log the shutdown signal. This is the expected way for upstream\n      // to close the connection (and will be logged downstream).\n      (e instanceof postgres.PostgresError && e.code === PG_ADMIN_SHUTDOWN) ||\n      lc.warn?.(`error from ${db.options.host}`, e),\n  );\n\n  pipe({\n    source: readable,\n    sink: messages,\n    parse: buffer => {\n      lastReceivedTime = Date.now();\n      return parseStreamMessage(lc, buffer, parser);\n    },\n    // Allow a small buffer of messages to be queued in the subscription so\n    // that the change-source loop can check the queue to determine if more\n    // messages are immediately available.\n    bufferMessages: 5,\n  });\n\n  return {\n    messages,\n    acks: {push: sendAck},\n  };\n}\n\n/**\n * Formats publication names for the START_REPLICATION command.\n * The replication protocol expects format: publication_names 'pub1,pub2'\n * Each name is escaped to handle any quotes that may have passed validation.\n */\nfunction formatPublicationNames(publications: string[]): string {\n  // lit() returns 'escaped_name' with surrounding quotes\n  // We strip the quotes since the outer quotes are in the template\n  return publications.map(p => lit(p).slice(1, -1)).join(',');\n}\n\nasync function startReplicationStream(\n  lc: LogContext,\n  session: postgres.Sql,\n  slot: string,\n  publications: string[],\n  lsn: bigint,\n  maxAttempts: number,\n) {\n  for (let i = 0; i < maxAttempts; i++) {\n    try {\n      const stream = session\n        .unsafe(\n          `START_REPLICATION SLOT ${id(slot)} LOGICAL ${fromBigInt(lsn)} (\n        proto_version '1',\n        publication_names '${formatPublicationNames(publications)}',\n        messages 'true'\n      )`,\n        )\n        .execute();\n      return await Promise.all([stream.readable(), stream.writable()]);\n    } catch (e) {\n      if (e instanceof postgres.PostgresError) {\n        // error: replication slot \"zero_slot_change_source_test_id\" is active for PID 268\n        if (e.code === PG_OBJECT_IN_USE) {\n          // The freeing up of the replication slot is not transactional;\n          // sometimes it takes time for Postgres to consider the slot\n          // inactive.\n          lc.warn?.(`attempt ${i + 1}: ${String(e)}`, e);\n          await sleep(10);\n          continue;\n        }\n        // error: This slot has been invalidated because it exceeded the maximum reserved size.\n        // (This is a different manifestation of a slot being invalidated when\n        //  the wal exceeds the max_slot_wal_keep_size)\n        if (e.code === PG_OBJECT_NOT_IN_PREREQUISITE_STATE) {\n          lc.error?.(`error starting replication stream`, e);\n          throw new AutoResetSignal(`unable to start replication stream`, {\n            cause: e,\n          });\n        }\n      }\n      throw e;\n    }\n  }\n  throw new Error(\n    `exceeded max attempts (${maxAttempts}) to start the Postgres stream`,\n  );\n}\n\nfunction parseStreamMessage(\n  lc: LogContext,\n  buffer: Buffer,\n  parser: PgoutputParser,\n): StreamMessage | null {\n  // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-START-REPLICATION\n  if (buffer[0] !== 0x77 && buffer[0] !== 0x6b) {\n    lc.warn?.('Unknown message', buffer[0]);\n    return null;\n  }\n  const lsn = buffer.readBigUInt64BE(1);\n  if (buffer[0] === 0x77) {\n    // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-XLOGDATA\n    // (Byte 25 is where the WAL data begins)\n    return [lsn, parser.parse(buffer.subarray(25))];\n  }\n  // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-PRIMARY-KEEPALIVE-MESSAGE\n  // (Byte 17: shouldRespond)\n  const shouldRespond = buffer.readInt8(17) !== 0;\n  return [lsn, {tag: 'keepalive', shouldRespond}];\n}\n\n// https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-STANDBY-STATUS-UPDATE\nfunction makeAck(lsn: bigint): Buffer {\n  const microNow = BigInt(Date.now() - Date.UTC(2000, 0, 1)) * BigInt(1000);\n\n  const x = Buffer.alloc(34);\n  x[0] = 'r'.charCodeAt(0);\n  x.writeBigInt64BE(lsn, 1);\n  x.writeBigInt64BE(lsn, 9);\n  x.writeBigInt64BE(lsn, 17);\n  x.writeBigInt64BE(microNow, 25);\n  return x;\n}\n"],"mappings":"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"}
+{"version":3,"file":"stream.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/logical-replication/stream.ts"],"sourcesContent":["import {\n  PG_ADMIN_SHUTDOWN,\n  PG_OBJECT_IN_USE,\n  PG_OBJECT_NOT_IN_PREREQUISITE_STATE,\n} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {defu} from 'defu';\nimport postgres, {type Options, type PostgresType} from 'postgres';\nimport {sleep} from '../../../../../../shared/src/sleep.ts';\nimport {getTypeParsers} from '../../../../db/pg-type-parser.ts';\nimport {type PostgresDB} from '../../../../types/pg.ts';\nimport {id, lit} from '../../../../types/sql.ts';\nimport {pipe, type Sink, type Source} from '../../../../types/streams.ts';\nimport {Subscription} from '../../../../types/subscription.ts';\nimport {AutoResetSignal} from '../../../change-streamer/schema/tables.ts';\nimport {fromBigInt} from '../lsn.ts';\nimport {PgoutputParser} from './pgoutput-parser.ts';\nimport type {Message} from './pgoutput.types.ts';\n\nconst DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE = 5;\n\nexport type StreamMessage = [\n  lsn: bigint,\n  Message | {tag: 'keepalive'; shouldRespond: boolean},\n];\n\n// Expose the `queued` variable of the Subscription to allow\n// the change-source to determine if there are more messages\n// immediately available.\ntype SourceWithPendingQueue<T> = Source<T> & {\n  queued: number;\n};\n\nexport async function subscribe(\n  lc: LogContext,\n  db: PostgresDB,\n  slot: string,\n  publications: string[],\n  lsn: bigint,\n  retriesIfReplicationSlotActive = DEFAULT_RETRIES_IF_REPLICATION_SLOT_ACTIVE,\n  applicationName = 'zero-replicator',\n  inboundTimeoutOverrideMs?: number | undefined,\n): Promise<{\n  messages: SourceWithPendingQueue<StreamMessage>;\n  acks: Sink<bigint>;\n}> {\n  const session = postgres(\n    defu(\n      {\n        max: 1,\n        ['fetch_types']: false, // Necessary for the streaming protocol\n        ['idle_timeout']: null,\n        ['max_lifetime']: null as unknown as number,\n        connection: {\n          ['application_name']: applicationName,\n          replication: 'database', // https://www.postgresql.org/docs/current/protocol-replication.html\n        },\n      },\n      // ParsedOptions are technically compatible with Options, but happen\n      // to not be typed that way. The postgres.js author does an equivalent\n      // merge of ParsedOptions and Options here:\n      // https://github.com/porsager/postgres/blob/089214e85c23c90cf142d47fb30bd03f42874984/src/subscribe.js#L13\n      db.options as unknown as Options<Record<string, PostgresType>>,\n    ),\n  );\n\n  // Postgres will send keepalives before timing out a wal_sender. It is possible that\n  // these keepalives are not received if there is back-pressure in the replication\n  // stream. To keep the connection alive, explicitly send keepalives if none have been\n  // sent within the last 75% of the wal_sender_timeout.\n  //\n  // https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT\n  const [{walSenderTimeoutMs}] = await session<\n    {walSenderTimeoutMs: number}[]\n  >`SELECT EXTRACT(EPOCH FROM (setting || unit)::interval) * 1000 \n        AS \"walSenderTimeoutMs\" FROM pg_settings\n        WHERE name = 'wal_sender_timeout'`.simple();\n  const {\n    enabled: livenessEnabled,\n    manualKeepaliveTimeout,\n    inboundTimeoutMs,\n    timerIntervalMs,\n  } = computeLivenessTimings(walSenderTimeoutMs, inboundTimeoutOverrideMs);\n  lc.info?.(\n    livenessEnabled\n      ? `wal_sender_timeout: ${walSenderTimeoutMs}ms. ` +\n          `Ensuring manual keepalives at least every ${manualKeepaliveTimeout}ms. ` +\n          `Inbound timeout: ${inboundTimeoutMs}ms` +\n          (inboundTimeoutMs === walSenderTimeoutMs * 2\n            ? ''\n            : ' (configured override)')\n      : `wal_sender_timeout is disabled (0); skipping manual keepalives and ` +\n          `inbound liveness detection.`,\n  );\n\n  const [readable, writable] = await startReplicationStream(\n    lc,\n    session,\n    slot,\n    publications,\n    lsn,\n    retriesIfReplicationSlotActive + 1,\n  );\n\n  let lastAckTime = Date.now();\n  function sendAck(lsn: bigint) {\n    writable.write(makeAck(lsn));\n    lastAckTime = Date.now();\n  }\n\n  // Tear down the readable to force a reconnect if the inbound half of the\n  // connection goes silent (our outbound acks keep flowing into the void,\n  // neither side errors, and the change-source would otherwise sit there\n  // forever). See computeLivenessTimings for the derivation of these\n  // thresholds — and why the whole timer is disabled when wal_sender_timeout\n  // is 0.\n  let lastReceivedTime = Date.now();\n\n  const livenessTimer = livenessEnabled\n    ? setInterval(() => {\n        const now = Date.now();\n        if (now - lastAckTime > manualKeepaliveTimeout) {\n          sendAck(0n);\n          lc.debug?.(`sent manual keepalive`);\n        }\n        const sinceLastReceived = now - lastReceivedTime;\n        const {resetWindow, timedOut} = evaluateInboundLiveness({\n          sinceLastReceived,\n          inboundTimeoutMs,\n          queued: messages.queued,\n        });\n        if (resetWindow) {\n          // Downstream back-pressure is preventing us from consuming (and thus\n          // receiving) upstream messages. Keep the inbound window fresh so that\n          // when the backlog finally drains we grant a full inboundTimeoutMs\n          // before concluding the connection is dead — otherwise a long stall\n          // would leave lastReceivedTime stale and fire this watchdog on the\n          // first post-drain tick, tearing down a healthy connection.\n          lastReceivedTime = now;\n        } else if (timedOut && !readable.destroyed) {\n          lc.warn?.(\n            `no message received from ${db.options.host} in ${sinceLastReceived}ms ` +\n              `(> inbound timeout ${inboundTimeoutMs}ms). Destroying ` +\n              `replication stream to force reconnect.`,\n          );\n          readable.destroy(\n            new Error(\n              `replication stream inbound timeout after ${sinceLastReceived}ms`,\n            ),\n          );\n        }\n      }, timerIntervalMs)\n    : undefined;\n\n  let destroyed = false;\n  const typeParsers = await getTypeParsers(db, {returnJsonAsString: true});\n  const parser = new PgoutputParser(typeParsers);\n  const messages = Subscription.create<StreamMessage>({\n    cleanup: () => {\n      destroyed = true;\n      readable.destroyed || readable.destroy();\n      clearInterval(livenessTimer);\n      return session.end();\n    },\n  });\n\n  readable.once(\n    'close',\n    () =>\n      // Only log a warning if the stream was not manually closed.\n      destroyed || lc.warn?.(`replication stream closed by ${db.options.host}`),\n  );\n  readable.once(\n    'error',\n    e =>\n      // Don't log the shutdown signal. This is the expected way for upstream\n      // to close the connection (and will be logged downstream).\n      (e instanceof postgres.PostgresError && e.code === PG_ADMIN_SHUTDOWN) ||\n      lc.warn?.(`error from ${db.options.host}`, e),\n  );\n\n  pipe({\n    source: readable,\n    sink: messages,\n    parse: buffer => {\n      lastReceivedTime = Date.now();\n      return parseStreamMessage(lc, buffer, parser);\n    },\n    // Allow a small buffer of messages to be queued in the subscription so\n    // that the change-source loop can check the queue to determine if more\n    // messages are immediately available.\n    bufferMessages: 5,\n  });\n\n  return {\n    messages,\n    acks: {push: sendAck},\n  };\n}\n\n/**\n * Derives the timings for the replication liveness timer from the server's\n * `wal_sender_timeout` (in milliseconds).\n *\n * Postgres treats `wal_sender_timeout = 0` as \"disabled\": it will neither\n * terminate an idle wal sender nor emit the periodic keepalives it otherwise\n * sends at roughly `wal_sender_timeout / 2`. Every timing below is derived from\n * that interval, so a disabled timeout disables the liveness machinery entirely\n * (`enabled: false`). Otherwise the derived thresholds would all collapse to 0,\n * inverting the intended meaning: the inbound watchdog would fire on the very\n * first tick and destroy the stream, while the timer itself would busy-spin at\n * a 0ms interval — together producing a continuous reconnect storm.\n *\n * An `inboundTimeoutOverrideMs` (when positive) replaces the default\n * `2x wal_sender_timeout` inbound threshold. The two timeouts protect\n * different parties with asymmetric false-positive costs: `wal_sender_timeout`\n * is the server reaping dead clients (a false positive there costs a cheap\n * reconnect), while the inbound watchdog tears down the stream and replays the\n * in-flight transaction — expensive, and self-defeating when the wal sender is\n * legitimately silent for long stretches (e.g. decoding through WAL from\n * unpublished tables, or assembling a large transaction that pgoutput only\n * sends at commit). Operators who don't own the server setting (e.g. managed\n * or operator-provisioned Postgres with an aggressive cluster-wide\n * `wal_sender_timeout`) can widen the client-side fuse independently.\n *\n * The override has no effect when `wal_sender_timeout` is disabled (0): the\n * server then sends no periodic keepalives, so inbound silence is normal even\n * on an idle healthy connection and any silence-based watchdog would\n * false-positive.\n *\n * https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT\n */\nexport function computeLivenessTimings(\n  walSenderTimeoutMs: number,\n  inboundTimeoutOverrideMs?: number | undefined,\n): {\n  enabled: boolean;\n  manualKeepaliveTimeout: number;\n  inboundTimeoutMs: number;\n  timerIntervalMs: number;\n} {\n  // Guard with `!(x > 0)` so that 0, negative, and NaN values all disable the\n  // timer rather than producing degenerate (zero / NaN) thresholds.\n  if (!(walSenderTimeoutMs > 0)) {\n    return {\n      enabled: false,\n      manualKeepaliveTimeout: 0,\n      inboundTimeoutMs: 0,\n      timerIntervalMs: 0,\n    };\n  }\n  // Send a manual keepalive if nothing has been sent in the last 75% of the\n  // wal_sender_timeout, so Postgres never times us out under back-pressure.\n  const manualKeepaliveTimeout = Math.floor(walSenderTimeoutMs * 0.75);\n  return {\n    enabled: true,\n    manualKeepaliveTimeout,\n    // Force a reconnect after 2x wal_sender_timeout — i.e. two consecutive\n    // missed keepalives — without any inbound message, to avoid spurious\n    // reconnects from a single delayed keepalive (PG scheduling jitter under\n    // load, our own event-loop stalls, etc.). A 0 / negative / NaN override\n    // falls back to the default rather than degenerating the threshold.\n    inboundTimeoutMs:\n      inboundTimeoutOverrideMs !== undefined && inboundTimeoutOverrideMs > 0\n        ? inboundTimeoutOverrideMs\n        : walSenderTimeoutMs * 2,\n    // Poll at 1/5th of the manual keepalive interval.\n    timerIntervalMs: manualKeepaliveTimeout / 5,\n  };\n}\n\n/**\n * Pure decision for the inbound-liveness watchdog, given the time since the\n * last inbound message, the timeout threshold, and the number of messages\n * currently queued downstream (see {@link SourceWithPendingQueue.queued}).\n *\n * A non-empty downstream queue means we have received data we haven't yet\n * consumed: the reason we aren't receiving *more* is our own back-pressure, not\n * upstream silence. In that case we `resetWindow` (treat the backlog as\n * liveness evidence) rather than counting the stall against the connection.\n * This both suppresses false timeouts during back-pressure and — crucially —\n * keeps `lastReceivedTime` fresh so the drain transition (queue emptying after\n * a long stall) doesn't fire the watchdog against a stale timestamp on the very\n * next tick.\n *\n * Only when the queue is empty (consumption has caught up, so reading — and\n * thus keepalives — should be flowing again) does an over-threshold gap\n * indicate a genuinely dead inbound half.\n */\nexport function evaluateInboundLiveness({\n  sinceLastReceived,\n  inboundTimeoutMs,\n  queued,\n}: {\n  sinceLastReceived: number;\n  inboundTimeoutMs: number;\n  queued: number;\n}): {resetWindow: boolean; timedOut: boolean} {\n  if (queued > 0) {\n    return {resetWindow: true, timedOut: false};\n  }\n  return {resetWindow: false, timedOut: sinceLastReceived > inboundTimeoutMs};\n}\n\n/**\n * Formats publication names for the START_REPLICATION command.\n * The replication protocol expects format: publication_names 'pub1,pub2'\n * Each name is escaped to handle any quotes that may have passed validation.\n */\nfunction formatPublicationNames(publications: string[]): string {\n  // lit() returns 'escaped_name' with surrounding quotes\n  // We strip the quotes since the outer quotes are in the template\n  return publications.map(p => lit(p).slice(1, -1)).join(',');\n}\n\nasync function startReplicationStream(\n  lc: LogContext,\n  session: postgres.Sql,\n  slot: string,\n  publications: string[],\n  lsn: bigint,\n  maxAttempts: number,\n) {\n  for (let i = 0; i < maxAttempts; i++) {\n    try {\n      const stream = session\n        .unsafe(\n          `START_REPLICATION SLOT ${id(slot)} LOGICAL ${fromBigInt(lsn)} (\n        proto_version '1',\n        publication_names '${formatPublicationNames(publications)}',\n        messages 'true'\n      )`,\n        )\n        .execute();\n      return await Promise.all([stream.readable(), stream.writable()]);\n    } catch (e) {\n      if (e instanceof postgres.PostgresError) {\n        // error: replication slot \"zero_slot_change_source_test_id\" is active for PID 268\n        if (e.code === PG_OBJECT_IN_USE) {\n          // The freeing up of the replication slot is not transactional;\n          // sometimes it takes time for Postgres to consider the slot\n          // inactive.\n          lc.warn?.(`attempt ${i + 1}: ${String(e)}`, e);\n          await sleep(10);\n          continue;\n        }\n        // error: This slot has been invalidated because it exceeded the maximum reserved size.\n        // (This is a different manifestation of a slot being invalidated when\n        //  the wal exceeds the max_slot_wal_keep_size)\n        if (e.code === PG_OBJECT_NOT_IN_PREREQUISITE_STATE) {\n          lc.error?.(`error starting replication stream`, e);\n          throw new AutoResetSignal(`unable to start replication stream`, {\n            cause: e,\n          });\n        }\n      }\n      throw e;\n    }\n  }\n  throw new Error(\n    `exceeded max attempts (${maxAttempts}) to start the Postgres stream`,\n  );\n}\n\nfunction parseStreamMessage(\n  lc: LogContext,\n  buffer: Buffer,\n  parser: PgoutputParser,\n): StreamMessage | null {\n  // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-START-REPLICATION\n  if (buffer[0] !== 0x77 && buffer[0] !== 0x6b) {\n    lc.warn?.('Unknown message', buffer[0]);\n    return null;\n  }\n  const lsn = buffer.readBigUInt64BE(1);\n  if (buffer[0] === 0x77) {\n    // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-XLOGDATA\n    // (Byte 25 is where the WAL data begins)\n    return [lsn, parser.parse(buffer.subarray(25))];\n  }\n  // https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-PRIMARY-KEEPALIVE-MESSAGE\n  // (Byte 17: shouldRespond)\n  const shouldRespond = buffer.readInt8(17) !== 0;\n  return [lsn, {tag: 'keepalive', shouldRespond}];\n}\n\n// https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION-STANDBY-STATUS-UPDATE\nfunction makeAck(lsn: bigint): Buffer {\n  const microNow = BigInt(Date.now() - Date.UTC(2000, 0, 1)) * BigInt(1000);\n\n  const x = Buffer.alloc(34);\n  x[0] = 'r'.charCodeAt(0);\n  x.writeBigInt64BE(lsn, 1);\n  x.writeBigInt64BE(lsn, 9);\n  x.writeBigInt64BE(lsn, 17);\n  x.writeBigInt64BE(microNow, 25);\n  return x;\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/change-source/pg/schema/ddl.d.ts

@@ -5,57 +5,24 @@ export declare const ddlEventSchema: v.ObjectType<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
-    schema: v.Type<{
-        indexes: {
-            isReplicaIdentity?: boolean | undefined;
-            isPrimaryKey?: boolean | undefined;
-            isImmediate?: boolean | undefined;
-            name: string;
-            columns: Record<string, "ASC" | "DESC">;
-            schema: string;
-            tableName: string;
-            unique: boolean;
-        }[];
-        tables: {
-            replicaIdentityColumns: string[];
-            primaryKey?: string[] | undefined;
-            schemaOID?: number | undefined;
-            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
-            name: string;
-            schema: string;
-            oid: number;
-            columns: Record<string, {
-                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
-                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
-                characterMaximumLength?: number | null | undefined;
-                notNull?: boolean | null | undefined;
-                dflt?: string | null | undefined;
-                pos: number;
-                dataType: string;
-                typeOID: number;
-            }>;
-            publications: Record<string, {
-                rowFilter: string | null;
-            }>;
-        }[];
-    }>;
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
     newColumns: v.Optional<Record<string, number[]> | null>;
 }, undefined>;
 /**
- * A {@link DdlStartEvent} message is emitted before every DDL event, containing
- * the current `schema` and the command `tag`.
+ * A {@link DdlStartEvent} message is emitted before every DDL event,
+ * containing the command `tag`.
  *
  * In most cases, the `DdlStartEvent` itself will not be associated with a
- * schema change, in which case `previousSchema` will be `null`. However, the
- * message is still emitted, both for backwards compatibility and to provide
- * the command `tag` context in case an immediately following `DdlStartEvent`
- * tag is emitted with a schema change (which can happen when another event
- * trigger results in a nested ddl statement).
+ * schema change, in which case the event is context-only (in protocol v2,
+ * planned, both `previousSchema` and `schema` will be absent; in v1,
+ * `schema` is set and `previousSchema` is `null`). The message is still
+ * emitted to provide the command `tag` context in case an immediately
+ * following `DdlStartEvent` tag is emitted with a schema change (which can
+ * happen when another event trigger results in a nested ddl statement).
  *
  * In such cases, the `previousSchema` and `schema` fields of the latter event
  * are used to determine the necessary schema change operations (as they are
@@ -68,9 +35,15 @@ export declare const ddlStartEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
-    schema: v.Type<{
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "event" | "previousSchema"> & {
+    type: v.Type<"ddlStart">;
+    schema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
             isPrimaryKey?: boolean | undefined;
@@ -104,12 +77,6 @@ export declare const ddlStartEventSchema: v.ObjectType<Omit<Omit<{
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "event" | "previousSchema"> & {
-    type: v.Type<"ddlStart">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -158,8 +125,14 @@ export declare const ddlUpdateEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "previousSchema"> & {
+    type: v.Type<"ddlUpdate">;
     schema: v.Type<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -194,12 +167,6 @@ export declare const ddlUpdateEventSchema: v.ObjectType<Omit<Omit<{
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "previousSchema"> & {
-    type: v.Type<"ddlUpdate">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -262,8 +229,14 @@ export declare const schemaSnapshotEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "previousSchema"> & {
+    type: v.Type<"schemaSnapshot">;
     schema: v.Type<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -298,12 +271,6 @@ export declare const schemaSnapshotEventSchema: v.ObjectType<Omit<Omit<{
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "previousSchema"> & {
-    type: v.Type<"schemaSnapshot">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -344,9 +311,15 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
-    schema: v.Type<{
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "event" | "previousSchema"> & {
+    type: v.Type<"ddlStart">;
+    schema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
             isPrimaryKey?: boolean | undefined;
@@ -380,12 +353,6 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "event" | "previousSchema"> & {
-    type: v.Type<"ddlStart">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -427,8 +394,14 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "previousSchema"> & {
+    type: v.Type<"ddlUpdate">;
     schema: v.Type<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -463,12 +436,6 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "previousSchema"> & {
-    type: v.Type<"ddlUpdate">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -507,8 +474,14 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     context: v.ObjectType<{
         query: v.Type<string>;
     }, v.Type<string>>;
-}, "schema" | "event" | "version" | "newColumns"> & {
-    version: v.Type<1>;
+}, "event" | "version" | "newColumns"> & {
+    version: v.Type<1 | 2>;
+    event: v.ObjectType<{
+        tag: v.Type<string>;
+    }, undefined>;
+    newColumns: v.Optional<Record<string, number[]> | null>;
+}, "type" | "schema" | "previousSchema"> & {
+    type: v.Type<"schemaSnapshot">;
     schema: v.Type<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;
@@ -543,12 +516,6 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
             }>;
         }[];
     }>;
-    event: v.ObjectType<{
-        tag: v.Type<string>;
-    }, undefined>;
-    newColumns: v.Optional<Record<string, number[]> | null>;
-}, "type" | "previousSchema"> & {
-    type: v.Type<"schemaSnapshot">;
     previousSchema: v.Optional<{
         indexes: {
             isReplicaIdentity?: boolean | undefined;

package/out/zero-cache/src/services/change-source/pg/schema/ddl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/ddl.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,wCAAwC,CAAC;AAC5D,OAAO,EAAiB,KAAK,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAU7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAQlC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAiBzB,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAc9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAQ/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAGpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAYtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,WAAW,UAwM/D;AAGD,eAAO,MAAM,IAAI,2HAQP,CAAC;AAEX,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,UAoC9D;AAGD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,UAMzB"}
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/ddl.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,wCAAwC,CAAC;AAC5D,OAAO,EAAiB,KAAK,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAU7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAkBlC,eAAO,MAAM,cAAc;;;;;;;;;;aAgBzB,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAc9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAU/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAIpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAYtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,WAAW,UAwM/D;AAGD,eAAO,MAAM,IAAI,2HAQP,CAAC;AAEX,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,UAoC9D;AAGD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,UAMzB"}

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

@@ -1,25 +1,26 @@
 import { assert } from "../../../../../../shared/src/asserts.js";
-import { valita_exports } from "../../../../../../shared/src/valita.js";
+import { literalUnion, valita_exports } from "../../../../../../shared/src/valita.js";
 import { upstreamSchema } from "../../../../types/shards.js";
 import { id } from "../../../../types/sql.js";
 import { publishedSchema, publishedSchemaQuery } from "./published.js";
 import { literal } from "pg-format";
+var versionSchema = literalUnion(1, 2);
 var ddlEventSchema = valita_exports.object({ context: valita_exports.object({ query: valita_exports.string() }).rest(valita_exports.string()) }).extend({
-	version: valita_exports.literal(1),
-	schema: publishedSchema,
+	version: versionSchema,
 	event: valita_exports.object({ tag: valita_exports.string() }),
 	newColumns: valita_exports.record(valita_exports.array(valita_exports.number())).nullable().optional()
 });
 /**
-* A {@link DdlStartEvent} message is emitted before every DDL event, containing
-* the current `schema` and the command `tag`.
+* A {@link DdlStartEvent} message is emitted before every DDL event,
+* containing the command `tag`.
 *
 * In most cases, the `DdlStartEvent` itself will not be associated with a
-* schema change, in which case `previousSchema` will be `null`. However, the
-* message is still emitted, both for backwards compatibility and to provide
-* the command `tag` context in case an immediately following `DdlStartEvent`
-* tag is emitted with a schema change (which can happen when another event
-* trigger results in a nested ddl statement).
+* schema change, in which case the event is context-only (in protocol v2,
+* planned, both `previousSchema` and `schema` will be absent; in v1,
+* `schema` is set and `previousSchema` is `null`). The message is still
+* emitted to provide the command `tag` context in case an immediately
+* following `DdlStartEvent` tag is emitted with a schema change (which can
+* happen when another event trigger results in a nested ddl statement).
 *
 * In such cases, the `previousSchema` and `schema` fields of the latter event
 * are used to determine the necessary schema change operations (as they are
@@ -30,6 +31,7 @@ var ddlEventSchema = valita_exports.object({ context: valita_exports.object({ qu
 */
 var ddlStartEventSchema = ddlEventSchema.extend({
 	type: valita_exports.literal("ddlStart"),
+	schema: publishedSchema.optional(),
 	previousSchema: publishedSchema.nullable().optional(),
 	event: valita_exports.object({ tag: valita_exports.string() }).optional(() => ({ tag: "UNKNOWN" }))
 });
@@ -40,6 +42,7 @@ var ddlStartEventSchema = ddlEventSchema.extend({
 */
 var ddlUpdateEventSchema = ddlEventSchema.extend({
 	type: valita_exports.literal("ddlUpdate"),
+	schema: publishedSchema,
 	previousSchema: publishedSchema.optional()
 });
 /**
@@ -66,6 +69,7 @@ var ddlUpdateEventSchema = ddlEventSchema.extend({
 */
 var schemaSnapshotEventSchema = ddlEventSchema.extend({
 	type: valita_exports.literal("schemaSnapshot"),
+	schema: publishedSchema,
 	previousSchema: publishedSchema.optional()
 });
 var replicationEventSchema = valita_exports.union(ddlStartEventSchema, ddlUpdateEventSchema, schemaSnapshotEventSchema);
@@ -175,7 +179,7 @@ BEGIN
 
   PERFORM pg_logical_emit_message(true, '${appID}/${shardNum}/ddl', message);
 
-  RAISE NOTICE 'Emitted ${appID}_${shardNum} % for % %', event_type, tag, 
+  RAISE NOTICE 'Emitted ${appID}_${shardNum} % for % %', event_type, tag,
     COALESCE(row_to_json(target)::text, '');
 END
 $$ LANGUAGE plpgsql;