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
  */