@rljson/server 0.0.9 → 0.0.10

package/README.public.md

@@ -164,6 +164,9 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `connector` – Connector wired to the route and socket (available when route was provided)
 - `route` – the Route passed to the constructor
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
+- `isConnected` – whether the socket is currently connected (tracks `disconnect`/`connect` events)
+- `onDisconnect(callback)` – registers a callback that fires when the socket disconnects (receives the reason string)
+- `onReconnect(callback)` – registers a callback that fires when the socket reconnects after a previous disconnect
 
 ### Server API
 
@@ -216,6 +219,60 @@ The same pattern is used for Bs (blob storage).
 - Peer initialization is guarded by a configurable timeout (`peerInitTimeoutMs`, default 30 s) on both server and client. On the server it prevents `addSocket()` from hanging on unresponsive clients; on the client it prevents `init()` from hanging when the server is unreachable.
 - Logging is opt-in via `{ logger }` options. Use `ConsoleLogger` for development, `BufferedLogger` for testing, `FilteredLogger` for production. Default is `NoopLogger` (zero overhead).
 
+## Reconnect handling
+
+The `Client` class tracks socket connection state and provides hooks for upper layers to react to disconnects and reconnections.
+
+### How it works
+
+Socket.IO auto-reconnects at the transport level by default. When the connection drops and is restored:
+
+1. The client-side Socket.IO socket emits `'disconnect'` then (later) `'connect'`.
+2. The `Client` class listens for these events and updates `isConnected`.
+3. Registered `onDisconnect` / `onReconnect` callbacks fire.
+4. The server auto-detects the dropped socket (`removeSocket`) and re-registers the reconnected socket via a new `'connection'` event.
+5. The server sends a bootstrap ref to the reconnected client, triggering a re-sync via the Connector's bootstrap handler.
+
+### Usage
+
+```ts
+import { Client } from '@rljson/server';
+
+const client = new Client(socket, io, bs, route, {
+  logger: new ConsoleLogger(),
+});
+await client.init();
+
+// Track connection state
+console.log(client.isConnected); // true
+
+// React to disconnects
+client.onDisconnect((reason) => {
+  console.warn(`Disconnected: ${reason}`);
+  // Pause user-facing sync indicators, queue local changes, etc.
+});
+
+// React to reconnections
+client.onReconnect(() => {
+  console.info('Reconnected to server');
+  // Resume sync, trigger re-fetch, update UI, etc.
+});
+```
+
+### What survives a reconnect
+
+| Layer             | Survives? | Details                                                           |
+| ----------------- | --------- | ----------------------------------------------------------------- |
+| Socket.IO         | ✅         | Auto-reconnects, reuses the same client-side socket object        |
+| SocketIoBridge    | ✅         | Wraps the same socket — event listeners are preserved             |
+| IoPeer / BsPeer   | ✅         | Listeners remain on the client socket; server re-creates its side |
+| Connector         | ✅         | Listeners remain; server bootstrap re-syncs state                 |
+| IoMulti / BsMulti | ✅         | Multi layers are unaffected; local Io/Bs always available         |
+
+### Cleanup
+
+All connection handlers are cleaned up automatically on `tearDown()`. After tearDown, no callbacks will fire.
+
 ## Logging
 
 Both `Server` and `Client` support structured logging via an injectable `ServerLogger` interface. Logging is opt-in — by default a zero-overhead `NoopLogger` is used.

package/dist/README.public.md

@@ -164,6 +164,9 @@ This is implemented with `IoMulti` and `BsMulti` internally, but the public API
 - `connector` – Connector wired to the route and socket (available when route was provided)
 - `route` – the Route passed to the constructor
 - `logger` – the `ServerLogger` instance (defaults to `noopLogger`)
+- `isConnected` – whether the socket is currently connected (tracks `disconnect`/`connect` events)
+- `onDisconnect(callback)` – registers a callback that fires when the socket disconnects (receives the reason string)
+- `onReconnect(callback)` – registers a callback that fires when the socket reconnects after a previous disconnect
 
 ### Server API
 
