@topgunbuild/server 0.1.0 → 0.2.0-alpha

package/dist/index.d.mts

@@ -199,6 +199,7 @@ declare class ServerCoordinator {
     private systemManager;
     private pendingClusterQueries;
     private gcInterval?;
+    private heartbeatCheckInterval?;
     private gcReports;
     private mapLoadingPromises;
     private _actualPort;
@@ -231,6 +232,27 @@ declare class ServerCoordinator {
     getMapAsync(name: string, typeHint?: 'LWW' | 'OR'): Promise<LWWMap<string, any> | ORMap<string, any>>;
     private loadMapFromStorage;
     private startGarbageCollection;
+    /**
+     * Starts the periodic check for dead clients (those that haven't sent PING).
+     */
+    private startHeartbeatCheck;
+    /**
+     * Handles incoming PING message from client.
+     * Responds with PONG immediately.
+     */
+    private handlePing;
+    /**
+     * Checks if a client is still alive based on heartbeat.
+     */
+    isClientAlive(clientId: string): boolean;
+    /**
+     * Returns how long the client has been idle (no PING received).
+     */
+    getClientIdleTime(clientId: string): number;
+    /**
+     * Evicts clients that haven't sent a PING within the timeout period.
+     */
+    private evictDeadClients;
     private reportLocalHlc;
     private handleGcReport;
     private performGarbageCollection;

package/dist/index.d.ts

@@ -199,6 +199,7 @@ declare class ServerCoordinator {
     private systemManager;
     private pendingClusterQueries;
     private gcInterval?;
+    private heartbeatCheckInterval?;
     private gcReports;
     private mapLoadingPromises;
     private _actualPort;
@@ -231,6 +232,27 @@ declare class ServerCoordinator {
     getMapAsync(name: string, typeHint?: 'LWW' | 'OR'): Promise<LWWMap<string, any> | ORMap<string, any>>;
     private loadMapFromStorage;
     private startGarbageCollection;
+    /**
+     * Starts the periodic check for dead clients (those that haven't sent PING).
+     */
+    private startHeartbeatCheck;
+    /**
+     * Handles incoming PING message from client.
+     * Responds with PONG immediately.
+     */
+    private handlePing;
+    /**
+     * Checks if a client is still alive based on heartbeat.
+     */
+    isClientAlive(clientId: string): boolean;
+    /**
+     * Returns how long the client has been idle (no PING received).
+     */
+    getClientIdleTime(clientId: string): number;
+    /**
+     * Evicts clients that haven't sent a PING within the timeout period.
+     */
+    private evictDeadClients;
     private reportLocalHlc;
     private handleGcReport;
     private performGarbageCollection;

package/dist/index.js

@@ -1251,6 +1251,8 @@ var SystemManager = class {
 // src/ServerCoordinator.ts
 var GC_INTERVAL_MS = 60 * 60 * 1e3;
 var GC_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var CLIENT_HEARTBEAT_TIMEOUT_MS = 2e4;
+var CLIENT_HEARTBEAT_CHECK_INTERVAL_MS = 5e3;
 var ServerCoordinator = class {
   constructor(config) {
     this.clients = /* @__PURE__ */ new Map();
@@ -1371,6 +1373,7 @@ var ServerCoordinator = class {
       });
     }
     this.startGarbageCollection();
+    this.startHeartbeatCheck();
   }
   /** Wait for server to be fully ready (ports assigned) */
   ready() {
@@ -1421,6 +1424,10 @@ var ServerCoordinator = class {
       clearInterval(this.gcInterval);
       this.gcInterval = void 0;
     }
+    if (this.heartbeatCheckInterval) {
+      clearInterval(this.heartbeatCheckInterval);
+      this.heartbeatCheckInterval = void 0;
+    }
     if (this.lockManager) {
       this.lockManager.stop();
     }
@@ -1437,8 +1444,10 @@ var ServerCoordinator = class {
       socket: ws,
       isAuthenticated: false,
       subscriptions: /* @__PURE__ */ new Set(),
-      lastActiveHlc: this.hlc.now()
+      lastActiveHlc: this.hlc.now(),
       // Initialize with current time
+      lastPingReceived: Date.now()
+      // Initialize heartbeat tracking
     };
     this.clients.set(clientId, connection);
     this.metricsService.setConnectedClients(this.clients.size);
@@ -1534,6 +1543,10 @@ var ServerCoordinator = class {
       return;
     }
     const message = parseResult.data;
+    if (message.type === "PING") {
+      this.handlePing(client, message.timestamp);
+      return;
+    }
     this.updateClientHlc(client, message);
     if (!client.isAuthenticated) {
       if (message.type === "AUTH") {
@@ -1900,6 +1913,184 @@ var ServerCoordinator = class {
         }
         break;
       }
+      // ============ ORMap Sync Message Handlers ============
+      case "ORMAP_SYNC_INIT": {
+        if (!this.securityManager.checkPermission(client.principal, message.mapName, "READ")) {
+          client.socket.send((0, import_core4.serialize)({
+            type: "ERROR",
+            payload: { code: 403, message: `Access Denied for map ${message.mapName}` }
+          }));
+          return;
+        }
+        const lastSync = message.lastSyncTimestamp || 0;
+        const now = Date.now();
+        if (lastSync > 0 && now - lastSync > GC_AGE_MS) {
+          logger.warn({ clientId: client.id, lastSync, age: now - lastSync }, "ORMap client too old, sending SYNC_RESET_REQUIRED");
+          client.socket.send((0, import_core4.serialize)({
+            type: "SYNC_RESET_REQUIRED",
+            payload: { mapName: message.mapName }
+          }));
+          return;
+        }
+        logger.info({ clientId: client.id, mapName: message.mapName }, "Client requested ORMap sync");
+        this.metricsService.incOp("GET", message.mapName);
+        try {
+          const mapForSync = await this.getMapAsync(message.mapName, "OR");
+          if (mapForSync instanceof import_core4.ORMap) {
+            const tree = mapForSync.getMerkleTree();
+            const rootHash = tree.getRootHash();
+            client.socket.send((0, import_core4.serialize)({
+              type: "ORMAP_SYNC_RESP_ROOT",
+              payload: {
+                mapName: message.mapName,
+                rootHash,
+                timestamp: this.hlc.now()
+              }
+            }));
+          } else {
+            client.socket.send((0, import_core4.serialize)({
+              type: "ERROR",
+              payload: { code: 400, message: `Map ${message.mapName} is not an ORMap` }
+            }));
+          }
+        } catch (err) {
+          logger.error({ err, mapName: message.mapName }, "Failed to load map for ORMAP_SYNC_INIT");
+          client.socket.send((0, import_core4.serialize)({
+            type: "ERROR",
+            payload: { code: 500, message: `Failed to load map ${message.mapName}` }
+          }));
+        }
+        break;
+      }
+      case "ORMAP_MERKLE_REQ_BUCKET": {
+        if (!this.securityManager.checkPermission(client.principal, message.payload.mapName, "READ")) {
+          client.socket.send((0, import_core4.serialize)({
+            type: "ERROR",
+            payload: { code: 403, message: `Access Denied for map ${message.payload.mapName}` }
+          }));
+          return;
+        }
+        const { mapName, path } = message.payload;
+        try {
+          const mapForBucket = await this.getMapAsync(mapName, "OR");
+          if (mapForBucket instanceof import_core4.ORMap) {
+            const tree = mapForBucket.getMerkleTree();
+            const buckets = tree.getBuckets(path);
+            const isLeaf = tree.isLeaf(path);
+            if (isLeaf) {
+              const keys = tree.getKeysInBucket(path);
+              const entries = [];
+              for (const key of keys) {
+                const recordsMap = mapForBucket.getRecordsMap(key);
+                if (recordsMap && recordsMap.size > 0) {
+                  entries.push({
+                    key,
+                    records: Array.from(recordsMap.values()),
+                    tombstones: mapForBucket.getTombstones()
+                  });
+                }
+              }
+              client.socket.send((0, import_core4.serialize)({
+                type: "ORMAP_SYNC_RESP_LEAF",
+                payload: { mapName, path, entries }
+              }));
+            } else {
+              client.socket.send((0, import_core4.serialize)({
+                type: "ORMAP_SYNC_RESP_BUCKETS",
+                payload: { mapName, path, buckets }
+              }));
+            }
+          }
+        } catch (err) {
+          logger.error({ err, mapName }, "Failed to load map for ORMAP_MERKLE_REQ_BUCKET");
+        }
+        break;
+      }
+      case "ORMAP_DIFF_REQUEST": {
+        if (!this.securityManager.checkPermission(client.principal, message.payload.mapName, "READ")) {
+          client.socket.send((0, import_core4.serialize)({
+            type: "ERROR",
+            payload: { code: 403, message: `Access Denied for map ${message.payload.mapName}` }
+          }));
+          return;
+        }
+        const { mapName: diffMapName, keys } = message.payload;
+        try {
+          const mapForDiff = await this.getMapAsync(diffMapName, "OR");
+          if (mapForDiff instanceof import_core4.ORMap) {
+            const entries = [];
+            const allTombstones = mapForDiff.getTombstones();
+            for (const key of keys) {
+              const recordsMap = mapForDiff.getRecordsMap(key);
+              entries.push({
+                key,
+                records: recordsMap ? Array.from(recordsMap.values()) : [],
+                tombstones: allTombstones
+              });
+            }
+            client.socket.send((0, import_core4.serialize)({
+              type: "ORMAP_DIFF_RESPONSE",
+              payload: { mapName: diffMapName, entries }
+            }));
+          }
+        } catch (err) {
+          logger.error({ err, mapName: diffMapName }, "Failed to load map for ORMAP_DIFF_REQUEST");
+        }
+        break;
+      }
+      case "ORMAP_PUSH_DIFF": {
+        if (!this.securityManager.checkPermission(client.principal, message.payload.mapName, "PUT")) {
+          client.socket.send((0, import_core4.serialize)({
+            type: "ERROR",
+            payload: { code: 403, message: `Access Denied for map ${message.payload.mapName}` }
+          }));
+          return;
+        }
+        const { mapName: pushMapName, entries: pushEntries } = message.payload;
+        try {
+          const mapForPush = await this.getMapAsync(pushMapName, "OR");
+          if (mapForPush instanceof import_core4.ORMap) {
+            let totalAdded = 0;
+            let totalUpdated = 0;
+            for (const entry of pushEntries) {
+              const { key, records, tombstones } = entry;
+              const result = mapForPush.mergeKey(key, records, tombstones);
+              totalAdded += result.added;
+              totalUpdated += result.updated;
+            }
+            if (totalAdded > 0 || totalUpdated > 0) {
+              logger.info({ mapName: pushMapName, added: totalAdded, updated: totalUpdated, clientId: client.id }, "Merged ORMap diff from client");
+              for (const entry of pushEntries) {
+                for (const record of entry.records) {
+                  this.broadcast({
+                    type: "SERVER_EVENT",
+                    payload: {
+                      mapName: pushMapName,
+                      eventType: "OR_ADD",
+                      key: entry.key,
+                      orRecord: record
+                    }
+                  }, client.id);
+                }
+              }
+              if (this.storage) {
+                for (const entry of pushEntries) {
+                  const recordsMap = mapForPush.getRecordsMap(entry.key);
+                  if (recordsMap && recordsMap.size > 0) {
+                    await this.storage.store(pushMapName, entry.key, {
+                      type: "OR",
+                      records: Array.from(recordsMap.values())
+                    });
+                  }
+                }
+              }
+            }
+          }
+        } catch (err) {
+          logger.error({ err, mapName: pushMapName }, "Failed to process ORMAP_PUSH_DIFF");
+        }
+        break;
+      }
       default:
         logger.warn({ type: message.type }, "Unknown message type");
     }
@@ -2422,6 +2613,75 @@ var ServerCoordinator = class {
       this.reportLocalHlc();
     }, GC_INTERVAL_MS);
   }
+  // ============ Heartbeat Methods ============
+  /**
+   * Starts the periodic check for dead clients (those that haven't sent PING).
+   */
+  startHeartbeatCheck() {
+    this.heartbeatCheckInterval = setInterval(() => {
+      this.evictDeadClients();
+    }, CLIENT_HEARTBEAT_CHECK_INTERVAL_MS);
+  }
+  /**
+   * Handles incoming PING message from client.
+   * Responds with PONG immediately.
+   */
+  handlePing(client, clientTimestamp) {
+    client.lastPingReceived = Date.now();
+    const pongMessage = {
+      type: "PONG",
+      timestamp: clientTimestamp,
+      serverTime: Date.now()
+    };
+    if (client.socket.readyState === import_ws2.WebSocket.OPEN) {
+      client.socket.send((0, import_core4.serialize)(pongMessage));
+    }
+  }
+  /**
+   * Checks if a client is still alive based on heartbeat.
+   */
+  isClientAlive(clientId) {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+    const idleTime = Date.now() - client.lastPingReceived;
+    return idleTime < CLIENT_HEARTBEAT_TIMEOUT_MS;
+  }
+  /**
+   * Returns how long the client has been idle (no PING received).
+   */
+  getClientIdleTime(clientId) {
+    const client = this.clients.get(clientId);
+    if (!client) return Infinity;
+    return Date.now() - client.lastPingReceived;
+  }
+  /**
+   * Evicts clients that haven't sent a PING within the timeout period.
+   */
+  evictDeadClients() {
+    const now = Date.now();
+    const deadClients = [];
+    for (const [clientId, client] of this.clients) {
+      if (client.isAuthenticated) {
+        const idleTime = now - client.lastPingReceived;
+        if (idleTime > CLIENT_HEARTBEAT_TIMEOUT_MS) {
+          deadClients.push(clientId);
+        }
+      }
+    }
+    for (const clientId of deadClients) {
+      const client = this.clients.get(clientId);
+      if (client) {
+        logger.warn({
+          clientId,
+          idleTime: now - client.lastPingReceived,
+          timeoutMs: CLIENT_HEARTBEAT_TIMEOUT_MS
+        }, "Evicting dead client (heartbeat timeout)");
+        if (client.socket.readyState === import_ws2.WebSocket.OPEN) {
+          client.socket.close(4002, "Heartbeat timeout");
+        }
+      }
+    }
+  }
   reportLocalHlc() {
     let minHlc = this.hlc.now();
     for (const client of this.clients.values()) {