@rljson/server 0.0.10 → 0.0.12

package/dist/server.js

@@ -1,949 +1,11 @@
-import { hshBuffer } from "@rljson/hash";
-import { Readable } from "node:stream";
+import { BsPeerBridge, BsMulti, BsPeer, BsServer, BsMem } from "@rljson/bs";
 import { Db, Connector } from "@rljson/db";
 import { IoPeerBridge, IoMulti, IoPeer, IoServer, IoMem, SocketMock } from "@rljson/io";
 import { existsSync, mkdirSync, appendFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { NetworkManager } from "@rljson/network";
 import { syncEvents, Route } from "@rljson/rljson";
 import { syncEvents as syncEvents2 } from "@rljson/rljson";
-class BsMem {
-  blobs = /* @__PURE__ */ new Map();
-  /**
-   * Convert content to Buffer
-   * @param content - Content to convert (Buffer, string, or ReadableStream)
-   */
-  async toBuffer(content) {
-    if (Buffer.isBuffer(content)) {
-      return content;
-    }
-    if (typeof content === "string") {
-      return Buffer.from(content, "utf8");
-    }
-    const reader = content.getReader();
-    const chunks = [];
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      chunks.push(value);
-    }
-    return Buffer.concat(chunks);
-  }
-  async setBlob(content) {
-    const buffer = await this.toBuffer(content);
-    const blobId = hshBuffer(buffer);
-    const existing = this.blobs.get(blobId);
-    if (existing) {
-      return existing.properties;
-    }
-    const properties = {
-      blobId,
-      size: buffer.length,
-      createdAt: /* @__PURE__ */ new Date()
-    };
-    this.blobs.set(blobId, {
-      content: buffer,
-      properties
-    });
-    return properties;
-  }
-  async getBlob(blobId, options) {
-    const stored = this.blobs.get(blobId);
-    if (!stored) {
-      throw new Error(`Blob not found: ${blobId}`);
-    }
-    let content = stored.content;
-    if (options?.range) {
-      const { start, end } = options.range;
-      content = stored.content.subarray(start, end);
-    }
-    return {
-      content,
-      properties: stored.properties
-    };
-  }
-  async getBlobStream(blobId) {
-    const stored = this.blobs.get(blobId);
-    if (!stored) {
-      throw new Error(`Blob not found: ${blobId}`);
-    }
-    const nodeStream = Readable.from(stored.content);
-    return Readable.toWeb(nodeStream);
-  }
-  async deleteBlob(blobId) {
-    const deleted = this.blobs.delete(blobId);
-    if (!deleted) {
-      throw new Error(`Blob not found: ${blobId}`);
-    }
-  }
-  async blobExists(blobId) {
-    return this.blobs.has(blobId);
-  }
-  async getBlobProperties(blobId) {
-    const stored = this.blobs.get(blobId);
-    if (!stored) {
-      throw new Error(`Blob not found: ${blobId}`);
-    }
-    return stored.properties;
-  }
-  async listBlobs(options) {
-    let blobs = Array.from(this.blobs.values()).map(
-      (stored) => stored.properties
-    );
-    if (options?.prefix) {
-      blobs = blobs.filter((blob) => blob.blobId.startsWith(options.prefix));
-    }
-    blobs.sort((a, b) => a.blobId.localeCompare(b.blobId));
-    const maxResults = options?.maxResults ?? blobs.length;
-    let startIndex = 0;
-    if (options?.continuationToken) {
-      const tokenIndex = blobs.findIndex(
-        (blob) => blob.blobId === options.continuationToken
-      );
-      startIndex = tokenIndex === -1 ? 0 : tokenIndex + 1;
-    }
-    const endIndex = Math.min(startIndex + maxResults, blobs.length);
-    const pageBlobs = blobs.slice(startIndex, endIndex);
-    const continuationToken = endIndex < blobs.length ? pageBlobs[pageBlobs.length - 1]?.blobId : void 0;
-    return {
-      blobs: pageBlobs,
-      continuationToken
-    };
-  }
-  async generateSignedUrl(blobId, expiresIn, permissions) {
-    if (!this.blobs.has(blobId)) {
-      throw new Error(`Blob not found: ${blobId}`);
-    }
-    const expires = Date.now() + expiresIn * 1e3;
-    const perm = permissions ?? "read";
-    return `mem://${blobId}?expires=${expires}&permissions=${perm}`;
-  }
-  /**
-   * Clear all blobs from storage (useful for testing)
-   */
-  clear() {
-    this.blobs.clear();
-  }
-  /**
-   * Get the number of blobs in storage
-   */
-  get size() {
-    return this.blobs.size;
-  }
-}
-class BsPeer {
-  constructor(_socket) {
-    this._socket = _socket;
-  }
-  isOpen = false;
-  // ...........................................................................
-  /**
-   * Initializes the Peer connection.
-   */
-  async init() {
-    this._socket.on("connect", () => {
-      this.isOpen = true;
-    });
-    this._socket.on("disconnect", () => {
-      this.isOpen = false;
-    });
-    this._socket.connect();
-    return new Promise((resolve) => {
-      if (this._socket.connected) {
-        this.isOpen = true;
-        resolve();
-      } else {
-        this._socket.on("connect", () => {
-          resolve();
-        });
-      }
-    });
-  }
-  // ...........................................................................
-  /**
-   * Closes the Peer connection.
-   */
-  async close() {
-    if (!this._socket.connected) return;
-    return new Promise((resolve) => {
-      this._socket.on("disconnect", () => {
-        resolve();
-      });
-      this._socket.disconnect();
-    });
-  }
-  // ...........................................................................
-  /**
-   * Returns a promise that resolves once the Peer connection is ready.
-   */
-  async isReady() {
-    if (!!this._socket && this._socket.connected === true) this.isOpen = true;
-    else this.isOpen = false;
-    return !!this.isOpen ? Promise.resolve() : Promise.reject();
-  }
-  // ...........................................................................
-  /**
-   * Stores a blob from Buffer, string, or ReadableStream and returns properties.
-   * @param content - The blob content to store
-   * @returns Promise resolving to blob properties
-   */
-  setBlob(content) {
-    return new Promise((resolve, reject) => {
-      if (content instanceof ReadableStream) {
-        const reader = content.getReader();
-        const chunks = [];
-        const readStream = async () => {
-          try {
-            while (true) {
-              const { done, value } = await reader.read();
-              if (done) break;
-              chunks.push(value);
-            }
-            const totalLength = chunks.reduce(
-              (sum, chunk) => sum + chunk.length,
-              0
-            );
-            const buffer = Buffer.concat(
-              chunks.map((chunk) => Buffer.from(chunk)),
-              totalLength
-            );
-            this._socket.emit(
-              "setBlob",
-              buffer,
-              (error, result) => {
-                if (error) reject(error);
-                else resolve(result);
-              }
-            );
-          } catch (err) {
-            reject(err);
-          }
-        };
-        readStream();
-      } else {
-        this._socket.emit(
-          "setBlob",
-          content,
-          (error, result) => {
-            if (error) reject(error);
-            else resolve(result);
-          }
-        );
-      }
-    });
-  }
-  // ...........................................................................
-  /**
-   * Retrieves a blob by its ID as a Buffer.
-   * @param blobId - The unique identifier of the blob
-   * @param options - Download options
-   * @returns Promise resolving to blob content and properties
-   */
-  getBlob(blobId, options) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "getBlob",
-        blobId,
-        options,
-        (error, result) => {
-          if (error) reject(error);
-          else resolve(result);
-        }
-      );
-    });
-  }
-  // ...........................................................................
-  /**
-   * Retrieves a blob by its ID as a ReadableStream.
-   * @param blobId - The unique identifier of the blob
-   * @returns Promise resolving to readable stream
-   */
-  getBlobStream(blobId) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "getBlobStream",
-        blobId,
-        (error, result) => {
-          if (error) reject(error);
-          else resolve(result);
-        }
-      );
-    });
-  }
-  // ...........................................................................
-  /**
-   * Deletes a blob by its ID.
-   * @param blobId - The unique identifier of the blob
-   * @returns Promise that resolves when deletion is complete
-   */
-  deleteBlob(blobId) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit("deleteBlob", blobId, (error) => {
-        if (error) reject(error);
-        else resolve();
-      });
-    });
-  }
-  // ...........................................................................
-  /**
-   * Checks if a blob exists.
-   * @param blobId - The unique identifier of the blob
-   * @returns Promise resolving to true if blob exists
-   */
-  blobExists(blobId) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "blobExists",
-        blobId,
-        (error, exists) => {
-          if (error) reject(error);
-          else resolve(exists);
-        }
-      );
-    });
-  }
-  // ...........................................................................
-  /**
-   * Gets blob properties (size, createdAt) without retrieving content.
-   * @param blobId - The unique identifier of the blob
-   * @returns Promise resolving to blob properties
-   */
-  getBlobProperties(blobId) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "getBlobProperties",
-        blobId,
-        (error, result) => {
-          if (error) reject(error);
-          else resolve(result);
-        }
-      );
-    });
-  }
-  // ...........................................................................
-  /**
-   * Lists all blobs with optional filtering and pagination.
-   * @param options - Optional listing configuration
-   * @returns Promise resolving to list of blobs
-   */
-  listBlobs(options) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "listBlobs",
-        options || {},
-        (error, result) => {
-          if (error) reject(error);
-          else resolve(result);
-        }
-      );
-    });
-  }
-  // ...........................................................................
-  /**
-   * Generates a signed URL for temporary blob access.
-   * @param blobId - The unique identifier of the blob
-   * @param expiresIn - Expiration time in seconds
-   * @param permissions - Permissions for the URL
-   * @returns Promise resolving to signed URL
-   */
-  generateSignedUrl(blobId, expiresIn, permissions) {
-    return new Promise((resolve, reject) => {
-      this._socket.emit(
-        "generateSignedUrl",
-        blobId,
-        expiresIn,
-        permissions,
-        (error, url) => {
-          if (error) reject(error);
-          else resolve(url);
-        }
-      );
-    });
-  }
-}
-class PeerSocketMock {
-  constructor(_bs) {
-    this._bs = _bs;
-  }
-  _listenersMap = /* @__PURE__ */ new Map();
-  connected = false;
-  disconnected = true;
-  // ............................................................................
-  /**
-   * Removes a specific listener for the specified event.
-   * @param eventName - The event name
-   * @param listener - The listener function to remove
-   * @returns This socket instance for chaining
-   */
-  off(eventName, listener) {
-    const listeners = this._listenersMap.get(eventName) || [];
-    const index = listeners.indexOf(listener);
-    if (index !== -1) {
-      listeners.splice(index, 1);
-      this._listenersMap.set(eventName, listeners);
-    }
-    return this;
-  }
-  // ............................................................................
-  /**
-   * Removes all listeners for the specified event, or all listeners if no event is specified.
-   * @param eventName - Optional event name
-   * @returns This socket instance for chaining
-   */
-  removeAllListeners(eventName) {
-    if (eventName) {
-      this._listenersMap.delete(eventName);
-    } else {
-      this._listenersMap.clear();
-    }
-    return this;
-  }
-  // ............................................................................
-  /**
-   * Registers an event listener for the specified event.
-   * @param eventName - The event name
-   * @param listener - The listener function to register
-   * @returns This socket instance for chaining
-   */
-  on(eventName, listener) {
-    if (!this._listenersMap.has(eventName)) {
-      this._listenersMap.set(eventName, []);
-    }
-    this._listenersMap.get(eventName).push(listener);
-    return this;
-  }
-  // ...........................................................................
-  /**
-   * Simulates a connection event.
-   */
-  connect() {
-    this.connected = true;
-    this.disconnected = false;
-    const listeners = this._listenersMap.get("connect") || [];
-    for (const cb of listeners) {
-      cb({});
-    }
-    return this;
-  }
-  // ...........................................................................
-  /**
-   * Simulates a disconnection event.
-   */
-  disconnect() {
-    this.connected = false;
-    this.disconnected = true;
-    const listeners = this._listenersMap.get("disconnect") || [];
-    for (const cb of listeners) {
-      cb({});
-    }
-    return this;
-  }
-  // ............................................................................
-  /**
-   * Emits an event, invoking the corresponding method on the Bs instance.
-   * @param eventName - The event name
-   * @param args - Event arguments
-   * @returns True if the event was handled
-   */
-  emit(eventName, ...args) {
-    const fn = this._bs[eventName];
-    if (typeof fn !== "function") {
-      throw new Error(`Event ${eventName.toString()} not supported`);
-    }
-    const cb = args[args.length - 1];
-    fn.apply(this._bs, args.slice(0, -1)).then((result) => {
-      cb(null, result);
-    }).catch((err) => {
-      cb(err);
-    });
-    return true;
-  }
-}
-class BsMulti {
-  constructor(_stores) {
-    this._stores = _stores;
-  }
-  // ...........................................................................
-  /**
-   * Initializes the BsMulti by assigning IDs to all underlying Bs instances.
-   * All underlying Bs instances must already be initialized.
-   */
-  async init() {
-    for (let idx = 0; idx < this._stores.length; idx++) {
-      this._stores[idx] = { ...this._stores[idx], id: `bs-${idx}` };
-    }
-    return Promise.resolve();
-  }
-  // ...........................................................................
-  /**
-   * Stores a blob in all writable Bs instances in parallel.
-   * @param content - The blob content to store
-   * @returns Promise resolving to blob properties from the first successful write
-   */
-  async setBlob(content) {
-    if (this.writables.length === 0) {
-      throw new Error("No writable Bs available");
-    }
-    const writes = this.writables.map(({ bs }) => bs.setBlob(content));
-    const results = await Promise.all(writes);
-    return results[0];
-  }
-  // ...........................................................................
-  /**
-   * Retrieves a blob from the highest priority readable Bs instance.
-   * Hot-swaps the blob to all writable instances for caching.
-   * @param blobId - The blob identifier
-   * @param options - Download options
-   * @returns Promise resolving to blob content and properties
-   */
-  async getBlob(blobId, options) {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    let result;
-    let readFrom = "";
-    const errors = [];
-    for (const readable of this.readables) {
-      try {
-        result = await readable.bs.getBlob(blobId, options);
-        readFrom = readable.id ?? "";
-        break;
-      } catch (e) {
-        errors.push(e);
-        continue;
-      }
-    }
-    if (!result) {
-      const notFoundErrors = errors.filter(
-        (err) => err.message.includes("Blob not found")
-      );
-      if (notFoundErrors.length === errors.length) {
-        throw new Error(`Blob not found: ${blobId}`);
-      } else {
-        throw errors[0];
-      }
-    }
-    if (this.writables.length > 0) {
-      const hotSwapWrites = this.writables.filter((writable) => writable.id !== readFrom).map(({ bs }) => bs.setBlob(result.content).catch(() => {
-      }));
-      await Promise.all(hotSwapWrites);
-    }
-    return result;
-  }
-  // ...........................................................................
-  /**
-   * Retrieves a blob as a ReadableStream from the highest priority readable Bs instance.
-   * @param blobId - The blob identifier
-   * @returns Promise resolving to a ReadableStream
-   */
-  async getBlobStream(blobId) {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    const errors = [];
-    for (const readable of this.readables) {
-      try {
-        return await readable.bs.getBlobStream(blobId);
-      } catch (e) {
-        errors.push(e);
-        continue;
-      }
-    }
-    const notFoundErrors = errors.filter(
-      (err) => err.message.includes("Blob not found")
-    );
-    if (notFoundErrors.length === errors.length) {
-      throw new Error(`Blob not found: ${blobId}`);
-    } else {
-      throw errors[0];
-    }
-  }
-  // ...........................................................................
-  /**
-   * Deletes a blob from all writable Bs instances in parallel.
-   * @param blobId - The blob identifier
-   */
-  async deleteBlob(blobId) {
-    if (this.writables.length === 0) {
-      throw new Error("No writable Bs available");
-    }
-    const deletes = this.writables.map(({ bs }) => bs.deleteBlob(blobId));
-    await Promise.all(deletes);
-  }
-  // ...........................................................................
-  /**
-   * Checks if a blob exists in any readable Bs instance.
-   * @param blobId - The blob identifier
-   * @returns Promise resolving to true if blob exists in any readable
-   */
-  async blobExists(blobId) {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    for (const readable of this.readables) {
-      try {
-        const exists = await readable.bs.blobExists(blobId);
-        if (exists) {
-          return true;
-        }
-      } catch {
-        continue;
-      }
-    }
-    return false;
-  }
-  // ...........................................................................
-  /**
-   * Gets blob properties from the highest priority readable Bs instance.
-   * @param blobId - The blob identifier
-   * @returns Promise resolving to blob properties
-   */
-  async getBlobProperties(blobId) {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    const errors = [];
-    for (const readable of this.readables) {
-      try {
-        return await readable.bs.getBlobProperties(blobId);
-      } catch (e) {
-        errors.push(e);
-        continue;
-      }
-    }
-    const notFoundErrors = errors.filter(
-      (err) => err.message.includes("Blob not found")
-    );
-    if (notFoundErrors.length === errors.length) {
-      throw new Error(`Blob not found: ${blobId}`);
-    } else {
-      throw errors[0];
-    }
-  }
-  // ...........................................................................
-  /**
-   * Lists blobs by merging results from all readable Bs instances.
-   * Deduplicates by blobId (content-addressable).
-   * @param options - Listing options
-   * @returns Promise resolving to list of blobs
-   */
-  async listBlobs(options) {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    const blobMap = /* @__PURE__ */ new Map();
-    for (const readable of this.readables) {
-      try {
-        let continuationToken2;
-        do {
-          const result = await readable.bs.listBlobs({
-            prefix: options?.prefix,
-            // Apply prefix filter during collection
-            continuationToken: continuationToken2,
-            maxResults: 1e3
-            // Fetch in chunks from each store
-          });
-          for (const blob of result.blobs) {
-            if (!blobMap.has(blob.blobId)) {
-              blobMap.set(blob.blobId, blob);
-            }
-          }
-          continuationToken2 = result.continuationToken;
-        } while (continuationToken2);
-      } catch {
-        continue;
-      }
-    }
-    const blobs = Array.from(blobMap.values());
-    blobs.sort((a, b) => a.blobId.localeCompare(b.blobId));
-    const maxResults = options?.maxResults ?? blobs.length;
-    let startIndex = 0;
-    if (options?.continuationToken) {
-      const tokenIndex = blobs.findIndex(
-        (blob) => blob.blobId === options.continuationToken
-      );
-      startIndex = tokenIndex === -1 ? 0 : tokenIndex + 1;
-    }
-    const endIndex = Math.min(startIndex + maxResults, blobs.length);
-    const pageBlobs = blobs.slice(startIndex, endIndex);
-    const continuationToken = endIndex < blobs.length ? pageBlobs[pageBlobs.length - 1]?.blobId : void 0;
-    return {
-      blobs: pageBlobs,
-      continuationToken
-    };
-  }
-  // ...........................................................................
-  /**
-   * Generates a signed URL from the highest priority readable Bs instance.
-   * @param blobId - The blob identifier
-   * @param expiresIn - Expiration time in seconds
-   * @param permissions - Access permissions
-   * @returns Promise resolving to signed URL
-   */
-  async generateSignedUrl(blobId, expiresIn, permissions = "read") {
-    if (this.readables.length === 0) {
-      throw new Error("No readable Bs available");
-    }
-    const errors = [];
-    for (const readable of this.readables) {
-      try {
-        return await readable.bs.generateSignedUrl(
-          blobId,
-          expiresIn,
-          permissions
-        );
-      } catch (e) {
-        errors.push(e);
-        continue;
-      }
-    }
-    const notFoundErrors = errors.filter(
-      (err) => err.message.includes("Blob not found")
-    );
-    if (notFoundErrors.length === errors.length) {
-      throw new Error(`Blob not found: ${blobId}`);
-    } else {
-      throw errors[0];
-    }
-  }
-  // ...........................................................................
-  /**
-   * Gets the list of underlying readable Bs instances, sorted by priority.
-   */
-  get readables() {
-    return this._stores.filter((store) => store.read).sort((a, b) => a.priority - b.priority);
-  }
-  // ...........................................................................
-  /**
-   * Gets the list of underlying writable Bs instances, sorted by priority.
-   */
-  get writables() {
-    return this._stores.filter((store) => store.write).sort((a, b) => a.priority - b.priority);
-  }
-  // ...........................................................................
-  /**
-   * Example: Local cache (BsMem) + Remote server (BsPeer)
-   */
-  static example = async () => {
-    const bsRemoteMem = new BsMem();
-    const bsRemoteSocket = new PeerSocketMock(bsRemoteMem);
-    const bsRemote = new BsPeer(bsRemoteSocket);
-    await bsRemote.init();
-    const bsLocal = new BsMem();
-    const stores = [
-      { bs: bsLocal, priority: 0, read: true, write: true },
-      // Cache first
-      { bs: bsRemote, priority: 1, read: true, write: false }
-      // Remote fallback
-    ];
-    const bsMulti = new BsMulti(stores);
-    await bsMulti.init();
-    return bsMulti;
-  };
-}
-class BsPeerBridge {
-  constructor(_bs, _socket) {
-    this._bs = _bs;
-    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._handleConnectBound);
-    this._socket.on("disconnect", this._handleDisconnectBound);
-    this._registerBsMethods();
-  }
-  /**
-   * Stops the bridge by removing all event handlers.
-   */
-  stop() {
-    this._socket.off("connect", this._handleConnectBound);
-    this._socket.off("disconnect", this._handleDisconnectBound);
-    for (const [eventName, handler] of this._eventHandlers) {
-      this._socket.off(eventName, handler);
-    }
-    this._eventHandlers.clear();
-  }
-  /**
-   * Automatically registers all Bs interface methods as socket event handlers.
-   */
-  _registerBsMethods() {
-    const bsMethods = [
-      "getBlob",
-      "getBlobStream",
-      "blobExists",
-      "getBlobProperties",
-      "listBlobs"
-    ];
-    for (const methodName of bsMethods) {
-      this.registerEvent(methodName);
-    }
-  }
-  /**
-   * Registers a socket event to be translated to a Bs method call.
-   * @param eventName - The socket event name (should match a Bs method name)
-   * @param bsMethodName - (Optional) The Bs method name if different from eventName
-   */
-  registerEvent(eventName, bsMethodName) {
-    const methodName = bsMethodName || eventName;
-    const handler = (...args) => {
-      const callback = args[args.length - 1];
-      const methodArgs = args.slice(0, -1);
-      const bsMethod = this._bs[methodName];
-      if (typeof bsMethod !== "function") {
-        const error = new Error(
-          `Method "${methodName}" not found on Bs instance`
-        );
-        if (typeof callback === "function") {
-          callback(error, null);
-        }
-        return;
-      }
-      bsMethod.apply(this._bs, methodArgs).then((result) => {
-        if (typeof callback === "function") {
-          callback(null, result);
-        }
-      }).catch((error) => {
-        if (typeof callback === "function") {
-          callback(error, null);
-        }
-      });
-    };
-    this._eventHandlers.set(eventName, handler);
-    this._socket.on(eventName, handler);
-  }
-  /**
-   * Registers multiple socket events at once.
-   * @param eventNames - Array of event names to register
-   */
-  registerEvents(eventNames) {
-    for (const eventName of eventNames) {
-      this.registerEvent(eventName);
-    }
-  }
-  /**
-   * Unregisters a socket event handler.
-   * @param eventName - The event name to unregister
-   */
-  unregisterEvent(eventName) {
-    const handler = this._eventHandlers.get(eventName);
-    if (handler) {
-      this._socket.off(eventName, handler);
-      this._eventHandlers.delete(eventName);
-    }
-  }
-  /**
-   * Emits a result back through the socket.
-   * @param eventName - The event name to emit
-   * @param data - The data to send
-   */
-  emitToSocket(eventName, ...data) {
-    this._socket.emit(eventName, ...data);
-  }
-  /**
-   * Calls a Bs method directly and emits the result through the socket.
-   * @param bsMethodName - The Bs method to call
-   * @param socketEventName - The socket event to emit with the result
-   * @param args - Arguments to pass to the Bs method
-   */
-  async callBsAndEmit(bsMethodName, socketEventName, ...args) {
-    try {
-      const bsMethod = this._bs[bsMethodName];
-      if (typeof bsMethod !== "function") {
-        throw new Error(`Method "${bsMethodName}" not found on Bs instance`);
-      }
-      const result = await bsMethod.apply(this._bs, args);
-      this._socket.emit(socketEventName, null, result);
-    } catch (error) {
-      this._socket.emit(socketEventName, error, null);
-    }
-  }
-  /* v8 ignore next -- @preserve */
-  _handleConnect() {
-  }
-  /* v8 ignore next -- @preserve */
-  _handleDisconnect() {
-  }
-  /**
-   * Gets the current socket instance.
-   */
-  get socket() {
-    return this._socket;
-  }
-  /**
-   * Gets the current Bs instance.
-   */
-  get bs() {
-    return this._bs;
-  }
-  /**
-   * Returns whether the socket is currently connected.
-   */
-  get isConnected() {
-    return this._socket.connected;
-  }
-}
-class BsServer {
-  constructor(_bs) {
-    this._bs = _bs;
-  }
-  _sockets = [];
-  // ...........................................................................
-  /**
-   * Adds a socket to the BsServer instance.
-   * @param socket - The socket to add.
-   */
-  async addSocket(socket) {
-    await this._addTransportLayer(socket);
-    this._sockets.push(socket);
-  }
-  // ...........................................................................
-  /**
-   * Removes a socket from the BsServer instance.
-   * @param socket - The socket to remove.
-   */
-  removeSocket(socket) {
-    this._sockets = this._sockets.filter((s) => s !== socket);
-  }
-  // ...........................................................................
-  /**
-   * Adds a transport layer to the given socket.
-   * @param socket - The socket to add the transport layer to.
-   */
-  async _addTransportLayer(socket) {
-    const methods = this._generateTransportLayer(this._bs);
-    for (const [key, fn] of Object.entries(methods)) {
-      socket.on(key, (...args) => {
-        const cb = args[args.length - 1];
-        fn.apply(this, args.slice(0, -1)).then((result) => {
-          cb(null, result);
-        }).catch((err) => {
-          cb(err);
-        });
-      });
-    }
-  }
-  // ...........................................................................
-  /**
-   * Generates a transport layer object for the given Bs instance.
-   * @param bs - The Bs instance to generate the transport layer for.
-   * @returns An object containing methods that correspond to the Bs interface.
-   */
-  _generateTransportLayer = (bs) => ({
-    setBlob: (content) => bs.setBlob(content),
-    getBlob: (blobId, options) => bs.getBlob(blobId, options),
-    getBlobStream: (blobId) => bs.getBlobStream(blobId),
-    deleteBlob: (blobId) => bs.deleteBlob(blobId),
-    blobExists: (blobId) => bs.blobExists(blobId),
-    getBlobProperties: (blobId) => bs.getBlobProperties(blobId),
-    listBlobs: (options) => bs.listBlobs(options),
-    generateSignedUrl: (blobId, expiresIn, permissions) => bs.generateSignedUrl(blobId, expiresIn, permissions)
-  });
-}
 class BaseNode {
   constructor(_localIo) {
     this._localIo = _localIo;
@@ -1737,6 +799,50 @@ class Server extends BaseNode {
     return this;
   }
   // ...........................................................................
+  /**
+   * Adds a socket to the multicast ring WITHOUT creating IoPeer/BsPeer.
+   * Use this when the hub needs to participate in the multicast (send and
+   * receive refs) but the server should NOT try to read data from this socket
+   * via IoPeer/BsPeer RPC — because no IoPeerBridge/BsPeerBridge is set up
+   * on the other end.
+   * Typical use case: hub creates a loopback socket pair so its own
+   * Connector can send/receive refs, but the server's IoMulti already has
+   * the hub's data in its local cache (IoMem/BsMem at priority 1).
+   * @param socket - Socket to register for broadcast only.
+   * @returns The server instance.
+   */
+  async addBroadcastSocket(socket) {
+    const sockets = normalizeSocketBundle(socket);
+    const clientId = `broadcast_${this._clients.size}_${Math.random().toString(36).slice(2)}`;
+    this._logger.info("Server", "Adding broadcast-only 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;
+    this._clients.set(clientId, {
+      ioUp,
+      ioDown,
+      bsUp,
+      bsDown,
+      io: null,
+      bs: null
+    });
+    this._removeAllListeners();
+    this._multicastRefs();
+    this._registerDisconnectHandler(clientId, ioUp);
+    this._sendBootstrap(ioDown);
+    this._startBootstrapHeartbeat();
+    this._logger.info("Server", "Broadcast-only socket added", {
+      clientId,
+      totalClients: this._clients.size
+    });
+    return this;
+  }
+  // ...........................................................................
   /**
    * Removes all listeners from all connected clients.
    */
@@ -2285,6 +1391,280 @@ class Server extends BaseNode {
     return new Server(route, io, bs).addSocket(socket);
   }
 }
+class Node {
+  constructor(_config, _deps) {
+    this._config = _config;
+    this._deps = _deps;
+    this._logger = _config.logger ?? noopLogger;
+    const networkConfig = {
+      domain: _config.domain,
+      port: _config.port,
+      identityDir: _config.identityDir,
+      broadcast: _config.network?.broadcast ?? {
+        enabled: true,
+        port: 41234
+      },
+      cloud: _config.network?.cloud ?? { enabled: false, endpoint: "" },
+      static: _config.network?.static ?? {},
+      probing: _config.network?.probing ?? { enabled: true }
+    };
+    this._networkManager = new NetworkManager(
+      networkConfig,
+      _deps.networkManagerOptions
+    );
+  }
+  _networkManager;
+  _server;
+  _client;
+  _hubTransport;
+  _clientSocket;
+  _agentHandle;
+  _ioMem;
+  _bsMem;
+  _role = "unassigned";
+  _running = false;
+  _transitioning;
+  _listeners = /* @__PURE__ */ new Map();
+  _logger;
+  // .........................................................................
+  // Lifecycle
+  // .........................................................................
+  /**
+   * Start the node. Begins network discovery and role assignment.
+   */
+  async start() {
+    if (this._running) return;
+    this._ioMem = new IoMem();
+    await this._ioMem.init();
+    await this._ioMem.isReady();
+    this._bsMem = new BsMem();
+    this._running = true;
+    this._networkManager.on("role-changed", this._onRoleChanged);
+    await this._networkManager.start();
+  }
+  /**
+   * Stop the node. Tears down Server/Client and network discovery.
+   */
+  async stop() {
+    if (!this._running) return;
+    this._running = false;
+    this._networkManager.off("role-changed", this._onRoleChanged);
+    if (this._transitioning) {
+      await this._transitioning;
+      this._transitioning = void 0;
+    }
+    await this._tearDownCurrentRole();
+    await this._networkManager.stop();
+    this._role = "unassigned";
+    this._emit("stopped");
+  }
+  // .........................................................................
+  // State
+  // .........................................................................
+  /** This node's current role. */
+  get role() {
+    return this._role;
+  }
+  /** Current network topology snapshot. */
+  get topology() {
+    return this._networkManager.getTopology();
+  }
+  /** The Io instance (from Server or Client), or undefined if unassigned. */
+  get io() {
+    return this._server?.io ?? this._client?.io;
+  }
+  /** The Bs instance (from Server or Client), or undefined if unassigned. */
+  get bs() {
+    return this._server?.bs ?? this._client?.bs;
+  }
+  /** The Server instance when this node is the hub, or undefined. */
+  get server() {
+    return this._server;
+  }
+  /** The Client instance when this node is a client, or undefined. */
+  get client() {
+    return this._client;
+  }
+  /** The socket used to connect to the hub (defined when role is `'client'`). */
+  get socket() {
+    return this._clientSocket;
+  }
+  /** Whether the node is currently running. */
+  get isRunning() {
+    return this._running;
+  }
+  /** The underlying NetworkManager. */
+  get networkManager() {
+    return this._networkManager;
+  }
+  // .........................................................................
+  // Events
+  // .........................................................................
+  /**
+   * Subscribe to node events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from node events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    set.delete(cb);
+  }
+  // .........................................................................
+  // Role transitions
+  // .........................................................................
+  _onRoleChanged = (event) => {
+    if (!this._running) return;
+    const { current } = event;
+    if (current === this._role) return;
+    const prev = this._transitioning ?? Promise.resolve();
+    this._transitioning = prev.then(() => this._performTransition(event));
+  };
+  async _performTransition(event) {
+    if (!this._running) return;
+    const { current } = event;
+    if (current === this._role) return;
+    this._logger.info("Node", `Role changing: ${this._role} → ${current}`);
+    await this._tearDownCurrentRole();
+    this._role = current;
+    this._emit("role-changed", event);
+    switch (current) {
+      case "hub":
+        await this._becomeHub();
+        break;
+      case "client":
+        await this._becomeClient();
+        break;
+    }
+  }
+  async _becomeHub() {
+    await this._ioMem.init();
+    await this._ioMem.isReady();
+    this._server = new Server(this._config.route, this._ioMem, this._bsMem, {
+      ...this._config.serverOptions,
+      logger: this._logger
+    });
+    await this._server.init();
+    try {
+      this._hubTransport = await this._deps.createHubTransport(
+        this._config.port
+      );
+      this._hubTransport.onConnection(async (socket) => {
+        if (!this._server) return;
+        await this._server.addSocket(socket);
+      });
+      this._logger.info("Node", "Now hub — accepting connections");
+    } catch (err) {
+      this._logger.error(
+        "Node",
+        `Hub transport failed (no incoming connections): ${err}`
+      );
+    }
+    const ctx = { role: "hub", server: this._server };
+    this._emit("ready", ctx);
+    await this._startAgent(ctx);
+  }
+  async _becomeClient() {
+    const topology = this._networkManager.getTopology();
+    const hubAddress = topology.hubAddress;
+    if (!hubAddress) {
+      this._logger.warn(
+        "Node",
+        "Cannot become client: no hub address in topology"
+      );
+      return;
+    }
+    try {
+      this._clientSocket = await this._deps.createClientTransport(hubAddress);
+    } catch (err) {
+      this._logger.error(
+        "Node",
+        `Client transport to ${hubAddress} failed: ${err}`
+      );
+      return;
+    }
+    await this._ioMem.init();
+    await this._ioMem.isReady();
+    this._client = new Client(
+      this._clientSocket,
+      this._ioMem,
+      this._bsMem,
+      this._config.route,
+      {
+        ...this._config.clientOptions,
+        logger: this._logger
+      }
+    );
+    await this._client.init();
+    this._logger.info("Node", `Now client — connected to hub ${hubAddress}`);
+    const ctx = {
+      role: "client",
+      client: this._client,
+      socket: this._clientSocket
+    };
+    this._emit("ready", ctx);
+    await this._startAgent(ctx);
+  }
+  // .........................................................................
+  // Internal
+  // .........................................................................
+  async _tearDownCurrentRole() {
+    await this._stopAgent();
+    if (this._server) {
+      await this._server.tearDown();
+      this._server = void 0;
+    }
+    if (this._hubTransport) {
+      await this._hubTransport.close();
+      this._hubTransport = void 0;
+    }
+    if (this._client) {
+      await this._client.tearDown();
+      this._client = void 0;
+    }
+    this._clientSocket = void 0;
+  }
+  async _startAgent(ctx) {
+    if (this._deps.createAgent) {
+      try {
+        this._agentHandle = await this._deps.createAgent(ctx);
+      } catch (err) {
+        this._logger.error("Node", `createAgent failed: ${err}`);
+      }
+    }
+  }
+  async _stopAgent() {
+    if (this._agentHandle) {
+      const handle = this._agentHandle;
+      this._agentHandle = void 0;
+      try {
+        await handle.stop();
+      } catch (err) {
+        this._logger.error("Node", `Agent stop failed: ${err}`);
+      }
+    }
+  }
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
 class SocketIoBridge {
   constructor(_socket) {
     this._socket = _socket;
@@ -2344,6 +1724,7 @@ export {
   ConsoleLogger,
   FileLogger,
   FilteredLogger,
+  Node,
   NoopLogger,
   Server,
   SocketIoBridge,