@powersync/service-module-mysql 0.15.0 → 0.16.1

package/src/replication/BinLogStream.ts

@@ -73,10 +73,14 @@ export class BinLogStream {
 
   private readonly logger: Logger;
 
+  private activeServerUuid: string | null = null;
+
   private tableCache = new Map<string | number, storage.SourceTable[]>();
 
   private replicationLag = new ReplicationLagTracker();
 
+  private binLogListener: BinLogListener | null = null;
+
   constructor(private options: BinLogStreamOptions) {
     this.logger = options.logger ?? defaultLogger;
     this.storage = options.storage;
@@ -220,16 +224,23 @@ export class BinLogStream {
       this.logger.info(`Initial replication already done.`);
 
       if (lastKnowGTID) {
-        // Check if the specific binlog file is still available. If it isn't, we need to snapshot again.
         const connection = await this.connections.getConnection();
         try {
-          const isAvailable = await common.isBinlogStillAvailable(connection, lastKnowGTID.position.filename);
+          // Check if the active server uuid matches the one in the GTID
+          if (this.activeServerUuid !== lastKnowGTID.serverUuid) {
+            this.logger.info(
+              `The source server uuid has changed. Active server uuid ${this.activeServerUuid} does not match the server uuid from the resume checkpoint: ${lastKnowGTID.serverUuid}, re-snapshotting to ensure consistency.`
+            );
+            return false;
+          }
+
+          const isAvailable = await common.isGtidPositionStillAvailable(connection, lastKnowGTID);
           if (!isAvailable) {
             this.logger.info(
-              `BinLog file ${lastKnowGTID.position.filename} is no longer available, starting initial replication again.`
+              `Resume GTID ${lastKnowGTID.raw} at ${lastKnowGTID.position.filename}:${lastKnowGTID.position.offset} is no longer present in the executed GTID history or available BinLogs, re-snapshotting to ensure consistency.`
             );
+            return false;
           }
-          return isAvailable;
         } finally {
           connection.release();
         }
@@ -267,9 +278,10 @@ export class BinLogStream {
       const flushResults = await this.storage.startBatch(
         {
           logger: this.logger,
-          zeroLSN: common.ReplicatedGTID.ZERO.comparable,
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
           defaultSchema: this.defaultSchema,
-          storeCurrentData: false
+          storeCurrentData: false,
+          signal: this.abortSignal
         },
         async (batch) => {
           for (let tablePattern of sourceTables) {
@@ -296,8 +308,8 @@ export class BinLogStream {
     }
 
     if (lastOp != null) {
-      // Populate the cache _after_ initial replication, but _before_ we switch to this replication stream.
-      await this.storage.populatePersistentChecksumCache({
+      // Compact storage _after_ initial replication, but _before_ we switch to this replication stream.
+      await this.storage.compactInitialReplication({
         // No checkpoint yet, but we do have the opId.
         maxOpId: lastOp,
         signal: this.abortSignal
@@ -363,7 +375,19 @@ export class BinLogStream {
     }
   }
 
+  private async ensureActiveServerUuid() {
+    if (this.activeServerUuid == null) {
+      const connection = await this.connections.getConnection();
+      try {
+        this.activeServerUuid = await common.readServerUuid(connection);
+      } finally {
+        connection.release();
+      }
+    }
+  }
+
   async initReplication() {
+    await this.ensureActiveServerUuid();
     const connection = await this.connections.getConnection();
     const errors = await common.checkSourceConfiguration(connection);
     connection.release();
@@ -382,9 +406,10 @@ export class BinLogStream {
       await this.storage.startBatch(
         {
           logger: this.logger,
-          zeroLSN: common.ReplicatedGTID.ZERO.comparable,
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
           defaultSchema: this.defaultSchema,
-          storeCurrentData: false
+          storeCurrentData: false,
+          signal: this.abortSignal
         },
         async (batch) => {
           for (let tablePattern of sourceTables) {
@@ -406,21 +431,31 @@ export class BinLogStream {
   }
 
   async streamChanges() {
+    await this.ensureActiveServerUuid();
     const serverId = createRandomServerId(this.storage.replicationStreamId);
 
     const connection = await this.connections.getConnection();
-    const { resumeLsn: resume_lsn } = await this.storage.getStatus();
-    if (resume_lsn) {
-      this.logger.info(`Existing resume LSN found: ${resume_lsn}`);
+    let fromGTID: common.ReplicatedGTID;
+    try {
+      const { resumeLsn: resume_lsn } = await this.storage.getStatus();
+      if (resume_lsn) {
+        this.logger.info(`Existing resume LSN found: ${resume_lsn}`);
+      }
+      fromGTID = resume_lsn
+        ? common.ReplicatedGTID.fromSerialized(resume_lsn)
+        : await common.readExecutedGtid(connection);
+    } finally {
+      connection.release();
     }
-    const fromGTID = resume_lsn
-      ? common.ReplicatedGTID.fromSerialized(resume_lsn)
-      : await common.readExecutedGtid(connection);
-    connection.release();
 
     if (!this.stopped) {
       await this.storage.startBatch(
-        { zeroLSN: common.ReplicatedGTID.ZERO.comparable, defaultSchema: this.defaultSchema, storeCurrentData: false },
+        {
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
+          defaultSchema: this.defaultSchema,
+          storeCurrentData: false,
+          signal: this.abortSignal
+        },
         async (batch) => {
           const binlogEventHandler = this.createBinlogEventHandler(batch);
           const binlogListener = new BinLogListener({
@@ -429,8 +464,10 @@ export class BinLogStream {
             startGTID: fromGTID,
             connectionManager: this.connections,
             serverId: serverId,
+            activeServerUuid: this.activeServerUuid!,
             eventHandler: binlogEventHandler
           });
+          this.binLogListener = binlogListener;
 
           this.abortSignal.addEventListener(
             'abort',
@@ -666,6 +703,14 @@ export class BinLogStream {
     return this.replicationLag.getLagMillis();
   }
 
+  /**
+   * Probe the liveness of the BinLog Listener's control connection. Called from the replication
+   * job's keepAlive. Does nothing before streaming starts (during the initial snapshot).
+   */
+  probeControlConnection(): void {
+    this.binLogListener?.probeControlConnection();
+  }
+
   async tryRollback(promiseConnection: mysqlPromise.Connection) {
     try {
       await promiseConnection.query('ROLLBACK');

package/src/replication/MySQLConnectionManager.ts

@@ -49,11 +49,17 @@ export class MySQLConnectionManager extends BaseObserver<MySQLConnectionManagerL
    * Create a new replication listener
    */
   createBinlogListener(): ZongJi {
+    // These options apply to both the binlog connection and the control connection Zongji creates.
     const listener = new ZongJi({
       host: this.options.hostname,
       port: this.options.port,
       user: this.options.username,
       password: this.options.password,
+      // TCP keepalive is disabled by default in @vlasky/mysql. Without it, the idle control
+      // connection can be silently dropped by stateful firewalls, freezing replication on the
+      // next table metadata query until the TCP retransmission timeout (~950s).
+      enableKeepAlive: true,
+      keepAliveInitialDelay: mysql_utils.TCP_KEEPALIVE_INITIAL_DELAY,
       // We want to avoid parsing date/time values to Date, because that drops sub-millisecond precision.
       dateStrings: true,
       timeZone: 'Z'

package/src/replication/zongji/BinLogListener.ts

@@ -1,4 +1,4 @@
-import { Logger, logger as defaultLogger } from '@powersync/lib-services-framework';
+import { Logger, ReplicationAssertionError, logger as defaultLogger } from '@powersync/lib-services-framework';
 import { BinLogEvent, BinLogQueryEvent, StartOptions, TableMapEntry, ZongJi } from '@powersync/mysql-zongji';
 import { TablePattern } from '@powersync/service-sync-rules';
 import async from 'async';
@@ -33,6 +33,19 @@ const { Parser } = pkg;
  *  Seconds of inactivity after which a keepalive event is sent by the MySQL server.
  */
 export const KEEPALIVE_INACTIVITY_THRESHOLD = 30;
+
+/**
+ *  Maximum time in milliseconds to wait for Zongji to stop before force-closing its control connection.
+ */
+export const ZONGJI_STOP_TIMEOUT = 5_000;
+
+/**
+ *  Maximum time in milliseconds a control connection liveness probe may execute before the
+ *  connection is considered dead. Time the probe spends queued behind other control queries
+ *  does not count towards this.
+ */
+export const CTRL_CONNECTION_PROBE_TIMEOUT = 5_000;
+
 export type Row = Record<string, any>;
 
 /**
@@ -76,10 +89,18 @@ export interface BinLogListenerOptions {
   connectionManager: MySQLConnectionManager;
   eventHandler: BinLogEventHandler;
   sourceTables: TablePattern[];
+  /**
+   *  Id that identifies this replication client.
+   */
   serverId: number;
+  /**
+   *  The server uuid of the source MySQL server that is being replicated.
+   */
+  activeServerUuid: string;
   startGTID: common.ReplicatedGTID;
   logger?: Logger;
   keepAliveInactivitySeconds?: number;
+  ctrlConnectionProbeTimeoutMs?: number;
 }
 
 /**
@@ -88,8 +109,6 @@ export interface BinLogListenerOptions {
  */
 export class BinLogListener {
   private sqlParser: ParserType;
-  private connectionManager: MySQLConnectionManager;
-  private eventHandler: BinLogEventHandler;
   private binLogPosition: common.BinLogPosition;
   private currentGTID: common.ReplicatedGTID;
   private logger: Logger;
@@ -99,8 +118,12 @@ export class BinLogListener {
   private isStopped: boolean = false;
   private isStopping: boolean = false;
 
+  // Set while a control connection probe is awaiting a response, so repeated probes do not pile up behind it.
+  private probePending: boolean = false;
+
   // Flag to indicate if are currently in a transaction that involves multiple row mutation events.
   private isTransactionOpen = false;
+
   zongji: ZongJi;
   processingQueue: async.QueueObject<BinLogEvent>;
 
@@ -111,9 +134,8 @@ export class BinLogListener {
 
   constructor(public options: BinLogListenerOptions) {
     this.logger = options.logger ?? defaultLogger;
-    this.connectionManager = options.connectionManager;
-    this.eventHandler = options.eventHandler;
-    this.binLogPosition = options.startGTID.position;
+    // Copy the position: the listener mutates it as events are processed, and the caller's startGTID must not change
+    this.binLogPosition = { ...options.startGTID.position };
     this.currentGTID = options.startGTID;
     this.sqlParser = new Parser();
     this.processingQueue = this.createProcessingQueue();
@@ -122,6 +144,18 @@ export class BinLogListener {
     this.databaseFilter = this.createDatabaseFilter(options.sourceTables);
   }
 
+  private get connectionManager(): MySQLConnectionManager {
+    return this.options.connectionManager;
+  }
+
+  private get eventHandler(): BinLogEventHandler {
+    return this.options.eventHandler;
+  }
+
+  private get activeServerUuid(): string {
+    return this.options.activeServerUuid;
+  }
+
   /**
    *  The queue memory limit in bytes as defined in the connection options.
    *  @private
@@ -205,12 +239,29 @@ export class BinLogListener {
   private async stopZongji(): Promise<void> {
     if (!this.zongji.stopped) {
       this.logger.info('Stopping BinLog Listener...');
-      await new Promise<void>((resolve) => {
+      const controlConnection = this.zongji.ctrlConnection;
+      let stopped = false;
+      const stopPromise = new Promise<void>((resolve) => {
         this.zongji.once('stopped', () => {
+          stopped = true;
           resolve();
         });
         this.zongji.stop();
       });
+      // Zongji only emits 'stopped' once the KILL query on its control connection has completed.
+      // If that connection has been dead for a while, the query can block on TCP retransmissions
+      // for many minutes, so we destroy the socket after a timeout to unblock the stop.
+      const timeout = timers.setTimeout(ZONGJI_STOP_TIMEOUT, undefined, { ref: false }).then(() => {
+        if (!stopped) {
+          this.logger.warn('Timed out waiting for the BinLog Listener to stop. Closing the control connection.');
+          controlConnection._socket?.destroy();
+        }
+      });
+      await Promise.race([stopPromise, timeout]);
+      // Zongji destroys the control connection when it stops, which drops pending query callbacks:
+      // a probe waiting on this connection would otherwise stay pending forever and disable
+      // probing after a restart.
+      this.probePending = false;
       this.logger.info('BinLog Listener stopped.');
     }
   }
@@ -236,6 +287,41 @@ export class BinLogListener {
     }
   }
 
+  /**
+   *  The binlog connection is kept alive by the MySQL server heartbeat, but the control connection
+   *  carries no traffic between metadata queries. TCP keepalive stops it from being dropped when idle,
+   *  but detects an already dead connection slowly, so the replication job's keepAlive additionally
+   *  probes it with a lightweight query and stops the listener (restarting replication) if the probe
+   *  does not respond in time.
+   *
+   *  The driver starts the query timeout when the query begins executing, not when it is queued, so a
+   *  probe waiting behind a legitimately slow metadata query does not produce a false failure. A probe
+   *  queued on a dead socket is failed together with the queued query by TCP keepalive on the socket.
+   */
+  public probeControlConnection(): void {
+    if (this.probePending || this.zongji.stopped || this.isStopped || this.isStopping) {
+      return;
+    }
+    this.probePending = true;
+    const controlConnection = this.zongji.ctrlConnection;
+    const timeout = this.options.ctrlConnectionProbeTimeoutMs ?? CTRL_CONNECTION_PROBE_TIMEOUT;
+    controlConnection.query({ sql: 'SELECT 1', timeout }, (error) => {
+      this.probePending = false;
+      // Only act if the probe failed on a connection that is still supposed to be alive.
+      if (
+        error != null &&
+        this.zongji.ctrlConnection === controlConnection &&
+        !this.zongji.stopped &&
+        !(this.isStopped || this.isStopping)
+      ) {
+        this.logger.warn('MySQL control connection is unresponsive. Stopping the BinLog Listener...');
+        this.listenerError = new Error('MySQL control connection is unresponsive.');
+        controlConnection._socket?.destroy();
+        this.stop();
+      }
+    });
+  }
+
   private createProcessingQueue(): async.QueueObject<BinLogEvent> {
     const queue = async.queue(this.createQueueWorker(), 1);
 
@@ -292,29 +378,41 @@ export class BinLogListener {
     return async (evt: BinLogEvent) => {
       switch (true) {
         case zongji_utils.eventIsGTIDLog(evt):
-          this.currentGTID = common.ReplicatedGTID.fromBinLogEvent({
-            raw_gtid: {
-              server_id: evt.serverId,
-              transaction_range: evt.transactionRange
+          const transactionGTID = common.ReplicatedGTID.fromBinLogEvent({
+            rawGtid: {
+              serverUuid: evt.serverId, // The server uuid this transaction originated from
+              transactionId: evt.transactionRange
             },
             position: {
               filename: this.binLogPosition.filename,
               offset: evt.nextPosition
             }
           });
+
+          if (transactionGTID.serverUuid !== this.activeServerUuid) {
+            throw new ReplicationAssertionError(
+              `Detected a transaction from a different MySQL server UUID: ${transactionGTID.serverUuid} than the server that is currently being replicated from: ${this.activeServerUuid}. ` +
+                `A re-snapshot is required to ensure consistency.`
+            );
+          }
+
+          this.currentGTID = transactionGTID;
           this.binLogPosition.offset = evt.nextPosition;
+
           await this.eventHandler.onTransactionStart({ timestamp: new Date(evt.timestamp) });
           this.logger.info(`Processed GTID event: ${this.currentGTID.comparable}`);
           break;
         case zongji_utils.eventIsRotation(evt):
           // The first event when starting replication is a synthetic Rotate event
-          // It describes the last binlog file and position that the replica client processed
+          // It describes the the position and file that the replica requested to start from
+          const isNewFile = this.binLogPosition.filename !== evt.binlogName;
+
           this.binLogPosition.filename = evt.binlogName;
-          this.binLogPosition.offset = evt.nextPosition !== 0 ? evt.nextPosition : evt.position;
+          this.binLogPosition.offset = evt.position;
+
           await this.eventHandler.onRotate();
 
-          const newFile = this.binLogPosition.filename !== evt.binlogName;
-          if (newFile) {
+          if (isNewFile) {
             this.logger.info(
               `Processed Rotate event. New BinLog file is: ${this.binLogPosition.filename}:${this.binLogPosition.offset}`
             );
@@ -359,11 +457,7 @@ export class BinLogListener {
           break;
         case zongji_utils.eventIsXid(evt):
           this.isTransactionOpen = false;
-          this.binLogPosition.offset = evt.nextPosition;
-          const LSN = new common.ReplicatedGTID({
-            raw_gtid: this.currentGTID.raw,
-            position: this.binLogPosition
-          }).comparable;
+          const LSN = this.advanceCommitPosition(evt.nextPosition);
           await this.eventHandler.onCommit(LSN);
           this.logger.info(`Processed Xid event - transaction complete. LSN: ${LSN}.`);
           break;
@@ -376,6 +470,21 @@ export class BinLogListener {
     };
   }
 
+  /**
+   *  Advances the binlog position to the end of a committed transaction and updates the currentGTID to match.
+   *  This ensures subsequent heartbeat keepalives report an LSN that is not behind the last commit LSN,
+   *  which would otherwise block checkpoint creation until the next transaction arrives.
+   *  Returns the commit LSN.
+   */
+  private advanceCommitPosition(nextPosition: number): string {
+    this.binLogPosition.offset = nextPosition;
+    this.currentGTID = new common.ReplicatedGTID({
+      rawGtid: this.currentGTID.raw,
+      position: { ...this.binLogPosition }
+    });
+    return this.currentGTID.comparable;
+  }
+
   private async processQueryEvent(event: BinLogQueryEvent): Promise<void> {
     const { query, nextPosition } = event;
 
@@ -398,11 +507,7 @@ export class BinLogListener {
       // DDL queries are auto commited, but do not come with a corresponding Xid event, in those cases we trigger a manual commit if we are not already in a transaction.
       // Some DDL queries include row events, and in those cases will include a Xid event.
       if (!this.isTransactionOpen) {
-        this.binLogPosition.offset = nextPosition;
-        const LSN = new common.ReplicatedGTID({
-          raw_gtid: this.currentGTID.raw,
-          position: this.binLogPosition
-        }).comparable;
+        const LSN = this.advanceCommitPosition(nextPosition);
         await this.eventHandler.onCommit(LSN);
       }
 
@@ -419,11 +524,7 @@ export class BinLogListener {
         await this.restartZongji();
       }
     } else if (!this.isTransactionOpen) {
-      this.binLogPosition.offset = nextPosition;
-      const LSN = new common.ReplicatedGTID({
-        raw_gtid: this.currentGTID.raw,
-        position: this.binLogPosition
-      }).comparable;
+      const LSN = this.advanceCommitPosition(nextPosition);
       await this.eventHandler.onCommit(LSN);
     }
   }

package/src/utils/mysql-utils.ts

@@ -12,6 +12,13 @@ export type RetriedQueryOptions = {
   retries?: number;
 };
 
+/**
+ *  TCP keepalive initial delay in milliseconds for connections to the MySQL server.
+ *  Keepalive prevents long-lived idle connections from being silently dropped by stateful
+ *  firewalls, which commonly time out idle flows after an hour.
+ */
+export const TCP_KEEPALIVE_INITIAL_DELAY = 40_000;
+
 /**
  * Retry a simple query - up to 2 attempts total.
  */
@@ -54,6 +61,10 @@ export function createPool(config: types.NormalizedMySQLConnectionConfig, option
     timezone: 'Z', // Ensure no auto timezone manipulation of the dates occur
     jsonStrings: true, // Return JSON columns as strings
     dateStrings: true, // We parse and format them ourselves
+    // mysql2 enables TCP keepalive by default, but without an initial delay the OS default of
+    // 7200 seconds applies, which is too late for common 3600 second firewall idle timeouts.
+    enableKeepAlive: true,
+    keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY,
     // Apply URL connection parameters (explicit options override these via spread below)
     ...(params.connectTimeout != null ? { connectTimeout: params.connectTimeout } : {}),
     ...(params.connectionLimit != null ? { connectionLimit: params.connectionLimit } : {}),

package/test/src/BinLogListener.test.ts

@@ -1,6 +1,12 @@
 import { MySQLConnectionManager } from '@module/replication/MySQLConnectionManager.js';
 import { BinLogListener, SchemaChange, SchemaChangeType } from '@module/replication/zongji/BinLogListener.js';
-import { getMySQLVersion, qualifiedMySQLTable, satisfiesVersion } from '@module/utils/mysql-utils.js';
+import {
+  getMySQLVersion,
+  qualifiedMySQLTable,
+  satisfiesVersion,
+  TCP_KEEPALIVE_INITIAL_DELAY
+} from '@module/utils/mysql-utils.js';
+import { MySQLConnection } from '@powersync/mysql-zongji';
 import { TablePattern } from '@powersync/service-sync-rules';
 import crypto from 'crypto';
 import { v4 as uuid } from 'uuid';
@@ -13,6 +19,11 @@ import {
   TestBinLogEventHandler
 } from './util.js';
 
+// The zongji type definitions do not expose the connection config.
+type ConnectionWithConfig = MySQLConnection & {
+  config: { enableKeepAlive?: boolean; keepAliveInitialDelay?: number };
+};
+
 describe('BinlogListener tests', { timeout: 60_000 }, () => {
   const MAX_QUEUE_CAPACITY_MB = 1;
   const BINLOG_LISTENER_CONNECTION_OPTIONS = {
@@ -59,6 +70,116 @@ describe('BinlogListener tests', { timeout: 60_000 }, () => {
 
     expect(stopSpy).toHaveBeenCalled();
     expect(queueStopSpy).toHaveBeenCalled();
+    // Zongji destroys its control connection when stopping.
+    expect(binLogListener.zongji.ctrlConnection.state).toBe('disconnected');
+  });
+
+  test('TCP keepalive is enabled on the binlog and control connections', async () => {
+    // Without keepalive, the control connection can idle for hours and be silently dropped by
+    // stateful firewalls. The next metadata query then blocks until the kernel gives up on TCP
+    // retransmissions, freezing the whole binlog pipeline for ~15 minutes.
+    const { connection } = binLogListener.zongji as unknown as { connection: ConnectionWithConfig };
+    const controlConnection = binLogListener.zongji.ctrlConnection as ConnectionWithConfig;
+
+    for (const conn of [connection, controlConnection]) {
+      expect(conn.config.enableKeepAlive).toBe(true);
+      expect(conn.config.keepAliveInitialDelay).toBe(TCP_KEEPALIVE_INITIAL_DELAY);
+    }
+  });
+
+  test('Stop completes when the control connection is unresponsive', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    // Simulate a control connection that was silently dropped by the network: the KILL query
+    // issued by zongji.stop() never gets a response.
+    vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation(() => {});
+
+    await binLogListener.stop();
+
+    expect(binLogListener.zongji.stopped).toBeTruthy();
+  });
+
+  test('Probe on a healthy control connection passes', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    // No mocking: the real driver must accept the options form of query and answer the probe.
+    const controlConnection = binLogListener.zongji.ctrlConnection;
+    const realQuery = controlConnection.query.bind(controlConnection);
+    const probeError = new Promise((resolve) => {
+      vi.spyOn(controlConnection, 'query').mockImplementation(((options: any, callback: any) => {
+        realQuery(options, (error: any, results: any, fields: any) => {
+          callback(error, results, fields);
+          resolve(error);
+        });
+      }) as any);
+    });
+
+    binLogListener.probeControlConnection();
+
+    expect(await probeError).toBeNull();
+    expect(binLogListener.zongji.stopped).toBeFalsy();
+
+    await binLogListener.stop();
+  });
+
+  test('Probe detects an unresponsive control connection', { timeout: 20_000 }, async () => {
+    binLogListener = await createBinlogListener({
+      connectionManager,
+      sourceTables: [new TablePattern(connectionManager.databaseName, 'test_DATA')],
+      eventHandler,
+      ctrlConnectionProbeTimeoutMs: 500
+    });
+    await binLogListener.start();
+
+    // The probe query starts executing but never gets a response, like a connection that died
+    // without either side being notified: the driver's query timeout fires.
+    vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation(((_options: any, callback: any) => {
+      const error: any = new Error('Query inactivity timeout');
+      error.code = 'PROTOCOL_SEQUENCE_TIMEOUT';
+      setTimeout(() => callback(error), 10);
+    }) as any);
+
+    const replication = binLogListener.replicateUntilStopped();
+    binLogListener.probeControlConnection();
+
+    await expect(replication).rejects.toThrow('control connection is unresponsive');
+    expect(binLogListener.zongji.stopped).toBeTruthy();
+  });
+
+  test('Probe queued behind a busy control connection does not report it dead', { timeout: 20_000 }, async () => {
+    binLogListener = await createBinlogListener({
+      connectionManager,
+      sourceTables: [new TablePattern(connectionManager.databaseName, 'test_DATA')],
+      eventHandler,
+      ctrlConnectionProbeTimeoutMs: 500
+    });
+    await binLogListener.start();
+
+    // The probe never even starts executing, as if queued behind a long-running metadata query on
+    // a healthy connection. The probe must not report the connection dead, and further probes must
+    // not pile up behind the pending one.
+    const querySpy = vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation((() => {}) as any);
+
+    binLogListener.probeControlConnection();
+    binLogListener.probeControlConnection();
+
+    expect(querySpy).toHaveBeenCalledTimes(1);
+    expect(binLogListener.zongji.stopped).toBeFalsy();
+
+    querySpy.mockRestore();
+    await binLogListener.stop();
+  });
+
+  test('Control connection errors stop the listener', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    const replication = binLogListener.replicateUntilStopped();
+    // The driver emits 'error' when the socket fails while no query is pending. Without the
+    // forwarding set up in createBinlogListener, this event has no listener and crashes the process.
+    (binLogListener.zongji.ctrlConnection as any).emit('error', new Error('Control connection failure'));
+
+    await expect(replication).rejects.toThrow('Control connection failure');
+    expect(binLogListener.zongji.stopped).toBeTruthy();
   });
 
   test('Zongji listener is stopped when processing queue reaches maximum memory size', async () => {
@@ -111,6 +232,24 @@ describe('BinlogListener tests', { timeout: 60_000 }, () => {
     expect(eventHandler.lastKeepAlive).toEqual(binLogListener.options.startGTID.comparable);
   });
 
+  test('Keepalive LSN after a commit is not less than the commit LSN', async () => {
+    binLogListener.options.keepAliveInactivitySeconds = 1;
+    await binLogListener.start();
+
+    await insertRows(connectionManager, 1);
+    await vi.waitFor(() => expect(eventHandler.commitCount).equals(1), { timeout: 5000 });
+    const commitLsn = eventHandler.lastCommitLsn!;
+
+    // Wait for a heartbeat keepalive that arrives after the commit.
+    // A keepalive LSN behind the commit LSN blocks checkpoint creation until the next transaction arrives.
+    await vi.waitFor(() => expect(eventHandler.lastKeepAlive && eventHandler.lastKeepAlive >= commitLsn).toBeTruthy(), {
+      timeout: 10_000
+    });
+    await binLogListener.stop();
+    // No binlog rotation happens in this test, so the keepalive LSN should exactly match the commit LSN
+    expect(eventHandler.lastKeepAlive).toEqual(commitLsn);
+  });
+
   test('Schema change event: Rename table', async () => {
     await binLogListener.start();
     await connectionManager.query(`ALTER TABLE test_DATA RENAME test_DATA_new`);