@lossless.org/nosqldb 10.11.0 → 11.0.0

package/ts/ts_nosqldb/classes.storagerehearsal.ts

@@ -0,0 +1,109 @@
+import { RustDbBridge, rustDbBridgeStorageRehearsal } from './rust-db-bridge.js';
+import type { INoSqlDbManagementOperationOptions } from './service-types.js';
+import {
+  normalizeNoSqlDbStorageRehearsalInput, normalizeNoSqlDbStorageRehearsalReceipt,
+  normalizeNoSqlDbStorageRehearsalOptions, normalizeNoSqlDbStorageRehearsalOperationOptions,
+  NoSqlDbStorageRehearsalError, noSqlDbStorageRehearsalErrorCodes,
+  type INoSqlDbStorageRehearsalInput, type INoSqlDbStorageRehearsalOptions,
+  type INoSqlDbStorageRehearsalReceipt, type TNoSqlDbStorageRehearsalErrorCode,
+} from './storage-rehearsal.js';
+
+/** Owns one offline rehearsal sidecar at a time. Separate instances are independent;
+ * native root ownership excludes concurrent use of a source or destination. */
+export class NoSqlDbStorageRehearsal {
+  private readonly binaryPath: string | undefined;
+  private bridge: RustDbBridge | undefined;
+  private cancellation: AbortController | undefined;
+  private completion: Promise<void> | undefined;
+
+  public constructor(options: INoSqlDbStorageRehearsalOptions = {}) {
+    this.binaryPath = normalizeNoSqlDbStorageRehearsalOptions(options).binaryPath;
+  }
+
+  /** Create or exactly retry a rehearsal. The default deadline is one hour,
+   * including spawn and the operation; maximum 24 hours. Cleanup confirms exit
+   * before this method settles. Retry the identical request after interruption. */
+  public async createDestination(inputArg: INoSqlDbStorageRehearsalInput,
+    optionsArg?: INoSqlDbManagementOperationOptions): Promise<INoSqlDbStorageRehearsalReceipt> {
+    let input: ReturnType<typeof normalizeNoSqlDbStorageRehearsalInput>;
+    try { input = normalizeNoSqlDbStorageRehearsalInput(inputArg); }
+    catch { throw new NoSqlDbStorageRehearsalError('INVALID_REQUEST'); }
+    const options = normalizeNoSqlDbStorageRehearsalOperationOptions(optionsArg);
+    const { timeoutMs } = options;
+    if (options.signal?.aborted) throw new NoSqlDbStorageRehearsalError('CANCELLED');
+    if (process.platform !== 'linux' && process.platform !== 'darwin') throw new NoSqlDbStorageRehearsalError('UNSUPPORTED');
+    if (this.completion) throw new NoSqlDbStorageRehearsalError('BUSY');
+    const deadline = performance.now() + timeoutMs;
+    const controller = new AbortController();
+    this.cancellation = controller;
+    const cancel = () => controller.abort();
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    let complete!: () => void;
+    this.completion = new Promise<void>((resolve) => { complete = resolve; });
+    let dispatched = false;
+    let receipt: INoSqlDbStorageRehearsalReceipt | undefined;
+    let failure: NoSqlDbStorageRehearsalError | undefined;
+    const remaining = () => {
+      const timeout = Math.ceil(deadline - performance.now());
+      if (timeout <= 0 || controller.signal.aborted) throw new NoSqlDbStorageRehearsalError(dispatched ? 'RECOVERY_REQUIRED' : 'CANCELLED');
+      return timeout;
+    };
+    try {
+      // A failed previous cleanup keeps its bridge here until exit is confirmed.
+      await this.terminateBridge();
+      remaining();
+      const bridge = new RustDbBridge({ binaryPath: this.binaryPath });
+      this.bridge = bridge;
+      if (!await bridge.spawn({ timeoutMs: remaining(), signal: controller.signal })) {
+        throw new NoSqlDbStorageRehearsalError('BINARY_UNAVAILABLE');
+      }
+      const commandTimeout = remaining();
+      dispatched = true;
+      const result = await bridge[rustDbBridgeStorageRehearsal](input, {
+        timeoutMs: commandTimeout, signal: controller.signal,
+      });
+      receipt = normalizeNoSqlDbStorageRehearsalReceipt(result, input);
+    } catch (error) {
+      if (error instanceof NoSqlDbStorageRehearsalError) failure = error;
+      else {
+        const nativeCode = error instanceof Error && 'responseErrorCode' in error ? error.responseErrorCode : undefined;
+        const code: TNoSqlDbStorageRehearsalErrorCode = typeof nativeCode === 'string'
+          && (noSqlDbStorageRehearsalErrorCodes as readonly string[]).includes(nativeCode)
+          ? nativeCode as TNoSqlDbStorageRehearsalErrorCode
+          : dispatched ? 'RECOVERY_REQUIRED' : controller.signal.aborted || performance.now() >= deadline ? 'CANCELLED' : 'BINARY_UNAVAILABLE';
+        failure = new NoSqlDbStorageRehearsalError(code);
+      }
+    } finally {
+      try { await this.terminateBridge(); }
+      catch { failure = new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED'); }
+      options.signal?.removeEventListener('abort', cancel);
+      this.cancellation = undefined;
+      this.completion = undefined;
+      complete();
+    }
+    if (failure) throw failure;
+    if (!receipt) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+    return receipt;
+  }
+
+  /** Cancel active work and confirm sidecar exit. Retry this method if cleanup
+   * reports RECOVERY_REQUIRED; the instance retains unconfirmed ownership. */
+  public async stop(): Promise<void> {
+    const completion = this.completion;
+    this.cancellation?.abort();
+    let failure: unknown;
+    try { await this.terminateBridge(); } catch (error) { failure = error; }
+    await completion;
+    if (failure) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+  }
+
+  private async terminateBridge(): Promise<void> {
+    const bridge = this.bridge;
+    if (!bridge) return;
+    try {
+      await bridge.terminate({ gracePeriodMs: 0 });
+      if (!bridge.ownershipReleased) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+      if (this.bridge === bridge) this.bridge = undefined;
+    } catch { throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED'); }
+  }
+}

package/ts/ts_nosqldb/committed-writes.ts

@@ -0,0 +1,38 @@
+export interface INoSqlDbCommitCursor {
+  timeline: string;
+  sequence: string;
+}
+
+export interface INoSqlDbCommittedNamespace {
+  database: string;
+  collection: string;
+}
+
+export interface INoSqlDbCommitReceipt {
+  session: string;
+  transaction: string;
+  statement?: number | null;
+}
+
+export interface INoSqlDbCommittedWrite {
+  stamp: INoSqlDbCommitCursor;
+  committedAtMs: number;
+  namespaces: INoSqlDbCommittedNamespace[];
+  receipt: INoSqlDbCommitReceipt | null;
+}
+
+export interface INoSqlDbGetCommittedWritesInput {
+  db: string;
+  after?: INoSqlDbCommitCursor;
+  limit?: number;
+  maximumBytes?: number;
+}
+
+export interface INoSqlDbCommittedWritesPage {
+  writes: INoSqlDbCommittedWrite[];
+  cursor: INoSqlDbCommitCursor;
+  head: INoSqlDbCommitCursor;
+  oldest: INoSqlDbCommitCursor;
+  gap: boolean;
+  hasMore: boolean;
+}

package/ts/ts_nosqldb/file-storage-options.ts

@@ -0,0 +1,33 @@
+import {
+  normalizeNoSqlDbFileStorageStartup,
+  type TNoSqlDbFileStorageStartup,
+} from './file-storage-startup.js';
+
+interface IFileStorageOptions {
+  storage?: string;
+  fileStorageStartup?: unknown;
+  auth?: { users?: unknown };
+}
+
+/** Pure, instance-local admission for the sole native serving engine. */
+export const normalizeNoSqlDbFileStorageOptions = (optionsArg: IFileStorageOptions): {
+  fileStorageStartup: TNoSqlDbFileStorageStartup | undefined;
+} => {
+  for (const removed of ['fileStorageEngine', 'persistPath', 'persistIntervalMs']) {
+    if (removed in optionsArg) throw new TypeError(`NoSQLDB ${removed} has been removed; native memory and file storage are selected by storage`);
+  }
+  if (optionsArg.auth && 'usersPath' in optionsArg.auth) {
+    throw new TypeError('NoSQLDB auth.usersPath has been removed; authentication is stored in the native database');
+  }
+  const storage = optionsArg.storage ?? 'memory';
+  if (storage !== 'file' && storage !== 'memory') throw new TypeError('NoSQLDB storage must be "memory" or "file"');
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new TypeError('NoSQLDB native storage requires Linux or macOS');
+  }
+  if (optionsArg.fileStorageStartup !== undefined && storage !== 'file') {
+    throw new TypeError('NoSQLDB fileStorageStartup requires storage: "file"');
+  }
+  return {
+    fileStorageStartup: storage === 'file' ? normalizeNoSqlDbFileStorageStartup(optionsArg.fileStorageStartup) : undefined,
+  };
+};

package/ts/ts_nosqldb/file-storage-startup.ts

@@ -0,0 +1,10 @@
+/** Native format admission is read-only until the engine owns the file root. */
+export type TNoSqlDbFileStorageStartup = 'current-format-only' | 'existing-only';
+
+export const normalizeNoSqlDbFileStorageStartup = (
+  valueArg: unknown,
+): TNoSqlDbFileStorageStartup => {
+  if (valueArg === undefined || valueArg === 'current-format-only') return 'current-format-only';
+  if (valueArg === 'existing-only') return 'existing-only';
+  throw new TypeError('NoSQLDB fileStorageStartup must be "current-format-only" or "existing-only"; automatic storage conversion has been removed');
+};

package/ts/ts_nosqldb/index.ts

@@ -0,0 +1,132 @@
+// NoSQLDB - Wire protocol compatible embedded database server
+export { NoSqlDbStoppedOperationError } from './stopped-storage.js';
+export type {
+  INoSqlDbStoppedOperationOptions, ILocalNoSqlDbStoppedStorageRootInspectionInput,
+  TLocalNoSqlDbStoppedStorageRootInspection, ILocalNoSqlDbAuditedStorageRoot,
+  ILocalNoSqlDbUnavailableStorageRoot, INoSqlDbPhysicalAdmissionViolation,
+  TNoSqlDbStorageRootBindingChange,
+} from './stopped-storage.js';
+export { NoSqlDbStorageRehearsal } from './classes.storagerehearsal.js';
+export { NoSqlDbStorageRehearsalError, noSqlDbStorageRehearsalErrorCodes } from './storage-rehearsal.js';
+export type {
+  INoSqlDbStorageRehearsalOptions, INoSqlDbStorageRehearsalInput,
+  INoSqlDbStorageRehearsalReceipt, INoSqlDbStorageRehearsalPreservation,
+  TNoSqlDbStorageRehearsalErrorCode,
+} from './storage-rehearsal.js';
+
+// Export server (the main entry point for using NoSQLDB)
+export { NoSqlDbServer, noSqlDbServerStopGraceMs } from './server/classes.nosqldbserver.js';
+export type {
+  INoSqlDbCommitCursor,
+  INoSqlDbCommittedNamespace,
+  INoSqlDbCommitReceipt,
+  INoSqlDbCommittedWrite,
+  INoSqlDbGetCommittedWritesInput,
+  INoSqlDbCommittedWritesPage,
+} from './committed-writes.js';
+export type { TNoSqlDbFileStorageStartup } from './file-storage-startup.js';
+export type {
+  INoSqlDbAuthOptions,
+  INoSqlDbAuthUser,
+  INoSqlDbOplogOptions,
+  INoSqlDbServerOptions,
+  INoSqlDbServerStopResult,
+  INoSqlDbTlsOptions,
+} from './server/classes.nosqldbserver.js';
+
+// Export bridge for advanced usage, its fail-stop ownership error, and the
+// engine-exit error and standard-error tail bounds.
+export {
+  RustDbBridge,
+  NoSqlDbManagementOperationTerminationError,
+  NoSqlDbEngineExitError,
+  noSqlDbEngineStderrTailLimits,
+  NoSqlDbUnknownRootError,
+} from './rust-db-bridge.js';
+
+// Export oplog / debug types
+export type {
+  IRustDbBridgeOptions,
+  INoSqlDbQueryOptions,
+  INoSqlDbInboundOptions,
+  IOpLogEntry,
+  IOpLogResult,
+  IOpLogStats,
+  IRevertResult,
+  ICollectionInfo,
+  IDocumentsResult,
+  INoSqlDbMetrics,
+} from './rust-db-bridge.js';
+
+// Export service API types
+export type {
+  INoSqlDbHealth,
+  INoSqlDbResourceFence,
+  INoSqlDbResourceFenceReceipt,
+  INoSqlDbHeldPublicationReceipt,
+  INoSqlDbCommitDatabasePublicationInput,
+  INoSqlDbManagementOperationOptions,
+  INoSqlDbDatabaseResourceFenceState,
+  INoSqlDbDatabaseAllocationIdentity,
+  INoSqlDbDatabaseAllocationLifecycle,
+  INoSqlDbDatabaseAllocationReadAccessGrantIdentity,
+  INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
+  INoSqlDbIssueDatabaseAllocationReadAccessGrantResult,
+  INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
+  INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult,
+  ILocalNoSqlDbOfflineInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
+  ILocalNoSqlDbOfflineStringValueInspection,
+  TLocalNoSqlDbOfflineStringValueInspectionResult,
+  TNoSqlDbCommitDatabasePublicationResult,
+  TNoSqlDbResourceFenceErrorCode,
+  TNoSqlDbAllocationReadAccessGrantErrorCode,
+  INoSqlDbDatabaseTenantInput,
+  INoSqlDbAttestDatabaseTenantInput,
+  INoSqlDbAttestDatabaseTenantResult,
+  INoSqlDbEnsureDatabaseTenantInput,
+  INoSqlDbEnsureDatabaseTenantResult,
+  INoSqlDbAllocateDatabaseTenantInput,
+  INoSqlDbAllocateDatabaseTenantResult,
+  INoSqlDbDeleteDatabaseTenantInput,
+  INoSqlDbRotateDatabaseTenantPasswordInput,
+  INoSqlDbDatabaseTenantDescriptor,
+  INoSqlDbDeleteDatabaseTenantResult,
+  INoSqlDbDatabaseExportCollection,
+  INoSqlDbDatabaseExport,
+  INoSqlDbDatabaseExportLimits,
+  INoSqlDbExportDatabaseInput,
+  INoSqlDbExportHeldDatabaseInput,
+  INoSqlDbDatabaseContentDigestLimits,
+  INoSqlDbGetDatabaseContentDigestInput,
+  INoSqlDbDatabaseContentDigest,
+  INoSqlDbImportDatabaseInput,
+  INoSqlDbImportDatabaseResult,
+} from './service-types.js';
+export {
+  NoSqlDbAllocationReadAccessGrantError,
+  normalizeNoSqlDbAllocationReadAccessGrantError,
+  noSqlDbAllocationReadAccessGrantErrorCodes,
+  NoSqlDbResourceFenceError,
+  normalizeNoSqlDbResourceFenceError,
+  noSqlDbResourceFenceErrorCodes,
+} from './service-types.js';
+export type {
+  ILocalNoSqlDbStoppedStorageRootRelocationInput,
+  ILocalNoSqlDbStoppedStorageRootRelocationReceipt,
+  TLocalNoSqlDbStorageRootRelocationErrorCode,
+} from './storage-root-relocation.js';
+export {
+  LocalNoSqlDbStorageRootRelocationError,
+  localNoSqlDbStorageRootRelocationErrorCodes,
+} from './storage-root-relocation.js';
+export type { TNoSqlDbEffectivePayloadInputV1 } from './resource-fencing.js';
+export { createNoSqlDbEffectivePayloadSha256V1 } from './resource-fencing.js';
+
+export type {
+  INoSqlDbStorageRootPins, ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+  ILocalNoSqlDbStoppedStorageRootAlignmentReceipt, TLocalNoSqlDbStoppedStorageRootAlignmentResult,
+  ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult,
+} from './storage-root-alignment.js';