@topgunbuild/client 0.10.1 → 0.12.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, HybridQueryRespPayload, HybridQueryDeltaPayload, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
+import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
 export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
 import pino from 'pino';
 
@@ -606,9 +606,18 @@ interface OperationDroppedEvent {
 /**
  * Connection Provider Types
  *
- * IConnectionProvider abstracts WebSocket connection handling to support
- * both single-server and cluster modes.
+ * IConnectionProvider abstracts connection handling to support
+ * both single-server and cluster modes across WebSocket and HTTP transports.
  */
+/**
+ * Minimal connection interface capturing the actual usage pattern.
+ * Allows transport-agnostic code without depending on the WebSocket global.
+ */
+interface IConnection {
+    send(data: ArrayBuffer | Uint8Array | string): void;
+    close(): void;
+    readonly readyState: number;
+}
 /**
  * Events emitted by IConnectionProvider.
  */
@@ -618,11 +627,13 @@ type ConnectionProviderEvent = 'connected' | 'disconnected' | 'reconnected' | 'm
  */
 type ConnectionEventHandler = (...args: any[]) => void;
 /**
- * Abstract interface for WebSocket connection providers.
+ * Abstract interface for connection providers.
  *
  * Implementations:
  * - SingleServerProvider: Direct connection to a single server
  * - ClusterClient: Multi-node connection pool with partition routing
+ * - HttpSyncProvider: HTTP polling for serverless environments
+ * - AutoConnectionProvider: WebSocket-to-HTTP fallback
  */
 interface IConnectionProvider {
     /**
@@ -638,14 +649,14 @@ interface IConnectionProvider {
      * @param key - The key to route (used for partition-aware routing)
      * @throws Error if not connected
      */
-    getConnection(key: string): WebSocket;
+    getConnection(key: string): IConnection;
     /**
      * Get any available connection.
      * Used for subscriptions, metadata requests, and non-key-specific operations.
      *
      * @throws Error if not connected
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
      * Check if at least one connection is active and ready.
      */
@@ -680,6 +691,25 @@ interface IConnectionProvider {
      * @param key - Optional key for routing (cluster mode)
      */
     send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Send a batch of keyed operations with per-key routing.
+     * Optional -- when implemented (e.g. by ClusterClient), SyncEngine delegates
+     * batch sending here so each operation is routed to the correct partition owner.
+     * When absent, SyncEngine falls back to sending all ops in a single OP_BATCH.
+     *
+     * @param operations - Array of { key, message } pairs where key is the routing key
+     * @returns Map of key -> success boolean
+     */
+    sendBatch?(operations: Array<{
+        key: string;
+        message: any;
+    }>): Map<string, boolean>;
+    /**
+     * Force-close the current connection to trigger reconnection.
+     * Unlike close(), this preserves reconnect behavior so the provider
+     * will automatically attempt to re-establish the connection.
+     */
+    forceReconnect(): void;
     /**
      * Close all connections gracefully.
      */
@@ -691,7 +721,7 @@ interface IConnectionProvider {
 interface SingleServerProviderConfig {
     /** WebSocket URL to connect to */
     url: string;
-    /** Maximum reconnection attempts (default: 10) */
+    /** Maximum reconnection attempts (default: 10). Use Infinity for unlimited. */
     maxReconnectAttempts?: number;
     /** Initial reconnect delay in ms (default: 1000) */
     reconnectDelayMs?: number;
@@ -699,6 +729,8 @@ interface SingleServerProviderConfig {
     backoffMultiplier?: number;
     /** Maximum reconnect delay in ms (default: 30000) */
     maxReconnectDelayMs?: number;
+    /** Listen for browser online/offline events to trigger instant reconnect (default: true) */
+    listenNetworkEvents?: boolean;
 }
 
 /**
@@ -1241,13 +1273,13 @@ declare class SyncEngine {
         matchedTerms?: string[];
     }>>;
     /**
-     * Handle hybrid query response from server.
+     * Handle operation rejected by server (permission denied, validation failure, etc.).
      */
-    handleHybridQueryResponse(payload: HybridQueryRespPayload): void;
+    private handleOpRejected;
     /**
-     * Handle hybrid query delta update from server.
+     * Handle generic error message from server.
      */
-    handleHybridQueryDelta(payload: HybridQueryDeltaPayload): void;
+    private handleError;
 }
 
 interface ILock {
@@ -2150,6 +2182,7 @@ interface ConnectionPoolEvents {
     'node:disconnected': (nodeId: string, reason: string) => void;
     'node:healthy': (nodeId: string) => void;
     'node:unhealthy': (nodeId: string, reason: string) => void;
+    'node:remapped': (oldId: string, newId: string) => void;
     'message': (nodeId: string, message: any) => void;
     'error': (nodeId: string, error: Error) => void;
 }
@@ -2177,20 +2210,25 @@ declare class ConnectionPool {
      * Remove a node from the connection pool
      */
     removeNode(nodeId: string): Promise<void>;
+    /**
+     * Remap a node from one ID to another, preserving the existing connection.
+     * Used when the server-assigned node ID differs from the temporary seed ID.
+     */
+    remapNodeId(oldId: string, newId: string): void;
     /**
      * Get connection for a specific node
      */
-    getConnection(nodeId: string): WebSocket | null;
+    getConnection(nodeId: string): IConnection | null;
     /**
      * Get primary connection (first/seed node)
      */
-    getPrimaryConnection(): WebSocket | null;
+    getPrimaryConnection(): IConnection | null;
     /**
      * Get any healthy connection
      */
     getAnyHealthyConnection(): {
         nodeId: string;
-        socket: WebSocket;
+        connection: IConnection;
     } | null;
     /**
      * Send message to a specific node
@@ -2213,7 +2251,7 @@ declare class ConnectionPool {
      */
     getAllNodes(): string[];
     /**
-     * Check if node is connected and authenticated
+     * Check if node has an open WebSocket connection
      */
     isNodeConnected(nodeId: string): boolean;
     /**
@@ -2290,7 +2328,7 @@ declare class PartitionRouter {
      */
     routeToConnection(key: string): {
         nodeId: string;
-        socket: WebSocket;
+        connection: IConnection;
     } | null;
     /**
      * Get routing info for multiple keys (batch routing)
@@ -2431,6 +2469,8 @@ declare class ClusterClient implements IConnectionProvider {
     private readonly routingMetrics;
     private readonly circuits;
     private readonly circuitBreakerConfig;
+    private partitionMapRequestTimer;
+    private static readonly PARTITION_MAP_REQUEST_DEBOUNCE_MS;
     constructor(config: ClusterClientConfig);
     on(event: string, listener: (...args: any[]) => void): this;
     off(event: string, listener: (...args: any[]) => void): this;
@@ -2446,7 +2486,7 @@ declare class ClusterClient implements IConnectionProvider {
      * Routes to partition owner based on key hash when smart routing is enabled.
      * @throws Error if not connected
      */
-    getConnection(key: string): WebSocket;
+    getConnection(key: string): IConnection;
     /**
      * Get fallback connection when owner is unavailable.
      * @throws Error if no connection available
@@ -2457,9 +2497,15 @@ declare class ClusterClient implements IConnectionProvider {
      * Called when routing to an unknown/disconnected owner.
      */
     private requestPartitionMapRefresh;
+    /**
+     * Debounce partition map requests to prevent flooding when multiple nodes
+     * reconnect simultaneously. Coalesces rapid requests into a single request
+     * sent to the most recently connected node.
+     */
+    private debouncedPartitionMapRequest;
     /**
      * Request partition map from a specific node.
-     * Called on first node connection.
+     * Called on node connection via debounced handler.
      */
     private requestPartitionMapFromNode;
     /**
@@ -2555,6 +2601,10 @@ declare class ClusterClient implements IConnectionProvider {
      * Force refresh of partition map
      */
     refreshPartitionMap(): Promise<void>;
+    /**
+     * Force reconnect all connections in the pool.
+     */
+    forceReconnect(): void;
     /**
      * Shutdown cluster client (IConnectionProvider interface).
      */
@@ -2568,15 +2618,15 @@ declare class ClusterClient implements IConnectionProvider {
      */
     getPartitionRouter(): PartitionRouter;
     /**
-     * Get any healthy WebSocket connection (IConnectionProvider interface).
+     * Get any healthy connection (IConnectionProvider interface).
      * @throws Error if not connected
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
-     * Get any healthy WebSocket connection, or null if none available.
+     * Get any healthy connection, or null if none available.
      * Use this for optional connection checks.
      */
-    getAnyConnectionOrNull(): WebSocket | null;
+    getAnyConnectionOrNull(): IConnection | null;
     /**
      * Get circuit breaker state for a node.
      */
@@ -2625,6 +2675,8 @@ declare class SingleServerProvider implements IConnectionProvider {
     private reconnectTimer;
     private isClosing;
     private listeners;
+    private onlineHandler;
+    private offlineHandler;
     constructor(config: SingleServerProviderConfig);
     /**
      * Connect to the WebSocket server.
@@ -2634,11 +2686,11 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Get connection for a specific key.
      * In single-server mode, key is ignored.
      */
-    getConnection(_key: string): WebSocket;
+    getConnection(_key: string): IConnection;
     /**
      * Get any available connection.
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
      * Check if connected.
      */
@@ -2677,6 +2729,17 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Calculate backoff delay with exponential increase.
      */
     private calculateBackoffDelay;
+    /**
+     * Force-close the current WebSocket and immediately schedule reconnection.
+     * Unlike close(), this does NOT set isClosing and preserves reconnect behavior.
+     * Resets the reconnect counter so the full backoff budget is available.
+     *
+     * Critically, this does NOT wait for the TCP close handshake (which can
+     * hang 20+ seconds on a dead network). Instead it strips all handlers from
+     * the old WebSocket, fires a best-effort close(), nulls the reference, and
+     * schedules reconnect right away.
+     */
+    forceReconnect(): void;
     /**
      * Get the WebSocket URL this provider connects to.
      */
@@ -2690,8 +2753,249 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Called externally after successful authentication.
      */
     resetReconnectAttempts(): void;
+    /**
+     * Listen for browser 'online' event to trigger instant reconnect
+     * when network comes back. Only active in browser environments.
+     */
+    private setupNetworkListeners;
+    /**
+     * Remove browser network event listeners.
+     */
+    private teardownNetworkListeners;
+}
+
+/**
+ * Configuration for HttpSyncProvider.
+ */
+interface HttpSyncProviderConfig {
+    /** HTTP URL of the TopGun server (e.g., 'http://localhost:8080') */
+    url: string;
+    /** Client identifier for the server to track HLC state */
+    clientId: string;
+    /** Hybrid Logical Clock instance for causality tracking */
+    hlc: HLC;
+    /** JWT auth token for Authorization header */
+    authToken?: string;
+    /** Polling interval in milliseconds (default: 5000) */
+    pollIntervalMs?: number;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    requestTimeoutMs?: number;
+    /** Map names to sync deltas for on each poll */
+    syncMaps?: string[];
+    /** Custom fetch implementation for testing or platform compatibility */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * HTTP-based connection provider for serverless environments.
+ *
+ * Implements IConnectionProvider by translating WebSocket-style send() calls
+ * into queued operations that are flushed via HTTP POST /sync at regular
+ * polling intervals. Responses are translated back into synthetic message
+ * events that SyncEngine understands.
+ *
+ * This provider is completely stateless on the server side -- each request
+ * carries the client's HLC state and the server computes deltas without
+ * maintaining per-client state.
+ */
+declare class HttpSyncProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly clientId;
+    private readonly hlc;
+    private readonly pollIntervalMs;
+    private readonly requestTimeoutMs;
+    private readonly syncMaps;
+    private readonly fetchImpl;
+    private authToken;
+    private listeners;
+    private pollTimer;
+    /** Queued operations to send on next poll */
+    private pendingOperations;
+    /** Queued one-shot queries to send on next poll */
+    private pendingQueries;
+    /** Per-map last sync timestamps for delta tracking */
+    private lastSyncTimestamps;
+    /** Whether the last HTTP request succeeded */
+    private connected;
+    /** Whether we were previously connected (for reconnected event) */
+    private wasConnected;
+    constructor(config: HttpSyncProviderConfig);
+    /**
+     * Connect by sending an initial sync request to verify auth and get state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * Returns an HttpConnection that queues operations for the next poll cycle.
+     */
+    getConnection(_key: string): IConnection;
+    /**
+     * Get any available connection.
+     * Returns an HttpConnection that queues operations for the next poll cycle.
+     */
+    getAnyConnection(): IConnection;
+    /**
+     * Check if connected (last HTTP request succeeded).
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Returns ['http'] when connected, [] when not.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send data via the HTTP sync provider.
+     *
+     * Deserializes the msgpackr binary to extract the message type and routes:
+     * - OP_BATCH / CLIENT_OP: queued as operations for next poll
+     * - AUTH: silently ignored (auth via HTTP header)
+     * - SYNC_INIT: silently ignored (HTTP uses timestamp-based deltas)
+     * - QUERY_SUB: queued as one-shot query for next poll
+     * - All other types: silently dropped with debug log
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Force reconnect by restarting the polling loop.
+     */
+    forceReconnect(): void;
+    /**
+     * Close the HTTP sync provider.
+     * Stops the polling loop, clears queued operations, and sets disconnected state.
+     */
+    close(): Promise<void>;
+    /**
+     * Update the auth token (e.g., after token refresh).
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send an HTTP sync request with queued operations and receive deltas.
+     */
+    private doSyncRequest;
+    /**
+     * Start the polling loop.
+     */
+    private startPolling;
+    /**
+     * Stop the polling loop.
+     */
+    private stopPolling;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+}
+
+/**
+ * Configuration for AutoConnectionProvider.
+ */
+interface AutoConnectionProviderConfig {
+    /** Server URL (ws:// or http://) */
+    url: string;
+    /** Client identifier */
+    clientId: string;
+    /** Hybrid Logical Clock instance */
+    hlc: HLC;
+    /** Max WebSocket connection attempts before falling back to HTTP (default: 3) */
+    maxWsAttempts?: number;
+    /** JWT auth token */
+    authToken?: string;
+    /** Skip WebSocket and go HTTP-only */
+    httpOnly?: boolean;
+    /** HTTP polling interval in ms (default: 5000) */
+    httpPollIntervalMs?: number;
+    /** Map names to sync via HTTP */
+    syncMaps?: string[];
+    /** Custom fetch implementation for HTTP mode */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * AutoConnectionProvider implements protocol negotiation by trying WebSocket
+ * first and falling back to HTTP sync when WebSocket connection fails.
+ *
+ * This enables seamless deployment in both traditional server environments
+ * (using WebSockets) and serverless environments (using HTTP polling).
+ */
+declare class AutoConnectionProvider implements IConnectionProvider {
+    private readonly config;
+    private readonly maxWsAttempts;
+    /** The active underlying provider */
+    private activeProvider;
+    /** Whether we're using HTTP mode */
+    private isHttpMode;
+    private listeners;
+    constructor(config: AutoConnectionProviderConfig);
+    /**
+     * Connect using WebSocket first, falling back to HTTP after maxWsAttempts failures.
+     * If httpOnly is true, skips WebSocket entirely.
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect using HTTP sync provider.
+     */
+    private connectHttp;
+    getConnection(key: string): IConnection;
+    getAnyConnection(): IConnection;
+    isConnected(): boolean;
+    getConnectedNodes(): string[];
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Force reconnect by delegating to the active provider.
+     */
+    forceReconnect(): void;
+    /**
+     * Close the active underlying provider.
+     */
+    close(): Promise<void>;
+    /**
+     * Whether currently using HTTP mode.
+     */
+    isUsingHttp(): boolean;
+    /**
+     * Proxy events from the underlying provider to our listeners.
+     */
+    private proxyEvents;
+    /**
+     * Convert a URL to WebSocket URL format.
+     */
+    private toWsUrl;
+    /**
+     * Convert a URL to HTTP URL format.
+     */
+    private toHttpUrl;
+}
+
+/**
+ * Ready-state constants matching the WebSocket spec values.
+ * Allows callers to compare readyState without depending on the WebSocket global.
+ */
+declare const ConnectionReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/**
+ * Thin adapter that wraps a raw WebSocket and exposes only the IConnection
+ * surface. This keeps the concrete WebSocket type out of public return types
+ * while adding zero overhead.
+ */
+declare class WebSocketConnection implements IConnection {
+    private readonly ws;
+    constructor(ws: WebSocket);
+    send(data: ArrayBuffer | Uint8Array | string): void;
+    close(): void;
+    get readyState(): number;
 }
 
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };
+export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, ConnectionReadyState, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnection, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, WebSocketConnection, isValidTransition, logger };