Class CascadeTree

Builds and maintains per-room cascade fan-out trees over an SfuCluster, scaling a single room's media to a very large viewer population.

For each room it runs planCascadeTree across the cluster's active nodes, then diffs the new plan against the previous one to emit the minimal set of link create/drop events and update per-node room tracking. It watches the cluster through a NodeFailureTracker: when a node that participates in a room's tree fails or is removed, that room's tree is rebuilt automatically.

Emits CascadeTreeEvent events. Pair with a CascadeBridge to realize the tree's links as real inter-node media pipes.

Example

const tree = new CascadeTree(cluster, { fanout: 8, viewersPerNode: 1000 })
tree.on(CascadeTreeEvent.LinkCreated, (roomId, from, to) => {
  media.pipeLink(roomId, from, to)
})

// Scale a broadcast to one million viewers:
const plan = tree.build('live-1', 'origin', 1_000_000)
if (plan.unmetViewers > 0) addMoreNodes()

tree.detach('live-1')

Remarks

Call CascadeTree.dispose to detach from cluster failure events when the tree is no longer needed.

Hierarchy (View Summary)

EventEmitter<CascadeTreeEvents>
- CascadeTree

Index

Constructors

constructor

Methods

build detach dispose emit getPlan listenerCount off on once removeAllListeners

Constructors

constructor

new CascadeTree(cluster: SfuCluster, options?: CascadeTreeOptions): CascadeTree
Parameters
- cluster: SfuCluster
  Cluster supplying the active nodes used to build trees, watched for failures.
- options: CascadeTreeOptions = {}
  Fan-out, per-node viewer capacity, and logging configuration.
Returns CascadeTree
Overrides EventEmitter.constructor
- Defined in packages/sfu/src/CascadeTree.ts:240

Methods

build

build(roomId: string, originId: string, viewerCount: number): CascadePlan
Build (or rebuild) the cascade tree for a room and reconcile it against any existing tree.

Computes a fresh plan over the cluster's active nodes, emits CascadeTreeEvent.LinkCreated / CascadeTreeEvent.LinkDropped for the links that changed, updates per-node room tracking, and emits CascadeTreeEvent.LeafAssigned for each seated leaf. If the plan cannot seat every viewer it emits CascadeTreeEvent.CapacityShortfall. Always emits CascadeTreeEvent.TreeBuilt with the final plan.
Parameters
- roomId: string
  Identifier of the room the tree serves.
- originId: string
  Identifier of the origin (root) node.
- viewerCount: number
  Total number of viewers to distribute across the tree.
Returns CascadePlan
The computed CascadePlan.
- Defined in packages/sfu/src/CascadeTree.ts:298

detach

detach(roomId: string): boolean
Tear down a room's cascade tree, untracking every participating node and emitting CascadeTreeEvent.LinkDropped for each link followed by CascadeTreeEvent.TreeDropped.
Parameters
- roomId: string
  Identifier of the room to detach.
Returns boolean
true if the room had a tree, false otherwise.
- Defined in packages/sfu/src/CascadeTree.ts:366

dispose

dispose(): void
Detach from cluster failure events. Existing room trees are left intact.

Returns void
- Defined in packages/sfu/src/CascadeTree.ts:271

emit

emit<K extends keyof CascadeTreeEvents>(
event: K,
...args: CascadeTreeEvents[K],
): boolean
Synchronously invokes every listener registered for event, in registration order.
Type Parameters
- K extends keyof CascadeTreeEvents
Parameters
- event: K
  The event name to emit.
- ...args: CascadeTreeEvents[K]
  The argument tuple to pass to each listener, matching Events[event].
Returns boolean
true if at least one listener was invoked, false if there were none.

Remarks
The listener list is snapshotted before dispatch, so mutations made by handlers take effect only on subsequent emissions. Listeners are isolated: if one throws, the remaining listeners still run and the error is surfaced via console.error rather than swallowed silently (consistent with LocalMessageBus).
Inherited from EventEmitter.emit
- Defined in packages/core/src/EventEmitter.ts:95

getPlan

getPlan(roomId: string): CascadePlan | undefined
Get the current cascade plan for a room.
Parameters
- roomId: string
  Identifier of the room.
Returns CascadePlan | undefined
The room's CascadePlan, or undefined if no tree exists for it.
- Defined in packages/sfu/src/CascadeTree.ts:384

listenerCount

listenerCount<K extends keyof CascadeTreeEvents>(event: K): number
Returns the number of listeners currently registered for event.
Type Parameters
- K extends keyof CascadeTreeEvents
Parameters
- event: K
  The event name to count listeners for.
Returns number
The count of registered listeners (0 if none).
Inherited from EventEmitter.listenerCount
- Defined in packages/core/src/EventEmitter.ts:128

off

off<K extends keyof CascadeTreeEvents>(
event: K,
listener: (...args: CascadeTreeEvents[K]) => void,
): this
Removes a previously registered listener for event.
Type Parameters
- K extends keyof CascadeTreeEvents
Parameters
- event: K
  The event name the listener was registered for.
- listener: (...args: CascadeTreeEvents[K]) => void
  The exact function reference passed to on or once.
Returns this
This emitter, for chaining.

Remarks
If the listener is not currently registered, this is a no-op. Only the first matching registration is removed.
Inherited from EventEmitter.off
- Defined in packages/core/src/EventEmitter.ts:74

on

on<K extends keyof CascadeTreeEvents>(
event: K,
listener: (...args: CascadeTreeEvents[K]) => void,
): this
Registers a listener that is invoked every time event is emitted.
Type Parameters
- K extends keyof CascadeTreeEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: CascadeTreeEvents[K]) => void
  Callback invoked with the event's argument tuple.
Returns this
This emitter, for chaining.
Inherited from EventEmitter.on
- Defined in packages/core/src/EventEmitter.ts:43

once

once<K extends keyof CascadeTreeEvents>(
event: K,
listener: (...args: CascadeTreeEvents[K]) => void,
): this
Registers a listener that is invoked at most once: it is removed automatically before being called the first time event is emitted.
Type Parameters
- K extends keyof CascadeTreeEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: CascadeTreeEvents[K]) => void
  Callback invoked with the event's argument tuple on the next emission.
Returns this
This emitter, for chaining.

Remarks
Remove a pending one-time listener by passing the same function reference to off.
Inherited from EventEmitter.once
- Defined in packages/core/src/EventEmitter.ts:57

removeAllListeners

removeAllListeners(event?: keyof CascadeTreeEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof CascadeTreeEvents
  The event name to clear; if omitted, listeners for every event are removed.
Returns this
This emitter, for chaining.
Inherited from EventEmitter.removeAllListeners
- Defined in packages/core/src/EventEmitter.ts:116

Class CascadeTree

Example

Remarks

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CascadeTree

Methods

build

Parameters

Returns CascadePlan

detach

Parameters

Returns boolean

dispose

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

getPlan

Parameters

Returns CascadePlan | undefined

listenerCount

Type Parameters

Parameters

Returns number

off

Type Parameters

Parameters

Returns this

Remarks

on

Type Parameters

Parameters

Returns this

once

Type Parameters

Parameters

Returns this

Remarks

removeAllListeners

Parameters

Returns this

Settings

On This Page