more docs, more http2 methods, more tests

Author: toptobes

src/api/http-client.ts

@@ -25,14 +25,11 @@ import { HTTP1AuthHeaderFactories, HTTP1Strategy } from '@/src/api/http1';
 import { HTTP2Strategy } from '@/src/api/http2';
 import { Mutable } from '@/src/data-api/types/utils';
 
-export const applicationTokenKey = Symbol('applicationToken');
-
 export class HttpClient {
   public readonly baseUrl: string;
   public readonly logSkippedOptions: boolean;
   public readonly userAgent: string;
   public requestStrategy: HTTPRequestStrategy;
-  // private [applicationTokenKey]!: string;
   #applicationToken: string;
 
   constructor(options: HTTPClientOptions) {
@@ -48,11 +45,6 @@ export class HttpClient {
       throw new Error("applicationToken required for initialization");
     }
 
-    // Object.defineProperty(this, applicationTokenKey, {
-    //   value: options.applicationToken,
-    //   enumerable: false,
-    //   writable: true,
-    // });
     this.#applicationToken = options.applicationToken;
 
     this.baseUrl = options.baseUrl;

src/api/http2.ts

@@ -16,13 +16,14 @@ import * as http2 from 'http2';
 import { HTTPRequestStrategy, GuaranteedAPIResponse, InternalHTTPRequestInfo } from '@/src/api/types';
 
 export class HTTP2Strategy implements HTTPRequestStrategy {
-  public origin: string;
+  #session: http2.ClientHttp2Session;
+
   public closed: boolean = false;
-  public session: http2.ClientHttp2Session;
+  public origin: string;
 
   constructor(baseURL: string) {
     this.origin = new URL(baseURL).origin;
-    this.session = this._reviveSession();
+    this.#session = this._reviveSession();
   }
 
   public async request(info: InternalHTTPRequestInfo): Promise<GuaranteedAPIResponse> {
@@ -33,16 +34,16 @@ export class HTTP2Strategy implements HTTPRequestStrategy {
 
       // Recreate session if session was closed except via an explicit `close()`
       // call. This happens when nginx sends a GOAWAY packet after 1000 requests.
-      if (this.session.closed) {
-        this.session = this._reviveSession();
+      if (this.#session.closed) {
+        this.#session = this._reviveSession();
       }
 
       const timer = setTimeout(() => reject(info.timeoutError()), info.timeout);
 
       const path = info.url.replace(this.origin, '');
       const params = info.params ? `?${new URLSearchParams(info.params).toString()}` : '';
 
-      const req = this.session.request({
+      const req = this.#session.request({
         ':path': path + params,
         ':method': info.method,
         token: info.token,
@@ -88,13 +89,13 @@ export class HTTP2Strategy implements HTTPRequestStrategy {
   }
 
   public close() {
-    this.session.close();
+    this.#session.close();
     this.closed = true;
   }
 
   private _reviveSession() {
-    if (this.session && !this.session.closed) {
-      return this.session;
+    if (this.#session && !this.#session.closed) {
+      return this.#session;
     }
 
     const session = http2.connect(this.origin);

src/client/data-api-client.ts

@@ -40,31 +40,29 @@ export class DataApiClient {
   constructor(token: string, options?: RootClientOptions) {
     this.#options = {
       ...options,
-      dataApiOptions: {
+      dbOptions: {
         token: token,
-        ...options?.dataApiOptions,
+        ...options?.dbOptions,
       },
-      devopsOptions: {
+      adminOptions: {
         adminToken: token,
-        ...options?.devopsOptions,
+        ...options?.adminOptions,
       },
     };
   }
 
   /**
    * Spawns a new {@link Db} instance using a direct endpoint and given options.
    *
+   * **NB. This method does not validate the existence of the database—it simply creates a reference.**
+   *
    * This endpoint should include the protocol and the hostname, but not the path. It's typically in the form of
    * `https://<db_id>-<region>.apps.astra.datastax.com`, but it can be used with DSE or any other Data-API-compatible
    * endpoint.
    *
    * The given options will override any default options set when creating the {@link DataApiClient} through
    * a deep merge (i.e. unset properties in the options object will just default to the default options).
    *
-   * Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to
-   * ensure that the endpoint is correct. If you want to create an actual database, see {@link AstraAdmin.createDatabase}
-   * instead.
-   *
    * @example
    * ```typescript
    * const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
@@ -75,6 +73,11 @@ export class DataApiClient {
    * });
    * ```
    *
+   * @remarks
+   * Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to
+   * ensure that the endpoint is correct. If you want to create an actual database, see {@link AstraAdmin.createDatabase}
+   * instead.
+   *
    * @param endpoint - The direct endpoint to use.
    * @param options - Any options to override the default options set when creating the {@link DataApiClient}.
    *
@@ -85,16 +88,14 @@ export class DataApiClient {
   /**
    * Spawns a new {@link Db} instance using a direct endpoint and given options.
    *
+   * **NB. This method does not validate the existence of the database—it simply creates a reference.**
+   *
    * This overload is purely for user convenience, but it **only supports using Astra as the underlying database**. For
    * DSE or any other Data-API-compatible endpoint, use the other overload instead.
    *
    * The given options will override any default options set when creating the {@link DataApiClient} through
    * a deep merge (i.e. unset properties in the options object will just default to the default options).
    *
-   * Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to
-   * ensure that the endpoint is correct. If you want to create an actual database, see {@link AstraAdmin.createDatabase}
-   * instead.
-   *
    * @example
    * ```typescript
    * const db1 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1');
@@ -105,6 +106,11 @@ export class DataApiClient {
    * });
    * ```
    *
+   * @remarks
+   * Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to
+   * ensure that the endpoint is correct. If you want to create an actual database, see {@link AstraAdmin.createDatabase}
+   * instead.
+   *
    * @param id - The database ID to use.
    * @param region - The region to use.
    * @param options - Any options to override the default options set when creating the {@link DataApiClient}.

src/client/types.ts

@@ -44,11 +44,11 @@ export interface RootClientOptions {
   /**
    * The default options when spawning a {@link Db} instance.
    */
-  dataApiOptions?: DbSpawnOptions,
+  dbOptions?: DbSpawnOptions,
   /**
    * The default options when spawning an {@link AstraAdmin} instance.
    */
-  devopsOptions?: AdminSpawnOptions,
+  adminOptions?: AdminSpawnOptions,
 }
 
 /**
@@ -189,6 +189,6 @@ export interface AdminSpawnOptions {
 export interface RootClientOptsWithToken {
   logLevel?: string,
   caller?: Caller | Caller[],
-  dataApiOptions: DbSpawnOptions & { token: string },
-  devopsOptions: AdminSpawnOptions & { adminToken: string },
+  dbOptions: DbSpawnOptions & { token: string },
+  adminOptions: AdminSpawnOptions & { adminToken: string },
 }

src/data-api/db.ts

@@ -34,7 +34,7 @@ import { RunCommandOptions } from '@/src/data-api/types/collections/command';
 /**
  * @internal
  */
-type DbOptions = RootClientOptsWithToken & { dataApiOptions: { token: string } };
+type DbOptions = RootClientOptsWithToken & { dbOptions: { token: string } };
 
 /**
  * Represents an interface to some Astra database instance. This is the entrypoint for database-level DML, such as
@@ -68,7 +68,7 @@ type DbOptions = RootClientOptsWithToken & { dataApiOptions: { token: string } }
  * @see DataApiClient.db
  * @see AstraAdmin.db
  */
-export class Db {
+export class Db implements Disposable {
   readonly #defaultOpts!: RootClientOptsWithToken;
 
   private readonly _httpClient!: DataApiHttpClient;
@@ -85,7 +85,7 @@ export class Db {
    *
    * // Overrides the default namespace for all future db spawns
    * const client2 = new DataApiClient('AstraCS:...', {
-   *   dataApiOptions: { namespace: 'my_namespace' }
+   *   dbOptions: { namespace: 'my_namespace' }
    * });
    *
    * // Created with 'default_keyspace' as the default namespace
@@ -113,7 +113,7 @@ export class Db {
    * @internal
    */
   constructor(endpoint: string, options: DbOptions) {
-    const dbOpts = options.dataApiOptions ?? {};
+    const dbOpts = options.dbOptions ?? {};
 
     Object.defineProperty(this, 'namespace', {
       value: dbOpts.namespace ?? DEFAULT_NAMESPACE,
@@ -150,7 +150,7 @@ export class Db {
   /**
    * The ID of the database, if it's an Astra database. If it's a non-Astra database, this will throw an error.
    *
-   * @throws An error if the database is not an Astra database.
+   * @throws Error - if the database is not an Astra database.
    */
   get id(): string {
     if (!this._id) {
@@ -181,7 +181,7 @@ export class Db {
    *
    * @returns A new {@link AstraDbAdmin} instance for this database instance.
    *
-   * @throws An error if the database is not an Astra database.
+   * @throws Error - if the database is not an Astra database.
    */
   public admin(options?: AdminSpawnOptions): AstraDbAdmin {
     if (!this._id) {
@@ -208,7 +208,7 @@ export class Db {
    *
    * @returns A promise that resolves to the database information.
    *
-   * @throws An error if the database is not an Astra database.
+   * @throws Error - if the database is not an Astra database.
    */
   public async info(): Promise<DatabaseInfo> {
     return await this.admin().info().then(i => i.info);
@@ -441,6 +441,49 @@ export class Db {
   public async command(command: Record<string, any>, options?: RunCommandOptions): Promise<RawDataApiResponse> {
     return await this._httpClient.executeCommand(command, options);
   }
+
+  /**
+   * @returns whether the client is using HTTP/2 for requests.
+   */
+  public httpStrategy(): 'http1' | 'http2' {
+    return this._httpClient.isUsingHttp2()
+      ? 'http2'
+      : 'http1';
+  }
+
+  /**
+   * Returns if the underlying HTTP/2 session was explicitly closed by the {@link close} method (or through ERM with
+   * the `using` clause).
+   *
+   * If the client's using HTTP/1, this method will return `undefined`.
+   *
+   * @returns whether the client was explicitly closed if using HTTP/2.
+   */
+  public isClosed(): boolean | undefined {
+    return this._httpClient.isClosed();
+  }
+
+  /**
+   * Closes the underlying HTTP/2 session, if the client is using HTTP/2. Closing the session will prevent any further
+   * requests from being made from this Db instance.
+   *
+   * This method is idempotent. If the client is using HTTP/1, this method will do nothing.
+   */
+  public close() {
+    this._httpClient.close();
+  }
+
+  /**
+   * Closes the underlying HTTP/2 session, if the client is using HTTP/2. Closing the session will prevent any further
+   * requests from being made from this Db instance.
+   *
+   * This method is idempotent. If the client is using HTTP/1, this method will do nothing.
+   *
+   * Meant for usage with the `using` clause in ERM (Explicit Resource Management).
+   */
+  [Symbol.dispose]() {
+    this.close();
+  }
 }
 
 /**
@@ -457,8 +500,8 @@ export function mkDb(rootOpts: RootClientOptsWithToken, endpointOrId: string, re
 
   return new Db(endpoint, {
     ...rootOpts,
-    dataApiOptions: {
-      ...rootOpts?.dataApiOptions,
+    dbOptions: {
+      ...rootOpts?.dbOptions,
       ...options,
     },
   });