Skip to content

Commit

Permalink
Various 2.0 cleanups/tweaks (#83)
Browse files Browse the repository at this point in the history 
* more intuitive naming for events/logging stuff

* formatting + timestamps for log messages

* dropIndex ifExists

* sourceModel

* createindex options resturcuting

* split filter & update types

* remove cql from datatypes names

* timeout for cursor.toArray() & coll.distinct()

* added class names for admin event name sourcse

* remove "spawn" from spawn type names
  • Loading branch information
@toptobes
toptobes authored Nov 20, 2024
1 parent 9b26268 commit 09d1d66
Show file tree
Hide file tree
Showing 84 changed files with 1,848 additions and 1,527 deletions.
1,172 changes: 622 additions & 550 deletions etc/astra-db-ts.api.md
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion scripts/repl.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ sh scripts/build.sh -light || exit 2
while [ $# -gt 0 ]; do
case "$1" in
"-local")
export CLIENT_DB_ENVIRONMENT='dse'
export CLIENT_DB_ENVIRONMENT='hcd'
export CLIENT_DB_TOKEN='Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh'
export CLIENT_DB_URL='http://localhost:8181'
;;
Expand Down
20 changes: 12 additions & 8 deletions src/administration/astra-admin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ 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 { AdminSpawnOptions, DbSpawnOptions } from '@/src/client';
import { AdminOptions, DbOptions } from '@/src/client';
import { $CustomInspect } from '@/src/lib/constants';
import { SomeDoc } from '@/src/documents';
import { Timeouts } from '@/src/lib/api/timeouts';
Expand Down Expand Up @@ -71,7 +71,7 @@ export class AstraAdmin {
*
* @internal
*/
constructor(rootOpts: InternalRootClientOpts, rawAdminOpts?: AdminSpawnOptions) {
constructor(rootOpts: InternalRootClientOpts, rawAdminOpts?: AdminOptions) {
const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');

const token = TokenProvider.parseToken([adminOpts?.adminToken, rootOpts.adminOptions.adminToken], 'admin token');
Expand Down Expand Up @@ -142,7 +142,7 @@ export class AstraAdmin {
*
* @returns A new {@link Db} instance.
*/
public db(endpoint: string, options?: DbSpawnOptions): Db;
public db(endpoint: string, options?: DbOptions): Db;

/**
* Spawns a new {@link Db} instance using a direct endpoint and given options.
Expand Down Expand Up @@ -176,9 +176,9 @@ export class AstraAdmin {
*
* @returns A new {@link Db} instance.
*/
public db(id: string, region: string, options?: DbSpawnOptions): Db;
public db(id: string, region: string, options?: DbOptions): Db;

public db(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): Db {
public db(endpointOrId: string, regionOrOptions?: string | DbOptions, maybeOptions?: DbOptions): Db {
const dbOpts = (typeof regionOrOptions === 'string')
? maybeOptions
: regionOrOptions;
Expand Down Expand Up @@ -229,7 +229,7 @@ export class AstraAdmin {
*
* @returns A new {@link Db} instance.
*/
public dbAdmin(endpoint: string, options?: DbSpawnOptions): AstraDbAdmin;
public dbAdmin(endpoint: string, options?: DbOptions): AstraDbAdmin;

/**
* Spawns a new {@link Db} instance using a direct endpoint and given options.
Expand Down Expand Up @@ -266,9 +266,9 @@ export class AstraAdmin {
*
* @returns A new {@link Db} instance.
*/
public dbAdmin(id: string, region: string, options?: DbSpawnOptions): AstraDbAdmin;
public dbAdmin(id: string, region: string, options?: DbOptions): AstraDbAdmin;

public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): AstraDbAdmin {
public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbOptions, maybeOptions?: DbOptions): AstraDbAdmin {
/* @ts-expect-error - calls internal representation of method */
return this.db(endpointOrId, regionOrOptions, maybeOptions).admin(this.#defaultOpts.adminOptions);
}
Expand All @@ -291,6 +291,7 @@ export class AstraAdmin {
const resp = await this.#httpClient.request({
method: HttpMethods.Get,
path: `/databases/${id}`,
methodName: 'admin.dbInfo',
}, tm);

return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
Expand Down Expand Up @@ -347,6 +348,7 @@ export class AstraAdmin {
method: HttpMethods.Get,
path: `/databases`,
params: params,
methodName: 'admin.listDatabases',
}, tm);

return resp.data!.map((d: SomeDoc) => buildAstraDatabaseAdminInfo(d, this.#environment));
Expand Down Expand Up @@ -419,6 +421,7 @@ export class AstraAdmin {
method: HttpMethods.Post,
path: '/databases',
data: definition,
methodName: 'admin.createDatabase',
}, {
id: (resp) => resp.headers.location,
target: 'ACTIVE',
Expand Down Expand Up @@ -466,6 +469,7 @@ export class AstraAdmin {
await this.#httpClient.requestLongRunning({
method: HttpMethods.Post,
path: `/databases/${id}/terminate`,
methodName: 'admin.dropDatabase',
}, {
id: id,
target: 'TERMINATED',
Expand Down
20 changes: 14 additions & 6 deletions src/administration/astra-db-admin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ 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';
import { AdminOptions } from '@/src/client';
import { DataAPIHttpClient } from '@/src/lib/api/clients';

/**
* An administrative class for managing Astra databases, including creating, listing, and deleting keyspaces.
Expand Down Expand Up @@ -69,6 +70,7 @@ import { AdminSpawnOptions } from '@/src/client';
*/
export class AstraDbAdmin extends DbAdmin {
readonly #httpClient: DevOpsAPIHttpClient;
readonly #dataApiHttpClient: DataAPIHttpClient<'admin'>;
readonly #db: Db;
readonly #environment: 'dev' | 'test' | 'prod';

Expand All @@ -77,7 +79,7 @@ export class AstraDbAdmin extends DbAdmin {
*
* @internal
*/
constructor(db: Db, rootOpts: InternalRootClientOpts, rawAdminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider | undefined, endpoint: string) {
constructor(db: Db, rootOpts: InternalRootClientOpts, rawAdminOpts: AdminOptions | undefined, dbToken: TokenProvider | undefined, endpoint: string) {
super();

const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
Expand All @@ -101,6 +103,7 @@ export class AstraDbAdmin extends DbAdmin {
timeoutDefaults: Timeouts.merge(rootOpts.adminOptions.timeoutDefaults, adminOpts?.timeoutDefaults),
});

this.#dataApiHttpClient = db._httpClient.forDbAdmin(adminOpts);
this.#db = db;

Object.defineProperty(this, $CustomInspect, {
Expand Down Expand Up @@ -155,8 +158,9 @@ export class AstraDbAdmin extends DbAdmin {
* @returns The available embedding providers.
*/
public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
const resp = await this.#db._httpClient.executeCommand({ findEmbeddingProviders: {} }, {
const resp = await this.#dataApiHttpClient.executeCommand({ findEmbeddingProviders: {} }, {
timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
methodName: 'dbAdmin.findEmbeddingProviders',
keyspace: null,
});
return resp.status as FindEmbeddingProvidersResult;
Expand All @@ -179,7 +183,7 @@ export class AstraDbAdmin extends DbAdmin {
*/
public async info(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo> {
const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
return this.#info(tm);
return this.#info('dbAdmin.info', tm);
}

/**
Expand All @@ -200,7 +204,7 @@ export class AstraDbAdmin extends DbAdmin {
*/
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);
return this.#info('dbAdmin.listKeyspaces', tm).then(i => i.keyspaces);
}

/**
Expand Down Expand Up @@ -243,6 +247,7 @@ export class AstraDbAdmin extends DbAdmin {
await this.#httpClient.requestLongRunning({
method: HttpMethods.Post,
path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
methodName: 'dmAdmin.createKeyspace',
}, {
id: this.#db.id,
target: 'ACTIVE',
Expand Down Expand Up @@ -290,6 +295,7 @@ export class AstraDbAdmin extends DbAdmin {
await this.#httpClient.requestLongRunning({
method: HttpMethods.Delete,
path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
methodName: 'dbAdmin.dropKeyspace',
}, {
id: this.#db.id,
target: 'ACTIVE',
Expand Down Expand Up @@ -327,6 +333,7 @@ export class AstraDbAdmin extends DbAdmin {
await this.#httpClient.requestLongRunning({
method: HttpMethods.Post,
path: `/databases/${this.#db.id}/terminate`,
methodName: 'dbAdmin.drop',
}, {
id: this.#db.id,
target: 'TERMINATED',
Expand All @@ -341,10 +348,11 @@ export class AstraDbAdmin extends DbAdmin {
return this.#httpClient;
}

async #info(tm: TimeoutManager): Promise<AstraDbAdminInfo> {
async #info(methodName: string, tm: TimeoutManager): Promise<AstraDbAdminInfo> {
const resp = await this.#httpClient.request({
method: HttpMethods.Get,
path: `/databases/${this.#db.id}`,
methodName,
}, tm);

return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
Expand Down
14 changes: 9 additions & 5 deletions src/administration/data-api-db-admin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@
// limitations under the License.
// noinspection ExceptionCaughtLocallyJS

import { LocalCreateKeyspaceOptions } from '@/src/administration/types';
import { DataAPICreateKeyspaceOptions } from '@/src/administration/types';
import { DbAdmin } from '@/src/administration/db-admin';
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';
import { AdminOptions } from '@/src/client';

/**
* An administrative class for managing non-Astra databases, including creating, listing, and deleting keyspaces.
Expand Down Expand Up @@ -57,15 +57,15 @@ import { AdminSpawnOptions } from '@/src/client';
* @public
*/
export class DataAPIDbAdmin extends DbAdmin {
readonly #httpClient: DataAPIHttpClient;
readonly #httpClient: DataAPIHttpClient<'admin'>;
readonly #db: Db;

/**
* Use {@link Db.admin} to obtain an instance of this class.
*
* @internal
*/
constructor(db: Db, httpClient: DataAPIHttpClient, rawAdminOpts?: AdminSpawnOptions) {
constructor(db: Db, httpClient: DataAPIHttpClient, rawAdminOpts?: AdminOptions) {
super();
const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
this.#httpClient = httpClient.forDbAdmin(adminOpts);
Expand Down Expand Up @@ -116,6 +116,7 @@ export class DataAPIDbAdmin extends DbAdmin {
public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
const resp = await this.#httpClient.executeCommand({ findEmbeddingProviders: {} }, {
timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
methodName: 'dbAdmin.findEmbeddingProviders',
keyspace: null,
});
return resp.status as FindEmbeddingProvidersResult;
Expand All @@ -140,6 +141,7 @@ export class DataAPIDbAdmin extends DbAdmin {
public override async listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]> {
const resp = await this.#httpClient.executeCommand({ findKeyspaces: {} }, {
timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
methodName: 'dbAdmin.listKeyspaces',
keyspace: null,
});
return resp.status!.keyspaces;
Expand Down Expand Up @@ -175,7 +177,7 @@ export class DataAPIDbAdmin extends DbAdmin {
*
* @returns A promise that resolves when the operation completes.
*/
public override async createKeyspace(keyspace: string, options?: LocalCreateKeyspaceOptions): Promise<void> {
public override async createKeyspace(keyspace: string, options?: DataAPICreateKeyspaceOptions): Promise<void> {
if (options?.updateDbKeyspace) {
this.#db.useKeyspace(keyspace);
}
Expand All @@ -187,6 +189,7 @@ export class DataAPIDbAdmin extends DbAdmin {

await this.#httpClient.executeCommand({ createKeyspace: { name: keyspace, options: { replication } } }, {
timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
methodName: 'dbAdmin.createKeyspace',
keyspace: null,
});
}
Expand Down Expand Up @@ -215,6 +218,7 @@ export class DataAPIDbAdmin extends DbAdmin {
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),
methodName: 'dbAdmin.dropKeyspace',
keyspace: null,
});
}
Expand Down
Loading

1 comment on commit 09d1d66

@vkarpov15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nitpick: I dislike using nameOnly as a client-side override for the explain option. I understand that nameOnly is a bit more semantic. But I think it is more important that client option names match server option names, so developers that are used to either working with the HTTP API directly or with other clients can more easily jump into code that uses astra-db-ts.

Please sign in to comment.