Timeouts overhaul (#81)

* timeouts overhaul

* keyspace impl & tests

* more tests & tweaks

* fix timeout/sort bgus

* refined WithTimeout types

* createCollection custom timeout impl

* more docs and stuff

Author: toptobes

src/administration/astra-admin.ts

@@ -14,8 +14,6 @@
 // noinspection ExceptionCaughtLocallyJS
 
 import {
-  AdminSpawnOptions,
-  AstraAdminBlockingOptions,
   AstraDatabaseConfig,
   CreateAstraDatabaseOptions,
   ListAstraDatabasesOptions,
@@ -31,9 +29,11 @@ import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { InternalRootClientOpts } from '@/src/client/types/internal';
 import { buildAstraEndpoint } from '@/src/lib/utils';
 import { Logger } from '@/src/lib/logging/logger';
-import { DbSpawnOptions } from '@/src/client';
+import { AdminSpawnOptions, DbSpawnOptions } from '@/src/client';
 import { $CustomInspect } from '@/src/lib/constants';
 import { SomeDoc } from '@/src/documents';
+import { Timeouts } from '@/src/lib/api/timeouts';
+import { DropAstraDatabaseOptions } from '@/src/administration/types/admin/drop-database';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting databases.
@@ -84,6 +84,7 @@ export class AstraAdmin {
         logging: Logger.advanceConfig(rootOpts.adminOptions.logging, adminOpts?.logging),
         additionalHeaders: { ...rootOpts.adminOptions.additionalHeaders, ...adminOpts?.additionalHeaders },
         astraEnv: adminOpts?.astraEnv ?? rootOpts.adminOptions.astraEnv,
+        timeoutDefaults: Timeouts.merge(rootOpts.adminOptions.timeoutDefaults, adminOpts?.timeoutDefaults),
       },
       dbOptions: {
         ...rootOpts.dbOptions,
@@ -101,6 +102,7 @@ export class AstraAdmin {
       userAgent: rootOpts.userAgent,
       tokenProvider: this.#defaultOpts.adminOptions.adminToken,
       additionalHeaders: this.#defaultOpts.adminOptions.additionalHeaders,
+      timeoutDefaults: Timeouts.merge(rootOpts.adminOptions.timeoutDefaults, this.#defaultOpts.adminOptions.timeoutDefaults),
     });
 
     Object.defineProperty(this, $CustomInspect, {
@@ -283,11 +285,13 @@ export class AstraAdmin {
    *
    * @returns A promise that resolves to the complete database information.
    */
-  public async dbInfo(id: string, options?: WithTimeout): Promise<AstraDbAdminInfo> {
+  public async dbInfo(id: string, options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo> {
+    const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
+
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases/${id}`,
-    }, options);
+    }, tm);
 
     return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
   }
@@ -337,11 +341,13 @@ export class AstraAdmin {
       params['starting_after'] = String(options.skip);
     }
 
+    const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
+
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases`,
       params: params,
-    }, options);
+    }, tm);
 
     return resp.data!.map((d: SomeDoc) => buildAstraDatabaseAdminInfo(d, this.#environment));
   }
@@ -407,6 +413,8 @@ export class AstraAdmin {
       ...config,
     };
 
+    const tm = this.#httpClient.tm.multipart('databaseAdminTimeoutMs', options);
+
     const resp = await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: '/databases',
@@ -416,6 +424,7 @@ export class AstraAdmin {
       target: 'ACTIVE',
       legalStates: ['INITIALIZING', 'PENDING'],
       defaultPollInterval: 10000,
+      timeoutManager: tm,
       options,
     });
 
@@ -449,9 +458,11 @@ export class AstraAdmin {
    *
    * @remarks Use with caution. Wear a harness. Don't say I didn't warn you.
    */
-  public async dropDatabase(db: Db | string, options?: AstraAdminBlockingOptions): Promise<void> {
+  public async dropDatabase(db: Db | string, options?: DropAstraDatabaseOptions): Promise<void> {
     const id = typeof db === 'string' ? db : db.id;
 
+    const tm = this.#httpClient.tm.multipart('databaseAdminTimeoutMs', options);
+
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${id}/terminate`,
@@ -460,6 +471,7 @@ export class AstraAdmin {
       target: 'TERMINATED',
       legalStates: ['TERMINATING'],
       defaultPollInterval: 10000,
+      timeoutManager: tm,
       options,
     });
   }

src/administration/astra-db-admin.ts

@@ -14,24 +14,25 @@
 // noinspection ExceptionCaughtLocallyJS
 
 import {
-  AdminSpawnOptions,
-  AstraAdminBlockingOptions,
   AstraCreateKeyspaceOptions,
+  AstraDropKeyspaceOptions,
 } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
-import { WithTimeout } from '@/src/lib/types';
+import type { WithTimeout } from '@/src/lib';
+import { StaticTokenProvider, TokenProvider } from '@/src/lib';
 import { buildAstraDatabaseAdminInfo, extractAstraEnvironment } from '@/src/administration/utils';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { DEFAULT_DEVOPS_API_ENDPOINTS, HttpMethods } from '@/src/lib/api/constants';
 import { DevOpsAPIHttpClient } from '@/src/lib/api/clients/devops-api-http-client';
 import { Db } from '@/src/db';
-import { StaticTokenProvider, TokenProvider } from '@/src/lib';
 import { isNullish } from '@/src/lib/utils';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { InternalRootClientOpts } from '@/src/client/types/internal';
 import { $CustomInspect } from '@/src/lib/constants';
 import { AstraDbAdminInfo } from '@/src/administration/types/admin/database-info';
 import { Logger } from '@/src/lib/logging/logger';
+import { TimeoutManager, Timeouts } from '@/src/lib/api/timeouts';
+import { AdminSpawnOptions } from '@/src/client';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting keyspaces.
@@ -97,6 +98,7 @@ export class AstraDbAdmin extends DbAdmin {
       userAgent: rootOpts.userAgent,
       tokenProvider: adminToken,
       additionalHeaders: { ...rootOpts.adminOptions.additionalHeaders, ...adminOpts?.additionalHeaders },
+      timeoutDefaults: Timeouts.merge(rootOpts.adminOptions.timeoutDefaults, adminOpts?.timeoutDefaults),
     });
 
     this.#db = db;
@@ -152,8 +154,11 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns The available embedding providers.
    */
-  public override async findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult> {
-    const resp = await this.#db.command({ findEmbeddingProviders: {} }, { keyspace: null, maxTimeMS: options?.maxTimeMS });
+  public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
+    const resp = await this.#db._httpClient.executeCommand({ findEmbeddingProviders: {} }, {
+      timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
+      keyspace: null,
+    });
     return resp.status as FindEmbeddingProvidersResult;
   }
 
@@ -172,13 +177,9 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves to the complete database information.
    */
-  public async info(options?: WithTimeout): Promise<AstraDbAdminInfo> {
-    const resp = await this.#httpClient.request({
-      method: HttpMethods.Get,
-      path: `/databases/${this.#db.id}`,
-    }, options);
-
-    return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
+  public async info(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo> {
+    const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
+    return this.#info(tm);
   }
 
   /**
@@ -197,8 +198,9 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves to list of all the keyspaces in the database.
    */
-  public override async listKeyspaces(options?: WithTimeout): Promise<string[]> {
-    return this.info(options).then(i => i.keyspaces);
+  public override async listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]> {
+    const tm = this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options);
+    return this.#info(tm).then(i => i.keyspaces);
   }
 
   /**
@@ -236,6 +238,8 @@ export class AstraDbAdmin extends DbAdmin {
       this.#db.useKeyspace(keyspace);
     }
 
+    const tm = this.#httpClient.tm.multipart('keyspaceAdminTimeoutMs', options);
+
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
@@ -244,6 +248,7 @@ export class AstraDbAdmin extends DbAdmin {
       target: 'ACTIVE',
       legalStates: ['MAINTENANCE'],
       defaultPollInterval: 1000,
+      timeoutManager: tm,
       options,
     });
   }
@@ -279,7 +284,9 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async dropKeyspace(keyspace: string, options?: AstraAdminBlockingOptions): Promise<void> {
+  public override async dropKeyspace(keyspace: string, options?: AstraDropKeyspaceOptions): Promise<void> {
+    const tm = this.#httpClient.tm.multipart('keyspaceAdminTimeoutMs', options);
+
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Delete,
       path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
@@ -288,6 +295,7 @@ export class AstraDbAdmin extends DbAdmin {
       target: 'ACTIVE',
       legalStates: ['MAINTENANCE'],
       defaultPollInterval: 1000,
+      timeoutManager: tm,
       options,
     });
   }
@@ -313,7 +321,9 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @remarks Use with caution. Use a surge protector. Don't say I didn't warn you.
    */
-  public async drop(options?: AstraAdminBlockingOptions): Promise<void> {
+  public async drop(options?: AstraDropKeyspaceOptions): Promise<void> {
+    const tm = this.#httpClient.tm.multipart('databaseAdminTimeoutMs', options);
+
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this.#db.id}/terminate`,
@@ -322,11 +332,21 @@ export class AstraDbAdmin extends DbAdmin {
       target: 'TERMINATED',
       legalStates: ['TERMINATING'],
       defaultPollInterval: 10000,
+      timeoutManager: tm,
       options,
     });
   }
 
   public get _httpClient() {
     return this.#httpClient;
   }
+
+  async #info(tm: TimeoutManager): Promise<AstraDbAdminInfo> {
+    const resp = await this.#httpClient.request({
+      method: HttpMethods.Get,
+      path: `/databases/${this.#db.id}`,
+    }, tm);
+
+    return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
+  }
 }

src/administration/data-api-db-admin.ts

@@ -13,14 +13,15 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminSpawnOptions, LocalCreateKeyspaceOptions } from '@/src/administration/types';
+import { LocalCreateKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
-import { WithTimeout } from '@/src/lib/types';
+import type { WithTimeout } from '@/src/lib';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { DataAPIHttpClient } from '@/src/lib/api/clients/data-api-http-client';
 import { Db } from '@/src/db';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { $CustomInspect } from '@/src/lib/constants';
+import { AdminSpawnOptions } from '@/src/client';
 
 /**
  * An administrative class for managing non-Astra databases, including creating, listing, and deleting keyspaces.
@@ -112,8 +113,11 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns The available embedding providers.
    */
-  public override async findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult> {
-    const resp = await this.#httpClient.executeCommand({ findEmbeddingProviders: {} }, { keyspace: null, maxTimeMS: options?.maxTimeMS });
+  public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
+    const resp = await this.#httpClient.executeCommand({ findEmbeddingProviders: {} }, {
+      timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
+      keyspace: null,
+    });
     return resp.status as FindEmbeddingProvidersResult;
   }
 
@@ -133,8 +137,11 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves to list of all the keyspaces in the database.
    */
-  public override async listKeyspaces(options?: WithTimeout): Promise<string[]> {
-    const resp = await this.#httpClient.executeCommand({ findKeyspaces: {} }, { maxTimeMS: options?.maxTimeMS, keyspace: null });
+  public override async listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]> {
+    const resp = await this.#httpClient.executeCommand({ findKeyspaces: {} }, {
+      timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      keyspace: null,
+    });
     return resp.status!.keyspaces;
   }
 
