@topgunbuild/client 0.11.0 → 0.13.0

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   ClusterClient: () => ClusterClient,
   ConflictResolverClient: () => ConflictResolverClient,
   ConnectionPool: () => ConnectionPool,
+  ConnectionReadyState: () => ConnectionReadyState,
   DEFAULT_BACKPRESSURE_CONFIG: () => DEFAULT_BACKPRESSURE_CONFIG,
   DEFAULT_CLUSTER_CONFIG: () => DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter: () => EncryptedStorageAdapter,
@@ -57,6 +58,7 @@ __export(index_exports, {
   TopGunClient: () => TopGunClient,
   TopicHandle: () => TopicHandle,
   VALID_TRANSITIONS: () => VALID_TRANSITIONS,
+  WebSocketConnection: () => WebSocketConnection,
   isValidTransition: () => isValidTransition,
   logger: () => logger
 });
@@ -720,9 +722,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();
     }
   }
   /**
@@ -1015,14 +1015,17 @@ var QueryManager = class {
   }
   /**
    * Send query subscription message to server.
+   * Includes field projection when specified in the query filter.
    */
   sendQuerySubscription(query) {
+    const filter = query.getFilter();
     this.config.sendMessage({
       type: "QUERY_SUB",
       payload: {
         queryId: query.id,
         mapName: query.getMapName(),
-        query: query.getFilter()
+        query: filter,
+        fields: filter.fields
       }
     });
   }
