feat(boxsdkgen): Add configurable timeouts for SDKs (box/box-codegen#924) (#1361)

Co-authored-by: box-sdk-build <box-sdk-build@box.com>

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "482939a", "specHash": "77eac4b", "version": "4.4.0" }
+{ "engineHash": "bc04b80", "specHash": "77eac4b", "version": "4.4.0" }

docs/sdk-gen/client.md

@@ -17,6 +17,7 @@ divided across resource managers.
 - [Custom Base URLs](#custom-base-urls)
 - [Custom Agent Options](#custom-agent-options)
 - [Interceptors](#interceptors)
+- [Use Timeouts for API calls](#use-timeouts-for-api-calls)
 - [Use Proxy for API calls](#use-proxy-for-api-calls)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -181,6 +182,20 @@ const clientWithInterceptor: BoxClient = client.withInterceptors([
 ]);
 ```
 
+# Use Timeouts for API calls
+
+In order to configure timeout for API calls, call `client.withTimeouts(config)` to create a new client with timeout settings, leaving the original client unmodified.
+
+`timeoutMs` is in milliseconds and is applied to each request attempt.
+
+```js
+const newClient = client.withTimeouts({
+  timeoutMs: 30000,
+});
+```
+
+If `timeoutMs` is not provided or is less than or equal to `0`, no SDK timeout is applied.
+
 # Use Proxy for API calls
 
 In order to use a proxy for API calls, calling the `client.withProxy(proxyConfig)` method creates a new client, leaving the original client unmodified, with the username and password being optional.

docs/sdk-gen/configuration.md

@@ -13,6 +13,7 @@
   - [Network Exception Handling](#network-exception-handling)
   - [Customizing Retry Parameters](#customizing-retry-parameters)
   - [Custom Retry Strategy](#custom-retry-strategy)
+- [Timeouts](#timeouts)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -174,3 +175,24 @@ const networkSession = new NetworkSession({
 });
 const client = new BoxClient({ auth, networkSession });
 ```
+
+## Timeouts
+
+You can configure request timeout using `timeoutConfig` on `NetworkSession`.
+`timeoutMs` is in milliseconds and applies to each HTTP request attempt.
+
+```js
+const auth = new BoxDeveloperTokenAuth({ token: 'DEVELOPER_TOKEN_GOES_HERE' });
+const networkSession = new NetworkSession({
+  timeoutConfig: { timeoutMs: 30000 },
+});
+const client = new BoxClient({ auth, networkSession });
+```
+
+How timeout handling works:
+
+- The SDK applies timeout only when `timeoutMs` is provided and greater than `0`.
+- To disable SDK timeout handling, set `timeoutMs` to `0` (or a negative value), or omit `timeoutMs`.
+- On timeout, the request is aborted and treated as a network error (`Connection timeout after <timeoutMs>ms`); if retries are exhausted, the SDK throws `BoxSdkError`.
+- Timeout failures are handled as request exceptions, then retry behavior is controlled by the configured retry strategy.
+- Timeout applies to a single HTTP request attempt to the Box API (not the total time across all retries).

src/sdk-gen/client.ts

@@ -90,6 +90,7 @@ import { BoxSdkError } from './box/errors';
 import { FetchOptions } from './networking/fetchOptions';
 import { FetchResponse } from './networking/fetchResponse';
 import { BaseUrls } from './networking/baseUrls';
+import { TimeoutConfig } from './networking/timeoutConfig';
 import { ProxyConfig } from './networking/proxyConfig';
 import { AgentOptions } from './internal/utils';
 import { Interceptor } from './networking/interceptors';
@@ -279,6 +280,7 @@ export class BoxClient {
       | 'withExtraHeaders'
       | 'withCustomBaseUrls'
       | 'withProxy'
+      | 'withTimeouts'
       | 'withCustomAgentOptions'
       | 'withInterceptors'
     > &
@@ -739,6 +741,17 @@ export class BoxClient {
       networkSession: this.networkSession.withProxy(config),
     });
   }
+  /**
+   * Create a new client with custom timeouts that will be used for every API call
+   * @param {TimeoutConfig} config Timeout configuration.
+   * @returns {BoxClient}
+   */
+  withTimeouts(config: TimeoutConfig): BoxClient {
+    return new BoxClient({
+      auth: this.auth,
+      networkSession: this.networkSession.withTimeoutConfig(config),
+    });
+  }
   /**
    * Create a new client with a custom set of agent options that will be used for every API call
    * @param {AgentOptions} agentOptions Custom set of agent options that will be used for every API call

src/sdk-gen/networking/boxNetworkClient.ts

@@ -40,6 +40,55 @@ export const shouldIncludeBoxUaHeader = (options: FetchOptions) => {
   );
 };
 
+function createAbortSignalWithTimeout(
+  baseSignal: RequestInit['signal'],
+  timeoutMs: number
+): {
+  signal: AbortSignal;
+  clearTimeout: () => void;
+  didTimeout: () => boolean;
+} {
+  const controller = new AbortController();
+  const upstream = baseSignal as unknown as AbortSignal | undefined;
+  let timedOut = false;
+
+  const abortFromUpstream = () => {
+    try {
+      (controller as any).abort((upstream as any)?.reason);
+    } catch {
+      controller.abort();
+    }
+  };
+
+  if (upstream) {
+    if (upstream.aborted) {
+      abortFromUpstream();
+    } else {
+      upstream.addEventListener('abort', abortFromUpstream, { once: true });
+    }
+  }
+
+  const timeoutId = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  // Node.js timers keep the event loop alive. If the only pending work is this
+  // watchdog timeout, we don't want it to prevent process exit (e.g. short CLI
+  // runs, tests, scripts). `unref()` detaches the timer from the event loop.
+  // It’s a no-op in environments where `unref` isn’t available.
+  (timeoutId as any)?.unref?.();
+
+  return {
+    signal: controller.signal,
+    clearTimeout: () => {
+      clearTimeout(timeoutId);
+      if (upstream) upstream.removeEventListener('abort', abortFromUpstream);
+    },
+    didTimeout: () => timedOut,
+  };
+}
+
 type FetchOptionsExtended = FetchOptions & {
   attemptNumber?: number;
   numberOfRetriesOnException?: number;
@@ -193,19 +242,33 @@ export class BoxNetworkClient implements NetworkClient {
         : void 0,
     });
 
+    const timeoutConfig = fetchOptions.networkSession?.timeoutConfig;
+    const timeoutMs = timeoutConfig?.timeoutMs;
+
+    const requestTimeout =
+      timeoutMs != null && timeoutMs > 0
+        ? createAbortSignalWithTimeout(requestInit.signal, timeoutMs)
+        : undefined;
+    const requestInitWithTimeout: RequestInit = requestTimeout
+      ? {
+          ...requestInit,
+          signal: requestTimeout.signal as unknown as RequestInit['signal'],
+        }
+      : requestInit;
+
     try {
-      const response = await nodeFetch(
-        ''.concat(
-          fetchOptions.url,
-          Object.keys(params).length === 0 || fetchOptions.url.endsWith('?')
-            ? ''
-            : '?',
-          new URLSearchParams(params).toString()
-        ),
-        { ...requestInit, redirect: isBrowser() ? 'follow' : 'manual' }
+      const requestUrl = ''.concat(
+        fetchOptions.url,
+        Object.keys(params).length === 0 || fetchOptions.url.endsWith('?')
+          ? ''
+          : '?',
+        new URLSearchParams(params).toString()
       );
+      const response = await nodeFetch(requestUrl, {
+        ...requestInitWithTimeout,
+        redirect: isBrowser() ? 'follow' : 'manual',
+      });
 
-      const contentType = response.headers.get('content-type') ?? '';
       const ignoreResponseBody = fetchOptions.followRedirects === false;
 
       let data: SerializedData | undefined;
@@ -244,8 +307,14 @@ export class BoxNetworkClient implements NetworkClient {
     } catch (error) {
       isExceptionCase = true;
       numberOfRetriesOnException++;
-      caughtError = error instanceof Error ? error : new Error(String(error));
+      if (requestTimeout?.didTimeout()) {
+        caughtError = new Error(`Connection timeout after ${timeoutMs}ms`);
+      } else {
+        caughtError = error instanceof Error ? error : new Error(String(error));
+      }
       fetchResponse = fetchResponse ?? { status: 0, headers: {} };
+    } finally {
+      requestTimeout?.clearTimeout();
     }
     const attemptForRetry = isExceptionCase
       ? numberOfRetriesOnException
@@ -325,7 +394,7 @@ export class BoxNetworkClient implements NetworkClient {
       : [];
     if (fetchResponse.status === 0) {
       throw new BoxSdkError({
-        message: `Unexpected Error occurred`,
+        message: caughtError?.message || `Unexpected Error occurred`,
         timestamp: `${Date.now()}`,
         error: caughtError,
       });

src/sdk-gen/networking/network.ts

@@ -5,6 +5,7 @@ import { Agent } from '../internal/utils';
 import { AgentOptions } from '../internal/utils';
 import { createAgent } from '../internal/utils';
 import { ProxyConfig } from './proxyConfig';
+import { TimeoutConfig } from './timeoutConfig';
 import { BoxNetworkClient } from './boxNetworkClient';
 import { NetworkClient } from './networkClient';
 import { RetryStrategy } from './retries';
@@ -22,6 +23,7 @@ export class NetworkSession {
   readonly networkClient: NetworkClient = new BoxNetworkClient({});
   readonly retryStrategy: RetryStrategy = new BoxRetryStrategy({});
   readonly dataSanitizer: DataSanitizer = new DataSanitizer({});
+  readonly timeoutConfig?: TimeoutConfig;
   constructor(
     fields: Omit<
       NetworkSession,
@@ -40,6 +42,7 @@ export class NetworkSession {
       | 'withNetworkClient'
       | 'withRetryStrategy'
       | 'withDataSanitizer'
+      | 'withTimeoutConfig'
     > &
       Partial<
         Pick<
@@ -81,6 +84,9 @@ export class NetworkSession {
     if (fields.dataSanitizer !== undefined) {
       this.dataSanitizer = fields.dataSanitizer;
     }
+    if (fields.timeoutConfig !== undefined) {
+      this.timeoutConfig = fields.timeoutConfig;
+    }
   }
   /**
      * Generate a fresh network session by duplicating the existing configuration and network parameters, while also including additional headers to be attached to every API call.
@@ -122,6 +128,7 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -140,6 +147,7 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -158,6 +166,7 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -176,6 +185,7 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -194,6 +204,7 @@ export class NetworkSession {
       networkClient: networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -212,6 +223,7 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: retryStrategy,
       dataSanitizer: this.dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
     });
   }
   /**
@@ -231,6 +243,26 @@ export class NetworkSession {
       networkClient: this.networkClient,
       retryStrategy: this.retryStrategy,
       dataSanitizer: dataSanitizer,
+      timeoutConfig: this.timeoutConfig,
+    });
+  }
+  /**
+   * Generate a fresh network session by duplicating the existing configuration and network parameters, while also applying timeout config
+   * @param {TimeoutConfig} timeoutConfig
+   * @returns {NetworkSession}
+   */
+  withTimeoutConfig(timeoutConfig: TimeoutConfig): NetworkSession {
+    return new NetworkSession({
+      additionalHeaders: this.additionalHeaders,
+      baseUrls: this.baseUrls,
+      interceptors: this.interceptors,
+      agent: this.agent,
+      agentOptions: this.agentOptions,
+      proxyConfig: this.proxyConfig,
+      networkClient: this.networkClient,
+      retryStrategy: this.retryStrategy,
+      dataSanitizer: this.dataSanitizer,
+      timeoutConfig: timeoutConfig,
     });
   }
 }
@@ -246,4 +278,5 @@ export interface NetworkSessionInput {
   readonly networkClient?: NetworkClient;
   readonly retryStrategy?: RetryStrategy;
   readonly dataSanitizer?: DataSanitizer;
+  readonly timeoutConfig?: TimeoutConfig;
 }

src/sdk-gen/networking/timeoutConfig.ts

@@ -0,0 +1,3 @@
+export interface TimeoutConfig {
+  readonly timeoutMs?: number;
+}

tests/sdk-gen/client.test.ts

@@ -37,6 +37,7 @@ import { FileFull } from '@/schemas/fileFull';
 import { ResponseFormat } from '@/networking/fetchOptions';
 import { UserFull } from '@/schemas/userFull';
 import { CreateUserRequestBody } from '@/managers/users';
+import { TimeoutConfig } from '@/networking/timeoutConfig';
 import { getUuid } from '@/internal/utils';
 import { generateByteStream } from '@/internal/utils';
 import { bufferEquals } from '@/internal/utils';
@@ -368,6 +369,22 @@ test('testWithCustomBaseUrls', async function testWithCustomBaseUrls(): Promise<
     await customBaseClient.users.getUserMe();
   }).rejects.toThrow();
 });
+test('testWithTimeoutWhenTimeoutOccurs', async function testWithTimeoutWhenTimeoutOccurs(): Promise<any> {
+  const timeoutMs: number = 1;
+  const clientWithTimeout: BoxClient = client.withTimeouts({
+    timeoutMs: timeoutMs,
+  } satisfies TimeoutConfig);
+  await expect(async () => {
+    await clientWithTimeout.users.getUserMe();
+  }).rejects.toThrow();
+});
+test('testWithTimeoutWhenTimeoutDoesNotOccur', async function testWithTimeoutWhenTimeoutDoesNotOccur(): Promise<any> {
+  const timeoutMs: number = 10000;
+  const clientWithTimeout: BoxClient = client.withTimeouts({
+    timeoutMs: timeoutMs,
+  } satisfies TimeoutConfig);
+  await clientWithTimeout.users.getUserMe();
+});
 test('testWithInterceptors', async function testWithInterceptors(): Promise<any> {
   const user: UserFull = await client.users.getUserMe();
   if (!(user.role == void 0)) {