livekit-server-sdk 2.16.0 → 2.17.0

package/src/TwirpRPC.ts

@@ -2,6 +2,19 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import type { JsonValue } from '@bufbuild/protobuf';
+import {
+  FAILOVER_BACKOFF_BASE_MS,
+  failoverAttempts,
+  hostKey,
+  pickNext,
+  regionOrigins,
+  sleep,
+} from './failover.js';
+import { SDK_VERSION } from './version.js';
+
+// Identifies the SDK and version to the server on every request. Browsers forbid
+// setting User-Agent via fetch and silently drop it; Node honors it.
+const USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;
 
 // twirp RPC adapter for client implementation
 
@@ -10,10 +23,16 @@ type Options = {
   prefix?: string;
   /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */
   requestTimeout?: number;
+  /** Whether region failover is enabled (LiveKit Cloud hosts only). Defaults to true. */
+  failover?: boolean;
+  /** @internal test-only: force failover regardless of host. */
+  failoverForce?: boolean;
+  /** @internal test-only: base retry backoff in ms. */
+  failoverBackoffMs?: number;
 };
 
 const defaultPrefix = '/twirp';
-const defaultTimeoutSeconds = 60;
+const defaultTimeoutSeconds = 10;
 
 export const livekitPackage = 'livekit';
 export interface Rpc {
@@ -26,7 +45,7 @@ export interface Rpc {
   ): Promise<string>;
 }
 
