webrtc-tree 1.0.0

package/dist/server/RTCTreeCoordinator.d.ts

@@ -0,0 +1,38 @@
+export interface RTCTreeNode {
+    children: string[];
+    parent: string | null;
+    layer: number;
+}
+export interface RoomConfig {
+    maxNodesPerLayer: number[];
+}
+export declare class RTCTreeCoordinator {
+    private trees;
+    private configs;
+    /**
+     * 建立一個新的直播房間拓撲結構
+     * @param roomId 房間 ID
+     * @param streamerPeerId 直播主的 Peer ID
+     * @param config 拓撲設定，例如 maxNodesPerLayer: [1, 4, 8, 16, 64]
+     */
+    createRoom(roomId: string, streamerPeerId: string, config: RoomConfig): void;
+    /**
+     * 新節點加入，透過 BFS 分配最合適的父節點
+     * @param roomId 房間 ID
+     * @param newPeerId 新節點的 Peer ID
+     * @returns 分配到的父節點 Peer ID，若無法分配則回傳 null
+     */
+    joinNode(roomId: string, newPeerId: string): string | null;
+    /**
+     * 節點斷線，將其從樹中移除，並讓其子節點變成孤兒 (等待重新 join)
+     */
+    removeNode(roomId: string, deadPeerId: string): void;
+    /**
+     * 報告節點失效 (Self-Healing 觸發點)
+     */
+    reportDeadNode(roomId: string, deadPeerId: string): void;
+    /**
+     * 取得房間目前的樹狀結構 (For Debug/Monitor)
+     */
+    getTree(roomId: string): Record<string, RTCTreeNode> | null;
+}

package/dist/server/RTCTreeCoordinator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export * from './RTCTreeCoordinator';

package/dist/server/index.js

