@rljson/server 0.0.10 → 0.0.11

package/README.architecture.md

@@ -77,6 +77,41 @@ In default setups you can reuse a single socket for all four channels; the code
 
 ## Core Components
 
+### 0. Node (Self-Organizing Orchestrator)
+
+The `Node` class sits above `Server` and `Client`, bridging `@rljson/network` topology events into role transitions. It:
+
+1. **Owns storage**: Creates a single `IoMem`/`BsMem` pair at `start()`, reused across all role transitions. Data survives hub↔client switches because `IoMem.close()` only flips `_isOpen` — the in-memory data is never cleared.
+2. **Reacts to topology**: Subscribes to `NetworkManager`'s `role-changed` event. On `'hub'`, tears down any Client and creates a Server. On `'client'`, tears down any Server and creates a Client.
+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.
+
+```text
+┌─────────────────────────────────────────┐
+│ Node                                    │
+│  ┌──────┐ ┌──────┐                      │
+│  │IoMem │ │BsMem │ ← owned by Node      │
+│  └──┬───┘ └──┬───┘                      │
+│     │        │                           │
+│  ┌──▼────────▼───┐  ┌────────────────┐  │
+│  │ Server/Client │──│ HubTransport   │  │
+│  │ (role-based)  │  │ or ClientSocket│  │
+│  └───────┬───────┘  └────────────────┘  │
+│          │                               │
+│  ┌───────▼───────┐                       │
+│  │ AgentHandle   │  ← optional, wired    │
+│  │ (e.g. FsAgent)│    via createAgent    │
+│  └───────────────┘                       │
+│     ▲                                    │
+│     │ role-changed                       │
+│  ┌──┴───────────┐                        │
+│  │NetworkManager│                        │
+│  └──────────────┘                        │
+└─────────────────────────────────────────┘
+```
+
 ### 1. Client
 
 The `Client` class provides a unified interface for data access by combining local storage with server storage.

package/README.public.md

