@delali/sirannon-db 0.1.6 → 0.1.8

package/dist/server/index.d.ts

@@ -1,45 +1,57 @@
-import { W as WriteConcern, R as ReadConcern, E as ExecuteResult, d as ServerOptions, e as WSHandlerOptions } from '../types-D-74JiXb.js';
-import { S as Sirannon } from '../sirannon-Cd-lK6T0.js';
-import '../types-BFSsG77t.js';
-import '../database-BVY1GqE7.js';
-import '../types-BeozgNPr.js';
+import { W as WriteConcern, g as BulkLoadDurability, h as BulkLoadResult, R as ReadConcern, E as ExecuteResult, i as ServerOptions, j as WSHandlerOptions } from '../types-D_hQW1hr.js';
+import { S as Sirannon } from '../sirannon-4SspRvP5.js';
+import '../database-DuGp0Rtr.js';
+import '../types-D4p4UyDK.js';
 
-/** Body for POST /db/:id/query */
 interface QueryRequest {
     sql: string;
     params?: Record<string, unknown> | unknown[];
     readConcern?: ReadConcern;
 }
-/** Body for POST /db/:id/execute */
 interface ExecuteRequest {
     sql: string;
     params?: Record<string, unknown> | unknown[];
     writeConcern?: WriteConcern;
 }
-/** A single statement within a transaction batch. */
 interface TransactionStatement {
     sql: string;
     params?: Record<string, unknown> | unknown[];
 }
-/** Body for POST /db/:id/transaction */
 interface TransactionRequest {
     statements: TransactionStatement[];
     writeConcern?: WriteConcern;
 }
-/** Response for a successful query. */
+/** The whole batch commits atomically in one server-side transaction with one fsync. */
+interface BatchRequest {
+    sql: string;
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    writeConcern?: WriteConcern;
+}
 interface QueryResponse {
     rows: Record<string, unknown>[];
 }
-/** Response for a successful execute. */
 interface ExecuteResponse {
     changes: number;
     lastInsertRowId: number | string;
 }
-/** Response for a successful transaction. */
 interface TransactionResponse {
     results: ExecuteResponse[];
 }