-export class TwirpError extends Error {
+export class ServerError extends Error {
   status: number;
   code?: string;
   metadata?: Record<string, string>;
@@ -46,6 +65,68 @@ export class TwirpError extends Error {
   }
 }
 
+/** @deprecated use {@link ServerError} */
+export const TwirpError = ServerError;
+/** @deprecated use {@link ServerError} */
+export type TwirpError = ServerError;
+
+/**
+ * A {@link ServerError} from a SIP dialing call (`createSipParticipant` /
+ * `transferSipParticipant`) that failed with a SIP response status. The SIP code
+ * and reason are exposed as getters; any other error metadata remains available
+ * via {@link ServerError.metadata}.
+ */
+export class SipCallError extends ServerError {
+  constructor(
+    name: string,
+    message: string,
+    status: number,
+    code?: string,
+    metadata?: Record<string, string>,
+  ) {
+    super(name, SipCallError.describe(message, code, metadata), status, code, metadata);
+    this.name = 'SipCallError';
+  }
+
+  /** The SIP response code of the failed call, e.g. 486 (Busy Here). */
+  get sipStatusCode(): number | undefined {
+    const raw = this.metadata?.sip_status_code;
+    return raw !== undefined ? Number(raw) : undefined;
+  }
+
+  /** The SIP reason phrase of the failed call, e.g. "Busy Here". */
+  get sipStatus(): string | undefined {
+    return this.metadata?.sip_status;
+  }
+
+  /** Builds a SipCallError from a ServerError, preserving its code and metadata. */
+  static fromServerError(err: ServerError): SipCallError {
+    return new SipCallError(err.name, err.message, err.status, err.code, err.metadata);
+  }
+
+  // describe renders a clear message: the SIP status, the error code, and any
+  // other metadata the server attached. Falls back to the raw message when the
+  // error carries no SIP status.
+  private static describe(fallback: string, code?: string, metadata?: Record<string, string>) {
+    const sipCode = metadata?.sip_status_code;
+    if (!sipCode) {
+      return fallback;
+    }
+    const reason = metadata?.sip_status;
+    let msg = `SIP call failed: ${sipCode}${reason ? ` ${reason}` : ''}`;
+    if (code) {
+      msg += ` (${code})`;
+    }
+    const extra = Object.entries(metadata ?? {})
+      .filter(([k]) => k !== 'sip_status_code' && k !== 'sip_status' && k !== 'error_details')
+      .map(([k, v]) => `${k}=${v}`);
+    if (extra.length) {
+      msg += ` [${extra.join(', ')}]`;
+    }
+    return msg;
+  }
+}
+
 /**
  * JSON based Twirp V7 RPC
  */
@@ -58,6 +139,12 @@ export class TwirpRpc {
 
   requestTimeout: number;
 
+  failover: boolean;
+
+  private failoverForce: boolean;
+
+  private failoverBackoffMs: number;
+
   constructor(host: string, pkg: string, options?: Options) {
     if (host.startsWith('ws')) {
       host = host.replace('ws', 'http');
@@ -66,8 +153,18 @@ export class TwirpRpc {
     this.pkg = pkg;
     this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;
     this.prefix = options?.prefix || defaultPrefix;
+    this.failover = options?.failover ?? true;
+    this.failoverForce = options?.failoverForce ?? false;
+    this.failoverBackoffMs = options?.failoverBackoffMs ?? FAILOVER_BACKOFF_BASE_MS;
   }
 
+  /**
+   * Issues a Twirp request, failing over to alternative regions on retryable
+   * errors. On any transport error or HTTP 5xx it discovers regions via
+   * /settings/regions and replays the request — body and headers intact —
+   * against the next untried region, with exponential backoff. A 4xx is
+   * returned immediately.
+   */
   async request(
     service: string,
     method: string,
@@ -77,52 +174,103 @@ export class TwirpRpc {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): Promise<any> {
     const path = `${this.prefix}/${this.pkg}.${service}/${method}`;
-    const url = new URL(path, this.host);
-    const init: RequestInit = {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json;charset=UTF-8',
-        ...headers,
-      },
-      body: JSON.stringify(data),
+    const body = JSON.stringify(data);
+    const requestHeaders = {
+      'Content-Type': 'application/json;charset=UTF-8',
+      'User-Agent': USER_AGENT,
+      ...headers,
     };
 
-    if (timeout) {
-      init.signal = AbortSignal.timeout(timeout * 1000);
-    }
+    const origin = new URL(this.host);
+    const maxAttempts = failoverAttempts(
+      this.failover,
+      origin.hostname,
+      this.failoverForce,
+      timeout,
+    );
+    const attempted = new Set([hostKey(origin)]);
+    let regions: string[] | undefined;
+    let current = this.host;
 
-    const response = await fetch(url, init);
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const isLast = attempt + 1 >= maxAttempts;
+      const init: RequestInit = { method: 'POST', headers: requestHeaders, body };
+      if (timeout) {
+        init.signal = AbortSignal.timeout(timeout * 1000);
+      }
 
-    if (!response.ok) {
-      const isJson = response.headers.get('content-type') === 'application/json';
-      let errorMessage = 'Unknown internal error';
-      let errorCode: string | undefined = undefined;
-      let metadata: Record<string, string> | undefined = undefined;
+      let response: Response | undefined;
+      let transportError: unknown;
       try {
-        if (isJson) {
-          const parsedError = (await response.json()) as Record<string, unknown>;
-          if ('msg' in parsedError) {
-            errorMessage = <string>parsedError.msg;
-          }
-          if ('code' in parsedError) {
-            errorCode = <string>parsedError.code;
-          }
-          if ('meta' in parsedError) {
-            metadata = <Record<string, string>>parsedError.meta;
-          }
-        } else {
-          errorMessage = await response.text();
-        }
+        response = await fetch(new URL(path, current), init);
       } catch (e) {
-        // parsing went wrong, no op and we keep default error message
-        console.debug(`Error when trying to parse error message, using defaults`, e);
+        transportError = e;
+      }
+
+      if (response?.ok) {
+        // Return the raw JSON. Every caller parses it with protobuf-es
+        // fromJson(), which per the proto3 JSON spec accepts both the proto
+        // field names (snake_case) and their json_name (camelCase), so no key
+        // conversion is needed. Converting keys would also corrupt map<string,…>
+        // entries (e.g. participant attributes), whose keys are user data.
+        return (await response.json()) as Record<string, unknown>;
       }
 
-      throw new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);
+      // Only retryable failures (a transport error or HTTP 5xx) continue;
+      // a 4xx is terminal.
+      const retryable = transportError !== undefined || (!!response && response.status >= 500);
+      let next: string | undefined;
+      if (retryable && !isLast) {
+        if (!regions) {
+          regions = await regionOrigins(origin, headers);
+        }
+        next = pickNext(regions, attempted);
+      }
+
+      if (!retryable || next === undefined) {
+        if (response) {
+          throw await toTwirpError(response);
+        }
+        throw transportError;
+      }
+
+      const reason = response ? `status ${response.status}` : transportError;
+      console.warn(
+        `livekit API request to ${new URL(current).host} failed (${reason}), retrying with fallback url ${next}`,
+      );
+      await sleep(this.failoverBackoffMs * 2 ** attempt);
+      attempted.add(hostKey(new URL(next)));
+      current = next;
     }
-    const parsedResp = (await response.json()) as Record<string, unknown>;
 
-    const camelcaseKeys = await import('camelcase-keys').then((mod) => mod.default);
-    return camelcaseKeys(parsedResp, { deep: true });
+    throw new Error('failover loop exited without returning'); // unreachable
+  }
+}
+
+/** Builds a TwirpError from a non-2xx response, mirroring Twirp's JSON error shape. */
+async function toTwirpError(response: Response): Promise<TwirpError> {
+  const isJson = response.headers.get('content-type') === 'application/json';
+  let errorMessage = 'Unknown internal error';
+  let errorCode: string | undefined = undefined;
+  let metadata: Record<string, string> | undefined = undefined;
+  try {
+    if (isJson) {
+      const parsedError = (await response.json()) as Record<string, unknown>;
+      if ('msg' in parsedError) {
+        errorMessage = <string>parsedError.msg;
+      }
+      if ('code' in parsedError) {
+        errorCode = <string>parsedError.code;
+      }
+      if ('meta' in parsedError) {
+        metadata = <Record<string, string>>parsedError.meta;
+      }
+    } else {
+      errorMessage = await response.text();
+    }
+  } catch (e) {
+    // parsing went wrong, no op and we keep default error message
+    console.debug(`Error when trying to parse error message, using defaults`, e);
   }
+  return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);
 }

package/src/dialTimeout.test.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_RINGING_TIMEOUT_SECONDS,
+  RINGING_TIMEOUT_MARGIN_SECONDS,
+  dialRequestTimeout,
+} from './dialTimeout.js';
+
+const DEFAULT_FLOOR = DEFAULT_RINGING_TIMEOUT_SECONDS + RINGING_TIMEOUT_MARGIN_SECONDS;
+
+describe('dialRequestTimeout', () => {
+  it('falls back to the default ring window plus margin when nothing is set', () => {
+    // No ringing timeout means the server's default ring applies, so the request
+    // must still outlast it by the margin.
+    expect(dialRequestTimeout(undefined, undefined)).toBe(DEFAULT_FLOOR);
+  });
+
+  it('honors a user timeout above the default floor, raises one below it', () => {
+    expect(dialRequestTimeout(45, undefined)).toBe(45);
+    expect(dialRequestTimeout(5, undefined)).toBe(DEFAULT_FLOOR);
+  });
+
+  it('tracks a short ringing timeout (ring + margin), no fixed floor', () => {
+    expect(dialRequestTimeout(undefined, 10)).toBe(10 + RINGING_TIMEOUT_MARGIN_SECONDS);
+  });
+
+  it('raises the timeout to stay above a long ringing timeout', () => {
+    expect(dialRequestTimeout(undefined, 60)).toBe(60 + RINGING_TIMEOUT_MARGIN_SECONDS);
+  });
+
+  it('raises a user timeout that is too tight for the ringing window', () => {
+    // user asked for 30s but ringing is 40s; must outlast ringing by the margin.
+    expect(dialRequestTimeout(30, 40)).toBe(40 + RINGING_TIMEOUT_MARGIN_SECONDS);
+  });
+
+  it('keeps a user timeout that already clears the ringing window', () => {
+    expect(dialRequestTimeout(90, 40)).toBe(90);
+  });
+});

package/src/dialTimeout.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// Shared request-timeout handling for calls that may block until a call is
+// answered (SIP CreateSIPParticipant/TransferSIPParticipant, WhatsApp
+// AcceptWhatsAppCall). These take longer than a normal API call, and the request
+// must outlast the wait or it would abort before the call is answered.
+
+/**
+ * Ring window (seconds) assumed when a request doesn't set a ringing timeout;
+ * matches the server default. A dialing request must outlast it.
+ */
+export const DEFAULT_RINGING_TIMEOUT_SECONDS = 30;
+
+/**
+ * When a call waits on ringing, the request must outlast the ringing window or
+ * it would abort before the call can be answered. We keep at least this margin
+ * (seconds) of request timeout above the ringing timeout.
+ */
+export const RINGING_TIMEOUT_MARGIN_SECONDS = 2;
+
+/**
+ * Resolves the request timeout (seconds) for a phone-dialing call: the ring
+ * window plus a margin, so the request doesn't abort before the call can be
+ * answered. The ring window is the request's `ringingTimeout` when set, else
+ * {@link DEFAULT_RINGING_TIMEOUT_SECONDS}. A longer user-supplied `timeout` is
+ * honored; a shorter one is raised to the floor.
+ */
+export function dialRequestTimeout(
+  timeout: number | undefined,
+  ringingTimeout: number | undefined,
+): number {
+  const ring = ringingTimeout ?? DEFAULT_RINGING_TIMEOUT_SECONDS;
+  const floor = ring + RINGING_TIMEOUT_MARGIN_SECONDS;
+  return Math.max(timeout ?? floor, floor);
+}

package/src/failover.test.ts

@@ -0,0 +1,188 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  FAILOVER_MAX_ATTEMPTS,
+  MIN_FAILOVER_TIMEOUT_SECONDS,
+  failoverAttempts,
+  hostKey,
+  parseMaxAge,
+  pickNext,
+  regionOrigins,
+  sleep,
+} from './failover.js';
+
+describe('failoverAttempts', () => {
+  it('fails over for LiveKit Cloud hosts when enabled', () => {
+    expect(failoverAttempts(true, 'myproject.livekit.cloud')).toBe(FAILOVER_MAX_ATTEMPTS);
+    expect(failoverAttempts(true, 'myproject.region.livekit.cloud')).toBe(FAILOVER_MAX_ATTEMPTS);
+  });
+
+  it('does not fail over for non-cloud hosts', () => {
+    expect(failoverAttempts(true, 'myproject.livekit.io')).toBe(1);
+    expect(failoverAttempts(true, 'example.com')).toBe(1);
+    expect(failoverAttempts(true, '127.0.0.1')).toBe(1);
+    expect(failoverAttempts(true, 'notlivekit.cloud')).toBe(1);
+  });
+
+  it('force bypasses the cloud-host check; disabled never fails over', () => {
+    expect(failoverAttempts(true, '127.0.0.1', true)).toBe(FAILOVER_MAX_ATTEMPTS);
+    expect(failoverAttempts(false, 'myproject.livekit.cloud', true)).toBe(1);
+    expect(failoverAttempts(false, 'myproject.livekit.cloud')).toBe(1);
+  });
+
+  it('applies the thundering-herd guard for sub-threshold timeouts', () => {
+    expect(
+      failoverAttempts(true, 'myproject.livekit.cloud', false, MIN_FAILOVER_TIMEOUT_SECONDS - 1),
+    ).toBe(1);
+    expect(
+      failoverAttempts(true, 'myproject.livekit.cloud', false, MIN_FAILOVER_TIMEOUT_SECONDS),
+    ).toBe(FAILOVER_MAX_ATTEMPTS);
+    // 0 means "no timeout set" and is not guarded.
+    expect(failoverAttempts(true, 'myproject.livekit.cloud', false, 0)).toBe(FAILOVER_MAX_ATTEMPTS);
+  });
+});
+
+describe('hostKey', () => {
+  it('lowercases the host and keeps a non-default port', () => {
+    expect(hostKey(new URL('https://Example.LiveKit.Cloud/twirp'))).toBe('example.livekit.cloud');
+    expect(hostKey(new URL('https://example.livekit.cloud:8080/twirp'))).toBe(
+      'example.livekit.cloud:8080',
+    );
+  });
+});
+
+describe('pickNext', () => {
+  const origins = ['https://a.livekit.cloud', 'https://b.livekit.cloud'];
+
+  it('returns the first origin not yet attempted', () => {
+    expect(pickNext(origins, new Set())).toBe('https://a.livekit.cloud');
+    expect(pickNext(origins, new Set(['a.livekit.cloud']))).toBe('https://b.livekit.cloud');
+  });
+
+  it('returns undefined once every origin has been attempted', () => {
+    expect(pickNext(origins, new Set(['a.livekit.cloud', 'b.livekit.cloud']))).toBeUndefined();
+  });
+
+  it('skips malformed origin URLs', () => {
+    expect(pickNext(['not a url', 'https://c.livekit.cloud'], new Set())).toBe(
+      'https://c.livekit.cloud',
+    );
+  });
+});
+
+describe('sleep', () => {
+  it('resolves immediately for non-positive durations', async () => {
+    await expect(sleep(0)).resolves.toBeUndefined();
+    await expect(sleep(-5)).resolves.toBeUndefined();
+  });
+});
+
+describe('parseMaxAge', () => {
+  it('returns 0 when the header is absent or empty', () => {
+    expect(parseMaxAge(null)).toBe(0);
+    expect(parseMaxAge('')).toBe(0);
+  });
+
+  it('parses max-age (in seconds) to milliseconds', () => {
+    expect(parseMaxAge('max-age=300')).toBe(300_000);
+  });
+
+  it('finds max-age alongside other directives', () => {
+    expect(parseMaxAge('public, max-age=3600')).toBe(3_600_000);
+    expect(parseMaxAge('private, max-age=600, must-revalidate')).toBe(600_000);
+    expect(parseMaxAge('no-cache, max-age=30')).toBe(30_000);
+  });
+
+  it('is case-insensitive and tolerates surrounding whitespace', () => {
+    expect(parseMaxAge('Max-Age=300')).toBe(300_000);
+    expect(parseMaxAge('  max-age = 300 ')).toBe(0); // spaces around "=" are not valid per RFC
+    expect(parseMaxAge('public,   max-age=120')).toBe(120_000);
+  });
+
+  it('treats max-age=0 and non-caching directives as "do not cache"', () => {
+    expect(parseMaxAge('max-age=0')).toBe(0);
+    expect(parseMaxAge('no-cache')).toBe(0);
+    expect(parseMaxAge('no-store')).toBe(0);
+    expect(parseMaxAge('public')).toBe(0);
+  });
+
+  it('ignores s-maxage and only honors max-age', () => {
+    expect(parseMaxAge('s-maxage=3600, max-age=120')).toBe(120_000);
+    expect(parseMaxAge('s-maxage=3600')).toBe(0);
+  });
+
+  it('returns 0 for negative or non-numeric max-age', () => {
+    expect(parseMaxAge('max-age=-5')).toBe(0);
+    expect(parseMaxAge('max-age=abc')).toBe(0);
+  });
+});
+
+describe('regionOrigins', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const mockResponse = (regions: Array<{ url: string }>, cacheControl: string | null): Response =>
+    ({
+      ok: true,
+      status: 200,
+      headers: { get: (h: string) => (h.toLowerCase() === 'cache-control' ? cacheControl : null) },
+      json: async () => ({ regions }),
+    }) as unknown as Response;
+
+  it('coalesces concurrent discovery fetches for the same origin', async () => {
+    let resolveFetch: (r: Response) => void = () => {};
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockImplementation(() => new Promise<Response>((resolve) => (resolveFetch = resolve)));
+
+    const origin = new URL('https://primary.coalesce.livekit.cloud');
+    const p1 = regionOrigins(origin, {});
+    const p2 = regionOrigins(origin, {});
+
+    // Both callers share a single in-flight request.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    resolveFetch(mockResponse([{ url: 'wss://r1.coalesce.livekit.cloud' }], 'max-age=300'));
+    const [o1, o2] = await Promise.all([p1, p2]);
+
+    expect(o1).toEqual(['https://r1.coalesce.livekit.cloud']);
+    expect(o2).toEqual(o1);
+  });
+
+  it('serves later callers from the cache within the TTL', async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(mockResponse([{ url: 'wss://r.cached.livekit.cloud' }], 'max-age=300'));
+
+    const origin = new URL('https://primary.cached.livekit.cloud');
+    const first = await regionOrigins(origin, {});
+    const second = await regionOrigins(origin, {});
+
+    expect(first).toEqual(['https://r.cached.livekit.cloud']);
+    expect(second).toEqual(first);
+    // The second call is served from the cache, so no second fetch.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not cache when the TTL is zero (max-age=0)', async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(mockResponse([{ url: 'wss://r.nocache.livekit.cloud' }], 'max-age=0'));
+
+    const origin = new URL('https://primary.nocache.livekit.cloud');
+    await regionOrigins(origin, {});
+    await regionOrigins(origin, {});
+
+    // Nothing cached, so each call re-fetches.
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns an empty list when discovery fails and nothing is cached', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('network down'));
+    const origin = new URL('https://primary.error.livekit.cloud');
+    await expect(regionOrigins(origin, {})).resolves.toEqual([]);
+  });
+});