@@ -637,6 +637,84 @@ await server.removeSocket(clientIds[0]);
 // Automatic: clients are removed when their socket emits 'disconnect'
 ```
 
+## Self-Organizing Node
+
+The `Node` class bridges `@rljson/network` peer discovery with `Server`/`Client` role transitions. Every node runs the same code — on startup it discovers peers, elects a hub, and automatically assumes the correct role.
+
+### Quick start
+
+```ts
+import { Node } from '@rljson/server';
+import { Route } from '@rljson/rljson';
+
+const node = new Node(
+  {
+    domain: 'my-app',
+    port: 3000,
+    route: Route.fromFlat('/sharedTree'),
+  },
+  {
+    createHubTransport: async (port) => { /* start HTTP+Socket.IO server */ },
+    createClientTransport: async (hubAddress) => { /* connect to hub */ },
+  },
+);
+
+await node.start();
+
+// The node auto-discovers peers and assumes a role:
+node.on('ready', ({ role, client, server, socket }) => {
+  console.log(`Role: ${role}`);          // 'hub' or 'client'
+  console.log(`Server: ${server}`);      // Server instance (hub only)
+  console.log(`Client: ${client}`);      // Client instance (client only)
+  console.log(`Socket: ${socket}`);      // Socket to hub (client only)
+});
+```
+
+### Data preservation across role transitions
+
+The `Node` owns a single `IoMem`/`BsMem` pair, created once at `start()` and reused across all role transitions. When a role changes (e.g., hub → client → hub), the underlying storage is re-initialized without losing data — `IoMem.close()` only sets `_isOpen = false`, the data in memory is preserved.
+
+This means:
+- Data written while hub survives a transition to client
+- Data written while client survives a transition to hub
+- A re-elected hub still serves all previously stored blobs and tables
+
+### Agent lifecycle
+
+The `createAgent` factory in `NodeDeps` is called on every role transition. The returned `AgentHandle.stop()` is called before the next transition or when the node stops. This is how you wire application-level agents (e.g. `FsAgent`) without creating circular dependencies:
+
+```ts
+const node = new Node(config, {
+  createHubTransport: ...,
+  createClientTransport: ...,
+  createAgent: async ({ role, client, server, socket }) => {
+    // Wire your agent here — called on every role transition
+    const stopSync = await startMySync(role, client, server);
+    return { stop: () => stopSync() };
+  },
+});
+```
+
+The Node serializes transitions — a new transition waits for the previous one to complete, ensuring agents are always stopped cleanly.
+
+Errors in `createAgent` or `agentHandle.stop()` are caught and logged — they never crash the node. Similarly, transport factory failures degrade connectivity but leave the node functional locally.
+
+### API
+
+| Property / Method     | Description                                           |
+| --------------------- | ----------------------------------------------------- |
+| `node.start()`        | Begin peer discovery and role assignment              |
+| `node.stop()`         | Tear down current role and stop discovery             |
+| `node.role`           | Current role: `'hub'`, `'client'`, or `'unassigned'`  |
+| `node.io`             | IoMulti from active Server or Client                  |
+| `node.bs`             | BsMulti from active Server or Client                  |
+| `node.server`         | Server instance (when hub), else `undefined`          |
+| `node.client`         | Client instance (when client), else `undefined`       |
+| `node.socket`         | Socket to hub (when client), else `undefined`         |
+| `node.topology`       | Current network topology snapshot                     |
+| `node.on(event, cb)`  | Subscribe to `'ready'`, `'role-changed'`, `'stopped'` |
+| `node.off(event, cb)` | Unsubscribe                                           |
+
 ## Architecture Overview
 
 ### Pull-Based Reference Architecture

package/dist/README.architecture.md

@@ -77,6 +77,41 @@ In default setups you can reuse a single socket for all four channels; the code
 
 ## Core Components
 
+### 0. Node (Self-Organizing Orchestrator)
+
+The `Node` class sits above `Server` and `Client`, bridging `@rljson/network` topology events into role transitions. It:
+
+1. **Owns storage**: Creates a single `IoMem`/`BsMem` pair at `start()`, reused across all role transitions. Data survives hub↔client switches because `IoMem.close()` only flips `_isOpen` — the in-memory data is never cleared.
+2. **Reacts to topology**: Subscribes to `NetworkManager`'s `role-changed` event. On `'hub'`, tears down any Client and creates a Server. On `'client'`, tears down any Server and creates a Client.
+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.
+
+```text
+┌─────────────────────────────────────────┐
+│ Node                                    │
+│  ┌──────┐ ┌──────┐                      │
+│  │IoMem │ │BsMem │ ← owned by Node      │
+│  └──┬───┘ └──┬───┘                      │
+│     │        │                           │
+│  ┌──▼────────▼───┐  ┌────────────────┐  │
+│  │ Server/Client │──│ HubTransport   │  │
+│  │ (role-based)  │  │ or ClientSocket│  │
+│  └───────┬───────┘  └────────────────┘  │
+│          │                               │
+│  ┌───────▼───────┐                       │
+│  │ AgentHandle   │  ← optional, wired    │
+│  │ (e.g. FsAgent)│    via createAgent    │
+│  └───────────────┘                       │
+│     ▲                                    │
+│     │ role-changed                       │
+│  ┌──┴───────────┐                        │
+│  │NetworkManager│                        │
+│  └──────────────┘                        │
+└─────────────────────────────────────────┘
+```
+
 ### 1. Client
 
 The `Client` class provides a unified interface for data access by combining local storage with server storage.

package/dist/README.public.md

@@ -637,6 +637,84 @@ await server.removeSocket(clientIds[0]);
 // Automatic: clients are removed when their socket emits 'disconnect'
 ```
 
