@voltro/sql-mysql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+import { CdcConfig } from '@voltro/database';
+import { ChangeEvent } from '@voltro/database';
+import { ChangeStrategy } from '@voltro/database';
+import { ConfigError } from 'effect';
+import { ConnectionConfig } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { DialectId } from '@voltro/database';
+import { DialectReplicationAdapter } from '@voltro/database';
+import { Effect } from 'effect';
+import { EventEmitter } from 'node:events';
+import { Layer } from 'effect';
+import { ManagedRuntime } from 'effect';
+import { MysqlClient } from '@effect/sql-mysql2';
+import { Predicate } from '@voltro/database';
+import { QueryDescriptor } from '@voltro/database';
+import { QueryNamespace } from '@voltro/database';
+import { RawSqlFragment } from '@voltro/database/sql';
+import { RetryDecision } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { SqlClient } from '@effect/sql';
+import { SqlClient as SqlClient_2 } from '@effect/sql/SqlClient';
+import { SqlDialect } from '@voltro/database';
+import { SqlError } from '@effect/sql';
+import { TableLike } from '@voltro/database';
+import { TransactionConnection } from '@effect/sql/SqlClient';
+
+export declare interface BinlogCdcHandle {
+    readonly stop: () => Promise<void>;
+    /** Last position the reader has advanced past (for a final checkpoint). */
+    readonly currentPosition: () => BinlogPosition | null;
+}
+
+export declare interface BinlogCdcOptions {
+    readonly connection: BinlogConnection;
+    /** Unique per reader. Duplicate server_id silently breaks binlog streams. */
+    readonly serverId: number;
+    readonly variant: 'mysql' | 'mariadb';
+    /** Unqualified table names to surface; undefined = every table in `database`. */
+    readonly includeTables?: ReadonlyArray<string>;
+    /** Resume point. Omit / null → start at the current end of the binlog. */
+    readonly startPosition?: BinlogPosition | null;
+    readonly onChange: (event: ChangeEvent) => void;
+    /** Called with the next position after each handled event (for checkpointing). */
+    readonly onPosition?: (pos: BinlogPosition) => void;
+    readonly onError?: (err: unknown) => void;
+    /**
+     * Re-resolve the current binlog end. Used when the persisted position
+     * is no longer valid (binlog purged past it — err 1236 — or after a
+     * failover to a different primary). Provided by the store
+     * (SHOW MASTER STATUS).
+     */
+    readonly resolveStartPosition?: () => Promise<BinlogPosition | null>;
+    /**
+     * Called when the reader had to skip forward to the current binlog end
+     * (a gap: purge/failover). The caller should treat live state as
+     * possibly-stale and re-query (self-heal) — the dispatcher's
+     * per-subscribe re-query already does this on the next change.
+     */
+    readonly onResync?: () => void;
+    /**
+     * Watchdog liveness cadence + stall threshold (ms). The reader tracks its
+     * last progress (any binlog event or a fresh attach); when nothing has
+     * arrived for `stallThresholdMs`, the watchdog probes the primary's current
+     * binlog end (`resolveStartPosition`) and — if the primary has advanced past
+     * the reader — force-reconnects. This is the SAFETY NET for a silently-dead
+     * stream: a server-side idle timeout / half-open socket can end the binlog
+     * connection WITHOUT mysql2 emitting an `error`, so `zongji` never fires and
+     * the plain error-driven reconnect never runs. The watchdog does not depend
+     * on any stream event. Defaults: probe every 15s, stall after 25s.
+     */
+    readonly watchdogIntervalMs?: number;
+    readonly stallThresholdMs?: number;
+    /**
+     * TCP keepalive idle delay (ms) for the replication socket — the PROACTIVE
+     * defense against the stall the watchdog only recovers from. A binlog dump
+     * connection carries NO traffic during quiet periods (zongji requests no
+     * replication heartbeat), so an idle NAT / firewall / load-balancer silently
+     * reaps it and a half-open socket (e.g. the host slept) is never noticed.
+     * Enabling keepalive with a SHORT idle delay makes the OS emit a probe after
+     * this many ms of silence: the socket is never truly idle (intermediaries
+     * keep it), and a dead peer surfaces as a connection error in seconds rather
+     * than sitting frozen forever. mysql2 defaults keepalive ON but with a 0
+     * delay (→ the OS default idle of ~2h), which is useless here. Default 10s.
+     */
+    readonly keepAliveInitialDelayMs?: number;
+}
+
+export declare interface BinlogConnection {
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly password: string;
+    readonly database: string;
+}
+
+export declare interface BinlogPosition {
+    readonly filename: string;
+    readonly position: number;
+}
+
+export declare const CDC_OFFSETS_TABLE = "_voltro_cdc_offsets";
+
+declare class CdcDeliveryGate {
+    private readonly variant;
+    private readonly ttlMs;
+    private readonly schedule;
+    /** fingerprint → count of occurrences seen but not yet paired. A value of N
+     *  means N deliveries have happened and are each awaiting their duplicate. */
+    private readonly seen;
+    constructor(variant: 'mysql' | 'mariadb', ttlMs?: number, schedule?: DelayScheduler);
+    /** Fingerprint an event by (table, op, pk, decoded-row-image). Returns null
+     *  when there's no usable primary key (nothing to pair on → always admit). */
+    private key;
+    /**
+     * Decide whether to deliver this candidate. Returns true for the FIRST
+     * occurrence of a fingerprint (deliver it) and false for the paired second
+     * occurrence (the same write arriving over the other path — drop it).
+     */
+    admit(event: ChangeEvent): boolean;
+    private expireOne;
+    /** Distinct fingerprints currently awaiting their pair — tests / diagnostics. */
+    get pending(): number;
+}
+
+/**
+ * Parse a `ConnectionConfig` into the mysql-specific shape. The same
+ * resolver handles `mariadb://` URLs — the wire protocol is identical,
+ * and the dialect's `id` field is what discriminates downstream.
+ *
+ * Defaults: port 3306, user `app`, password `app`, database `app`.
+ */
+export declare const connectionFromConfig: (config: ConnectionConfig) => MysqlConnection;
+
+/** Injectable scheduler so tests can drive the TTL deterministically without
+ *  real timers. The default unref's the timer so it never keeps the process
+ *  alive. */
+declare type DelayScheduler = (fn: () => void, ms: number) => void;
+
+export declare const makeMysqlSqlLayer: (options: MysqlConnection) => ReturnType<typeof MysqlClient.layerConfig>;
+
+export declare const makeMysqlSqlLayerFromConfig: (config: ConnectionConfig) => ReturnType<typeof MysqlClient.layerConfig>;
+
+export declare const makeMysqlStore: (options: MysqlStoreOptions) => Promise<MysqlStore>;
+
+/**
+ * MariaDB 10.6+. Same driver, separate dialect id so logs / boot
+ * banners / docs can say "mariadb" when that's what's live. MariaDB
+ * quirks (SEQUENCE-vs-AUTO_INCREMENT, JSON_VALID strictness) get
+ * handled inside the store via `variant === 'mariadb'` guards as they
+ * surface.
+ */
+export declare const mariadbDialect: SqlDialect;
+
+declare interface MysqlAdapterFriend {
+    readonly runEffect: <A, E>(effect: Effect.Effect<A, E, SqlClient_2>) => Promise<A>;
+    readonly variant: 'mysql' | 'mariadb';
+}
+
+export { MysqlClient }
+
+export declare interface MysqlConnection {
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly password: string;
+    readonly database: string;
+    readonly maxConnections?: number;
+}
+
+/**
+ * MySQL 8+. MySQL has no `INSERT ... RETURNING` in any version
+ * (that's MariaDB-only in this package) — the store produces
+ * post-image rows via a write-then-SELECT fallback on every mutation.
+ */
+export declare const mysqlDialect: SqlDialect;
+
+export declare const mysqlReplicationAdapter: () => DialectReplicationAdapter;
+
+export declare const mysqlRetryFilter: (err: unknown) => RetryDecision;
+
+export declare class MysqlStore implements DataStore {
+    private readonly sql;
+    private readonly runtime;
+    private readonly variant;
+    private readonly changeStrategy;
+    private readonly namespace;
+    private readonly emitter;
+    private inflightTxns;
+    private readonly log;
+    private cdcHandle;
+    private cdcCheckpointTimer;
+    private cdcPendingPosition;
+    private cdcReplicaId;
+    private cdcStreamName;
+    private readonly cdcGate;
+    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | MysqlClient.MysqlClient, never>, variant: 'mysql' | 'mariadb', changeStrategy?: ChangeStrategy, namespace?: QueryNamespace, sharedEmitter?: EventEmitter, sharedGate?: CdcDeliveryGate);
+    /**
+     * Bind a per-request tenant namespace (a DATABASE on mysql/mariadb),
+     * returning a view that qualifies every table reference to
+     * `<database>.<table>`. Shares this store's pool + emitter + CDC. The
+     * database must already exist — see the migrator's namespace fan-out.
+     */
+    withNamespace(namespace: string | null): DataStore;
+    /** Qualify a table to this view's namespace (no-op when unset). */
+    private nsT;
+    /* Excluded from this release type: dialectId */
+    /**
+     * Friend-handle the mysql/mariadb replication adapter reads via a
+     * structural check on `DataStore` (declared in
+     * `./replicationAdapter.ts`). The adapter needs raw SQL access against
+     * THIS store's managed runtime to issue `@@global.gtid_executed` /
+     * `@@global.gtid_current_pos` — without a friend handle it would need
+     * its own connection pool + config, which would double the deployment
+     * cost.
+     *
+     * The handle stays on the store class as a public-but-prefixed
+     * property so the type cast in `adapterFriend(store)` resolves
+     * without exporting the runtime to the wider API surface. The
+     * `variant` field flows through so the adapter picks the right
+     * dialect-specific SQL (mysql vs mariadb session var name).
+     */
+    get __mysqlReplicationFriend(): MysqlAdapterFriend;
+    private executeQuery;
+    /**
+     * `RETURNING` clause support across the mysql family is NOT uniform:
+     *
+     *   - MySQL (every version, including 8.x): NO `RETURNING` at all.
+     *   - MariaDB 10.5+:        `INSERT ... RETURNING *` ✓
+     *   - MariaDB 10.0+:        `DELETE ... RETURNING *` ✓
+     *   - MariaDB (any version): `UPDATE ... RETURNING *` ✗ — explicitly
+     *                            not supported, despite the otherwise
+     *                            broad RETURNING coverage.
+     *
+     * Two per-operation flags keep the dispatch explicit. The fallback
+     * paths INSERT/UPDATE/DELETE-then-SELECT-by-known-id all rely on
+     * the framework's auto-inject middleware which generates ids
+     * client-side (TypeID / ULID / Snowflake), so we always know the
+     * row's primary key BEFORE issuing the mutation. Getters (not
+     * inline `=` initializers) avoid referring to `this.variant`
+     * before constructor assignment.
+     */
+    private get supportsInsertReturning();
+    private get supportsDeleteReturning();
+    private get supportsUpdateReturning();
+    private executeInsert;
+    /**
+     * AUTO_INCREMENT id recovery for a single INSERT with no client-side
+     * id. `LAST_INSERT_ID()` is connection-scoped, so INSERT →
+     * LAST_INSERT_ID() → post-image SELECT must share one pinned
+     * connection. When the caller already holds a txn connection we run
+     * on it; otherwise we open a short transaction to pin the pool
+     * connection for the round-trip. Retries on a deadlock/lock-timeout.
+     */
+    private insertRecoverAutoId;
+    /**
+     * Run `body` on ONE pinned connection. Inside a caller-held txn we run
+     * on that connection directly; otherwise we open a short transaction so
+     * the connection-scoped `LAST_INSERT_ID()` stays valid across the
+     * INSERT → read → post-SELECT round-trip. The transactional path retries
+     * on a deadlock / lock-wait timeout (mirrors `updateMany`/`deleteMany`).
+     */
+    private runPinned;
+    private executeInsertMany;
+    /**
+     * AUTO_INCREMENT id recovery for a multi-row INSERT with no client-side
+     * ids. `LAST_INSERT_ID()` returns the FIRST generated id; the engine
+     * allocates the rest consecutively (guaranteed for a single multi-row
+     * `INSERT … VALUES` under the default `innodb_autoinc_lock_mode`), so
+     * the range is [first, first + n - 1]. Re-selects that range ordered by
+     * id (= input order) for the post-images. Same connection-pinning +
+     * retry as the single-row path.
+     */
+    private insertManyRecoverAutoIds;
+    private executePatchJson;
+    private executeUpdate;
+    private executeDelete;
+    private routeEvent;
+    private executeUpsert;
+    /**
+     * MariaDB 10.5+ native upsert:
+     * `INSERT … ON DUPLICATE KEY UPDATE col = VALUES(col), … RETURNING *`.
+     * One round-trip. `RETURNING *` gives the final row (post-insert OR
+     * post-update). The conflict columns + id are excluded from the SET
+     * list (they identify the row and must not be silently rewritten),
+     * matching the postgres `ON CONFLICT … DO UPDATE` shape.
+     */
+    private executeMariadbUpsert;
+    private executeInsertIgnore;
+    private findByConflict;
+    query(d: QueryDescriptor): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    raw<T extends object = Row>(fragment: RawSqlFragment, _opts?: {
+        dependsOn?: ReadonlyArray<string>;
+    }): Promise<ReadonlyArray<T>>;
+    private runWithEager;
+    /* Excluded from this release type: getInternalRunWithEager */
+    insert(t: string, r: Row): Promise<Readonly<Record<string, unknown>>>;
+    insertMany(t: string, rows: ReadonlyArray<Row>): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    patchJson(t: string, pk: string, path: string, value: unknown): Promise<Readonly<Record<string, unknown>> | null>;
+    upsert(t: string, r: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Readonly<Record<string, unknown>>>;
+    insertIgnore(t: string, r: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Readonly<Record<string, unknown>>>;
+    update(t: string, pk: string, p: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>> | null>;
+    delete(t: string, pk: string): Promise<boolean>;
+    updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
+        where: Predicate;
+    }): Promise<number>;
+    deleteMany(table: string, options: {
+        where: Predicate;
+    }): Promise<number>;
+    /* Excluded from this release type: emitChange */
+    /* Excluded from this release type: startCdcConsumer */
+    /* Excluded from this release type: assertBinlogConfig */
+    /* Excluded from this release type: resolveBinlogEnd */
+    /* Excluded from this release type: readCdcOffset */
+    /* Excluded from this release type: flushCdcOffset */
+    /* Excluded from this release type: getInternalExecuteQuery */
+    /* Excluded from this release type: getInternalExecuteInsert */
+    /* Excluded from this release type: getInternalExecuteInsertMany */
+    /* Excluded from this release type: getInternalExecutePatchJson */
+    /* Excluded from this release type: getInternalExecuteUpdate */
+    /* Excluded from this release type: getInternalExecuteDelete */
+    /* Excluded from this release type: getInternalExecuteUpsert */
+    /* Excluded from this release type: getInternalExecuteInsertIgnore */
+    transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
+    onChange(listener: (event: ChangeEvent) => void): () => void;
+    /** Cross-instance reactivity seam — emit an externally-sourced event to
+     *  local subscribers without re-persisting. The binlog CDC consumer and
+     *  `@voltro/plugin-broadcast` route through here. See
+     *  `DataStore.injectExternalChange`. */
+    /** 'fleet' under binlog CDC (every replica gets the full stream);
+     *  'local' under inline emission. See DataStore.changeScope. */
+    get changeScope(): 'local' | 'fleet';
+    injectExternalChange(event: ChangeEvent): void;
+    run<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+    close(gracePeriodMs?: number): Promise<void>;
+    /** Liveness probe — `SELECT 1`. Rejects if the pool can't answer. */
+    ping(): Promise<void>;
+}
+
+export declare interface MysqlStoreOptions {
+    readonly sqlLayer: Layer.Layer<SqlClient.SqlClient | MysqlClient.MysqlClient, ConfigError.ConfigError | SqlError.SqlError, never>;
+    readonly tracerLayer?: Layer.Layer<never, never, never>;
+    /** `'inline'` (default): local reactivity only — the writing instance sees
+     *  its own deltas. `'cdc'`: ADDITIVE cross-instance fan-out — the writer
+     *  still emits its own deltas inline, and a ROW-format binlog reader also
+     *  surfaces every OTHER replica's writes on this replica's `onChange` (own
+     *  echoes deduped). Supported on BOTH mysql-8 and mariadb (same binlog
+     *  reader, per-variant detection). */
+    readonly changeStrategy?: ChangeStrategy;
+    /** Binlog CDC wiring — required when `changeStrategy: 'cdc'` (mysql or mariadb). */
+    readonly cdcConfig?: CdcConfig;
+    /** Variant id — `'mysql'` or `'mariadb'`. Surfaces in spans + logs;
+     *  the wire protocol is identical so no behavioural branch needed. */
+    readonly variant?: 'mysql' | 'mariadb';
+}
+
+/**
+ * Start a binlog reader. Resolves once the reader is attached and
+ * streaming (so the caller can guarantee "reader attached before
+ * subscriptions"). The returned handle stops it.
+ */
+export declare const startBinlogCdc: (opts: BinlogCdcOptions) => Promise<BinlogCdcHandle>;
+
+declare type TxnContext = Context.Tag.Service<typeof TransactionConnection>;
+
+export declare const _voltroCdcOffsetsTable: TableLike;
+
+export { }