@@ -178,7 +185,10 @@ export class DataAPIDbAdmin extends DbAdmin {
       replicationFactor: 1,
     };
 
-    await this.#httpClient.executeCommand({ createKeyspace: { name: keyspace, options: { replication } } }, { maxTimeMS: options?.maxTimeMS, keyspace: null });
+    await this.#httpClient.executeCommand({ createKeyspace: { name: keyspace, options: { replication } } }, {
+      timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      keyspace: null,
+    });
   }
 
   /**
@@ -202,8 +212,11 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async dropKeyspace(keyspace: string, options?: WithTimeout): Promise<void> {
-    await this.#httpClient.executeCommand({ dropKeyspace: { name: keyspace } }, { maxTimeMS: options?.maxTimeMS, keyspace: null });
+  public override async dropKeyspace(keyspace: string, options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<void> {
+    await this.#httpClient.executeCommand({ dropKeyspace: { name: keyspace } }, {
+      timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      keyspace: null,
+    });
   }
 
   public get _httpClient() {

src/administration/db-admin.ts

@@ -63,7 +63,7 @@ export abstract class DbAdmin {
    *
    * @returns The available embedding providers.
    */
-  abstract findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult>;
+  abstract findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult>;
   /**
    * Retrieves a list of all the keyspaces in the database.
    *
@@ -80,7 +80,7 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves to list of all the keyspaces in the database.
    */
-  abstract listKeyspaces(): Promise<string[]>;
+  abstract listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]>;
   /**
    * Creates a new, additional, keyspace for this database.
    *
@@ -111,7 +111,7 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  abstract createKeyspace(keyspace: string, options?: WithTimeout): Promise<void>;
+  abstract createKeyspace(keyspace: string, options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<void>;
   /**
    * Drops a keyspace from this database.
    *
@@ -143,5 +143,5 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  abstract dropKeyspace(keyspace: string, options?: WithTimeout): Promise<void>;
+  abstract dropKeyspace(keyspace: string, options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<void>;
 }