Scale & Sticky Sessions

← Back to Architecture Reference

Three things matter to a client: sticky routing, capacity handling, and what survives a reconnect.

Sticky routing: stickyId

Send the same stickyId on every socket connection, and do not rotate it mid-session.

• The SDK generates a stickyId once per session (16 random characters, or your own value via the stickyId option). It does not change it on each connect().
• It goes out as a socket query param (query.stickyId), so it goes out on every socket connection the SDK opens. The SDK uses the WebSocket transport only.
• Read it with getStickyId().
• It is kept for the whole session, including a cold reconnect. A rebuilt socket carries the same stickyId.
• A new KalturaAvatarSession gets a new stickyId.

The STV video channel needs no stickiness. It is a plain WHEP stream, independent of the control socket.

Capacity & the queue (throwToNoAgent / throwToExceededTier)

The number of live avatars is limited. There are two "full" signals:

After either signal the server closes the socket. To retry, call connect() again, or wait first with waitForCapacity().

All capacity codes are KalturaError values. status is an SDK number, not an HTTP status.

During connect():

• The SDK sends stvNewSession at once and also polls checkAvailability on the same socket. The poll never disconnects, so stickiness is kept.
• Every availabilityResult is re-emitted as capacityChanged { available, details }.
• If available is false, the SDK polls again after a delay. The delays are [30s, 45s, 60s, 90s, 120s, 180s, 240s, 300s, 360s] with ±15% jitter. After the last one it keeps using 360s.
• The wait shares the 30 s overall connect deadline. It is not paused while queued, so a long wait can end in a timeout error.

Waiting longer, before connect(): waitForCapacity({ maxWaitMs, pollIntervalMs }).

It opens its own light socket, uses no slot, and resolves { available: true, details? } as soon as a slot is free. It also emits capacityChanged on each reply. See Architecture Reference · Connection and Handshake.

What survives a reconnect

Only the conversation thread resumes across sessions, via threadId. The recovery layers are in Architecture Reference · Resilience and Failure Handling.

Slot data

capacityChanged.details is an optional, informational object. The SDK passes it through and does not read it.

For what a custom (no-Kaltura-lib) client must implement to work with this model, see ARCHITECTURE-RECIPE.md's "Implications for a Custom Client".

Related docs