Added extended http1 options (#33)

You can now set, through the `DataAPIClient`, the following options:
- `preferHttp2`
- `maxTimeMS` (default maxTimeMS)
- `http1.keepAlive`
- `http1.keepAliveMs`
- `http1.maxSockets`
- `http1.maxFreeSockets`

The `preferHttp2` field directly on the `DataAPIClientOptions` is deprecated, with a message to prefer to use the one in `DataAPIHttpOptions` instead

Author: toptobes

src/api/data-api-http-client.ts

@@ -24,7 +24,7 @@ import {
   RawDataAPIResponse,
 } from '@/src/api';
 import { DataAPIResponseError, DataAPITimeoutError, ObjectId, UUID, WithNamespace } from '@/src/data-api';
-import { MkTimeoutError, TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
+import { TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
 import { CommandFailedEvent, CommandStartedEvent, CommandSucceededEvent } from '@/src/data-api/events';
 import { CollectionNotFoundError, DataAPIHttpError, mkRespErrorFromResponse } from '@/src/data-api/errors';
 
@@ -56,10 +56,6 @@ export class DataAPIHttpClient extends HttpClient {
     super({
       ...props,
       mkAuthHeader: (token) => ({ [DEFAULT_DATA_API_AUTH_HEADER]: token }),
-      fetchCtx: {
-        preferred: props.fetchCtx.preferred,
-        closed: props.fetchCtx.closed,
-      },
     });
     this.namespace = props.namespace;
     this.#props = props;
@@ -73,11 +69,11 @@ export class DataAPIHttpClient extends HttpClient {
   }
 
   public timeoutManager(timeoutMs: number | undefined) {
-    return mkTimeoutManager(timeoutMs);
+    return this._mkTimeoutManager(timeoutMs);
   }
 
   public async executeCommand(command: Record<string, any>, options: TimeoutOptions & ExecuteCommandOptions | undefined) {
-    const timeoutManager = options?.timeoutManager ?? mkTimeoutManager(options?.maxTimeMS);
+    const timeoutManager = options?.timeoutManager ?? this._mkTimeoutManager(options?.maxTimeMS);
 
     return await this._requestDataAPI({
       url: this.baseUrl,
@@ -149,15 +145,11 @@ export class DataAPIHttpClient extends HttpClient {
       throw e;
     }
   }
-}
-
-const mkTimeoutManager = (maxMs: number | undefined) => {
-  const timeout = maxMs ?? DEFAULT_TIMEOUT;
-  return new TimeoutManager(timeout, mkTimeoutErrorMaker(timeout));
-}
 
-const mkTimeoutErrorMaker = (timeout: number): MkTimeoutError => {
-  return () => new DataAPITimeoutError(timeout);
+  private _mkTimeoutManager(timeout: number | undefined) {
+    timeout ??= this.fetchCtx.maxTimeMS ?? DEFAULT_TIMEOUT;
+    return new TimeoutManager(timeout, () => new DataAPITimeoutError(timeout));
+  }
 }
 
 const mkFauxErroredResponse = (message: string): RawDataAPIResponse => {

src/api/devops-api-http-client.ts

@@ -17,7 +17,7 @@ import { hrTimeMs, HttpClient } from '@/src/api/http-client';
 import { APIResponse, HTTPClientOptions, HttpMethodStrings } from '@/src/api/types';
 import { DevOpsAPIResponseError, DevOpsAPITimeoutError, DevOpsUnexpectedStateError } from '@/src/devops/errors';
 import { AdminBlockingOptions } from '@/src/devops/types';
-import { MkTimeoutError, TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
+import { TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
 import { DEFAULT_DEVOPS_API_AUTH_HEADER, HttpMethods } from '@/src/api/constants';
 import {
   AdminCommandFailedEvent,
@@ -56,17 +56,17 @@ export class DevOpsAPIHttpClient extends HttpClient {
       ...props,
       mkAuthHeader: (token) => ({ [DEFAULT_DEVOPS_API_AUTH_HEADER]: `Bearer ${token}` }),
       fetchCtx: {
+        ...props.fetchCtx,
         preferred: props.fetchCtx.http1,
-        closed: props.fetchCtx.closed,
-      }
+      },
     });
   }
 
   public async request(req: DevOpsAPIRequestInfo, options: TimeoutOptions | undefined, started: number = 0): Promise<APIResponse> {
     const isLongRunning = started !== 0;
 
     try {
-      const timeoutManager = options?.timeoutManager ?? mkTimeoutManager(options?.maxTimeMS);
+      const timeoutManager = options?.timeoutManager ?? this._mkTimeoutManager(options?.maxTimeMS);
       const url = this.baseUrl + req.path;
 
       if (this.monitorCommands && !isLongRunning) {
@@ -112,7 +112,7 @@ export class DevOpsAPIHttpClient extends HttpClient {
   }
 
   public async requestLongRunning(req: DevOpsAPIRequestInfo, info: LongRunningRequestInfo): Promise<APIResponse> {
-    const timeoutManager = mkTimeoutManager(info.options?.maxTimeMS);
+    const timeoutManager = this._mkTimeoutManager(info.options?.maxTimeMS);
     const isLongRunning = info?.options?.blocking !== false;
 
     if (this.monitorCommands) {
@@ -183,13 +183,9 @@ export class DevOpsAPIHttpClient extends HttpClient {
       });
     }
   }
-}
 
-const mkTimeoutManager = (maxMs: number | undefined) => {
-  const timeout = maxMs ?? 0;
-  return new TimeoutManager(timeout, mkTimeoutErrorMaker(timeout));
-}
-
-const mkTimeoutErrorMaker = (timeout: number): MkTimeoutError => {
-  return (info) => new DevOpsAPITimeoutError(info.url, timeout);
+  private _mkTimeoutManager(timeout: number | undefined) {
+    timeout ??= this.fetchCtx.maxTimeMS ?? (12 * 60 * 1000);
+    return new TimeoutManager(timeout, (info) => new DevOpsAPITimeoutError(info.url, timeout));
+  }
 }

src/api/types.ts

@@ -47,6 +47,7 @@ export interface FetchCtx {
   http1: ReturnType<typeof context>,
   preferredType: 'http1' | 'http2',
   closed: { ref: boolean },
+  maxTimeMS: number | undefined,
 }
 
 /**
@@ -55,6 +56,7 @@ export interface FetchCtx {
 export interface InternalFetchCtx {
   preferred: ReturnType<typeof context>,
   closed: { ref: boolean },
+  maxTimeMS: number | undefined,
 }
 
 /**

src/client/data-api-client.ts

@@ -11,22 +11,24 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+// noinspection JSDeprecatedSymbols
 
 import { Db, mkDb, validateDbOpts } from '@/src/data-api/db';
 import { AstraAdmin, mkAdmin, validateAdminOpts } from '@/src/devops/astra-admin';
 import {
   AdminSpawnOptions,
   Caller,
+  DataAPIClientOptions,
+  DataAPIHttpOptions,
   DbSpawnOptions,
   InternalRootClientOpts,
-  DataAPIClientOptions,
 } from '@/src/client/types';
 import TypedEmitter from 'typed-emitter';
 import EventEmitter from 'events';
 import { DataAPICommandEvents } from '@/src/data-api/events';
 import { AdminCommandEvents } from '@/src/devops';
 import { validateOption } from '@/src/data-api/utils';
-import { context } from 'fetch-h2';
+import { context, ContextOptions } from 'fetch-h2';
 import { buildUserAgent } from '@/src/api';
 
 /**
@@ -103,17 +105,25 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
 
     validateRootOpts(options);
 
-    const baseCtxOptions = {
+    const baseCtxOptions: Partial<ContextOptions> = {
       userAgent: buildUserAgent(options?.caller),
       overwriteUserAgent: true,
+      http1: {
+        keepAlive: options?.httpOptions?.http1?.keepAlive,
+        keepAliveMsecs: options?.httpOptions?.http1?.keepAliveMS,
+        maxSockets: options?.httpOptions?.http1?.maxSockets,
+        maxFreeSockets: options?.httpOptions?.http1?.maxFreeSockets,
+      },
     };
 
     const http1Ctx = context({
       ...baseCtxOptions,
       httpsProtocols: ['http1'],
     });
 
-    const preferredCtx = (options?.preferHttp2 !== false)
+    const preferHttp2 = options?.httpOptions?.preferHttp2 ?? getDeprecatedPrefersHttp2(options) ?? true;
+
+    const preferredCtx = (preferHttp2)
       ? context(baseCtxOptions)
       : http1Ctx;
 
@@ -122,10 +132,11 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
       fetchCtx: {
         http1: http1Ctx,
         preferred: preferredCtx,
-        preferredType: (options?.preferHttp2 !== false)
+        preferredType: (preferHttp2)
           ? 'http2'
           : 'http1',
         closed: { ref: false },
+        maxTimeMS: options?.httpOptions?.maxTimeMS,
       },
       dbOptions: {
         monitorCommands: false,
@@ -299,6 +310,11 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
   public [Symbol.asyncDispose]!: () => Promise<void>;
 }
 
+// Shuts the linter up about 'preferHttp2' not being deprecated
+function getDeprecatedPrefersHttp2(opts: DataAPIClientOptions | undefined | null) {
+  return opts?.[('preferHttp2' as any as null)!];
+}
+
 function validateRootOpts(opts: DataAPIClientOptions | undefined | null) {
   validateOption('root client options', opts, 'object');
 
@@ -307,12 +323,29 @@ function validateRootOpts(opts: DataAPIClientOptions | undefined | null) {
   }
 
   validateOption('caller', opts.caller, 'object', validateCaller);
-
-  validateOption('preferHttp2 option', opts.preferHttp2, 'boolean');
+  validateOption('preferHttp2 option', getDeprecatedPrefersHttp2(opts), 'boolean');
 
   validateDbOpts(opts.dbOptions);
-
   validateAdminOpts(opts.adminOptions);
+  validateHttpOpts(opts.httpOptions);
+}
+
+function validateHttpOpts(opts: DataAPIHttpOptions | undefined | null) {
+  validateOption('http options', opts, 'object');
+
+  if (!opts) {
+    return;
+  }
+
+  validateOption('preferHttp2 option', opts.preferHttp2, 'boolean');
+  validateOption('maxTimeMS option', opts.maxTimeMS, 'number');
+
+  validateOption('http1 options', opts.http1, 'object', (http1) => {
+    validateOption('http1.keepAlive option', http1.keepAlive, 'boolean');
+    validateOption('http1.keepAliveMS option', http1.keepAliveMS, 'number');
+    validateOption('http1.maxSockets option', http1.maxSockets, 'number');
+    validateOption('http1.maxFreeSockets option', http1.maxFreeSockets, 'number');
+  });
 }
 
 function validateCaller(caller: Caller | Caller[]) {

src/client/types.ts

@@ -44,15 +44,9 @@ export type Caller = [name: string, version?: string];
  */
 export interface DataAPIClientOptions {
   /**
-   * Whether to prefer HTTP/2 for requests to the Data API.
-   *
-   * Both versions are generally interchangeable, but HTTP2 is generally recommended for better performance.
-   *
-   * Defaults to `true` if never provided.
-   *
-   * @defaultValue true
+   * The client-wide options related to http operations.
    */
-  preferHttp2?: boolean,
+  httpOptions?: DataAPIHttpOptions,
   /**
    * The default options when spawning a {@link Db} instance.
    */
@@ -90,6 +84,83 @@ export interface DataAPIClientOptions {
    * ```
    */
   caller?: Caller | Caller[],
+  /**
+   * **Prefer to use the {@link httpOptions} property instead.**
+   *
+   * @deprecated
+   *
+   * @see DataAPIHttpOptions
+   */
+  preferHttp2?: boolean,
+}
+
+/**
+ * The options available for the {@link DataAPIClient} related to making HTTP requests.
+ */
+export interface DataAPIHttpOptions {
+  /**
+   * Whether to prefer HTTP/2 for requests to the Data API; if set to `false`, HTTP/1.1 will be used instead.
+   *
+   * **Note that this is only available when using the Data API; the DevOps API does not support HTTP/2**
+   *
+   * Both versions are generally interchangeable, but HTTP2 is generally recommended for better performance.
+   *
+   * Defaults to `true` if never provided.
+   *
+   * @defaultValue true
+   */
+  preferHttp2?: boolean,
+  /**
+   * The default maximum time in milliseconds to wait for a response from the server.
+   *
+   * This does *not* mean the request will be cancelled after this time, but rather that the client will wait
+   * for this time before considering the request to have timed out.
+   *
+   * The request may or may not still be running on the server after this time.
+   */
+  maxTimeMS?: number,
+  /**
+   * Options specific to HTTP/1.1 requests.
+   */
+  http1?: DataAPIHttp1Options,
+}
+
+/**
+ * The options available for the {@link DataAPIClient} related to making HTTP/1.1 requests.
+ */
+export interface DataAPIHttp1Options {
+  /**
+   * Whether to keep the connection alive for future requests. This is generally recommended for better performance.
+   *
+   * Defaults to true.
+   *
+   * @defaultValue true
+   */
+  keepAlive?: boolean,
+  /**
+   * The delay (in milliseconds) before keep-alive probing.
+   *
+   * Defaults to 1000ms.
+   *
+   * @defaultValue 1000
+   */
+  keepAliveMS?: number,
+  /**
+   * Maximum number of sockets to allow per origin.
+   *
+   * Defaults to 256.
+   *
+   * @defaultValue 256
+   */
+  maxSockets?: number,
+  /**
+   * Maximum number of lingering sockets, waiting to be re-used for new requests.
+   *
+   * Defaults to Infinity.
+   *
+   * @defaultValue Infinity
+   */
+  maxFreeSockets?: number,
 }
 
 /**

src/data-api/types/collections/list-collection.ts

@@ -30,7 +30,7 @@ export interface ListCollectionsCommand {
  *
  * @field nameOnly - If true, only the name of the collection is returned. If false, the full collection info is returned. Defaults to true.
  * @field namespace - Overrides the namespace to list collections from. If not provided, the default namespace is used.
- * @field maxTimeMs - The maximum amount of time to allow the operation to run.
+ * @field maxTimeMS - The maximum amount of time to allow the operation to run.
  *
  * @see Db.listCollections
  *

src/data-api/utils.ts

@@ -70,7 +70,7 @@ export function replaceAstraUrlIdAndRegion(uri: string, id: string, region: stri
 /**
  * @internal
  */
-export function validateOption<T = unknown>(name: string, obj: unknown, type: string, test?: (obj: T) => void): void {
+export function validateOption<T>(name: string, obj: T, type: string, test?: (obj: NonNullable<T>) => void): void {
   if (obj === null || obj === undefined) {
     return;
   }
@@ -79,7 +79,7 @@ export function validateOption<T = unknown>(name: string, obj: unknown, type: st
     throw new TypeError(`Invalid ${name}; expected a ${type} value, or undefined/null`);
   }
 
-  test?.(obj as T);
+  test?.(obj);
 }
 
 /**

tests/fixtures.ts

@@ -34,7 +34,7 @@ export const initTestObjects = async (ctx: Context, preferHttp2 = USE_HTTP2): Pr
     ctx.skip();
   }
 
-  const client = new DataAPIClient(process.env.APPLICATION_TOKEN!, { preferHttp2 });
+  const client = new DataAPIClient(process.env.APPLICATION_TOKEN!, { httpOptions: { preferHttp2 } });
   const db = client.db(process.env.ASTRA_URI!);
 
   const coll = (!collCreated)