@lossless.org/nosqldb 10.11.0 → 11.0.0

package/dist_ts/ts_nosqldb/rust-db-bridge.d.ts

@@ -69,6 +69,48 @@ export interface IDocumentsResult {
     documents: Record<string, any>[];
     total: number;
 }
+/**
+ * Bounds of the engine standard-error tail that start failures, unexpected
+ * engine exits and failed management calls carry: the engine's last 64 lines.
+ * A longer line keeps its first 1,024 characters, followed by
+ * ` [<n> more characters]`.
+ */
+export declare const noSqlDbEngineStderrTailLimits: Readonly<{
+    lines: 64;
+    lineCharacters: 1024;
+}>;
+/**
+ * Attach the engine's last standard-error lines to an error as its own field
+ * `engineStderrTail`, leaving its message and cause unchanged. Values that
+ * cannot carry a field (primitives, frozen objects) are left as they are.
+ */
+export declare function attachNoSqlDbEngineStderrTail(errorArg: unknown, tailArg: readonly string[]): void;
+/**
+ * The engine process exited with a non-zero status or by a signal while its
+ * server was running and no stop was in progress. `engineStderrTail` holds
+ * its last standard-error lines.
+ */
+export declare class NoSqlDbEngineExitError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly engineStderrTail: readonly string[];
+    constructor(exitCode: number | null, signal: string | null, engineStderrTailArg: readonly string[]);
+}
+/**
+ * A start that the engine refused because the storage root, or a feature it
+ * carries, comes from a later NoSQLDB release than this one: the engine's
+ * management reply carried the code `UNKNOWN_ROOT`. The engine wrote nothing
+ * into the root (storage-root-names-and-start.md, "Roots of later releases";
+ * requirements A300 and A319). `code` holds the code, and `cause` the
+ * management error that carried it.
+ */
+export declare class NoSqlDbUnknownRootError extends Error {
+    readonly code: 'UNKNOWN_ROOT';
+    readonly responseErrorCode: 'UNKNOWN_ROOT';
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
 export declare class NoSqlDbManagementOperationTerminationError extends AggregateError {
     constructor(operationErrorArg: unknown, terminationErrorArg: unknown);
 }
@@ -131,6 +173,7 @@ interface INoSqlDbRustConfig {
     storagePath?: string;
     query?: INoSqlDbQueryOptions;
     inbound?: INoSqlDbInboundOptions;
+    storageBudgetBytes?: number;
     auth?: {
         enabled?: boolean;
         users?: Array<{
@@ -154,10 +197,30 @@ interface INoSqlDbRustConfig {
         maxBytes?: number;
     };
 }
-export declare function getRustDbAllocatorEnv(environment?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * What a spawn() that returned false after `waitedMs` means, stating only what
+ * is known. Smartrust refuses a `binaryPath` that does not pass its validation
+ * before spawn() can return false, so with one the engine there passed
+ * Smartrust's validation and did not report ready within the bridge's limit,
+ * and its path is given as the caller gave it.
+ * Without one, whatever NOSQLDB_RUST_BINARY holds (one of the places that
+ * Smartrust's search looks), either the search found no engine or the engine
+ * it found did not report ready, and nothing tells which.
+ */
+export declare function describeRefusedSpawn(binaryPath: string | undefined, waitedMs: number): string;
 export interface IRustDbBridgeOptions {
     /** Exact engine executable, validated by Smartrust without discovery fallback or permission changes. */
     binaryPath?: string;
+    /**
+     * Receives every line the engine writes to its standard error, in order and
+     * without its line break. Without it, no engine line reaches the host
+     * process's standard error. Either way the bridge keeps the last lines for
+     * errors (`noSqlDbEngineStderrTailLimits`). Each call runs in its own
+     * microtask after the bridge has recorded the line, so an exception it
+     * throws cannot disturb the bridge; it is not caught and reaches the process
+     * as an uncaught exception.
+     */
+    engineLog?: (line: string) => void;
 }
 /**
  * Bridge between TypeScript NoSqlDbServer and the Rust binary.
@@ -171,13 +234,73 @@ export declare class RustDbBridge extends EventEmitter {
      * termination, or when the bridge is connected to an external process.
      */
     get processId(): number | undefined;
+    /** The engine child process of the latest spawn, while the bridge holds it. */
+    private get childProcess();
+    /** How the engine process of the latest spawn exited, once it has. */
+    private engineExit;
+    private engineExitPromise;
+    /** Records the exit of the engine process that a spawn has just started. */
+    private watchEngineExit;
+    /**
+     * The exit code and signal of the engine process of the latest spawn, as its
+     * process exit reported them, each null where it reported none; or null
+     * while that process has not exited, or no spawn started one.
+     */
+    get lastEngineExit(): {
+        code: number | null;
+        signal: string | null;
+    } | null;
+    /** Whether the engine process of the latest spawn exists and has not exited. */
+    get engineProcessAlive(): boolean;
+    /** Waits up to `timeoutMs` for the engine process to exit by itself; resolves whether it has. */
+    waitForEngineExit(timeoutMs: number): Promise<boolean>;
+    /**
+     * Closes the engine's management input, the end of the management protocol
+     * after an acknowledged `stop`, on which the engine exits by itself. This is
+     * neither a signal nor a kill. Returns whether there was an input to close.
+     */
+    endManagementInput(): boolean;
     private terminationConfirmed;
     private terminationPromise;
     private terminationFailure;
+    private readonly stderrTail;
+    /** The `binaryPath` this bridge was given, if any, as given: the bridge's only configured path. */
+    private readonly binaryPath;
+    private spawnRefusal;
+    /**
+     * Why Smartrust's spawn() returned false, as far as the bridge knows. Each
+     * spawn() clears it as it starts, and sets it when Smartrust's spawn()
+     * returns false before this spawn()'s own `timeoutMs` or `signal` cuts it
+     * short, before the engine is ended. That spawn() then returns false, or
+     * throws if ending the engine fails. After any other spawn() it is
+     * undefined, including one cut short by its own `timeoutMs` or `signal`.
+     * Smartrust's spawn() returns false both when it finds no engine and when
+     * the engine it starts does not report ready within its limit; a
+     * `binaryPath` tells the two apart, as Smartrust refuses one that does not
+     * pass its validation with RustBinaryLocatorError before spawn() can return
+     * false.
+     */
+    get spawnFailureMessage(): string | undefined;
     constructor(options?: IRustDbBridgeOptions);
+    /**
+     * The last standard-error lines of the running or most recently spawned
+     * engine process, within `noSqlDbEngineStderrTailLimits`.
+     */
+    get engineStderrTail(): string[];
+    /**
+     * Send one management command. A failure while no engine runs (it exited
+     * or never started) carries the engine's last standard-error lines.
+     */
+    private send;
     /**
      * Spawn the Rust binary in management mode.
-     * Returns true if the binary was found and spawned successfully.
+     * Returns true once the engine reported ready. Returns false when
+     * Smartrust's spawn() returned false: no engine was found, or the one found
+     * did not report ready within the bridge's limit. spawnFailureMessage then
+     * says what that means, as far as the bridge knows, and still says it if
+     * ending that engine fails and this throws instead. After any other
+     * outcome, including a throw on this spawn()'s own `timeoutMs` or `signal`,
+     * spawnFailureMessage is undefined.
      */
     spawn(optionsArg?: INoSqlDbManagementOperationOptions): Promise<boolean>;
     /**