@topgunbuild/client 0.1.0 → 0.2.0-alpha

package/dist/index.mjs

@@ -20,12 +20,200 @@ var logger = pino({
   }
 });
 
+// src/SyncState.ts
+var SyncState = /* @__PURE__ */ ((SyncState2) => {
+  SyncState2["INITIAL"] = "INITIAL";
+  SyncState2["CONNECTING"] = "CONNECTING";
+  SyncState2["AUTHENTICATING"] = "AUTHENTICATING";
+  SyncState2["SYNCING"] = "SYNCING";
+  SyncState2["CONNECTED"] = "CONNECTED";
+  SyncState2["DISCONNECTED"] = "DISCONNECTED";
+  SyncState2["BACKOFF"] = "BACKOFF";
+  SyncState2["ERROR"] = "ERROR";
+  return SyncState2;
+})(SyncState || {});
+var VALID_TRANSITIONS = {
+  ["INITIAL" /* INITIAL */]: ["CONNECTING" /* CONNECTING */],
+  ["CONNECTING" /* CONNECTING */]: ["AUTHENTICATING" /* AUTHENTICATING */, "BACKOFF" /* BACKOFF */, "ERROR" /* ERROR */, "DISCONNECTED" /* DISCONNECTED */],
+  ["AUTHENTICATING" /* AUTHENTICATING */]: ["SYNCING" /* SYNCING */, "BACKOFF" /* BACKOFF */, "ERROR" /* ERROR */, "DISCONNECTED" /* DISCONNECTED */],
+  ["SYNCING" /* SYNCING */]: ["CONNECTED" /* CONNECTED */, "BACKOFF" /* BACKOFF */, "ERROR" /* ERROR */, "DISCONNECTED" /* DISCONNECTED */],
+  ["CONNECTED" /* CONNECTED */]: ["SYNCING" /* SYNCING */, "DISCONNECTED" /* DISCONNECTED */, "BACKOFF" /* BACKOFF */],
+  ["DISCONNECTED" /* DISCONNECTED */]: ["CONNECTING" /* CONNECTING */, "BACKOFF" /* BACKOFF */, "INITIAL" /* INITIAL */],
+  ["BACKOFF" /* BACKOFF */]: ["CONNECTING" /* CONNECTING */, "DISCONNECTED" /* DISCONNECTED */, "INITIAL" /* INITIAL */],
+  ["ERROR" /* ERROR */]: ["INITIAL" /* INITIAL */]
+};
+function isValidTransition(from, to) {
+  return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+// src/SyncStateMachine.ts
+var DEFAULT_MAX_HISTORY_SIZE = 50;
+var SyncStateMachine = class {
+  constructor(config = {}) {
+    this.state = "INITIAL" /* INITIAL */;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.history = [];
+    this.maxHistorySize = config.maxHistorySize ?? DEFAULT_MAX_HISTORY_SIZE;
+  }
+  /**
+   * Attempt to transition to a new state.
+   * @param to The target state
+   * @returns true if the transition was valid and executed, false otherwise
+   */
+  transition(to) {
+    const from = this.state;
+    if (from === to) {
+      return true;
+    }
+    if (!isValidTransition(from, to)) {
+      logger.warn(
+        { from, to, currentHistory: this.getHistory(5) },
+        `Invalid state transition attempted: ${from} \u2192 ${to}`
+      );
+      return false;
+    }
+    this.state = to;
+    const event = {
+      from,
+      to,
+      timestamp: Date.now()
+    };
+    this.history.push(event);
+    if (this.history.length > this.maxHistorySize) {
+      this.history.shift();
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        logger.error({ err, event }, "State change listener threw an error");
+      }
+    }
+    logger.debug({ from, to }, `State transition: ${from} \u2192 ${to}`);
+    return true;
+  }
+  /**
+   * Get the current state.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Check if a transition from the current state to the target state is valid.
+   * @param to The target state to check
+   */
+  canTransition(to) {
+    return this.state === to || isValidTransition(this.state, to);
+  }
+  /**
+   * Subscribe to state change events.
+   * @param listener Callback function to be called on each state change
+   * @returns An unsubscribe function
+   */
+  onStateChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Get the state transition history.
+   * @param limit Maximum number of entries to return (default: all)
+   * @returns Array of state change events, oldest first
+   */
+  getHistory(limit) {
+    if (limit === void 0 || limit >= this.history.length) {
+      return [...this.history];
+    }
+    return this.history.slice(-limit);
+  }
+  /**
+   * Reset the state machine to INITIAL state.
+   * This is a forced reset that bypasses normal transition validation.
+   * Use for testing or hard resets after fatal errors.
+   * @param clearHistory If true, also clears the transition history (default: true)
+   */
+  reset(clearHistory = true) {
+    const from = this.state;
+    this.state = "INITIAL" /* INITIAL */;
+    if (clearHistory) {
+      this.history = [];
+    } else {
+      const event = {
+        from,
+        to: "INITIAL" /* INITIAL */,
+        timestamp: Date.now()
+      };
+      this.history.push(event);
+      if (this.history.length > this.maxHistorySize) {
+        this.history.shift();
+      }
+      for (const listener of this.listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          logger.error({ err, event }, "State change listener threw an error during reset");
+        }
+      }
+    }
+    logger.info({ from }, "State machine reset to INITIAL");
+  }
+  /**
+   * Check if the state machine is in a "connected" state
+   * (either SYNCING or CONNECTED)
+   */
+  isConnected() {
+    return this.state === "CONNECTED" /* CONNECTED */ || this.state === "SYNCING" /* SYNCING */;
+  }
+  /**
+   * Check if the state machine is in a state where operations can be sent
+   * (authenticated and connected)
+   */
+  isReady() {
+    return this.state === "CONNECTED" /* CONNECTED */;
+  }
+  /**
+   * Check if the state machine is currently attempting to connect
+   */
+  isConnecting() {
+    return this.state === "CONNECTING" /* CONNECTING */ || this.state === "AUTHENTICATING" /* AUTHENTICATING */ || this.state === "SYNCING" /* SYNCING */;
+  }
+};
+
+// src/errors/BackpressureError.ts
+var BackpressureError = class _BackpressureError extends Error {
+  constructor(pendingCount, maxPending) {
+    super(
+      `Backpressure limit reached: ${pendingCount}/${maxPending} pending operations. Wait for acknowledgments or increase maxPendingOps.`
+    );
+    this.pendingCount = pendingCount;
+    this.maxPending = maxPending;
+    this.name = "BackpressureError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _BackpressureError);
+    }
+  }
+};
+
+// src/BackpressureConfig.ts
+var DEFAULT_BACKPRESSURE_CONFIG = {
+  maxPendingOps: 1e3,
+  strategy: "pause",
+  highWaterMark: 0.8,
+  lowWaterMark: 0.5
+};
+
 // src/SyncEngine.ts
