@rljson/server 0.0.4 → 0.0.6

package/dist/README.trouble.md

@@ -11,6 +11,7 @@ found in the LICENSE file in the root of this package.
 ## Table of contents <!-- omit in toc -->
 
 - [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)
 
 ## Vscode Windows: Debugging is not working
 
@@ -21,3 +22,52 @@ in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
 working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
 time to time if the issue has been fixed and remove this note once it is
 resolved.
+
+## Test Isolation: Socket.IO event listener accumulation
+
+Date: 2025-01-28
+
+**Problem:**
+
+When running multiple tests that use Socket.IO connections, tests pass individually but fail when run together. This is caused by event listeners from previous tests remaining active on persistent socket instances.
+
+**Symptoms:**
+
+- Individual tests pass: ✅
+- All tests together fail: ❌
+- Error messages like "received 0 instead of expected number of nodes"
+- Unexpected behavior when sockets receive messages from previous tests
+
+**Root Cause:**
+
+Socket.IO sockets persist across tests in the `beforeAll` setup. When `SocketIoBridge` instances are created in `beforeEach`, old event listeners accumulate on the underlying sockets, causing interference between tests.
+
+**Solution:**
+
+Clear all event listeners in `beforeEach` before creating new bridges:
+
+```typescript
+beforeEach(async () => {
+  // Remove all event listeners from previous test to prevent interference
+  serverSockets.forEach((socket) => socket.removeAllListeners());
+  clientSockets.forEach((socket) => socket.removeAllListeners());
+
+  // Now proceed with test setup...
+  server = new Server(route, serverIo, serverBs);
+  await server.init();
+  // ... rest of setup
+});
+```
+
+**Why This Works:**
+
+- `removeAllListeners()` clears accumulated event handlers
+- Each test starts with clean sockets
+- No interference from previous test's `SocketIoBridge` instances
+- Maintains socket connections established in `beforeAll`
+
+**Alternative Approaches Considered:**
+
+1. ❌ `tearDown()` in `afterEach`: Caused hook timeouts
+2. ❌ Creating new socket connections per test: Too slow, defeats purpose of `beforeAll`
+3. ✅ Clear listeners while reusing connections: Fast and reliable

package/dist/client.d.ts

@@ -1,21 +1,59 @@
 import { Bs } from '@rljson/bs';
-import { Io, IoMulti, Socket } from '@rljson/io';
+import { Connector, Db } from '@rljson/db';
+import { Io, IoMulti } from '@rljson/io';
+import { ClientId, Route, SyncConfig } from '@rljson/rljson';
 import { BaseNode } from './base-node.ts';