@@ -0,0 +1,137 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  RTCTreeCoordinator: () => RTCTreeCoordinator
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/server/RTCTreeCoordinator.ts
+var RTCTreeCoordinator = class {
+  constructor() {
+    // roomId -> peerId -> Node Data
+    this.trees = {};
+    this.configs = {};
+  }
+  /**
+   * 建立一個新的直播房間拓撲結構
+   * @param roomId 房間 ID
+   * @param streamerPeerId 直播主的 Peer ID
+   * @param config 拓撲設定，例如 maxNodesPerLayer: [1, 4, 8, 16, 64]
+   */
+  createRoom(roomId, streamerPeerId, config) {
+    this.configs[roomId] = config;
+    this.trees[roomId] = {};
+    this.trees[roomId][streamerPeerId] = { children: [], parent: null, layer: 0 };
+  }
+  /**
+   * 新節點加入，透過 BFS 分配最合適的父節點
+   * @param roomId 房間 ID
+   * @param newPeerId 新節點的 Peer ID
+   * @returns 分配到的父節點 Peer ID，若無法分配則回傳 null
+   */
+  joinNode(roomId, newPeerId) {
+    const tree = this.trees[roomId];
+    const config = this.configs[roomId];
+    if (!tree || !config) return null;
+    let rootId = null;
+    for (const [id, node] of Object.entries(tree)) {
+      if (node.layer === 0) {
+        rootId = id;
+        break;
+      }
+    }
+    if (!rootId) return null;
+    if (tree[newPeerId]) {
+      this.removeNode(roomId, newPeerId);
+    }
+    const layerCounts = {};
+    for (const node of Object.values(tree)) {
+      layerCounts[node.layer] = (layerCounts[node.layer] || 0) + 1;
+    }
+    const queue = [rootId];
+    while (queue.length > 0) {
+      const currentId = queue.shift();
+      const currentNode = tree[currentId];
+      const currentLayer = currentNode.layer;
+      const nextLayer = currentLayer + 1;
+      if (nextLayer >= config.maxNodesPerLayer.length) {
+        queue.push(...currentNode.children);
+        continue;
+      }
+      const nextLayerMax = config.maxNodesPerLayer[nextLayer];
+      const currentNextLayerCount = layerCounts[nextLayer] || 0;
+      if (currentNextLayerCount >= nextLayerMax) {
+        queue.push(...currentNode.children);
+        continue;
+      }
+      const currentLayerMax = config.maxNodesPerLayer[currentLayer];
+      const maxChildrenPerNode = Math.floor(nextLayerMax / currentLayerMax) || 1;
+      if (currentNode.children.length < maxChildrenPerNode) {
+        currentNode.children.push(newPeerId);
+        tree[newPeerId] = {
+          children: [],
+          parent: currentId,
+          layer: nextLayer
+        };
+        return currentId;
+      }
+      queue.push(...currentNode.children);
+    }
+    return null;
+  }
+  /**
+   * 節點斷線，將其從樹中移除，並讓其子節點變成孤兒 (等待重新 join)
+   */
+  removeNode(roomId, deadPeerId) {
+    const tree = this.trees[roomId];
+    if (!tree) return;
+    const deadNode = tree[deadPeerId];
+    if (!deadNode) return;
+    if (deadNode.parent && tree[deadNode.parent]) {
+      const parentNode = tree[deadNode.parent];
+      parentNode.children = parentNode.children.filter((id) => id !== deadPeerId);
+    }
+    for (const childId of deadNode.children) {
+      if (tree[childId]) {
+        tree[childId].parent = null;
+      }
+    }
+    delete tree[deadPeerId];
+  }
+  /**
+   * 報告節點失效 (Self-Healing 觸發點)
+   */
+  reportDeadNode(roomId, deadPeerId) {
+    this.removeNode(roomId, deadPeerId);
+  }
+  /**
+   * 取得房間目前的樹狀結構 (For Debug/Monitor)
+   */
+  getTree(roomId) {
+    return this.trees[roomId] || null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RTCTreeCoordinator
+});
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/index.ts","../../src/server/RTCTreeCoordinator.ts"],"sourcesContent":["export * from './RTCTreeCoordinator';\n","export interface RTCTreeNode {\n  children: string[];\n  parent: string | null;\n  layer: number;\n}\n\nexport interface RoomConfig {\n  maxNodesPerLayer: number[]; // e.g. [1, 4, 8, 16, 64]\n}\n\nexport class RTCTreeCoordinator {\n  // roomId -> peerId -> Node Data\n  private trees: Record<string, Record<string, RTCTreeNode>> = {};\n  private configs: Record<string, RoomConfig> = {};\n\n  /**\n   * 建立一個新的直播房間拓撲結構\n   * @param roomId 房間 ID\n   * @param streamerPeerId 直播主的 Peer ID\n   * @param config 拓撲設定，例如 maxNodesPerLayer: [1, 4, 8, 16, 64]\n   */\n  public createRoom(roomId: string, streamerPeerId: string, config: RoomConfig): void {\n    this.configs[roomId] = config;\n    this.trees[roomId] = {};\n    // Streamer is at layer 0\n    this.trees[roomId][streamerPeerId] = { children: [], parent: null, layer: 0 };\n  }\n\n  /**\n   * 新節點加入，透過 BFS 分配最合適的父節點\n   * @param roomId 房間 ID\n   * @param newPeerId 新節點的 Peer ID\n   * @returns 分配到的父節點 Peer ID，若無法分配則回傳 null\n   */\n  public joinNode(roomId: string, newPeerId: string): string | null {\n    const tree = this.trees[roomId];\n    const config = this.configs[roomId];\n    if (!tree || !config) return null;\n\n    // 尋找樹根 (layer 0 的節點，通常是 streamer)\n    let rootId: string | null = null;\n    for (const [id, node] of Object.entries(tree)) {\n      if (node.layer === 0) {\n        rootId = id;\n        break;\n      }\n    }\n\n    if (!rootId) return null;\n\n    // 如果該節點已經在樹中，先將其從原本的位置移除 (防止重複加入或狀態不一致)\n    if (tree[newPeerId]) {\n      this.removeNode(roomId, newPeerId);\n    }\n\n    // 計算目前每一層的總節點數\n    const layerCounts: Record<number, number> = {};\n    for (const node of Object.values(tree)) {\n      layerCounts[node.layer] = (layerCounts[node.layer] || 0) + 1;\n    }\n\n    // BFS 尋找未滿載的節點\n    const queue: string[] = [rootId];\n    \n    while (queue.length > 0) {\n      const currentId = queue.shift()!;\n      const currentNode = tree[currentId];\n      const currentLayer = currentNode.layer;\n      \n      // 下一層的索引\n      const nextLayer = currentLayer + 1;\n\n      // 如果已經達到最大層數設定，該節點不能再有子節點\n      if (nextLayer >= config.maxNodesPerLayer.length) {\n        // Continue searching in queue\n        queue.push(...currentNode.children);\n        continue;\n      }\n\n      // 檢查下一層是否已經達到整體上限\n      const nextLayerMax = config.maxNodesPerLayer[nextLayer];\n      const currentNextLayerCount = layerCounts[nextLayer] || 0;\n\n      if (currentNextLayerCount >= nextLayerMax) {\n        // 下一層已經滿了，把目前節點的子節點加入 queue 繼續尋找更下層\n        queue.push(...currentNode.children);\n        continue;\n      }\n\n      // 如果下一層還沒滿，那我們要決定「目前這個節點」還能不能接客\n      // 算法：該層平均每個節點可以接的子節點數\n      // 例如 layer 1 最大 4 人，layer 2 最大 8 人，代表 layer 1 每個節點最多接 8/4 = 2 人\n      const currentLayerMax = config.maxNodesPerLayer[currentLayer];\n      const maxChildrenPerNode = Math.floor(nextLayerMax / currentLayerMax) || 1;\n\n      if (currentNode.children.length < maxChildrenPerNode) {\n        // 找到可以接客的節點了！\n        currentNode.children.push(newPeerId);\n        tree[newPeerId] = {\n          children: [],\n          parent: currentId,\n          layer: nextLayer\n        };\n        return currentId;\n      }\n\n      // 目前節點滿了，把它的小孩加進 queue\n      queue.push(...currentNode.children);\n    }\n\n    return null; // 樹已滿或無法分配\n  }\n\n  /**\n   * 節點斷線，將其從樹中移除，並讓其子節點變成孤兒 (等待重新 join)\n   */\n  public removeNode(roomId: string, deadPeerId: string): void {\n    const tree = this.trees[roomId];\n    if (!tree) return;\n\n    const deadNode = tree[deadPeerId];\n    if (!deadNode) return;\n\n    // 將自己從父節點的 children 中移除\n    if (deadNode.parent && tree[deadNode.parent]) {\n      const parentNode = tree[deadNode.parent];\n      parentNode.children = parentNode.children.filter(id => id !== deadPeerId);\n    }\n\n    // 將子節點的 parent 設為 null (它們需要重新連線)\n    for (const childId of deadNode.children) {\n      if (tree[childId]) {\n        tree[childId].parent = null;\n      }\n    }\n\n    delete tree[deadPeerId];\n  }\n\n  /**\n   * 報告節點失效 (Self-Healing 觸發點)\n   */\n  public reportDeadNode(roomId: string, deadPeerId: string): void {\n    this.removeNode(roomId, deadPeerId);\n  }\n\n  /**\n   * 取得房間目前的樹狀結構 (For Debug/Monitor)\n   */\n  public getTree(roomId: string): Record<string, RTCTreeNode> | null {\n    return this.trees[roomId] || null;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACUO,IAAM,qBAAN,MAAyB;AAAA,EAAzB;AAEL;AAAA,SAAQ,QAAqD,CAAC;AAC9D,SAAQ,UAAsC,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQxC,WAAW,QAAgB,gBAAwB,QAA0B;AAClF,SAAK,QAAQ,MAAM,IAAI;AACvB,SAAK,MAAM,MAAM,IAAI,CAAC;AAEtB,SAAK,MAAM,MAAM,EAAE,cAAc,IAAI,EAAE,UAAU,CAAC,GAAG,QAAQ,MAAM,OAAO,EAAE;AAAA,EAC9E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,SAAS,QAAgB,WAAkC;AAChE,UAAM,OAAO,KAAK,MAAM,MAAM;AAC9B,UAAM,SAAS,KAAK,QAAQ,MAAM;AAClC,QAAI,CAAC,QAAQ,CAAC,OAAQ,QAAO;AAG7B,QAAI,SAAwB;AAC5B,eAAW,CAAC,IAAI,IAAI,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC7C,UAAI,KAAK,UAAU,GAAG;AACpB,iBAAS;AACT;AAAA,MACF;AAAA,IACF;AAEA,QAAI,CAAC,OAAQ,QAAO;AAGpB,QAAI,KAAK,SAAS,GAAG;AACnB,WAAK,WAAW,QAAQ,SAAS;AAAA,IACnC;AAGA,UAAM,cAAsC,CAAC;AAC7C,eAAW,QAAQ,OAAO,OAAO,IAAI,GAAG;AACtC,kBAAY,KAAK,KAAK,KAAK,YAAY,KAAK,KAAK,KAAK,KAAK;AAAA,IAC7D;AAGA,UAAM,QAAkB,CAAC,MAAM;AAE/B,WAAO,MAAM,SAAS,GAAG;AACvB,YAAM,YAAY,MAAM,MAAM;AAC9B,YAAM,cAAc,KAAK,SAAS;AAClC,YAAM,eAAe,YAAY;AAGjC,YAAM,YAAY,eAAe;AAGjC,UAAI,aAAa,OAAO,iBAAiB,QAAQ;AAE/C,cAAM,KAAK,GAAG,YAAY,QAAQ;AAClC;AAAA,MACF;AAGA,YAAM,eAAe,OAAO,iBAAiB,SAAS;AACtD,YAAM,wBAAwB,YAAY,SAAS,KAAK;AAExD,UAAI,yBAAyB,cAAc;AAEzC,cAAM,KAAK,GAAG,YAAY,QAAQ;AAClC;AAAA,MACF;AAKA,YAAM,kBAAkB,OAAO,iBAAiB,YAAY;AAC5D,YAAM,qBAAqB,KAAK,MAAM,eAAe,eAAe,KAAK;AAEzE,UAAI,YAAY,SAAS,SAAS,oBAAoB;AAEpD,oBAAY,SAAS,KAAK,SAAS;AACnC,aAAK,SAAS,IAAI;AAAA,UAChB,UAAU,CAAC;AAAA,UACX,QAAQ;AAAA,UACR,OAAO;AAAA,QACT;AACA,eAAO;AAAA,MACT;AAGA,YAAM,KAAK,GAAG,YAAY,QAAQ;AAAA,IACpC;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKO,WAAW,QAAgB,YAA0B;AAC1D,UAAM,OAAO,KAAK,MAAM,MAAM;AAC9B,QAAI,CAAC,KAAM;AAEX,UAAM,WAAW,KAAK,UAAU;AAChC,QAAI,CAAC,SAAU;AAGf,QAAI,SAAS,UAAU,KAAK,SAAS,MAAM,GAAG;AAC5C,YAAM,aAAa,KAAK,SAAS,MAAM;AACvC,iBAAW,WAAW,WAAW,SAAS,OAAO,QAAM,OAAO,UAAU;AAAA,IAC1E;AAGA,eAAW,WAAW,SAAS,UAAU;AACvC,UAAI,KAAK,OAAO,GAAG;AACjB,aAAK,OAAO,EAAE,SAAS;AAAA,MACzB;AAAA,IACF;AAEA,WAAO,KAAK,UAAU;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKO,eAAe,QAAgB,YAA0B;AAC9D,SAAK,WAAW,QAAQ,UAAU;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKO,QAAQ,QAAoD;AACjE,WAAO,KAAK,MAAM,MAAM,KAAK;AAAA,EAC/B;AACF;","names":[]}

package/dist/server/index.mjs

@@ -0,0 +1,110 @@
+// src/server/RTCTreeCoordinator.ts
+var RTCTreeCoordinator = class {
+  constructor() {
+    // roomId -> peerId -> Node Data
+    this.trees = {};
+    this.configs = {};
+  }
+  /**
+   * 建立一個新的直播房間拓撲結構
+   * @param roomId 房間 ID
+   * @param streamerPeerId 直播主的 Peer ID
+   * @param config 拓撲設定，例如 maxNodesPerLayer: [1, 4, 8, 16, 64]
+   */
+  createRoom(roomId, streamerPeerId, config) {
+    this.configs[roomId] = config;
+    this.trees[roomId] = {};
+    this.trees[roomId][streamerPeerId] = { children: [], parent: null, layer: 0 };
+  }
+  /**
+   * 新節點加入，透過 BFS 分配最合適的父節點
+   * @param roomId 房間 ID
+   * @param newPeerId 新節點的 Peer ID
+   * @returns 分配到的父節點 Peer ID，若無法分配則回傳 null
+   */
+  joinNode(roomId, newPeerId) {
+    const tree = this.trees[roomId];
+    const config = this.configs[roomId];
+    if (!tree || !config) return null;
+    let rootId = null;
+    for (const [id, node] of Object.entries(tree)) {
+      if (node.layer === 0) {
+        rootId = id;
+        break;
+      }
+    }
+    if (!rootId) return null;
+    if (tree[newPeerId]) {
+      this.removeNode(roomId, newPeerId);
+    }
+    const layerCounts = {};
+    for (const node of Object.values(tree)) {
+      layerCounts[node.layer] = (layerCounts[node.layer] || 0) + 1;
+    }
+    const queue = [rootId];
+    while (queue.length > 0) {
+      const currentId = queue.shift();
+      const currentNode = tree[currentId];
+      const currentLayer = currentNode.layer;
+      const nextLayer = currentLayer + 1;
+      if (nextLayer >= config.maxNodesPerLayer.length) {
+        queue.push(...currentNode.children);
+        continue;
+      }
+      const nextLayerMax = config.maxNodesPerLayer[nextLayer];
+      const currentNextLayerCount = layerCounts[nextLayer] || 0;
+      if (currentNextLayerCount >= nextLayerMax) {
+        queue.push(...currentNode.children);
+        continue;
+      }
+      const currentLayerMax = config.maxNodesPerLayer[currentLayer];
+      const maxChildrenPerNode = Math.floor(nextLayerMax / currentLayerMax) || 1;
+      if (currentNode.children.length < maxChildrenPerNode) {
+        currentNode.children.push(newPeerId);
+        tree[newPeerId] = {
+          children: [],
+          parent: currentId,
+          layer: nextLayer
+        };
+        return currentId;
+      }
+      queue.push(...currentNode.children);
+    }
+    return null;
+  }
+  /**
+   * 節點斷線，將其從樹中移除，並讓其子節點變成孤兒 (等待重新 join)
+   */
+  removeNode(roomId, deadPeerId) {
+    const tree = this.trees[roomId];
+    if (!tree) return;
+    const deadNode = tree[deadPeerId];
+    if (!deadNode) return;
+    if (deadNode.parent && tree[deadNode.parent]) {
+      const parentNode = tree[deadNode.parent];
+      parentNode.children = parentNode.children.filter((id) => id !== deadPeerId);
+    }
+    for (const childId of deadNode.children) {
+      if (tree[childId]) {
+        tree[childId].parent = null;
+      }
+    }
+    delete tree[deadPeerId];
+  }
+  /**
+   * 報告節點失效 (Self-Healing 觸發點)
+   */
+  reportDeadNode(roomId, deadPeerId) {
+    this.removeNode(roomId, deadPeerId);
+  }
+  /**
+   * 取得房間目前的樹狀結構 (For Debug/Monitor)
+   */
+  getTree(roomId) {
+    return this.trees[roomId] || null;
+  }
+};
+export {
+  RTCTreeCoordinator
+};
+//# sourceMappingURL=index.mjs.map

package/dist/server/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/RTCTreeCoordinator.ts"],"sourcesContent":["export interface RTCTreeNode {\n  children: string[];\n  parent: string | null;\n  layer: number;\n}\n\nexport interface RoomConfig {\n  maxNodesPerLayer: number[]; // e.g. [1, 4, 8, 16, 64]\n}\n\nexport class RTCTreeCoordinator {\n  // roomId -> peerId -> Node Data\n  private trees: Record<string, Record<string, RTCTreeNode>> = {};\n  private configs: Record<string, RoomConfig> = {};\n\n  /**\n   * 建立一個新的直播房間拓撲結構\n   * @param roomId 房間 ID\n   * @param streamerPeerId 直播主的 Peer ID\n   * @param config 拓撲設定，例如 maxNodesPerLayer: [1, 4, 8, 16, 64]\n   */\n  public createRoom(roomId: string, streamerPeerId: string, config: RoomConfig): void {\n    this.configs[roomId] = config;\n    this.trees[roomId] = {};\n    // Streamer is at layer 0\n    this.trees[roomId][streamerPeerId] = { children: [], parent: null, layer: 0 };\n  }\n\n  /**\n   * 新節點加入，透過 BFS 分配最合適的父節點\n   * @param roomId 房間 ID\n   * @param newPeerId 新節點的 Peer ID\n   * @returns 分配到的父節點 Peer ID，若無法分配則回傳 null\n   */\n  public joinNode(roomId: string, newPeerId: string): string | null {\n    const tree = this.trees[roomId];\n    const config = this.configs[roomId];\n    if (!tree || !config) return null;\n\n    // 尋找樹根 (layer 0 的節點，通常是 streamer)\n    let rootId: string | null = null;\n    for (const [id, node] of Object.entries(tree)) {\n      if (node.layer === 0) {\n        rootId = id;\n        break;\n      }\n    }\n\n    if (!rootId) return null;\n\n    // 如果該節點已經在樹中，先將其從原本的位置移除 (防止重複加入或狀態不一致)\n    if (tree[newPeerId]) {\n      this.removeNode(roomId, newPeerId);\n    }\n\n    // 計算目前每一層的總節點數\n    const layerCounts: Record<number, number> = {};\n    for (const node of Object.values(tree)) {\n      layerCounts[node.layer] = (layerCounts[node.layer] || 0) + 1;\n    }\n\n    // BFS 尋找未滿載的節點\n    const queue: string[] = [rootId];\n    \n    while (queue.length > 0) {\n      const currentId = queue.shift()!;\n      const currentNode = tree[currentId];\n      const currentLayer = currentNode.layer;\n      \n      // 下一層的索引\n      const nextLayer = currentLayer + 1;\n\n      // 如果已經達到最大層數設定，該節點不能再有子節點\n      if (nextLayer >= config.maxNodesPerLayer.length) {\n        // Continue searching in queue\n        queue.push(...currentNode.children);\n        continue;\n      }\n\n      // 檢查下一層是否已經達到整體上限\n      const nextLayerMax = config.maxNodesPerLayer[nextLayer];\n      const currentNextLayerCount = layerCounts[nextLayer] || 0;\n\n      if (currentNextLayerCount >= nextLayerMax) {\n        // 下一層已經滿了，把目前節點的子節點加入 queue 繼續尋找更下層\n        queue.push(...currentNode.children);\n        continue;\n      }\n\n      // 如果下一層還沒滿，那我們要決定「目前這個節點」還能不能接客\n      // 算法：該層平均每個節點可以接的子節點數\n      // 例如 layer 1 最大 4 人，layer 2 最大 8 人，代表 layer 1 每個節點最多接 8/4 = 2 人\n      const currentLayerMax = config.maxNodesPerLayer[currentLayer];\n      const maxChildrenPerNode = Math.floor(nextLayerMax / currentLayerMax) || 1;\n\n      if (currentNode.children.length < maxChildrenPerNode) {\n        // 找到可以接客的節點了！\n        currentNode.children.push(newPeerId);\n        tree[newPeerId] = {\n          children: [],\n          parent: currentId,\n          layer: nextLayer\n        };\n        return currentId;\n      }\n\n      // 目前節點滿了，把它的小孩加進 queue\n      queue.push(...currentNode.children);\n    }\n\n    return null; // 樹已滿或無法分配\n  }\n\n  /**\n   * 節點斷線，將其從樹中移除，並讓其子節點變成孤兒 (等待重新 join)\n   */\n  public removeNode(roomId: string, deadPeerId: string): void {\n    const tree = this.trees[roomId];\n    if (!tree) return;\n\n    const deadNode = tree[deadPeerId];\n    if (!deadNode) return;\n\n    // 將自己從父節點的 children 中移除\n    if (deadNode.parent && tree[deadNode.parent]) {\n      const parentNode = tree[deadNode.parent];\n      parentNode.children = parentNode.children.filter(id => id !== deadPeerId);\n    }\n\n    // 將子節點的 parent 設為 null (它們需要重新連線)\n    for (const childId of deadNode.children) {\n      if (tree[childId]) {\n        tree[childId].parent = null;\n      }\n    }\n\n    delete tree[deadPeerId];\n  }\n\n  /**\n   * 報告節點失效 (Self-Healing 觸發點)\n   */\n  public reportDeadNode(roomId: string, deadPeerId: string): void {\n    this.removeNode(roomId, deadPeerId);\n  }\n\n  /**\n   * 取得房間目前的樹狀結構 (For Debug/Monitor)\n   */\n  public getTree(roomId: string): Record<string, RTCTreeNode> | null {\n    return this.trees[roomId] || null;\n  }\n}\n"],"mappings":"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","names":[]}

package/jest.config.js

@@ -0,0 +1,6 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.ts'],
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "webrtc-tree",
+  "version": "1.0.0",
+  "description": "Auto-balancing WebRTC Mesh Tree for live streaming",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "require": "./dist/server/index.cjs",
+      "import": "./dist/server/index.mjs",
+      "types": "./dist/server/index.d.ts"
+    },
+    "./client": {
+      "require": "./dist/client/index.cjs",
+      "import": "./dist/client/index.mjs",
+      "types": "./dist/client/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build:types": "tsc --emitDeclarationOnly",
+    "build": "tsup && npm run build:types",
+    "test": "jest"
+  },
+  "keywords": [
+    "webrtc",
+    "mesh",
+    "p2p",
+    "live",
+    "streaming",
+    "tree",
+    "auto-balancing"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "peerDependencies": {
+    "peerjs": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/client/RTCTreeClient.ts

@@ -0,0 +1,208 @@
+import Peer, { MediaConnection } from 'peerjs';
+
+export interface RTCTreeClientOptions {
+  onStreamReceived?: (stream: MediaStream) => void;
+  onStatusChange?: (status: string) => void;
+  onError?: (error: any) => void;
+  fetchParentIdFn?: () => Promise<string | null>; // Client uses this to ask Server for a parent
+  reportDeadFn?: (deadPeerId: string) => Promise<void>; // Client uses this to tell Server a node is dead
+}
+
+export class RTCTreeClient {
+  private peer: Peer | null = null;
+  private myPeerId: string | null = null;
+  private myStream: MediaStream | null = null;
+  private activeCalls: Record<string, MediaConnection> = {};
+  private parentConnection: MediaConnection | null = null;
+  
+  // State
+  private isStreamer: boolean = false;
+  private isReconnecting: boolean = false;
+
+  constructor(private options: RTCTreeClientOptions) {}
+
+  /**
+   * 初始化為直播主 (Streamer)
+   * @param stream 本地攝影機/麥克風的 MediaStream
+   * @param maxChildren 第一層最大觀眾數 (Layer 1 Capacity)
+   * @returns 建立完成後的 Peer ID
+   */
+  public initStreamer(stream: MediaStream, maxChildren: number = 4): Promise<string> {
+    this.isStreamer = true;
+    this.myStream = stream;
+
+    return new Promise((resolve, reject) => {
+      this.peer = new Peer();
+
+      this.peer.on('open', (id) => {
+        this.myPeerId = id;
+        this.options.onStatusChange?.("直播已開始");
+        resolve(id);
+      });
+
+      this.peer.on('error', (err) => {
+        this.options.onError?.(err);
+        reject(err);
+      });
+
+      // 監聽觀眾連線請求
+      this.peer.on('connection', (conn) => {
+        conn.on('data', (data: any) => {
+          if (data === 'VIEWER_READY') {
+            if (Object.keys(this.activeCalls).length < maxChildren) {
+              const call = this.peer!.call(conn.peer, this.myStream!);
+              this.activeCalls[conn.peer] = call;
+            } else {
+              conn.send({ type: 'REJECT_FULL' });
+            }
+          }
+        });
+
+        conn.on('close', () => {
+          if (this.activeCalls[conn.peer]) {
+            this.activeCalls[conn.peer].close();
+            delete this.activeCalls[conn.peer];
+          }
+        });
+      });
+    });
+  }
+
+  /**
+   * 初始化為觀眾 (Viewer)
+   * @param maxChildren 轉發最大觀眾數 (Layer N Capacity)
+   */
+  public initViewer(maxChildren: number = 4): Promise<string> {
+    this.isStreamer = false;
+
+    return new Promise((resolve, reject) => {
+      this.peer = new Peer();
+
+      this.peer.on('open', async (id) => {
+        this.myPeerId = id;
+        this.options.onStatusChange?.("正在分配節點...");
+        resolve(id);
+        
+        // 開始加入流程
+        await this.connectToMesh();
+      });
+
+      this.peer.on('error', (err) => {
+        this.options.onError?.(err);
+        reject(err);
+      });
+
+      // 當我們自己也是別人的 parent 時，處理下層觀眾連線
+      this.peer.on('connection', (conn) => {
+        conn.on('data', (data: any) => {
+          if (data === 'VIEWER_READY') {
+            if (Object.keys(this.activeCalls).length < maxChildren && this.myStream) {
+              const call = this.peer!.call(conn.peer, this.myStream);
+              this.activeCalls[conn.peer] = call;
+            } else {
+              conn.send({ type: 'REJECT_FULL' });
+            }
+          }
+        });
+
+        conn.on('close', () => {
+          if (this.activeCalls[conn.peer]) {
+            this.activeCalls[conn.peer].close();
+            delete this.activeCalls[conn.peer];
+          }
+        });
+      });
+
+      // 接收上層傳來的影像
+      this.peer.on('call', (call) => {
+        this.options.onStatusChange?.("接收影像中...");
+        this.parentConnection = call;
+        call.answer(); 
+        
+        call.on('stream', (remoteStream) => {
+          this.myStream = remoteStream;
+          this.options.onStatusChange?.(""); 
+          this.options.onStreamReceived?.(remoteStream);
+        });
+
+        call.on('close', () => {
+          // 上層斷線！啟動 Self-Healing
+          this.handleParentDisconnect(call.peer);
+        });
+      });
+    });
+  }
+
+  private async connectToMesh(): Promise<void> {
+    if (!this.options.fetchParentIdFn) {
+      throw new Error("fetchParentIdFn is required for viewers");
+    }
+
+    try {
+      const targetPeerId = await this.options.fetchParentIdFn();
+      if (!targetPeerId) {
+        this.options.onStatusChange?.("暫無可用節點，請稍後重試");
+        // 可以加上 retry 機制
+        return;
+      }
+
+      this.options.onStatusChange?.("連線中...");
+      const conn = this.peer!.connect(targetPeerId);
+
+      const timeoutId = setTimeout(() => {
+        conn.close();
+        this.handleParentDisconnect(targetPeerId);
+      }, 5000);
+
+      conn.on('open', () => {
+        clearTimeout(timeoutId);
+        conn.send('VIEWER_READY');
+      });
+
+      conn.on('data', (data: any) => {
+        if (data && data.type === 'REJECT_FULL') {
+          clearTimeout(timeoutId);
+          conn.close();
+          this.handleParentDisconnect(targetPeerId);
+        }
+      });
+
+      conn.on('close', () => {
+        clearTimeout(timeoutId);
+        this.handleParentDisconnect(targetPeerId);
+      });
+
+      conn.on('error', () => {
+        clearTimeout(timeoutId);
+        this.handleParentDisconnect(targetPeerId);
+      });
+
+    } catch (e) {
+      this.options.onStatusChange?.("連線失敗");
+      console.error(e);
+    }
+  }
+
+  private async handleParentDisconnect(deadPeerId: string) {
+    if (this.isReconnecting) return;
+    this.isReconnecting = true;
+    this.options.onStatusChange?.("上層節點斷線，重新尋找路徑...");
+
+    if (this.options.reportDeadFn) {
+      await this.options.reportDeadFn(deadPeerId).catch(console.error);
+    }
+
+    // 延遲一下避免大量 request
+    setTimeout(async () => {
+      this.isReconnecting = false;
+      await this.connectToMesh();
+    }, 2000);
+  }
+
+  public destroy() {
+    if (this.peer) {
+      this.peer.destroy();
+      this.peer = null;
+    }
+  }
+}

package/src/client/index.ts

@@ -0,0 +1 @@
+export * from './RTCTreeClient';

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './server/index';
+export * from './client/index';

package/src/server/RTCTreeCoordinator.test.ts

@@ -0,0 +1,83 @@
+import { RTCTreeCoordinator } from './RTCTreeCoordinator';
+
+describe('RTCTreeCoordinator', () => {
+  let coordinator: RTCTreeCoordinator;
+  const roomId = 'test-room';
+  const streamerId = 'peer-streamer';
+
+  beforeEach(() => {
+    coordinator = new RTCTreeCoordinator();
+  });
+
+  test('should create a room and streamer should be at layer 0', () => {
+    coordinator.createRoom(roomId, streamerId, { maxNodesPerLayer: [1, 4, 8, 16] });
+    const tree = coordinator.getTree(roomId);
+    expect(tree).toBeDefined();
+    expect(tree![streamerId]).toBeDefined();
+    expect(tree![streamerId].layer).toBe(0);
+    expect(tree![streamerId].children.length).toBe(0);
+  });
+
+  test('should distribute viewers according to maxNodesPerLayer [1, 4, 8]', () => {
+    // 1 Streamer
+    // Layer 1: Max 4
+    // Layer 2: Max 8 (each Layer 1 node handles 2 children)
+    coordinator.createRoom(roomId, streamerId, { maxNodesPerLayer: [1, 4, 8] });
+
+    // Join 4 viewers
+    for (let i = 1; i <= 4; i++) {
+      const parent = coordinator.joinNode(roomId, `peer-v${i}`);
+      expect(parent).toBe(streamerId);
+    }
+
+    const tree = coordinator.getTree(roomId);
+    expect(tree![streamerId].children.length).toBe(4);
+
+    // Join 5th viewer, should go to layer 2
+    const parent5 = coordinator.joinNode(roomId, `peer-v5`);
+    expect(parent5).not.toBe(streamerId);
+    expect(['peer-v1', 'peer-v2', 'peer-v3', 'peer-v4']).toContain(parent5);
+
+    // Join up to 12 total viewers (4 in L1, 8 in L2)
+    for (let i = 6; i <= 12; i++) {
+      coordinator.joinNode(roomId, `peer-v${i}`);
+    }
+
+    // Now L1 has 4 nodes, L2 has 8 nodes. Total 13 nodes (including streamer)
+    const treeState = coordinator.getTree(roomId)!;
+    let l1Count = 0;
+    let l2Count = 0;
+    for (const node of Object.values(treeState)) {
+      if (node.layer === 1) l1Count++;
+      if (node.layer === 2) l2Count++;
+    }
+    expect(l1Count).toBe(4);
+    expect(l2Count).toBe(8);
+
+    // Join 13th viewer. Tree should be FULL because config only specifies up to L2 (maxNodesPerLayer length is 3)
+    const parent13 = coordinator.joinNode(roomId, 'peer-v13');
+    expect(parent13).toBeNull();
+  });
+
+  test('should self-heal when a node is removed', () => {
+    coordinator.createRoom(roomId, streamerId, { maxNodesPerLayer: [1, 4] });
+    coordinator.joinNode(roomId, 'peer-v1');
+    coordinator.joinNode(roomId, 'peer-v2');
+
+    let tree = coordinator.getTree(roomId)!;
+    expect(tree[streamerId].children).toEqual(['peer-v1', 'peer-v2']);
+
+    // Remove v1
+    coordinator.reportDeadNode(roomId, 'peer-v1');
+    tree = coordinator.getTree(roomId)!;
+
+    expect(tree['peer-v1']).toBeUndefined();
+    expect(tree[streamerId].children).toEqual(['peer-v2']);
+
+    // Re-join v1 (simulate reconnection)
+    const parent = coordinator.joinNode(roomId, 'peer-v1');
+    expect(parent).toBe(streamerId);
+    tree = coordinator.getTree(roomId)!;
+    expect(tree[streamerId].children).toEqual(['peer-v2', 'peer-v1']);
+  });
+});