+## Self-Organizing Node
+
+The `Node` class bridges `@rljson/network` peer discovery with `Server`/`Client` role transitions. Every node runs the same code — on startup it discovers peers, elects a hub, and automatically assumes the correct role.
+
+### Quick start
+
+```ts
+import { Node } from '@rljson/server';
+import { Route } from '@rljson/rljson';
+
+const node = new Node(
+  {
+    domain: 'my-app',
+    port: 3000,
+    route: Route.fromFlat('/sharedTree'),
+  },
+  {
+    createHubTransport: async (port) => { /* start HTTP+Socket.IO server */ },
+    createClientTransport: async (hubAddress) => { /* connect to hub */ },
+  },
+);
+
+await node.start();
+
+// The node auto-discovers peers and assumes a role:
+node.on('ready', ({ role, client, server, socket }) => {
+  console.log(`Role: ${role}`);          // 'hub' or 'client'
+  console.log(`Server: ${server}`);      // Server instance (hub only)
+  console.log(`Client: ${client}`);      // Client instance (client only)
+  console.log(`Socket: ${socket}`);      // Socket to hub (client only)
+});
+```
+
+### Data preservation across role transitions
+
+The `Node` owns a single `IoMem`/`BsMem` pair, created once at `start()` and reused across all role transitions. When a role changes (e.g., hub → client → hub), the underlying storage is re-initialized without losing data — `IoMem.close()` only sets `_isOpen = false`, the data in memory is preserved.
+
+This means:
+- Data written while hub survives a transition to client
+- Data written while client survives a transition to hub
+- A re-elected hub still serves all previously stored blobs and tables
+
+### Agent lifecycle
+
+The `createAgent` factory in `NodeDeps` is called on every role transition. The returned `AgentHandle.stop()` is called before the next transition or when the node stops. This is how you wire application-level agents (e.g. `FsAgent`) without creating circular dependencies:
+
+```ts
+const node = new Node(config, {
+  createHubTransport: ...,
+  createClientTransport: ...,
+  createAgent: async ({ role, client, server, socket }) => {
+    // Wire your agent here — called on every role transition
+    const stopSync = await startMySync(role, client, server);
+    return { stop: () => stopSync() };
+  },
+});
+```
+
+The Node serializes transitions — a new transition waits for the previous one to complete, ensuring agents are always stopped cleanly.
+
+Errors in `createAgent` or `agentHandle.stop()` are caught and logged — they never crash the node. Similarly, transport factory failures degrade connectivity but leave the node functional locally.
+
+### API
+
+| Property / Method     | Description                                           |
+| --------------------- | ----------------------------------------------------- |
+| `node.start()`        | Begin peer discovery and role assignment              |
+| `node.stop()`         | Tear down current role and stop discovery             |
+| `node.role`           | Current role: `'hub'`, `'client'`, or `'unassigned'`  |
+| `node.io`             | IoMulti from active Server or Client                  |
+| `node.bs`             | BsMulti from active Server or Client                  |
+| `node.server`         | Server instance (when hub), else `undefined`          |
+| `node.client`         | Client instance (when client), else `undefined`       |
+| `node.socket`         | Socket to hub (when client), else `undefined`         |
+| `node.topology`       | Current network topology snapshot                     |
+| `node.on(event, cb)`  | Subscribe to `'ready'`, `'role-changed'`, `'stopped'` |
+| `node.off(event, cb)` | Unsubscribe                                           |
+
 ## Architecture Overview
 
 ### Pull-Based Reference Architecture

package/dist/index.d.ts

@@ -4,8 +4,10 @@ export { FileLogger } from './file-logger.ts';
 export type { FileLoggerOptions } from './file-logger.ts';
 export { BufferedLogger, ConsoleLogger, FilteredLogger, NoopLogger, noopLogger, } from './logger.ts';
 export type { LogEntry, ServerLogger } from './logger.ts';
+export { Node } from './node.ts';
+export type { AgentHandle, CreateAgent, CreateClientTransport, CreateHubTransport, HubTransport, NodeConfig, NodeDeps, NodeEventName, NodeEvents, ReadyContext, } from './node.ts';
 export { Server } from './server.ts';
 export type { ServerOptions } from './server.ts';
 export { SocketIoBridge } from './socket-io-bridge.ts';
-export type { AckPayload, ConnectorPayload, GapFillRequest, GapFillResponse, SyncConfig, SyncEventNames, } from '@rljson/rljson';
 export { syncEvents } from '@rljson/rljson';
+export type { AckPayload, ConnectorPayload, GapFillRequest, GapFillResponse, SyncConfig, SyncEventNames, } from '@rljson/rljson';

package/dist/node.d.ts

