import { ClientInfo_Capability, DataPacket, DataStream_Chunk, DataStream_Header, DataStream_TextHeader, DataStream_Trailer, DisconnectReason, Encryption_Type, JoinResponse, LeaveRequest, LeaveRequest_Action, ParticipantInfo, ParticipantInfo_State, StreamState as ProtoStreamState, StreamStateUpdate, SubscriptionError, SubscriptionResponse, TrackInfo, TrackSource, TrackType, Transcription, TranscriptionSegment as TranscriptionSegmentModel, } from '@livekit/protocol'; import v8 from 'node:v8'; import { runInNewContext } from 'node:vm'; import { afterEach, describe, expect, it, vi } from 'vitest'; import { SignalConnectionState, type SignalOptions } from '../api/SignalClient'; import MockMediaStream from '../test/MockMediaStream'; import MockMediaStreamTrack from '../test/MockMediaStreamTrack'; import { stubMissingDeflateRawSupport } from '../test/compressionStreamStubs'; import { subscribeToEvents } from '../utils/subscribeToEvents'; import { BackOffStrategy } from './BackOffStrategy'; import RTCEngine from './RTCEngine'; import { RegionUrlProvider } from './RegionUrlProvider'; import { ConnectionState, Room, type RoomEventCallbacks } from './Room'; import { dataStreams } from './data-stream/extension'; import { roomConnectOptionDefaults, roomOptionDefaults } from './defaults'; import { ConnectionError, ConnectionErrorReason } from './errors'; import { EngineEvent, ParticipantEvent, RoomEvent, TrackEvent } from './events'; import RemoteParticipant from './participant/RemoteParticipant'; import RemoteTrackPublication from './track/RemoteTrackPublication'; import RemoteVideoTrack from './track/RemoteVideoTrack'; import { Track } from './track/Track'; import { Future } from './utils'; describe('Active device switch', () => { it('updates devices correctly', async () => { const room = new Room(); await room.switchActiveDevice('audioinput', 'test'); expect(room.getActiveDevice('audioinput')).toBe('test'); }); it('updates devices with exact constraint', async () => { const room = new Room(); await room.switchActiveDevice('audioinput', 'test', true); expect(room.getActiveDevice('audioinput')).toBe('test'); }); it('emits changed event', async () => { const room = new Room(); let kind: MediaDeviceKind | undefined; let deviceId: string | undefined; const deviceChangeHandler = (_kind: MediaDeviceKind, _deviceId: string) => { kind = _kind; deviceId = _deviceId; }; room.on(RoomEvent.ActiveDeviceChanged, deviceChangeHandler); await room.switchActiveDevice('audioinput', 'test', true); expect(deviceId).toBe('test'); expect(kind).toBe('audioinput'); }); describe('audiooutput with webAudioMix', () => { function roomWithMixedAudioContext(setSinkId: (deviceId: string) => Promise) { const room = new Room({ webAudioMix: true }); (room as unknown as { audioContext: { setSinkId: typeof setSinkId } }).audioContext = { setSinkId, }; return room; } it('waits for the audio context to finish routing before confirming the switch', async () => { const route = new Future(); const room = roomWithMixedAudioContext(() => route.promise); const deviceChanged = vi.fn(); room.on(RoomEvent.ActiveDeviceChanged, deviceChanged); let settled = false; const switchPromise = room.switchActiveDevice('audiooutput', 'speaker').then(() => { settled = true; }); await new Promise((resolve) => setTimeout(resolve, 0)); expect(settled).toBe(false); expect(deviceChanged).not.toHaveBeenCalled(); route.resolve?.(); await switchPromise; expect(deviceChanged).toHaveBeenCalledWith('audiooutput', 'speaker'); expect(room.getActiveDevice('audiooutput')).toBe('speaker'); }); it('rejects and keeps the previous output when the audio context fails to route', async () => { const room = roomWithMixedAudioContext(async (deviceId) => { if (deviceId === 'broken') { throw new Error('setSinkId failed'); } }); await room.switchActiveDevice('audiooutput', 'speaker'); const deviceChanged = vi.fn(); room.on(RoomEvent.ActiveDeviceChanged, deviceChanged); await expect(room.switchActiveDevice('audiooutput', 'broken')).rejects.toThrow( 'setSinkId failed', ); expect(deviceChanged).not.toHaveBeenCalled(); expect(room.getActiveDevice('audiooutput')).toBe('speaker'); expect(room.options.audioOutput?.deviceId).toBe('speaker'); }); }); }); describe('Room signaling options', () => { /** Drives `connectSignal` with E2EE enabled against a stub engine, returning the `join` mock. */ async function connectSignalWithE2EE(room: Room) { const join = vi.fn().mockResolvedValue({ joinResponse: new JoinResponse({ room: { name: 'test-room', sid: 'room-sid' }, participant: { sid: 'participant-sid', identity: 'test-user' }, }), serverInfo: { version: '1.0.0' }, }); const engine = { join }; ( room as unknown as { slots: { e2eeManager: unknown }; connectSignal: ( url: string, token: string, engine: unknown, connectOptions: typeof roomConnectOptionDefaults, roomOptions: typeof roomOptionDefaults, abortController: AbortController, ) => Promise; } ).slots.e2eeManager = {}; await ( room as unknown as { connectSignal: ( url: string, token: string, engine: unknown, connectOptions: typeof roomConnectOptionDefaults, roomOptions: typeof roomOptionDefaults, abortController: AbortController, ) => Promise; } ).connectSignal( 'wss://test.livekit.io', 'test-token', engine, roomConnectOptionDefaults, roomOptionDefaults, new AbortController(), ); return join; } function expectCapabilities( join: ReturnType, clientInfoCapabilities: Array, ) { expect(join).toHaveBeenCalledWith( 'wss://test.livekit.io', 'test-token', expect.objectContaining({ clientInfoCapabilities, e2eeEnabled: true, }), expect.any(AbortSignal), false, ); } it('advertises packet trailer capability when E2EE can handle trailers', async () => { const join = await connectSignalWithE2EE(new Room()); expectCapabilities(join, [ ClientInfo_Capability.CAP_PACKET_TRAILER, ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW, ]); }); it('does not advertise deflate-raw compression when the runtime cannot decompress it', async () => { const restoreCompressionStreams = stubMissingDeflateRawSupport(); try { const join = await connectSignalWithE2EE(new Room()); // Otherwise peers would compress what they send us and we'd have to drop it. expectCapabilities(join, [ClientInfo_Capability.CAP_PACKET_TRAILER]); } finally { restoreCompressionStreams(); } }); }); describe('Room lifecycle', () => { afterEach(() => { vi.restoreAllMocks(); // Tear down the mocked mediaDevices so other tests see the env they // expected (happy-dom does not provide navigator.mediaDevices by default). if ((navigator as { mediaDevices?: unknown }).mediaDevices) { Object.defineProperty(navigator, 'mediaDevices', { configurable: true, value: undefined, }); } }); it('wraps the constructor-registered devicechange listener in a WeakRef so the Room is GC-eligible (#1940)', async () => { // happy-dom does not provide navigator.mediaDevices. Install a minimal // EventTarget stand-in so the constructor takes the listener-registration // branch and we can observe the registered listener. const mediaDevices = new EventTarget() as EventTarget & { addEventListener: EventTarget['addEventListener']; removeEventListener: EventTarget['removeEventListener']; }; Object.defineProperty(navigator, 'mediaDevices', { configurable: true, value: mediaDevices, }); const addSpy = vi.spyOn(mediaDevices, 'addEventListener'); const derefSpy = vi.spyOn(WeakRef.prototype, 'deref'); const cleanupRegistrySpy = Room.cleanupRegistry ? vi.spyOn(Room.cleanupRegistry, 'register') : undefined; const room = new Room(); const handleDeviceChangeSpy = vi.spyOn( room as unknown as { handleDeviceChange: (ev: Event) => void }, 'handleDeviceChange', ); // Constructor must register exactly one devicechange listener with AbortSignal teardown. const deviceChangeAdds = addSpy.mock.calls.filter(([type]) => type === 'devicechange'); expect(deviceChangeAdds).toHaveLength(1); const listener = deviceChangeAdds[0][1] as EventListener; const addOptions = deviceChangeAdds[0][2] as AddEventListenerOptions | undefined; expect(addOptions?.signal).toBeInstanceOf(AbortSignal); // FinalizationRegistry must be registered with the Room as the target so the // cleanup callback fires when the user drops their Room reference. if (Room.cleanupRegistry) { expect(cleanupRegistrySpy).toHaveBeenCalledWith(room, expect.any(AbortController)); } // While the WeakRef still derefs to the Room, the listener forwards to handleDeviceChange. listener.call(null, new Event('devicechange')); expect(handleDeviceChangeSpy).toHaveBeenCalledTimes(1); // Simulate the Room being GC'd by forcing deref to return undefined; the // listener must short-circuit instead of calling handleDeviceChange. derefSpy.mockReturnValue(undefined); listener.call(null, new Event('devicechange')); expect(handleDeviceChangeSpy).toHaveBeenCalledTimes(1); }); it('falls back to a direct devicechange listener when WeakRef/FinalizationRegistry are unavailable (#1944)', async () => { const mediaDevices = new EventTarget() as EventTarget & { addEventListener: EventTarget['addEventListener']; removeEventListener: EventTarget['removeEventListener']; }; Object.defineProperty(navigator, 'mediaDevices', { configurable: true, value: mediaDevices, }); // Simulate a legacy browser by stubbing out cleanupRegistry. const originalRegistry = Room.cleanupRegistry; Object.defineProperty(Room, 'cleanupRegistry', { configurable: true, value: false, }); try { const addSpy = vi.spyOn(mediaDevices, 'addEventListener'); const room = new Room(); const handleDeviceChange = (room as unknown as { handleDeviceChange: () => void }) .handleDeviceChange; const deviceChangeAdds = addSpy.mock.calls.filter(([type]) => type === 'devicechange'); expect(deviceChangeAdds).toHaveLength(1); // The registered listener is the bare handleDeviceChange method (no WeakRef closure). expect(deviceChangeAdds[0][1]).toBe(handleDeviceChange); } finally { Object.defineProperty(Room, 'cleanupRegistry', { configurable: true, value: originalRegistry, }); } }); it('lets a dropped Room be garbage collected (#2008)', async () => { Object.defineProperty(navigator, 'mediaDevices', { configurable: true, value: new EventTarget(), }); // A Room is retained if either the devicechange listener or the registry's held value closes // over the constructor's context, so check reachability with a real GC. v8.setFlagsFromString('--expose-gc'); const gc = runInNewContext('gc') as () => void; const roomRef = new WeakRef(new Room()); // WeakRef targets stay alive until the current job ends, so yield before each collection for (let i = 0; i < 10 && roomRef.deref(); i += 1) { await new Promise((resolve) => setTimeout(resolve, 10)); gc(); } expect(roomRef.deref()).toBeUndefined(); }); }); describe('remote track subscription', () => { it('does not replay a deferred ontrack after the subscription failed', () => { const room = new Room(); room.state = ConnectionState.Connecting; const trackSid = 'TR_h264'; const mediaTrack = { id: trackSid } as MediaStreamTrack; const stream = { id: `PA_remote|${trackSid}`, getTracks: () => [mediaTrack], } as unknown as MediaStream; const receiver = {} as RTCRtpReceiver; room.engine.emit(EngineEvent.MediaTrackAdded, mediaTrack, stream, receiver); const replay = vi.spyOn( room as unknown as { onTrackAdded( mediaTrack: MediaStreamTrack, stream: MediaStream, receiver: RTCRtpReceiver, ): void; }, 'onTrackAdded', ); room.engine.emit( EngineEvent.SubscriptionError, new SubscriptionResponse({ trackSid, err: SubscriptionError.SE_CODEC_UNSUPPORTED, }), ); room.state = ConnectionState.Connected; room.emit(RoomEvent.Connected); expect(replay).not.toHaveBeenCalled(); }); it('does not subscribe a deferred track the server stopped sending before the room connected', () => { const room = new Room(); room.state = ConnectionState.Connecting; room.engine.emit(EngineEvent.ParticipantUpdate, [ new ParticipantInfo({ sid: 'PA_remote', identity: 'remote', state: ParticipantInfo_State.ACTIVE, tracks: [new TrackInfo({ sid: 'TR_video', type: TrackType.VIDEO })], }), ]); const trackSubscribed = vi.fn(); room.on(RoomEvent.TrackSubscribed, trackSubscribed); // the track arrives while the room connects, so the room defers it const mediaTrack = new MockMediaStreamTrack(); const stream = new MockMediaStream('PA_remote|TR_video', [mediaTrack]); room.engine.emit(EngineEvent.MediaTrackAdded, mediaTrack, stream, {} as RTCRtpReceiver); // the subscription fails and the next answer stops the track, so the browser removes it stream.removeTrack(mediaTrack); room.state = ConnectionState.Connected; room.emit(RoomEvent.Connected); expect(trackSubscribed).not.toHaveBeenCalled(); }); it('subscribes a deferred track once the room connects', () => { const room = new Room(); room.state = ConnectionState.Connecting; room.engine.emit(EngineEvent.ParticipantUpdate, [ new ParticipantInfo({ sid: 'PA_remote', identity: 'remote', state: ParticipantInfo_State.ACTIVE, tracks: [new TrackInfo({ sid: 'TR_video', type: TrackType.VIDEO })], }), ]); const trackSubscribed = vi.fn(); room.on(RoomEvent.TrackSubscribed, trackSubscribed); // the track arrives while the room connects, so the room defers it const mediaTrack = new MockMediaStreamTrack(); const stream = new MockMediaStream('PA_remote|TR_video', [mediaTrack]); room.engine.emit(EngineEvent.MediaTrackAdded, mediaTrack, stream, {} as RTCRtpReceiver); room.state = ConnectionState.Connected; room.emit(RoomEvent.Connected); expect(trackSubscribed).toHaveBeenCalledOnce(); }); }); describe('stream state updates', () => { const participantSid = 'PA_remote'; const participantIdentity = 'remote-user'; const trackSid = 'TR_video'; function setupSubscribedTrack() { const room = new Room(); room.state = ConnectionState.Connected; const participant = new RemoteParticipant( room.engine.client, participantSid, participantIdentity, ); const publication = new RemoteTrackPublication( Track.Kind.Video, new TrackInfo({ sid: trackSid, type: TrackType.VIDEO, name: 'camera' }), true, ); publication.setTrack( new RemoteVideoTrack(new MockMediaStreamTrack(), trackSid, undefined as never, {}), ); participant.trackPublications.set(trackSid, publication); ( room as unknown as { remoteParticipants: Map } ).remoteParticipants.set(participantIdentity, participant); (room as unknown as { sidToIdentity: Map }).sidToIdentity.set( participantSid, participantIdentity, ); return { room, participant, publication }; } function pushStreamState(room: Room, state: ProtoStreamState) { ( room as unknown as { handleStreamStateUpdate: (update: StreamStateUpdate) => void } ).handleStreamStateUpdate( new StreamStateUpdate({ streamStates: [{ participantSid, trackSid, state }], }), ); } it('emits TrackStreamStateChanged when the SFU pauses a subscribed track', () => { const { room, participant, publication } = setupSubscribedTrack(); const roomEvents = vi.fn(); const participantEvents = vi.fn(); room.on(RoomEvent.TrackStreamStateChanged, roomEvents); participant.on(ParticipantEvent.TrackStreamStateChanged, participantEvents); pushStreamState(room, ProtoStreamState.PAUSED); expect(publication.track?.streamState).toBe(Track.StreamState.Paused); expect(roomEvents).toHaveBeenCalledWith(publication, Track.StreamState.Paused, participant); expect(participantEvents).toHaveBeenCalledWith(publication, Track.StreamState.Paused); }); it('does not emit TrackStreamStateChanged when the state is unchanged', () => { const { room, participant } = setupSubscribedTrack(); const roomEvents = vi.fn(); const participantEvents = vi.fn(); room.on(RoomEvent.TrackStreamStateChanged, roomEvents); participant.on(ParticipantEvent.TrackStreamStateChanged, participantEvents); // The track starts Active; a redundant ACTIVE update must stay silent. pushStreamState(room, ProtoStreamState.ACTIVE); expect(roomEvents).not.toHaveBeenCalled(); expect(participantEvents).not.toHaveBeenCalled(); }); }); describe('full reconnect', () => { function roomIn(state: ConnectionState) { const room = new Room(); room.state = state; if (state === ConnectionState.Connecting) { // connect() is pending (room as unknown as { connectFuture: Future }).connectFuture = new Future(); } const events: string[] = []; room .on(RoomEvent.SignalReconnecting, () => events.push(RoomEvent.SignalReconnecting)) .on(RoomEvent.Reconnecting, () => events.push(RoomEvent.Reconnecting)) .on(RoomEvent.Reconnected, () => events.push(RoomEvent.Reconnected)) .on(RoomEvent.ConnectionStateChanged, (s) => events.push(`state:${s}`)); return { room, events }; } function restartFrom(state: ConnectionState, { resumeFirst = false } = {}) { const { room, events } = roomIn(state); vi.spyOn(room.engine, 'waitForRestarted').mockResolvedValue(true); if (resumeFirst) { // a rejected resume escalates to a full reconnect, as in a server CONNECTION_TIMEOUT leave room.engine.emit(EngineEvent.Resuming); } room.engine.emit(EngineEvent.Restarting); room.engine.emit( EngineEvent.SignalRestarted, new JoinResponse({ participant: { sid: 'PA_local', identity: 'local' } }), new AbortController().signal, ); return { room, events }; } const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); it('leaves an initial connection to connect() instead of reporting a reconnect', async () => { const { room, events } = restartFrom(ConnectionState.Connecting); await flush(); expect(events).toEqual([]); expect(room.state).toBe(ConnectionState.Connecting); }); it('leaves an initial connection to connect() when a resume preceded the restart', async () => { const { room, events } = restartFrom(ConnectionState.Connecting, { resumeFirst: true }); await flush(); expect(events).toEqual([]); expect(room.state).toBe(ConnectionState.Connecting); }); it('leaves an initial connection to connect() when a resume succeeds', () => { const { room, events } = roomIn(ConnectionState.Connecting); room.engine.emit(EngineEvent.Resuming); room.engine.emit(EngineEvent.Resumed); expect(events).toEqual([]); expect(room.state).toBe(ConnectionState.Connecting); }); it('stays Connecting when the browser goes offline inside connect()', () => { const { room, events } = roomIn(ConnectionState.Connecting); room.engine.emit(EngineEvent.Offline); expect(events).toEqual([]); expect(room.state).toBe(ConnectionState.Connecting); }); it('reports a reconnect of an established session', async () => { const { room, events } = restartFrom(ConnectionState.Connected); await flush(); expect(events).toEqual([ `state:${ConnectionState.Reconnecting}`, RoomEvent.Reconnecting, `state:${ConnectionState.Connected}`, RoomEvent.Reconnected, ]); expect(room.state).toBe(ConnectionState.Connected); }); }); describe('audio context ownership', () => { class StubAudioContext { state: AudioContextState = 'running'; closed = false; async close() { this.closed = true; this.state = 'closed'; } async resume() { this.state = 'running'; } } const created: StubAudioContext[] = []; function stubAudioContext() { created.length = 0; vi.stubGlobal( 'AudioContext', class extends StubAudioContext { constructor() { super(); created.push(this); } }, ); } /** `acquireAudioContext` and `releaseAudioContext` are private */ function internals(room: Room) { return room as unknown as { acquireAudioContext: () => Promise; releaseAudioContext: (retained?: unknown[]) => Promise; audioContext?: StubAudioContext; ownsAudioContext: boolean; localParticipant: { setAudioContext: (ctx: AudioContext | undefined) => Promise }; }; } afterEach(() => { vi.unstubAllGlobals(); vi.restoreAllMocks(); }); it('closes a context it created for a webAudioMix object that supplies none', async () => { stubAudioContext(); const room = internals(new Room({ webAudioMix: {} })); await room.acquireAudioContext(); expect(created).toHaveLength(1); expect(room.ownsAudioContext).toBe(true); expect(room.audioContext).toBe(created[0]); await room.releaseAudioContext(); expect(created[0].closed).toBe(true); expect(room.audioContext).toBeUndefined(); }); it('leaves a supplied context open', async () => { stubAudioContext(); const provided = new StubAudioContext(); const room = internals( new Room({ webAudioMix: { audioContext: provided as unknown as AudioContext } }), ); await room.acquireAudioContext(); expect(room.ownsAudioContext).toBe(false); expect(created).toHaveLength(0); await room.releaseAudioContext(); expect(provided.closed).toBe(false); }); it('closes the context even when a retained track fails to detach', async () => { stubAudioContext(); const room = internals(new Room({ webAudioMix: {} })); await room.acquireAudioContext(); const retained = { setAudioContext: () => Promise.reject(new Error('detach failed')) }; await room.releaseAudioContext([retained]); expect(created[0].closed).toBe(true); }); it('does not build a context for an acquire queued behind a release', async () => { stubAudioContext(); const room = internals(new Room({ webAudioMix: {} })); await room.acquireAudioContext(); expect(created).toHaveLength(1); // `startAudio` reads `audioContextReleased` before it waits on the mutex, so its acquire can // already be queued behind a disconnect by the time the flag is set const released = room.releaseAudioContext(); const acquired = room.acquireAudioContext(); await Promise.all([released, acquired]); expect(created).toHaveLength(1); expect(created[0].closed).toBe(true); expect(room.audioContext).toBeUndefined(); }); it('closes the outgoing context even when a participant fails to move off it', async () => { stubAudioContext(); const room = internals(new Room({ webAudioMix: {} })); await room.acquireAudioContext(); vi.spyOn(room.localParticipant, 'setAudioContext').mockRejectedValue(new Error('move failed')); await room.releaseAudioContext(); expect(created[0].closed).toBe(true); }); }); describe('connection attempt racing disconnect (#2150)', () => { afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); }); type AttemptConnection = ( url: string, token: string, opts: undefined, abortController: AbortController, ) => Promise; /** Starts a connection attempt whose signal join stays pending until `failJoin` is called. */ async function startAttempt(room: Room) { let failJoin!: () => void; vi.spyOn(RTCEngine.prototype, 'join').mockImplementationOnce( () => new Promise((_, reject) => { failJoin = () => reject(ConnectionError.cancelled('Connection aborted')); }), ); const engine = room.engine; const abortController = new AbortController(); (room as unknown as { abortController: AbortController }).abortController = abortController; room.state = ConnectionState.Connecting; const attempt = (room as unknown as { attemptConnection: AttemptConnection }).attemptConnection( 'ws://localhost:7880', 'token', undefined, abortController, ); await vi.waitFor(() => expect(failJoin).toBeDefined()); return { attempt, engine, failJoin }; } it('rejects as cancelled when disconnect() clears the engine mid-join', async () => { const room = new Room(); const { attempt, engine, failJoin } = await startAttempt(room); const close = vi.spyOn(engine, 'close'); await room.disconnect(); expect(room.engine).toBeUndefined(); failJoin(); await expect(attempt).rejects.toMatchObject({ reason: ConnectionErrorReason.Cancelled }); expect(close).toHaveBeenCalled(); }); it('leaves a newer connect() alone when a stale join fails', async () => { // connect() bails out unless the runtime looks like it supports WebRTC vi.stubGlobal( 'RTCPeerConnection', class { addTrack() {} }, ); let failStaleJoin!: () => void; vi.spyOn(RTCEngine.prototype, 'join') .mockImplementationOnce( () => new Promise((_, reject) => { failStaleJoin = () => reject(ConnectionError.cancelled('Connection aborted')); }), ) .mockImplementationOnce(() => new Promise(() => {})); const room = new Room(); const stale = room.connect('ws://localhost:7880', 'token'); await vi.waitFor(() => expect(failStaleJoin).toBeDefined()); await room.disconnect(); await expect(stale).rejects.toMatchObject({ reason: ConnectionErrorReason.Cancelled }); room.connect('ws://localhost:7880', 'token').catch(() => {}); await vi.waitFor(() => expect(RTCEngine.prototype.join).toHaveBeenCalledTimes(2)); const newerEngine = room.engine; const close = vi.spyOn(newerEngine, 'close'); const disconnected = vi.fn(); room.on(RoomEvent.Disconnected, disconnected); failStaleJoin(); await new Promise((resolve) => setTimeout(resolve, 0)); expect(room.state).toBe(ConnectionState.Connecting); expect(room.engine).toBe(newerEngine); expect(close).not.toHaveBeenCalled(); expect(disconnected).not.toHaveBeenCalled(); }); }); describe('full reconnect failing over to a second region', () => { const join = (metadata: string) => new JoinResponse({ room: { sid: 'RM_test', name: 'test', metadata }, participant: { sid: 'PA_local', identity: 'local' }, }); const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); /** Drives the room as the engine does: each region attempt has a signal the next one aborts. */ function restarts(room: Room) { let attempt: AbortController | undefined; return { restarting() { attempt?.abort(); attempt = new AbortController(); room.engine.emit(EngineEvent.Restarting); }, signalRestarted(metadata: string) { room.engine.emit(EngineEvent.SignalRestarted, join(metadata), attempt!.signal); }, }; } function setup() { const room = new Room(); room.state = ConnectionState.Connected; room.engine.emit(EngineEvent.RoomUpdate, join('old').room!); const republish = vi .spyOn(room.localParticipant, 'republishAllTracks') .mockImplementation(async () => {}); const roomEvents = subscribeToEvents(room, [ RoomEvent.Reconnected, RoomEvent.RoomMetadataChanged, ]); return { room, engine: restarts(room), republish, roomEvents }; } /** Holds the next republish open until the returned function is called. */ function holdNextRepublish(republish: ReturnType['republish']) { let finish!: () => void; republish.mockImplementationOnce(() => new Promise((resolve) => (finish = resolve))); return () => finish(); } it('reports the recovery once, with the changes the connected region reports', async () => { const { room, engine, roomEvents } = setup(); // the first region joins, then its peer connection fails engine.restarting(); engine.signalRestarted('new'); await flush(); // the second region joins and connects engine.restarting(); engine.signalRestarted('new'); await flush(); room.engine.emit(EngineEvent.Restarted); await flush(); expect(room.state).toBe(ConnectionState.Connected); await roomEvents.waitFor(RoomEvent.Reconnected); expect(roomEvents.areThereBufferedEvents(RoomEvent.Reconnected)).toBe(false); expect(await roomEvents.waitFor(RoomEvent.RoomMetadataChanged)).toBe('new'); expect(roomEvents.areThereBufferedEvents(RoomEvent.RoomMetadataChanged)).toBe(false); await room.disconnect(); }); it('reports the recovery once when the failed region republishes past its failure', async () => { const { room, engine, republish, roomEvents } = setup(); const finishFirstRepublish = holdNextRepublish(republish); engine.restarting(); engine.signalRestarted('new'); await flush(); engine.restarting(); finishFirstRepublish(); await flush(); engine.signalRestarted('new'); await flush(); expect(roomEvents.areThereBufferedEvents(RoomEvent.Reconnected)).toBe(false); room.engine.emit(EngineEvent.Restarted); await flush(); await roomEvents.waitFor(RoomEvent.Reconnected); expect(roomEvents.areThereBufferedEvents(RoomEvent.Reconnected)).toBe(false); await room.disconnect(); }); it('leaves a restart alone that began while an earlier one was still republishing', async () => { const { room, engine, republish, roomEvents } = setup(); const finishFirstRepublish = holdNextRepublish(republish); // the engine reports a pending reconnect for as long as an attempt runs let attemptRunning = true; vi.spyOn(room.engine, 'pendingReconnect', 'get').mockImplementation(() => attemptRunning); // the first restart connects while its republish is still running engine.restarting(); engine.signalRestarted('a'); await flush(); room.engine.emit(EngineEvent.Restarted); attemptRunning = false; await flush(); // a second restart begins before that republish ends attemptRunning = true; engine.restarting(); finishFirstRepublish(); await flush(); expect(room.state).toBe(ConnectionState.Reconnecting); expect(roomEvents.areThereBufferedEvents(RoomEvent.Reconnected)).toBe(false); // the second restart fails over from region c to region d engine.signalRestarted('c'); await flush(); engine.restarting(); engine.signalRestarted('c'); await flush(); room.engine.emit(EngineEvent.Restarted); attemptRunning = false; await flush(); expect(room.state).toBe(ConnectionState.Connected); await roomEvents.waitFor(RoomEvent.Reconnected); expect(roomEvents.areThereBufferedEvents(RoomEvent.Reconnected)).toBe(false); expect(await roomEvents.waitFor(RoomEvent.RoomMetadataChanged)).toBe('c'); expect(roomEvents.areThereBufferedEvents(RoomEvent.RoomMetadataChanged)).toBe(false); await room.disconnect(); }); }); describe('server leave during connect()', () => { afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); BackOffStrategy.getInstance().resetAll(); }); /** * Starts `connect()` against a LiveKit Cloud URL whose signal join succeeds but whose transports * never connect: the attempt only ends through its abort signal, or once the test lets the peer * connection timeout elapse (after which every transport wait times out right away). */ async function connectUntilTransportWait() { // connect() bails out unless the runtime looks like it supports WebRTC vi.stubGlobal( 'RTCPeerConnection', class { addTrack() {} }, ); vi.spyOn(RegionUrlProvider.prototype, 'fetchRegionSettings').mockReturnValue( new Promise(() => {}), ); const getNextBestRegionUrl = vi .spyOn(RegionUrlProvider.prototype, 'getNextBestRegionUrl') .mockResolvedValueOnce('wss://test-project-other-region.livekit.cloud') .mockResolvedValue(null); const join = vi.spyOn(RTCEngine.prototype, 'join').mockImplementation(async function ( this: RTCEngine, ) { // the real join wires the signal callbacks, among them the server leave handler (this as unknown as { setupSignalClientCallbacks: () => void }).setupSignalClientCallbacks(); return { joinResponse: new JoinResponse({ room: { name: 'test-room', sid: 'room-sid' }, participant: { sid: 'participant-sid', identity: 'test-user' }, }), serverInfo: { version: '1.0.0' }, }; }); let timedOut = false; const pendingWaits: Array<() => void> = []; vi.spyOn(RTCEngine.prototype, 'waitForPCInitialConnection').mockImplementation( (_timeout, abortController) => new Promise((_, reject) => { const timeOut = () => reject(ConnectionError.internal('could not establish pc connection')); if (timedOut) { timeOut(); return; } abortController?.signal.addEventListener('abort', () => reject(ConnectionError.cancelled('room connection has been cancelled')), ); pendingWaits.push(timeOut); }), ); const room = new Room(); const outcome = room.connect('wss://test-project.livekit.cloud', 'token').then( () => 'connected', (error: unknown) => error, ); await vi.waitFor(() => expect(pendingWaits).toHaveLength(1)); const elapsePeerConnectionTimeout = () => { timedOut = true; pendingWaits.forEach((timeOut) => timeOut()); }; return { room, outcome, join, getNextBestRegionUrl, elapsePeerConnectionTimeout }; } /** What the signal client does with a server `leave` (another session took this identity). */ function receiveDuplicateIdentityLeave(room: Room) { room.engine.client.onLeave?.( new LeaveRequest({ action: LeaveRequest_Action.DISCONNECT, reason: DisconnectReason.DUPLICATE_IDENTITY, }), ); } it('cancels the attempt instead of rejoining another region with the same token', async () => { const { room, outcome, join, getNextBestRegionUrl, elapsePeerConnectionTimeout } = await connectUntilTransportWait(); const connected = vi.fn(); room.on(RoomEvent.Connected, connected); receiveDuplicateIdentityLeave(room); expect(room.state).toBe(ConnectionState.Disconnected); elapsePeerConnectionTimeout(); const error = await outcome; expect(join).toHaveBeenCalledTimes(1); expect(getNextBestRegionUrl).not.toHaveBeenCalled(); expect(error).toMatchObject({ reason: ConnectionErrorReason.Cancelled }); expect(room.state).toBe(ConnectionState.Disconnected); expect(connected).not.toHaveBeenCalled(); }); it('leaves no attempt running when disconnect() follows the leave', async () => { const { room, outcome, join, elapsePeerConnectionTimeout } = await connectUntilTransportWait(); receiveDuplicateIdentityLeave(room); // the room already reports Disconnected, so this returns early await room.disconnect(); elapsePeerConnectionTimeout(); const error = await outcome; expect(join).toHaveBeenCalledTimes(1); expect(error).toMatchObject({ reason: ConnectionErrorReason.Cancelled }); }); }); describe('events during a full reconnect (#2183)', () => { afterEach(() => { vi.restoreAllMocks(); }); interface EngineInternals { _isClosed: boolean; url: string; token: string; signalOpts: SignalOptions; pcState: number; configure: () => Promise; waitForPCReconnected: () => Promise; } /** * Starts a full reconnect on a connected room whose engine still reports its (old) peer * connection as connected, as after a signal-only drop. The restart parks in * `waitForPCReconnected` until `finishPCReconnect` is called. */ async function startFullReconnect() { const room = new Room({ reconnectPolicy: { nextRetryDelayInMs: () => 0 } }); room.state = ConnectionState.Connected; const engine = room.engine; const internals = engine as unknown as EngineInternals; internals._isClosed = false; internals.url = 'wss://test.livekit.io'; internals.token = 'test-token'; internals.signalOpts = { autoSubscribe: true, maxRetries: 1, websocketTimeout: 15_000 }; // PCState.Connected, left over from the session being replaced internals.pcState = 1; vi.spyOn(internals, 'configure').mockResolvedValue(); vi.spyOn(engine.client, 'sendLeave').mockResolvedValue(); vi.spyOn(engine.client, 'currentState', 'get').mockReturnValue(SignalConnectionState.CONNECTED); vi.spyOn(engine.client, 'join').mockResolvedValue( new JoinResponse({ participant: new ParticipantInfo({ sid: 'PA_local', identity: 'local' }), subscriberPrimary: true, }), ); const pcReconnecting = new Future(); const pcReconnected = new Future(); vi.spyOn(internals, 'waitForPCReconnected').mockImplementation(async () => { pcReconnecting.resolve?.(); await pcReconnected.promise; }); const restarted = new Future(); engine.once(EngineEvent.Restarted, () => restarted.resolve?.()); const events: string[] = []; room.on(RoomEvent.Reconnected, () => events.push('reconnected')); room.on(RoomEvent.ParticipantConnected, (p) => events.push(`participantConnected:${p.identity}`), ); engine.reconnect(); await pcReconnecting.promise; // let the room's SignalRestarted handler run as far as it will await new Promise((resolve) => setTimeout(resolve, 0)); const finishPCReconnect = async () => { pcReconnected.resolve?.(); await restarted.promise; await vi.waitFor(() => expect(engine.pendingReconnect).toBe(false)); }; return { room, engine, events, finishPCReconnect }; } it('does not report the room reconnected before the engine restart completes', async () => { const { room, events, finishPCReconnect } = await startFullReconnect(); expect(room.state).toBe(ConnectionState.Reconnecting); expect(events).toEqual([]); await finishPCReconnect(); expect(room.state).toBe(ConnectionState.Connected); expect(events).toEqual(['reconnected']); }); it('delivers participant events that arrive while the restart is settling', async () => { const { room, engine, events, finishPCReconnect } = await startFullReconnect(); // a remote participant (re)joins while the engine is still waiting on the transports engine.emit(EngineEvent.ParticipantUpdate, [ new ParticipantInfo({ sid: 'PA_remote', identity: 'remote', state: ParticipantInfo_State.ACTIVE, }), ]); expect(events).toEqual([]); await finishPCReconnect(); expect(events).toEqual(['reconnected', 'participantConnected:remote']); expect((room as unknown as { bufferedEvents: unknown[] }).bufferedEvents).toEqual([]); }); }); describe('participant updates for an earlier session (#2228)', () => { // PA_new joined after PA_old, so the server orders it as the newer session const joinTimes = { PA_old: { joinedAt: 1_700_000_000n, joinedAtMs: 1_700_000_000_100n }, PA_new: { joinedAt: 1_700_000_009n, joinedAtMs: 1_700_000_009_200n }, }; function setup() { const room = new Room(); const update = ( sid: keyof typeof joinTimes, state: ParticipantInfo_State, reason?: DisconnectReason, ) => ( room as unknown as { handleParticipantUpdates: (infos: ParticipantInfo[]) => void } ).handleParticipantUpdates([ new ParticipantInfo({ sid, identity: 'tutor', state, disconnectReason: reason, ...joinTimes[sid], }), ]); const disconnected: string[] = []; room.on(RoomEvent.ParticipantDisconnected, (p) => disconnected.push(p.sid)); // the data track extension unpublishes the tracks of each identity it gets without them const dataTracks = ( room as unknown as { extensionResults: Array<{ onParticipantUpdates?: (infos: ParticipantInfo[]) => void }>; } ).extensionResults.find((result) => result.onParticipantUpdates)!; const extensionUpdates = vi.spyOn(dataTracks, 'onParticipantUpdates'); const forwardedSids = () => extensionUpdates.mock.calls.flatMap(([infos]) => infos.map((info) => info.sid)); return { room, update, disconnected, forwardedSids }; } it('keeps the new session when a late DISCONNECTED arrives for the old session', () => { const { room, update, disconnected, forwardedSids } = setup(); update('PA_old', ParticipantInfo_State.ACTIVE); update('PA_old', ParticipantInfo_State.DISCONNECTED, DisconnectReason.SIGNAL_CLOSE); update('PA_new', ParticipantInfo_State.ACTIVE); update('PA_old', ParticipantInfo_State.DISCONNECTED, DisconnectReason.DUPLICATE_IDENTITY); expect(room.remoteParticipants.get('tutor')?.sid).toBe('PA_new'); expect(disconnected).toEqual(['PA_old']); expect(forwardedSids()).toEqual(['PA_old', 'PA_old', 'PA_new']); }); it('keeps the new session when the old session leaves after the new one joined', () => { const { room, update, disconnected, forwardedSids } = setup(); update('PA_old', ParticipantInfo_State.ACTIVE); update('PA_new', ParticipantInfo_State.ACTIVE); update('PA_old', ParticipantInfo_State.DISCONNECTED, DisconnectReason.DUPLICATE_IDENTITY); expect(room.remoteParticipants.get('tutor')?.sid).toBe('PA_new'); expect(disconnected).toEqual([]); expect(forwardedSids()).toEqual(['PA_old', 'PA_new']); update('PA_new', ParticipantInfo_State.DISCONNECTED, DisconnectReason.CLIENT_INITIATED); expect(room.remoteParticipants.has('tutor')).toBe(false); expect(disconnected).toEqual(['PA_new']); }); it('keeps the new session when a late ACTIVE arrives for the old session', () => { const { room, update, disconnected, forwardedSids } = setup(); update('PA_old', ParticipantInfo_State.ACTIVE); update('PA_new', ParticipantInfo_State.ACTIVE); update('PA_old', ParticipantInfo_State.ACTIVE); expect(room.remoteParticipants.get('tutor')?.sid).toBe('PA_new'); expect(disconnected).toEqual([]); expect(forwardedSids()).toEqual(['PA_old', 'PA_new']); }); it('does not resolve the old sid to the new session', () => { const { room, update } = setup(); const getBySid = (sid: string) => ( room as unknown as { getRemoteParticipantBySid: (sid: string) => unknown } ).getRemoteParticipantBySid(sid); update('PA_old', ParticipantInfo_State.ACTIVE); update('PA_new', ParticipantInfo_State.ACTIVE); expect(getBySid('PA_new')).toBe(room.remoteParticipants.get('tutor')); expect(getBySid('PA_old')).toBeUndefined(); }); it('removes the old session when the first update for the new session is DISCONNECTED', () => { const { room, update, disconnected, forwardedSids } = setup(); update('PA_old', ParticipantInfo_State.ACTIVE); update('PA_new', ParticipantInfo_State.DISCONNECTED, DisconnectReason.CLIENT_INITIATED); expect(room.remoteParticipants.has('tutor')).toBe(false); expect(disconnected).toEqual(['PA_old']); expect(forwardedSids()).toEqual(['PA_old', 'PA_new']); }); }); describe('rpc', () => { it('rejects a pending performRpc when the room disconnects', async () => { const room = new Room(); room.state = ConnectionState.Connected; vi.spyOn(room.engine, 'sendDataPacket').mockResolvedValue(undefined); const response = room.localParticipant.performRpc({ destinationIdentity: 'remote', method: 'm', payload: 'p', responseTimeout: 300_000, }); const settled = response.then( () => 'resolved', (e: Error) => e.message, ); await vi.waitFor(() => expect(room.engine.sendDataPacket).toHaveBeenCalled()); await room.disconnect(); expect(await settled).toBe('Connection closed'); }); }); describe('transcription back-conversion', () => { const agentIdentity = 'agent-1'; const trackSid = 'TR_mic'; /** A connected room with one remote participant publishing a microphone track. */ function setupRoom() { const room = new Room(); room.state = ConnectionState.Connected; ( room as unknown as { installedExtensions: Map void } }>; } ).installedExtensions .get(dataStreams.key)! .incoming.setConnected(true); const participant = new RemoteParticipant(room.engine.client, 'PA_agent', agentIdentity); const publication = new RemoteTrackPublication( Track.Kind.Audio, new TrackInfo({ sid: trackSid, type: TrackType.AUDIO, name: 'roomio_audio', source: TrackSource.MICROPHONE, }), true, ); participant.trackPublications.set(trackSid, publication); ( room as unknown as { remoteParticipants: Map } ).remoteParticipants.set(agentIdentity, participant); return { room, participant, publication }; } function pushPacket(room: Room, packet: DataPacket) { ( room as unknown as { handleDataPacket: (packet: DataPacket, encryptionType: Encryption_Type) => void; } ).handleDataPacket(packet, Encryption_Type.NONE); } /** Publishes a complete single-chunk `lk.transcription` stream from `senderIdentity`. */ function pushTranscriptionStream( room: Room, senderIdentity: string, text: string, attributes: Record, ) { const streamId = crypto.randomUUID(); pushPacket( room, new DataPacket({ participantIdentity: senderIdentity, value: { case: 'streamHeader', value: new DataStream_Header({ streamId, topic: 'lk.transcription', mimeType: 'text/plain', timestamp: 0n, attributes, contentHeader: { case: 'textHeader', value: new DataStream_TextHeader({}) }, }), }, }), ); pushPacket( room, new DataPacket({ participantIdentity: senderIdentity, value: { case: 'streamChunk', value: new DataStream_Chunk({ streamId, chunkIndex: 0n, content: new TextEncoder().encode(text), }), }, }), ); pushPacket( room, new DataPacket({ participantIdentity: senderIdentity, value: { case: 'streamTrailer', value: new DataStream_Trailer({ streamId }), }, }), ); } it('ignores legacy Transcription data packets', () => { const { room } = setupRoom(); const received: Array = []; room.on(RoomEvent.TranscriptionReceived, (segments) => received.push(segments)); pushPacket( room, new DataPacket({ participantIdentity: agentIdentity, value: { case: 'transcription', value: new Transcription({ transcribedParticipantIdentity: agentIdentity, trackId: trackSid, segments: [ new TranscriptionSegmentModel({ id: 'SG_legacy', text: 'legacy', final: true }), ], }), }, }), ); expect(received).toHaveLength(0); }); it('emits TranscriptionReceived from an lk.transcription stream', async () => { const { room, participant, publication } = setupRoom(); const roomEvents: Array<{ segments: Array<{ text: string }>; identity?: string }> = []; const trackEvents: Array> = []; room.on(RoomEvent.TranscriptionReceived, (segments, p) => roomEvents.push({ segments, identity: p?.identity }), ); publication.on(TrackEvent.TranscriptionReceived, (segments) => trackEvents.push(segments)); pushTranscriptionStream(room, agentIdentity, 'Hello world', { 'lk.segment_id': 'SG_1', 'lk.transcribed_track_id': trackSid, 'lk.transcription_final': 'true', }); await new Promise((resolve) => setTimeout(resolve, 0)); expect(roomEvents.length).toBeGreaterThan(0); expect(roomEvents[0].segments[0].text).toBe('Hello world'); expect(roomEvents[0].identity).toBe(participant.identity); expect(trackEvents.length).toBeGreaterThan(0); expect(trackEvents[0][0].text).toBe('Hello world'); }); it("resolves the publication from the speaker's mic track when the attribute is absent", async () => { const { room, publication } = setupRoom(); const trackEvents: Array> = []; publication.on(TrackEvent.TranscriptionReceived, (segments) => trackEvents.push(segments)); pushTranscriptionStream(room, agentIdentity, 'No track attribute', { 'lk.segment_id': 'SG_1', 'lk.transcription_final': 'true', }); await new Promise((resolve) => setTimeout(resolve, 0)); expect(trackEvents.length).toBeGreaterThan(0); expect(trackEvents[0][0].text).toBe('No track attribute'); }); it('still delivers lk.transcription to an application text stream handler', async () => { const { room } = setupRoom(); const appTexts: Array = []; room.registerTextStreamHandler('lk.transcription', async (reader) => { appTexts.push(await reader.readAll()); }); pushTranscriptionStream(room, agentIdentity, 'Hello world', { 'lk.segment_id': 'SG_1', 'lk.transcription_final': 'true', }); await new Promise((resolve) => setTimeout(resolve, 0)); expect(appTexts).toEqual(['Hello world']); }); });