/** * `tenant:restore` — read a snapshot tarball (local or S3), decrypt if needed, * extract the manifest + per-model JSONL, replay rows into the target Prisma * with the new tenant id, then upload tenant storage objects under the new * `tenants//` prefix. * * The Prisma layer is dependency-injected via the `PrismaRestoreRunner` * interface so the CLI package stays free of `@prisma/client`. Production * callers wire up a real client in `bin/hivegrid-cli.mjs`; tests pass a fake. * * Foreign-key remapping: direct tenant rows receive the target `tenantId`; * FK-derived children keep their original foreign keys because parent primary * keys are preserved. The snapshot is intended to land in a separate * environment, so id collisions with other tenants in that target are not * handled here. */ import { defineCommand } from "citty"; import consola from "consola"; import { createReadStream, createWriteStream } from "node:fs"; import { mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { createInterface } from "node:readline"; import { Readable } from "node:stream"; import { extract as extractTar } from "tar"; import { GetObjectCommand, ListObjectsV2Command, S3Client, type S3ClientConfig, } from "@aws-sdk/client-s3"; import { Upload } from "@aws-sdk/lib-storage"; import { deserializeTenantManifest, type TenantSnapshotManifest, } from "./manifest.js"; import { isTenantDerivedModel } from "./derived-models.js"; import { decryptFile, type EncryptionConfig } from "../backup/encryption.js"; export interface PrismaRestoreRunner { /** * Bulk-create rows into `modelName`, returning the number of rows actually * persisted (after skipping duplicates the caller chose to ignore). */ createMany(modelName: string, rows: Record[]): Promise<{ written: number }>; /** * Upsert rows into `modelName` keyed by `id`. Returns counts split by * whether each row was created fresh or matched an existing row. * Optional so legacy fake runners only used for the tenant-only path * keep working — when missing, the restore falls back to createMany * with skipDuplicates for the globals slice (same semantics as * `--globals=skip`). */ upsertManyById?( modelName: string, rows: Record[], ): Promise<{ created: number; updated: number }>; } /** * How to handle global rows (User, etc.) during restore. * * - `upsert` (default): `prisma..upsert({ where:{id}, ... })` per * row. Existing globals on the target are left in place; new globals * get inserted. Best for typical "merge into existing dev/staging DB" * scenarios. * - `skip`: `createMany({ skipDuplicates: true })`. Same effect as * upsert when only inserting; differs in that conflicting unique * columns OTHER than `id` (e.g. `email`) silently drop the new row. * - `error`: refuse to restore if any global id already exists on * target. Useful for "sensitive restore into a known-empty DB" * where overlap means the target wasn't actually empty. */ export type GlobalsRestoreMode = "upsert" | "skip" | "error"; export function isGlobalsRestoreMode(value: string): value is GlobalsRestoreMode { return value === "upsert" || value === "skip" || value === "error"; } export interface RunRestoreOptions { /** Target tenant id the snapshot should land under. */ readonly tenantId: string; /** Either an s3://bucket/key URL or a local filesystem path. */ readonly source: string; readonly prisma: PrismaRestoreRunner; readonly s3?: S3ClientConfig; readonly s3Client?: S3Client; readonly storageBucket?: string; readonly encryption?: EncryptionConfig; /** When true, skip the interactive confirmation prompt. */ readonly yes?: boolean; /** Stream used to ask for confirmation; defaults to process.stdin. */ readonly stdin?: NodeJS.ReadableStream; /** Stream used to print the confirmation question; defaults to process.stdout. */ readonly stdout?: NodeJS.WritableStream; readonly logger?: { info: (m: string) => void; warn: (m: string) => void }; /** Refuse to run when NODE_ENV=production unless explicitly allowed. */ readonly allowProductionRestore?: boolean; /** * Strategy for the globals slice. Defaults to `upsert`. See the * `GlobalsRestoreMode` docblock for the three modes. */ readonly globalsMode?: GlobalsRestoreMode; } export interface RunRestoreResult { readonly manifest: TenantSnapshotManifest; readonly perModel: ReadonlyArray<{ model: string; written: number; expected: number }>; /** * Per-global summary: how many rows the manifest carried, how many * were inserted fresh, and how many already existed on target (under * `upsert` they were left in place; under `skip` they were dropped; * under `error` the restore aborts before this is populated). */ readonly globals: ReadonlyArray<{ model: string; expected: number; created: number; existed: number }>; readonly storageObjectsUploaded: number; } export async function runTenantRestore(opts: RunRestoreOptions): Promise { const logger = opts.logger ?? consola.create({ defaults: { tag: "tenant:restore" } }); if (process.env.NODE_ENV === "production" && !opts.allowProductionRestore) { throw new Error( "Refusing to run tenant:restore in NODE_ENV=production without allowProductionRestore=true (pass --allow-production-restore).", ); } const workRoot = await mkdtemp(join(tmpdir(), "tenant-restore-")); try { // 1. Download (if S3) into the work dir; decrypt if needed; untar. const downloadedPath = await materializeSource(opts, workRoot, logger); let archivePath = downloadedPath; if (opts.encryption && opts.encryption.method !== "none") { const decryptedPath = join(workRoot, "decrypted.tar.gz"); logger.info(`Decrypting via ${opts.encryption.method}`); await decryptFile({ config: opts.encryption, inputPath: archivePath, outputPath: decryptedPath }); archivePath = decryptedPath; } const extractDir = join(workRoot, "extracted"); await mkdir(extractDir, { recursive: true }); await extractTar({ file: archivePath, cwd: extractDir }); // 2. Locate the (single) top-level snapshot directory and read the manifest. const { readdir } = await import("node:fs/promises"); const tops = await readdir(extractDir); const snapshotDir = tops.find((d) => d.startsWith("tenant-snapshot-")); if (!snapshotDir) { throw new Error(`No tenant-snapshot-* directory found inside ${archivePath}`); } const stageDir = join(extractDir, snapshotDir); const manifestRaw = await readFile(join(stageDir, "manifest.json"), "utf8"); const manifest = deserializeTenantManifest(manifestRaw); logger.info( `Manifest: source=${manifest.sourceTenantId} profile=${manifest.anonymization.profile} models=${manifest.models.length}`, ); // 3. Confirmation prompt unless --yes. if (!opts.yes) { const answered = await promptYesNo( `About to restore snapshot of tenant ${manifest.sourceTenantId} into ${opts.tenantId}. Continue?`, opts.stdin ?? process.stdin, opts.stdout ?? process.stdout, ); if (!answered) { throw new Error("Aborted by operator."); } } // 4a. Replay globals FIRST (in FK-correct order) so the tenant-scoped // models that follow can resolve their FK columns (User, etc.). // Manifests created before this extractor landed carry no `globals` // array — we tolerate that and warn so the operator knows they still // need pre-seeded globals on the target DB. const mode: GlobalsRestoreMode = opts.globalsMode ?? "upsert"; const globalsSummary: { model: string; expected: number; created: number; existed: number }[] = []; if (manifest.globals && manifest.globals.length > 0) { logger.info(`Replaying ${manifest.globals.length} globals slice(s) with mode=${mode}.`); for (const entry of manifest.globals) { const filePath = join(stageDir, entry.path); const rows = await readJsonl(filePath); // Globals are NOT remapped onto a new tenantId — they live in // global space. Pass rows through verbatim. const summary = await replayGlobalsForModel({ modelName: entry.model, rows, mode, prisma: opts.prisma, logger, }); globalsSummary.push({ model: entry.model, expected: entry.rowCount, created: summary.created, existed: summary.existed, }); } } else { logger.warn( "Manifest carries no globals slice (legacy snapshot). Tenant-scoped models with FKs into global rows will fail unless those rows already exist on the target DB.", ); } // 4b. Replay each tenant-scoped model with the new tenantId. const perModel: { model: string; written: number; expected: number }[] = []; for (const entry of manifest.models) { const filePath = join(stageDir, entry.path); const rows = await readJsonl(filePath); const remapped = isTenantDerivedModel(entry.model) ? rows : rows.map((row) => ({ ...row, tenantId: opts.tenantId })); const result = await opts.prisma.createMany(entry.model, remapped); perModel.push({ model: entry.model, written: result.written, expected: entry.rowCount }); if (result.written !== entry.rowCount) { logger.warn(`Model ${entry.model}: wrote ${result.written} rows but manifest expected ${entry.rowCount}.`); } } // 5. Re-upload storage objects to the new tenant prefix. let storageObjectsUploaded = 0; if (manifest.storage && opts.storageBucket) { storageObjectsUploaded = await restoreStorage({ stageDir, storageEntry: manifest.storage, targetBucket: opts.storageBucket, targetPrefix: `tenants/${opts.tenantId}/`, sourcePrefix: `tenants/${manifest.sourceTenantId}/`, client: ensureS3Client(opts), }); } // 6. Sanity check: per-model row counts must match within tolerance. const mismatched = perModel.filter((m) => m.written !== m.expected); if (mismatched.length > 0) { logger.warn(`Row-count mismatch in ${mismatched.length} models. See restore log for details.`); } return { manifest, perModel, globals: globalsSummary, storageObjectsUploaded }; } finally { await rm(workRoot, { recursive: true, force: true }); } } interface ReplayGlobalsForModelOptions { readonly modelName: string; readonly rows: Record[]; readonly mode: GlobalsRestoreMode; readonly prisma: PrismaRestoreRunner; readonly logger: { info: (m: string) => void; warn: (m: string) => void }; } /** * Insert/upsert globals according to the chosen mode. * * Strategy * -------- * The PrismaRestoreRunner interface treats `upsertManyById` as * optional. When the production wiring provides it (real PrismaClient, * see `prisma-runner.ts`), `upsert` and `error` modes use it. Test * fakes that only implement `createMany` fall through to a * `createMany({skipDuplicates:true})` shim and emit a warning telling * the operator the mode they asked for could not be honored. * * `error` mode pre-checks for any pre-existing id by performing an * upsert that throws on update (the runner's upsertManyById returns * `updated > 0` when a row already existed; we treat that as a fail). */ async function replayGlobalsForModel( opts: ReplayGlobalsForModelOptions, ): Promise<{ created: number; existed: number }> { if (opts.rows.length === 0) { return { created: 0, existed: 0 }; } const supportsUpsert = typeof opts.prisma.upsertManyById === "function"; if (opts.mode === "skip" || !supportsUpsert) { if (opts.mode !== "skip" && !supportsUpsert) { opts.logger.warn( `Globals restore mode=${opts.mode} requested but runner does not implement upsertManyById; falling back to skip-duplicates semantics.`, ); } const result = await opts.prisma.createMany(opts.modelName, opts.rows); return { created: result.written, existed: opts.rows.length - result.written }; } const result = await opts.prisma.upsertManyById!(opts.modelName, opts.rows); if (opts.mode === "error" && result.updated > 0) { throw new Error( `tenant:restore aborted (--globals=error): ${opts.modelName} had ${result.updated} pre-existing row(s) on the target. Pass --globals=upsert to overlay snapshot rows over existing ones, or --globals=skip to leave them in place.`, ); } return { created: result.created, existed: result.updated }; } async function materializeSource( opts: RunRestoreOptions, workRoot: string, logger: { info: (m: string) => void; warn: (m: string) => void }, ): Promise { if (opts.source.startsWith("s3://")) { const rest = opts.source.slice("s3://".length); const slash = rest.indexOf("/"); if (slash <= 0) throw new Error(`Invalid --source: ${opts.source}`); const bucket = rest.slice(0, slash); const key = rest.slice(slash + 1); const dest = join(workRoot, "snapshot.tar.gz"); logger.info(`Downloading s3://${bucket}/${key}`); const client = ensureS3Client(opts); const resp = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key })); await streamToFile(asReadable(resp.Body), dest); return dest; } return opts.source; } async function readJsonl(path: string): Promise[]> { try { await stat(path); } catch { return []; } const rows: Record[] = []; const stream = createReadStream(path, { encoding: "utf8" }); const rl = createInterface({ input: stream, crlfDelay: Infinity }); for await (const line of rl) { if (line.trim().length === 0) continue; rows.push(JSON.parse(line) as Record); } return rows; } interface RestoreStorageOptions { stageDir: string; storageEntry: NonNullable; targetBucket: string; targetPrefix: string; sourcePrefix: string; client: S3Client; } async function restoreStorage(opts: RestoreStorageOptions): Promise { const storageDir = join(opts.stageDir, "storage"); const manifestLines = (await readFile(join(storageDir, "manifest.jsonl"), "utf8")).split("\n").filter((l) => l.length > 0); if (manifestLines.length === 0) return 0; const archive = join(storageDir, "objects.tar"); const stagingDir = join(opts.stageDir, "_storage_staging"); await mkdir(stagingDir, { recursive: true }); await extractTar({ file: archive, cwd: stagingDir }); let uploaded = 0; for (const line of manifestLines) { const entry = JSON.parse(line) as { key: string; relPath: string }; const localPath = join(stagingDir, entry.relPath); const newKey = entry.key.startsWith(opts.sourcePrefix) ? `${opts.targetPrefix}${entry.key.slice(opts.sourcePrefix.length)}` : `${opts.targetPrefix}${entry.relPath}`; const stream = createReadStream(localPath); const upload = new Upload({ client: opts.client, params: { Bucket: opts.targetBucket, Key: newKey, Body: stream }, }); await upload.done(); uploaded += 1; } return uploaded; } function promptYesNo( question: string, stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, ): Promise { return new Promise((resolve) => { const rl = createInterface({ input: stdin, output: stdout }); rl.question(`${question} [y/N] `, (answer) => { rl.close(); resolve(/^y(es)?$/iu.test(answer.trim())); }); }); } function ensureS3Client(opts: RunRestoreOptions): S3Client { if (opts.s3Client) return opts.s3Client; if (!opts.s3) throw new Error("S3 client or config is required"); return new S3Client(opts.s3); } function asReadable(body: unknown): Readable { if (body && typeof (body as Readable).pipe === "function") { return body as Readable; } if (body && typeof (body as { transformToWebStream?: () => unknown }).transformToWebStream === "function") { const webStream = (body as { transformToWebStream: () => ReadableStream }).transformToWebStream(); return Readable.fromWeb(webStream as never); } if (body && Symbol.asyncIterator in (body as object)) { return Readable.from(body as AsyncIterable); } throw new Error("Unsupported S3 GetObject body type"); } async function streamToFile(stream: Readable, path: string): Promise { const sink = createWriteStream(path); await new Promise((resolve, reject) => { stream.pipe(sink); sink.on("finish", () => resolve()); sink.on("error", reject); stream.on("error", reject); }); } // Suppress the unused-import lint for ListObjectsV2Command; it remains in the // import list so a future iteration that wants to discover unknown keys in // the bucket can pick it up without re-importing. void ListObjectsV2Command; export const tenantRestoreCommand = defineCommand({ meta: { name: "restore", description: "Restore a tenant snapshot into a new tenant id (FK-remapped).", }, args: { "tenant-id": { type: "string", required: true, description: "Target tenant id to create." }, source: { type: "string", required: true, description: "s3://bucket/key or local path of the snapshot." }, yes: { type: "boolean", default: false, description: "Skip confirmation prompts." }, "allow-production-restore": { type: "boolean", default: false, description: "Permit restore when NODE_ENV=production (DANGEROUS).", }, globals: { type: "string", default: "upsert", description: "How to handle global rows (User, etc.) on the target: upsert (default, idempotent overlay) | skip (leave conflicting rows in place) | error (abort if any global already exists — for sensitive restores into a known-empty DB).", }, }, async run({ args }) { const { resolveTenantSnapshotConfig } = await import("./env.js"); const cfg = resolveTenantSnapshotConfig(process.env as Record); const { getDbClient } = await import("@hivegrid/db/client.server"); const { createPrismaRestoreRunner } = await import("./prisma-runner.js"); const { parseSchemaScalarTypes } = await import("./json-codec.js"); const { dirname, join } = await import("node:path"); const { fileURLToPath } = await import("node:url"); const here = dirname(fileURLToPath(import.meta.url)); // From packages/cli/src/commands/tenant/restore.ts → repo root is 5 levels up. const schemaDir = join(here, "..", "..", "..", "..", "..", "prisma", "schema"); const scalarTypes = parseSchemaScalarTypes(schemaDir); const prisma = getDbClient(); const runner = createPrismaRestoreRunner(prisma as unknown as Record, scalarTypes); const globalsRaw = args.globals === undefined ? "upsert" : String(args.globals); if (!isGlobalsRestoreMode(globalsRaw)) { throw new Error(`Invalid --globals: ${globalsRaw}; expected upsert | skip | error.`); } const result = await runTenantRestore({ tenantId: String(args["tenant-id"]), source: String(args.source), prisma: runner, s3: cfg.s3, storageBucket: cfg.appStorageBucket ?? undefined, encryption: cfg.encryption.method === "none" ? undefined : cfg.encryption, yes: Boolean(args.yes), allowProductionRestore: Boolean(args["allow-production-restore"]), globalsMode: globalsRaw, }); const totalWritten = result.perModel.reduce((n, m) => n + m.written, 0); const totalExpected = result.perModel.reduce((n, m) => n + m.expected, 0); const mismatches = result.perModel.filter((m) => m.written !== m.expected); consola.success( `Restored snapshot of tenant ${result.manifest.sourceTenantId} → ${String(args["tenant-id"])}: ${totalWritten}/${totalExpected} rows across ${result.perModel.length} models.`, ); if (result.globals.length > 0) { const summary = result.globals .map((g) => `${g.model}(created=${g.created} existed=${g.existed} expected=${g.expected})`) .join(", "); consola.info(`Globals (mode=${globalsRaw}): ${summary}.`); } if (result.storageObjectsUploaded > 0) { consola.info(`Storage objects re-uploaded: ${result.storageObjectsUploaded}.`); } if (mismatches.length > 0) { consola.warn( `Row-count mismatch in ${mismatches.length} models: ${mismatches.map((m) => `${m.model}(${m.written}/${m.expected})`).join(", ")}`, ); } }, });