@serve.zone/dcrouter 34.1.0 → 34.2.0

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '34.1.0',
+    version: '34.2.0',
     description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfd2ViLzAwX2NvbW1pdGluZm9fZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRztJQUN4QixJQUFJLEVBQUUsc0JBQXNCO0lBQzVCLE9BQU8sRUFBRSxRQUFRO0lBQ2pCLFdBQVcsRUFBRSwwRUFBMEU7Q0FDeEYsQ0FBQSJ9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "34.1.0",
+  "version": "34.2.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "@git.zone/tsrepo": "^1.1.1",
     "@push.rocks/smartdb-v2": "npm:@push.rocks/smartdb@2.14.6",
     "@push.rocks/smartdb-v5.2": "npm:@push.rocks/smartdb@5.2.2",
+    "@serve.zone/dcrouter-v33": "npm:@serve.zone/dcrouter@33.0.0",
     "@types/dns-packet": "^5.6.5",
     "@types/node": "26.6.5",
     "@types/web-push": "3.6.4",
@@ -50,7 +51,7 @@
     "@push.rocks/smartlog": "^3.2.2",
     "@push.rocks/smartmcp": "^0.3.0",
     "@push.rocks/smartmetrics": "^3.0.3",
-    "@push.rocks/smartmigration": "2.0.1",
+    "@push.rocks/smartmigration": "2.1.0",
     "@push.rocks/smartmta": "^13.0.1",
     "@push.rocks/smartnetwork": "^4.10.1",
     "@push.rocks/smartpath": "^6.0.0",
@@ -70,6 +71,7 @@
     "@tsclass/tsclass": "^9.5.1",
     "@types/qrcode": "^1.5.6",
     "argon2": "^0.45.1",
+    "bson": "7.3.2",
     "ipaddr.js": "^2.5.0",
     "lru-cache": "^11.5.2",
     "qrcode": "^1.5.4",

package/readme.md

@@ -63,6 +63,31 @@ Use the package as a TypeScript library:
 pnpm add @serve.zone/dcrouter
 ```
 
+## CLI
+
+```bash
+dcrouter                 # start the router (DCROUTER_MODE=OCI_CONTAINER for the container configuration)
+dcrouter --version
+dcrouter --help
+dcrouter migrate --storage-path <absolute root> --to <version> [--db-name dcrouter] [--plan]
+```
+
+`dcrouter` starts the router only without arguments; from 34.2.0 on it refuses any argument it does not know (exit code 2) and starts nothing. Releases up to 34.1.0 started the router on an unknown argument, so check `dcrouter --version` before running a command a later release added.
+
+`dcrouter migrate` walks the data of a **stopped** dcrouter back to an earlier data version through the migration steps' down handlers; forward migrations happen when dcrouter starts. The supported downgrade is data version `34.0.0` → `32.6.0`, the data dcrouter 33.0.0 reads, which returns the route DNS ownership the `release-annexed-gateway-route-dns-records` step released:
+
+```bash
+# the embedded database's default root is ~/.serve.zone/dcrouter/tsmdb (dbConfig.storagePath overrides it)
+dcrouter migrate --storage-path /root/.serve.zone/dcrouter/tsmdb --to 32.6.0 --plan   # report only
+dcrouter migrate --storage-path /root/.serve.zone/dcrouter/tsmdb --to 32.6.0
+```
+
+- `--storage-path` (required, absolute, no default) is the embedded database's storage root; `--db-name` is the database inside it (default `dcrouter`). The root is checked offline first and the engine's owner lock is taken, so a root a running dcrouter owns is refused.
+- `--to` must be a step boundary behind the ledger. A forward target, a ledger a newer dcrouter wrote and a database without a ledger are refused; a target equal to the ledger is a no-op.
+- A database that dcrouter 34.0.0 or 34.1.0 upgraded is refused: those releases did not record the ownership they released, so restore the export taken before that upgrade instead. Upgrade a 33.0.0 database straight to 34.2.0 or later to keep the way back.
+- Records written after the upgrade are kept: a record deleted since is not recreated, an edited one gets its ownership back, and any record whose ownership conflicts with the recorded one refuses the whole downgrade with nothing changed.
+- The last output line is `DCROUTER_MIGRATE_RESULT:{json}` (`ok`, the versions and the steps, or the error); the exit code is 0, 1 on a refusal or failure, and 2 on a command line it does not accept.
+
 ## Quick Start
 
 This starts the gateway on unprivileged ports and stores data under the default `~/.serve.zone/dcrouter` base directory.

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -7,6 +7,7 @@ export type { IUnifiedEmailServerOptions, IEmailRoute, IEmailDomainConfig } from
 
 // DcRouter
 import { DcRouter } from './classes.dcrouter.js';
+import { runMigrateCommand } from './migrate-command.js';
 export * from './classes.dcrouter.js';
 
 // RADIUS module
@@ -21,27 +22,44 @@ export * from './webpush/index.js';
 // HTTP/3 module
 export type { IHttp3Config } from './http3/index.js';
 
+const cliUsage = `Usage:
+  dcrouter
+  dcrouter --version
+  dcrouter --help
+  dcrouter migrate --storage-path <absolute path> --to <version> [--db-name <name>] [--plan]
+
+Environment:
+  DCROUTER_MODE=OCI_CONTAINER   Start with OCI container configuration
+  DCROUTER_DNS_BIND_INTERFACE   Override the embedded DNS UDP bind address
+  DATA_DIR=<path>               Override the writable dcrouter data directory
+`;
+
 export const runCli = async () => {
   const args = process.argv.slice(2);
 
+  if (args[0] === 'migrate') {
+    process.exitCode = await runMigrateCommand(args.slice(1));
+    return;
+  }
+
   if (args.includes('--version') || args.includes('version')) {
     console.log(commitinfo.version);
     return;
   }
 
   if (args.includes('--help') || args.includes('-h') || args.includes('help')) {
-    console.log(`dcrouter ${commitinfo.version}
-
-Usage:
-  dcrouter
-  dcrouter --version
-  dcrouter --help
+    console.log(`dcrouter ${commitinfo.version}\n\n${cliUsage}`);
+    return;
+  }
 
-Environment:
-  DCROUTER_MODE=OCI_CONTAINER   Start with OCI container configuration
-  DCROUTER_DNS_BIND_INTERFACE   Override the embedded DNS UDP bind address
-  DATA_DIR=<path>               Override the writable dcrouter data directory
-`);
+  // Only a bare `dcrouter` starts the router: an argument this release does not know (a command
+  // a later release added, a typo) must never start it against the data it was meant for.
+  if (args.length > 0) {
+    console.error(
+      `dcrouter: unknown argument${args.length > 1 ? 's' : ''} ${args.map((argArg) => `"${argArg}"`).join(' ')}; `
+      + `nothing was started.\n\n${cliUsage}`,
+    );
+    process.exitCode = 2;
     return;
   }
 

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.1.0',
+  version: '34.2.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }