@rljson/server 0.0.15 → 0.0.17

package/dist/node.d.ts

@@ -121,6 +121,7 @@ export declare class Node {
     private _bsMem?;
     private _role;
     private _running;
+    private _transportReady;
     private _transitioning?;
     private _listeners;
     private readonly _logger;
@@ -149,6 +150,12 @@ export declare class Node {
     get socket(): SocketLike | undefined;
     /** Whether the node is currently running. */
     get isRunning(): boolean;
+    /**
+     * Whether the node's transport is fully ready.
+     * `false` during role transitions and before the first transition completes.
+     * `true` only after `_becomeHub()` or `_becomeClient()` has finished.
+     */
+    get isTransportReady(): boolean;
     /** The underlying NetworkManager. */
     get networkManager(): NetworkManager;
     /**

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();
@@ -1423,6 +1488,7 @@ class Node {
   _bsMem;
   _role = "unassigned";
   _running = false;
+  _transportReady = false;
   _transitioning;
   _listeners = /* @__PURE__ */ new Map();
   _logger;
@@ -1449,6 +1515,7 @@ class Node {
   async stop() {
     if (!this._running) return;
     this._running = false;
+    this._transportReady = false;
     this._networkManager.off("role-changed", this._onRoleChanged);
     this._networkManager.off("hub-changed", this._onHubChanged);
     if (this._transitioning) {
@@ -1495,6 +1562,14 @@ class Node {
   get isRunning() {
     return this._running;
   }
+  /**
+   * Whether the node's transport is fully ready.
+   * `false` during role transitions and before the first transition completes.
+   * `true` only after `_becomeHub()` or `_becomeClient()` has finished.
+   */
+  get isTransportReady() {
+    return this._transportReady;
+  }
   /** The underlying NetworkManager. */
   get networkManager() {
     return this._networkManager;
@@ -1542,6 +1617,7 @@ class Node {
     const prev = this._transitioning ?? Promise.resolve();
     this._transitioning = prev.then(async () => {
       if (!this._running || this._role !== "client") return;
+      this._transportReady = false;
       await this._tearDownCurrentRole();
       await this._becomeClient();
     });
@@ -1557,6 +1633,7 @@ class Node {
     if (!this._running) return;
     const { current } = event;
     if (current === this._role) return;
+    this._transportReady = false;
     this._logger.info("Node", `Role changing: ${this._role} → ${current}`);
     await this._tearDownCurrentRole();
     this._role = current;
@@ -1605,6 +1682,7 @@ class Node {
         `Hub transport failed (no incoming connections): ${err}`
       );
     }
+    this._transportReady = true;
     const ctx = { role: "hub", server: this._server };
     this._emit("ready", ctx);
     await this._startAgent(ctx);
@@ -1642,6 +1720,7 @@ class Node {
     );
     await this._client.init();
     this._logger.info("Node", `Now client — connected to hub ${hubAddress}`);
+    this._transportReady = true;
     const ctx = {
       role: "client",
       client: this._client,

package/package.json

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