@rljson/server 0.0.15 → 0.0.16

package/dist/server.d.ts

@@ -49,6 +49,19 @@ export interface ServerOptions {
      * Defaults to false (local cache enabled).
      */
     disableLocalCache?: boolean;
+    /**
+     * Interval in milliseconds for application-level health checks.
+     * The server pings each connected client and prunes those that
+     * do not respond within {@link healthCheckTimeoutMs}.
+     * Defaults to 30 000 (30 s). Set to 0 to disable health checks.
+     */
+    healthCheckIntervalMs?: number;
+    /**
+     * Timeout in milliseconds to wait for a health check pong.
+     * Clients that do not respond within this window are pruned.
+     * Defaults to 10 000 (10 s).
+     */
+    healthCheckTimeoutMs?: number;
 }
 export declare class Server extends BaseNode {
     private _route;
@@ -77,6 +90,9 @@ export declare class Server extends BaseNode {
     private _disableLocalCache;
     private _latestRef;
     private _bootstrapHeartbeatTimer?;
+    private _healthCheckIntervalMs;
+    private _healthCheckTimeoutMs;
+    private _healthCheckTimer?;
     private _tornDown;
     constructor(_route: Route, _localIo: Io, _localBs: Bs, options?: ServerOptions);
     /**
@@ -181,6 +197,18 @@ export declare class Server extends BaseNode {
      * Each client's dedup pipeline will filter out refs it already has.
      */
     private _broadcastBootstrapHeartbeat;
+    /**
+     * Starts the periodic health check timer if not already running.
+     * Each cycle sends a ping to every non-broadcast client and waits
+     * for a pong. Clients that do not respond are pruned.
+     */
+    private _startHealthChecks;
+    /**
+     * Sends a health ping to each connected (non-broadcast) client.
+     * If a client does not respond within `_healthCheckTimeoutMs`,
+     * the server force-disconnects and removes it.
+     */
+    private _runHealthCheck;
     /**
      * Starts the periodic bootstrap heartbeat timer if configured
      * and not already running.

package/dist/server.js

@@ -393,9 +393,14 @@ class Client extends BaseNode {
     };
     socket.on("disconnect", disconnectHandler);
     socket.on("connect", reconnectHandler);
+    const healthHandler = (payload) => {
+      sockets.ioUp.emit("__health:pong", { nonce: payload.nonce });
+    };
+    sockets.ioDown.on("__health:ping", healthHandler);
     this._connectionCleanup = () => {
       socket.off("disconnect", disconnectHandler);
       socket.off("connect", reconnectHandler);
+      sockets.ioDown.off("__health:ping", healthHandler);
     };
   }
   /**
@@ -655,6 +660,8 @@ class Server extends BaseNode {
     this._logger = options?.logger ?? noopLogger;
     this._peerInitTimeoutMs = options?.peerInitTimeoutMs ?? 3e4;
     this._disableLocalCache = options?.disableLocalCache ?? false;
+    this._healthCheckIntervalMs = options?.healthCheckIntervalMs ?? 3e4;
+    this._healthCheckTimeoutMs = options?.healthCheckTimeoutMs ?? 1e4;
     this._syncConfig = options?.syncConfig;
     this._refLogSize = options?.refLogSize ?? 1e3;
     this._ackTimeoutMs = options?.ackTimeoutMs ?? options?.syncConfig?.ackTimeoutMs ?? 1e4;
@@ -728,6 +735,10 @@ class Server extends BaseNode {
   // Bootstrap state
   _latestRef;
   _bootstrapHeartbeatTimer;
+  // Health check state
+  _healthCheckIntervalMs;
+  _healthCheckTimeoutMs;
+  _healthCheckTimer;
   _tornDown = false;
   /**
    * Initializes Io and Bs multis on the server.
@@ -786,6 +797,7 @@ class Server extends BaseNode {
       this._registerDisconnectHandler(clientId, ioUp);
       this._sendBootstrap(ioDown);
       this._startBootstrapHeartbeat();
+      this._startHealthChecks();
       this._logger.info("Server", "Client socket added successfully", {
         clientId,
         totalClients: this._clients.size
@@ -836,6 +848,7 @@ class Server extends BaseNode {
     this._registerDisconnectHandler(clientId, ioUp);
     this._sendBootstrap(ioDown);
     this._startBootstrapHeartbeat();
+    this._startHealthChecks();
     this._logger.info("Server", "Broadcast-only socket added", {
       clientId,
       totalClients: this._clients.size
@@ -1034,6 +1047,54 @@ class Server extends BaseNode {
       ioDown.emit(this._events.bootstrap, payload);
     }
   }
+  // ...........................................................................
+  // Health checks
+  // ...........................................................................
+  /**
+   * Starts the periodic health check timer if not already running.
+   * Each cycle sends a ping to every non-broadcast client and waits
+   * for a pong. Clients that do not respond are pruned.
+   */
+  _startHealthChecks() {
+    if (this._healthCheckTimer || this._healthCheckIntervalMs <= 0) return;
+    this._healthCheckTimer = setInterval(() => {
+      this._runHealthCheck();
+    }, this._healthCheckIntervalMs);
+    this._healthCheckTimer.unref();
+  }
+  /**
+   * Sends a health ping to each connected (non-broadcast) client.
+   * If a client does not respond within `_healthCheckTimeoutMs`,
+   * the server force-disconnects and removes it.
+   */
+  _runHealthCheck() {
+    for (const [clientId, { ioUp, ioDown }] of this._clients.entries()) {
+      if (clientId.startsWith("broadcast_")) continue;
+      const nonce = Math.random().toString(36).slice(2);
+      let resolved = false;
+      const handler = (payload) => {
+        if (payload?.nonce !== nonce) return;
+        resolved = true;
+        ioUp.off("__health:pong", handler);
+        clearTimeout(timer);
+      };
+      ioUp.on("__health:pong", handler);
+      const timer = setTimeout(() => {
+        if (resolved) return;
+        ioUp.off("__health:pong", handler);
+        this._logger.warn(
+          "Server.Health",
+          "Client failed health check — pruning",
+          { clientId }
+        );
+        if ("disconnect" in ioUp) {
+          ioUp.disconnect(true);
+        }
+        this.removeSocket(clientId);
+      }, this._healthCheckTimeoutMs);
+      ioDown.emit("__health:ping", { nonce });
+    }
+  }
   /**
    * Starts the periodic bootstrap heartbeat timer if configured
    * and not already running.
@@ -1315,6 +1376,10 @@ class Server extends BaseNode {
       clearInterval(this._bootstrapHeartbeatTimer);
       this._bootstrapHeartbeatTimer = void 0;
     }
+    if (this._healthCheckTimer) {
+      clearInterval(this._healthCheckTimer);
+      this._healthCheckTimer = void 0;
+    }
     this._removeAllListeners();
     for (const cleanup of this._disconnectCleanups.values()) {
       cleanup();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/server",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Rljson server description",
   "homepage": "https://github.com/rljson/server",
   "bugs": "https://github.com/rljson/server/issues",