Class SfuCluster

Manages a set of SfuNode instances and selects nodes for rooms via a pluggable PlacementStrategy.

The cluster can optionally reconcile its membership against an external Membership source and run periodic health checks that mark failing nodes as failed and trigger a rebalance. Placement always considers only active nodes — those that are neither failed nor draining.

Emits SfuClusterEvent events.

Example

const cluster = new SfuCluster({
  placementStrategy: new LeastLoadedStrategy(),
  healthCheck: {
    intervalMs: 10_000,
    onCheck: async (id) => probe(id),
  },
  onRebalance: (nodeId, reason) => migrateRooms(nodeId, reason),
})

cluster.addNode(new SfuNode('sfu-eu-1', 'eu'))
cluster.addNode(new SfuNode('sfu-eu-2', 'eu'))
cluster.startHealthChecks()

const node = cluster.assignNode('eu', 'room-42')

Remarks

Call SfuCluster.dispose when the cluster is no longer needed to stop membership reconciliation and health checks.

Hierarchy (View Summary)

EventEmitter<SfuClusterEvents>
- SfuCluster

Index

Constructors

constructor

new SfuCluster(options?: SfuClusterOptions): SfuCluster
Parameters
- options: SfuClusterOptions = {}
  Placement, membership, health-check, and logging configuration. When a SfuClusterOptions.membership source is supplied, membership reconciliation starts immediately.
Returns SfuCluster
Overrides EventEmitter.constructor
- Defined in packages/sfu/src/SfuCluster.ts:67

Accessors

nodes

get nodes(): SfuNode[]
All nodes currently registered with the cluster, regardless of state.

Returns SfuNode[]
- Defined in packages/sfu/src/SfuCluster.ts:99

Methods

addNode

addNode(node: SfuNode): void
Register a node with the cluster and begin listening for its overload events. Emits SfuClusterEvent.NodeAdded.
Parameters
- node: SfuNode
  The node to add. Re-adding an existing id replaces its entry.
Returns void
- Defined in packages/sfu/src/SfuCluster.ts:124

assignNode

assignNode(region?: string, key?: string): SfuNode | undefined
Select an active node for a room using the configured placement strategy.
Parameters
- Optionalregion: string
  Optional preferred region for region-affinity placement.
- Optionalkey: string
  Optional routing key (for example a room id) for deterministic strategies.
Returns SfuNode | undefined
The chosen node, or undefined when no active node is available.
- Defined in packages/sfu/src/SfuCluster.ts:166

dispose

dispose(): void
Release cluster resources: stop membership reconciliation and health checks. Does not remove nodes or emit membership events.

Returns void
- Defined in packages/sfu/src/SfuCluster.ts:92

emit

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

getActiveNodes

getActiveNodes(): SfuNode[]
Nodes eligible to serve traffic: those that are neither failed nor draining.

Returns SfuNode[]
The active subset of SfuCluster.nodes.
- Defined in packages/sfu/src/SfuCluster.ts:110

listenerCount

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

rebalance

rebalance(): void
Invoke the SfuClusterOptions.onRebalance callback for every node that is currently draining or failed, so the host can migrate their rooms.

Emits SfuClusterEvent.Overloaded if at least one such node was found. Called automatically when a health check fails; may also be called manually.

Returns void
- Defined in packages/sfu/src/SfuCluster.ts:240

removeAllListeners

removeAllListeners(event?: keyof SfuClusterEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof SfuClusterEvents
  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

removeNode

removeNode(id: string): boolean
Remove a node from the cluster and detach its overload listener. Emits SfuClusterEvent.NodeRemoved when a node was removed.
Parameters
- id: string
  Identifier of the node to remove.
Returns boolean
true if a node was removed, false if no node had that id.
- Defined in packages/sfu/src/SfuCluster.ts:144

startHealthChecks

startHealthChecks(): void
Start periodic health checks.

No-op unless a SfuClusterOptions.healthCheck onCheck probe was configured. Each sweep probes every node; a node that fails is marked failed, surfaces an SfuClusterEvent.Error, and triggers SfuCluster.rebalance. A previously failed node that passes is marked recovered.

Returns void
- Defined in packages/sfu/src/SfuCluster.ts:179

stopHealthChecks

stopHealthChecks(): void
Stop periodic health checks if they are running.

Returns void
- Defined in packages/sfu/src/SfuCluster.ts:196

Class SfuCluster

Example

Remarks

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns SfuCluster

Accessors

nodes

Returns SfuNode[]

Methods

addNode

Parameters

Returns void

assignNode

Parameters

Returns SfuNode | undefined

dispose

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

getActiveNodes

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

rebalance

Returns void

removeAllListeners

Parameters

Returns this

removeNode

Parameters

Returns boolean

startHealthChecks

Returns void

stopHealthChecks

Returns void

Settings

On This Page