Class CascadingRouter

Assigns rooms to SFU nodes and grows per-room cascades across additional nodes on top of an SfuCluster.

Each room gets one primary node via the cluster's placement strategy. When a room is attached again and placement resolves to a different node, that node is added as a cascade link — letting a single room span multiple SFUs (for example across regions). The router watches the cluster through a NodeFailureTracker: when a node fails or is removed, its room assignments are cleared and its cascade links dropped, emitting the corresponding detach and drop events.

Emits CascadingRouterEvent events. Pair with an SfuBridge to apply these decisions onto a concrete media plane.

Example

const router = new CascadingRouter(cluster)
router.on(CascadingRouterEvent.RoomAssigned, (roomId, node) => {
  console.log(`${roomId} -> ${node.id}`)
})

const primary = router.attachRoom('room-1', 'us-east')
// A second attach that resolves elsewhere creates a cascade link:
router.attachRoom('room-1', 'eu-west')

router.detachRoom('room-1')

Remarks

Call CascadingRouter.dispose to detach from cluster events when the router is no longer needed.

Hierarchy (View Summary)

EventEmitter<CascadingRouterEvents>
- CascadingRouter

Index

Constructors

constructor

new CascadingRouter(
cluster: SfuCluster,
options?: CascadingRouterOptions,
): CascadingRouter
Parameters
- cluster: SfuCluster
  Cluster whose nodes are assigned to rooms and watched for failures.
- options: CascadingRouterOptions = {}
  Optional logging configuration.
Returns CascadingRouter
Overrides EventEmitter.constructor
- Defined in packages/sfu/src/CascadingRouter.ts:60

Accessors

assignmentCount

get assignmentCount(): number
Number of rooms with a primary node assignment.

Returns number
- Defined in packages/sfu/src/CascadingRouter.ts:108

Methods

attachRoom

attachRoom(roomId: string, preferredRegion?: string): SfuNode
Attach a room to an SFU node, or extend it with a cascade link.

On first attach the room is assigned a primary node and CascadingRouterEvent.RoomAssigned is emitted. On subsequent attaches that resolve to a different node, that node is added as a cascade link and CascadingRouterEvent.CascadeCreated is emitted (once per distinct node). Attaches that resolve to an already-linked node are no-ops.
Parameters
- roomId: string
  Identifier of the room to attach.
- OptionalpreferredRegion: string
  Optional region hint passed to the placement strategy.
Returns SfuNode
The node selected for this attach (primary on first call, cascade target otherwise).

Throws
NoAvailableNodeError when the cluster has no active node to assign.
- Defined in packages/sfu/src/CascadingRouter.ts:126

detachRoom

detachRoom(roomId: string): boolean
Detach a room from the SFU entirely, releasing its primary node and every cascade link. Emits CascadingRouterEvent.RoomDetached.
Parameters
- roomId: string
  Identifier of the room to detach.
Returns boolean
true if the room was attached, false otherwise.
- Defined in packages/sfu/src/CascadingRouter.ts:167

dispose

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

Returns void
- Defined in packages/sfu/src/CascadingRouter.ts:103

emit

emit<K extends keyof CascadingRouterEvents>(
event: K,
...args: CascadingRouterEvents[K],
): boolean
Synchronously invokes every listener registered for event, in registration order.
Type Parameters
- K extends keyof CascadingRouterEvents
Parameters
- event: K
  The event name to emit.
- ...args: CascadingRouterEvents[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

getAssignment

getAssignment(roomId: string): SfuNode | undefined
Get the primary node currently assigned to a room.
Parameters
- roomId: string
  Identifier of the room.
Returns SfuNode | undefined
The primary node, or undefined if the room is not attached.
- Defined in packages/sfu/src/CascadingRouter.ts:186

getCascadeNodes

getCascadeNodes(roomId: string): SfuNode[]
Get the cascade nodes (beyond the primary) currently serving a room.
Parameters
- roomId: string
  Identifier of the room.
Returns SfuNode[]
A copy of the room's cascade node list (empty if none).
- Defined in packages/sfu/src/CascadingRouter.ts:196

listenerCount

listenerCount<K extends keyof CascadingRouterEvents>(event: K): number
Returns the number of listeners currently registered for event.
Type Parameters
- K extends keyof CascadingRouterEvents
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 CascadingRouterEvents>(
event: K,
listener: (...args: CascadingRouterEvents[K]) => void,
): this
Removes a previously registered listener for event.
Type Parameters
- K extends keyof CascadingRouterEvents
Parameters
- event: K
  The event name the listener was registered for.
- listener: (...args: CascadingRouterEvents[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 CascadingRouterEvents>(
event: K,
listener: (...args: CascadingRouterEvents[K]) => void,
): this
Registers a listener that is invoked every time event is emitted.
Type Parameters
- K extends keyof CascadingRouterEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: CascadingRouterEvents[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 CascadingRouterEvents>(
event: K,
listener: (...args: CascadingRouterEvents[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 CascadingRouterEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: CascadingRouterEvents[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 CascadingRouterEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof CascadingRouterEvents
  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 CascadingRouter

Example

Remarks

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns CascadingRouter

Accessors

assignmentCount

Returns number

Methods

attachRoom

Parameters

Returns SfuNode

Throws

detachRoom

Parameters

Returns boolean

dispose

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

getAssignment

Parameters

Returns SfuNode | undefined

getCascadeNodes

Parameters

Returns SfuNode[]

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