-/** Standard error response envelope. */
+interface BatchResponse {
+    results: ExecuteResponse[];
+}
+/**
+ * Loads rows with relaxed writer durability; the configured durability is
+ * restored before the response is sent, and a load interrupted by a crash is
+ * recovered by re-running it.
+ */
+interface LoadRequest {
+    sql: string;
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    durability?: BulkLoadDurability;
+    checkpoint?: boolean;
+}
+type LoadResponse = BulkLoadResult;
 interface ErrorResponse {
     error: {
         code: string;
@@ -47,13 +59,26 @@ interface ErrorResponse {
         details?: Record<string, unknown>;
     };
 }
-/** Inbound WS message types. */
-type WSClientMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSQueryMessage | WSExecuteMessage;
+type WSClientMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSQueryMessage | WSExecuteMessage | WSTransactionMessage | WSBatchMessage | WSLoadMessage;
 interface WSSubscribeMessage {
     type: 'subscribe';
     id: string;
     table: string;
     filter?: Record<string, unknown>;
+    /**
+     * Highest `seq` the client has already processed. When present, the server
+     * replays every retained change with a greater seq before delivering live
+     * events, so a reconnecting subscriber does not miss changes. Sent as a
+     * decimal string to preserve values beyond `Number.MAX_SAFE_INTEGER`.
+     */
+    sinceSeq?: string;
+    /**
+     * The `epoch` the server reported when this cursor was issued. A `sinceSeq`
+     * only means something within the sequence space that produced it, so a
+     * mismatch tells the server the cursor came from another database and it must
+     * resync rather than replay foreign rows against it.
+     */
+    epoch?: string;
 }
 interface WSUnsubscribeMessage {
     type: 'unsubscribe';
@@ -71,11 +96,54 @@ interface WSExecuteMessage {
     sql: string;
     params?: Record<string, unknown> | unknown[];
 }
-/** Outbound WS message types. */
+/**
+ * Runs every statement in one server-side transaction and replies once with
+ * all results. The client is never in the loop between statements, so the
+ * single writer lock is held only for the duration of local execution.
+ */
+interface WSTransactionMessage {
+    type: 'transaction';
+    id: string;
+    statements: TransactionStatement[];
+    writeConcern?: WriteConcern;
+}
+interface WSBatchMessage {
+    type: 'batch';
+    id: string;
+    sql: string;
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    writeConcern?: WriteConcern;
+}
+interface WSLoadMessage {
+    type: 'load';
+    id: string;
+    sql: string;
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    durability?: BulkLoadDurability;
+    checkpoint?: boolean;
+}
 type WSServerMessage = WSSubscribedMessage | WSUnsubscribedMessage | WSChangeMessage | WSResultMessage | WSErrorMessage;
 interface WSSubscribedMessage {
     type: 'subscribed';
     id: string;
+    /**
+     * The seq the subscription is live from. A client that has not yet seen any
+     * change adopts this as its resume cursor, so a reconnect during an idle
+     * spell still replays what it missed instead of silently skipping it.
+     */
+    seq?: string;
+    /**
+     * Set when a requested `sinceSeq` fell below the retained history, so the
+     * gap cannot be replayed. The subscription still starts live from now; the
+     * client must treat its prior state as stale and re-read.
+     */
+    resync?: boolean;
+    /**
+     * Identifies the sequence space this subscription streams from. The client
+     * stores it and echoes it when resuming, so a cursor carried to a different
+     * database forces a resync instead of a silent replay of unrelated rows.
+     */
+    epoch?: string;
 }
 interface WSUnsubscribedMessage {
     type: 'unsubscribed';
@@ -96,7 +164,7 @@ interface WSChangeMessage {
 interface WSResultMessage {
     type: 'result';
     id: string;
-    data: QueryResponse | ExecuteResponse;
+    data: QueryResponse | ExecuteResponse | TransactionResponse | BatchResponse | LoadResponse;
 }
 interface WSErrorMessage {
     type: 'error';
@@ -106,7 +174,6 @@ interface WSErrorMessage {
         message: string;
     };
 }
-/** Convert an ExecuteResult (with possible bigint) to a JSON-safe response. */
 declare function toExecuteResponse(result: ExecuteResult): ExecuteResponse;
 
 declare class SirannonServer {
@@ -121,6 +188,8 @@ declare class SirannonServer {
     private readonly getClusterStatus;
     private readonly sirannon;
     private readonly wsHandler;
+    private readonly maxBodyBytes;
+    private readonly maxWsBackpressureBytes;
     constructor(sirannon: Sirannon, options?: ServerOptions);
     listen(): Promise<void>;
     close(): Promise<void>;
@@ -133,32 +202,46 @@ declare class SirannonServer {
 }
 declare function createServer(sirannon: Sirannon, options?: ServerOptions): SirannonServer;
 
+/**
+ * Result of writing a frame to a WebSocket connection.
+ *
+ * - `sent`: delivered with no backpressure.
+ * - `buffered`: accepted into the socket's outbound buffer under the
+ *   backpressure limit; it will drain over time and must not be resent.
+ * - `dropped`: rejected because it would exceed the backpressure limit, so
+ *   the frame was not delivered. The caller must fail loud rather than treat
+ *   the request as answered.
+ */
+type WSSendOutcome = 'sent' | 'buffered' | 'dropped';
 interface WSConnection {
-    send(data: string): void;
+    send(data: string): WSSendOutcome;
     close(code?: number, reason?: string): void;
 }
+
 declare class WSHandler {
     private readonly sirannon;
     private readonly maxPayloadLength;
     private readonly resolveExecutionTarget;
     private readonly connections;
-    private readonly cdcContexts;
-    private readonly cdcPending;
+    private readonly cdc;
     private closed;
     constructor(sirannon: Sirannon, options?: WSHandlerOptions);
     handleOpen(conn: WSConnection, databaseId: string): Promise<void>;
+    /**
+     * Tears down a connection whose outbound buffer overflowed. Closing lets the
+     * client reject in-flight requests and reconnect; guarding on `overloaded`
+     * keeps a burst of dropped frames from repeatedly re-closing the socket.
+     */
+    handleOverload(conn: WSConnection): void;
     handleMessage(conn: WSConnection, data: string): void;
     handleClose(conn: WSConnection): void;
     get connectionCount(): number;
     close(): Promise<void>;
-    private handleQuery;
-    private handleExecute;
+    private operationContext;
     private handleSubscribe;
+    private subscribeLive;
+    private subscribeResuming;
     private handleUnsubscribe;
-    private ensureCDC;
-    private createCDCContext;
-    private maybeCleanupCDC;
-    private isValidParams;
     private resolveTarget;
     private send;
     private sendError;
@@ -167,4 +250,4 @@ declare class WSHandler {
 }
 declare function createWSHandler(sirannon: Sirannon, options?: WSHandlerOptions): WSHandler;
 
-export { type ErrorResponse, type ExecuteRequest, type ExecuteResponse, type QueryRequest, type QueryResponse, SirannonServer, type TransactionRequest, type TransactionResponse, type TransactionStatement, type WSChangeMessage, type WSClientMessage, type WSConnection, type WSErrorMessage, type WSExecuteMessage, WSHandler, type WSQueryMessage, type WSResultMessage, type WSServerMessage, type WSSubscribeMessage, type WSSubscribedMessage, type WSUnsubscribeMessage, type WSUnsubscribedMessage, createServer, createWSHandler, toExecuteResponse };
+export { type BatchRequest, type BatchResponse, type ErrorResponse, type ExecuteRequest, type ExecuteResponse, type LoadRequest, type LoadResponse, type QueryRequest, type QueryResponse, SirannonServer, type TransactionRequest, type TransactionResponse, type TransactionStatement, type WSBatchMessage, type WSChangeMessage, type WSClientMessage, type WSConnection, type WSErrorMessage, type WSExecuteMessage, WSHandler, type WSLoadMessage, type WSQueryMessage, type WSResultMessage, type WSServerMessage, type WSSubscribeMessage, type WSSubscribedMessage, type WSTransactionMessage, type WSUnsubscribeMessage, type WSUnsubscribedMessage, createServer, createWSHandler, toExecuteResponse };