+var DEFAULT_BACKOFF_CONFIG = {
+  initialDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  multiplier: 2,
+  jitter: true,
+  maxRetries: 10
+};
 var SyncEngine = class {
   constructor(config) {
     this.websocket = null;
-    this.isOnline = false;
-    this.isAuthenticated = false;
     this.opLog = [];
     this.maps = /* @__PURE__ */ new Map();
     this.queries = /* @__PURE__ */ new Map();
@@ -36,25 +224,95 @@ var SyncEngine = class {
     // NodeJS.Timeout
     this.authToken = null;
     this.tokenProvider = null;
+    this.backoffAttempt = 0;
+    this.heartbeatInterval = null;
+    this.lastPongReceived = Date.now();
+    this.lastRoundTripTime = null;
+    this.backpressurePaused = false;
+    this.waitingForCapacity = [];
+    this.highWaterMarkEmitted = false;
+    this.backpressureListeners = /* @__PURE__ */ new Map();
     this.nodeId = config.nodeId;
     this.serverUrl = config.serverUrl;
     this.storageAdapter = config.storageAdapter;
-    this.reconnectInterval = config.reconnectInterval || 5e3;
     this.hlc = new HLC(this.nodeId);
+    this.stateMachine = new SyncStateMachine();
+    this.heartbeatConfig = {
+      intervalMs: config.heartbeat?.intervalMs ?? 5e3,
+      timeoutMs: config.heartbeat?.timeoutMs ?? 15e3,
+      enabled: config.heartbeat?.enabled ?? true
+    };
+    this.backoffConfig = {
+      ...DEFAULT_BACKOFF_CONFIG,
+      ...config.backoff
+    };
+    this.backpressureConfig = {
+      ...DEFAULT_BACKPRESSURE_CONFIG,
+      ...config.backpressure
+    };
     this.initConnection();
     this.loadOpLog();
   }
+  // ============================================
+  // State Machine Public API
+  // ============================================
+  /**
+   * Get the current connection state
+   */
+  getConnectionState() {
+    return this.stateMachine.getState();
+  }
+  /**
+   * Subscribe to connection state changes
+   * @returns Unsubscribe function
+   */
+  onConnectionStateChange(listener) {
+    return this.stateMachine.onStateChange(listener);
+  }
+  /**
+   * Get state machine history for debugging
+   */
+  getStateHistory(limit) {
+    return this.stateMachine.getHistory(limit);
+  }
+  // ============================================
+  // Internal State Helpers (replace boolean flags)
+  // ============================================
+  /**
+   * Check if WebSocket is connected (but may not be authenticated yet)
+   */
+  isOnline() {
+    const state = this.stateMachine.getState();
+    return state === "CONNECTING" /* CONNECTING */ || state === "AUTHENTICATING" /* AUTHENTICATING */ || state === "SYNCING" /* SYNCING */ || state === "CONNECTED" /* CONNECTED */;
+  }
+  /**
+   * Check if fully authenticated and ready for operations
+   */
+  isAuthenticated() {
+    const state = this.stateMachine.getState();
+    return state === "SYNCING" /* SYNCING */ || state === "CONNECTED" /* CONNECTED */;
+  }
+  /**
+   * Check if fully connected and synced
+   */
+  isConnected() {
+    return this.stateMachine.getState() === "CONNECTED" /* CONNECTED */;
+  }
+  // ============================================
+  // Connection Management
+  // ============================================
   initConnection() {
+    this.stateMachine.transition("CONNECTING" /* CONNECTING */);
     this.websocket = new WebSocket(this.serverUrl);
     this.websocket.binaryType = "arraybuffer";
     this.websocket.onopen = () => {
       if (this.authToken || this.tokenProvider) {
         logger.info("WebSocket connected. Sending auth...");
-        this.isOnline = true;
+        this.stateMachine.transition("AUTHENTICATING" /* AUTHENTICATING */);
         this.sendAuth();
       } else {
         logger.info("WebSocket connected. Waiting for auth token...");
-        this.isOnline = true;
+        this.stateMachine.transition("AUTHENTICATING" /* AUTHENTICATING */);
       }
     };
     this.websocket.onmessage = (event) => {
@@ -72,9 +330,9 @@ var SyncEngine = class {
       this.handleServerMessage(message);
     };
     this.websocket.onclose = () => {
-      logger.info("WebSocket disconnected. Retrying...");
-      this.isOnline = false;
-      this.isAuthenticated = false;
+      logger.info("WebSocket disconnected.");
+      this.stopHeartbeat();
+      this.stateMachine.transition("DISCONNECTED" /* DISCONNECTED */);
       this.scheduleReconnect();
     };
     this.websocket.onerror = (error) => {
@@ -82,10 +340,41 @@ var SyncEngine = class {
     };
   }
   scheduleReconnect() {
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.backoffAttempt >= this.backoffConfig.maxRetries) {
+      logger.error(
+        { attempts: this.backoffAttempt },
+        "Max reconnection attempts reached. Entering ERROR state."
+      );
+      this.stateMachine.transition("ERROR" /* ERROR */);
+      return;
+    }
+    this.stateMachine.transition("BACKOFF" /* BACKOFF */);
+    const delay = this.calculateBackoffDelay();
+    logger.info({ delay, attempt: this.backoffAttempt }, `Backing off for ${delay}ms`);
     this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.backoffAttempt++;
       this.initConnection();
-    }, this.reconnectInterval);
+    }, delay);
+  }
+  calculateBackoffDelay() {
+    const { initialDelayMs, maxDelayMs, multiplier, jitter } = this.backoffConfig;
+    let delay = initialDelayMs * Math.pow(multiplier, this.backoffAttempt);
+    delay = Math.min(delay, maxDelayMs);
+    if (jitter) {
+      delay = delay * (0.5 + Math.random());
+    }
+    return Math.floor(delay);
+  }
+  /**
+   * Reset backoff counter (called on successful connection)
+   */
+  resetBackoff() {
+    this.backoffAttempt = 0;
   }
   async loadOpLog() {
     const storedTimestamp = await this.storageAdapter.getMeta("lastSyncTimestamp");
@@ -109,6 +398,7 @@ var SyncEngine = class {
     this.maps.set(mapName, map);
   }
   async recordOperation(mapName, opType, key, data) {
+    await this.checkBackpressure();
     const opLogEntry = {
       mapName,
       opType,
@@ -122,9 +412,11 @@ var SyncEngine = class {
     const id = await this.storageAdapter.appendOpLog(opLogEntry);
     opLogEntry.id = String(id);
     this.opLog.push(opLogEntry);
-    if (this.isOnline && this.isAuthenticated) {
+    this.checkHighWaterMark();
+    if (this.isAuthenticated()) {
       this.syncPendingOperations();
     }
+    return opLogEntry.id;
   }
   syncPendingOperations() {
     const pending = this.opLog.filter((op) => !op.synced);
@@ -142,32 +434,47 @@ var SyncEngine = class {
   startMerkleSync() {
     for (const [mapName, map] of this.maps) {
       if (map instanceof LWWMap) {
-        logger.info({ mapName }, "Starting Merkle sync for map");
+        logger.info({ mapName }, "Starting Merkle sync for LWWMap");
         this.websocket?.send(serialize({
           type: "SYNC_INIT",
           mapName,
           lastSyncTimestamp: this.lastSyncTimestamp
         }));
+      } else if (map instanceof ORMap) {
+        logger.info({ mapName }, "Starting Merkle sync for ORMap");
+        const tree = map.getMerkleTree();
+        const rootHash = tree.getRootHash();
+        const bucketHashes = tree.getBuckets("");
+        this.websocket?.send(serialize({
+          type: "ORMAP_SYNC_INIT",
+          mapName,
+          rootHash,
+          bucketHashes,
+          lastSyncTimestamp: this.lastSyncTimestamp
+        }));
       }
     }
   }
   setAuthToken(token) {
     this.authToken = token;
     this.tokenProvider = null;
-    if (this.isOnline) {
+    const state = this.stateMachine.getState();
+    if (state === "AUTHENTICATING" /* AUTHENTICATING */ || state === "CONNECTING" /* CONNECTING */) {
       this.sendAuth();
-    } else {
+    } else if (state === "BACKOFF" /* BACKOFF */ || state === "DISCONNECTED" /* DISCONNECTED */) {
+      logger.info("Auth token set during backoff/disconnect. Reconnecting immediately.");
       if (this.reconnectTimer) {
-        logger.info("Auth token set during backoff. Reconnecting immediately.");
         clearTimeout(this.reconnectTimer);
         this.reconnectTimer = null;
-        this.initConnection();
       }
+      this.resetBackoff();
+      this.initConnection();
     }
   }
   setTokenProvider(provider) {
     this.tokenProvider = provider;
-    if (this.isOnline && !this.isAuthenticated) {
+    const state = this.stateMachine.getState();
+    if (state === "AUTHENTICATING" /* AUTHENTICATING */) {
       this.sendAuth();
     }
   }
@@ -192,19 +499,19 @@ var SyncEngine = class {
   }
   subscribeToQuery(query) {
     this.queries.set(query.id, query);
-    if (this.isOnline && this.isAuthenticated) {
+    if (this.isAuthenticated()) {
       this.sendQuerySubscription(query);
     }
   }
   subscribeToTopic(topic, handle) {
     this.topics.set(topic, handle);
-    if (this.isOnline && this.isAuthenticated) {
+    if (this.isAuthenticated()) {
       this.sendTopicSubscription(topic);
     }
   }
   unsubscribeFromTopic(topic) {
     this.topics.delete(topic);
-    if (this.isOnline && this.isAuthenticated) {
+    if (this.isAuthenticated()) {
       this.websocket?.send(serialize({
         type: "TOPIC_UNSUB",
         payload: { topic }
@@ -212,7 +519,7 @@ var SyncEngine = class {
     }
   }
   publishTopic(topic, data) {
-    if (this.isOnline && this.isAuthenticated) {
+    if (this.isAuthenticated()) {
       this.websocket?.send(serialize({
         type: "TOPIC_PUB",
         payload: { topic, data }
@@ -261,7 +568,7 @@ var SyncEngine = class {
   }
   unsubscribeFromQuery(queryId) {
     this.queries.delete(queryId);
-    if (this.isOnline && this.isAuthenticated) {
+    if (this.isAuthenticated()) {
       this.websocket?.send(serialize({
         type: "QUERY_UNSUB",
         payload: { queryId }
@@ -279,7 +586,7 @@ var SyncEngine = class {
     }));
   }
   requestLock(name, requestId, ttl) {
-    if (!this.isOnline || !this.isAuthenticated) {
+    if (!this.isAuthenticated()) {
       return Promise.reject(new Error("Not connected or authenticated"));
     }
     return new Promise((resolve, reject) => {
@@ -303,7 +610,7 @@ var SyncEngine = class {
     });
   }
   releaseLock(name, requestId, fencingToken) {
-    if (!this.isOnline) return Promise.resolve(false);
+    if (!this.isOnline()) return Promise.resolve(false);
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         if (this.pendingLockRequests.has(requestId)) {
@@ -331,10 +638,12 @@ var SyncEngine = class {
         break;
       case "AUTH_ACK": {
         logger.info("Authenticated successfully");
-        const wasAuthenticated = this.isAuthenticated;
-        this.isAuthenticated = true;
+        const wasAuthenticated = this.isAuthenticated();
+        this.stateMachine.transition("SYNCING" /* SYNCING */);
+        this.resetBackoff();
         this.syncPendingOperations();
         if (!wasAuthenticated) {
+          this.startHeartbeat();
           this.startMerkleSync();
           for (const query of this.queries.values()) {
             this.sendQuerySubscription(query);
@@ -343,19 +652,27 @@ var SyncEngine = class {
             this.sendTopicSubscription(topic);
           }
         }
+        this.stateMachine.transition("CONNECTED" /* CONNECTED */);
+        break;
+      }
+      case "PONG": {
+        this.handlePong(message);
         break;
       }
       case "AUTH_FAIL":
         logger.error({ error: message.error }, "Authentication failed");
-        this.isAuthenticated = false;
         this.authToken = null;
         break;
       case "OP_ACK": {
         const { lastId } = message.payload;
         logger.info({ lastId }, "Received ACK for ops");
         let maxSyncedId = -1;
+        let ackedCount = 0;
         this.opLog.forEach((op) => {
           if (op.id && op.id <= lastId) {
+            if (!op.synced) {
+              ackedCount++;
+            }
             op.synced = true;
             const idNum = parseInt(op.id, 10);
             if (!isNaN(idNum) && idNum > maxSyncedId) {
@@ -366,6 +683,9 @@ var SyncEngine = class {
         if (maxSyncedId !== -1) {
           this.storageAdapter.markOpsSynced(maxSyncedId).catch((err) => logger.error({ err }, "Failed to mark ops synced"));
         }
+        if (ackedCount > 0) {
+          this.checkLowWaterMark();
+        }
         break;
       }
       case "LOCK_GRANTED": {
@@ -520,6 +840,96 @@ var SyncEngine = class {
         }
         break;
       }
+      // ============ ORMap Sync Message Handlers ============
+      case "ORMAP_SYNC_RESP_ROOT": {
+        const { mapName, rootHash, timestamp } = message.payload;
+        const map = this.maps.get(mapName);
+        if (map instanceof ORMap) {
+          const localTree = map.getMerkleTree();
+          const localRootHash = localTree.getRootHash();
+          if (localRootHash !== rootHash) {
+            logger.info({ mapName, localRootHash, remoteRootHash: rootHash }, "ORMap root hash mismatch, requesting buckets");
+            this.websocket?.send(serialize({
+              type: "ORMAP_MERKLE_REQ_BUCKET",
+              payload: { mapName, path: "" }
+            }));
+          } else {
+            logger.info({ mapName }, "ORMap is in sync");
+          }
+        }
+        if (timestamp) {
+          this.hlc.update(timestamp);
+          this.lastSyncTimestamp = timestamp.millis;
+          await this.saveOpLog();
+        }
+        break;
+      }
+      case "ORMAP_SYNC_RESP_BUCKETS": {
+        const { mapName, path, buckets } = message.payload;
+        const map = this.maps.get(mapName);
+        if (map instanceof ORMap) {
+          const tree = map.getMerkleTree();
+          const localBuckets = tree.getBuckets(path);
+          for (const [bucketKey, remoteHash] of Object.entries(buckets)) {
+            const localHash = localBuckets[bucketKey] || 0;
+            if (localHash !== remoteHash) {
+              const newPath = path + bucketKey;
+              this.websocket?.send(serialize({
+                type: "ORMAP_MERKLE_REQ_BUCKET",
+                payload: { mapName, path: newPath }
+              }));
+            }
+          }
+          for (const [bucketKey, localHash] of Object.entries(localBuckets)) {
+            if (!(bucketKey in buckets) && localHash !== 0) {
+              const newPath = path + bucketKey;
+              const keys = tree.getKeysInBucket(newPath);
+              if (keys.length > 0) {
+                this.pushORMapDiff(mapName, keys, map);
+              }
+            }
+          }
+        }
+        break;
+      }
+      case "ORMAP_SYNC_RESP_LEAF": {
+        const { mapName, entries } = message.payload;
+        const map = this.maps.get(mapName);
+        if (map instanceof ORMap) {
+          let totalAdded = 0;
+          let totalUpdated = 0;
+          for (const entry of entries) {
+            const { key, records, tombstones } = entry;
+            const result = map.mergeKey(key, records, tombstones);
+            totalAdded += result.added;
+            totalUpdated += result.updated;
+          }
+          if (totalAdded > 0 || totalUpdated > 0) {
+            logger.info({ mapName, added: totalAdded, updated: totalUpdated }, "Synced ORMap records from server");
+          }
+          const keysToCheck = entries.map((e) => e.key);
+          await this.pushORMapDiff(mapName, keysToCheck, map);
+        }
+        break;
+      }
+      case "ORMAP_DIFF_RESPONSE": {
+        const { mapName, entries } = message.payload;
+        const map = this.maps.get(mapName);
+        if (map instanceof ORMap) {
+          let totalAdded = 0;
+          let totalUpdated = 0;
+          for (const entry of entries) {
+            const { key, records, tombstones } = entry;
+            const result = map.mergeKey(key, records, tombstones);
+            totalAdded += result.added;
+            totalUpdated += result.updated;
+          }
+          if (totalAdded > 0 || totalUpdated > 0) {
+            logger.info({ mapName, added: totalAdded, updated: totalUpdated }, "Merged ORMap diff from server");
+          }
+        }
+        break;
+      }
     }
     if (message.timestamp) {
       this.hlc.update(message.timestamp);
@@ -534,6 +944,7 @@ var SyncEngine = class {
    * Closes the WebSocket connection and cleans up resources.
    */
   close() {
+    this.stopHeartbeat();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -543,10 +954,19 @@ var SyncEngine = class {
       this.websocket.close();
       this.websocket = null;
     }
-    this.isOnline = false;
-    this.isAuthenticated = false;
+    this.stateMachine.transition("DISCONNECTED" /* DISCONNECTED */);
     logger.info("SyncEngine closed");
   }
+  /**
+   * Reset the state machine and connection.
+   * Use after fatal errors to start fresh.
+   */
+  resetConnection() {
+    this.close();
+    this.stateMachine.reset();
+    this.resetBackoff();
+    this.initConnection();
+  }
   async resetMap(mapName) {
     const map = this.maps.get(mapName);
     if (map) {
@@ -563,6 +983,297 @@ var SyncEngine = class {
     }
     logger.info({ mapName, removedStorageCount: mapKeys.length }, "Reset map: Cleared memory and storage");
   }
+  // ============ Heartbeat Methods ============
+  /**
+   * Starts the heartbeat mechanism after successful connection.
+   */
+  startHeartbeat() {
+    if (!this.heartbeatConfig.enabled) {
+      return;
+    }
+    this.stopHeartbeat();
+    this.lastPongReceived = Date.now();
+    this.heartbeatInterval = setInterval(() => {
+      this.sendPing();
+      this.checkHeartbeatTimeout();
+    }, this.heartbeatConfig.intervalMs);
+    logger.info({ intervalMs: this.heartbeatConfig.intervalMs }, "Heartbeat started");
+  }
+  /**
+   * Stops the heartbeat mechanism.
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+      logger.info("Heartbeat stopped");
+    }
+  }
+  /**
+   * Sends a PING message to the server.
+   */
+  sendPing() {
+    if (this.websocket?.readyState === WebSocket.OPEN) {
+      const pingMessage = {
+        type: "PING",
+        timestamp: Date.now()
+      };
+      this.websocket.send(serialize(pingMessage));
+    }
+  }
+  /**
+   * Handles incoming PONG message from server.
+   */
+  handlePong(msg) {
+    const now = Date.now();
+    this.lastPongReceived = now;
+    this.lastRoundTripTime = now - msg.timestamp;
+    logger.debug({
+      rtt: this.lastRoundTripTime,
+      serverTime: msg.serverTime,
+      clockSkew: msg.serverTime - (msg.timestamp + this.lastRoundTripTime / 2)
+    }, "Received PONG");
+  }
+  /**
+   * Checks if heartbeat has timed out and triggers reconnection if needed.
+   */
+  checkHeartbeatTimeout() {
+    const now = Date.now();
+    const timeSinceLastPong = now - this.lastPongReceived;
+    if (timeSinceLastPong > this.heartbeatConfig.timeoutMs) {
+      logger.warn({
+        timeSinceLastPong,
+        timeoutMs: this.heartbeatConfig.timeoutMs
+      }, "Heartbeat timeout - triggering reconnection");
+      this.stopHeartbeat();
+      if (this.websocket) {
+        this.websocket.close();
+      }
+    }
+  }
+  /**
+   * Returns the last measured round-trip time in milliseconds.
+   * Returns null if no PONG has been received yet.
+   */
+  getLastRoundTripTime() {
+    return this.lastRoundTripTime;
+  }
+  /**
+   * Returns true if the connection is considered healthy based on heartbeat.
+   * A connection is healthy if it's online, authenticated, and has received
+   * a PONG within the timeout window.
+   */
+  isConnectionHealthy() {
+    if (!this.isOnline() || !this.isAuthenticated()) {
+      return false;
+    }
+    if (!this.heartbeatConfig.enabled) {
+      return true;
+    }
+    const timeSinceLastPong = Date.now() - this.lastPongReceived;
+    return timeSinceLastPong < this.heartbeatConfig.timeoutMs;
+  }
+  // ============ ORMap Sync Methods ============
+  /**
+   * Push local ORMap diff to server for the given keys.
+   * Sends local records and tombstones that the server might not have.
+   */
+  async pushORMapDiff(mapName, keys, map) {
+    const entries = [];
+    const snapshot = map.getSnapshot();
+    for (const key of keys) {
+      const recordsMap = map.getRecordsMap(key);
+      if (recordsMap && recordsMap.size > 0) {
+        const records = Array.from(recordsMap.values());
+        const tombstones = [];
+        for (const tag of snapshot.tombstones) {
+          tombstones.push(tag);
+        }
+        entries.push({
+          key,
+          records,
+          tombstones
+        });
+      }
+    }
+    if (entries.length > 0) {
+      this.websocket?.send(serialize({
+        type: "ORMAP_PUSH_DIFF",
+        payload: {
+          mapName,
+          entries
+        }
+      }));
+      logger.debug({ mapName, keyCount: entries.length }, "Pushed ORMap diff to server");
+    }
+  }
+  // ============ Backpressure Methods ============
+  /**
+   * Get the current number of pending (unsynced) operations.
+   */
+  getPendingOpsCount() {
+    return this.opLog.filter((op) => !op.synced).length;
+  }
+  /**
+   * Get the current backpressure status.
+   */
+  getBackpressureStatus() {
+    const pending = this.getPendingOpsCount();
+    const max = this.backpressureConfig.maxPendingOps;
+    return {
+      pending,
+      max,
+      percentage: max > 0 ? pending / max : 0,
+      isPaused: this.backpressurePaused,
+      strategy: this.backpressureConfig.strategy
+    };
+  }
+  /**
+   * Returns true if writes are currently paused due to backpressure.
+   */
+  isBackpressurePaused() {
+    return this.backpressurePaused;
+  }
+  /**
+   * Subscribe to backpressure events.
+   * @param event Event name: 'backpressure:high', 'backpressure:low', 'backpressure:paused', 'backpressure:resumed', 'operation:dropped'
+   * @param listener Callback function
+   * @returns Unsubscribe function
+   */
+  onBackpressure(event, listener) {
+    if (!this.backpressureListeners.has(event)) {
+      this.backpressureListeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.backpressureListeners.get(event).add(listener);
+    return () => {
+      this.backpressureListeners.get(event)?.delete(listener);
+    };
+  }
+  /**
+   * Emit a backpressure event to all listeners.
+   */
+  emitBackpressureEvent(event, data) {
+    const listeners = this.backpressureListeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(data);
+        } catch (err) {
+          logger.error({ err, event }, "Error in backpressure event listener");
+        }
+      }
+    }
+  }
+  /**
+   * Check backpressure before adding a new operation.
+   * May pause, throw, or drop depending on strategy.
+   */
+  async checkBackpressure() {
+    const pendingCount = this.getPendingOpsCount();
+    if (pendingCount < this.backpressureConfig.maxPendingOps) {
+      return;
+    }
+    switch (this.backpressureConfig.strategy) {
+      case "pause":
+        await this.waitForCapacity();
+        break;
+      case "throw":
+        throw new BackpressureError(
+          pendingCount,
+          this.backpressureConfig.maxPendingOps
+        );
+      case "drop-oldest":
+        this.dropOldestOp();
+        break;
+    }
+  }
+  /**
+   * Check high water mark and emit event if threshold reached.
+   */
+  checkHighWaterMark() {
+    const pendingCount = this.getPendingOpsCount();
+    const threshold = Math.floor(
+      this.backpressureConfig.maxPendingOps * this.backpressureConfig.highWaterMark
+    );
+    if (pendingCount >= threshold && !this.highWaterMarkEmitted) {
+      this.highWaterMarkEmitted = true;
+      logger.warn(
+        { pending: pendingCount, max: this.backpressureConfig.maxPendingOps },
+        "Backpressure high water mark reached"
+      );
+      this.emitBackpressureEvent("backpressure:high", {
+        pending: pendingCount,
+        max: this.backpressureConfig.maxPendingOps
+      });
+    }
+  }
+  /**
+   * Check low water mark and resume paused writes if threshold reached.
+   */
+  checkLowWaterMark() {
+    const pendingCount = this.getPendingOpsCount();
+    const lowThreshold = Math.floor(
+      this.backpressureConfig.maxPendingOps * this.backpressureConfig.lowWaterMark
+    );
+    const highThreshold = Math.floor(
+      this.backpressureConfig.maxPendingOps * this.backpressureConfig.highWaterMark
+    );
+    if (pendingCount < highThreshold && this.highWaterMarkEmitted) {
+      this.highWaterMarkEmitted = false;
+    }
+    if (pendingCount <= lowThreshold) {
+      if (this.backpressurePaused) {
+        this.backpressurePaused = false;
+        logger.info(
+          { pending: pendingCount, max: this.backpressureConfig.maxPendingOps },
+          "Backpressure low water mark reached, resuming writes"
+        );
+        this.emitBackpressureEvent("backpressure:low", {
+          pending: pendingCount,
+          max: this.backpressureConfig.maxPendingOps
+        });
+        this.emitBackpressureEvent("backpressure:resumed");
+        const waiting = this.waitingForCapacity;
+        this.waitingForCapacity = [];
+        for (const resolve of waiting) {
+          resolve();
+        }
+      }
+    }
+  }
+  /**
+   * Wait for capacity to become available (used by 'pause' strategy).
+   */
+  async waitForCapacity() {
+    if (!this.backpressurePaused) {
+      this.backpressurePaused = true;
+      logger.warn("Backpressure paused - waiting for capacity");
+      this.emitBackpressureEvent("backpressure:paused");
+    }
+    return new Promise((resolve) => {
+      this.waitingForCapacity.push(resolve);
+    });
+  }
+  /**
+   * Drop the oldest pending operation (used by 'drop-oldest' strategy).
+   */
+  dropOldestOp() {
+    const oldestIndex = this.opLog.findIndex((op) => !op.synced);
+    if (oldestIndex !== -1) {
+      const dropped = this.opLog[oldestIndex];
+      this.opLog.splice(oldestIndex, 1);
+      logger.warn(
+        { opId: dropped.id, mapName: dropped.mapName, key: dropped.key },
+        "Dropped oldest pending operation due to backpressure"
+      );
+      this.emitBackpressureEvent("operation:dropped", {
+        opId: dropped.id,
+        mapName: dropped.mapName,
+        opType: dropped.opType,
+        key: dropped.key
+      });
+    }
+  }
 };
 
 // src/TopGunClient.ts
@@ -777,7 +1488,9 @@ var TopGunClient = class {
     const syncEngineConfig = {
       nodeId: this.nodeId,
       serverUrl: config.serverUrl,
-      storageAdapter: this.storageAdapter
+      storageAdapter: this.storageAdapter,
+      backoff: config.backoff,
+      backpressure: config.backpressure
     };
     this.syncEngine = new SyncEngine(syncEngineConfig);
   }
@@ -941,6 +1654,90 @@ var TopGunClient = class {
   close() {
     this.syncEngine.close();
   }
+  // ============================================
+  // Connection State API
+  // ============================================
+  /**
+   * Get the current connection state
+   */
+  getConnectionState() {
+    return this.syncEngine.getConnectionState();
+  }
+  /**
+   * Subscribe to connection state changes
+   * @param listener Callback function called on each state change
+   * @returns Unsubscribe function
+   */
+  onConnectionStateChange(listener) {
+    return this.syncEngine.onConnectionStateChange(listener);
+  }
+  /**
+   * Get state machine history for debugging
+   * @param limit Maximum number of entries to return
+   */
+  getStateHistory(limit) {
+    return this.syncEngine.getStateHistory(limit);
+  }
+  /**
+   * Reset the connection and state machine.
+   * Use after fatal errors to start fresh.
+   */
+  resetConnection() {
+    this.syncEngine.resetConnection();
+  }
+  // ============================================
+  // Backpressure API
+  // ============================================
+  /**
+   * Get the current number of pending (unacknowledged) operations.
+   */
+  getPendingOpsCount() {
+    return this.syncEngine.getPendingOpsCount();
+  }
+  /**
+   * Get the current backpressure status.
+   */
+  getBackpressureStatus() {
+    return this.syncEngine.getBackpressureStatus();
+  }
+  /**
+   * Returns true if writes are currently paused due to backpressure.
+   */
+  isBackpressurePaused() {
+    return this.syncEngine.isBackpressurePaused();
+  }
+  /**
+   * Subscribe to backpressure events.
+   *
+   * Available events:
+   * - 'backpressure:high': Emitted when pending ops reach high water mark
+   * - 'backpressure:low': Emitted when pending ops drop below low water mark
+   * - 'backpressure:paused': Emitted when writes are paused (pause strategy)
+   * - 'backpressure:resumed': Emitted when writes resume after being paused
+   * - 'operation:dropped': Emitted when an operation is dropped (drop-oldest strategy)
+   *
+   * @param event Event name
+   * @param listener Callback function
+   * @returns Unsubscribe function
+   *
+   * @example
+   * ```typescript
+   * client.onBackpressure('backpressure:high', ({ pending, max }) => {
+   *   console.warn(`Warning: ${pending}/${max} pending ops`);
+   * });
+   *
+   * client.onBackpressure('backpressure:paused', () => {
+   *   showLoadingSpinner();
+   * });
+   *
+   * client.onBackpressure('backpressure:resumed', () => {
+   *   hideLoadingSpinner();
+   * });
+   * ```
+   */
+  onBackpressure(event, listener) {
+    return this.syncEngine.onBackpressure(event, listener);
+  }
 };
 
 // src/adapters/IDBAdapter.ts
@@ -1370,15 +2167,21 @@ var EncryptedStorageAdapter = class {
 // src/index.ts
 import { LWWMap as LWWMap3, Predicates } from "@topgunbuild/core";
 export {
+  BackpressureError,
+  DEFAULT_BACKPRESSURE_CONFIG,
   EncryptedStorageAdapter,
   IDBAdapter,
   LWWMap3 as LWWMap,
   Predicates,
   QueryHandle,
   SyncEngine,
+  SyncState,
+  SyncStateMachine,
   TopGun,
   TopGunClient,
   TopicHandle,
+  VALID_TRANSITIONS,
+  isValidTransition,
   logger
 };
 //# sourceMappingURL=index.mjs.map