@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/transport/memory.d.ts

@@ -0,0 +1,221 @@
+interface NodeInfo {
+    id: string;
+    groupId?: string;
+    role: 'primary' | 'replica';
+    primaryTerm?: bigint;
+    protocolVersion?: string;
+    joinedAt: number;
+    lastSeenAt: number;
+    lastAckedSeq: bigint;
+    metadata?: Record<string, unknown>;
+}
+interface ReplicationChange {
+    table: string;
+    operation: 'insert' | 'update' | 'delete' | 'ddl';
+    rowId: string;
+    primaryKey: Record<string, unknown>;
+    hlc: string;
+    txId: string;
+    nodeId: string;
+    newData: Record<string, unknown> | null;
+    oldData: Record<string, unknown> | null;
+    ddlStatement?: string;
+}
+interface ReplicationBatch {
+    sourceNodeId: string;
+    batchId: string;
+    fromSeq: bigint;
+    toSeq: bigint;
+    hlcRange: {
+        min: string;
+        max: string;
+    };
+    changes: ReplicationChange[];
+    checksum: string;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface ReplicationAck {
+    batchId: string;
+    ackedSeq: bigint;
+    nodeId: string;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface ForwardedTransaction {
+    statements: Array<{
+        sql: string;
+        params?: Record<string, unknown> | unknown[];
+    }>;
+    requestId: string;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface ForwardedTransactionResult {
+    results: Array<{
+        changes: number;
+        lastInsertRowId: number | string;
+    }>;
+    requestId: string;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+type TopologyRole = 'primary' | 'replica';
+interface TransportConfig {
+    endpoints?: string[];
+    localRole?: TopologyRole;
+    groupId?: string;
+    primaryTerm?: bigint;
+    protocolVersion?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ReplicationTransport {
+    connect(localNodeId: string, config: TransportConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    send(peerId: string, batch: ReplicationBatch): Promise<void>;
+    broadcast(batch: ReplicationBatch): Promise<void>;
+    sendAck(peerId: string, ack: ReplicationAck): Promise<void>;
+    forward(peerId: string, request: ForwardedTransaction): Promise<ForwardedTransactionResult>;
+    requestSync(peerId: string, request: SyncRequest): Promise<void>;
+    sendSyncBatch(peerId: string, batch: SyncBatch): Promise<void>;
+    sendSyncComplete(peerId: string, complete: SyncComplete): Promise<void>;
+    sendSyncAck(peerId: string, ack: SyncAck): Promise<void>;
+    onBatchReceived(handler: (batch: ReplicationBatch, fromPeerId: string) => Promise<void>): void;
+    onAckReceived(handler: (ack: ReplicationAck, fromPeerId: string) => void): void;
+    onForwardReceived(handler: (request: ForwardedTransaction, fromPeerId: string) => Promise<ForwardedTransactionResult>): void;
+    onSyncRequested(handler: (request: SyncRequest, fromPeerId: string) => Promise<void>): void;
+    onSyncBatchReceived(handler: (batch: SyncBatch, fromPeerId: string) => Promise<void>): void;
+    onSyncCompleteReceived(handler: (complete: SyncComplete, fromPeerId: string) => Promise<void>): void;
+    onSyncAckReceived(handler: (ack: SyncAck, fromPeerId: string) => void): void;
+    onPeerConnected(handler: (peer: NodeInfo) => void): void;
+    onPeerDisconnected(handler: (peerId: string) => void): void;
+    peers(): ReadonlyMap<string, NodeInfo>;
+}
+interface SyncRequest {
+    requestId: string;
+    joinerNodeId: string;
+    completedTables: string[];
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface SyncBatch {
+    requestId: string;
+    table: string;
+    batchIndex: number;
+    rows: Record<string, unknown>[];
+    schema?: string[];
+    checksum: string;
+    isLastBatchForTable: boolean;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface SyncTableManifest {
+    table: string;
+    rowCount: number;
+    pkHash: string;
+}
+interface SyncComplete {
+    requestId: string;
+    snapshotSeq: bigint;
+    manifests: SyncTableManifest[];
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+interface SyncAck {
+    requestId: string;
+    joinerNodeId: string;
+    table: string;
+    batchIndex: number;
+    success: boolean;
+    error?: string;
+    groupId?: string;
+    primaryTerm?: bigint;
+}
+
+type BatchHandler = (batch: ReplicationBatch, fromPeerId: string) => Promise<void>;
+type AckHandler = (ack: ReplicationAck, fromPeerId: string) => void;
+type ForwardHandler = (request: ForwardedTransaction, fromPeerId: string) => Promise<ForwardedTransactionResult>;
+type PeerConnectedHandler = (peer: NodeInfo) => void;
+type PeerDisconnectedHandler = (peerId: string) => void;
+type SyncRequestHandler = (request: SyncRequest, fromPeerId: string) => Promise<void>;
+type SyncBatchHandler = (batch: SyncBatch, fromPeerId: string) => Promise<void>;
+type SyncCompleteHandler = (complete: SyncComplete, fromPeerId: string) => Promise<void>;
+type SyncAckHandler = (ack: SyncAck, fromPeerId: string) => void;
+
+/**
+ * In-process ReplicationTransport for testing and single-process multi-node
+ * scenarios.
+ *
+ * Messages between peers are delivered through a shared MemoryBus via
+ * microtask scheduling (`queueMicrotask`), preserving the async delivery
+ * semantics of a real network transport while avoiding actual I/O. All
+ * message types (batches, acks, forwards) go through runtime
+ * validation before delivery, and malformed payloads are silently dropped
+ * to match the behavior of a lossy network.
+ */
+declare class InMemoryTransport implements ReplicationTransport {
+    private localNodeId;
+    private localRole;
+    private localGroupId;
+    private localPrimaryTerm;
+    private localProtocolVersion;
+    connected: boolean;
+    private readonly bus;
+    readonly connectedPeers: Map<string, NodeInfo>;
+    private batchHandler;
+    private ackHandler;
+    private forwardHandler;
+    peerConnectedHandler: PeerConnectedHandler | null;
+    peerDisconnectedHandler: PeerDisconnectedHandler | null;
+    private syncRequestHandler;
+    private syncBatchHandler;
+    private syncCompleteHandler;
+    private syncAckHandler;
+    constructor(bus: MemoryBus);
+    get role(): 'primary' | 'replica';
+    connect(localNodeId: string, config: TransportConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    send(peerId: string, batch: ReplicationBatch): Promise<void>;
+    broadcast(batch: ReplicationBatch): Promise<void>;
+    sendAck(peerId: string, ack: ReplicationAck): Promise<void>;
+    forward(peerId: string, request: ForwardedTransaction): Promise<ForwardedTransactionResult>;
+    requestSync(peerId: string, request: SyncRequest): Promise<void>;
+    sendSyncBatch(peerId: string, batch: SyncBatch): Promise<void>;
+    sendSyncComplete(peerId: string, complete: SyncComplete): Promise<void>;
+    sendSyncAck(peerId: string, ack: SyncAck): Promise<void>;
+    onBatchReceived(handler: BatchHandler): void;
+    onAckReceived(handler: AckHandler): void;
+    onForwardReceived(handler: ForwardHandler): void;
+    onSyncRequested(handler: SyncRequestHandler): void;
+    onSyncBatchReceived(handler: SyncBatchHandler): void;
+    onSyncCompleteReceived(handler: SyncCompleteHandler): void;
+    onSyncAckReceived(handler: SyncAckHandler): void;
+    onPeerConnected(handler: PeerConnectedHandler): void;
+    onPeerDisconnected(handler: PeerDisconnectedHandler): void;
+    peers(): ReadonlyMap<string, NodeInfo>;
+    _receiveBatch(batch: ReplicationBatch, fromPeerId: string): Promise<void>;
+    _receiveAck(ack: ReplicationAck, fromPeerId: string): void;
+    _receiveForward(request: ForwardedTransaction, fromPeerId: string): Promise<ForwardedTransactionResult>;
+    _receiveSyncRequest(request: SyncRequest, fromPeerId: string): Promise<void>;
+    _receiveSyncBatch(batch: SyncBatch, fromPeerId: string): Promise<void>;
+    _receiveSyncComplete(complete: SyncComplete, fromPeerId: string): Promise<void>;
+    _receiveSyncAck(ack: SyncAck, fromPeerId: string): void;
+    private ensureConnected;
+}
+
+/**
+ * Shared message bus that connects InMemoryTransport instances within the
+ * same process. Each transport registers itself on `connect()` and messages
+ * are delivered via direct method calls on the target transport through
+ * microtask scheduling, simulating async network delivery without actual I/O.
+ */
+declare class MemoryBus {
+    private readonly transports;
+    join(peerId: string, transport: InMemoryTransport): void;
+    leave(peerId: string): void;
+    getTransport(peerId: string): InMemoryTransport | undefined;
+    peerIds(): IterableIterator<string>;
+    get size(): number;
+}
+
+export { InMemoryTransport, MemoryBus };

package/dist/transport/memory.mjs

@@ -0,0 +1,337 @@
+// src/transport/memory/bus.ts
+var MemoryBus = class {
+  transports = /* @__PURE__ */ new Map();
+  join(peerId, transport) {
+    this.transports.set(peerId, transport);
+  }
+  leave(peerId) {
+    this.transports.delete(peerId);
+  }
+  getTransport(peerId) {
+    return this.transports.get(peerId);
+  }
+  peerIds() {
+    return this.transports.keys();
+  }
+  get size() {
+    return this.transports.size;
+  }
+};
+
+// src/core/errors.ts
+var SirannonError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SirannonError";
+  }
+};
+
+// src/replication/errors.ts
+var ReplicationError = class extends SirannonError {
+  constructor(message, code = "REPLICATION_ERROR", details) {
+    super(message, code);
+    this.details = details;
+    this.name = "ReplicationError";
+  }
+};
+var TransportError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "TRANSPORT_ERROR");
+    this.name = "TransportError";
+  }
+};
+
+// src/transport/validators.ts
+function isValidBatch(batch) {
+  if (typeof batch !== "object" || batch === null) return false;
+  const b = batch;
+  return typeof b.sourceNodeId === "string" && typeof b.batchId === "string" && typeof b.fromSeq === "bigint" && typeof b.toSeq === "bigint" && typeof b.checksum === "string" && Array.isArray(b.changes) && typeof b.hlcRange === "object" && b.hlcRange !== null && optionalString(b.groupId) && optionalBigint(b.primaryTerm);
+}
+function isValidAck(ack) {
+  if (typeof ack !== "object" || ack === null) return false;
+  const a = ack;
+  return typeof a.batchId === "string" && typeof a.ackedSeq === "bigint" && typeof a.nodeId === "string" && optionalString(a.groupId) && optionalBigint(a.primaryTerm);
+}
+function isValidForwardedTransaction(req) {
+  if (typeof req !== "object" || req === null) return false;
+  const r = req;
+  return typeof r.requestId === "string" && Array.isArray(r.statements) && optionalString(r.groupId) && optionalBigint(r.primaryTerm);
+}
+function isValidSyncRequest(req) {
+  if (typeof req !== "object" || req === null) return false;
+  const r = req;
+  return typeof r.requestId === "string" && typeof r.joinerNodeId === "string" && Array.isArray(r.completedTables) && optionalString(r.groupId) && optionalBigint(r.primaryTerm);
+}
+function isValidSyncBatch(batch) {
+  if (typeof batch !== "object" || batch === null) return false;
+  const b = batch;
+  return typeof b.requestId === "string" && typeof b.table === "string" && typeof b.batchIndex === "number" && Array.isArray(b.rows) && typeof b.checksum === "string" && typeof b.isLastBatchForTable === "boolean" && optionalString(b.groupId) && optionalBigint(b.primaryTerm);
+}
+function isValidSyncComplete(complete) {
+  if (typeof complete !== "object" || complete === null) return false;
+  const c = complete;
+  return typeof c.requestId === "string" && typeof c.snapshotSeq === "bigint" && Array.isArray(c.manifests) && optionalString(c.groupId) && optionalBigint(c.primaryTerm);
+}
+function isValidSyncAck(ack) {
+  if (typeof ack !== "object" || ack === null) return false;
+  const a = ack;
+  return typeof a.requestId === "string" && typeof a.joinerNodeId === "string" && typeof a.table === "string" && typeof a.batchIndex === "number" && typeof a.success === "boolean" && optionalString(a.groupId) && optionalBigint(a.primaryTerm);
+}
+function optionalString(value) {
+  return value === void 0 || typeof value === "string";
+}
+function optionalBigint(value) {
+  return value === void 0 || typeof value === "bigint";
+}
+
+// src/transport/memory/transport.ts
+var InMemoryTransport = class {
+  localNodeId = "";
+  localRole = "replica";
+  localGroupId;
+  localPrimaryTerm;
+  localProtocolVersion;
+  connected = false;
+  bus;
+  connectedPeers = /* @__PURE__ */ new Map();
+  batchHandler = null;
+  ackHandler = null;
+  forwardHandler = null;
+  peerConnectedHandler = null;
+  peerDisconnectedHandler = null;
+  syncRequestHandler = null;
+  syncBatchHandler = null;
+  syncCompleteHandler = null;
+  syncAckHandler = null;
+  constructor(bus) {
+    this.bus = bus;
+  }
+  get role() {
+    return this.localRole;
+  }
+  async connect(localNodeId, config) {
+    if (this.connected) {
+      throw new TransportError("Transport is already connected");
+    }
+    this.localNodeId = localNodeId;
+    this.localRole = config.localRole ?? "replica";
+    this.localGroupId = config.groupId;
+    this.localPrimaryTerm = config.primaryTerm;
+    this.localProtocolVersion = config.protocolVersion;
+    this.connected = true;
+    this.bus.join(localNodeId, this);
+    for (const peerId of this.bus.peerIds()) {
+      if (peerId === localNodeId) continue;
+      const peerTransport = this.bus.getTransport(peerId);
+      if (!peerTransport || !peerTransport.connected) continue;
+      const peerInfo = {
+        id: peerId,
+        groupId: peerTransport.localGroupId,
+        role: peerTransport.role,
+        primaryTerm: peerTransport.localPrimaryTerm,
+        protocolVersion: peerTransport.localProtocolVersion,
+        joinedAt: Date.now(),
+        lastSeenAt: Date.now(),
+        lastAckedSeq: 0n
+      };
+      this.connectedPeers.set(peerId, peerInfo);
+      const localInfo = {
+        id: localNodeId,
+        groupId: this.localGroupId,
+        role: this.localRole,
+        primaryTerm: this.localPrimaryTerm,
+        protocolVersion: this.localProtocolVersion,
+        joinedAt: Date.now(),
+        lastSeenAt: Date.now(),
+        lastAckedSeq: 0n
+      };
+      peerTransport.connectedPeers.set(localNodeId, localInfo);
+      if (this.peerConnectedHandler) {
+        this.peerConnectedHandler(peerInfo);
+      }
+      if (peerTransport.peerConnectedHandler) {
+        peerTransport.peerConnectedHandler(localInfo);
+      }
+    }
+  }
+  async disconnect() {
+    if (!this.connected) return;
+    this.connected = false;
+    this.bus.leave(this.localNodeId);
+    for (const [peerId] of this.connectedPeers) {
+      const peerTransport = this.bus.getTransport(peerId);
+      if (peerTransport) {
+        peerTransport.connectedPeers.delete(this.localNodeId);
+        if (peerTransport.peerDisconnectedHandler) {
+          peerTransport.peerDisconnectedHandler(this.localNodeId);
+        }
+      }
+    }
+    this.connectedPeers.clear();
+  }
+  async send(peerId, batch) {
+    this.ensureConnected();
+    if (!isValidBatch(batch)) {
+      throw new TransportError("Invalid batch structure");
+    }
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) {
+      throw new TransportError(`Peer '${peerId}' is not connected`);
+    }
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveBatch(batch, fromPeerId).catch(() => {
+      });
+    });
+  }
+  async broadcast(batch) {
+    this.ensureConnected();
+    if (!isValidBatch(batch)) {
+      throw new TransportError("Invalid batch structure");
+    }
+    const fromPeerId = this.localNodeId;
+    for (const [peerId] of this.connectedPeers) {
+      const peer = this.bus.getTransport(peerId);
+      if (peer?.connected) {
+        queueMicrotask(() => {
+          peer._receiveBatch(batch, fromPeerId).catch(() => {
+          });
+        });
+      }
+    }
+  }
+  async sendAck(peerId, ack) {
+    this.ensureConnected();
+    if (!isValidAck(ack)) {
+      throw new TransportError("Invalid ack structure");
+    }
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) {
+      throw new TransportError(`Peer '${peerId}' is not connected`);
+    }
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveAck(ack, fromPeerId);
+    });
+  }
+  async forward(peerId, request) {
+    this.ensureConnected();
+    if (!isValidForwardedTransaction(request)) {
+      throw new TransportError("Invalid forward request structure");
+    }
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) {
+      throw new TransportError(`Peer '${peerId}' is not connected`);
+    }
+    return peer._receiveForward(request, this.localNodeId);
+  }
+  async requestSync(peerId, request) {
+    this.ensureConnected();
+    if (!isValidSyncRequest(request)) throw new TransportError("Invalid sync request structure");
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) throw new TransportError(`Peer '${peerId}' is not connected`);
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveSyncRequest(request, fromPeerId).catch(() => {
+      });
+    });
+  }
+  async sendSyncBatch(peerId, batch) {
+    this.ensureConnected();
+    if (!isValidSyncBatch(batch)) throw new TransportError("Invalid sync batch structure");
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) throw new TransportError(`Peer '${peerId}' is not connected`);
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveSyncBatch(batch, fromPeerId).catch(() => {
+      });
+    });
+  }
+  async sendSyncComplete(peerId, complete) {
+    this.ensureConnected();
+    if (!isValidSyncComplete(complete)) throw new TransportError("Invalid sync complete structure");
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) throw new TransportError(`Peer '${peerId}' is not connected`);
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveSyncComplete(complete, fromPeerId).catch(() => {
+      });
+    });
+  }
+  async sendSyncAck(peerId, ack) {
+    this.ensureConnected();
+    if (!isValidSyncAck(ack)) throw new TransportError("Invalid sync ack structure");
+    const peer = this.bus.getTransport(peerId);
+    if (!peer || !peer.connected) throw new TransportError(`Peer '${peerId}' is not connected`);
+    const fromPeerId = this.localNodeId;
+    queueMicrotask(() => {
+      peer._receiveSyncAck(ack, fromPeerId);
+    });
+  }
+  onBatchReceived(handler) {
+    this.batchHandler = handler;
+  }
+  onAckReceived(handler) {
+    this.ackHandler = handler;
+  }
+  onForwardReceived(handler) {
+    this.forwardHandler = handler;
+  }
+  onSyncRequested(handler) {
+    this.syncRequestHandler = handler;
+  }
+  onSyncBatchReceived(handler) {
+    this.syncBatchHandler = handler;
+  }
+  onSyncCompleteReceived(handler) {
+    this.syncCompleteHandler = handler;
+  }
+  onSyncAckReceived(handler) {
+    this.syncAckHandler = handler;
+  }
+  onPeerConnected(handler) {
+    this.peerConnectedHandler = handler;
+  }
+  onPeerDisconnected(handler) {
+    this.peerDisconnectedHandler = handler;
+  }
+  peers() {
+    return this.connectedPeers;
+  }
+  async _receiveBatch(batch, fromPeerId) {
+    if (this.batchHandler) {
+      await this.batchHandler(batch, fromPeerId);
+    }
+  }
+  _receiveAck(ack, fromPeerId) {
+    if (this.ackHandler) {
+      this.ackHandler(ack, fromPeerId);
+    }
+  }
+  async _receiveForward(request, fromPeerId) {
+    if (!this.forwardHandler) {
+      throw new TransportError("No forward handler registered");
+    }
+    return this.forwardHandler(request, fromPeerId);
+  }
+  async _receiveSyncRequest(request, fromPeerId) {
+    if (this.syncRequestHandler) await this.syncRequestHandler(request, fromPeerId);
+  }
+  async _receiveSyncBatch(batch, fromPeerId) {
+    if (this.syncBatchHandler) await this.syncBatchHandler(batch, fromPeerId);
+  }
+  async _receiveSyncComplete(complete, fromPeerId) {
+    if (this.syncCompleteHandler) await this.syncCompleteHandler(complete, fromPeerId);
+  }
+  _receiveSyncAck(ack, fromPeerId) {
+    if (this.syncAckHandler) this.syncAckHandler(ack, fromPeerId);
+  }
+  ensureConnected() {
+    if (!this.connected) {
+      throw new TransportError("Transport is not connected");
+    }
+  }
+};
+
+export { InMemoryTransport, MemoryBus };