@rljson/server 0.0.4 → 0.0.6

package/dist/server.js

@@ -1,8 +1,9 @@
 import { hshBuffer } from "@rljson/hash";
 import { Readable } from "node:stream";
+import { Db, Connector } from "@rljson/db";
 import { IoPeerBridge, IoMulti, IoPeer, IoServer, IoMem, SocketMock } from "@rljson/io";
-import { Db } from "@rljson/db";
-import { Route } from "@rljson/rljson";
+import { syncEvents, Route } from "@rljson/rljson";
+import { syncEvents as syncEvents2 } from "@rljson/rljson";
 class BsMem {
   blobs = /* @__PURE__ */ new Map();
   /**
@@ -743,21 +744,23 @@ class BsPeerBridge {
     this._socket = _socket;
   }
   _eventHandlers = /* @__PURE__ */ new Map();
+  _handleConnectBound = this._handleConnect.bind(this);
+  _handleDisconnectBound = this._handleDisconnect.bind(this);
   /**
    * Starts the bridge by setting up connection event handlers and
    * automatically registering all Bs methods.
    */
   start() {
-    this._socket.on("connect", () => this._handleConnect());
-    this._socket.on("disconnect", () => this._handleDisconnect());
+    this._socket.on("connect", this._handleConnectBound);
+    this._socket.on("disconnect", this._handleDisconnectBound);
     this._registerBsMethods();
   }
   /**
    * Stops the bridge by removing all event handlers.
    */
   stop() {
-    this._socket.off("connect", () => this._handleConnect());
-    this._socket.off("disconnect", () => this._handleDisconnect());
+    this._socket.off("connect", this._handleConnectBound);
+    this._socket.off("disconnect", this._handleDisconnectBound);
     for (const [eventName, handler] of this._eventHandlers) {
       this._socket.off(eventName, handler);
     }
@@ -768,14 +771,11 @@ class BsPeerBridge {
    */
   _registerBsMethods() {
     const bsMethods = [
-      "setBlob",
       "getBlob",
       "getBlobStream",
-      "deleteBlob",
       "blobExists",
       "getBlobProperties",
-      "listBlobs",
-      "generateSignedUrl"
+      "listBlobs"
     ];
     for (const methodName of bsMethods) {
       this.registerEvent(methodName);
@@ -797,17 +797,17 @@ class BsPeerBridge {
           `Method "${methodName}" not found on Bs instance`
         );
         if (typeof callback === "function") {
-          callback(null, error);
+          callback(error, null);
         }
         return;
       }
       bsMethod.apply(this._bs, methodArgs).then((result) => {
         if (typeof callback === "function") {
-          callback(result, null);
+          callback(null, result);
         }
       }).catch((error) => {
         if (typeof callback === "function") {
-          callback(null, error);
+          callback(error, null);
         }
       });
     };
@@ -855,9 +855,9 @@ class BsPeerBridge {
         throw new Error(`Method "${bsMethodName}" not found on Bs instance`);
       }
       const result = await bsMethod.apply(this._bs, args);
-      this._socket.emit(socketEventName, result, null);
+      this._socket.emit(socketEventName, null, result);
     } catch (error) {
-      this._socket.emit(socketEventName, null, error);
+      this._socket.emit(socketEventName, error, null);
     }
   }
   /* v8 ignore next -- @preserve */
@@ -978,33 +978,208 @@ class BaseNode {
     await this._localDb.core.import(data);
   }
 }
