@lossless.org/nosqldb 10.11.0 → 11.0.0

package/ts/ts_nosqldb/server/index.ts

@@ -0,0 +1,4 @@
+// Server module exports
+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/service-types.ts

@@ -0,0 +1,499 @@
+export interface INoSqlDbHealth {
+  /** Present on engines supporting stopped root alignment. */
+  providerRootId?: string;
+  lsn?: string | null;
+  running: boolean;
+  storage?: 'memory' | 'file';
+  fileStorageEngine?: 'mvcc';
+  storagePurpose?: 'production' | 'rehearsal';
+  storageRehearsalId?: string | null;
+  storagePath?: string;
+  resourceFencingVersion?: 1;
+  resourceFencingSupported?: boolean;
+  resourceFencingRequiresDrain?: true;
+  allocationFencingVersion?: 1;
+  allocationFencingSupported?: boolean;
+  allocationFencingRequiresDrain?: true;
+  databaseAllocationReadAccessGrantVersion?: 1;
+  databaseAllocationReadAccessGrantSupported?: true;
+  publicationHoldVersion: 1;
+  publicationHoldSupported: boolean;
+  publicationHoldRequiresExternalDrain: boolean;
+  authEnabled?: boolean;
+  authUsers?: number;
+  usersPathConfigured?: boolean;
+  databaseCount: number;
+  collectionCount: number;
+  uptimeSeconds?: number;
+}
+
+/** Per-operation admission bounds for read-only stopped native storage inspection. */
+export interface ILocalNoSqlDbOfflineInspectionLimits {
+  maximumEntries: number;
+  maximumTotalFileBytes: number;
+  maximumRecords: number;
+  maximumRecordBytes: number;
+  maximumResultBytes: number;
+}
+
+export interface ILocalNoSqlDbOfflineStringValueInspection {
+  folderPath: string;
+  databaseName: string;
+  collectionName: string;
+  match: {
+    field: string;
+    value: string;
+  };
+  valueField: string;
+  limits: ILocalNoSqlDbOfflineInspectionLimits;
+}
+
+export type TLocalNoSqlDbOfflineStringValueInspectionResult =
+  | { status: 'not-found' }
+  | { status: 'found'; value: string };
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits {
+  maximumEntries: number;
+  maximumDatabases: number;
+  maximumCollections: number;
+  maximumIndexes: number;
+  maximumTotalFileBytes: number;
+  maximumRecordsPerCollection: number;
+  maximumRecordBytes: number;
+  maximumResultBytes: number;
+}
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspection {
+  folderPath: string;
+  limits: ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits;
+}
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult {
+  schemaVersion: 1;
+  databases: Array<{
+    name: string;
+    collections: string[];
+  }>;
+}
+
+export const noSqlDbResourceFenceErrorCodes = [
+  'EFENCE_REQUIRED',
+  'EFENCE_STALE',
+  'EFENCE_SCOPE_MISMATCH',
+  'EFENCE_UNSUPPORTED',
+  'EFENCE_MUTATION_MISMATCH',
+  'EFENCE_OWNERSHIP_MISMATCH',
+  'EFENCE_STATE_CORRUPT',
+  'EFENCE_RECEIPT_LIMIT',
+  'EFENCE_BUSY',
+  '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 TNoSqlDbResourceFenceErrorCode =
+  (typeof noSqlDbResourceFenceErrorCodes)[number];
+
+export interface INoSqlDbResourceFence {
+  version: 1;
+  scopeId: string;
+  token: number;
+  mutationId: string;
+  payloadSha256: string;
+}
+
+export interface INoSqlDbResourceFenceReceipt
+  extends INoSqlDbResourceFence {
+  kind:
+    | 'smartdb.database.replace.v1'
+    | 'smartdb.database.delete.v1'
+    | 'smartdb.database.ensure.v1'
+    | 'smartdb.database.allocate.v1';
+  /** Digest of the canonical payload interpretation derived by NoSQLDB. */
+  effectivePayloadSha256: string;
+  provider?: 'smartdb';
+  resourceIdSha256?: string;
+  holdPublication?: true;
+  publicationState?: 'held' | 'released';
+  bindingSha256?: string;
+  resultSha256?: string;
+  receiptSha256?: string;
+  publicationCapabilitySha256?: string;
+  /** Present only while publication is held; never returned after release. */
+  publicationCapability?: string;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDatabaseAllocationIdentity {
+  version: 1;
+  provider: 'smartdb';
+  state: 'active';
+  databaseName: string;
+  username: string;
+  allocationId: string;
+  generation: number;
+  principalId: string;
+  resourceIdSha256: string;
+  bindingSha256: string;
+  receiptSha256: string;
+}
+
+export interface INoSqlDbDatabaseAllocationLifecycle {
+  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 INoSqlDbDatabaseAllocationReadAccessGrantIdentity {
+  version: 1;
+  grantId: string;
+  principalId: string;
+  generation: number;
+}
+
+export interface INoSqlDbIssueDatabaseAllocationReadAccessGrantInput {
+  databaseName: string;
+  grantId: string;
+  username: string;
+  password: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbIssueDatabaseAllocationReadAccessGrantResult {
+  databaseName: string;
+  username: string;
+  roles: ['read'];
+  authSource: string;
+  mongodbUri?: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+  grant: INoSqlDbDatabaseAllocationReadAccessGrantIdentity;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export interface INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput {
+  databaseName: string;
+  grantId: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult {
+  databaseName: string;
+  grantId: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+  revoked: true;
+}
+
+export const noSqlDbAllocationReadAccessGrantErrorCodes = [
+  'EGRANT_INVALID_REQUEST',
+  'EGRANT_CREDENTIAL_MISMATCH',
+  'EGRANT_CONFLICT',
+  'EGRANT_REPLAY_CAPACITY',
+  'EGRANT_STATE_UNAVAILABLE',
+] as const;
+
+export type TNoSqlDbAllocationReadAccessGrantErrorCode =
+  (typeof noSqlDbAllocationReadAccessGrantErrorCodes)[number];
+
+export class NoSqlDbAllocationReadAccessGrantError extends Error {
+  public readonly code: TNoSqlDbAllocationReadAccessGrantErrorCode;
+
+  public constructor(
+    codeArg: TNoSqlDbAllocationReadAccessGrantErrorCode,
+    messageArg: string,
+    causeArg?: unknown,
+  ) {
+    super(`${codeArg}: ${messageArg}`, { cause: causeArg });
+    this.name = 'NoSqlDbAllocationReadAccessGrantError';
+    this.code = codeArg;
+  }
+}
+
+export const normalizeNoSqlDbAllocationReadAccessGrantError = (
+  errorArg: unknown,
+  codeArg?: unknown,
+): Error => {
+  const error =
+    errorArg instanceof Error
+      ? errorArg
+      : new Error(String(errorArg));
+  if (
+    typeof codeArg !== 'string'
+    || !noSqlDbAllocationReadAccessGrantErrorCodes.includes(
+      codeArg as TNoSqlDbAllocationReadAccessGrantErrorCode,
+    )
+  ) {
+    return error;
+  }
+  return new NoSqlDbAllocationReadAccessGrantError(
+    codeArg as TNoSqlDbAllocationReadAccessGrantErrorCode,
+    error.message,
+    error,
+  );
+};
+
+export interface INoSqlDbHeldPublicationReceipt
+  extends INoSqlDbResourceFenceReceipt {
+  provider: 'smartdb';
+  resourceIdSha256: string;
+  holdPublication: true;
+  publicationState: 'held';
+  bindingSha256: string;
+  resultSha256: string;
+  receiptSha256: string;
+  publicationCapabilitySha256: string;
+  publicationCapability: string;
+}
+
+export interface INoSqlDbCommitDatabasePublicationInput {
+  databaseName: string;
+  resourceFence: INoSqlDbHeldPublicationReceipt;
+}
+
+/**
+ * Cancellation and deadline ownership for one durable database-management
+ * operation. Aborting or timing out is fail-stop: NoSQLDB terminates the Rust
+ * engine so the operation cannot continue after the caller has released it.
+ */
+export interface INoSqlDbManagementOperationOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface INoSqlDbDatabaseResourceFenceState {
+  providerRootId?: string;
+  version: 1;
+  databaseName: string;
+  resourceIdSha256: string;
+  scopeId: string;
+  highestToken: number;
+  publicationState: 'requested' | 'publishing' | 'held' | 'released';
+  allocation?: INoSqlDbDatabaseAllocationLifecycle;
+}
+
+export class NoSqlDbResourceFenceError extends Error {
+  public readonly code: TNoSqlDbResourceFenceErrorCode;
+
+  public constructor(
+    codeArg: TNoSqlDbResourceFenceErrorCode,
+    messageArg: string,
+    causeArg?: unknown,
+  ) {
+    super(`${codeArg}: ${messageArg}`, { cause: causeArg });
+    this.name = 'NoSqlDbResourceFenceError';
+    this.code = codeArg;
+  }
+}
+
+export const normalizeNoSqlDbResourceFenceError = (
+  errorArg: unknown,
+): Error => {
+  const error =
+    errorArg instanceof Error
+      ? errorArg
+      : new Error(String(errorArg));
+  const match = /^((?:EFENCE|EALLOCATION)_[A-Z_]+):\s*(.*)$/s.exec(error.message);
+  if (
+    !match ||
+    !noSqlDbResourceFenceErrorCodes.includes(
+      match[1] as TNoSqlDbResourceFenceErrorCode,
+    )
+  ) {
+    return error;
+  }
+  return new NoSqlDbResourceFenceError(
+    match[1] as TNoSqlDbResourceFenceErrorCode,
+    match[2],
+    error,
+  );
+};
+
+export interface INoSqlDbDatabaseTenantInput {
+  databaseName: string;
+  username: string;
+  password: string;
+  roles?: string[];
+}
+
+export interface INoSqlDbEnsureDatabaseTenantInput
+  extends INoSqlDbDatabaseTenantInput {
+  fence: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbAttestDatabaseTenantInput {
+  databaseName: string;
+  username: string;
+  roles: string[];
+  password: string;
+}
+
+export interface INoSqlDbAttestDatabaseTenantResult {
+  matches: boolean;
+}
+
+export interface INoSqlDbAllocateDatabaseTenantInput
+  extends INoSqlDbDatabaseTenantInput {
+  expectedAbsent: true;
+  fence: INoSqlDbResourceFence;
+}
+
+export interface INoSqlDbDeleteDatabaseTenantInput {
+  databaseName: string;
+  /**
+   * Exact tenant user to revoke. For a fenced deletion this identity is
+   * included in the durable mutation and is removed idempotently after the
+   * database deletion is durable. Omitting it from a fenced deletion
+   * preserves auth users; an unfenced omission retains the legacy behavior
+   * of deleting every user for the database. If the database exists, a
+   * fenced deletion fails closed unless this exact user currently owns it.
+   */
+  username?: string;
+  fence?: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
+}
+
+export interface INoSqlDbRotateDatabaseTenantPasswordInput {
+  username: string;
+  password: string;
+}
+
+export interface INoSqlDbDatabaseTenantDescriptor {
+  databaseName: string;
+  username: string;
+  roles: string[];
+  authSource: string;
+  mongodbUri?: string;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbEnsureDatabaseTenantResult
+  extends INoSqlDbDatabaseTenantDescriptor {
+  resourceFence: INoSqlDbResourceFenceReceipt;
+}
+
+export interface INoSqlDbAllocateDatabaseTenantResult
+  extends INoSqlDbDatabaseTenantDescriptor {
+  resourceFence: INoSqlDbResourceFenceReceipt;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDeleteDatabaseTenantResult {
+  databaseName: string;
+  /**
+   * Users removed during the completing attempt. This can be zero after
+   * crash recovery when the exact user was durably removed by the prior
+   * attempt.
+   */
+  deletedUsers: number;
+  databaseDropped: boolean;
+  /**
+   * Present for fenced calls. False means the bound exact username is now
+   * absent; true means no username was supplied and auth users were preserved.
+   */
+  usersPreserved?: boolean;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDatabaseExportCollection {
+  name: string;
+  /**
+   * Collection options exactly as `listCollections` reports them
+   * (`validator`, `validationLevel`, `validationAction`). Present only when
+   * the collection has options; engines up to 10.6.1 refuse such an export.
+   */
+  options?: Record<string, any>;
+  documents: Record<string, any>[];
+  indexes: Record<string, any>[];
+}
+
+export interface INoSqlDbDatabaseExportLimits {
+  maxEncodedBytes?: number;
+  maxCollections?: number;
+  maxDocuments?: number;
+  maxIndexes?: number;
+}
+
+export interface INoSqlDbExportDatabaseInput {
+  databaseName: string;
+  limits?: INoSqlDbDatabaseExportLimits;
+}
+
+/** Management-only read under an exact, still-held publication capability. */
+export interface INoSqlDbExportHeldDatabaseInput extends INoSqlDbExportDatabaseInput {
+  resourceFence: INoSqlDbHeldPublicationReceipt;
+}
+
+export interface INoSqlDbDatabaseContentDigestLimits {
+  maxScannedBsonBytes?: number;
+  maxCollections?: number;
+  maxDocuments?: number;
+  maxIndexes?: number;
+}
+
+export interface INoSqlDbGetDatabaseContentDigestInput {
+  databaseName: string;
+  limits?: INoSqlDbDatabaseContentDigestLimits;
+}
+
+export interface INoSqlDbDatabaseContentDigest {
+  format: 'smartdb.database.content-digest.v1';
+  algorithm: 'sha256';
+  databaseName: string;
+  sha256: string;
+  scannedBsonBytes: number;
+  collections: number;
+  documents: number;
+  indexes: number;
+}
+
+export interface INoSqlDbDatabaseExport {
+  format: 'smartdb.database.export.v1';
+  databaseName: string;
+  exportedAtMs: number;
+  collections: INoSqlDbDatabaseExportCollection[];
+}
+
+export interface INoSqlDbImportDatabaseInput {
+  databaseName: string;
+  source: INoSqlDbDatabaseExport;
+  /**
+   * Exact exclusive tenant owner required for this replacement. When used
+   * with a fence, the username is included in the provider-derived mutation
+   * identity. Omission preserves the original version 1 replacement profile.
+   */
+  username?: string;
+  fence?: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
+}
+
+export interface INoSqlDbImportDatabaseResult {
+  databaseName: string;
+  collections: number;
+  documents: number;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export type TNoSqlDbCommitDatabasePublicationResult =
+  | INoSqlDbImportDatabaseResult
+  | INoSqlDbDeleteDatabaseTenantResult;

package/ts/ts_nosqldb/stopped-storage.ts

@@ -0,0 +1,116 @@
+import * as plugins from './plugins.js';
+import { validateNoSqlDbManagementOperationOptions } from './offline-inspection.js';
+import type { INoSqlDbManagementOperationOptions } from './service-types.js';
+import type { TLocalNoSqlDbStorageRootRelocationErrorCode } from './storage-root-relocation.js';
+
+export interface INoSqlDbStoppedOperationOptions extends INoSqlDbManagementOperationOptions {
+  /** Exact executable; invalid explicit paths never fall back to discovery. */
+  binaryPath?: string;
+}
+
+export interface ILocalNoSqlDbStoppedStorageRootInspectionInput { folderPath: string; }
+export type TNoSqlDbStorageRootBindingChange = 'none' | 'path' | 'inode' | 'path+inode';
+export interface INoSqlDbPhysicalAdmissionViolation {
+  relativePath: string;
+  rule: string;
+  observed: string;
+}
+export interface ILocalNoSqlDbAuditedStorageRoot {
+  status: 'audited';
+  bindingState: 'matching' | 'foreign';
+  bindingChange: TNoSqlDbStorageRootBindingChange;
+  storagePurpose: 'production';
+  profileSchema: 1 | 4;
+  providerRootId: string;
+  /** Group/timeline describe shared lineage, not independent provider identity. */
+  groupId: string;
+  timelineId: string;
+  /** All counts and positions are canonical unsigned decimal strings. */
+  lsn: string;
+  records: string;
+  recordsSha256: string;
+  recordsWithoutFencingProfileSha256: string;
+  authUsers: string;
+  authority: {
+    resourceFences: string;
+    receipts: string;
+    publicationHolds: string;
+    activeAllocations: string;
+    retiredAllocations: string;
+    allocationReplays: string;
+    activeGrants: '0';
+    importStages: '0';
+  };
+  /**
+   * 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: [];
+}
+export interface ILocalNoSqlDbUnavailableStorageRoot {
+  status: 'unavailable';
+  stage: 'admission' | 'audit';
+  alignmentEligible: false;
+  reasons: string[];
+  /** Bounded advisory evidence. No logical identity or pin is trusted here. */
+  physicalAdmissionViolations: INoSqlDbPhysicalAdmissionViolation[];
+}
+export type TLocalNoSqlDbStoppedStorageRootInspection =
+  ILocalNoSqlDbAuditedStorageRoot | ILocalNoSqlDbUnavailableStorageRoot;
+
+export class NoSqlDbStoppedOperationError extends Error {
+  public readonly responseErrorCode: TLocalNoSqlDbStorageRootRelocationErrorCode;
+  public constructor(public readonly code: TLocalNoSqlDbStorageRootRelocationErrorCode) {
+    super(`NoSQLDB stopped operation failed with code ${code}`);
+    this.name = 'NoSqlDbStoppedOperationError';
+    this.responseErrorCode = code;
+  }
+}
+
+export const validateNoSqlDbStoppedOperationOptions = (options?: INoSqlDbStoppedOperationOptions): void => {
+  validateNoSqlDbManagementOperationOptions(options);
+  if (options?.binaryPath !== undefined && (typeof options.binaryPath !== 'string'
+    || !options.binaryPath.length || options.binaryPath.includes('\0'))) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+};
+
+export const normalizeStoppedStorageRootInspectionInput = (
+  input: ILocalNoSqlDbStoppedStorageRootInspectionInput,
+): ILocalNoSqlDbStoppedStorageRootInspectionInput => {
+  if (!input || Object.getPrototypeOf(input) !== Object.prototype
+    || Reflect.ownKeys(input).length !== 1
+    || !Object.getOwnPropertyDescriptor(input, 'folderPath')?.enumerable
+    || !('value' in Object.getOwnPropertyDescriptor(input, 'folderPath')!)) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+  const folderPath = input.folderPath;
+  if (typeof folderPath !== 'string' || plugins.buffer.Buffer.byteLength(folderPath) > 4095
+    || !plugins.path.isAbsolute(folderPath) || plugins.path.dirname(folderPath) === folderPath
+    || folderPath.endsWith('/') || folderPath.includes('//') || /\p{Cc}/u.test(folderPath)
+    || folderPath.split('/').some(part => part === '.' || part === '..' || part.startsWith('.smartdb-rehearsal-'))) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+  return { folderPath };
+};
+
+/** Only a confirmed Rust response for this exact command proves non-dispatch.
+ * Transport errors with the same text remain ambiguous. */
+export const isStoppedOperationUnknownMethod = (error: unknown, method: string): boolean =>
+  error instanceof Error && 'code' in error
+  && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
+  && 'requestId' in error && typeof error.requestId === 'string' && error.requestId.length > 0
+  && 'method' in error && error.method === method
+  && (('responseErrorCode' in error && error.responseErrorCode === 'UNKNOWN_METHOD')
+    || ((!('responseErrorCode' in error) || error.responseErrorCode === undefined)
+      && error.message === `Unknown method: ${method}`));
+
+export const normalizeStoppedOperationUnknownMethod = (error: unknown, method: string): unknown =>
+  isStoppedOperationUnknownMethod(error, method) ? new NoSqlDbStoppedOperationError('UNSUPPORTED') : error;