+import { ServerLogger } from './logger.ts';
+import { SocketLike } from './socket-bundle.ts';
+/**
+ * Options for the Client constructor.
+ */
+export interface ClientOptions {
+    /** Logger instance for monitoring (defaults to NoopLogger). */
+    logger?: ServerLogger;
+    /**
+     * Sync protocol configuration. When provided, the Connector created
+     * by the client will use enriched payloads (sequence numbers, causal
+     * ordering, ACK support, client identity).
+     */
+    syncConfig?: SyncConfig;
+    /**
+     * Stable client identity. When provided, this identity is passed
+     * to the Connector. When omitted but `syncConfig.includeClientIdentity`
+     * is true, a new identity is auto-generated.
+     */
+    clientIdentity?: ClientId;
+    /**
+     * Timeout in milliseconds for peer initialization during init().
+     * If an Io or Bs peer does not respond within this window, init()
+     * rejects. Defaults to 30 000 (30 s). Set to 0 to disable the timeout.
+     */
+    peerInitTimeoutMs?: number;
+}
 export declare class Client extends BaseNode {
     private _socketToServer;
     protected _localIo: Io;
     protected _localBs: Bs;
+    private _route?;
     private _ioMultiIos;
     private _ioMulti?;
     private _bsMultiBss;
     private _bsMulti?;
+    private _db?;
+    private _connector?;
+    private _logger;
+    private _syncConfig?;
+    private _clientIdentity?;
+    private _peerInitTimeoutMs;
     /**
      * Creates a Client instance
-     * @param _socketToServer - Socket to connect to server
+     * @param _socketToServer - Socket or namespace bundle to connect to server
      * @param _localIo - Local Io for local storage
      * @param _localBs - Local Bs for local blob storage
+     * @param _route - Optional route for automatic Db and Connector creation
+     * @param options - Optional configuration including logger for monitoring
      */
-    constructor(_socketToServer: Socket, _localIo: Io, _localBs: Bs);
+    constructor(_socketToServer: SocketLike, _localIo: Io, _localBs: Bs, _route?: Route | undefined, options?: ClientOptions);
     /**
      * Initializes Io and Bs multis and their peer bridges.
      * @returns The initialized Io implementation.
@@ -37,6 +75,27 @@ export declare class Client extends BaseNode {
      * Returns the Bs implementation.
      */
     get bs(): Bs | undefined;
+    /**
+     * Returns the Db instance (available when route was provided).
+     */
+    get db(): Db | undefined;
+    /**
+     * Returns the Connector instance (available when route was provided).
+     */
+    get connector(): Connector | undefined;
+    /**
+     * Returns the route (if provided).
+     */
+    get route(): Route | undefined;
+    /**
+     * Returns the logger instance.
+     */
+    get logger(): ServerLogger;
+    /**
+     * Creates Db and Connector from the route and IoMulti.
+     * Called during init() when a route was provided.
+     */
+    private _setupDbAndConnector;
     /**
      * Builds the Io multi with local and peer layers.
      */
@@ -47,10 +106,23 @@ export declare class Client extends BaseNode {
     private _setupBs;
     /**
      * Creates and initializes a downstream Io peer.
+     * @param socket - Downstream socket to the server Io namespace.
      */
     private _createIoPeer;
     /**
      * Creates and initializes a downstream Bs peer.
+     * @param socket - Downstream socket to the server Bs namespace.
      */
     private _createBsPeer;
+    /**
+     * Returns the configured peer init timeout in milliseconds.
+     */
+    get peerInitTimeoutMs(): number;
+    /**
+     * Races a promise against a timeout. Resolves/rejects with the original
+     * promise outcome if it settles first, or rejects with a timeout error.
+     * @param promise - The promise to race.
+     * @param label - Human-readable label for timeout error messages.
+     */
+    private _withTimeout;
 }

package/dist/index.d.ts

@@ -1,3 +1,9 @@
 export { Client } from './client.ts';
+export type { ClientOptions } from './client.ts';
+export { BufferedLogger, ConsoleLogger, FilteredLogger, NoopLogger, noopLogger, } from './logger.ts';
+export type { LogEntry, ServerLogger } from './logger.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';

package/dist/logger.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Logger interface for monitoring Client/Server lifecycle, errors,
+ * and network traffic. Implementations can be injected via options.
+ *
+ * Use `NoopLogger` (default) in production for zero overhead.
+ * Use `ConsoleLogger` or `BufferedLogger` for development/testing.
+ */
+export interface ServerLogger {
+    /**
+     * Informational messages (lifecycle events, state changes).
+     * @param source - Component identifier (e.g., 'Server', 'Client.Io')
+     * @param message - Human-readable message
+     * @param data - Optional structured context
+     */
+    info(source: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Warning messages (suppressed duplicates, loop prevention).
+     * @param source - Component identifier
+     * @param message - Human-readable message
+     * @param data - Optional structured context
+     */
+    warn(source: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Error messages (failures during init, multicast, peer creation).
+     * @param source - Component identifier
+     * @param message - Human-readable message
+     * @param error - The caught error or unknown value
+     * @param data - Optional structured context
+     */
+    error(source: string, message: string, error?: unknown, data?: Record<string, unknown>): void;
+    /**
+     * Network traffic messages (socket emit/on events).
+     * @param direction - 'in' for received, 'out' for sent
+     * @param source - Component identifier
+     * @param event - Socket event name
+     * @param data - Optional structured context (ref, clientId, etc.)
+     */
+    traffic(direction: 'in' | 'out', source: string, event: string, data?: Record<string, unknown>): void;
+}
+/**
+ * No-op logger. All methods are empty. Zero overhead in production.
+ * This is the default logger when none is provided.
+ */
+export declare class NoopLogger implements ServerLogger {
+    info(..._args: Parameters<ServerLogger['info']>): void;
+    warn(..._args: Parameters<ServerLogger['warn']>): void;
+    error(..._args: Parameters<ServerLogger['error']>): void;
+    traffic(..._args: Parameters<ServerLogger['traffic']>): void;
+}
+/**
+ * Logs all events to console. Useful for development and debugging.
+ * Data is serialized inline as compact JSON for single-line output.
+ */
+export declare class ConsoleLogger implements ServerLogger {
+    private _fmt;
+    info(source: string, message: string, data?: Record<string, unknown>): void;
+    warn(source: string, message: string, data?: Record<string, unknown>): void;
+    error(source: string, message: string, error?: unknown, data?: Record<string, unknown>): void;
+    traffic(direction: 'in' | 'out', source: string, event: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Log entry stored by BufferedLogger.
+ */
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'traffic';
+    source: string;
+    message: string;
+    error?: unknown;
+    data?: Record<string, unknown>;
+    direction?: 'in' | 'out';
+    event?: string;
+    timestamp: number;
+}
+/**
+ * Stores log entries in memory. Useful for test assertions.
+ */
+export declare class BufferedLogger implements ServerLogger {
+    readonly entries: LogEntry[];
+    info(source: string, message: string, data?: Record<string, unknown>): void;
+    warn(source: string, message: string, data?: Record<string, unknown>): void;
+    error(source: string, message: string, error?: unknown, data?: Record<string, unknown>): void;
+    traffic(direction: 'in' | 'out', source: string, event: string, data?: Record<string, unknown>): void;
+    /**
+     * Returns entries filtered by level.
+     * @param level - The log level to filter by
+     */
+    byLevel(level: LogEntry['level']): LogEntry[];
+    /**
+     * Returns entries filtered by source (substring match).
+     * @param source - The source substring to match
+     */
+    bySource(source: string): LogEntry[];
+    /**
+     * Clears all stored entries.
+     */
+    clear(): void;
+}
+/**
+ * Wraps another logger and filters entries by level and/or source.
+ */
+export declare class FilteredLogger implements ServerLogger {
+    private _inner;
+    private _filter;
+    constructor(_inner: ServerLogger, _filter?: {
+        levels?: Array<'info' | 'warn' | 'error' | 'traffic'>;
+        sources?: string[];
+    });
+    private _shouldLog;
+    info(source: string, message: string, data?: Record<string, unknown>): void;
+    warn(source: string, message: string, data?: Record<string, unknown>): void;
+    error(source: string, message: string, error?: unknown, data?: Record<string, unknown>): void;
+    traffic(direction: 'in' | 'out', source: string, event: string, data?: Record<string, unknown>): void;
+}
+/** Shared no-op instance to avoid repeated allocations. */
+export declare const noopLogger: ServerLogger;

package/dist/server.d.ts

@@ -1,10 +1,47 @@
 import { Bs, BsPeer } from '@rljson/bs';
 import { Io, IoPeer, Socket } from '@rljson/io';
-import { Route } from '@rljson/rljson';
+import { ConnectorPayload, Route, SyncConfig, SyncEventNames } from '@rljson/rljson';
 import { BaseNode } from './base-node.ts';
+import { ServerLogger } from './logger.ts';
+import { SocketLike } from './socket-bundle.ts';
 export type SocketWithClientId = Socket & {
     __clientId?: string;
 };
+/**
+ * Options for the Server constructor.
+ */
+export interface ServerOptions {
+    /** Logger instance for monitoring (defaults to NoopLogger). */
+    logger?: ServerLogger;
+    /**
+     * Interval in milliseconds for evicting stale multicast ref entries.
+     * Uses a two-generation sweep: refs older than two intervals are discarded.
+     * Defaults to 60 000 (60 s). Set to 0 to disable automatic eviction.
+     */
+    refEvictionIntervalMs?: number;
+    /**
+     * Timeout in milliseconds for peer initialization during addSocket().
+     * If a peer does not respond within this window, addSocket() rejects.
+     * Defaults to 30 000 (30 s). Set to 0 to disable the timeout.
+     */
+    peerInitTimeoutMs?: number;
+    /**
+     * Sync protocol configuration. When provided, the server activates
+     * ACK aggregation, gap-fill response, and enriched payload forwarding.
+     */
+    syncConfig?: SyncConfig;
+    /**
+     * Maximum number of recent payloads to retain in the ref log
+     * for gap-fill responses. Defaults to 1000.
+     */
+    refLogSize?: number;
+    /**
+     * Timeout in milliseconds for collecting individual client ACKs
+     * before emitting the aggregated AckPayload back to the sender.
+     * Defaults to the SyncConfig's ackTimeoutMs (or 10 000 ms).
+     */
+    ackTimeoutMs?: number;
+}
 export declare class Server extends BaseNode {
     private _route;
     protected _localIo: Io;
@@ -16,10 +53,23 @@ export declare class Server extends BaseNode {
     private _bss;
     private _bsMulti;
     private _bsServer;
-    private _multicastedRefs;
+    private _multicastedRefsCurrent;
+    private _multicastedRefsPrevious;
+    private _refEvictionTimer?;
     private _refreshPromise?;
     private _pendingSockets;
-    constructor(_route: Route, _localIo: Io, _localBs: Bs);
+    private _logger;
+    private _peerInitTimeoutMs;
+    private _disconnectCleanups;
+    private _syncConfig;
+    private _events;
+    private _refLog;
+    private _refLogSize;
+    private _ackTimeoutMs;
+    private _latestRef;
+    private _bootstrapHeartbeatTimer?;
+    private _tornDown;
+    constructor(_route: Route, _localIo: Io, _localBs: Bs, options?: ServerOptions);
     /**
      * Initializes Io and Bs multis on the server.
      */
@@ -33,17 +83,22 @@ export declare class Server extends BaseNode {
      * @param socket - Client socket to register.
      * @returns The server instance.
      */
-    addSocket(socket: Socket): Promise<this>;
+    addSocket(socket: SocketLike): Promise<this>;
     /**
      * Removes all listeners from all connected clients.
      */
     private _removeAllListeners;
     /**
      * Broadcasts incoming payloads from any client to all other connected clients.
-     * Ensures the sender is filtered out when broadcasting.
+     * Enriched with ref log, ACK aggregation, and gap-fill support when
+     * syncConfig is provided.
      */
     private _multicastRefs;
     get route(): Route;
+    /**
+     * Returns the logger instance.
+     */
+    get logger(): ServerLogger;
     /**
      * Returns the Io implementation.
      */
@@ -56,24 +111,82 @@ export declare class Server extends BaseNode {
      * Returns the connected clients map.
      */
     get clients(): Map<string, {
-        socket: SocketWithClientId;
+        ioUp: SocketWithClientId;
+        ioDown: SocketWithClientId;
+        bsUp: SocketWithClientId;
+        bsDown: SocketWithClientId;
         io: IoPeer;
         bs: BsPeer;
     }>;
+    /**
+     * Returns the sync configuration, if any.
+     */
+    get syncConfig(): SyncConfig | undefined;
+    /**
+     * Returns the typed sync event names.
+     */
+    get events(): SyncEventNames;
+    /**
+     * Returns the current ref log contents (for diagnostics / testing).
+     */
+    get refLog(): readonly ConnectorPayload[];
+    /**
+     * Returns the latest ref tracked by the server (for bootstrap / diagnostics).
+     */
+    get latestRef(): string | undefined;
+    /**
+     * Appends a payload to the bounded ref log (ring buffer).
+     * Drops the oldest entry when the log exceeds `_refLogSize`.
+     * @param payload - The ConnectorPayload to append.
+     */
+    private _appendToRefLog;
+    /**
+     * Sends the latest ref to a specific client socket as a bootstrap message.
+     * If no ref has been seen yet, this is a no-op.
+     * @param ioDown - The downstream socket to send the bootstrap message on.
+     */
+    private _sendBootstrap;
+    /**
+     * Broadcasts the latest ref to all connected clients as a heartbeat.
+     * Each client's dedup pipeline will filter out refs it already has.
+     */
+    private _broadcastBootstrapHeartbeat;
+    /**
+     * Starts the periodic bootstrap heartbeat timer if configured
+     * and not already running.
+     */
+    private _startBootstrapHeartbeat;
+    /**
+     * Sets up ACK collection listeners before broadcast.
+     * Returns a cleanup function that emits an immediate ACK
+     * (used when there are no receivers).
+     * @param senderClientId - The internal client ID of the sender.
+     * @param ref - The ref being acknowledged.
+     * @returns A function to call for immediate ACK (zero receivers).
+     */
+    private _setupAckCollection;
+    /**
+     * Registers a gap-fill request listener for a specific client socket.
+     * @param clientId - The internal client ID.
+     * @param socket - The upstream socket to listen on.
+     */
+    private _registerGapFillListener;
     /**
      * Creates and initializes a downstream Io peer for a socket.
      * @param socket - Client socket to bind the peer to.
+     * @param clientId - Client identifier for logging.
      */
     private _createIoPeer;
     /**
      * Creates and initializes a downstream Bs peer for a socket.
      * @param socket - Client socket to bind the peer to.
+     * @param clientId - Client identifier for logging.
      */
     private _createBsPeer;
     /**
      * Registers the client socket and peers.
      * @param clientId - Stable client identifier.
-     * @param socket - Client socket to register.
+     * @param sockets - Directional sockets to register.
      * @param io - Io peer associated with the client.
      * @param bs - Bs peer associated with the client.
      */
@@ -100,6 +213,34 @@ export declare class Server extends BaseNode {
      * Batches multi/server refreshes into a single queued task.
      */
     private _queueRefresh;
+    /**
+     * Removes a connected client by its internal client ID.
+     * Cleans up listeners, peers, and rebuilds multis.
+     * @param clientId - The client identifier (from server.clients keys).
+     */
+    removeSocket(clientId: string): Promise<void>;
+    /**
+     * Gracefully shuts down the server: stops timers, removes listeners,
+     * clears all client state, and closes storage layers.
+     */
+    tearDown(): Promise<void>;
+    /**
+     * Whether the server has been torn down.
+     */
+    get isTornDown(): boolean;
+    /**
+     * Registers a listener that auto-removes the client on socket disconnect.
+     * @param clientId - Client identifier.
+     * @param socket - The upstream socket to listen on.
+     */
+    private _registerDisconnectHandler;
+    /**
+     * Races a promise against a timeout. Resolves/rejects with the original
+     * promise outcome if it settles first, or rejects with a timeout error.
+     * @param promise - The promise to race.
+     * @param label - Human-readable label for timeout error messages.
+     */
+    private _withTimeout;
     /** Example instance for test purposes */
     static example(): Promise<Server>;
 }