@@ -216,6 +219,60 @@ The same pattern is used for Bs (blob storage).
 - Peer initialization is guarded by a configurable timeout (`peerInitTimeoutMs`, default 30 s) on both server and client. On the server it prevents `addSocket()` from hanging on unresponsive clients; on the client it prevents `init()` from hanging when the server is unreachable.
 - Logging is opt-in via `{ logger }` options. Use `ConsoleLogger` for development, `BufferedLogger` for testing, `FilteredLogger` for production. Default is `NoopLogger` (zero overhead).
 
+## Reconnect handling
+
+The `Client` class tracks socket connection state and provides hooks for upper layers to react to disconnects and reconnections.
+
+### How it works
+
+Socket.IO auto-reconnects at the transport level by default. When the connection drops and is restored:
+
+1. The client-side Socket.IO socket emits `'disconnect'` then (later) `'connect'`.
+2. The `Client` class listens for these events and updates `isConnected`.
+3. Registered `onDisconnect` / `onReconnect` callbacks fire.
+4. The server auto-detects the dropped socket (`removeSocket`) and re-registers the reconnected socket via a new `'connection'` event.
+5. The server sends a bootstrap ref to the reconnected client, triggering a re-sync via the Connector's bootstrap handler.
+
+### Usage
+
+```ts
+import { Client } from '@rljson/server';
+
+const client = new Client(socket, io, bs, route, {
+  logger: new ConsoleLogger(),
+});
+await client.init();
+
+// Track connection state
+console.log(client.isConnected); // true
+
+// React to disconnects
+client.onDisconnect((reason) => {
+  console.warn(`Disconnected: ${reason}`);
+  // Pause user-facing sync indicators, queue local changes, etc.
+});
+
+// React to reconnections
+client.onReconnect(() => {
+  console.info('Reconnected to server');
+  // Resume sync, trigger re-fetch, update UI, etc.
+});
+```
+
+### What survives a reconnect
+
+| Layer             | Survives? | Details                                                           |
+| ----------------- | --------- | ----------------------------------------------------------------- |
+| Socket.IO         | ✅         | Auto-reconnects, reuses the same client-side socket object        |
+| SocketIoBridge    | ✅         | Wraps the same socket — event listeners are preserved             |
+| IoPeer / BsPeer   | ✅         | Listeners remain on the client socket; server re-creates its side |
+| Connector         | ✅         | Listeners remain; server bootstrap re-syncs state                 |
+| IoMulti / BsMulti | ✅         | Multi layers are unaffected; local Io/Bs always available         |
+
+### Cleanup
+
+All connection handlers are cleaned up automatically on `tearDown()`. After tearDown, no callbacks will fire.
+
 ## Logging
 
 Both `Server` and `Client` support structured logging via an injectable `ServerLogger` interface. Logging is opt-in — by default a zero-overhead `NoopLogger` is used.

package/dist/client.d.ts

