@lossless.org/nosqldb 10.10.0 → 11.0.0

package/ts/ts_nosqldb/server/classes.nosqldbserver.ts

@@ -1,6 +1,8 @@
 import {
   RustDbBridge,
+  NoSqlDbEngineExitError,
   NoSqlDbManagementOperationTerminationError,
+  attachNoSqlDbEngineStderrTail,
 } from '../rust-db-bridge.js';
 import { validateNoSqlDbManagementOperationOptions } from '../offline-inspection.js';
 import type { INoSqlDbGetCommittedWritesInput, INoSqlDbCommittedWritesPage } from '../committed-writes.js';
@@ -83,6 +85,32 @@ export interface INoSqlDbServerOptions {
   query?: INoSqlDbQueryOptions;
   /** Memory budgets for received requests (default: sized from the memory limit). */
   inbound?: INoSqlDbInboundOptions;
+  /**
+   * The store's memory budget in bytes, which its node cache and write buffer
+   * share: 4 MiB to 1 TiB. The engine refuses a start with a value outside
+   * that range and never clamps it. Unset, the budget is computed from the
+   * memory the process may use.
+   */
+  storageBudgetBytes?: number;
+  /**
+   * Receives every line the engine writes to its standard error, in order and
+   * without its line break. Without it, nothing is written to the host
+   * process's standard error. Start failures and unexpected engine exits
+   * carry the engine's last lines either way, in `engineStderrTail`. Each
+   * call runs in its own microtask; an exception it throws is not caught and
+   * reaches the process as an uncaught exception.
+   */
+  engineLog?: (line: string) => void;
+  /**
+   * Called once for each unexpected engine exit: an exit with a non-zero
+   * status or by a signal while the server runs and no stop is in progress.
+   * An exit with status 0, which the engine makes after a graceful shutdown
+   * it was signalled to make, is not reported; the server counts as stopped
+   * either way. The call runs in a microtask after the server has recorded the
+   * exit. An exception it throws is not caught and reaches the process as an
+   * uncaught exception.
+   */
+  onEngineExit?: (error: NoSqlDbEngineExitError) => void;
 }
 
 export interface INoSqlDbOplogOptions {
@@ -115,6 +143,59 @@ export interface INoSqlDbTlsOptions {
   requireClientCert?: boolean;
 }
 
+/**
+ * How `stop()` ended the engine. A stop is clean exactly when a stop request
+ * was sent and acknowledged, the server neither signalled nor killed the
+ * engine, and the engine exited with code 0 and no signal; `clean` says so.
+ */
+export interface INoSqlDbServerStopResult {
+  /** Whether a stop request was sent to a running engine. */
+  stopRequestSent: boolean;
+  /** Whether the engine acknowledged that request. */
+  stopAcknowledged: boolean;
+  /**
+   * Whether the server had to signal or kill the engine to end it: the engine
+   * had not exited by itself within `noSqlDbServerStopGraceMs` of an
+   * acknowledged request, or no request was acknowledged while it ran.
+   */
+  forcedByServer: boolean;
+  /** The engine's exit code as its process exit reported it, or null. */
+  exitCode: number | null;
+  /** The signal that ended the engine as its process exit reported it, or null. */
+  exitSignal: string | null;
+  /** Whether the stop was clean, as defined above. */
+  clean: boolean;
+}
+
+/**
+ * How long `stop()` waits, after the engine has acknowledged the stop request
+ * and its management input is closed, for the engine to exit by itself before
+ * the server ends it.
+ */
+export const noSqlDbServerStopGraceMs = 10_000;
+
+/** One stop's result, frozen, as all of its callers share it. */
+const stopResult = (
+  stopRequestSent: boolean,
+  stopAcknowledged: boolean,
+  forcedByServer: boolean,
+  exit: { code: number | null; signal: string | null } | null,
+): INoSqlDbServerStopResult => {
+  const exitCode = exit?.code ?? null;
+  const exitSignal = exit?.signal ?? null;
+  return Object.freeze({
+    stopRequestSent,
+    stopAcknowledged,
+    forcedByServer,
+    exitCode,
+    exitSignal,
+    clean: stopRequestSent && stopAcknowledged && !forcedByServer && exitCode === 0 && exitSignal === null,
+  });
+};
+
+/** The result of a stop when no engine runs: no request was sent. */
+export const noStopRequestResult = stopResult(false, false, false, null);
+
 /**
  * NoSqlDbServer - Wire protocol compatible database server backed by Rust
  *
@@ -140,7 +221,7 @@ export class NoSqlDbServer {
   private bridgeOwned = false;
   private startInProgress = false;
   private startCompletionPromise: Promise<void> | null = null;
-  private stopCompletionPromise: Promise<void> | null = null;
+  private stopCompletionPromise: Promise<INoSqlDbServerStopResult> | null = null;
   private isRunning = false;
   private resolvedConnectionUri = '';
   private resolvedPort: number | undefined;
@@ -162,25 +243,50 @@ export class NoSqlDbServer {
       oplog: options.oplog,
       query: options.query,
       inbound: options.inbound,
+      storageBudgetBytes: options.storageBudgetBytes,
+      engineLog: options.engineLog,
+      onEngineExit: options.onEngineExit,
     };
-    this.bridge = new RustDbBridge({ binaryPath: this.options.binaryPath });
+    this.bridge = new RustDbBridge({ binaryPath: this.options.binaryPath, engineLog: this.options.engineLog });
     this.bridge.on('exit', (code: number | null, signal: string | null) => {
+      // A stop keeps the running state until it has confirmed the bridge's
+      // termination, also when the engine exits by itself first.
+      if (this.stopCompletionPromise) return;
       const exitedUnexpectedly = this.isRunning
-        && !this.stopCompletionPromise
         && (code !== 0 || signal !== null);
       this.isRunning = false;
       this.resolvedConnectionUri = '';
       this.resolvedPort = undefined;
       if (exitedUnexpectedly) {
-        console.error(`nosqldb Rust process exited unexpectedly (code=${code}, signal=${signal})`);
+        const onEngineExit = this.options.onEngineExit;
+        const exit = new NoSqlDbEngineExitError(code, signal, this.bridge.engineStderrTail);
+        // Outside the bridge's exit event, so a throwing callback cannot
+        // interrupt the bridge's own exit handling.
+        if (onEngineExit) queueMicrotask(() => onEngineExit(exit));
       }
     });
   }
 
   /**
-   * Start the server
+   * Start the server. A rejection carries `engineStderrTail`: the last
+   * standard-error lines of the engine this start spawned, or none.
    */
   async start(optionsArg?: INoSqlDbManagementOperationOptions): Promise<void> {
+    const attempt = { engineSpawned: false };
+    try {
+      await this.startAttempt(optionsArg, attempt);
+    } catch (error) {
+      // Read after the attempt's cleanup termination, once the engine's last
+      // lines have arrived.
+      attachNoSqlDbEngineStderrTail(error, attempt.engineSpawned ? this.bridge.engineStderrTail : []);
+      throw error;
+    }
+  }
+
+  private async startAttempt(
+    optionsArg: INoSqlDbManagementOperationOptions | undefined,
+    attempt: { engineSpawned: boolean },
+  ): Promise<void> {
     validateNoSqlDbManagementOperationOptions(optionsArg);
     optionsArg?.signal?.throwIfAborted();
     if (this.isRunning || this.startInProgress || this.bridgeOwned || this.stopCompletionPromise) {
@@ -255,13 +361,13 @@ export class NoSqlDbServer {
       // 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(getBridgeOperationOptions());
+      const spawnOptions = getBridgeOperationOptions();
+      attempt.engineSpawned = true;
+      const spawned = await this.bridge.spawn(spawnOptions);
       checkpoint();
       if (!spawned) {
-        throw new Error(
-          'nosqldb Rust binary not found. Set NOSQLDB_RUST_BINARY env var, ' +
-          'install the platform package, or build locally with `tsrust`.'
-        );
+        // The bridge states what it knows: that the engine at its binaryPath did not report ready, or, without one, both meanings.
+        throw new Error(this.bridge.spawnFailureMessage ?? 'the nosqldb engine did not start: spawn() returned false');
       }
 
       // Send config, get back connectionUri
@@ -278,6 +384,7 @@ export class NoSqlDbServer {
         oplog: this.options.oplog,
         query: this.options.query,
         inbound: this.options.inbound,
+        storageBudgetBytes: this.options.storageBudgetBytes,
       }, getBridgeOperationOptions());
       checkpoint();
       if (!this.bridgeOwned || !this.bridge.running) {
@@ -341,9 +448,15 @@ export class NoSqlDbServer {
   }
 
   /**
-   * Stop the server
+   * Stop the server: wait for active startup work, send the engine a stop
+   * request, close its management input once it has acknowledged, give it
+   * `noSqlDbServerStopGraceMs` to exit by itself, and end it otherwise; then
+   * confirm the bridge's cleanup. Resolves with how the engine ended, which
+   * concurrent callers share; when no engine runs, the result says that no
+   * request was sent. Rejects, retaining ownership for a retry, only when the
+   * bridge's termination fails.
    */
-  stop(): Promise<void> {
+  stop(): Promise<INoSqlDbServerStopResult> {
     if (this.stopCompletionPromise) {
       return this.stopCompletionPromise;
     }
@@ -359,30 +472,53 @@ export class NoSqlDbServer {
     return stopCompletionPromise;
   }
 
-  private async stopInternal(): Promise<void> {
+  private async stopInternal(): Promise<INoSqlDbServerStopResult> {
     const startCompletionPromise = this.startCompletionPromise;
     if (startCompletionPromise) {
       await startCompletionPromise;
     }
 
     if (!this.isRunning && !this.bridgeOwned) {
-      return;
+      return noStopRequestResult;
     }
 
     const requestGracefulStop = this.isRunning && this.bridge.running;
+    let stopAcknowledged = false;
     if (requestGracefulStop) {
       try {
         await this.bridge.stopDb();
+        stopAcknowledged = true;
       } catch {
         // Confirmed bridge termination below still releases the owned process.
       }
     }
+    // An engine that acknowledged the stop exits by itself once its management
+    // input closes; it is ended only if it has not within the grace.
+    if (stopAcknowledged && this.bridge.engineProcessAlive) {
+      this.bridge.endManagementInput();
+      await this.bridge.waitForEngineExit(noSqlDbServerStopGraceMs);
+    }
+    const forcedByServer = this.bridge.engineProcessAlive;
 
-    await this.bridge.terminate();
+    try {
+      await this.bridge.terminate();
+    } catch (error) {
+      // An engine that has exited no longer runs, as the exit handler would
+      // have recorded outside a stop; ownership stays for a retry.
+      if (this.bridge.lastEngineExit !== null) {
+        this.isRunning = false;
+        this.resolvedConnectionUri = '';
+        this.resolvedPort = undefined;
+      }
+      throw error;
+    }
     this.bridgeOwned = false;
     this.isRunning = false;
     this.resolvedConnectionUri = '';
     this.resolvedPort = undefined;
+    // The process's exit event may follow the confirmed termination by a tick.
+    if (this.bridge.engineProcessAlive) await this.bridge.waitForEngineExit(1_000);
+    return stopResult(requestGracefulStop, stopAcknowledged, forcedByServer, this.bridge.lastEngineExit);
   }
 
   /**

package/ts/ts_nosqldb/server/index.ts

@@ -1,4 +1,4 @@
 // Server module exports
-export { NoSqlDbServer } from './classes.nosqldbserver.js';
-export type { INoSqlDbServerOptions } from './classes.nosqldbserver.js';
+export { NoSqlDbServer, noSqlDbServerStopGraceMs } from './classes.nosqldbserver.js';
+export type { INoSqlDbServerOptions, INoSqlDbServerStopResult } from './classes.nosqldbserver.js';
 export type { INoSqlDbQueryOptions, INoSqlDbInboundOptions } from '../rust-db-bridge.js';

package/ts/ts_nosqldb/stopped-storage.ts

@@ -41,7 +41,15 @@ export interface ILocalNoSqlDbAuditedStorageRoot {
     activeGrants: '0';
     importStages: '0';
   };
-  generations: { manifest: string; onDisk: string[] };
+  /**
+   * The generation inventory of a root that a 10.x release wrote, as this
+   * release's audit reports it and a 10.x engine's audit of its own root does.
+   * A root of this release keeps none: its report has no `generations` and
+   * says `storageFormat: 'format-3'`.
+   */
+  generations?: { manifest: string; onDisk: string[] };
+  /** `'format-3'` for a root of this release; absent for a root that a 10.x release wrote. */
+  storageFormat?: 'format-3';
   alignmentEligible: boolean;
   reasons: string[];
   physicalAdmissionViolations: [];

package/ts/ts_nosqldb/storage-rehearsal.ts

@@ -189,7 +189,7 @@ export const normalizeNoSqlDbStorageRehearsalReceipt = (value: unknown, input: T
     || (input.expectedSourceProviderRootId !== undefined && value.sourceProviderRootId !== input.expectedSourceProviderRootId)
     || !['sourceProviderRootId', 'destinationProviderRootId', 'sourceSnapshotSha256', 'sourceRecordsSha256', 'preservedRecordsSha256', 'receiptSha256'].every((key) => digest(value[key]))
     || value.sourceProviderRootId === value.destinationProviderRootId
-    || value.sourceStorageRootSha256 !== plugins.crypto.createHash('sha256').update(`${input.sourceFolderPath}/.__rustdb_mvcc/data`).digest('hex')
+    || value.sourceStorageRootSha256 !== plugins.crypto.createHash('sha256').update(`${input.sourceFolderPath}/.nosqldb-store/data`).digest('hex')
     || value.requestSha256 !== sha256('smartdb.storage-rehearsal.request.v2\0', input)
     || !integer(value.scramIterations, 4096, 0xffff_ffff)
     || ![value.destinationDevice, value.destinationInode, value.sourceLsn, value.destinationLsn].every(unsigned)

package/ts/ts_nosqldb/storage-root-alignment.ts

@@ -119,7 +119,7 @@ const eligibleGenerations = (value: unknown): boolean => {
 const eligibleInspection = (value: unknown, request: ILocalNoSqlDbStoppedStorageRootAlignmentInput): value is ILocalNoSqlDbAuditedStorageRoot => {
   if (!data(value, ['status', 'bindingState', 'bindingChange', 'storagePurpose', 'profileSchema', 'providerRootId',
     'groupId', 'timelineId', 'lsn', 'records', 'recordsSha256', 'recordsWithoutFencingProfileSha256', 'authUsers',
-    'authority', 'generations', 'alignmentEligible', 'reasons', 'physicalAdmissionViolations'])
+    'authority', 'alignmentEligible', 'reasons', 'physicalAdmissionViolations'], ['generations', 'storageFormat'])
     || value.status !== 'audited' || value.alignmentEligible !== true || value.storagePurpose !== 'production'
     || ![1, 4].includes(value.profileSchema as number) || !sha(value.providerRootId) || !sha(value.recordsSha256)
     || !sha(value.recordsWithoutFencingProfileSha256) || !lineage(value.groupId) || !lineage(value.timelineId)
@@ -128,7 +128,11 @@ const eligibleInspection = (value: unknown, request: ILocalNoSqlDbStoppedStorage
     || value.bindingState !== (value.bindingChange === 'none' ? 'matching' : 'foreign')
     || !data(value.authority, ['resourceFences', 'receipts', 'publicationHolds', 'activeAllocations', 'retiredAllocations',
       'allocationReplays', 'activeGrants', 'importStages']) || Object.values(value.authority).some(count => count !== '0')
-    || !eligibleGenerations(value.generations)
+    // A format-3 root says so and keeps no generation inventory; any other
+    // report is a paged root's and must carry an eligible one.
+    || !(value.storageFormat === 'format-3'
+      ? !('generations' in value)
+      : !('storageFormat' in value) && eligibleGenerations(value.generations))
     || !Array.isArray(value.reasons) || value.reasons.length || !Array.isArray(value.physicalAdmissionViolations)
     || value.physicalAdmissionViolations.length) return false;
   const pins = request.expect;

package/ts/ts_nosqldb/storage-root-relocation.ts

@@ -239,7 +239,7 @@ export const assertNoLocalNoSqlDbStorageRootRelocationWorkspace = async (
   storagePathArg: string,
 ): Promise<void> => {
   const storagePath = plugins.path.resolve(storagePathArg);
-  const internalPath = plugins.path.join(storagePath, '.__rustdb_internal');
+  const internalPath = plugins.path.join(storagePath, '.nosqldb-control');
   try {
     const storage = await plugins.fs.stat(storagePath);
     if (!storage.isDirectory()) {