feat(media-streaming,pubsub): expand helper swarm and chunk scheduler APIs

- helper-swarm-coordinator: autoAssign, rebalance, resetUtilization
- chunk-scheduler-media: enqueueBatch, dropBelowPriority, clear
- qos-topic: queueDepths, clearQueues
- Update routing-advanced category README highlights

Co-authored-by: Cursor <[email protected]>

media-streaming/hyper-p2p-chunk-scheduler-media/index.js

@@ -84,6 +84,23 @@ class HyperP2PChunkSchedulerMedia extends EventEmitter {
     return this._queue.length
   }
 
+  enqueueBatch (chunks) {
+    if (!Array.isArray(chunks)) throw new Error('chunks must be an array')
+    return chunks.map((c) => this.enqueue(c.chunk || c, c.priority))
+  }
+
+  dropBelowPriority (minPriority) {
+    const before = this._queue.length
+    this._queue = this._queue.filter((e) => e.priority >= minPriority)
+    return before - this._queue.length
+  }
+
+  clear () {
+    const n = this._queue.length
+    this._queue = []
+    return n
+  }
+
   getStats () {
     return mediaStats(this._stats, PROTOCOL, { pending: this._queue.length })
   }

media-streaming/hyper-p2p-helper-swarm-coordinator/index.js

@@ -73,6 +73,26 @@ class HyperP2PHelperSwarmCoordinator extends EventEmitter {
     return Math.min(1, h.usedBps / h.capacityBps)
   }
 
+  autoAssign (viewerId, count = 3) {
+    const available = this.availableHelpers()
+      .sort((a, b) => (a.usedBps / (a.capacityBps || 1)) - (b.usedBps / (b.capacityBps || 1)))
+    const helpers = available.slice(0, Math.max(0, count | 0)).map((h) => h.peerId)
+    return this.assignViewer(viewerId, helpers)
+  }
+
+  resetUtilization () {
+    let n = 0
+    for (const h of this._helpers.values()) {
+      h.usedBps = 0
+      n++
+    }
+    return n
+  }
+
+  rebalance (viewerId) {
+    return this.autoAssign(viewerId)
+  }
+
   _gossip (payload) {
     if (this._peerMsgs) gossipSend(this, payload)
   }

messaging-pubsub/hyper-p2p-qos-topic/index.js

@@ -75,6 +75,19 @@ class HyperP2PQosTopic extends EventEmitter {
 
   hasHandler (channel) { return this._handlers.has(channel) }
 
+  queueDepths () {
+    return this._queues.map((q, qos) => ({ qos, depth: q.length }))
+  }
+
+  clearQueues () {
+    let n = 0
+    for (const q of this._queues) {
+      n += q.length
+      q.length = 0
+    }
+    return n
+  }
+
   _onGossip (data) {
     if (!data || data.type !== 'qos-publish') return
     this._stats.gossipIn++