@@ -0,0 +1,174 @@
+import { Bs } from '@rljson/bs';
+import { Io } from '@rljson/io';
+import { NetworkConfig, NetworkManagerOptions, NetworkTopology, NodeRole, RoleChangedEvent, NetworkManager } from '@rljson/network';
+import { Route } from '@rljson/rljson';
+import { Client, ClientOptions } from './client.ts';
+import { ServerLogger } from './logger.ts';
+import { Server, ServerOptions } from './server.ts';
+import { SocketLike } from './socket-bundle.ts';
+/**
+ * Transport handle returned by {@link CreateHubTransport}.
+ *
+ * Abstracts the "server side" of the transport layer so the Node class
+ * can accept incoming connections without knowing whether Socket.IO,
+ * WebSocket, or mock sockets are being used.
+ */
+export interface HubTransport {
+    /** Register a callback for incoming client connections. */
+    onConnection: (callback: (socket: SocketLike) => void) => void;
+    /** Shut down the transport (close HTTP server, etc.). */
+    close: () => Promise<void>;
+}
+/**
+ * Factory that creates a hub-side transport (e.g. HTTP + Socket.IO server).
+ * Called when this node becomes the hub.
+ */
+export type CreateHubTransport = (port: number) => Promise<HubTransport>;
+/**
+ * Factory that creates a client-side socket to connect to the hub.
+ * Called when this node becomes a client.
+ */
+export type CreateClientTransport = (hubAddress: string) => Promise<SocketLike>;
+/**
+ * Injectable dependencies for the Node class.
+ */
+export interface NodeDeps {
+    /** Factory to create hub-side transport. */
+    createHubTransport: CreateHubTransport;
+    /** Factory to create client-side socket to hub. */
+    createClientTransport: CreateClientTransport;
+    /** Options passed to NetworkManager (e.g. mock probe function). */
+    networkManagerOptions?: NetworkManagerOptions;
+    /**
+     * Optional factory for application-level agents (e.g. FsAgent).
+     * Called on every `ready` event. The returned handle's `stop()`
+     * is called before the next role transition or on `node.stop()`.
+     */
+    createAgent?: CreateAgent;
+}
+/**
+ * Configuration for a self-organizing Node.
+ */
+export interface NodeConfig {
+    /** Network domain for peer discovery. */
+    domain: string;
+    /** Port for this node's hub server / probing. */
+    port: number;
+    /** Data route for Server/Client sync. */
+    route: Route;
+    /** Full network configuration (broadcast, cloud, static, probing). */
+    network?: Partial<NetworkConfig>;
+    /** Options forwarded to the Server constructor. */
+    serverOptions?: ServerOptions;
+    /** Options forwarded to the Client constructor. */
+    clientOptions?: ClientOptions;
+    /** Logger shared across Node, Server, and Client. */
+    logger?: ServerLogger;
+    /** Directory for persistent node identity. */
+    identityDir?: string;
+}
+/**
+ * Context passed to the `ready` event and to {@link CreateAgent}.
+ */
+export interface ReadyContext {
+    /** The node's current role. */
+    role: NodeRole;
+    /** The Client instance (defined when role is `'client'`). */
+    client?: Client;
+    /** The Server instance (defined when role is `'hub'`). */
+    server?: Server;
+    /** The socket used to connect to the hub (defined when role is `'client'`). */
+    socket?: SocketLike;
+}
+/**
+ * Handle returned by {@link CreateAgent}.
+ * Node calls `stop()` before every role transition and on `node.stop()`.
+ */
+export interface AgentHandle {
+    stop: () => Promise<void> | void;
+}
+/**
+ * Factory called after each role transition to wire application-level agents
+ * (e.g. FsAgent). Return an {@link AgentHandle} whose `stop()` will be called
+ * before the next role transition or when the node stops.
+ */
+export type CreateAgent = (context: ReadyContext) => Promise<AgentHandle>;
+/** Events emitted by Node. */
+export interface NodeEvents {
+    /** Emitted when the node has assumed its role and is ready. */
+    ready: (context: ReadyContext) => void;
+    /** Emitted when the node's role changes. */
+    'role-changed': (event: RoleChangedEvent) => void;
+    /** Emitted when the node is stopped. */
+    stopped: () => void;
+}
+/** Valid event names for Node. */
+export type NodeEventName = keyof NodeEvents;
+/**
+ * Self-organizing node that automatically transitions between
+ * hub (Server) and client (Client) roles based on network topology.
+ */
+export declare class Node {
+    private readonly _config;
+    private readonly _deps;
+    private _networkManager;
+    private _server?;
+    private _client?;
+    private _hubTransport?;
+    private _clientSocket?;
+    private _agentHandle?;
+    private _ioMem?;
+    private _bsMem?;
+    private _role;
+    private _running;
+    private _transitioning?;
+    private _listeners;
+    private readonly _logger;
+    constructor(_config: NodeConfig, _deps: NodeDeps);
+    /**
+     * Start the node. Begins network discovery and role assignment.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the node. Tears down Server/Client and network discovery.
+     */
+    stop(): Promise<void>;
+    /** This node's current role. */
+    get role(): NodeRole;
+    /** Current network topology snapshot. */
+    get topology(): NetworkTopology;
+    /** The Io instance (from Server or Client), or undefined if unassigned. */
+    get io(): Io | undefined;
+    /** The Bs instance (from Server or Client), or undefined if unassigned. */
+    get bs(): Bs | undefined;
+    /** The Server instance when this node is the hub, or undefined. */
+    get server(): Server | undefined;
+    /** The Client instance when this node is a client, or undefined. */
+    get client(): Client | undefined;
+    /** The socket used to connect to the hub (defined when role is `'client'`). */
+    get socket(): SocketLike | undefined;
+    /** Whether the node is currently running. */
+    get isRunning(): boolean;
+    /** The underlying NetworkManager. */
+    get networkManager(): NetworkManager;
+    /**
+     * Subscribe to node events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends NodeEventName>(event: E, cb: NodeEvents[E]): void;
+    /**
+     * Unsubscribe from node events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends NodeEventName>(event: E, cb: NodeEvents[E]): void;
+    private _onRoleChanged;
+    private _performTransition;
+    private _becomeHub;
+    private _becomeClient;
+    private _tearDownCurrentRole;
+    private _startAgent;
+    private _stopAgent;
+    private _emit;
+}