@serve.zone/dcrouter 34.0.0 → 34.2.0

package/ts/migrate-command.ts

@@ -0,0 +1,198 @@
+import * as plugins from './plugins.js';
+import { createDowngradeMigrationRunner, DcRouterMigrationError } from '../ts_migrations/index.js';
+import type { IDowngradeMigrationRunResult } from '../ts_migrations/index.js';
+
+/** The prefix of the one line `dcrouter migrate` ends with: the outcome as JSON. */
+export const migrateResultLinePrefix = 'DCROUTER_MIGRATE_RESULT:';
+
+export const migrateCommandUsage = `Usage:
+  dcrouter migrate --storage-path <absolute path> --to <version> [--db-name <name>] [--plan]
+
+Walks the data of a stopped dcrouter back to an earlier data version, running each
+step's down handler. Forward migrations happen when dcrouter starts.
+
+  --storage-path <path>   The embedded database's storage root (absolute; no default)
+  --to <version>          The data version to walk back to, a step boundary
+  --db-name <name>        The database inside the root (default: dcrouter)
+  --plan                  Report the steps the downgrade would run, change nothing
+
+The root must not be in use: the command refuses a root a running dcrouter owns.
+The last line of the output is ${migrateResultLinePrefix}{json}.
+`;
+
+/** A command line `dcrouter migrate` refuses before it opens anything. */
+export class MigrateCommandUsageError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'MigrateCommandUsageError';
+  }
+}
+
+export interface IMigrateCommandOptions {
+  storagePath: string;
+  targetVersion: string;
+  dbName: string;
+  planOnly: boolean;
+}
+
+export type TMigrateCommandResult =
+  | ({ ok: true; plan: boolean; storagePath: string; dbName: string } & IDowngradeMigrationRunResult)
+  | { ok: false; error: { name: string; code?: string; message: string } };
+
+/**
+ * The stopped-root check's bounds: the largest every input admits (smartdb readme, "Offline
+ * Physical Namespace Inspection"). A root over any of them is refused, never partly inspected: a
+ * data file over `maximumDataFileBytes` fails the whole inspection with `ERESOURCE_LIMIT`
+ * (nosqldb 5.7.1 `rustdb-storage/src/offline_inspection/physical_namespace_inspection.rs:760`).
+ */
+export const offlineInspectionLimits: plugins.smartdb.ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits = {
+  maximumEntries: 100_000,
+  maximumDatabases: 4_096,
+  maximumCollections: 10_000,
+  maximumIndexes: 100_000,
+  maximumDataFileBytes: 268_435_456,
+  maximumWalFileBytes: 67_108_864,
+  maximumIndexFileBytes: 16_777_216,
+  maximumTotalFileBytes: 1_099_511_627_776,
+  maximumRecordsPerCollection: 1_000_000,
+  maximumRecordBytes: 17_825_792,
+  maximumResultBytes: 16_777_216,
+};
+const offlineInspectionTimeoutMs = 10 * 60_000;
+
+export function parseMigrateArguments(argsArg: string[]): IMigrateCommandOptions {
+  let storagePath: string | undefined;
+  let targetVersion: string | undefined;
+  let dbName = 'dcrouter';
+  let planOnly = false;
+  const valueOf = (indexArg: number, flagArg: string) => {
+    const value = argsArg[indexArg + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new MigrateCommandUsageError(`${flagArg} needs a value.`);
+    }
+    return value;
+  };
+  for (let index = 0; index < argsArg.length; index++) {
+    const arg = argsArg[index];
+    switch (arg) {
+      case '--storage-path':
+        storagePath = valueOf(index++, arg);
+        break;
+      case '--to':
+        targetVersion = valueOf(index++, arg);
+        break;
+      case '--db-name':
+        dbName = valueOf(index++, arg);
+        break;
+      case '--plan':
+        planOnly = true;
+        break;
+      default:
+        throw new MigrateCommandUsageError(`Unknown argument "${arg}".`);
+    }
+  }
+  if (!storagePath) throw new MigrateCommandUsageError('--storage-path is required.');
+  if (!plugins.path.isAbsolute(storagePath)) {
+    throw new MigrateCommandUsageError(`--storage-path must be an absolute path, not "${storagePath}".`);
+  }
+  if (!targetVersion) throw new MigrateCommandUsageError('--to is required.');
+  return { storagePath: plugins.path.resolve(storagePath), targetVersion, dbName, planOnly };
+}
+
+/**
+ * Runs the downgrade offline: a stopped-root check first, then the engine, whose owner lock refuses
+ * a root a running dcrouter holds, then the reverse migration. Both handles are released before it
+ * returns, whatever happened.
+ */
+export async function runMigrateCommandOptions(optionsArg: IMigrateCommandOptions): Promise<TMigrateCommandResult> {
+  // Refuses a root an engine holds (the sidecar takes the shared owner lock), a root that is not a
+  // current SmartDB root, and any file that does not validate, before the engine is started.
+  const inspection = await plugins.smartdb.LocalSmartDb.inspectOfflinePhysicalNamespaces(
+    { folderPath: optionsArg.storagePath, limits: offlineInspectionLimits },
+    { timeoutMs: offlineInspectionTimeoutMs },
+  );
+  const databaseNames = inspection.databases.map((databaseArg) => databaseArg.name);
+  if (!databaseNames.includes(optionsArg.dbName)) {
+    throw new DcRouterMigrationError(
+      `The storage root holds no database "${optionsArg.dbName}" (it holds ${databaseNames.length > 0
+        ? databaseNames.map((nameArg) => `"${nameArg}"`).join(', ')
+        : 'none'}). Nothing was changed.`,
+    );
+  }
+
+  const localSmartDb = new plugins.smartdb.LocalSmartDb({ folderPath: optionsArg.storagePath });
+  let db: plugins.smartdata.SmartdataDb | undefined;
+  let failure: { error: unknown } | undefined;
+  try {
+    const { connectionUri } = await localSmartDb.start();
+    db = new plugins.smartdata.SmartdataDb({ mongoDbUrl: connectionUri, mongoDbName: optionsArg.dbName });
+    await db.init();
+    const runner = await createDowngradeMigrationRunner(db, optionsArg.targetVersion);
+    const result = optionsArg.planOnly ? await runner.plan() : await runner.run();
+    return {
+      ok: true,
+      plan: optionsArg.planOnly,
+      storagePath: optionsArg.storagePath,
+      dbName: optionsArg.dbName,
+      currentVersionBefore: result.currentVersionBefore,
+      currentVersionAfter: result.currentVersionAfter,
+      targetVersion: result.targetVersion,
+      wasUpToDate: result.wasUpToDate,
+      wasFreshInstall: result.wasFreshInstall,
+      totalDurationMs: result.totalDurationMs,
+      stepsApplied: result.stepsApplied.map(({ id, fromVersion, toVersion, status }) => ({ id, fromVersion, toVersion, status })),
+      stepsSkipped: result.stepsSkipped.map(({ id, fromVersion, toVersion, status }) => ({ id, fromVersion, toVersion, status })),
+    };
+  } catch (error: unknown) {
+    failure = { error };
+    throw error;
+  } finally {
+    // Both handles are released whatever happened. A cleanup failure after a failed migration is
+    // reported beside it, and the migration's own error stays the one the command answers with.
+    const cleanupErrors: unknown[] = [];
+    for (const release of [() => db?.close(), () => localSmartDb.stop()]) {
+      try {
+        await release();
+      } catch (cleanupError: unknown) {
+        cleanupErrors.push(cleanupError);
+      }
+    }
+    if (cleanupErrors.length > 0 && !failure) {
+      throw new AggregateError(cleanupErrors, 'dcrouter migrate could not release the database');
+    }
+    for (const cleanupError of failure ? cleanupErrors : []) {
+      console.error(`dcrouter migrate: releasing the database also failed: ${describeMigrateError(cleanupError).message}`);
+    }
+  }
+}
+
+const describeMigrateError = (errorArg: unknown): { name: string; code?: string; message: string } => {
+  if (!(errorArg instanceof Error)) return { name: 'Error', message: String(errorArg) };
+  const code = (errorArg as Error & { code?: unknown }).code;
+  return {
+    name: errorArg.name,
+    ...(typeof code === 'string' ? { code } : {}),
+    message: errorArg.message,
+  };
+};
+
+/** `dcrouter migrate …`; resolves to the process exit code and prints the result line last. */
+export async function runMigrateCommand(argsArg: string[]): Promise<number> {
+  if (argsArg.includes('--help') || argsArg.includes('-h')) {
+    console.log(migrateCommandUsage);
+    return 0;
+  }
+  let result: TMigrateCommandResult;
+  let exitCode: number;
+  try {
+    result = await runMigrateCommandOptions(parseMigrateArguments(argsArg));
+    exitCode = 0;
+  } catch (error: unknown) {
+    result = { ok: false, error: describeMigrateError(error) };
+    exitCode = error instanceof MigrateCommandUsageError ? 2 : 1;
+    console.error(`dcrouter migrate: ${result.error.message}`);
+    if (error instanceof MigrateCommandUsageError) console.error(migrateCommandUsage);
+  }
+  console.log(`${migrateResultLinePrefix}${JSON.stringify(result)}`);
+  return exitCode;
+}

package/ts/plugins.ts

@@ -115,6 +115,7 @@ export {
 
 // third party
 import * as argon2 from 'argon2';
+import * as bson from 'bson';
 import * as lruCache from 'lru-cache';
 import ipaddr from 'ipaddr.js';
 import * as uuid from 'uuid';
@@ -122,6 +123,7 @@ import webpush from 'web-push';
 
 export {
   argon2,
+  bson,
   lruCache,
   ipaddr,
   uuid,

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '34.0.0',
+  version: '34.2.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }