@lossless.org/nosqldb 8.0.0

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

@@ -0,0 +1,277 @@
+import * as plugins from './plugins.js';
+
+export const localNoSqlDbStorageRootRelocationErrorCodes = [
+  'INVALID_REQUEST',
+  'UNSUPPORTED',
+  'BUSY',
+  'NOT_FOUND',
+  'DESTINATION_CONFLICT',
+  'IDENTITY_MISMATCH',
+  'STATE_CORRUPT',
+  'SOURCE_CHANGED',
+  'CAPACITY',
+  'CANCELLED',
+  'IO',
+  'RECOVERY_REQUIRED',
+] as const;
+
+export type TLocalNoSqlDbStorageRootRelocationErrorCode =
+  (typeof localNoSqlDbStorageRootRelocationErrorCodes)[number];
+
+export interface ILocalNoSqlDbStoppedStorageRootRelocationInput {
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  relocationId: string;
+}
+
+export interface ILocalNoSqlDbStoppedStorageRootRelocationReceipt {
+  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 LocalNoSqlDbStorageRootRelocationError extends Error {
+  public readonly code: TLocalNoSqlDbStorageRootRelocationErrorCode;
+
+  public constructor(codeArg: TLocalNoSqlDbStorageRootRelocationErrorCode) {
+    super(`NoSQLDB stopped storage-root relocation failed with code ${codeArg}`);
+    this.name = 'LocalNoSqlDbStorageRootRelocationError';
+    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: TLocalNoSqlDbStorageRootRelocationErrorCode,
+): LocalNoSqlDbStorageRootRelocationError =>
+  new LocalNoSqlDbStorageRootRelocationError(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 normalizeLocalNoSqlDbStoppedStorageRootRelocationInput = (
+  inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
+): ILocalNoSqlDbStoppedStorageRootRelocationInput => {
+  if (!isPlainExactDataObject(inputArg, relocationInputKeys)) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const sourceFolderPath = normalizeFolderPath(inputArg.sourceFolderPath);
+  const destinationFolderPath = normalizeFolderPath(inputArg.destinationFolderPath);
+  if (
+    sourceFolderPath === destinationFolderPath
+    || isNestedPath(sourceFolderPath, destinationFolderPath)
+    || isNestedPath(destinationFolderPath, sourceFolderPath)
+  ) {
+    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<ILocalNoSqlDbStoppedStorageRootRelocationReceipt, '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 normalizeLocalNoSqlDbStoppedStorageRootRelocationReceipt = (
+  valueArg: unknown,
+  inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
+): ILocalNoSqlDbStoppedStorageRootRelocationReceipt => {
+  if (!isPlainExactDataObject(valueArg, relocationReceiptKeys)) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  const receipt = valueArg as unknown as ILocalNoSqlDbStoppedStorageRootRelocationReceipt;
+  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<ILocalNoSqlDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>;
+  if (receiptDigest(withoutDigest) !== receipt.receiptSha256) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  return { ...withoutDigest, receiptSha256: receipt.receiptSha256 };
+};
+
+export const assertNoLocalNoSqlDbStorageRootRelocationWorkspace = 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('NoSQLDB 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('NoSQLDB 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('NoSQLDB storage-root relocation workspace inspection is ambiguous');
+  }
+  throw new Error('NoSQLDB storage-root relocation recovery must complete before startup');
+};
+
+export const isLocalNoSqlDbStorageRootRelocationErrorCode = (
+  valueArg: unknown,
+): valueArg is TLocalNoSqlDbStorageRootRelocationErrorCode =>
+  typeof valueArg === 'string'
+  && localNoSqlDbStorageRootRelocationErrorCodes.includes(
+    valueArg as TLocalNoSqlDbStorageRootRelocationErrorCode,
+  );