@push.rocks/smartdb 2.18.1 → 3.0.1

package/ts/ts_smartdb/server/SmartdbServer.ts

@@ -2,7 +2,12 @@ import {
   RustDbBridge,
   SmartDbManagementOperationTerminationError,
 } from '../rust-db-bridge.js';
-import { AuthMetadataMigrationRunner, StorageMigrator } from '../../ts_migration/index.js';
+import {
+  AuthMetadataMigrationRunner,
+  SmartDbStorageMigrationCleanupError,
+  StorageMigrator,
+} from '../../ts_migration/index.js';
+import { validateSmartDbManagementOperationOptions } from '../offline-inspection.js';
 import type {
   IOpLogEntry,
   IOpLogResult,
@@ -17,6 +22,8 @@ import type {
   ISmartDbDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantResult,
+  ISmartDbAllocateDatabaseTenantInput,
+  ISmartDbAllocateDatabaseTenantResult,
   ISmartDbDeleteDatabaseTenantInput,
   ISmartDbRotateDatabaseTenantPasswordInput,
   ISmartDbDatabaseTenantDescriptor,
@@ -146,11 +153,63 @@ export class SmartdbServer {
   /**
    * Start the server
    */
-  async start(): Promise<void> {
+  async start(optionsArg?: ISmartDbManagementOperationOptions): Promise<void> {
+    validateSmartDbManagementOperationOptions(optionsArg);
+    optionsArg?.signal?.throwIfAborted();
     if (this.isRunning || this.startInProgress || this.bridgeOwned) {
       throw new Error('Server is already running or still owns a Rust bridge');
     }
 
+    const startupStartedAt = Date.now();
+    const startupDeadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : startupStartedAt + optionsArg.timeoutMs;
+    const timeoutError = new DOMException(
+      optionsArg?.timeoutMs === undefined
+        ? 'SmartDB startup timed out'
+        : `SmartDB startup timed out after ${optionsArg.timeoutMs}ms`,
+      'TimeoutError',
+    );
+    const startupAbortController = new AbortController();
+    let startupTimeout: ReturnType<typeof setTimeout> | undefined;
+    let externalAbortHandler: (() => void) | undefined;
+    if (optionsArg?.signal) {
+      externalAbortHandler = () => {
+        startupAbortController.abort(optionsArg.signal!.reason);
+      };
+      optionsArg.signal.addEventListener('abort', externalAbortHandler, { once: true });
+    }
+    if (optionsArg?.timeoutMs !== undefined) {
+      startupTimeout = setTimeout(() => {
+        startupAbortController.abort(timeoutError);
+      }, optionsArg.timeoutMs);
+    }
+    const checkpoint = () => {
+      if (
+        startupDeadline !== undefined
+        && Date.now() >= startupDeadline
+        && !startupAbortController.signal.aborted
+      ) {
+        startupAbortController.abort(timeoutError);
+      }
+      startupAbortController.signal.throwIfAborted();
+    };
+    const getBridgeOperationOptions = (): ISmartDbManagementOperationOptions | undefined => {
+      checkpoint();
+      const remainingTimeoutMs = startupDeadline === undefined
+        ? undefined
+        : startupDeadline - Date.now();
+      if (remainingTimeoutMs !== undefined && remainingTimeoutMs <= 0) {
+        startupAbortController.abort(timeoutError);
+        checkpoint();
+      }
+      if (!optionsArg?.signal && remainingTimeoutMs === undefined) return undefined;
+      return {
+        ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+        ...(remainingTimeoutMs === undefined ? {} : { timeoutMs: remainingTimeoutMs }),
+      };
+    };
+
     this.startInProgress = true;
     let resolveStartCompletion!: () => void;
     const startCompletionPromise = new Promise<void>((resolveArg) => {
@@ -158,16 +217,19 @@ export class SmartdbServer {
     });
     this.startCompletionPromise = startCompletionPromise;
     try {
+      checkpoint();
       // Run storage migration for file-based storage before starting Rust engine
       if (this.options.storage === 'file' && this.options.storagePath) {
         const migrator = new StorageMigrator(this.options.storagePath);
-        await migrator.run();
+        await migrator.run(startupAbortController.signal);
+        checkpoint();
       }
 
       // Ownership starts before spawn because a rejected spawn can still have
       // created a child whose termination must be confirmed.
       this.bridgeOwned = true;
-      const spawned = await this.bridge.spawn();
+      const spawned = await this.bridge.spawn(getBridgeOperationOptions());
+      checkpoint();
       if (!spawned) {
         throw new Error(
           'smartdb Rust binary not found. Set SMARTDB_RUST_BINARY env var, ' +
@@ -179,7 +241,11 @@ export class SmartdbServer {
         const authMetadataMigrationRunner = new AuthMetadataMigrationRunner(
           this.options.auth.usersPath,
         );
-        await authMetadataMigrationRunner.run(this.bridge);
+        await authMetadataMigrationRunner.run(
+          this.bridge,
+          getBridgeOperationOptions(),
+        );
+        checkpoint();
       }
 
       // Send config, get back connectionUri
@@ -194,7 +260,8 @@ export class SmartdbServer {
         auth: this.options.auth,
         tls: this.options.tls,
         oplog: this.options.oplog,
-      });
+      }, getBridgeOperationOptions());
+      checkpoint();
       if (!this.bridgeOwned || !this.bridge.running) {
         throw new Error('smartdb Rust process exited during startup');
       }
@@ -214,8 +281,19 @@ export class SmartdbServer {
         this.resolvedPort = resolvedPort;
       }
       this.resolvedConnectionUri = result.connectionUri;
+      checkpoint();
       this.isRunning = true;
     } catch (error) {
+      const startupError = error instanceof SmartDbManagementOperationTerminationError
+        || error instanceof SmartDbStorageMigrationCleanupError
+        ? error
+        : optionsArg?.signal?.aborted
+          ? optionsArg.signal.reason
+          : startupAbortController.signal.aborted || (
+              startupDeadline !== undefined && Date.now() >= startupDeadline
+            )
+            ? timeoutError
+            : error;
       this.isRunning = false;
       this.resolvedConnectionUri = '';
       this.resolvedPort = undefined;
@@ -225,14 +303,18 @@ export class SmartdbServer {
           this.bridgeOwned = false;
         } catch (cleanupError) {
           throw new AggregateError(
-            [error, cleanupError],
+            [startupError, cleanupError],
             'SmartDB startup failed and Rust bridge cleanup was incomplete',
-            { cause: error },
+            { cause: startupError },
           );
         }
       }
-      throw error;
+      throw startupError;
     } finally {
+      if (startupTimeout) clearTimeout(startupTimeout);
+      if (externalAbortHandler && optionsArg?.signal) {
+        optionsArg.signal.removeEventListener('abort', externalAbortHandler);
+      }
       this.startInProgress = false;
       resolveStartCompletion();
       if (this.startCompletionPromise === startCompletionPromise) {
@@ -345,6 +427,17 @@ export class SmartdbServer {
     return this.withTenantMongoUri(descriptor, params.password);
   }
 
+  /** Authoritatively allocate an absent, fenced database tenant. */
+  async allocateDatabaseTenant(
+    params: ISmartDbAllocateDatabaseTenantInput,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ISmartDbAllocateDatabaseTenantResult> {
+    const descriptor = await this.runDatabaseManagementOperation(
+      () => this.bridge.allocateDatabaseTenant(params, optionsArg),
+    );
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
   /**
    * Idempotently provision or rotate one exclusively owned database tenant.
    */
@@ -465,6 +558,9 @@ export class SmartdbServer {
         resourceFencingVersion: this.options.storage === 'file' ? 1 : undefined,
         resourceFencingSupported: this.options.storage === 'file' ? false : undefined,
         resourceFencingRequiresDrain: this.options.storage === 'file' ? true : undefined,
+        allocationFencingVersion: this.options.storage === 'file' ? 1 : undefined,
+        allocationFencingSupported: this.options.storage === 'file' ? false : undefined,
+        allocationFencingRequiresDrain: this.options.storage === 'file' ? true : undefined,
         publicationHoldVersion: 1,
         publicationHoldSupported: false,
         publicationHoldRequiresExternalDrain: false,

package/ts/ts_smartdb/service-types.ts

@@ -5,6 +5,9 @@ export interface ISmartDbHealth {
   resourceFencingVersion?: 1;
   resourceFencingSupported?: boolean;
   resourceFencingRequiresDrain?: true;
+  allocationFencingVersion?: 1;
+  allocationFencingSupported?: boolean;
+  allocationFencingRequiresDrain?: true;
   publicationHoldVersion: 1;
   publicationHoldSupported: boolean;
   publicationHoldRequiresExternalDrain: boolean;
@@ -53,6 +56,11 @@ export const smartDbResourceFenceErrorCodes = [
   'EFENCE_PUBLICATION_HELD',
   'EFENCE_CAPABILITY_MISMATCH',
   'EFENCE_NOT_HELD',
+  'EALLOCATION_EXPECTED_ABSENT_CONFLICT',
+  'EALLOCATION_REQUIRED',
+  'EALLOCATION_MISMATCH',
+  'EALLOCATION_GENERATION_EXHAUSTED',
+  'EALLOCATION_DEPROVISIONED',
 ] as const;
 
 export type TSmartDbResourceFenceErrorCode =
@@ -71,7 +79,8 @@ export interface ISmartDbResourceFenceReceipt
   kind:
     | 'smartdb.database.replace.v1'
     | 'smartdb.database.delete.v1'
-    | 'smartdb.database.ensure.v1';
+    | 'smartdb.database.ensure.v1'
+    | 'smartdb.database.allocate.v1';
   /** Digest of the canonical payload interpretation derived by SmartDB. */
   effectivePayloadSha256: string;
   provider?: 'smartdb';
@@ -84,6 +93,35 @@ export interface ISmartDbResourceFenceReceipt
   publicationCapabilitySha256?: string;
   /** Present only while publication is held; never returned after release. */
   publicationCapability?: string;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
+}
+
+export interface ISmartDbDatabaseAllocationIdentity {
+  version: 1;
+  provider: 'smartdb';
+  state: 'active';
+  databaseName: string;
+  username: string;
+  allocationId: string;
+  generation: number;
+  principalId: string;
+  resourceIdSha256: string;
+  bindingSha256: string;
+  receiptSha256: string;
+}
+
+export interface ISmartDbDatabaseAllocationLifecycle {
+  version: 1;
+  provider: 'smartdb';
+  state: 'allocating' | 'active' | 'deprovisioning' | 'deprovisioned';
+  databaseName: string;
+  username: string;
+  allocationId: string;
+  generation: number;
+  principalId: string;
+  resourceIdSha256: string;
+  bindingSha256: string;
+  receiptSha256: string;
 }
 
 export interface ISmartDbHeldPublicationReceipt
@@ -121,6 +159,7 @@ export interface ISmartDbDatabaseResourceFenceState {
   scopeId: string;
   highestToken: number;
   publicationState: 'requested' | 'publishing' | 'held' | 'released';
+  allocation?: ISmartDbDatabaseAllocationLifecycle;
 }
 
 export class SmartDbResourceFenceError extends Error {
@@ -144,7 +183,7 @@ export const normalizeSmartDbResourceFenceError = (
     errorArg instanceof Error
       ? errorArg
       : new Error(String(errorArg));
-  const match = /^(EFENCE_[A-Z_]+):\s*(.*)$/s.exec(error.message);
+  const match = /^((?:EFENCE|EALLOCATION)_[A-Z_]+):\s*(.*)$/s.exec(error.message);
   if (
     !match ||
     !smartDbResourceFenceErrorCodes.includes(
@@ -170,6 +209,13 @@ export interface ISmartDbDatabaseTenantInput {
 export interface ISmartDbEnsureDatabaseTenantInput
   extends ISmartDbDatabaseTenantInput {
   fence: ISmartDbResourceFence;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
+}
+
+export interface ISmartDbAllocateDatabaseTenantInput
+  extends ISmartDbDatabaseTenantInput {
+  expectedAbsent: true;
+  fence: ISmartDbResourceFence;
 }
 
 export interface ISmartDbDeleteDatabaseTenantInput {
@@ -184,6 +230,7 @@ export interface ISmartDbDeleteDatabaseTenantInput {
    */
   username?: string;
   fence?: ISmartDbResourceFence;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
   /** Keep the database data plane closed until commitDatabasePublication. */
   holdPublication?: boolean;
 }
@@ -200,6 +247,7 @@ export interface ISmartDbDatabaseTenantDescriptor {
   authSource: string;
   mongodbUri?: string;
   resourceFence?: ISmartDbResourceFenceReceipt;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 
 export interface ISmartDbEnsureDatabaseTenantResult
@@ -207,6 +255,12 @@ export interface ISmartDbEnsureDatabaseTenantResult
   resourceFence: ISmartDbResourceFenceReceipt;
 }
 
+export interface ISmartDbAllocateDatabaseTenantResult
+  extends ISmartDbDatabaseTenantDescriptor {
+  resourceFence: ISmartDbResourceFenceReceipt;
+  allocation: ISmartDbDatabaseAllocationIdentity;
+}
+
 export interface ISmartDbDeleteDatabaseTenantResult {
   databaseName: string;
   /**
@@ -222,6 +276,7 @@ export interface ISmartDbDeleteDatabaseTenantResult {
    */
   usersPreserved?: boolean;
   resourceFence?: ISmartDbResourceFenceReceipt;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 
 export interface ISmartDbDatabaseExportCollection {
@@ -282,6 +337,7 @@ export interface ISmartDbImportDatabaseInput {
    */
   username?: string;
   fence?: ISmartDbResourceFence;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
   /** Keep the database data plane closed until commitDatabasePublication. */
   holdPublication?: boolean;
 }
@@ -291,6 +347,7 @@ export interface ISmartDbImportDatabaseResult {
   collections: number;
   documents: number;
   resourceFence?: ISmartDbResourceFenceReceipt;
+  allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 
 export type TSmartDbCommitDatabasePublicationResult =