@rljson/server 0.0.13 → 0.0.15

package/README.architecture.md

@@ -86,7 +86,9 @@ The `Node` class sits above `Server` and `Client`, bridging `@rljson/network` to
 3. **Manages transport**: Uses injectable factories (`CreateHubTransport`/`CreateClientTransport`) to create the transport layer, keeping the Node class transport-agnostic.
 4. **Agent lifecycle**: An optional `createAgent` factory in `NodeDeps` is called on every `ready` event. The returned `AgentHandle.stop()` is called before the next role transition. This enables application-level wiring (e.g. FsAgent) without circular dependencies.
 5. **Serialized transitions**: Role transitions are queued — a new `role-changed` event waits for the previous transition to complete before starting. This prevents race conditions between teardown and setup.
-6. **Error resilience**: Errors in user-provided code (agent factories, transport factories) are caught and logged. The node continues functioning — a failed transport degrades connectivity but doesn't crash, a failed agent leaves the node's core intact.
+6. **Hub-changed reconnect** (v0.0.14): Subscribes to `NetworkManager`'s `hub-changed` event in addition to `role-changed`. When the hub changes but the node's role stays `client`, the node tears down its connection and reconnects to the new hub. This prevents split-brain scenarios where clients remain attached to a stale hub.
+7. **Clean socket teardown** (v0.0.14): `_tearDownCurrentRole()` explicitly calls `disconnect()` on client sockets before clearing the reference. This prevents orphaned Socket.IO connections from auto-reconnecting to the old hub.
+8. **Error resilience**: Errors in user-provided code (agent factories, transport factories) are caught and logged. The node continues functioning — a failed transport degrades connectivity but doesn't crash, a failed agent leaves the node's core intact.
 
 ```text
 ┌─────────────────────────────────────────┐

package/README.blog.md

@@ -17,3 +17,11 @@ Add posts as Markdown entries in this file (newest last). Keep each post small a
 - Why it matters
 - Links: PRs, docs, demos
 ```
+
+## 2026-03-20 — v0.0.14: Split-brain fix and hub-changed reconnect
+
+- Node class now listens to `hub-changed` events from NetworkManager — clients reconnect when hub changes but role stays `client`
+- `_tearDownCurrentRole()` explicitly disconnects sockets before clearing references — prevents orphaned connections
+- Validated on 4-node Windows test lab: E2E Reports 18 & 19 both score **38/41 passed, 0 failures**
+- Previous Report 17 showed split-brain (two simultaneous hubs, 23/41 passed) — now fully resolved
+- PR: https://github.com/rljson/server/pull/14

package/README.trouble.md

@@ -10,9 +10,42 @@ found in the LICENSE file in the root of this package.
 
 ## Table of contents <!-- omit in toc -->
 