@@ -1192,6 +1195,16 @@ var QueryManager = class {
     logger.debug({ queryCount: this.queries.size, hybridCount: this.hybridQueries.size }, "QueryManager: resubscribing all queries");
     for (const query of this.queries.values()) {
       this.sendQuerySubscription(query);
+      const filter = query.getFilter();
+      if (filter.fields && filter.fields.length > 0 && query.merkleRootHash !== 0) {
+        this.config.sendMessage({
+          type: "QUERY_SYNC_INIT",
+          payload: {
+            queryId: query.id,
+            rootHash: query.merkleRootHash
+          }
+        });
+      }
     }
     for (const query of this.hybridQueries.values()) {
       if (query.hasFTSPredicate()) {
@@ -1409,7 +1422,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);
@@ -1420,7 +1433,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);
@@ -1837,6 +1850,8 @@ var import_core3 = require("@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;
   }
   /**
@@ -1858,7 +1873,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 import_core3.LWWMap) {
       const localRootHash = map.getMerkleTree().getRootHash();
@@ -1886,9 +1902,11 @@ var MerkleSyncHandler = class {
     if (map instanceof import_core3.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",
@@ -1915,7 +1933,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);
       }
     }
   }
@@ -2198,6 +2226,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),
@@ -2220,12 +2250,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),
@@ -2263,10 +2293,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)
+    }
   });
 }
 
@@ -2401,8 +2428,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,
@@ -2555,6 +2582,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: {
@@ -2575,7 +2611,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.");
@@ -2680,9 +2716,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();
     }
   }
@@ -2736,20 +2773,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"));
     }
@@ -2758,18 +2812,18 @@ var SyncEngine = class {
     }
   }
   handleQueryResp(message) {
-    const { queryId, results, nextCursor, hasMore, cursorStatus } = message.payload;
+    const { queryId, results, nextCursor, hasMore, cursorStatus, merkleRootHash } = message.payload;
     const query = this.queryManager.getQueries().get(queryId);
     if (query) {
-      query.onResult(results, "server");
+      query.onResult(results, "server", merkleRootHash);
       query.updatePaginationInfo({ nextCursor, hasMore, cursorStatus });
     }
   }
   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) {
@@ -3174,31 +3228,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");
   }
 };
 
@@ -3305,12 +3352,15 @@ var QueryHandle = class {
     // Pagination info
     this._paginationInfo = { hasMore: false, cursorStatus: "none" };
     this.paginationListeners = /* @__PURE__ */ new Set();
+    /** Merkle root hash from last server QUERY_RESP — used for delta reconnect */
+    this.merkleRootHash = 0;
     // Track if we've received authoritative server response
     this.hasReceivedServerData = false;
     this.id = crypto.randomUUID();
     this.syncEngine = syncEngine;
     this.mapName = mapName;
     this.filter = filter;
+    this.fields = filter.fields;
   }
   subscribe(callback) {
     this.listeners.add(callback);
@@ -3346,7 +3396,7 @@ var QueryHandle = class {
    * - This prevents clearing local data when server hasn't loaded from storage yet
    * - Works with any async storage adapter (PostgreSQL, SQLite, Redis, etc.)
    */
-  onResult(items, source = "server") {
+  onResult(items, source = "server", merkleRootHash) {
     logger.debug({
       mapName: this.mapName,
       itemCount: items.length,
@@ -3361,6 +3411,9 @@ var QueryHandle = class {
     if (source === "server" && items.length > 0) {
       this.hasReceivedServerData = true;
     }
+    if (merkleRootHash !== void 0) {
+      this.merkleRootHash = merkleRootHash;
+    }
     const newKeys = new Set(items.map((i) => i.key));
     const removedKeys = [];
     for (const key of this.currentResults.keys()) {
@@ -4082,8 +4135,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,
@@ -4400,6 +4453,30 @@ var import_core10 = require("@topgunbuild/core");
 // src/cluster/ConnectionPool.ts
 var import_core7 = require("@topgunbuild/core");
 var import_core8 = require("@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();
@@ -4471,10 +4548,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,
@@ -4509,15 +4593,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)
@@ -4531,8 +4634,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;
@@ -4588,7 +4694,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
@@ -4597,11 +4703,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.
@@ -4666,25 +4772,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) {
@@ -4713,18 +4820,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) {
@@ -4732,10 +4836,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) {
@@ -4902,17 +5002,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 };
         }
       }
     }
@@ -5188,7 +5288,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;
@@ -5201,6 +5301,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 = {
       ...import_core10.DEFAULT_CIRCUIT_BREAKER_CONFIG,
@@ -5292,14 +5394,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.
@@ -5307,10 +5409,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.
@@ -5321,9 +5423,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);
@@ -5492,8 +5608,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;
     }
@@ -5504,7 +5620,7 @@ var ClusterClient = class {
         mapVersion: this.partitionRouter.getMapVersion()
       }
     };
-    connection.socket.send((0, import_core10.serialize)(routedMessage));
+    route.connection.send((0, import_core10.serialize)(routedMessage));
     return true;
   }
   /**
@@ -5608,10 +5724,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;
@@ -5634,23 +5763,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
@@ -5741,9 +5870,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");
       }
@@ -5798,6 +5925,8 @@ var ClusterClient = class {
     });
   }
 };
+_ClusterClient.PARTITION_MAP_REQUEST_DEBOUNCE_MS = 500;
+var ClusterClient = _ClusterClient;
 
 // src/connection/SingleServerProvider.ts
 var DEFAULT_CONFIG = {
@@ -5813,14 +5942,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.
@@ -5829,6 +5962,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 {
@@ -5881,7 +6017,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.
@@ -5932,6 +6068,7 @@ var SingleServerProvider = class {
    */
   async close() {
     this.isClosing = true;
+    this.teardownNetworkListeners();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -5970,6 +6107,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 },
@@ -6005,6 +6146,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.
    */
@@ -6024,6 +6196,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
@@ -6081,7 +6290,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,
@@ -7131,6 +7346,24 @@ var import_core14 = require("@topgunbuild/core");
 
 // src/connection/HttpSyncProvider.ts
 var import_core13 = require("@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();
@@ -7172,17 +7405,17 @@ var HttpSyncProvider = class {
   }
   /**
    * Get connection for a specific key.
-   * HTTP mode does not expose raw WebSocket connections.
+   * Returns an HttpConnection that queues operations for the next poll cycle.
    */
   getConnection(_key) {
-    throw new Error("HTTP mode does not support direct WebSocket access");
+    return new HttpConnection(this);
   }
   /**
    * Get any available connection.
-   * HTTP mode does not expose raw WebSocket connections.
+   * Returns an HttpConnection that queues operations for the next poll cycle.
    */
   getAnyConnection() {
-    throw new Error("HTTP mode does not support direct WebSocket access");
+    return new HttpConnection(this);
   }
   /**
    * Check if connected (last HTTP request succeeded).
@@ -7263,6 +7496,17 @@ var HttpSyncProvider = class {
       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.
@@ -7535,6 +7779,14 @@ var AutoConnectionProvider = class {
     }
     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.
    */
@@ -7592,6 +7844,7 @@ var AutoConnectionProvider = class {
   ClusterClient,
   ConflictResolverClient,
   ConnectionPool,
+  ConnectionReadyState,
   DEFAULT_BACKPRESSURE_CONFIG,
   DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
@@ -7613,6 +7866,7 @@ var AutoConnectionProvider = class {
   TopGunClient,
   TopicHandle,
   VALID_TRANSITIONS,
+  WebSocketConnection,
   isValidTransition,
   logger
 });