livekit-server-sdk 2.16.0 → 2.18.0

package/src/failover.ts

@@ -0,0 +1,170 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// Region failover for the Twirp API clients.
+//
+// On a retryable failure (any transport error or HTTP 5xx) the client discovers
+// alternative LiveKit Cloud regions via /settings/regions and replays the
+// request against the next region, with exponential backoff. 4xx responses are
+// returned immediately.
+
+// Total attempts (the original request + fallback regions) and the base retry
+// backoff are fixed, not user-configurable, so retries can't be tuned to values
+// that could overwhelm the server.
+export const FAILOVER_MAX_ATTEMPTS = 3;
+export const FAILOVER_BACKOFF_BASE_MS = 200;
+// Below this per-request timeout, a retry is unlikely to help and many clients
+// would retry in lockstep across regions, so a short request gets a single
+// attempt (thundering-herd guard).
+export const MIN_FAILOVER_TIMEOUT_SECONDS = 5;
+
+/**
+ * Total request attempts for a host; 1 means no failover. Failover only engages
+ * when enabled, the host is a LiveKit Cloud domain, and the request timeout is
+ * long enough to retry. `force` bypasses the cloud-host check (test-only).
+ */
+export function failoverAttempts(
+  enabled: boolean,
+  hostname: string,
+  force = false,
+  timeoutSeconds = 0,
+): number {
+  if (!enabled || !(force || isCloud(hostname))) {
+    return 1;
+  }
+  if (timeoutSeconds > 0 && timeoutSeconds < MIN_FAILOVER_TIMEOUT_SECONDS) {
+    return 1;
+  }
+  return FAILOVER_MAX_ATTEMPTS;
+}
+
+// Failover only engages for LiveKit Cloud project domains.
+function isCloud(hostname: string): boolean {
+  return hostname.endsWith('.livekit.cloud');
+}
+
+/** Normalizes a region URL to an http(s) scheme (ws -> http, wss -> https). */
+function toHttp(url: string): string {
+  return url.startsWith('ws') ? `http${url.slice(2)}` : url;
+}
+
+/** A stable key identifying a host (including port) for dedup across attempts. */
+export function hostKey(url: URL): string {
+  return url.host.toLowerCase();
+}
+
+/** Returns the first region origin whose host has not yet been attempted. */
+export function pickNext(regionOrigins: string[], attempted: Set<string>): string | undefined {
+  for (const origin of regionOrigins) {
+    try {
+      if (!attempted.has(hostKey(new URL(origin)))) {
+        return origin;
+      }
+    } catch {
+      // skip malformed URLs
+    }
+  }
+  return undefined;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+}
+
+type CacheEntry = {
+  origins: string[];
+  fetchedAt: number;
+  ttl: number; // ms
+};
+
+// Shared across all clients in the process so the region list is fetched once.
+const regionCache = new Map<string, CacheEntry>();
+// Coalesces concurrent discovery fetches per origin: while one /settings/regions
+// request is in flight, other callers for the same origin await its result
+// rather than issuing their own (avoids a thundering herd when many requests
+// fail over at once).
+const inflight = new Map<string, Promise<string[]>>();
+
+/**
+ * Returns alternative region origins for `origin`, fetching /settings/regions
+ * if the cache is stale. Best-effort: on a fetch failure it serves a stale
+ * cached list when available, otherwise an empty list. Forwards `headers` so a
+ * valid token — and any test directives — reach the discovery endpoint.
+ */
+export async function regionOrigins(origin: URL, headers: unknown): Promise<string[]> {
+  const key = hostKey(origin);
+  const cached = regionCache.get(key);
+  if (cached && Date.now() - cached.fetchedAt < cached.ttl) {
+    return cached.origins;
+  }
+
+  const existing = inflight.get(key);
+  if (existing) {
+    return existing;
+  }
+  const request = (async () => {
+    try {
+      const { origins, ttl } = await fetchRegions(origin, headers);
+      // A zero TTL (e.g. Cache-Control: max-age=0) means "do not cache".
+      if (ttl > 0) {
+        regionCache.set(key, { origins, fetchedAt: Date.now(), ttl });
+      }
+      return origins;
+    } catch {
+      return cached?.origins ?? [];
+    } finally {
+      inflight.delete(key);
+    }
+  })();
+
+  inflight.set(key, request);
+  return request;
+}
+
+async function fetchRegions(
+  origin: URL,
+  headers: unknown,
+): Promise<{ origins: string[]; ttl: number }> {
+  // Forward the caller's headers (auth + any custom), minus body-specific ones.
+  const fetchHeaders: Record<string, string> = {};
+  for (const [k, v] of Object.entries((headers as Record<string, string>) ?? {})) {
+    if (k.toLowerCase() === 'content-type' || k.toLowerCase() === 'content-length') continue;
+    fetchHeaders[k] = v;
+  }
+
+  const response = await fetch(new URL('/settings/regions', origin.origin), {
+    method: 'GET',
+    headers: fetchHeaders,
+    // Short timeout so a slow/unreachable discovery endpoint doesn't stall the
+    // failover path.
+    signal: AbortSignal.timeout(2000),
+  });
+  if (!response.ok) {
+    throw new Error(`region discovery failed: ${response.status}`);
+  }
+  const ttl = parseMaxAge(response.headers.get('cache-control'));
+  const body = (await response.json()) as { regions?: Array<{ url?: string }> };
+  const origins = (body.regions ?? [])
+    .filter((r) => !!r.url)
+    .map((r) => new URL(toHttp(r.url!)).origin);
+  return { origins, ttl };
+}
+
+/**
+ * Returns the `max-age` from a Cache-Control header in milliseconds, or 0 when
+ * absent, non-positive, or unparseable (meaning "do not cache"). Only `max-age`
+ * is honored; other directives (including `s-maxage`, which targets shared
+ * proxies) are ignored.
+ */
+export function parseMaxAge(cacheControl: string | null): number {
+  if (!cacheControl) return 0;
+  for (const directive of cacheControl.split(',')) {
+    const trimmed = directive.trim().toLowerCase();
+    if (trimmed.startsWith('max-age=')) {
+      const secs = parseInt(trimmed.slice('max-age='.length), 10);
+      return Number.isFinite(secs) && secs > 0 ? secs * 1000 : 0;
+    }
+  }
+  return 0;
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   EncodedFileType,
   EncodingOptions,
   EncodingOptionsPreset,
+  FileOutput,
   GCPUpload,
   ImageCodec,
   ImageFileSuffix,
@@ -38,10 +39,13 @@ export {
   IngressVideoEncodingPreset,
   IngressVideoOptions,
   JobRestartPolicy,
+  MediaSource,
+  Output,
   ParticipantEgressRequest,
   ParticipantInfo,
   ParticipantInfo_State,
   ParticipantPermission,
+  ParticipantVideo,
   Room,
   RoomAgentDispatch,
   RoomCompositeEgressRequest,
@@ -61,14 +65,18 @@ export {
   SIPCallStatus,
   SegmentedFileOutput,
   SegmentedFileProtocol,
+  StartEgressRequest,
+  StorageConfig,
   StreamOutput,
   StreamProtocol,
+  TemplateSource,
   TrackCompositeEgressRequest,
   TrackEgressRequest,
   TrackInfo,
   TrackSource,
   TrackType,
   WebEgressRequest,
+  WebSource,
   VideoCodec,
   WebhookConfig,
 } from '@livekit/protocol';
@@ -78,7 +86,9 @@ export * from './ConnectorClient.js';
 export * from './EgressClient.js';
 export * from './grants.js';
 export * from './IngressClient.js';
+export * from './LiveKitAPI.js';
 export * from './RoomServiceClient.js';
 export * from './SipClient.js';
-export { TwirpError } from './TwirpRPC.js';
+export { ServerError, SipCallError, TwirpError } from './TwirpRPC.js';
+export type { ClientOptions } from './ClientOptions.js';
 export * from './WebhookReceiver.js';

package/src/version.ts

@@ -0,0 +1 @@
+export const SDK_VERSION = "2.18.0";