@push.rocks/smartdb 5.0.4 → 5.1.0

package/ts/ts_smartdb/rust-db-bridge.ts

@@ -11,6 +11,11 @@ import {
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from './offline-inspection.js';
+import {
+  normalizeLocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationReceipt,
+} from './storage-root-relocation.js';
 import type {
   ISmartDbHealth,
   ISmartDbDatabaseTenantInput,
@@ -180,6 +185,10 @@ type TOfflinePhysicalNamespaceInspectionCommandParams = {
 } & ILocalSmartDbOfflinePhysicalNamespaceInspection['limits'];
 
 type TSmartDbCommands = {
+  relocateStoppedStorageRoot: {
+    params: ILocalSmartDbStoppedStorageRootRelocationInput;
+    result: ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  };
   inspectOfflinePhysicalNamespaces: {
     params: TOfflinePhysicalNamespaceInspectionCommandParams;
     result: ILocalSmartDbOfflinePhysicalNamespaceInspectionResult;
@@ -276,6 +285,10 @@ type TSmartDbCommands = {
   };
 };
 
+export const rustDbBridgeStorageRootRelocation = Symbol(
+  'smartdb.internal.storage-root-relocation',
+);
+
 export type TAuthMetadataPermissionTransitionStatus =
   | 'not-present'
   | 'already-target'
@@ -557,6 +570,19 @@ export class RustDbBridge extends EventEmitter {
 
   // --- Convenience methods for each management command ---
 
+  public async [rustDbBridgeStorageRootRelocation](
+    inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbStoppedStorageRootRelocationReceipt> {
+    const input = normalizeLocalSmartDbStoppedStorageRootRelocationInput(inputArg);
+    validateSmartDbManagementOperationOptions(optionsArg);
+    return await this.bridge.sendCommand(
+      'relocateStoppedStorageRoot',
+      input,
+      optionsArg,
+    ) as ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  }
+
   public async inspectOfflinePhysicalNamespaces(
     inputArg: ILocalSmartDbOfflinePhysicalNamespaceInspection,
     optionsArg?: ISmartDbManagementOperationOptions,

package/ts/ts_smartdb/server/SmartdbServer.ts

@@ -8,6 +8,7 @@ import {
   StorageMigrator,
 } from '../../ts_migration/index.js';
 import { validateSmartDbManagementOperationOptions } from '../offline-inspection.js';
+import { assertNoLocalSmartDbStorageRootRelocationWorkspace } from '../storage-root-relocation.js';
 import type {
   IOpLogEntry,
   IOpLogResult,
@@ -226,6 +227,8 @@ export class SmartdbServer {
       checkpoint();
       // Run storage migration for file-based storage before starting Rust engine
       if (this.options.storage === 'file' && this.options.storagePath) {
+        await assertNoLocalSmartDbStorageRootRelocationWorkspace(this.options.storagePath);
+        checkpoint();
         const migrator = new StorageMigrator(this.options.storagePath);
         await migrator.run(startupAbortController.signal);
         checkpoint();

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

@@ -0,0 +1,277 @@
+import * as plugins from './plugins.js';
+
+export const localSmartDbStorageRootRelocationErrorCodes = [
+  'INVALID_REQUEST',
+  'UNSUPPORTED',
+  'BUSY',
+  'NOT_FOUND',
+  'DESTINATION_CONFLICT',
+  'IDENTITY_MISMATCH',
+  'STATE_CORRUPT',
+  'IO',
+  'RECOVERY_REQUIRED',
+] as const;
+
+export type TLocalSmartDbStorageRootRelocationErrorCode =
+  (typeof localSmartDbStorageRootRelocationErrorCodes)[number];
+
+export interface ILocalSmartDbStoppedStorageRootRelocationInput {
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  relocationId: string;
+}
+
+export interface ILocalSmartDbStoppedStorageRootRelocationReceipt {
+  format: 'smartdb.storage-root-relocation.receipt.v1';
+  version: 1;
+  relocationId: string;
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  providerRootId: string;
+  storageRootDevice: string;
+  storageRootInode: string;
+  receiptSha256: string;
+  sourceReceiptRetained: true;
+}
+
+export class LocalSmartDbStorageRootRelocationError extends Error {
+  public readonly code: TLocalSmartDbStorageRootRelocationErrorCode;
+
+  public constructor(codeArg: TLocalSmartDbStorageRootRelocationErrorCode) {
+    super(`SmartDB stopped storage-root relocation failed with code ${codeArg}`);
+    this.name = 'LocalSmartDbStorageRootRelocationError';
+    this.code = codeArg;
+  }
+}
+
+const relocationInputKeys = [
+  'sourceFolderPath',
+  'destinationFolderPath',
+  'relocationId',
+] as const;
+const relocationReceiptKeys = [
+  'format',
+  'version',
+  'relocationId',
+  'sourceFolderPath',
+  'destinationFolderPath',
+  'providerRootId',
+  'storageRootDevice',
+  'storageRootInode',
+  'receiptSha256',
+  'sourceReceiptRetained',
+] as const;
+const maximumFolderPathBytes = 4095;
+const maximumRelocationIdBytes = 256;
+const maximumU64Decimal = '18446744073709551615';
+const receiptDigestDomain = 'smartdb.storage-root-relocation.receipt.v1\0';
+
+const relocationError = (
+  codeArg: TLocalSmartDbStorageRootRelocationErrorCode,
+): LocalSmartDbStorageRootRelocationError =>
+  new LocalSmartDbStorageRootRelocationError(codeArg);
+
+const isPlainExactDataObject = (
+  valueArg: unknown,
+  keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || Array.isArray(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Object.prototype
+  ) {
+    return false;
+  }
+  const ownKeys = Reflect.ownKeys(valueArg);
+  if (
+    ownKeys.length !== keysArg.length
+    || ownKeys.some((keyArg) => typeof keyArg !== 'string' || !keysArg.includes(keyArg))
+  ) {
+    return false;
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  return keysArg.every((keyArg) => {
+    const descriptor = descriptors[keyArg];
+    return descriptor !== undefined
+      && descriptor.enumerable
+      && Object.prototype.hasOwnProperty.call(descriptor, 'value');
+  });
+};
+
+const isValidUnicodeScalarString = (valueArg: string): boolean => {
+  for (let index = 0; index < valueArg.length; index++) {
+    const code = valueArg.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = valueArg.charCodeAt(index + 1);
+      if (next < 0xdc00 || next > 0xdfff) return false;
+      index++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const isNestedPath = (parentArg: string, childArg: string): boolean => {
+  const relative = plugins.path.relative(parentArg, childArg);
+  return relative !== ''
+    && relative !== '..'
+    && !relative.startsWith(`..${plugins.path.sep}`)
+    && !plugins.path.isAbsolute(relative);
+};
+
+const normalizeFolderPath = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || !plugins.path.isAbsolute(valueArg)
+    || !isValidUnicodeScalarString(valueArg)
+    || [...valueArg].some(characterArg => /\p{Cc}/u.test(characterArg))
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const initialBytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+  if (initialBytes < 1 || initialBytes > maximumFolderPathBytes) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const normalized = plugins.path.resolve(valueArg);
+  const normalizedBytes = plugins.buffer.Buffer.byteLength(normalized, 'utf8');
+  if (
+    normalizedBytes < 1
+    || normalizedBytes > maximumFolderPathBytes
+    || plugins.path.parse(normalized).root === normalized
+    || !isValidUnicodeScalarString(normalized)
+    || [...normalized].some(characterArg => /\p{Cc}/u.test(characterArg))
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  return normalized;
+};
+
+export const normalizeLocalSmartDbStoppedStorageRootRelocationInput = (
+  inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+): ILocalSmartDbStoppedStorageRootRelocationInput => {
+  if (!isPlainExactDataObject(inputArg, relocationInputKeys)) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const sourceFolderPath = normalizeFolderPath(inputArg.sourceFolderPath);
+  const destinationFolderPath = normalizeFolderPath(inputArg.destinationFolderPath);
+  const sourceFolderPathBytes = plugins.buffer.Buffer.byteLength(sourceFolderPath, 'utf8');
+  const destinationFolderPathBytes = plugins.buffer.Buffer.byteLength(destinationFolderPath, 'utf8');
+  if (
+    sourceFolderPath === destinationFolderPath
+    || isNestedPath(sourceFolderPath, destinationFolderPath)
+    || isNestedPath(destinationFolderPath, sourceFolderPath)
+    || destinationFolderPathBytes > sourceFolderPathBytes
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  if (
+    typeof inputArg.relocationId !== 'string'
+    || plugins.buffer.Buffer.byteLength(inputArg.relocationId, 'utf8') > maximumRelocationIdBytes
+    || !/^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(inputArg.relocationId)
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  return {
+    sourceFolderPath,
+    destinationFolderPath,
+    relocationId: inputArg.relocationId,
+  };
+};
+
+const receiptDigest = (
+  receiptArg: Omit<ILocalSmartDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>,
+): string => plugins.crypto
+  .createHash('sha256')
+  .update(receiptDigestDomain, 'utf8')
+  .update(JSON.stringify(receiptArg), 'utf8')
+  .digest('hex');
+
+const isCanonicalU64Decimal = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string'
+  && /^(?:0|[1-9][0-9]{0,19})$/.test(valueArg)
+  && (valueArg.length < 20 || valueArg <= maximumU64Decimal);
+
+const isLowercaseSha256 = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[0-9a-f]{64}$/.test(valueArg);
+
+export const normalizeLocalSmartDbStoppedStorageRootRelocationReceipt = (
+  valueArg: unknown,
+  inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+): ILocalSmartDbStoppedStorageRootRelocationReceipt => {
+  if (!isPlainExactDataObject(valueArg, relocationReceiptKeys)) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  const receipt = valueArg as unknown as ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  if (
+    receipt.format !== 'smartdb.storage-root-relocation.receipt.v1'
+    || receipt.version !== 1
+    || receipt.relocationId !== inputArg.relocationId
+    || receipt.sourceFolderPath !== inputArg.sourceFolderPath
+    || receipt.destinationFolderPath !== inputArg.destinationFolderPath
+    || !isLowercaseSha256(receipt.providerRootId)
+    || !isCanonicalU64Decimal(receipt.storageRootDevice)
+    || !isCanonicalU64Decimal(receipt.storageRootInode)
+    || !isLowercaseSha256(receipt.receiptSha256)
+    || receipt.sourceReceiptRetained !== true
+  ) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  const withoutDigest = {
+    format: receipt.format,
+    version: receipt.version,
+    relocationId: receipt.relocationId,
+    sourceFolderPath: receipt.sourceFolderPath,
+    destinationFolderPath: receipt.destinationFolderPath,
+    providerRootId: receipt.providerRootId,
+    storageRootDevice: receipt.storageRootDevice,
+    storageRootInode: receipt.storageRootInode,
+    sourceReceiptRetained: receipt.sourceReceiptRetained,
+  } satisfies Omit<ILocalSmartDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>;
+  if (receiptDigest(withoutDigest) !== receipt.receiptSha256) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  return { ...withoutDigest, receiptSha256: receipt.receiptSha256 };
+};
+
+export const assertNoLocalSmartDbStorageRootRelocationWorkspace = async (
+  storagePathArg: string,
+): Promise<void> => {
+  const storagePath = plugins.path.resolve(storagePathArg);
+  const internalPath = plugins.path.join(storagePath, '.__rustdb_internal');
+  const workspacePath = plugins.path.join(internalPath, 'storage-root-relocation');
+  try {
+    const storage = await plugins.fs.stat(storagePath);
+    if (!storage.isDirectory()) {
+      throw new Error('not a directory');
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  try {
+    const internal = await plugins.fs.lstat(internalPath);
+    if (internal.isSymbolicLink() || !internal.isDirectory()) {
+      throw new Error('not a safe directory');
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  try {
+    await plugins.fs.lstat(workspacePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  throw new Error('SmartDB storage-root relocation recovery must complete before startup');
+};
+
+export const isLocalSmartDbStorageRootRelocationErrorCode = (
+  valueArg: unknown,
+): valueArg is TLocalSmartDbStorageRootRelocationErrorCode =>
+  typeof valueArg === 'string'
+  && localSmartDbStorageRootRelocationErrorCodes.includes(
+    valueArg as TLocalSmartDbStorageRootRelocationErrorCode,
+  );