+class NoopLogger {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  info(..._args) {
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  warn(..._args) {
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  error(..._args) {
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  traffic(..._args) {
+  }
+}
+class ConsoleLogger {
+  _fmt(data) {
+    return data ? " " + JSON.stringify(data) : "";
+  }
+  info(source, message, data) {
+    console.log(`[INFO] [${source}] ${message}${this._fmt(data)}`);
+  }
+  warn(source, message, data) {
+    console.warn(`[WARN] [${source}] ${message}${this._fmt(data)}`);
+  }
+  error(source, message, error, data) {
+    const errStr = error ? ` ${error}` : "";
+    console.error(`[ERROR] [${source}] ${message}${errStr}${this._fmt(data)}`);
+  }
+  traffic(direction, source, event, data) {
+    const arrow = direction === "in" ? "⬅" : "➡";
+    console.log(`[TRAFFIC] ${arrow} [${source}] ${event}${this._fmt(data)}`);
+  }
+}
+class BufferedLogger {
+  entries = [];
+  info(source, message, data) {
+    this.entries.push({
+      level: "info",
+      source,
+      message,
+      data,
+      timestamp: Date.now()
+    });
+  }
+  warn(source, message, data) {
+    this.entries.push({
+      level: "warn",
+      source,
+      message,
+      data,
+      timestamp: Date.now()
+    });
+  }
+  error(source, message, error, data) {
+    this.entries.push({
+      level: "error",
+      source,
+      message,
+      error,
+      data,
+      timestamp: Date.now()
+    });
+  }
+  traffic(direction, source, event, data) {
+    this.entries.push({
+      level: "traffic",
+      source,
+      message: event,
+      direction,
+      event,
+      data,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Returns entries filtered by level.
+   * @param level - The log level to filter by
+   */
+  byLevel(level) {
+    return this.entries.filter((e) => e.level === level);
+  }
+  /**
+   * Returns entries filtered by source (substring match).
+   * @param source - The source substring to match
+   */
+  bySource(source) {
+    return this.entries.filter((e) => e.source.includes(source));
+  }
+  /**
+   * Clears all stored entries.
+   */
+  clear() {
+    this.entries.length = 0;
+  }
+}
+class FilteredLogger {
+  constructor(_inner, _filter = {}) {
+    this._inner = _inner;
+    this._filter = _filter;
+  }
+  _shouldLog(level, source) {
+    if (this._filter.levels && !this._filter.levels.includes(level)) {
+      return false;
+    }
+    if (this._filter.sources && !this._filter.sources.some((s) => source.includes(s))) {
+      return false;
+    }
+    return true;
+  }
+  info(source, message, data) {
+    if (this._shouldLog("info", source)) {
+      this._inner.info(source, message, data);
+    }
+  }
+  warn(source, message, data) {
+    if (this._shouldLog("warn", source)) {
+      this._inner.warn(source, message, data);
+    }
+  }
+  error(source, message, error, data) {
+    if (this._shouldLog("error", source)) {
+      this._inner.error(source, message, error, data);
+    }
+  }
+  traffic(direction, source, event, data) {
+    if (this._shouldLog("traffic", source)) {
+      this._inner.traffic(direction, source, event, data);
+    }
+  }
+}
+const noopLogger = new NoopLogger();
+function normalizeSocketBundle(socket) {
+  const bundle = socket;
+  if (bundle.ioUp && bundle.ioDown && bundle.bsUp && bundle.bsDown) {
+    return bundle;
+  }
+  const single = socket;
+  return {
+    ioUp: single,
+    ioDown: single,
+    bsUp: single,
+    bsDown: single
+  };
+}
 class Client extends BaseNode {
   // ...........................................................................
   /**
    * 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, _localIo, _localBs) {
+  constructor(_socketToServer, _localIo, _localBs, _route, options) {
     super(_localIo);
     this._socketToServer = _socketToServer;
     this._localIo = _localIo;
     this._localBs = _localBs;
+    this._route = _route;
+    this._logger = options?.logger ?? noopLogger;
+    this._syncConfig = options?.syncConfig;
+    this._clientIdentity = options?.clientIdentity;
+    this._peerInitTimeoutMs = options?.peerInitTimeoutMs ?? 3e4;
+    this._logger.info("Client", "Constructing client", {
+      hasRoute: !!this._route,
+      route: this._route?.flat
+    });
   }
   _ioMultiIos = [];
   _ioMulti;
   _bsMultiBss = [];
   _bsMulti;
+  _db;
+  _connector;
+  _logger;
+  _syncConfig;
+  _clientIdentity;
+  _peerInitTimeoutMs;
   /**
    * Initializes Io and Bs multis and their peer bridges.
    * @returns The initialized Io implementation.
    */
   async init() {
-    await this._setupIo();
-    await this._setupBs();
-    await this.ready();
-    return this._ioMulti;
+    this._logger.info("Client", "Initializing client");
+    try {
+      await this._setupIo();
+      await this._setupBs();
+      if (this._route) {
+        this._setupDbAndConnector();
+      }
+      await this.ready();
+      this._logger.info("Client", "Client initialized successfully", {
+        hasRoute: !!this._route,
+        hasDb: !!this._db,
+        hasConnector: !!this._connector
+      });
+      return this._ioMulti;
+    } catch (error) {
+      this._logger.error("Client", "Failed to initialize client", error);
+      throw error;
+    }
   }
   /**
    * Resolves once the Io implementation is ready.
@@ -1018,14 +1193,18 @@ class Client extends BaseNode {
    * Closes client resources and clears internal state.
    */
   async tearDown() {
+    this._logger.info("Client", "Tearing down client");
     if (this._ioMulti && this._ioMulti.isOpen) {
       this._ioMulti.close();
     }
-    if (this._bsMulti) ;
-    this._ioMultiIos = [];
+    this._connector?.tearDown();
     this._bsMultiBss = [];
+    this._ioMultiIos = [];
     this._ioMulti = void 0;
     this._bsMulti = void 0;
+    this._db = void 0;
+    this._connector = void 0;
+    this._logger.info("Client", "Client torn down successfully");
   }
   /**
    * Returns the Io implementation.
@@ -1039,77 +1218,210 @@ class Client extends BaseNode {
   get bs() {
     return this._bsMulti;
   }
+  /**
+   * Returns the Db instance (available when route was provided).
+   */
+  get db() {
+    return this._db;
+  }
+  /**
+   * Returns the Connector instance (available when route was provided).
+   */
+  get connector() {
+    return this._connector;
+  }
+  /**
+   * Returns the route (if provided).
+   */
+  get route() {
+    return this._route;
+  }
+  /**
+   * Returns the logger instance.
+   */
+  get logger() {
+    return this._logger;
+  }
+  /**
+   * Creates Db and Connector from the route and IoMulti.
+   * Called during init() when a route was provided.
+   */
+  _setupDbAndConnector() {
+    this._logger.info("Client", "Setting up Db and Connector", {
+      route: this._route.flat
+    });
+    this._db = new Db(this._ioMulti);
+    const socket = normalizeSocketBundle(this._socketToServer);
+    this._connector = new Connector(
+      this._db,
+      this._route,
+      socket.ioUp,
+      this._syncConfig,
+      this._clientIdentity
+    );
+    this._logger.info("Client", "Db and Connector created");
+  }
   /**
    * Builds the Io multi with local and peer layers.
    */
   async _setupIo() {
-    this._ioMultiIos.push({
-      io: this._localIo,
-      dump: true,
-      read: true,
-      write: true,
-      priority: 1
-    });
-    const ioPeerBridge = new IoPeerBridge(this._localIo, this._socketToServer);
-    ioPeerBridge.start();
-    const ioPeer = await this._createIoPeer();
-    this._ioMultiIos.push({
-      io: ioPeer,
-      dump: false,
-      read: true,
-      write: false,
-      priority: 2
-    });
-    this._ioMulti = new IoMulti(this._ioMultiIos);
-    await this._ioMulti.init();
-    await this._ioMulti.isReady();
+    this._logger.info("Client.Io", "Setting up Io multi");
+    try {
+      const sockets = normalizeSocketBundle(this._socketToServer);
+      this._ioMultiIos.push({
+        io: this._localIo,
+        dump: true,
+        read: true,
+        write: true,
+        priority: 1
+      });
+      const ioPeerBridge = new IoPeerBridge(this._localIo, sockets.ioUp);
+      ioPeerBridge.start();
+      this._logger.info("Client.Io", "Io peer bridge started (upstream)");
+      const ioPeer = await this._createIoPeer(sockets.ioDown);
+      this._ioMultiIos.push({
+        io: ioPeer,
+        dump: false,
+        read: true,
+        write: false,
+        priority: 2
+      });
+      this._ioMulti = new IoMulti(this._ioMultiIos);
+      await this._ioMulti.init();
+      await this._ioMulti.isReady();
+      this._logger.info("Client.Io", "Io multi ready");
+    } catch (error) {
+      this._logger.error("Client.Io", "Failed to set up Io", error);
+      throw error;
+    }
   }
   /**
    * Builds the Bs multi with local and peer layers.
    */
   async _setupBs() {
-    this._bsMultiBss.push({
-      bs: this._localBs,
-      read: true,
-      write: true,
-      priority: 1
-    });
-    const bsPeerBridge = new BsPeerBridge(this._localBs, this._socketToServer);
-    bsPeerBridge.start();
-    const bsPeer = await this._createBsPeer();
-    this._bsMultiBss.push({
-      bs: bsPeer,
-      read: true,
-      write: false,
-      priority: 2
-    });
-    this._bsMulti = new BsMulti(this._bsMultiBss);
-    await this._bsMulti.init();
+    this._logger.info("Client.Bs", "Setting up Bs multi");
+    try {
+      const sockets = normalizeSocketBundle(this._socketToServer);
+      this._bsMultiBss.push({
+        bs: this._localBs,
+        read: true,
+        write: true,
+        priority: 1
+      });
+      const bsPeerBridge = new BsPeerBridge(this._localBs, sockets.bsUp);
+      bsPeerBridge.start();
+      this._logger.info("Client.Bs", "Bs peer bridge started (upstream)");
+      const bsPeer = await this._createBsPeer(sockets.bsDown);
+      this._bsMultiBss.push({
+        bs: bsPeer,
+        read: true,
+        write: false,
+        priority: 2
+      });
+      this._bsMulti = new BsMulti(this._bsMultiBss);
+      await this._bsMulti.init();
+      this._logger.info("Client.Bs", "Bs multi ready");
+    } catch (error) {
+      this._logger.error("Client.Bs", "Failed to set up Bs", error);
+      throw error;
+    }
   }
   /**
    * Creates and initializes a downstream Io peer.
+   * @param socket - Downstream socket to the server Io namespace.
    */
-  async _createIoPeer() {
-    const ioPeer = new IoPeer(this._socketToServer);
-    await ioPeer.init();
-    await ioPeer.isReady();
-    return ioPeer;
+  async _createIoPeer(socket) {
+    this._logger.info("Client.Io", "Creating Io peer (downstream)");
+    try {
+      const ioPeer = new IoPeer(socket);
+      await this._withTimeout(
+        ioPeer.init().then(() => ioPeer.isReady()),
+        "IoPeer init"
+      );
+      this._logger.info("Client.Io", "Io peer created (downstream)");
+      return ioPeer;
+    } catch (error) {
+      this._logger.error(
+        "Client.Io",
+        "Failed to create Io peer (downstream)",
+        error
+      );
+      throw error;
+    }
   }
   /**
    * Creates and initializes a downstream Bs peer.
+   * @param socket - Downstream socket to the server Bs namespace.
    */
-  async _createBsPeer() {
-    const bsPeer = new BsPeer(this._socketToServer);
-    await bsPeer.init();
-    return bsPeer;
+  async _createBsPeer(socket) {
+    this._logger.info("Client.Bs", "Creating Bs peer (downstream)");
+    try {
+      const bsPeer = new BsPeer(socket);
+      await this._withTimeout(bsPeer.init(), "BsPeer init");
+      this._logger.info("Client.Bs", "Bs peer created (downstream)");
+      return bsPeer;
+    } catch (error) {
+      this._logger.error(
+        "Client.Bs",
+        "Failed to create Bs peer (downstream)",
+        error
+      );
+      throw error;
+    }
+  }
+  /**
+   * Returns the configured peer init timeout in milliseconds.
+   */
+  get peerInitTimeoutMs() {
+    return this._peerInitTimeoutMs;
+  }
+  // ...........................................................................
+  /**
+   * 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.
+   */
+  _withTimeout(promise, label) {
+    const ms = this._peerInitTimeoutMs;
+    if (ms <= 0) return promise;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        /* v8 ignore next -- @preserve */
+        () => reject(new Error(`Timeout after ${ms}ms: ${label}`)),
+        ms
+      );
+    });
+    return Promise.race([promise, timeout]).finally(
+      /* v8 ignore next -- @preserve */
+      () => clearTimeout(timer)
+    );
   }
 }
 class Server extends BaseNode {
-  constructor(_route, _localIo, _localBs) {
+  constructor(_route, _localIo, _localBs, options) {
     super(_localIo);
     this._route = _route;
     this._localIo = _localIo;
     this._localBs = _localBs;
+    this._logger = options?.logger ?? noopLogger;
+    this._peerInitTimeoutMs = options?.peerInitTimeoutMs ?? 3e4;
+    this._syncConfig = options?.syncConfig;
+    this._refLogSize = options?.refLogSize ?? 1e3;
+    this._ackTimeoutMs = options?.ackTimeoutMs ?? options?.syncConfig?.ackTimeoutMs ?? 1e4;
+    this._events = syncEvents(this._route.flat);
+    this._logger.info("Server", "Constructing server", {
+      route: this._route.flat
+    });
+    const evictionMs = options?.refEvictionIntervalMs ?? 6e4;
+    if (evictionMs > 0) {
+      this._refEvictionTimer = setInterval(() => {
+        this._multicastedRefsPrevious = this._multicastedRefsCurrent;
+        this._multicastedRefsCurrent = /* @__PURE__ */ new Set();
+      }, evictionMs);
+      this._refEvictionTimer.unref();
+    }
     const ioMultiIoLocal = {
       io: this._localIo,
       dump: true,
@@ -1142,18 +1454,42 @@ class Server extends BaseNode {
   _bsMulti;
   // Storage => Let Clients read from Servers Bs
   _bsServer;
-  // To avoid rebroadcasting the same edit refs multiple times
-  _multicastedRefs = /* @__PURE__ */ new Set();
+  // Two-generation ref dedup: refs in current or previous are considered seen.
+  // On each eviction tick, previous is discarded and current becomes previous.
+  _multicastedRefsCurrent = /* @__PURE__ */ new Set();
+  _multicastedRefsPrevious = /* @__PURE__ */ new Set();
+  _refEvictionTimer;
   _refreshPromise;
   _pendingSockets = [];
+  _logger;
+  _peerInitTimeoutMs;
+  // Cleanup callbacks for socket disconnect listeners (clientId → cleanup fn)
+  _disconnectCleanups = /* @__PURE__ */ new Map();
+  // Sync protocol state
+  _syncConfig;
+  _events;
+  _refLog = [];
+  _refLogSize;
+  _ackTimeoutMs;
+  // Bootstrap state
+  _latestRef;
+  _bootstrapHeartbeatTimer;
+  _tornDown = false;
   /**
    * Initializes Io and Bs multis on the server.
    */
   async init() {
-    await this._ioMulti.init();
-    await this._ioMulti.isReady();
-    await this._bsMulti.init();
-    await this.ready();
+    this._logger.info("Server", "Initializing server");
+    try {
+      await this._ioMulti.init();
+      await this._ioMulti.isReady();
+      await this._bsMulti.init();
+      await this.ready();
+      this._logger.info("Server", "Server initialized successfully");
+    } catch (error) {
+      this._logger.error("Server", "Failed to initialize server", error);
+      throw error;
+    }
   }
   /**
    * Resolves once the Io implementation is ready.
@@ -1167,17 +1503,45 @@ class Server extends BaseNode {
    * @returns The server instance.
    */
   async addSocket(socket) {
+    const sockets = normalizeSocketBundle(socket);
     const clientId = `client_${this._clients.size}_${Math.random().toString(36).slice(2)}`;
-    socket.__clientId = clientId;
-    const ioPeer = await this._createIoPeer(socket);
-    const bsPeer = await this._createBsPeer(socket);
-    this._registerClient(clientId, socket, ioPeer, bsPeer);
-    this._pendingSockets.push(socket);
-    this._queueIoPeer(ioPeer);
-    this._queueBsPeer(bsPeer);
-    await this._queueRefresh();
-    this._removeAllListeners();
-    this._multicastRefs();
+    this._logger.info("Server", "Adding client socket", { clientId });
+    const ioUp = sockets.ioUp;
+    const ioDown = sockets.ioDown;
+    const bsUp = sockets.bsUp;
+    const bsDown = sockets.bsDown;
+    ioUp.__clientId = clientId;
+    ioDown.__clientId = clientId;
+    bsUp.__clientId = clientId;
+    bsDown.__clientId = clientId;
+    try {
+      const ioPeer = await this._createIoPeer(socket, clientId);
+      const bsPeer = await this._createBsPeer(socket, clientId);
+      this._registerClient(
+        clientId,
+        { ioUp, ioDown, bsUp, bsDown },
+        ioPeer,
+        bsPeer
+      );
+      this._pendingSockets.push({ ioDown, bsDown });
+      this._queueIoPeer(ioPeer);
+      this._queueBsPeer(bsPeer);
+      await this._queueRefresh();
+      this._removeAllListeners();
+      this._multicastRefs();
+      this._registerDisconnectHandler(clientId, ioUp);
+      this._sendBootstrap(ioDown);
+      this._startBootstrapHeartbeat();
+      this._logger.info("Server", "Client socket added successfully", {
+        clientId,
+        totalClients: this._clients.size
+      });
+    } catch (error) {
+      this._logger.error("Server", "Failed to add client socket", error, {
+        clientId
+      });
+      throw error;
+    }
     return this;
   }
   // ...........................................................................
@@ -1185,44 +1549,87 @@ class Server extends BaseNode {
    * Removes all listeners from all connected clients.
    */
   _removeAllListeners() {
-    for (const { socket } of this._clients.values()) {
-      socket.removeAllListeners(this._route.flat);
+    for (const { ioUp } of this._clients.values()) {
+      ioUp.removeAllListeners(this._route.flat);
+      ioUp.removeAllListeners(this._events.gapFillReq);
+      ioUp.removeAllListeners(this._events.ackClient);
     }
   }
   // ...........................................................................
   /**
    * 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.
    */
   _multicastRefs = () => {
-    for (const [clientIdA, { socket: socketA }] of this._clients.entries()) {
+    for (const [clientIdA, { ioUp: socketA }] of this._clients.entries()) {
       socketA.on(this._route.flat, (payload) => {
         const ref = payload.r;
-        if (this._multicastedRefs.has(ref)) {
+        this._logger.traffic("in", "Server.Multicast", this._route.flat, {
+          ref,
+          from: clientIdA
+        });
+        if (this._multicastedRefsCurrent.has(ref) || this._multicastedRefsPrevious.has(ref)) {
+          this._logger.warn("Server.Multicast", "Duplicate ref suppressed", {
+            ref,
+            from: clientIdA
+          });
           return;
         }
-        this._multicastedRefs.add(ref);
+        this._multicastedRefsCurrent.add(ref);
+        this._latestRef = ref;
         const p = payload;
         if (p && p.__origin) {
+          this._logger.warn(
+            "Server.Multicast",
+            "Loop prevention: payload already has origin",
+            { ref, origin: p.__origin, from: clientIdA }
+          );
           return;
         }
+        if (this._syncConfig) {
+          this._appendToRefLog(payload);
+        }
+        let receiverCount = 0;
+        let ackCollector;
+        if (this._syncConfig?.requireAck) {
+          ackCollector = this._setupAckCollection(clientIdA, ref);
+        }
         for (const [
           clientIdB,
-          { socket: socketB }
+          { ioDown: socketB }
         ] of this._clients.entries()) {
           if (clientIdA !== clientIdB) {
             const forwarded = Object.assign({}, payload, {
               __origin: clientIdA
             });
+            this._logger.traffic("out", "Server.Multicast", this._route.flat, {
+              ref,
+              from: clientIdA,
+              to: clientIdB
+            });
             socketB.emit(this._route.flat, forwarded);
+            receiverCount++;
           }
         }
+        if (ackCollector && receiverCount === 0) {
+          ackCollector();
+        }
       });
+      if (this._syncConfig?.causalOrdering) {
+        this._registerGapFillListener(clientIdA, socketA);
+      }
     }
   };
   get route() {
     return this._route;
   }
+  /**
+   * Returns the logger instance.
+   */
+  get logger() {
+    return this._logger;
+  }
   /**
    * Returns the Io implementation.
    */
@@ -1241,35 +1648,229 @@ class Server extends BaseNode {
   get clients() {
     return this._clients;
   }
+  /**
+   * Returns the sync configuration, if any.
+   */
+  get syncConfig() {
+    return this._syncConfig;
+  }
+  /**
+   * Returns the typed sync event names.
+   */
+  get events() {
+    return this._events;
+  }
+  /**
+   * Returns the current ref log contents (for diagnostics / testing).
+   */
+  get refLog() {
+    return this._refLog;
+  }
+  /**
+   * Returns the latest ref tracked by the server (for bootstrap / diagnostics).
+   */
+  get latestRef() {
+    return this._latestRef;
+  }
+  // ...........................................................................
+  // Sync protocol private methods
+  // ...........................................................................
+  /**
+   * 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.
+   */
+  _appendToRefLog(payload) {
+    this._refLog.push(payload);
+    if (this._refLog.length > this._refLogSize) {
+      this._refLog.shift();
+    }
+  }
+  // ...........................................................................
+  // Bootstrap methods
+  // ...........................................................................
+  /**
+   * 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.
+   */
+  _sendBootstrap(ioDown) {
+    if (!this._latestRef) return;
+    const payload = {
+      o: "__server__",
+      r: this._latestRef
+    };
+    this._logger.info("Server.Bootstrap", "Sending bootstrap ref", {
+      ref: this._latestRef,
+      to: ioDown.__clientId
+    });
+    ioDown.emit(this._events.bootstrap, payload);
+  }
+  /**
+   * Broadcasts the latest ref to all connected clients as a heartbeat.
+   * Each client's dedup pipeline will filter out refs it already has.
+   */
+  _broadcastBootstrapHeartbeat() {
+    if (!this._latestRef) return;
+    const payload = {
+      o: "__server__",
+      r: this._latestRef
+    };
+    this._logger.info("Server.Bootstrap", "Heartbeat broadcast", {
+      ref: this._latestRef,
+      clientCount: this._clients.size
+    });
+    for (const { ioDown } of this._clients.values()) {
+      ioDown.emit(this._events.bootstrap, payload);
+    }
+  }
+  /**
+   * Starts the periodic bootstrap heartbeat timer if configured
+   * and not already running.
+   */
+  _startBootstrapHeartbeat() {
+    const ms = this._syncConfig?.bootstrapHeartbeatMs;
+    if (!ms || ms <= 0 || this._bootstrapHeartbeatTimer) return;
+    this._bootstrapHeartbeatTimer = setInterval(() => {
+      this._broadcastBootstrapHeartbeat();
+    }, ms);
+    this._bootstrapHeartbeatTimer.unref();
+    this._logger.info("Server.Bootstrap", "Heartbeat timer started", {
+      intervalMs: ms
+    });
+  }
+  /**
+   * 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).
+   */
+  _setupAckCollection(senderClientId, ref) {
+    const senderEntry = this._clients.get(senderClientId);
+    if (!senderEntry) return () => {
+    };
+    const totalClients = this._clients.size - 1;
+    let acksReceived = 0;
+    let finished = false;
+    const ackHandlers = /* @__PURE__ */ new Map();
+    const finish = (ok) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timeout);
+      for (const [cId, handler] of ackHandlers.entries()) {
+        const clientEntry = this._clients.get(cId);
+        if (clientEntry) {
+          clientEntry.ioUp.off(this._events.ackClient, handler);
+        }
+      }
+      ackHandlers.clear();
+      const ack = {
+        r: ref,
+        ok,
+        receivedBy: acksReceived,
+        totalClients
+      };
+      senderEntry.ioDown.emit(this._events.ack, ack);
+    };
+    const timeout = setTimeout(() => {
+      finish(false);
+    }, this._ackTimeoutMs);
+    for (const [clientId, { ioUp }] of this._clients.entries()) {
+      if (clientId === senderClientId) continue;
+      const handler = (clientAck) => {
+        if (clientAck.r !== ref) return;
+        acksReceived++;
+        if (acksReceived >= totalClients) {
+          finish(true);
+        }
+      };
+      ioUp.on(this._events.ackClient, handler);
+      ackHandlers.set(clientId, handler);
+    }
+    return () => {
+      finish(true);
+    };
+  }
+  /**
+   * 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.
+   */
+  _registerGapFillListener(clientId, socket) {
+    socket.on(this._events.gapFillReq, (req) => {
+      this._logger.info("Server.GapFill", "Gap-fill request received", {
+        from: clientId,
+        afterSeq: req.afterSeq
+      });
+      const refs = this._refLog.filter(
+        (p) => p.seq != null && p.seq > req.afterSeq
+      );
+      const res = {
+        route: req.route,
+        refs
+      };
+      const clientEntry = this._clients.get(clientId);
+      if (clientEntry) {
+        clientEntry.ioDown.emit(this._events.gapFillRes, res);
+      }
+    });
+  }
   /**
    * 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.
    */
-  async _createIoPeer(socket) {
-    const ioPeer = new IoPeer(socket);
-    await ioPeer.init();
-    await ioPeer.isReady();
-    return ioPeer;
+  async _createIoPeer(socket, clientId) {
+    const sockets = normalizeSocketBundle(socket);
+    this._logger.info("Server.Io", "Creating Io peer", { clientId });
+    try {
+      const ioPeer = new IoPeer(sockets.ioUp);
+      await this._withTimeout(ioPeer.init(), "IoPeer.init()");
+      await this._withTimeout(ioPeer.isReady(), "IoPeer.isReady()");
+      this._logger.info("Server.Io", "Io peer created", { clientId });
+      return ioPeer;
+    } catch (error) {
+      this._logger.error("Server.Io", "Failed to create Io peer", error, {
+        clientId
+      });
+      throw error;
+    }
   }
   /**
    * 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.
    */
-  async _createBsPeer(socket) {
-    const bsPeer = new BsPeer(socket);
-    await bsPeer.init();
-    return bsPeer;
+  async _createBsPeer(socket, clientId) {
+    const sockets = normalizeSocketBundle(socket);
+    this._logger.info("Server.Bs", "Creating Bs peer", { clientId });
+    try {
+      const bsPeer = new BsPeer(sockets.bsUp);
+      await this._withTimeout(bsPeer.init(), "BsPeer.init()");
+      this._logger.info("Server.Bs", "Bs peer created", { clientId });
+      return bsPeer;
+    } catch (error) {
+      this._logger.error("Server.Bs", "Failed to create Bs peer", error, {
+        clientId
+      });
+      throw error;
+    }
   }
   /**
    * 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.
    */
-  _registerClient(clientId, socket, io, bs) {
+  _registerClient(clientId, sockets, io, bs) {
     this._clients.set(clientId, {
-      socket,
+      ioUp: sockets.ioUp,
+      ioDown: sockets.ioDown,
+      bsUp: sockets.bsUp,
+      bsDown: sockets.bsDown,
       io,
       bs
     });
@@ -1303,38 +1904,171 @@ class Server extends BaseNode {
    * Rebuilds Io and Bs multis from queued peers.
    */
   async _rebuildMultis() {
-    this._ioMulti = new IoMulti(this._ios);
-    await this._ioMulti.init();
-    await this._ioMulti.isReady();
-    this._bsMulti = new BsMulti(this._bss);
-    await this._bsMulti.init();
+    this._logger.info("Server", "Rebuilding multis", {
+      ioCount: this._ios.length,
+      bsCount: this._bss.length
+    });
+    try {
+      this._ioMulti = new IoMulti(this._ios);
+      await this._ioMulti.init();
+      await this._ioMulti.isReady();
+      this._bsMulti = new BsMulti(this._bss);
+      await this._bsMulti.init();
+      this._logger.info("Server", "Multis rebuilt successfully");
+    } catch (error) {
+      this._logger.error("Server", "Failed to rebuild multis", error);
+      throw error;
+    }
   }
   /**
    * Recreates servers and reattaches sockets.
    */
   async _refreshServers() {
-    this._ioServer._io = this._ioMulti;
-    this._bsServer._bs = this._bsMulti;
-    for (const socket of this._pendingSockets) {
-      await this._ioServer.addSocket(socket);
-      await this._bsServer.addSocket(socket);
+    this._logger.info("Server", "Refreshing servers", {
+      pendingSockets: this._pendingSockets.length
+    });
+    try {
+      this._ioServer._io = this._ioMulti;
+      this._bsServer._bs = this._bsMulti;
+      for (const pending of this._pendingSockets) {
+        await this._ioServer.addSocket(pending.ioDown);
+        await this._bsServer.addSocket(pending.bsDown);
+      }
+      this._pendingSockets = [];
+      this._logger.info("Server", "Servers refreshed successfully");
+    } catch (error) {
+      this._logger.error("Server", "Failed to refresh servers", error);
+      throw error;
     }
-    this._pendingSockets = [];
   }
   /**
    * Batches multi/server refreshes into a single queued task.
    */
   _queueRefresh() {
     if (!this._refreshPromise) {
+      this._logger.info("Server", "Queuing refresh");
       this._refreshPromise = Promise.resolve().then(async () => {
         await this._rebuildMultis();
         await this._refreshServers();
-      }).finally(() => {
+      }).catch(
+        /* v8 ignore next -- @preserve */
+        (error) => {
+          this._logger.error("Server", "Queued refresh failed", error);
+          throw error;
+        }
+      ).finally(() => {
         this._refreshPromise = void 0;
       });
     }
     return this._refreshPromise;
   }
+  // ...........................................................................
+  /**
+   * 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).
+   */
+  async removeSocket(clientId) {
+    const client = this._clients.get(clientId);
+    if (!client) return;
+    this._logger.info("Server", "Removing client socket", { clientId });
+    client.ioUp.removeAllListeners(this._route.flat);
+    const cleanup = this._disconnectCleanups.get(clientId);
+    if (cleanup) {
+      cleanup();
+      this._disconnectCleanups.delete(clientId);
+    }
+    this._ios = this._ios.filter((entry) => entry.io !== client.io);
+    this._bss = this._bss.filter((entry) => entry.bs !== client.bs);
+    this._clients.delete(clientId);
+    await this._rebuildMultis();
+    await this._refreshServers();
+    this._removeAllListeners();
+    this._multicastRefs();
+    this._logger.info("Server", "Client socket removed", {
+      clientId,
+      remainingClients: this._clients.size
+    });
+  }
+  // ...........................................................................
+  /**
+   * Gracefully shuts down the server: stops timers, removes listeners,
+   * clears all client state, and closes storage layers.
+   */
+  async tearDown() {
+    this._logger.info("Server", "Tearing down server");
+    if (this._refEvictionTimer) {
+      clearInterval(this._refEvictionTimer);
+      this._refEvictionTimer = void 0;
+    }
+    if (this._bootstrapHeartbeatTimer) {
+      clearInterval(this._bootstrapHeartbeatTimer);
+      this._bootstrapHeartbeatTimer = void 0;
+    }
+    this._removeAllListeners();
+    for (const cleanup of this._disconnectCleanups.values()) {
+      cleanup();
+    }
+    this._disconnectCleanups.clear();
+    this._clients.clear();
+    this._pendingSockets = [];
+    if (this._ioMulti && this._ioMulti.isOpen) {
+      this._ioMulti.close();
+    }
+    this._ios = [];
+    this._bss = [];
+    this._multicastedRefsCurrent.clear();
+    this._multicastedRefsPrevious.clear();
+    this._refLog = [];
+    this._latestRef = void 0;
+    this._tornDown = true;
+    this._logger.info("Server", "Server torn down successfully");
+  }
+  /**
+   * Whether the server has been torn down.
+   */
+  get isTornDown() {
+    return this._tornDown;
+  }
+  // ...........................................................................
+  /**
+   * Registers a listener that auto-removes the client on socket disconnect.
+   * @param clientId - Client identifier.
+   * @param socket - The upstream socket to listen on.
+   */
+  _registerDisconnectHandler(clientId, socket) {
+    const handler = () => {
+      this._logger.info("Server", "Client disconnected", { clientId });
+      this.removeSocket(clientId);
+    };
+    socket.on("disconnect", handler);
+    this._disconnectCleanups.set(clientId, () => {
+      socket.off("disconnect", handler);
+    });
+  }
+  // ...........................................................................
+  /**
+   * 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.
+   */
+  _withTimeout(promise, label) {
+    const ms = this._peerInitTimeoutMs;
+    if (ms <= 0) return promise;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        /* v8 ignore next -- @preserve */
+        () => reject(new Error(`Timeout after ${ms}ms: ${label}`)),
+        ms
+      );
+    });
+    return Promise.race([promise, timeout]).finally(
+      /* v8 ignore next -- @preserve */
+      () => clearTimeout(timer)
+    );
+  }
   /** Example instance for test purposes */
   static async example() {
     const route = Route.fromFlat("example.route");
@@ -1401,7 +2135,13 @@ class SocketIoBridge {
   }
 }
 export {
+  BufferedLogger,
   Client,
+  ConsoleLogger,
+  FilteredLogger,
+  NoopLogger,
   Server,
-  SocketIoBridge
+  SocketIoBridge,
+  noopLogger,
+  syncEvents2 as syncEvents
 };