@rljson/server 0.0.5 → 0.0.6

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,11 +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;
@@ -17,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.
      */
@@ -41,10 +90,15 @@ export declare class Server extends BaseNode {
     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.
      */
@@ -64,14 +118,69 @@ export declare class Server extends BaseNode {
         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;
     /**
@@ -104,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>;
 }