+- [Split-Brain: Clients not reconnecting on hub change (fixed in v0.0.14)](#split-brain-clients-not-reconnecting-on-hub-change-fixed-in-v0014)
 - [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
 - [Test Isolation: Socket.IO event listener accumulation](#test-isolation-socketio-event-listener-accumulation)
 
+## Split-Brain: Clients not reconnecting on hub change (fixed in v0.0.14)
+
+Date: 2026-03-20
+
+**Problem:**
+
+In a 4-node deployment, two nodes simultaneously acted as hub (split-brain). Clients stayed connected to the old hub while a new hub was elected. File sync stopped working because the hub had no real clients.
+
+**Symptoms:**
+
+- E2E Report 17: 23/41 passed, 18 failed
+- Two nodes reporting `role=hub` simultaneously
+- Files written by one hub never appearing on clients
+- File counts diverging between nodes (hub accumulating files, clients stuck)
+
+**Root Cause:**
+
+Two bugs in the `Node` class:
+
+1. **Missing `hub-changed` listener**: Node only subscribed to `role-changed` from NetworkManager. When the hub changed but the node's role stayed `client`, the `role-changed` handler skipped (same role). Clients never reconnected to the new hub.
+
+2. **No socket disconnect on teardown**: `_tearDownCurrentRole()` set `_clientSocket = undefined` without calling `disconnect()`. The orphaned Socket.IO connection kept auto-reconnecting to the old hub (especially with the `socket.connect()` reconnect fix from v0.0.13).
+
+**Solution (v0.0.14):**
+
+1. Added `_onHubChanged` listener that tears down and reconnects when hub changes while role stays `client`
+2. Added explicit `socket.disconnect()` call in `_tearDownCurrentRole()` before clearing the reference
+
+**Validation:**
+
+- E2E Reports 18 & 19: **38/41 passed, 0 failures** on 4-node test lab
+
 ## Vscode Windows: Debugging is not working
 
 Date: 2025-03-08

package/dist/README.architecture.md

@@ -86,7 +86,9 @@ The `Node` class sits above `Server` and `Client`, bridging `@rljson/network` to
 3. **Manages transport**: Uses injectable factories (`CreateHubTransport`/`CreateClientTransport`) to create the transport layer, keeping the Node class transport-agnostic.
 4. **Agent lifecycle**: An optional `createAgent` factory in `NodeDeps` is called on every `ready` event. The returned `AgentHandle.stop()` is called before the next role transition. This enables application-level wiring (e.g. FsAgent) without circular dependencies.
 5. **Serialized transitions**: Role transitions are queued — a new `role-changed` event waits for the previous transition to complete before starting. This prevents race conditions between teardown and setup.
-6. **Error resilience**: Errors in user-provided code (agent factories, transport factories) are caught and logged. The node continues functioning — a failed transport degrades connectivity but doesn't crash, a failed agent leaves the node's core intact.
+6. **Hub-changed reconnect** (v0.0.14): Subscribes to `NetworkManager`'s `hub-changed` event in addition to `role-changed`. When the hub changes but the node's role stays `client`, the node tears down its connection and reconnects to the new hub. This prevents split-brain scenarios where clients remain attached to a stale hub.
+7. **Clean socket teardown** (v0.0.14): `_tearDownCurrentRole()` explicitly calls `disconnect()` on client sockets before clearing the reference. This prevents orphaned Socket.IO connections from auto-reconnecting to the old hub.
+8. **Error resilience**: Errors in user-provided code (agent factories, transport factories) are caught and logged. The node continues functioning — a failed transport degrades connectivity but doesn't crash, a failed agent leaves the node's core intact.
 
 ```text
 ┌─────────────────────────────────────────┐

package/dist/README.blog.md

@@ -17,3 +17,11 @@ Add posts as Markdown entries in this file (newest last). Keep each post small a
 - Why it matters
 - Links: PRs, docs, demos
 ```
+
+## 2026-03-20 — v0.0.14: Split-brain fix and hub-changed reconnect
+
+- Node class now listens to `hub-changed` events from NetworkManager — clients reconnect when hub changes but role stays `client`
+- `_tearDownCurrentRole()` explicitly disconnects sockets before clearing references — prevents orphaned connections
+- Validated on 4-node Windows test lab: E2E Reports 18 & 19 both score **38/41 passed, 0 failures**
+- Previous Report 17 showed split-brain (two simultaneous hubs, 23/41 passed) — now fully resolved
+- PR: https://github.com/rljson/server/pull/14

package/dist/README.trouble.md

@@ -10,9 +10,42 @@ found in the LICENSE file in the root of this package.
 
 ## Table of contents <!-- omit in toc -->
 
+- [Split-Brain: Clients not reconnecting on hub change (fixed in v0.0.14)](#split-brain-clients-not-reconnecting-on-hub-change-fixed-in-v0014)
 - [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
 - [Test Isolation: Socket.IO event listener accumulation](#test-isolation-socketio-event-listener-accumulation)
 
+## Split-Brain: Clients not reconnecting on hub change (fixed in v0.0.14)
+
+Date: 2026-03-20
+
+**Problem:**
+
+In a 4-node deployment, two nodes simultaneously acted as hub (split-brain). Clients stayed connected to the old hub while a new hub was elected. File sync stopped working because the hub had no real clients.
+
+**Symptoms:**
+
+- E2E Report 17: 23/41 passed, 18 failed
+- Two nodes reporting `role=hub` simultaneously
+- Files written by one hub never appearing on clients
+- File counts diverging between nodes (hub accumulating files, clients stuck)
+
+**Root Cause:**
+
+Two bugs in the `Node` class:
+
+1. **Missing `hub-changed` listener**: Node only subscribed to `role-changed` from NetworkManager. When the hub changed but the node's role stayed `client`, the `role-changed` handler skipped (same role). Clients never reconnected to the new hub.
+
+2. **No socket disconnect on teardown**: `_tearDownCurrentRole()` set `_clientSocket = undefined` without calling `disconnect()`. The orphaned Socket.IO connection kept auto-reconnecting to the old hub (especially with the `socket.connect()` reconnect fix from v0.0.13).
+
+**Solution (v0.0.14):**
+
+1. Added `_onHubChanged` listener that tears down and reconnects when hub changes while role stays `client`
+2. Added explicit `socket.disconnect()` call in `_tearDownCurrentRole()` before clearing the reference
+
+**Validation:**
+
+- E2E Reports 18 & 19: **38/41 passed, 0 failures** on 4-node test lab
+
 ## Vscode Windows: Debugging is not working
 
 Date: 2025-03-08

package/dist/node.d.ts

@@ -163,6 +163,13 @@ export declare class Node {
      * @param cb - Callback
      */
     off<E extends NodeEventName>(event: E, cb: NodeEvents[E]): void;
+    /**
+     * Handle hub-changed while role stays 'client'.
+     * When NetworkManager emits hub-changed but NOT role-changed (because
+     * old role === new role === 'client'), the Node must tear down the old
+     * client connection and reconnect to the new hub.
+     */
+    private _onHubChanged;
     private _onRoleChanged;
     private _performTransition;
     private _becomeHub;

package/dist/server.js

@@ -1440,6 +1440,7 @@ class Node {
     this._bsMem = new BsMem();
     this._running = true;
     this._networkManager.on("role-changed", this._onRoleChanged);
+    this._networkManager.on("hub-changed", this._onHubChanged);
     await this._networkManager.start();
   }
   /**
@@ -1449,6 +1450,7 @@ class Node {
     if (!this._running) return;
     this._running = false;
     this._networkManager.off("role-changed", this._onRoleChanged);
+    this._networkManager.off("hub-changed", this._onHubChanged);
     if (this._transitioning) {
       await this._transitioning;
       this._transitioning = void 0;
@@ -1526,6 +1528,24 @@ class Node {
   // .........................................................................
   // Role transitions
   // .........................................................................
+  /**
+   * Handle hub-changed while role stays 'client'.
+   * When NetworkManager emits hub-changed but NOT role-changed (because
+   * old role === new role === 'client'), the Node must tear down the old
+   * client connection and reconnect to the new hub.
+   */
+  _onHubChanged = () => {
+    if (!this._running || this._role !== "client") return;
+    const topology = this._networkManager.getTopology();
+    if (topology.myRole !== "client") return;
+    this._logger.info("Node", "Hub changed while client — reconnecting");
+    const prev = this._transitioning ?? Promise.resolve();
+    this._transitioning = prev.then(async () => {
+      if (!this._running || this._role !== "client") return;
+      await this._tearDownCurrentRole();
+      await this._becomeClient();
+    });
+  };
   _onRoleChanged = (event) => {
     if (!this._running) return;
     const { current } = event;
@@ -1549,6 +1569,18 @@ class Node {
         await this._becomeClient();
         break;
     }
+    if (!this._running) return;
+    const networkRole = this._networkManager.getTopology().myRole;
+    if (networkRole !== this._role && networkRole !== "unassigned") {
+      this._logger.info(
+        "Node",
+        `Reconciling stale role: node=${this._role} → network=${networkRole}`
+      );
+      await this._performTransition({
+        previous: this._role,
+        current: networkRole
+      });
+    }
   }
   async _becomeHub() {
     await this._ioMem.init();
@@ -1635,6 +1667,9 @@ class Node {
       await this._client.tearDown();
       this._client = void 0;
     }
+    if (this._clientSocket && "disconnect" in this._clientSocket) {
+      this._clientSocket.disconnect();
+    }
     this._clientSocket = void 0;
   }
   async _startAgent(ctx) {

package/package.json

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