Add optional timeouts to clients in server APIs (#560)

* Add timeout option to server clients

* Rename

* Share options type; remove ctor docs

* Re-word

* Format

* License header

* Create honest-apes-sparkle.md

---------

Co-authored-by: lukasIO <[email protected]>

Author: bryfox

.changeset/honest-apes-sparkle.md

@@ -0,0 +1,5 @@
+---
+"livekit-server-sdk": patch
+---
+
+Add optional timeouts to clients in server APIs

packages/livekit-server-sdk/src/AgentDispatchClient.ts

@@ -8,6 +8,7 @@ import {
   ListAgentDispatchRequest,
   ListAgentDispatchResponse,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import { type Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
 
@@ -29,10 +30,14 @@ export class AgentDispatchClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
    * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

packages/livekit-server-sdk/src/ClientOptions.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Options common to all clients
+ */
+export type ClientOptions = {
+  /**
+   * Optional timeout, in seconds, for all server requests
+   */
+  requestTimeout?: number;
+};

packages/livekit-server-sdk/src/EgressClient.ts

@@ -25,6 +25,7 @@ import {
   UpdateStreamRequest,
   WebEgressRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -137,10 +138,14 @@ export class EgressClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
    * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

packages/livekit-server-sdk/src/IngressClient.ts

@@ -10,6 +10,7 @@ import {
   ListIngressResponse,
   UpdateIngressRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -124,10 +125,14 @@ export class IngressClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
    * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

packages/livekit-server-sdk/src/RoomServiceClient.ts

@@ -22,6 +22,7 @@ import {
   UpdateRoomMetadataRequest,
   UpdateSubscriptionsRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -120,10 +121,14 @@ export class RoomServiceClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
    * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

packages/livekit-server-sdk/src/SipClient.ts

@@ -39,6 +39,7 @@ import {
   UpdateSIPInboundTrunkRequest,
   UpdateSIPOutboundTrunkRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -216,10 +217,14 @@ export class SipClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
    * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

packages/livekit-server-sdk/src/TwirpRPC.ts

@@ -5,7 +5,15 @@ import type { JsonValue } from '@bufbuild/protobuf';
 
 // twirp RPC adapter for client implementation
 
+type Options = {
+  /** Prefix for the RPC requests */
+  prefix?: string;
+  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */
+  requestTimeout?: number;
+};
+
 const defaultPrefix = '/twirp';
+const defaultTimeoutSeconds = 60;
 
 export const livekitPackage = 'livekit';
 export interface Rpc {
@@ -48,21 +56,24 @@ export class TwirpRpc {
 
   prefix: string;
 
-  constructor(host: string, pkg: string, prefix?: string) {
+  requestTimeout: number;
+
+  constructor(host: string, pkg: string, options?: Options) {
     if (host.startsWith('ws')) {
       host = host.replace('ws', 'http');
     }
     this.host = host;
     this.pkg = pkg;
-    this.prefix = prefix || defaultPrefix;
+    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;
+    this.prefix = options?.prefix || defaultPrefix;
   }
 
   async request(
     service: string,
     method: string,
     data: any, // eslint-disable-line @typescript-eslint/no-explicit-any
     headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any
-    timeout = 60,
+    timeout = this.requestTimeout,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): Promise<any> {
     const path = `${this.prefix}/${this.pkg}.${service}/${method}`;