@vlasky/zongji 0.7.1 → 0.9.0

package/index.d.ts

@@ -11,8 +11,27 @@ export interface ZongJiOptions {
   filename?: string;
   /** Binlog position to start from */
   position?: number;
+  /**
+   * Executed GTIDs to resume from (e.g. a persisted zongji.gtidSet): a
+   * MySQL GTID set ('uuid:1-5,...', tagged intervals as
+   * 'uuid:1-5:tag_a:1,...' on MySQL 8.3+) or a MariaDB GTID position
+   * ('0-1-1234,...'), matching the server flavour. The server locates
+   * the right binlog file and skips transactions already processed
+   * (MySQL: COM_BINLOG_DUMP_GTID, requires gtid_mode=ON; MariaDB:
+   * @slave_connect_state, always available), so this works across
+   * failover to another server in the same topology. '' streams the
+   * server's entire available history. Takes precedence over
+   * filename/position. A set containing tags uses a wire encoding only
+   * MySQL 8.3+ understands; older servers reject it.
+   */
+  gtidSet?: string;
   /** If true, use non-blocking mode */
   nonBlock?: boolean;
+  /**
+   * MariaDB only: request ANNOTATE_ROWS events (the SQL statement text
+   * preceding each row operation's TableMap events). Ignored on MySQL.
+   */
+  requestAnnotateRows?: boolean;
   /** List of event types to include (e.g., ['tablemap', 'writerows']) */
   includeEvents?: string[];
   /** List of event types to exclude */
@@ -23,13 +42,22 @@ export interface ZongJiOptions {
   excludeSchema?: Record<string, string[] | true>;
 }
 
-// Column metadata from INFORMATION_SCHEMA
+// Column metadata, either fetched from INFORMATION_SCHEMA or synthesised
+// from the binlog's own TableMap metadata (binlog_row_metadata=FULL).
+// In the synthesised form COLUMN_TYPE is approximate for character columns
+// (no display width) and COLLATION_NAME/COLUMN_COMMENT are not available.
 export interface ColumnSchema {
   COLUMN_NAME: string;
   COLLATION_NAME: string | null;
   CHARACTER_SET_NAME: string | null;
   COLUMN_COMMENT: string;
   COLUMN_TYPE: string;
+  /** Exact signedness from binlog metadata (MySQL 8.0+); numeric columns only */
+  UNSIGNED?: boolean;
+  /** ENUM value list from binlog metadata (binlog_row_metadata=FULL) */
+  ENUM_VALUES?: string[];
+  /** SET value list from binlog metadata (binlog_row_metadata=FULL) */
+  SET_VALUES?: string[];
 }
 
 // Column information from TableMap event
@@ -95,9 +123,15 @@ export interface GtidEvent extends BinlogEvent {
   flags: number;
   /** Source UUID */
   sid: string;
-  /** Group number */
-  gno: number;
-  /** Full GTID string (sid:gno) */
+  /** Group number (exact string beyond Number.MAX_SAFE_INTEGER) */
+  gno: number | string;
+  /**
+   * GTID tag (MySQL 8.3+, set via GTID_NEXT='AUTOMATIC:tag'); '' for
+   * untagged transactions. Only present on events that arrived as
+   * GTID_TAGGED_LOG_EVENT; classic GTID events leave it undefined.
+   */
+  tag?: string;
+  /** Full GTID string (sid:gno, or sid:tag:gno when tagged) */
   gtid: string;
 }
 
@@ -109,20 +143,34 @@ export interface AnonymousGtidEvent extends BinlogEvent {
   flags: number;
   /** Source UUID */
   sid: string;
-  /** Group number */
-  gno: number;
+  /** Group number (exact string beyond Number.MAX_SAFE_INTEGER) */
+  gno: number | string;
   /** Full GTID string (sid:gno) */
   gtid: string;
 }
 
 // Previous GTIDs event
 export interface GtidInterval {
-  start: number;
-  end: number;
+  /**
+   * Interval start GNO, inclusive (exact string above
+   * Number.MAX_SAFE_INTEGER)
+   */
+  start: number | string;
+  /**
+   * Interval end GNO, exclusive as on the wire (exact string above
+   * Number.MAX_SAFE_INTEGER)
+   */
+  end: number | string;
 }
 
 export interface GtidSidEntry {
   sid: string;
+  /**
+   * GTID tag ('' for the untagged entry). Only present when the server
+   * wrote the tagged set encoding (MySQL 8.3+ after any tagged GTID);
+   * each (sid, tag) pair is its own entry, repeating the sid.
+   */
+  tag?: string;
   intervals: GtidInterval[];
 }
 
@@ -197,7 +245,45 @@ export interface TableMapEvent extends BinlogEvent {
   columnsMetadata: Record<string, unknown>[];
   /** Reference to the tableMap cache */
   tableMap: Record<number, TableMapEntry>;
-  /** Update column info after fetching from INFORMATION_SCHEMA */
+  /**
+   * Column names carried by the event itself (MySQL 8.0+ with
+   * binlog_row_metadata=FULL)
+   */
+  columnNames?: string[];
+  /**
+   * Per-column signedness from binlog metadata (MySQL 8.0+, MINIMAL and
+   * FULL); true = unsigned. Undefined entries are non-numeric columns.
+   */
+  signedness?: (boolean | undefined)[];
+  /**
+   * Primary key column indexes (0-based, all-columns numbering) from
+   * binlog_row_metadata=FULL
+   */
+  primaryKey?: number[];
+  /**
+   * Per-column visibility from binlog_row_metadata=FULL (MySQL 8.0.23+);
+   * false = INVISIBLE column
+   */
+  columnVisibility?: boolean[];
+  /**
+   * Per-column geometry subtype from binlog metadata (0 = geometry,
+   * 1 = point, ...); undefined entries are non-spatial columns
+   */
+  geometryTypes?: (number | undefined)[];
+  /**
+   * True when the event carries binlog_row_metadata=FULL metadata, in
+   * which case zongji decodes rows without querying INFORMATION_SCHEMA
+   */
+  hasSelfDescribingMetadata(): boolean;
+  /**
+   * True when the table contains classic temporal type codes, which on
+   * MariaDB may hide 5.3 "hires" columns that binlog metadata cannot
+   * reveal; such tables use the INFORMATION_SCHEMA path even under FULL
+   */
+  hasAmbiguousTemporalColumns(): boolean;
+  /** Build ColumnSchema entries from the event's own metadata (FULL only) */
+  buildColumnSchemas(): ColumnSchema[];
+  /** Update column info after table metadata is available */
   updateColumnInfo(): void;
 }
 
@@ -262,6 +348,151 @@ export interface PartialUpdateRowsEvent extends BinlogEvent {
   getEventName(): 'partialupdaterows';
 }
 
+// Heartbeat event - sent while the connection idles (when a heartbeat
+// period is configured) and after transactions were skipped server-side
+// during a GTID dump; nextPosition carries the advanced position
+export interface HeartbeatEvent extends BinlogEvent {
+  getTypeName(): 'Heartbeat';
+  getEventName(): 'heartbeat';
+  /** Current binlog filename */
+  binlogName: string;
+  /**
+   * Heartbeat position beyond 4 GiB (MariaDB only: sent in a sub-header
+   * when the u32 nextPosition cannot represent it, which is then 0)
+   */
+  position?: number | string;
+}
+
+// MariaDB GTID event (code 162) - replaces the BEGIN Query event of a
+// transaction (standalone=false) or marks a standalone group such as DDL
+export interface MariadbGtidEvent extends BinlogEvent {
+  getTypeName(): 'MariadbGtid';
+  getEventName(): 'mariadbgtid';
+  /**
+   * Sequence number within the domain. Arrives as an exact string above
+   * Number.MAX_SAFE_INTEGER, so never compare it numerically: use
+   * event.gtid with MariadbGtidPosition.covers() (or GtidSet on MySQL)
+   * instead.
+   */
+  seqNo: number | string;
+  /** Replication domain id */
+  domainId: number;
+  /** Originating server id (from the event header) */
+  serverId: number;
+  /** Raw flags2 byte */
+  flags2: number;
+  /** True for standalone groups (DDL, ...) with no terminating commit */
+  standalone: boolean;
+  /** True when the group can be safely rolled back */
+  transactional: boolean;
+  /** True when the group contains DDL */
+  isDdl: boolean;
+  /** XA PREPARE group; XID fields present */
+  preparedXa: boolean;
+  /** XA COMMIT/ROLLBACK group; XID fields present */
+  completedXa: boolean;
+  /** Group-commit id (same for all members of one group commit) */
+  commitId?: number | string;
+  /** XA format id, when preparedXa/completedXa */
+  xidFormatId?: number;
+  /** XA gtrid, when preparedXa/completedXa */
+  xidGtrid?: Buffer;
+  /** XA bqual, when preparedXa/completedXa */
+  xidBqual?: Buffer;
+  /** Raw flags_extra byte, when present */
+  flagsExtra?: number;
+  /** Number of extra engines, when FL_EXTRA_MULTI_ENGINE is set */
+  extraEngines?: number;
+  /** Start-alter sequence number, for COMMIT/ROLLBACK ALTER groups */
+  saSeqNo?: number | string;
+  /** Thread id of the originating connection (MariaDB 11.5+) */
+  threadId?: number;
+  /** Full GTID string (domain-server-sequence) */
+  gtid: string;
+}
+
+export interface MariadbGtidListEntry {
+  domainId: number;
+  serverId: number;
+  /**
+   * Sequence number within the domain. Arrives as an exact string above
+   * Number.MAX_SAFE_INTEGER, so never compare it numerically: use the
+   * gtid string with MariadbGtidPosition.covers() instead.
+   */
+  seqNo: number | string;
+  /** Full GTID string (domain-server-sequence) */
+  gtid: string;
+}
+
+// MariaDB GTID list event (code 163) - at the start of every binlog file,
+// the last GTID per (domain, server) seen so far; MariaDB's analogue of
+// MySQL's Previous_gtids
+export interface MariadbGtidListEvent extends BinlogEvent {
+  getTypeName(): 'MariadbGtidList';
+  getEventName(): 'mariadbgtidlist';
+  count: number;
+  /** High 4 bits of the count word (FLAG_UNTIL_REACHED, FLAG_IGN_GTIDS) */
+  flags: number;
+  gtids: MariadbGtidListEntry[];
+}
+
+// MariaDB binlog checkpoint event (code 161) - XA-recovery marker naming
+// the oldest binlog file that may still be needed for crash recovery
+export interface BinlogCheckpointEvent extends BinlogEvent {
+  getTypeName(): 'BinlogCheckpoint';
+  getEventName(): 'binlogcheckpoint';
+  binlogName: string;
+}
+
+// MariaDB annotate rows event (code 160) - the SQL statement text for the
+// row events that follow
+export interface AnnotateRowsEvent extends BinlogEvent {
+  getTypeName(): 'AnnotateRows';
+  getEventName(): 'annotaterows';
+  /**
+   * The event carries the statement's original bytes with no charset
+   * metadata; decoded as utf8 (exact for utf8/utf8mb4 clients, the
+   * overwhelmingly common case).
+   */
+  statement: string;
+}
+
+// MySQL rows query event (code 29) - the SQL statement text for the row
+// events that follow, sent while the server runs with
+// binlog_rows_query_log_events=ON
+export interface RowsQueryEvent extends BinlogEvent {
+  getTypeName(): 'RowsQuery';
+  getEventName(): 'rowsquery';
+  /**
+   * The event carries the statement's original bytes with no charset
+   * metadata; decoded as utf8 (exact for utf8/utf8mb4 clients, the
+   * overwhelmingly common case).
+   */
+  statement: string;
+}
+
+// MariaDB start encryption event (code 164) - informational; the dump
+// thread decrypts server-side and the stream itself is cleartext
+export interface StartEncryptionEvent extends BinlogEvent {
+  getTypeName(): 'StartEncryption';
+  getEventName(): 'startencryption';
+  scheme: number;
+  keyVersion: number;
+  nonce: Buffer;
+}
+
+// XA prepare event (code 38, MySQL 5.7+ and MariaDB) - terminates an
+// XA-prepared event group
+export interface XaPrepareEvent extends BinlogEvent {
+  getTypeName(): 'XaPrepare';
+  getEventName(): 'xaprepare';
+  /** XA COMMIT ... ONE PHASE (commits immediately) */
+  onePhase: boolean;
+  xidFormatId: number;
+  xidGtrid: Buffer;
+  xidBqual: Buffer;
+}
+
 // Unknown event type
 export interface UnknownEvent extends BinlogEvent {
   getTypeName(): 'Unknown';
@@ -284,6 +515,14 @@ export type AnyBinlogEvent =
   | UpdateRowsEvent
   | TransactionPayloadEvent
   | PartialUpdateRowsEvent
+  | HeartbeatEvent
+  | MariadbGtidEvent
+  | MariadbGtidListEvent
+  | BinlogCheckpointEvent
+  | AnnotateRowsEvent
+  | RowsQueryEvent
+  | StartEncryptionEvent
+  | XaPrepareEvent
   | UnknownEvent;
 
 /** Union of all possible getTypeName() return values (e.g. 'Rotate', 'WriteRows') */
@@ -329,14 +568,42 @@ declare class ZongJi extends EventEmitter {
   stopped: boolean;
   /** Whether binlog checksum is enabled */
   useChecksum: boolean;
+  /**
+   * Server version string as reported by SELECT VERSION(), e.g.
+   * '8.4.5' or '11.8.8-MariaDB-ubu2404-log'. Set during start()
+   * initialisation, before the 'ready' event.
+   */
+  serverVersion: string | undefined;
+  /** True when the connected server is MariaDB (set during start()) */
+  isMariaDb: boolean;
   /** Current binlog options */
   options: {
     serverId?: number;
     filename?: string;
     position?: number;
     startAtEnd?: boolean;
+    gtidSet?: string;
     nonBlock?: boolean;
+    requestAnnotateRows?: boolean;
   };
+  /**
+   * The transactions this instance knows to be processed: the start()
+   * seed plus every transaction whose commit has been observed. A MySQL
+   * GTID set ('uuid:1-5,...') or a MariaDB GTID position ('0-1-1234,...')
+   * depending on the connected server. Persist it and pass to
+   * start({ gtidSet }) to resume, including on a different server.
+   * Undefined when no exact seed was available (a mid-file file+position
+   * start).
+   */
+  readonly gtidSet: string | undefined;
+  /**
+   * The GTID of the transaction whose events are currently being
+   * delivered (equal to their event.gtid); undefined between
+   * transactions and for anonymous transactions. Only coherent when
+   * read synchronously inside a 'binlog' handler: checkpointing code
+   * should use event.gtid.
+   */
+  readonly lastGtid: string | undefined;
   /** Current filter settings */
   filters: {
     includeEvents?: string[];
@@ -394,3 +661,86 @@ declare class ZongJi extends EventEmitter {
 }
 
 export default ZongJi;
+
+/**
+ * A MySQL GTID set (the model behind zongji.gtidSet): which transactions
+ * per source are already executed. String form matches @@gtid_executed,
+ * including tagged GTIDs (MySQL 8.3+): 'uuid:1-5:11,uuid2:1-27',
+ * 'uuid:1-5:tag_a:1'. Exported so consumers can parse persisted sets and
+ * test event.gtid membership without their own parser.
+ */
+export class GtidSet {
+  /**
+   * Parses a GTID set string ('' gives an empty set). Within a uuid
+   * block a non-numeric item is a tag naming the source of the interval
+   * items that follow it. Throws on malformed input.
+   */
+  static parse(text: string): GtidSet;
+  /** Adds a single transaction ('uuid:gno' or 'uuid:tag:gno') */
+  add(gtid: string): void;
+  /**
+   * Whether a single transaction ('uuid:gno' or 'uuid:tag:gno', e.g. an
+   * event.gtid) is contained in the set. null/undefined (an anonymous
+   * transaction's event.gtid) is never contained; a malformed string
+   * throws.
+   */
+  contains(gtid: string | null | undefined): boolean;
+  isEmpty(): boolean;
+  /** Canonical text form (sorted; tagged intervals after untagged) */
+  toString(): string;
+}
+
+/**
+ * A MariaDB GTID position (the model behind zongji.gtidSet on MariaDB):
+ * the last transaction processed per replication domain. String form
+ * matches @@gtid_binlog_pos / @@gtid_current_pos, e.g. '0-1-1234,1-3-45'.
+ * Exported so consumers can parse persisted positions and test coverage
+ * via covers() instead of hand-rolling seqNo comparators (which silently
+ * round above Number.MAX_SAFE_INTEGER when done with Number; internally
+ * this class is exact over the full u64 sequence range).
+ */
+export class MariadbGtidPosition {
+  /**
+   * Parses a GTID position string ('' gives an empty position). Rejects
+   * two entries for one domain, as the server would. Throws on malformed
+   * input.
+   */
+  static parse(text: string): MariadbGtidPosition;
+  /**
+   * Builds the position implied by a MariadbGtidList event's gtids
+   * array: the last entry per domain wins
+   */
+  static fromGtidList(entries: Array<{
+    domainId: number;
+    serverId: number;
+    seqNo: number | string;
+  }>): MariadbGtidPosition;
+  /**
+   * Records a transaction as the last processed in its domain
+   * (an overwrite, not a max: "last processed" survives failovers where
+   * sequence numbers regress under a new server id)
+   */
+  add(gtid: {
+    domainId: number;
+    serverId: number;
+    seqNo: number | string;
+  }): void;
+  /**
+   * Whether a transaction ('domain-server-sequence', e.g. an event.gtid)
+   * is covered by this position. inclusive (default true) counts the
+   * position's own last transaction as covered (snapshot-barrier
+   * semantics); redelivery watermarks must pass { inclusive: false },
+   * because all events of a transaction share one GTID and an inclusive
+   * check would drop every replayed event of the watermark transaction
+   * after the first. A server-id mismatch within a domain and an unknown
+   * domain both report not covered; null/undefined is never covered; a
+   * malformed string throws.
+   */
+  covers(
+    gtid: string | null | undefined,
+    options?: { inclusive?: boolean },
+  ): boolean;
+  isEmpty(): boolean;
+  /** Text form, sorted by domain ('D-S-N[,D-S-N...]') */
+  toString(): string;
+}