@@ -45,6 +45,10 @@ export declare class Client extends BaseNode {
     private _syncConfig?;
     private _clientIdentity?;
     private _peerInitTimeoutMs;
+    private _isConnected;
+    private _disconnectCallbacks;
+    private _reconnectCallbacks;
+    private _connectionCleanup?;
     /**
      * Creates a Client instance
      * @param _socketToServer - Socket or namespace bundle to connect to server
@@ -91,11 +95,34 @@ export declare class Client extends BaseNode {
      * Returns the logger instance.
      */
     get logger(): ServerLogger;
+    /**
+     * Whether the client is currently connected to the server.
+     * Tracks socket-level connection state via `disconnect` and `connect` events.
+     */
+    get isConnected(): boolean;
+    /**
+     * Registers a callback that fires when the socket disconnects.
+     * The callback receives the disconnect reason string.
+     * @param callback - Invoked with the disconnect reason
+     */
+    onDisconnect(callback: (reason: string) => void): void;
+    /**
+     * Registers a callback that fires when the socket reconnects
+     * after a previous disconnect.
+     * @param callback - Invoked on reconnection
+     */
+    onReconnect(callback: () => void): void;
     /**
      * Creates Db and Connector from the route and IoMulti.
      * Called during init() when a route was provided.
      */
     private _setupDbAndConnector;
+    /**
+     * Registers socket-level disconnect/connect listeners.
+     * Logs state transitions and invokes registered callbacks.
+     * The `connect` callback only fires on RE-connections (not the initial connect).
+     */
+    private _registerConnectionHandlers;
     /**
      * Builds the Io multi with local and peer layers.
      */

package/dist/server.js

@@ -1159,6 +1159,11 @@ class Client extends BaseNode {
   _syncConfig;
   _clientIdentity;
   _peerInitTimeoutMs;
+  // Connection state
+  _isConnected = true;
+  _disconnectCallbacks = [];
+  _reconnectCallbacks = [];
+  _connectionCleanup;
   /**
    * Initializes Io and Bs multis and their peer bridges.
    * @returns The initialized Io implementation.
@@ -1171,6 +1176,7 @@ class Client extends BaseNode {
       if (this._route) {
         this._setupDbAndConnector();
       }
+      this._registerConnectionHandlers();
       await this.ready();
       this._logger.info("Client", "Client initialized successfully", {
         hasRoute: !!this._route,
@@ -1196,6 +1202,12 @@ class Client extends BaseNode {
    */
   async tearDown() {
     this._logger.info("Client", "Tearing down client");
+    if (this._connectionCleanup) {
+      this._connectionCleanup();
+      this._connectionCleanup = void 0;
+    }
+    this._disconnectCallbacks = [];
+    this._reconnectCallbacks = [];
     if (this._ioMulti && this._ioMulti.isOpen) {
       this._ioMulti.close();
     }
@@ -1244,6 +1256,29 @@ class Client extends BaseNode {
   get logger() {
     return this._logger;
   }
+  /**
+   * Whether the client is currently connected to the server.
+   * Tracks socket-level connection state via `disconnect` and `connect` events.
+   */
+  get isConnected() {
+    return this._isConnected;
+  }
+  /**
+   * Registers a callback that fires when the socket disconnects.
+   * The callback receives the disconnect reason string.
+   * @param callback - Invoked with the disconnect reason
+   */
+  onDisconnect(callback) {
+    this._disconnectCallbacks.push(callback);
+  }
+  /**
+   * Registers a callback that fires when the socket reconnects
+   * after a previous disconnect.
+   * @param callback - Invoked on reconnection
+   */
+  onReconnect(callback) {
+    this._reconnectCallbacks.push(callback);
+  }
   /**
    * Creates Db and Connector from the route and IoMulti.
    * Called during init() when a route was provided.
@@ -1263,6 +1298,44 @@ class Client extends BaseNode {
     );
     this._logger.info("Client", "Db and Connector created");
   }
+  /**
+   * Registers socket-level disconnect/connect listeners.
+   * Logs state transitions and invokes registered callbacks.
+   * The `connect` callback only fires on RE-connections (not the initial connect).
+   */
+  _registerConnectionHandlers() {
+    const sockets = normalizeSocketBundle(this._socketToServer);
+    const socket = sockets.ioUp;
+    const disconnectHandler = (...args) => {
+      const reason = typeof args[0] === "string" ? args[0] : "unknown";
+      this._isConnected = false;
+      this._logger.warn("Client", "Disconnected from server", { reason });
+      for (const cb of this._disconnectCallbacks) {
+        try {
+          cb(reason);
+        } catch {
+        }
+      }
+    };
+    const reconnectHandler = () => {
+      if (!this._isConnected) {
+        this._isConnected = true;
+        this._logger.info("Client", "Reconnected to server");
+        for (const cb of this._reconnectCallbacks) {
+          try {
+            cb();
+          } catch {
+          }
+        }
+      }
+    };
+    socket.on("disconnect", disconnectHandler);
+    socket.on("connect", reconnectHandler);
+    this._connectionCleanup = () => {
+      socket.off("disconnect", disconnectHandler);
+      socket.off("connect", reconnectHandler);
+    };
+  }
   /**
    * Builds the Io multi with local and peer layers.
    */

package/package.json

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