Initial logging implementation (#77)

* started work overhauling validation logic

* so much validation

* some folder resturcuting

* loggign hierarchy

* basic logging impl

* implement warning events

* tests for logging and such

Author: toptobes

src/administration/astra-admin.ts

@@ -22,12 +22,14 @@ import {
   ListDatabasesOptions,
 } from '@/src/administration/types';
 import { AstraDbAdmin } from '@/src/administration/astra-db-admin';
-import { DbSpawnOptions, InternalRootClientOpts } from '@/src/client/types';
 import { Db } from '@/src/db/db';
-import { validateAdminOpts } from '@/src/administration/utils';
 import { DEFAULT_DEVOPS_API_ENDPOINTS, DEFAULT_KEYSPACE, HttpMethods } from '@/src/lib/api/constants';
 import { DevOpsAPIHttpClient } from '@/src/lib/api/clients/devops-api-http-client';
 import { TokenProvider, WithTimeout } from '@/src/lib';
+import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
+import { InternalRootClientOpts } from '@/src/client/types/internal';
+import { DbSpawnOptions, Logger } from '@/src/client';
+import { buildAstraEndpoint } from '@/src/lib/utils';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting databases.
@@ -64,24 +66,31 @@ export class AstraAdmin {
    *
    * @internal
    */
-  constructor(rootOpts: InternalRootClientOpts, adminOpts?: AdminSpawnOptions) {
-    validateAdminOpts(adminOpts);
+  constructor(rootOpts: InternalRootClientOpts, rawAdminOpts?: AdminSpawnOptions) {
+    const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
 
-    this.#defaultOpts = rootOpts;
+    const token = TokenProvider.parseToken([adminOpts?.adminToken, rootOpts.adminOptions.adminToken], 'admin token');
 
-    const combinedAdminOpts = {
-      ...rootOpts.adminOptions,
-      ...adminOpts,
-      adminToken: TokenProvider.parseToken(adminOpts?.adminToken ?? rootOpts.adminOptions.adminToken),
+    this.#defaultOpts = {
+      ...rootOpts,
+      adminOptions: {
+        endpointUrl: adminOpts?.endpointUrl || rootOpts.adminOptions.endpointUrl,
+        adminToken: token,
+        logging: Logger.advanceConfig(rootOpts.adminOptions.logging, adminOpts?.logging),
+      },
+      dbOptions: {
+        ...rootOpts.dbOptions,
+        token: TokenProvider.parseToken([rootOpts.dbOptions.token, token], 'admin token'),
+      },
     };
 
     this.#httpClient = new DevOpsAPIHttpClient({
-      baseUrl: combinedAdminOpts.endpointUrl || DEFAULT_DEVOPS_API_ENDPOINTS.prod,
-      monitorCommands: combinedAdminOpts.monitorCommands,
+      baseUrl: this.#defaultOpts.adminOptions.endpointUrl || DEFAULT_DEVOPS_API_ENDPOINTS.prod,
+      logging: this.#defaultOpts.adminOptions.logging,
       emitter: rootOpts.emitter,
       fetchCtx: rootOpts.fetchCtx,
       userAgent: rootOpts.userAgent,
-      tokenProvider: combinedAdminOpts.adminToken,
+      tokenProvider: this.#defaultOpts.adminOptions.adminToken,
     });
   }
 
@@ -245,7 +254,8 @@ export class AstraAdmin {
 
   public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): AstraDbAdmin {
     /* @ts-expect-error - calls internal representation of method */
-    return this.db(endpointOrId, regionOrOptions, maybeOptions).admin(this.#defaultOpts.adminOptions);
+    return this.db(endpointOrId, regionOrOptions, maybeOptions)
+      .admin(this.#defaultOpts.adminOptions);
   }
 
   /**
@@ -396,8 +406,9 @@ export class AstraAdmin {
       options,
     });
 
-    const db = this.db(resp.headers.location, definition.region, { ...options?.dbOptions, keyspace: definition.keyspace });
-    return db.admin(this.#defaultOpts.adminOptions);
+    const endpoint = buildAstraEndpoint(resp.headers.location, definition.region);
+    const db = this.db(endpoint, { ...options?.dbOptions, keyspace: definition.keyspace });
+    return new AstraDbAdmin(db, this.#defaultOpts, {}, this.#defaultOpts.adminOptions.adminToken, endpoint);
   }
 
   /**
@@ -425,7 +436,7 @@ export class AstraAdmin {
    *
    * @remarks Use with caution. Wear a harness. Don't say I didn't warn you.
    */
-  async dropDatabase(db: Db | string, options?: AdminBlockingOptions): Promise<void> {
+  public async dropDatabase(db: Db | string, options?: AdminBlockingOptions): Promise<void> {
     const id = typeof db === 'string' ? db : db.id;
 
     await this.#httpClient.requestLongRunning({
@@ -440,7 +451,7 @@ export class AstraAdmin {
     });
   }
 
-  private get _httpClient() {
+  public get _httpClient() {
     return this.#httpClient;
   }
 }

src/administration/astra-db-admin.ts

@@ -13,17 +13,24 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminBlockingOptions, AdminSpawnOptions, CreateKeyspaceOptions, FullDatabaseInfo } from '@/src/administration/types';
+import {
+  AdminBlockingOptions,
+  AdminSpawnOptions,
+  CreateKeyspaceOptions,
+  FullDatabaseInfo,
+} from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
 import { WithTimeout } from '@/src/lib/types';
-import { InternalRootClientOpts } from '@/src/client/types';
-import { extractAstraEnvironment, validateAdminOpts } from '@/src/administration/utils';
+import { 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 { Logger } from '@/src/lib/logging/logger';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting keyspaces.
@@ -67,17 +74,12 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @internal
    */
-  constructor(db: Db, rootOpts: InternalRootClientOpts, adminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider, endpoint: string) {
+  constructor(db: Db, rootOpts: InternalRootClientOpts, rawAdminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider | undefined, endpoint: string) {
     super();
 
-    validateAdminOpts(adminOpts);
+    const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
 
-    const combinedAdminOpts = {
-      ...rootOpts.adminOptions,
-      ...adminOpts,
-    };
-
-    const _adminToken = TokenProvider.parseToken(adminOpts?.adminToken ?? rootOpts.adminOptions.adminToken);
+    const _adminToken = TokenProvider.parseToken([adminOpts?.adminToken, rootOpts.adminOptions.adminToken], 'admin token');
 
     const adminToken = (_adminToken instanceof StaticTokenProvider && isNullish(_adminToken.getToken()))
       ? dbToken
@@ -86,8 +88,8 @@ export class AstraDbAdmin extends DbAdmin {
     const environment = extractAstraEnvironment(endpoint);
 
     this.#httpClient = new DevOpsAPIHttpClient({
-      baseUrl: combinedAdminOpts.endpointUrl ?? DEFAULT_DEVOPS_API_ENDPOINTS[environment],
-      monitorCommands: combinedAdminOpts.monitorCommands,
+      baseUrl: adminOpts?.endpointUrl ?? rootOpts.adminOptions.endpointUrl ?? DEFAULT_DEVOPS_API_ENDPOINTS[environment],
+      logging: Logger.advanceConfig(rootOpts.adminOptions.logging, adminOpts?.logging),
       fetchCtx: rootOpts.fetchCtx,
       emitter: rootOpts.emitter,
       userAgent: rootOpts.userAgent,
@@ -317,7 +319,7 @@ export class AstraDbAdmin extends DbAdmin {
     });
   }
 
-  private get _httpClient() {
+  public get _httpClient() {
     return this.#httpClient;
   }
 }

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

@@ -16,10 +16,10 @@
 import { AdminBlockingOptions, AdminSpawnOptions, LocalCreateKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
 import { WithTimeout } from '@/src/lib/types';
-import { validateAdminOpts } from '@/src/administration/utils';
 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';
 
 /**
  * An administrative class for managing non-Astra databases, including creating, listing, and deleting keyspaces.
@@ -34,7 +34,7 @@ import { Db } from '@/src/db';
  *
  * // Create an admin instance through a Db
  * const db = client.db('*ENDPOINT*');
- * const dbAdmin1 = db.admin({ environment: 'dse' );
+ * const dbAdmin1 = db.admin({ environment: 'dse' });
  * const dbAdmin2 = db.admin({ environment: 'dse', adminToken: 'stronger-token' });
  *
  * await admin1.createKeyspace({
@@ -55,18 +55,17 @@ import { Db } from '@/src/db';
  * @public
  */
 export class DataAPIDbAdmin extends DbAdmin {
-  readonly #httpClient!: DataAPIHttpClient;
-  readonly #db!: Db;
+  readonly #httpClient: DataAPIHttpClient;
+  readonly #db: Db;
 
   /**
    * Use {@link Db.admin} to obtain an instance of this class.
    *
    * @internal
    */
-  constructor(db: Db, httpClient: DataAPIHttpClient, adminOpts?: AdminSpawnOptions) {
+  constructor(db: Db, httpClient: DataAPIHttpClient, rawAdminOpts?: AdminSpawnOptions) {
     super();
-    validateAdminOpts(adminOpts);
-
+    const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
     this.#httpClient = httpClient.forDbAdmin(adminOpts);
     this.#db = db;
   }
@@ -146,7 +145,7 @@ export class DataAPIDbAdmin extends DbAdmin {
    * await dbAdmin.createKeyspace('my_keyspace', {
    *   replication: {
    *     class: 'SimpleStrategy',
-   *     replicatonFactor: 3,
+   *     replicationFactor: 3,
    *   },
    * });
    *
@@ -202,7 +201,7 @@ export class DataAPIDbAdmin extends DbAdmin {
     await this.#httpClient.executeCommand({ dropKeyspace: { name: keyspace } }, { maxTimeMS: options?.maxTimeMS, keyspace: null });
   }
 
-  private get _httpClient() {
+  public get _httpClient() {
     return this.#httpClient;
   }
 }

src/administration/events.ts

@@ -13,7 +13,8 @@
 // limitations under the License.
 
 import { DevOpsAPIRequestInfo } from '@/src/lib/api/clients/devops-api-http-client';
-import { hrTimeMs } from '@/src/lib/api/clients/http-client';
+import { DataAPIErrorDescriptor } from '@/src/documents';
+import { DataAPIClientEvent } from '@/src/lib/logging/events';
 
 /**
  * The events emitted by the {@link DataAPIClient}. These events are emitted at various stages of the
@@ -38,14 +39,15 @@ export type AdminCommandEvents = {
    * Emitted when an admin command has errored.
    */
   adminCommandFailed: (event: AdminCommandFailedEvent) => void,
+  adminCommandWarnings: (event: AdminCommandWarningsEvent) => void,
 }
 
 /**
  * Common base class for all admin command events.
  *
  * @public
  */
-export abstract class AdminCommandEvent {
+export abstract class AdminCommandEvent extends DataAPIClientEvent {
   /**
    * The path for the request, not including the Base URL.
    */
@@ -77,12 +79,17 @@ export abstract class AdminCommandEvent {
    * @internal
    */
   protected constructor(info: DevOpsAPIRequestInfo, longRunning: boolean) {
+    super();
     this.path = info.path;
     this.method = info.method;
     this.reqBody = info.data;
     this.params = info.params;
     this.longRunning = longRunning;
   }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
 }
 
 /**
@@ -107,6 +114,10 @@ export class AdminCommandStartedEvent extends AdminCommandEvent {
     super(info, longRunning);
     this.timeout = timeout;
   }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
 }
 
 /**
@@ -136,9 +147,13 @@ export class AdminCommandPollingEvent extends AdminCommandEvent {
    */
   constructor(info: DevOpsAPIRequestInfo, started: number, interval: number) {
     super(info, true);
-    this.elapsed = hrTimeMs() - started;
+    this.elapsed = performance.now() - started;
     this.interval = interval;
   }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
 }
 
 /**
@@ -159,25 +174,20 @@ export class AdminCommandSucceededEvent extends AdminCommandEvent {
    */
   public readonly resBody?: Record<string, any>;
 
-  /**
-   * Any warnings returned from the Data API that may point out deprecated/incorrect practices,
-   * or any other issues that aren't strictly an error.
-   *
-   * Does not apply to Astra users, as the admin classes will use the DevOps API instead.
-   */
-  public readonly warnings: string[];
-
   /**
    * Should not be instantiated by the user.
    *
    * @internal
    */
-  constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, data: Record<string, any> | undefined, warnings: string[], started: number) {
+  constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, data: Record<string, any> | undefined, started: number) {
     super(info, longRunning);
-    this.duration = hrTimeMs() - started;
-    this.warnings = warnings;
+    this.duration = performance.now() - started;
     this.resBody = data || undefined;
   }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
 }
 
 /**
@@ -208,7 +218,24 @@ export class AdminCommandFailedEvent extends AdminCommandEvent {
    */
   constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, error: Error, started: number) {
     super(info, longRunning);
-    this.duration = hrTimeMs() - started;
+    this.duration = performance.now() - started;
     this.error = error;
   }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
+}
+
+export class AdminCommandWarningsEvent extends AdminCommandEvent {
+  public readonly warnings: DataAPIErrorDescriptor[];
+
+  constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, warnings: DataAPIErrorDescriptor[]) {
+    super(info, longRunning);
+    this.warnings = warnings;
+  }
+
+  formatted(): string {
+    return JSON.stringify(this);
+  }
 }

src/administration/types/index.ts

@@ -44,7 +44,7 @@ export type {
 
 export type {
   AdminSpawnOptions,
-} from './admin/spawn-admin';
+} from '../../client/types/spawn-admin';
 
 export type {
   CreateKeyspaceOptions,

src/administration/utils.ts

@@ -12,19 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { AdminSpawnOptions } from '@/src/administration/types';
-import { validateOption } from '@/src/documents/utils';
-
-/**
- * @internal
- */
-export function validateAdminOpts(opts: AdminSpawnOptions | undefined) {
-  validateOption('adminOptions', opts, 'object', false, (opts) => {
-    validateOption('adminOptions.monitorCommands', opts.monitorCommands, 'boolean');
-    validateOption('adminOptions.endpointUrl', opts.endpointUrl, 'string');
-  });
-}
-
 /**
  * @internal
  */