livekit-client 2.21.0 → 2.22.1

package/src/room/Room.ts

@@ -91,6 +91,7 @@ import {
   type RpcInvocationData,
   RpcServerManager,
 } from './rpc';
+import { summarizeStatsReport } from './statsSummary';
 import CriticalTimers from './timers';
 import LocalAudioTrack from './track/LocalAudioTrack';
 import type LocalTrack from './track/LocalTrack';
@@ -113,6 +114,7 @@ import {
   Future,
   createDummyVideoStreamTrack,
   extractChatMessage,
+  extractTrackSid,
   extractTranscriptionSegments,
   getDisconnectReasonFromConnectionError,
   getEmptyAudioStreamTrack,
@@ -142,6 +144,7 @@ export enum ConnectionState {
 }
 
 const CONNECTION_RECONCILE_FREQUENCY_MS = 4 * 1000;
+const STATS_LOG_FREQUENCY_MS = 30 * 1000;
 
 /**
  * In LiveKit, a room is the logical grouping for a list of participants.
@@ -206,6 +209,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private connectionReconcileInterval?: ReturnType<typeof setInterval>;
 
+  private statsLogInterval?: ReturnType<typeof setInterval>;
+
   private regionUrlProvider?: RegionUrlProvider;
 
   private regionUrl?: string;
@@ -214,10 +219,14 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private log = log;
 
+  private statsLog = log;
+
   private bufferedEvents: Array<any> = [];
 
   private isResuming: boolean = false;
 
+  private pendingTrackAddedCallbacks = new Map<Track.SID, Set<() => void>>();
+
   /**
    * map to store first point in time when a particular transcription segment was received
    */
@@ -251,6 +260,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.options = { ...roomOptionDefaults, ...options };
 
     this.log = getLogger(this.options.loggerName ?? LoggerNames.Room, () => this.logContext);
+    // its own logger name, so the stats dumps can be silenced or routed
+    // separately from the rest of the room's logs
+    this.statsLog = getLogger(LoggerNames.Stats, () => this.logContext);
     this.transcriptionReceivedTimes = new Map();
 
     this.options.audioCaptureDefaults = {
@@ -268,7 +280,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
     this.maybeCreateEngine();
 
-    this.incomingDataStreamManager = new IncomingDataStreamManager();
+    this.incomingDataStreamManager = new IncomingDataStreamManager(
+      this.options.dataStream?.maxPayloadByteLength,
+    );
     this.outgoingDataStreamManager = new OutgoingDataStreamManager(
       this.engine,
       this.log,
@@ -636,10 +650,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         this.emitBufferedEvents();
       })
       .on(EngineEvent.SignalResumed, () => {
-        this.bufferedEvents = [];
         if (this.state === ConnectionState.Reconnecting || this.isResuming) {
           this.sendSyncState();
         }
+        this.emitBufferedEvents();
       })
       .on(EngineEvent.Restarting, this.handleRestarting)
       .on(EngineEvent.Restarted, this.handleRestarted)
@@ -1588,24 +1602,38 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     // at that time, ICE connectivity has not been established so the track is not
     // technically subscribed.
     // We'll defer these events until when the room is connected or eventually disconnected.
-    if (this.state === ConnectionState.Connecting || this.state === ConnectionState.Reconnecting) {
+    if ([ConnectionState.Connecting, ConnectionState.Reconnecting].includes(this.state)) {
+      const pendingTrackSid = extractTrackSid(mediaTrack, stream);
+      this.log.debug('deferring on track for later', {
+        mediaTrackId: mediaTrack.id,
+        mediaStreamId: stream.id,
+        tracksInStream: stream.getTracks().map((track) => track.id),
+      });
       const reconnectedHandler = () => {
-        this.log.debug('deferring on track for later', {
-          mediaTrackId: mediaTrack.id,
-          mediaStreamId: stream.id,
-          tracksInStream: stream.getTracks().map((track) => track.id),
-        });
-        this.onTrackAdded(mediaTrack, stream, receiver);
         cleanup();
+        this.onTrackAdded(mediaTrack, stream, receiver);
       };
       const cleanup = () => {
         this.off(RoomEvent.Reconnected, reconnectedHandler);
         this.off(RoomEvent.Connected, reconnectedHandler);
         this.off(RoomEvent.Disconnected, cleanup);
+        if (pendingTrackSid) {
+          const pendingCallbacks = this.pendingTrackAddedCallbacks.get(pendingTrackSid);
+          pendingCallbacks?.delete(cleanup);
+          if (pendingCallbacks?.size === 0) {
+            this.pendingTrackAddedCallbacks.delete(pendingTrackSid);
+          }
+        }
       };
       this.once(RoomEvent.Reconnected, reconnectedHandler);
       this.once(RoomEvent.Connected, reconnectedHandler);
       this.once(RoomEvent.Disconnected, cleanup);
+      if (pendingTrackSid) {
+        const pendingCallbacks =
+          this.pendingTrackAddedCallbacks.get(pendingTrackSid) ?? new Set<() => void>();
+        pendingCallbacks.add(cleanup);
+        this.pendingTrackAddedCallbacks.set(pendingTrackSid, pendingCallbacks);
+      }
       return;
     }
     if (this.state === ConnectionState.Disconnected) {
@@ -1618,11 +1646,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
     const parts = unpackStreamId(stream.id);
     const participantSid = parts[0];
-    let streamId = parts[1];
-    let trackId = mediaTrack.id;
+    const streamId = parts[1];
     // firefox will get streamId (pID|trackId) instead of (pID|streamId) as it doesn't support sync tracks by stream
     // and generates its own track id instead of infer from sdp track id.
-    if (streamId && streamId.startsWith('TR')) trackId = streamId;
+    let trackId = extractTrackSid(mediaTrack, stream) ?? mediaTrack.id;
 
     if (participantSid === this.localParticipant.sid) {
       this.log.warn('tried to create RemoteParticipant for local participant');
@@ -1691,6 +1718,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private cancelPendingTrackAdded(trackSid: Track.SID) {
+    this.pendingTrackAddedCallbacks.get(trackSid)?.forEach((cleanup) => cleanup());
+  }
+
   private handleLocalTrackSubscribed(subscribedSid: string) {
     const findPublication = () =>
       this.localParticipant
@@ -1893,7 +1924,13 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
       // when it's disconnected, send updates
       if (info.state === ParticipantInfo_State.DISCONNECTED) {
-        this.handleParticipantDisconnected(info.identity, remoteParticipant);
+        this.handleParticipantDisconnected(
+          info.identity,
+          remoteParticipant,
+          info.disconnectReason === DisconnectReason.UNKNOWN_REASON
+            ? undefined
+            : info.disconnectReason,
+        );
       } else {
         // create participant if doesn't exist
         this.getOrCreateParticipant(info.identity, info);
@@ -1911,7 +1948,11 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.incomingDataTrackManager.receiveSfuPublicationUpdates(mapped);
   };
 
-  private handleParticipantDisconnected(identity: string, participant?: RemoteParticipant) {
+  private handleParticipantDisconnected(
+    identity: string,
+    participant?: RemoteParticipant,
+    disconnectReason?: DisconnectReason,
+  ) {
     // remove and send event
     this.remoteParticipants.delete(identity);
     if (!participant) {
@@ -1924,7 +1965,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     participant.trackPublications.forEach((publication) => {
       participant.unpublishTrack(publication.trackSid, true);
     });
-    this.emit(RoomEvent.ParticipantDisconnected, participant);
+    this.emit(RoomEvent.ParticipantDisconnected, participant, disconnectReason);
     participant.setDisconnected();
     this.rpcClientManager.handleParticipantDisconnected(participant.identity);
   }
@@ -2008,8 +2049,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         return;
       }
       const newStreamState = Track.streamStateFromProto(streamState.state);
+      const prevStreamState = pub.track.streamState;
       pub.track.setStreamState(newStreamState);
-      if (newStreamState !== pub.track.streamState) {
+      if (newStreamState !== prevStreamState) {
         participant.emit(ParticipantEvent.TrackStreamStateChanged, pub, pub.track.streamState);
         this.emitWhenConnected(
           RoomEvent.TrackStreamStateChanged,
@@ -2035,6 +2077,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
   };
 
   private handleSubscriptionError = (update: SubscriptionResponse) => {
+    this.cancelPendingTrackAdded(update.trackSid);
+
     const participant = Array.from(this.remoteParticipants.values()).find((p) =>
       p.trackPublications.has(update.trackSid),
     );
@@ -2409,6 +2453,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         },
       )
       .on(ParticipantEvent.TrackUnpublished, (publication: RemoteTrackPublication) => {
+        this.cancelPendingTrackAdded(publication.trackSid);
         this.emit(RoomEvent.TrackUnpublished, publication, participant);
       })
       .on(
@@ -2558,6 +2603,46 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     );
   }
 
+  private setStatsLogging(enabled: boolean) {
+    if (enabled) {
+      if (!this.statsLogInterval) {
+        this.statsLogInterval = CriticalTimers.setInterval(() => {
+          // logWebRTCStats handles its own errors, nothing to await here
+          this.logWebRTCStats();
+        }, STATS_LOG_FREQUENCY_MS);
+      }
+    } else if (this.statsLogInterval) {
+      CriticalTimers.clearInterval(this.statsLogInterval);
+      this.statsLogInterval = undefined;
+    }
+  }
+
+  /**
+   * Dumps stats of both peer connections.
+   */
+  private logWebRTCStats = async () => {
+    const pcManager = this.engine?.pcManager;
+    if (!pcManager) {
+      return;
+    }
+    try {
+      const [publisher, subscriber] = await Promise.all([
+        pcManager.publisher.getStats(),
+        pcManager.subscriber?.getStats(),
+      ]);
+      const publisherStats = publisher && summarizeStatsReport(publisher);
+      const subscriberStats = subscriber && summarizeStatsReport(subscriber);
+      this.statsLog.info(`webrtc stats`, {
+        publisher: publisherStats?.connection,
+        subscriber: subscriberStats?.connection,
+        inbound: [...(publisherStats?.inbound ?? []), ...(subscriberStats?.inbound ?? [])],
+        outbound: publisherStats?.outbound,
+      });
+    } catch (error) {
+      this.statsLog.debug('could not collect webrtc stats', { error });
+    }
+  };
+
   private registerConnectionReconcile() {
     this.clearConnectionReconcile();
     let consecutiveFailures = 0;
@@ -2581,11 +2666,20 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
             : undefined,
         });
         if (consecutiveFailures >= 3) {
-          this.recreateEngine();
-          this.handleDisconnect(
-            this.options.stopLocalTrackOnUnpublish,
-            DisconnectReason.STATE_MISMATCH,
-          );
+          this.clearConnectionReconcile();
+          if (this.engine && !this.engine.isClosed) {
+            // The transport silently died while we still looked connected. Try a full reconnect
+            // (keeps the room alive; the engine falls back to Disconnected if it ultimately fails).
+            this.log.warn('detected connection state mismatch, attempting full reconnect');
+            this.engine.reconnect();
+          } else {
+            // No usable engine to reconnect with; tear down.
+            this.recreateEngine();
+            this.handleDisconnect(
+              this.options.stopLocalTrackOnUnpublish,
+              DisconnectReason.STATE_MISMATCH,
+            );
+          }
         }
       } else {
         consecutiveFailures = 0;
@@ -2607,7 +2701,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.log.info(`connection state changed: ${this.state} -> ${state}`);
     this.state = state;
     this.incomingDataStreamManager.setConnected(state === ConnectionState.Connected);
+    this.setStatsLogging(state === ConnectionState.Connected);
+
     this.emit(RoomEvent.ConnectionStateChanged, this.state);
+
     return true;
   }
 
@@ -2913,7 +3010,10 @@ export type RoomEventCallbacks = {
   moved: (name: string) => void;
   mediaDevicesChanged: () => void;
   participantConnected: (participant: RemoteParticipant) => void;
-  participantDisconnected: (participant: RemoteParticipant) => void;
+  participantDisconnected: (
+    participant: RemoteParticipant,
+    disconnectReason?: DisconnectReason,
+  ) => void;
   trackPublished: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
   trackSubscribed: (
     track: RemoteTrack,

package/src/room/data-stream/incoming/IncomingDataStreamManager.ts

@@ -535,7 +535,7 @@ function bytesToChunks(streamId: string): TransformStream<Uint8Array, DataStream
  * synthesized text chunk decodes independently. The `flush` emits the decoder's trailing bytes.
  */
 function bytesToDecodedUtf8(streamId: string): TransformStream<Uint8Array, DataStream_Chunk> {
-  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const decoder = new TextDecoder('utf-8');
   const encoder = new TextEncoder();
 
   let outIndex = 0;

package/src/room/data-stream/incoming/StreamReader.ts

@@ -204,7 +204,7 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
     // Suppress unhandled rejection on reader.closed — errors are
     // already propagated through reader.read() to the consumer.
     reader.closed.catch(() => {});
-    const decoder = new TextDecoder('utf-8', { fatal: true });
+    const decoder = new TextDecoder('utf-8');
     const signal = this.signal;
 
     const cleanup = () => {

package/src/room/errors.ts

@@ -248,8 +248,7 @@ export class PublishTrackError extends LivekitError {
 }
 
 export type RequestErrorReason =
-  | Exclude<RequestResponse_Reason, RequestResponse_Reason.OK>
-  | 'TimeoutError';
+  Exclude<RequestResponse_Reason, RequestResponse_Reason.OK> | 'TimeoutError';
 
 export class SignalRequestError extends LivekitReasonedError<RequestErrorReason> {
   readonly name = 'SignalRequestError';

package/src/room/events.ts

@@ -80,7 +80,7 @@ export enum RoomEvent {
    * When a [[RemoteParticipant]] leaves *after* the local
    * participant has joined.
    *
-   * args: ([[RemoteParticipant]])
+   * args: ([[RemoteParticipant]], [[DisconnectReason]] | undefined)
    */
   ParticipantDisconnected = 'participantDisconnected',
 

package/src/room/statsSummary.ts

@@ -0,0 +1,187 @@
+/** one summarised stats entry; keys without a value are dropped */
+type Summary = Record<string, unknown>;
+
+function compact<T extends Summary>(summary: T): Summary {
+  const compacted: Summary = {};
+  for (const [key, value] of Object.entries(summary)) {
+    if (value !== undefined) {
+      compacted[key] = value;
+    }
+  }
+  return compacted;
+}
+
+function resolution(width?: number, height?: number): string | undefined {
+  return width && height ? `${width}x${height}` : undefined;
+}
+
+/** keeps the derived durations readable; reported values are logged as they are */
+function round(seconds: number): number {
+  return Math.round(seconds * 10_000) / 10_000;
+}
+
+/**
+ * Average time media spent in the jitter buffer, in s. Both counters are
+ * cumulative, so this is the average over the lifetime of the stream.
+ */
+function jitterBuffer(stat: Summary): number | undefined {
+  const delay = stat.jitterBufferDelay as number | undefined;
+  const emitted = stat.jitterBufferEmittedCount as number | undefined;
+  return delay !== undefined && emitted ? round(delay / emitted) : undefined;
+}
+
+/**
+ * Playout delay in s. Video receive reports it directly, the audio path keeps it
+ * in the linked `media-playout` stats summed over the samples played out. Pairs
+ * with `RemoteTrack.setPlayoutDelay`.
+ */
+function playoutDelay(stat: Summary, playout?: Summary): number | undefined {
+  if (stat.playoutDelay !== undefined) {
+    return round(stat.playoutDelay as number);
+  }
+  const total = playout?.totalPlayoutDelay as number | undefined;
+  const samples = playout?.totalSamplesCount as number | undefined;
+  return total !== undefined && samples ? round(total / samples) : undefined;
+}
+
+/**
+ * Picks the interesting fields out of a `getStats()` report and groups them by
+ * RTP stream, so a stats dump can be read without unfolding the raw report.
+ */
+export function summarizeStatsReport(report: RTCStatsReport) {
+  const byId = new Map<string, Summary>();
+  const candidatePairs: Summary[] = [];
+  const inbound: Summary[] = [];
+  const outbound: Summary[] = [];
+  let transport: Summary | undefined;
+
+  report.forEach((stat) => byId.set(stat.id, stat));
+
+  const codecOf = (stat: Summary) =>
+    stat.codecId ? byId.get(stat.codecId as string)?.mimeType : undefined;
+  const relatedOf = (stat: Summary, key: 'remoteId' | 'mediaSourceId' | 'playoutId') =>
+    stat[key] ? byId.get(stat[key] as string) : undefined;
+
+  report.forEach((stat) => {
+    switch (stat.type) {
+      case 'inbound-rtp': {
+        const playout = relatedOf(stat, 'playoutId');
+        inbound.push(
+          compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            // matches `streamTrackID` in the track's own log context
+            trackId: stat.trackIdentifier,
+            codec: codecOf(stat),
+            decoder: stat.decoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            bytesReceived: stat.bytesReceived,
+            packetsReceived: stat.packetsReceived,
+            packetsLost: stat.packetsLost,
+            packetsDiscarded: stat.packetsDiscarded,
+            // frames received without frames decoded is a decode failure
+            framesReceived: stat.framesReceived,
+            framesDecoded: stat.framesDecoded,
+            framesDropped: stat.framesDropped,
+            keyFramesDecoded: stat.keyFramesDecoded,
+            freezeCount: stat.freezeCount,
+            totalFreezesDuration: stat.totalFreezesDuration,
+            pauseCount: stat.pauseCount,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            jitter: stat.jitter,
+            jitterBuffer: jitterBuffer(stat),
+            playoutDelay: playoutDelay(stat, playout),
+            audioLevel: stat.audioLevel,
+            totalSamplesReceived: stat.totalSamplesReceived,
+            concealedSamples: stat.concealedSamples,
+          }),
+        );
+        break;
+      }
+      case 'outbound-rtp': {
+        const remote = relatedOf(stat, 'remoteId');
+        const source = relatedOf(stat, 'mediaSourceId');
+        outbound.push(
+          compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            rid: stat.rid,
+            trackId: source?.trackIdentifier,
+            active: stat.active,
+            codec: codecOf(stat),
+            encoder: stat.encoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            // what the source produces, to tell a stalled capture from a stalled encoder
+            captureResolution: resolution(
+              source?.width as number | undefined,
+              source?.height as number | undefined,
+            ),
+            captureFps: source?.framesPerSecond,
+            audioLevel: source?.audioLevel,
+            targetBitrate: stat.targetBitrate,
+            bytesSent: stat.bytesSent,
+            packetsSent: stat.packetsSent,
+            retransmittedPacketsSent: stat.retransmittedPacketsSent,
+            framesEncoded: stat.framesEncoded,
+            keyFramesEncoded: stat.keyFramesEncoded,
+            limitedBy:
+              stat.qualityLimitationReason === 'none' ? undefined : stat.qualityLimitationReason,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            // loss, jitter and RTT are only known from what the remote reports
+            remotePacketsLost: remote?.packetsLost,
+            remoteFractionLost: remote?.fractionLost,
+            remoteJitter: remote?.jitter,
+            remoteRoundTripTime: remote?.roundTripTime,
+          }),
+        );
+        break;
+      }
+      case 'transport':
+        transport = stat;
+        break;
+      case 'candidate-pair':
+        candidatePairs.push(stat);
+        break;
+      default:
+    }
+  });
+
+  const selectedPairId = transport?.selectedCandidatePairId as string | undefined;
+  const pair =
+    (selectedPairId ? byId.get(selectedPairId) : undefined) ??
+    candidatePairs.find((candidate) => candidate.selected) ??
+    candidatePairs.find((candidate) => candidate.nominated);
+  const local = pair?.localCandidateId ? byId.get(pair.localCandidateId as string) : undefined;
+  const remote = pair?.remoteCandidateId ? byId.get(pair.remoteCandidateId as string) : undefined;
+
+  const connection = compact({
+    ice: transport?.iceState,
+    dtls: transport?.dtlsState,
+    route:
+      local && remote
+        ? `${local.candidateType}/${local.protocol} -> ${remote.candidateType}`
+        : undefined,
+    network: local?.networkType,
+    currentRoundTripTime: pair?.currentRoundTripTime,
+    // the send bandwidth estimate; no RTP stream reports it
+    availableOutgoingBitrate: pair?.availableOutgoingBitrate,
+    availableIncomingBitrate: pair?.availableIncomingBitrate,
+    bytesSent: pair?.bytesSent,
+    bytesReceived: pair?.bytesReceived,
+    candidatePairChanges: transport?.selectedCandidatePairChanges,
+  });
+
+  return {
+    connection: Object.keys(connection).length > 0 ? connection : undefined,
+    outbound: outbound.length > 0 ? outbound : undefined,
+    inbound: inbound.length > 0 ? inbound : undefined,
+  };
+}

package/src/room/token-source/TokenSource.ts

@@ -213,29 +213,34 @@ class TokenSourceEndpoint extends TokenSourceCached {
     const body = await response.json();
     return TokenSourceResponse.fromJson(body, {
       // NOTE: it could be possible that the response body could contain more fields than just
-      // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer)
+      // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer)
       ignoreUnknownFields: true,
     });
   }
 }
 
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
   baseUrl?: string;
 };
-
-class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-  constructor(sandboxId: string, options: SandboxTokenServerOptions) {
+class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+  constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) {
     const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options;
 
     super(`${baseUrl}/api/v2/sandbox/connection-details`, {
       ...rest,
       headers: {
-        'X-Sandbox-ID': sandboxId,
+        'X-Sandbox-ID': tokenServerId,
       },
     });
   }
 }
 
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {}
+
 export {
   /** The return type of {@link TokenSource.literal} */
   type TokenSourceLiteral,
@@ -243,8 +248,9 @@ export {
   type TokenSourceCustom,
   /** The return type of {@link TokenSource.endpoint} */
   type TokenSourceEndpoint,
-  /** The return type of {@link TokenSource.sandboxTokenServer} */
   type TokenSourceSandboxTokenServer,
+  /** The return type of {@link TokenSource.developmentTokenServer} */
+  type TokenSourceDevelopmentTokenServer,
   decodeTokenPayload,
   areTokenSourceFetchOptionsEqual,
 };
@@ -269,22 +275,29 @@ export const TokenSource = {
   /**
    * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
    * the standard endpoint format:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/endpoint/
    */
   endpoint(url: string, options: EndpointOptions = {}) {
     return new TokenSourceEndpoint(url, options);
   },
 
   /**
-   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+   */
+  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+
+  /**
+   * TokenSource.developmentTokenServer queries a development token server for credentials,
    * which supports quick prototyping / getting started types of use cases.
    *
    * This token provider is INSECURE and should NOT be used in production.
    *
    * For more info:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/sandbox-token-server/
    */
-  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
-    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) {
+    return new TokenSourceDevelopmentTokenServer(tokenServerId, options);
   },
 };

package/src/room/token-source/test-tokens.ts

@@ -1,3 +1,11 @@
+// Builds an unsigned (`alg: none`) JWT. These aren't signed at all, so they can only be used in
+// tests which don't care about the signature.
+function unsignedToken(payload: Record<string, unknown>) {
+  const encode = (value: Record<string, unknown>) =>
+    btoa(JSON.stringify(value)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  return `${encode({ alg: 'none', typ: 'JWT' })}.${encode(payload)}.`;
+}
+
 // Test JWTs created for test purposes only.
 // None of these actually auth against anything.
 export const TOKENS = {
@@ -25,4 +33,16 @@ export const TOKENS = {
   // A dummy roomConfig value is also set, with room_config.name = "test room name", room_config.extraField = "extra field value", and room_config.agents = [{"agentName": "test agent name","metadata":"test agent metadata","extraField":"extra field value"}]
   EXTRA_FIELDS:
     'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZXhwIjo5ODc2NTQzMjEwLCJuYmYiOjEyMzQ1Njc4OTAsImlhdCI6MTIzNDU2Nzg5MCwicm9vbUNvbmZpZyI6eyJuYW1lIjoidGVzdCByb29tIG5hbWUiLCJlbXB0eVRpbWVvdXQiOjAsImRlcGFydHVyZVRpbWVvdXQiOjAsIm1heFBhcnRpY2lwYW50cyI6MCwibWluUGxheW91dERlbGF5IjowLCJtYXhQbGF5b3V0RGVsYXkiOjAsInN5bmNTdHJlYW1zIjpmYWxzZSwiYWdlbnRzIjpbeyJhZ2VudE5hbWUiOiJ0ZXN0IGFnZW50IG5hbWUiLCJtZXRhZGF0YSI6InRlc3QgYWdlbnQgbWV0YWRhdGEiLCJleHRyYUZpZWxkIjoiZXh0cmEgZmllbGQgdmFsdWUifV0sIm1ldGFkYXRhIjoiIiwiZXh0cmFGaWVsZCI6ImV4dHJhIGZpZWxkIHZhbHVlIn19Cg.EDetpHG8cSubaApzgWJaQrpCiSy9KDBlfCfVdIydbQ-_CHiNnXOK_f_mCJbTf9A-duT1jmvPOkLrkkWFT60XPQ',
+
+  // Nbf date set at 1234567890 seconds (Fri Feb 13 2009 23:31:30 GMT+0000)
+  // No exp date set at all
+  NO_EXP: unsignedToken({ sub: '1234567890', nbf: 1234567890, iat: 1234567890 }),
+
+  // No nbf date set at all
+  // Exp date set at 1234567891 seconds (Fri Feb 13 2009 23:31:31 GMT+0000)
+  EXP_IN_PAST_NO_NBF: unsignedToken({ sub: '1234567890', exp: 1234567891, iat: 1234567890 }),
+
+  // No nbf date set at all
+  // Exp date set at 9876543210 seconds (Fri Dec 22 2282 20:13:30 GMT+0000)
+  VALID_NO_NBF: unsignedToken({ sub: '1234567890', exp: 9876543210, iat: 1234567890 }),
 };