@topgunbuild/client 0.10.1 → 0.12.0

package/dist/index.mjs

@@ -656,9 +656,7 @@ var WebSocketManager = class {
         timeoutMs: this.config.heartbeatConfig.timeoutMs
       }, "Heartbeat timeout - triggering reconnection");
       this.stopHeartbeat();
-      this.connectionProvider.close().catch((err) => {
-        logger.error({ err }, "Error closing ConnectionProvider on heartbeat timeout");
-      });
+      this.connectionProvider.forceReconnect();
     }
   }
   /**
@@ -1345,7 +1343,7 @@ var LockManager = class {
   /**
    * Handle lock granted message from server.
    */
-  handleLockGranted(requestId, fencingToken) {
+  handleLockGranted(requestId, _name, fencingToken) {
     const req = this.pendingLockRequests.get(requestId);
     if (req) {
       clearTimeout(req.timer);
@@ -1356,7 +1354,7 @@ var LockManager = class {
   /**
    * Handle lock released message from server.
    */
-  handleLockReleased(requestId, success) {
+  handleLockReleased(requestId, _name, success) {
     const req = this.pendingLockRequests.get(requestId);
     if (req) {
       clearTimeout(req.timer);
@@ -1773,6 +1771,8 @@ import { LWWMap } from "@topgunbuild/core";
 var MerkleSyncHandler = class {
   constructor(config) {
     this.lastSyncTimestamp = 0;
+    /** Accumulated sync stats per map, flushed after a quiet period */
+    this.syncStats = /* @__PURE__ */ new Map();
     this.config = config;
   }
   /**
@@ -1794,7 +1794,8 @@ var MerkleSyncHandler = class {
    * Compares root hashes and requests buckets if mismatch detected.
    */
   async handleSyncRespRoot(payload) {
-    const { mapName, rootHash, timestamp } = payload;
+    const { mapName, timestamp } = payload;
+    const rootHash = Number(payload.rootHash);
     const map = this.config.getMap(mapName);
     if (map instanceof LWWMap) {
       const localRootHash = map.getMerkleTree().getRootHash();
@@ -1822,9 +1823,11 @@ var MerkleSyncHandler = class {
     if (map instanceof LWWMap) {
       const tree = map.getMerkleTree();
       const localBuckets = tree.getBuckets(path);
+      let mismatchCount = 0;
       for (const [bucketKey, remoteHash] of Object.entries(buckets)) {
         const localHash = localBuckets[bucketKey] || 0;
         if (localHash !== remoteHash) {
+          mismatchCount++;
           const newPath = path + bucketKey;
           this.config.sendMessage({
             type: "MERKLE_REQ_BUCKET",
@@ -1851,7 +1854,17 @@ var MerkleSyncHandler = class {
         }
       }
       if (updateCount > 0) {
-        logger.info({ mapName, count: updateCount }, "Synced records from server");
+        const existing = this.syncStats.get(mapName);
+        if (existing) {
+          existing.count += updateCount;
+          clearTimeout(existing.timer);
+        }
+        const stats = existing ?? { count: updateCount, timer: void 0 };
+        if (!existing) this.syncStats.set(mapName, stats);
+        stats.timer = setTimeout(() => {
+          logger.info({ mapName, count: stats.count }, "Synced records from server");
+          this.syncStats.delete(mapName);
+        }, 100);
       }
     }
   }
@@ -2134,6 +2147,8 @@ function registerClientMessageHandlers(router, delegates, managers) {
     },
     // SYNC handlers
     "OP_ACK": (msg) => delegates.handleOpAck(msg),
+    "OP_REJECTED": (msg) => delegates.handleOpRejected(msg),
+    "ERROR": (msg) => delegates.handleError(msg),
     "SYNC_RESP_ROOT": (msg) => managers.merkleSyncHandler.handleSyncRespRoot(msg.payload),
     "SYNC_RESP_BUCKETS": (msg) => managers.merkleSyncHandler.handleSyncRespBuckets(msg.payload),
     "SYNC_RESP_LEAF": (msg) => managers.merkleSyncHandler.handleSyncRespLeaf(msg.payload),
@@ -2156,12 +2171,12 @@ function registerClientMessageHandlers(router, delegates, managers) {
     },
     // LOCK handlers
     "LOCK_GRANTED": (msg) => {
-      const { requestId, fencingToken } = msg.payload;
-      managers.lockManager.handleLockGranted(requestId, fencingToken);
+      const { requestId, name, fencingToken } = msg.payload;
+      managers.lockManager.handleLockGranted(requestId, name, fencingToken);
     },
     "LOCK_RELEASED": (msg) => {
-      const { requestId, success } = msg.payload;
-      managers.lockManager.handleLockReleased(requestId, success);
+      const { requestId, name, success } = msg.payload;
+      managers.lockManager.handleLockReleased(requestId, name, success);
     },
     // GC handler
     "GC_PRUNE": (msg) => delegates.handleGcPrune(msg),
@@ -2199,10 +2214,7 @@ function registerClientMessageHandlers(router, delegates, managers) {
       managers.searchClient.handleSearchResponse(msg.payload);
     },
     "SEARCH_UPDATE": () => {
-    },
-    // HYBRID handlers
-    "HYBRID_QUERY_RESP": (msg) => delegates.handleHybridQueryResponse(msg.payload),
-    "HYBRID_QUERY_DELTA": (msg) => delegates.handleHybridQueryDelta(msg.payload)
+    }
   });
 }
 
@@ -2337,8 +2349,8 @@ var SyncEngine = class {
         handleServerEvent: (msg) => this.handleServerEvent(msg),
         handleServerBatchEvent: (msg) => this.handleServerBatchEvent(msg),
         handleGcPrune: (msg) => this.handleGcPrune(msg),
-        handleHybridQueryResponse: (payload) => this.handleHybridQueryResponse(payload),
-        handleHybridQueryDelta: (payload) => this.handleHybridQueryDelta(payload)
+        handleOpRejected: (msg) => this.handleOpRejected(msg),
+        handleError: (msg) => this.handleError(msg)
       },
       {
         topicManager: this.topicManager,
@@ -2491,6 +2503,15 @@ var SyncEngine = class {
     const pending = this.opLog.filter((op) => !op.synced);
     if (pending.length === 0) return;
     logger.info({ count: pending.length }, "Syncing pending operations");
+    const connectionProvider = this.webSocketManager.getConnectionProvider();
+    if (connectionProvider.sendBatch) {
+      const results = connectionProvider.sendBatch(pending.map((op) => ({ key: op.key, message: op })));
+      const failedKeys = [...results.entries()].filter(([, success]) => !success).map(([key]) => key);
+      if (failedKeys.length > 0) {
+        logger.warn({ failedKeys, count: failedKeys.length }, "Some batch operations failed to send");
+      }
+      return;
+    }
     this.sendMessage({
       type: "OP_BATCH",
       payload: {
@@ -2511,7 +2532,7 @@ var SyncEngine = class {
     this.authToken = token;
     this.tokenProvider = null;
     const state = this.stateMachine.getState();
-    if (state === "AUTHENTICATING" /* AUTHENTICATING */ || state === "CONNECTING" /* CONNECTING */) {
+    if (state === "AUTHENTICATING" /* AUTHENTICATING */) {
       this.sendAuth();
     } else if (state === "BACKOFF" /* BACKOFF */ || state === "DISCONNECTED" /* DISCONNECTED */) {
       logger.info("Auth token set during backoff/disconnect. Reconnecting immediately.");
@@ -2616,9 +2637,10 @@ var SyncEngine = class {
       return;
     }
     await this.messageRouter.route(message);
-    if (message.timestamp) {
-      this.hlc.update(message.timestamp);
-      this.lastSyncTimestamp = message.timestamp.millis;
+    const ts = message.timestamp;
+    if (ts && typeof ts === "object" && "millis" in ts && "counter" in ts && "nodeId" in ts) {
+      this.hlc.update(ts);
+      this.lastSyncTimestamp = Number(ts.millis);
       await this.saveOpLog();
     }
   }
@@ -2672,20 +2694,37 @@ var SyncEngine = class {
         this.writeConcernManager.resolveWriteConcernPromise(result.opId, result);
       }
     }
+    const lastIdNum = parseInt(lastId, 10);
     let maxSyncedId = -1;
     let ackedCount = 0;
-    this.opLog.forEach((op) => {
-      if (op.id && op.id <= lastId) {
+    if (!isNaN(lastIdNum)) {
+      this.opLog.forEach((op) => {
+        if (op.id) {
+          const opIdNum = parseInt(op.id, 10);
+          if (!isNaN(opIdNum) && opIdNum <= lastIdNum) {
+            if (!op.synced) {
+              ackedCount++;
+            }
+            op.synced = true;
+            if (opIdNum > maxSyncedId) {
+              maxSyncedId = opIdNum;
+            }
+          }
+        }
+      });
+    } else {
+      logger.warn({ lastId }, "OP_ACK has non-numeric lastId \u2014 marking all pending ops as synced");
+      this.opLog.forEach((op) => {
         if (!op.synced) {
           ackedCount++;
+          op.synced = true;
+          const opIdNum = parseInt(op.id, 10);
+          if (!isNaN(opIdNum) && opIdNum > maxSyncedId) {
+            maxSyncedId = opIdNum;
+          }
         }
-        op.synced = true;
-        const idNum = parseInt(op.id, 10);
-        if (!isNaN(idNum) && idNum > maxSyncedId) {
-          maxSyncedId = idNum;
-        }
-      }
-    });
+      });
+    }
     if (maxSyncedId !== -1) {
       this.storageAdapter.markOpsSynced(maxSyncedId).catch((err) => logger.error({ err }, "Failed to mark ops synced"));
     }
@@ -2702,10 +2741,10 @@ var SyncEngine = class {
     }
   }
   handleQueryUpdate(message) {
-    const { queryId, key, value, type } = message.payload;
+    const { queryId, key, value, changeType } = message.payload;
     const query = this.queryManager.getQueries().get(queryId);
     if (query) {
-      query.onUpdate(key, type === "REMOVE" ? null : value);
+      query.onUpdate(key, changeType === "LEAVE" ? null : value);
     }
   }
   async handleServerEvent(message) {
@@ -3110,31 +3149,24 @@ var SyncEngine = class {
     return this.queryManager.runLocalHybridQuery(mapName, filter);
   }
   /**
-   * Handle hybrid query response from server.
+   * Handle operation rejected by server (permission denied, validation failure, etc.).
    */
-  handleHybridQueryResponse(payload) {
-    const query = this.queryManager.getHybridQuery(payload.subscriptionId);
-    if (query) {
-      query.onResult(payload.results, "server");
-      query.updatePaginationInfo({
-        nextCursor: payload.nextCursor,
-        hasMore: payload.hasMore,
-        cursorStatus: payload.cursorStatus
-      });
-    }
+  handleOpRejected(message) {
+    const { opId, reason, code } = message.payload;
+    logger.warn({ opId, reason, code }, "Operation rejected by server");
+    this.writeConcernManager.resolveWriteConcernPromise(opId, {
+      opId,
+      success: false,
+      achievedLevel: "FIRE_AND_FORGET",
+      error: reason
+    });
   }
   /**
-   * Handle hybrid query delta update from server.
+   * Handle generic error message from server.
    */
-  handleHybridQueryDelta(payload) {
-    const query = this.queryManager.getHybridQuery(payload.subscriptionId);
-    if (query) {
-      if (payload.type === "LEAVE") {
-        query.onUpdate(payload.key, null);
-      } else {
-        query.onUpdate(payload.key, payload.value, payload.score, payload.matchedTerms);
-      }
-    }
+  handleError(message) {
+    const { code, message: errorMessage, details } = message.payload;
+    logger.error({ code, message: errorMessage, details }, "Server error received");
   }
 };
 
@@ -4018,8 +4050,8 @@ var SearchHandle = class {
   handleSearchUpdate(message) {
     if (message.type !== "SEARCH_UPDATE") return;
     if (message.payload?.subscriptionId !== this.subscriptionId) return;
-    const { key, value, score, matchedTerms, type } = message.payload;
-    switch (type) {
+    const { key, value, score, matchedTerms, changeType } = message.payload;
+    switch (changeType) {
       case "ENTER":
         this.results.set(key, {
           key,
@@ -4343,6 +4375,30 @@ import {
   DEFAULT_CONNECTION_POOL_CONFIG
 } from "@topgunbuild/core";
 import { serialize as serialize2, deserialize as deserialize3 } from "@topgunbuild/core";
+
+// src/connection/WebSocketConnection.ts
+var ConnectionReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3
+};
+var WebSocketConnection = class {
+  constructor(ws) {
+    this.ws = ws;
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close() {
+    this.ws.close();
+  }
+  get readyState() {
+    return this.ws.readyState;
+  }
+};
+
+// src/cluster/ConnectionPool.ts
 var ConnectionPool = class {
   constructor(config = {}) {
     this.listeners = /* @__PURE__ */ new Map();
@@ -4414,10 +4470,17 @@ var ConnectionPool = class {
         return;
       }
     }
+    for (const [existingId, existingConn] of this.connections) {
+      if (existingConn.endpoint === endpoint && existingId !== nodeId) {
+        this.remapNodeId(existingId, nodeId);
+        return;
+      }
+    }
     const connection = {
       nodeId,
       endpoint,
       socket: null,
+      cachedConnection: null,
       state: "DISCONNECTED",
       lastSeen: 0,
       latencyMs: 0,
@@ -4452,15 +4515,34 @@ var ConnectionPool = class {
     }
     logger.info({ nodeId }, "Node removed from connection pool");
   }
+  /**
+   * 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, newId) {
+    const connection = this.connections.get(oldId);
+    if (!connection) return;
+    connection.nodeId = newId;
+    this.connections.delete(oldId);
+    this.connections.set(newId, connection);
+    if (this.primaryNodeId === oldId) {
+      this.primaryNodeId = newId;
+    }
+    logger.info({ oldId, newId }, "Node ID remapped");
+    this.emit("node:remapped", oldId, newId);
+  }
   /**
    * Get connection for a specific node
    */
   getConnection(nodeId) {
     const connection = this.connections.get(nodeId);
-    if (!connection || connection.state !== "AUTHENTICATED") {
+    if (!connection || connection.state !== "CONNECTED" && connection.state !== "AUTHENTICATED" || !connection.socket) {
       return null;
     }
-    return connection.socket;
+    if (!connection.cachedConnection) {
+      connection.cachedConnection = new WebSocketConnection(connection.socket);
+    }
+    return connection.cachedConnection;
   }
   /**
    * Get primary connection (first/seed node)
@@ -4474,8 +4556,11 @@ var ConnectionPool = class {
    */
   getAnyHealthyConnection() {
     for (const [nodeId, conn] of this.connections) {
-      if (conn.state === "AUTHENTICATED" && conn.socket) {
-        return { nodeId, socket: conn.socket };
+      if ((conn.state === "CONNECTED" || conn.state === "AUTHENTICATED") && conn.socket) {
+        if (!conn.cachedConnection) {
+          conn.cachedConnection = new WebSocketConnection(conn.socket);
+        }
+        return { nodeId, connection: conn.cachedConnection };
       }
     }
     return null;
@@ -4531,7 +4616,7 @@ var ConnectionPool = class {
    * Get list of connected node IDs
    */
   getConnectedNodes() {
-    return Array.from(this.connections.entries()).filter(([_, conn]) => conn.state === "AUTHENTICATED").map(([nodeId]) => nodeId);
+    return Array.from(this.connections.entries()).filter(([_, conn]) => conn.state === "CONNECTED" || conn.state === "AUTHENTICATED").map(([nodeId]) => nodeId);
   }
   /**
    * Get all node IDs
@@ -4540,11 +4625,11 @@ var ConnectionPool = class {
     return Array.from(this.connections.keys());
   }
   /**
-   * Check if node is connected and authenticated
+   * Check if node has an open WebSocket connection
    */
   isNodeConnected(nodeId) {
     const conn = this.connections.get(nodeId);
-    return conn?.state === "AUTHENTICATED";
+    return conn?.state === "CONNECTED" || conn?.state === "AUTHENTICATED";
   }
   /**
    * Check if connected to a specific node.
@@ -4609,25 +4694,26 @@ var ConnectionPool = class {
       };
       socket.onmessage = (event) => {
         connection.lastSeen = Date.now();
-        this.handleMessage(nodeId, event);
+        this.handleMessage(connection.nodeId, event);
       };
       socket.onerror = (error) => {
-        logger.error({ nodeId, error }, "WebSocket error");
-        this.emit("error", nodeId, error instanceof Error ? error : new Error("WebSocket error"));
+        logger.error({ nodeId: connection.nodeId, error }, "WebSocket error");
+        this.emit("error", connection.nodeId, error instanceof Error ? error : new Error("WebSocket error"));
       };
       socket.onclose = () => {
         const wasConnected = connection.state === "AUTHENTICATED";
         connection.state = "DISCONNECTED";
         connection.socket = null;
+        connection.cachedConnection = null;
         if (wasConnected) {
-          this.emit("node:disconnected", nodeId, "Connection closed");
+          this.emit("node:disconnected", connection.nodeId, "Connection closed");
         }
-        this.scheduleReconnect(nodeId);
+        this.scheduleReconnect(connection.nodeId);
       };
     } catch (error) {
       connection.state = "FAILED";
-      logger.error({ nodeId, error }, "Failed to connect");
-      this.scheduleReconnect(nodeId);
+      logger.error({ nodeId: connection.nodeId, error }, "Failed to connect");
+      this.scheduleReconnect(connection.nodeId);
     }
   }
   sendAuth(connection) {
@@ -4656,18 +4742,15 @@ var ConnectionPool = class {
       logger.info({ nodeId }, "Authenticated with node");
       this.emit("node:healthy", nodeId);
       this.flushPendingMessages(connection);
-      return;
     }
     if (message.type === "AUTH_REQUIRED") {
       if (this.authToken) {
         this.sendAuth(connection);
       }
-      return;
     }
     if (message.type === "AUTH_FAIL") {
       logger.error({ nodeId, error: message.error }, "Authentication failed");
       connection.state = "FAILED";
-      return;
     }
     if (message.type === "PONG") {
       if (message.timestamp) {
@@ -4675,10 +4758,6 @@ var ConnectionPool = class {
       }
       return;
     }
-    if (message.type === "PARTITION_MAP" || message.type === "PARTITION_MAP_DELTA") {
-      this.emit("message", nodeId, message);
-      return;
-    }
     this.emit("message", nodeId, message);
   }
   flushPendingMessages(connection) {
@@ -4849,17 +4928,17 @@ var PartitionRouter = class {
       }
       return null;
     }
-    const socket = this.connectionPool.getConnection(routing.nodeId);
-    if (socket) {
-      return { nodeId: routing.nodeId, socket };
+    const connection = this.connectionPool.getConnection(routing.nodeId);
+    if (connection) {
+      return { nodeId: routing.nodeId, connection };
     }
     const partition = this.partitionMap.partitions.find((p) => p.partitionId === routing.partitionId);
     if (partition) {
       for (const backupId of partition.backupNodeIds) {
-        const backupSocket = this.connectionPool.getConnection(backupId);
-        if (backupSocket) {
+        const backupConnection = this.connectionPool.getConnection(backupId);
+        if (backupConnection) {
           logger.debug({ key, owner: routing.nodeId, backup: backupId }, "Using backup node");
-          return { nodeId: backupId, socket: backupSocket };
+          return { nodeId: backupId, connection: backupConnection };
         }
       }
     }
@@ -5135,7 +5214,7 @@ var PartitionRouter = class {
 };
 
 // src/cluster/ClusterClient.ts
-var ClusterClient = class {
+var _ClusterClient = class _ClusterClient {
   constructor(config) {
     this.listeners = /* @__PURE__ */ new Map();
     this.initialized = false;
@@ -5148,6 +5227,8 @@ var ClusterClient = class {
     };
     // Circuit breaker state per node
     this.circuits = /* @__PURE__ */ new Map();
+    // Debounce timer for partition map requests on reconnect
+    this.partitionMapRequestTimer = null;
     this.config = config;
     this.circuitBreakerConfig = {
       ...DEFAULT_CIRCUIT_BREAKER_CONFIG,
@@ -5239,14 +5320,14 @@ var ClusterClient = class {
       this.requestPartitionMapRefresh();
       return this.getFallbackConnection();
     }
-    const socket = this.connectionPool.getConnection(owner);
-    if (!socket) {
+    const connection = this.connectionPool.getConnection(owner);
+    if (!connection) {
       this.routingMetrics.fallbackRoutes++;
       logger.debug({ key, owner }, "Could not get connection to owner, using fallback");
       return this.getFallbackConnection();
     }
     this.routingMetrics.directRoutes++;
-    return socket;
+    return connection;
   }
   /**
    * Get fallback connection when owner is unavailable.
@@ -5254,10 +5335,10 @@ var ClusterClient = class {
    */
   getFallbackConnection() {
     const conn = this.connectionPool.getAnyHealthyConnection();
-    if (!conn?.socket) {
+    if (!conn?.connection) {
       throw new Error("No healthy connection available");
     }
-    return conn.socket;
+    return conn.connection;
   }
   /**
    * Request a partition map refresh in the background.
@@ -5268,9 +5349,23 @@ var ClusterClient = class {
       logger.error({ err }, "Failed to refresh partition map");
     });
   }
+  /**
+   * 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.
+   */
+  debouncedPartitionMapRequest(nodeId) {
+    if (this.partitionMapRequestTimer) {
+      clearTimeout(this.partitionMapRequestTimer);
+    }
+    this.partitionMapRequestTimer = setTimeout(() => {
+      this.partitionMapRequestTimer = null;
+      this.requestPartitionMapFromNode(nodeId);
+    }, _ClusterClient.PARTITION_MAP_REQUEST_DEBOUNCE_MS);
+  }
   /**
    * Request partition map from a specific node.
-   * Called on first node connection.
+   * Called on node connection via debounced handler.
    */
   requestPartitionMapFromNode(nodeId) {
     const socket = this.connectionPool.getConnection(nodeId);
@@ -5439,8 +5534,8 @@ var ClusterClient = class {
    * Send directly to partition owner
    */
   sendDirect(key, message) {
-    const connection = this.partitionRouter.routeToConnection(key);
-    if (!connection) {
+    const route = this.partitionRouter.routeToConnection(key);
+    if (!route) {
       logger.warn({ key }, "No route available for key");
       return false;
     }
@@ -5451,7 +5546,7 @@ var ClusterClient = class {
         mapVersion: this.partitionRouter.getMapVersion()
       }
     };
-    connection.socket.send(serialize3(routedMessage));
+    route.connection.send(serialize3(routedMessage));
     return true;
   }
   /**
@@ -5555,10 +5650,23 @@ var ClusterClient = class {
   async refreshPartitionMap() {
     await this.partitionRouter.refreshPartitionMap();
   }
+  /**
+   * Force reconnect all connections in the pool.
+   */
+  forceReconnect() {
+    this.connectionPool.close();
+    this.connect().catch((err) => {
+      logger.error({ err }, "ClusterClient forceReconnect failed");
+    });
+  }
   /**
    * Shutdown cluster client (IConnectionProvider interface).
    */
   async close() {
+    if (this.partitionMapRequestTimer) {
+      clearTimeout(this.partitionMapRequestTimer);
+      this.partitionMapRequestTimer = null;
+    }
     this.partitionRouter.close();
     this.connectionPool.close();
     this.initialized = false;
@@ -5581,23 +5689,23 @@ var ClusterClient = class {
     return this.partitionRouter;
   }
   /**
-   * Get any healthy WebSocket connection (IConnectionProvider interface).
+   * Get any healthy connection (IConnectionProvider interface).
    * @throws Error if not connected
    */
   getAnyConnection() {
     const conn = this.connectionPool.getAnyHealthyConnection();
-    if (!conn?.socket) {
+    if (!conn?.connection) {
       throw new Error("No healthy connection available");
     }
-    return conn.socket;
+    return conn.connection;
   }
   /**
-   * 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() {
     const conn = this.connectionPool.getAnyHealthyConnection();
-    return conn?.socket ?? null;
+    return conn?.connection ?? null;
   }
   // ============================================
   // Circuit Breaker Methods
@@ -5688,9 +5796,7 @@ var ClusterClient = class {
   setupEventHandlers() {
     this.connectionPool.on("node:connected", (nodeId) => {
       logger.debug({ nodeId }, "Node connected");
-      if (this.partitionRouter.getMapVersion() === 0) {
-        this.requestPartitionMapFromNode(nodeId);
-      }
+      this.debouncedPartitionMapRequest(nodeId);
       if (this.connectionPool.getConnectedNodes().length === 1) {
         this.emit("connected");
       }
@@ -5745,6 +5851,8 @@ var ClusterClient = class {
     });
   }
 };
+_ClusterClient.PARTITION_MAP_REQUEST_DEBOUNCE_MS = 500;
+var ClusterClient = _ClusterClient;
 
 // src/connection/SingleServerProvider.ts
 var DEFAULT_CONFIG = {
@@ -5760,14 +5868,18 @@ var SingleServerProvider = class {
     this.reconnectTimer = null;
     this.isClosing = false;
     this.listeners = /* @__PURE__ */ new Map();
+    this.onlineHandler = null;
+    this.offlineHandler = null;
     this.url = config.url;
     this.config = {
       url: config.url,
       maxReconnectAttempts: config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts,
       reconnectDelayMs: config.reconnectDelayMs ?? DEFAULT_CONFIG.reconnectDelayMs,
       backoffMultiplier: config.backoffMultiplier ?? DEFAULT_CONFIG.backoffMultiplier,
-      maxReconnectDelayMs: config.maxReconnectDelayMs ?? DEFAULT_CONFIG.maxReconnectDelayMs
+      maxReconnectDelayMs: config.maxReconnectDelayMs ?? DEFAULT_CONFIG.maxReconnectDelayMs,
+      listenNetworkEvents: config.listenNetworkEvents ?? true
     };
+    this.setupNetworkListeners();
   }
   /**
    * Connect to the WebSocket server.
@@ -5776,6 +5888,9 @@ var SingleServerProvider = class {
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
       return;
     }
+    if (typeof globalThis.navigator !== "undefined" && globalThis.navigator.onLine === false) {
+      throw new Error("Browser is offline \u2014 skipping connection attempt");
+    }
     this.isClosing = false;
     return new Promise((resolve, reject) => {
       try {
@@ -5828,7 +5943,7 @@ var SingleServerProvider = class {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       throw new Error("Not connected");
     }
-    return this.ws;
+    return new WebSocketConnection(this.ws);
   }
   /**
    * Get any available connection.
@@ -5879,6 +5994,7 @@ var SingleServerProvider = class {
    */
   async close() {
     this.isClosing = true;
+    this.teardownNetworkListeners();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -5917,6 +6033,10 @@ var SingleServerProvider = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    if (typeof globalThis.navigator !== "undefined" && globalThis.navigator.onLine === false && this.config.listenNetworkEvents) {
+      logger.info({ url: this.url }, "Browser offline \u2014 waiting for online event instead of polling");
+      return;
+    }
     if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
       logger.error(
         { attempts: this.reconnectAttempts, url: this.url },
@@ -5952,6 +6072,37 @@ var SingleServerProvider = class {
     delay = delay * (0.5 + Math.random());
     return Math.floor(delay);
   }
+  /**
+   * 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() {
+    this.reconnectAttempts = 0;
+    this.isClosing = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onopen = null;
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      this.ws.onmessage = null;
+      try {
+        this.ws.close();
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.emit("disconnected", "default");
+    this.scheduleReconnect();
+  }
   /**
    * Get the WebSocket URL this provider connects to.
    */
@@ -5971,6 +6122,43 @@ var SingleServerProvider = class {
   resetReconnectAttempts() {
     this.reconnectAttempts = 0;
   }
+  /**
+   * Listen for browser 'online' event to trigger instant reconnect
+   * when network comes back. Only active in browser environments.
+   */
+  setupNetworkListeners() {
+    if (!this.config.listenNetworkEvents) return;
+    if (typeof globalThis.addEventListener !== "function") return;
+    this.onlineHandler = () => {
+      if (this.isClosing) return;
+      if (this.isConnected()) return;
+      logger.info({ url: this.url }, "Network online detected \u2014 forcing reconnect");
+      this.forceReconnect();
+    };
+    this.offlineHandler = () => {
+      if (this.isClosing) return;
+      if (!this.isConnected()) return;
+      logger.info({ url: this.url }, "Network offline detected \u2014 disconnecting immediately");
+      this.forceReconnect();
+    };
+    globalThis.addEventListener("online", this.onlineHandler);
+    globalThis.addEventListener("offline", this.offlineHandler);
+  }
+  /**
+   * Remove browser network event listeners.
+   */
+  teardownNetworkListeners() {
+    if (typeof globalThis.removeEventListener === "function") {
+      if (this.onlineHandler) {
+        globalThis.removeEventListener("online", this.onlineHandler);
+        this.onlineHandler = null;
+      }
+      if (this.offlineHandler) {
+        globalThis.removeEventListener("offline", this.offlineHandler);
+        this.offlineHandler = null;
+      }
+    }
+  }
 };
 
 // src/TopGunClient.ts
@@ -6028,7 +6216,13 @@ var TopGunClient = class {
       });
       logger.info({ seeds: this.clusterConfig.seeds }, "TopGunClient initialized in cluster mode");
     } else {
-      const singleServerProvider = new SingleServerProvider({ url: config.serverUrl });
+      const singleServerProvider = new SingleServerProvider({
+        url: config.serverUrl,
+        maxReconnectAttempts: config.backoff?.maxRetries,
+        reconnectDelayMs: config.backoff?.initialDelayMs,
+        backoffMultiplier: config.backoff?.multiplier,
+        maxReconnectDelayMs: config.backoff?.maxDelayMs
+      });
       this.syncEngine = new SyncEngine({
         nodeId: this.nodeId,
         connectionProvider: singleServerProvider,
@@ -7075,16 +7269,512 @@ var EncryptedStorageAdapter = class {
 
 // src/index.ts
 import { LWWMap as LWWMap4, Predicates } from "@topgunbuild/core";
+
+// src/connection/HttpSyncProvider.ts
+import { serialize as serialize5, deserialize as deserialize5 } from "@topgunbuild/core";
+var HttpConnection = class {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  send(data) {
+    if (typeof data === "string") {
+      const encoder = new TextEncoder();
+      this.provider.send(encoder.encode(data));
+    } else {
+      this.provider.send(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+    }
+  }
+  close() {
+  }
+  get readyState() {
+    return this.provider.isConnected() ? ConnectionReadyState.OPEN : ConnectionReadyState.CLOSED;
+  }
+};
+var HttpSyncProvider = class {
+  constructor(config) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.pollTimer = null;
+    /** Queued operations to send on next poll */
+    this.pendingOperations = [];
+    /** Queued one-shot queries to send on next poll */
+    this.pendingQueries = [];
+    /** Per-map last sync timestamps for delta tracking */
+    this.lastSyncTimestamps = /* @__PURE__ */ new Map();
+    /** Whether the last HTTP request succeeded */
+    this.connected = false;
+    /** Whether we were previously connected (for reconnected event) */
+    this.wasConnected = false;
+    this.url = config.url.replace(/\/$/, "");
+    this.clientId = config.clientId;
+    this.hlc = config.hlc;
+    this.authToken = config.authToken || "";
+    this.pollIntervalMs = config.pollIntervalMs ?? 5e3;
+    this.requestTimeoutMs = config.requestTimeoutMs ?? 3e4;
+    this.syncMaps = config.syncMaps || [];
+    this.fetchImpl = config.fetchImpl || globalThis.fetch.bind(globalThis);
+  }
+  /**
+   * Connect by sending an initial sync request to verify auth and get state.
+   */
+  async connect() {
+    try {
+      await this.doSyncRequest();
+      this.connected = true;
+      this.wasConnected = true;
+      this.emit("connected", "http");
+      this.startPolling();
+    } catch (err) {
+      this.connected = false;
+      this.emit("error", err);
+      throw err;
+    }
+  }
+  /**
+   * Get connection for a specific key.
+   * Returns an HttpConnection that queues operations for the next poll cycle.
+   */
+  getConnection(_key) {
+    return new HttpConnection(this);
+  }
+  /**
+   * Get any available connection.
+   * Returns an HttpConnection that queues operations for the next poll cycle.
+   */
+  getAnyConnection() {
+    return new HttpConnection(this);
+  }
+  /**
+   * Check if connected (last HTTP request succeeded).
+   */
+  isConnected() {
+    return this.connected;
+  }
+  /**
+   * Get connected node IDs.
+   * Returns ['http'] when connected, [] when not.
+   */
+  getConnectedNodes() {
+    return this.connected ? ["http"] : [];
+  }
+  /**
+   * Subscribe to connection events.
+   */
+  on(event, handler2) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler2);
+  }
+  /**
+   * Unsubscribe from connection events.
+   */
+  off(event, handler2) {
+    this.listeners.get(event)?.delete(handler2);
+  }
+  /**
+   * 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, _key) {
+    try {
+      const message = deserialize5(
+        data instanceof ArrayBuffer ? new Uint8Array(data) : data
+      );
+      switch (message.type) {
+        case "OP_BATCH":
+          if (message.payload?.ops) {
+            this.pendingOperations.push(...message.payload.ops);
+          }
+          break;
+        case "CLIENT_OP":
+          if (message.payload) {
+            this.pendingOperations.push(message.payload);
+          }
+          break;
+        case "AUTH":
+          break;
+        case "SYNC_INIT":
+          break;
+        case "QUERY_SUB":
+          if (message.payload) {
+            this.pendingQueries.push({
+              queryId: message.payload.requestId || `q-${Date.now()}`,
+              mapName: message.payload.mapName || message.mapName,
+              filter: message.payload.query?.where || message.payload.where,
+              limit: message.payload.query?.limit || message.payload.limit
+            });
+          }
+          break;
+        default:
+          logger.debug(
+            { type: message.type },
+            "HTTP sync provider: unsupported message type dropped"
+          );
+          break;
+      }
+    } catch (err) {
+      logger.warn({ err }, "HTTP sync provider: failed to deserialize message");
+    }
+  }
+  /**
+   * Force reconnect by restarting the polling loop.
+   */
+  forceReconnect() {
+    this.stopPolling();
+    this.connected = false;
+    this.emit("disconnected", "default");
+    this.connect().catch((err) => {
+      logger.error({ err }, "HttpSyncProvider forceReconnect failed");
+    });
+  }
+  /**
+   * Close the HTTP sync provider.
+   * Stops the polling loop, clears queued operations, and sets disconnected state.
+   */
+  async close() {
+    this.stopPolling();
+    this.pendingOperations = [];
+    this.pendingQueries = [];
+    this.connected = false;
+    logger.info({ url: this.url }, "HttpSyncProvider closed");
+  }
+  /**
+   * Update the auth token (e.g., after token refresh).
+   */
+  setAuthToken(token) {
+    this.authToken = token;
+  }
+  /**
+   * Send an HTTP sync request with queued operations and receive deltas.
+   */
+  async doSyncRequest() {
+    const syncMaps = this.syncMaps.map((mapName) => ({
+      mapName,
+      lastSyncTimestamp: this.lastSyncTimestamps.get(mapName) || {
+        millis: 0,
+        counter: 0,
+        nodeId: ""
+      }
+    }));
+    const operations = this.pendingOperations.splice(0);
+    const queries = this.pendingQueries.splice(0);
+    const requestBody = {
+      clientId: this.clientId,
+      clientHlc: this.hlc.now()
+    };
+    if (operations.length > 0) {
+      requestBody.operations = operations;
+    }
+    if (syncMaps.length > 0) {
+      requestBody.syncMaps = syncMaps;
+    }
+    if (queries.length > 0) {
+      requestBody.queries = queries;
+    }
+    const bodyBytes = serialize5(requestBody);
+    const bodyBuffer = new ArrayBuffer(bodyBytes.byteLength);
+    new Uint8Array(bodyBuffer).set(bodyBytes);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+    try {
+      const response = await this.fetchImpl(`${this.url}/sync`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-msgpack",
+          "Authorization": `Bearer ${this.authToken}`
+        },
+        body: bodyBuffer,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        throw new Error(`HTTP sync request failed: ${response.status} ${response.statusText}`);
+      }
+      const responseBuffer = await response.arrayBuffer();
+      const syncResponse = deserialize5(new Uint8Array(responseBuffer));
+      if (syncResponse.serverHlc) {
+        this.hlc.update(syncResponse.serverHlc);
+      }
+      if (syncResponse.ack) {
+        this.emit("message", "http", serialize5({
+          type: "OP_ACK",
+          payload: syncResponse.ack
+        }));
+      }
+      if (syncResponse.deltas) {
+        for (const delta of syncResponse.deltas) {
+          this.lastSyncTimestamps.set(delta.mapName, delta.serverSyncTimestamp);
+          for (const record of delta.records) {
+            this.emit("message", "http", serialize5({
+              type: "SERVER_EVENT",
+              payload: {
+                mapName: delta.mapName,
+                key: record.key,
+                record: record.record,
+                eventType: record.eventType
+              }
+            }));
+          }
+        }
+      }
+      if (syncResponse.queryResults) {
+        for (const result of syncResponse.queryResults) {
+          this.emit("message", "http", serialize5({
+            type: "QUERY_RESP",
+            payload: {
+              requestId: result.queryId,
+              results: result.results,
+              hasMore: result.hasMore,
+              nextCursor: result.nextCursor
+            }
+          }));
+        }
+      }
+      if (!this.connected) {
+        this.connected = true;
+        if (this.wasConnected) {
+          this.emit("reconnected", "http");
+        } else {
+          this.wasConnected = true;
+          this.emit("connected", "http");
+        }
+      }
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (this.connected) {
+        this.connected = false;
+        this.emit("disconnected", "http");
+      }
+      if (operations.length > 0) {
+        this.pendingOperations.unshift(...operations);
+      }
+      if (queries.length > 0) {
+        this.pendingQueries.unshift(...queries);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Start the polling loop.
+   */
+  startPolling() {
+    if (this.pollTimer) return;
+    this.pollTimer = setInterval(async () => {
+      try {
+        await this.doSyncRequest();
+      } catch (err) {
+        logger.debug({ err }, "HTTP sync poll failed");
+      }
+    }, this.pollIntervalMs);
+  }
+  /**
+   * Stop the polling loop.
+   */
+  stopPolling() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+  /**
+   * Emit an event to all listeners.
+   */
+  emit(event, ...args) {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      for (const handler2 of handlers) {
+        try {
+          handler2(...args);
+        } catch (err) {
+          logger.error({ err, event }, "Error in HttpSyncProvider event handler");
+        }
+      }
+    }
+  }
+};
+
+// src/connection/AutoConnectionProvider.ts
+var AutoConnectionProvider = class {
+  constructor(config) {
+    /** The active underlying provider */
+    this.activeProvider = null;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.config = config;
+    this.maxWsAttempts = config.maxWsAttempts ?? 3;
+    this.isHttpMode = config.httpOnly ?? false;
+  }
+  /**
+   * Connect using WebSocket first, falling back to HTTP after maxWsAttempts failures.
+   * If httpOnly is true, skips WebSocket entirely.
+   */
+  async connect() {
+    if (this.isHttpMode) {
+      await this.connectHttp();
+      return;
+    }
+    const wsUrl = this.toWsUrl(this.config.url);
+    let lastError = null;
+    for (let attempt = 0; attempt < this.maxWsAttempts; attempt++) {
+      try {
+        const wsProvider = new SingleServerProvider({
+          url: wsUrl,
+          maxReconnectAttempts: 1,
+          reconnectDelayMs: 1e3
+        });
+        await wsProvider.connect();
+        this.activeProvider = wsProvider;
+        this.proxyEvents(wsProvider);
+        logger.info({ url: wsUrl }, "AutoConnectionProvider: WebSocket connected");
+        return;
+      } catch (err) {
+        lastError = err;
+        logger.debug(
+          { attempt: attempt + 1, maxAttempts: this.maxWsAttempts, err: err.message },
+          "AutoConnectionProvider: WebSocket attempt failed"
+        );
+      }
+    }
+    logger.info(
+      { wsAttempts: this.maxWsAttempts, url: this.config.url },
+      "AutoConnectionProvider: WebSocket failed, falling back to HTTP"
+    );
+    this.isHttpMode = true;
+    await this.connectHttp();
+  }
+  /**
+   * Connect using HTTP sync provider.
+   */
+  async connectHttp() {
+    const httpUrl = this.toHttpUrl(this.config.url);
+    const httpProvider = new HttpSyncProvider({
+      url: httpUrl,
+      clientId: this.config.clientId,
+      hlc: this.config.hlc,
+      authToken: this.config.authToken,
+      pollIntervalMs: this.config.httpPollIntervalMs,
+      syncMaps: this.config.syncMaps,
+      fetchImpl: this.config.fetchImpl
+    });
+    this.activeProvider = httpProvider;
+    this.proxyEvents(httpProvider);
+    await httpProvider.connect();
+    logger.info({ url: httpUrl }, "AutoConnectionProvider: HTTP connected");
+  }
+  getConnection(key) {
+    if (!this.activeProvider) {
+      throw new Error("Not connected");
+    }
+    return this.activeProvider.getConnection(key);
+  }
+  getAnyConnection() {
+    if (!this.activeProvider) {
+      throw new Error("Not connected");
+    }
+    return this.activeProvider.getAnyConnection();
+  }
+  isConnected() {
+    return this.activeProvider?.isConnected() ?? false;
+  }
+  getConnectedNodes() {
+    return this.activeProvider?.getConnectedNodes() ?? [];
+  }
+  on(event, handler2) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler2);
+    if (this.activeProvider) {
+      this.activeProvider.on(event, handler2);
+    }
+  }
+  off(event, handler2) {
+    this.listeners.get(event)?.delete(handler2);
+    if (this.activeProvider) {
+      this.activeProvider.off(event, handler2);
+    }
+  }
+  send(data, key) {
+    if (!this.activeProvider) {
+      throw new Error("Not connected");
+    }
+    this.activeProvider.send(data, key);
+  }
+  /**
+   * Force reconnect by delegating to the active provider.
+   */
+  forceReconnect() {
+    if (this.activeProvider) {
+      this.activeProvider.forceReconnect();
+    }
+  }
+  /**
+   * Close the active underlying provider.
+   */
+  async close() {
+    if (this.activeProvider) {
+      await this.activeProvider.close();
+      this.activeProvider = null;
+    }
+  }
+  /**
+   * Whether currently using HTTP mode.
+   */
+  isUsingHttp() {
+    return this.isHttpMode;
+  }
+  /**
+   * Proxy events from the underlying provider to our listeners.
+   */
+  proxyEvents(provider) {
+    const events = [
+      "connected",
+      "disconnected",
+      "reconnected",
+      "message",
+      "partitionMapUpdated",
+      "error"
+    ];
+    for (const event of events) {
+      const handlers = this.listeners.get(event);
+      if (handlers) {
+        for (const handler2 of handlers) {
+          provider.on(event, handler2);
+        }
+      }
+    }
+  }
+  /**
+   * Convert a URL to WebSocket URL format.
+   */
+  toWsUrl(url) {
+    return url.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
+  }
+  /**
+   * Convert a URL to HTTP URL format.
+   */
+  toHttpUrl(url) {
+    return url.replace(/^ws:\/\//, "http://").replace(/^wss:\/\//, "https://");
+  }
+};
 export {
+  AutoConnectionProvider,
   BackpressureError,
   ChangeTracker,
   ClusterClient,
   ConflictResolverClient,
   ConnectionPool,
+  ConnectionReadyState,
   DEFAULT_BACKPRESSURE_CONFIG,
   DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
   EventJournalReader,
+  HttpSyncProvider,
   HybridQueryHandle,
   IDBAdapter,
   LWWMap4 as LWWMap,
@@ -7101,6 +7791,7 @@ export {
   TopGunClient,
   TopicHandle,
   VALID_TRANSITIONS,
+  WebSocketConnection,
   isValidTransition,
   logger
 };