Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/cli/src/commands/backup/restore.ts
T

219 lines
8.8 KiB
TypeScript

import { defineCommand } from "citty";
import consola from "consola";
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { spawn, type SpawnOptions } from "node:child_process";
import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
import { tmpdir } from "node:os";
import { isAbsolute, join, relative, resolve, sep } from "node:path";
import { extract as extractTar } from "tar";
import { S3Client } from "@aws-sdk/client-s3";
import { downloadObjectToFile } from "./s3-upload.js";
import { decryptFile } from "./encryption.js";
import { deserializeManifest, type BackupManifest, type ComponentEntry } from "./manifest.js";
import { resolveBackupConfig, type BackupEnv } from "./env.js";
export interface RunRestoreOptions {
/** S3 key (e.g. `backup-2026-...tar.gz.age`) or just a backup id (the CLI prefixes/suffixes). */
snapshot: string;
env?: BackupEnv;
client?: S3Client;
/** Override the target Postgres DSN; defaults to env.DIRECT_URL / DATABASE_URL. */
targetDatabaseUrl?: string;
/** Skip restoring storage objects. */
skipStorage?: boolean;
/** Override pg_restore binary (tests). */
pgRestoreBinary?: string;
/** Spawn override for tests. */
spawnFn?: typeof spawn;
}
export interface RunRestoreResult {
manifest: BackupManifest;
archivePath: string;
}
export async function runRestoreBackup(opts: RunRestoreOptions): Promise<RunRestoreResult> {
const env = opts.env ?? (process.env as unknown as BackupEnv);
const config = resolveBackupConfig(env);
const client = opts.client ?? new S3Client(config.s3);
const tempRoot = await mkdtemp(join(tmpdir(), "backup-restore-"));
try {
const downloadPath = join(tempRoot, "download.bin");
consola.info(`Downloading s3://${config.backupBucket}/${opts.snapshot}`);
await downloadObjectToFile({ client, bucket: config.backupBucket, key: opts.snapshot, destPath: downloadPath });
const decryptedPath = join(tempRoot, "archive.tar.gz");
if (config.encryption.method !== "none") {
consola.info(`Decrypting via ${config.encryption.method}`);
await decryptFile({ config: config.encryption, inputPath: downloadPath, outputPath: decryptedPath });
} else {
await rename(downloadPath, decryptedPath);
}
const extractDir = join(tempRoot, "extracted");
await mkdir(extractDir, { recursive: true });
await extractTar({ file: decryptedPath, cwd: extractDir });
const entries = await readdir(extractDir);
if (entries.length !== 1) {
throw new Error(`Unexpected archive layout; got ${entries.length} top-level entries`);
}
const stageDir = await resolveExtractedStageDirectory(extractDir, entries[0]);
const manifestPath = await resolveContainedRegularFile(stageDir, "manifest.json", "backup manifest");
const manifestRaw = await readFile(manifestPath, "utf8");
const manifest = deserializeManifest(manifestRaw);
const dbUrl = opts.targetDatabaseUrl ?? config.databaseUrl;
if (manifest.components.postgres) {
const dumpPath = await verifyBackupComponent(stageDir, manifest.components.postgres, "Postgres dump");
consola.info("Restoring Postgres dump");
await pgRestore({
connectionString: dbUrl,
dumpPath,
binary: opts.pgRestoreBinary,
spawnFn: opts.spawnFn,
});
}
if (manifest.components.storage && !opts.skipStorage) {
const storagePath = await verifyBackupComponent(stageDir, manifest.components.storage, "storage archive", { verifySize: false });
// Storage restore is operator-driven via re-upload from the staged tar.
// Implementation lives in storage.ts in a follow-up if/when staging
// verifies the create flow against a real bucket. For now we surface
// a clear hint so the operator can manually re-import.
consola.warn(
`Storage tar at ${storagePath} not auto-uploaded; re-upload via aws s3 sync or use --target-bucket in a future revision.`,
);
}
return { manifest, archivePath: decryptedPath };
} finally {
await rm(tempRoot, { recursive: true, force: true });
}
}
async function resolveExtractedStageDirectory(extractDir: string, entry: string): Promise<string> {
const extractRoot = await realpath(extractDir);
const candidate = resolve(extractRoot, entry);
assertContainedPath(extractRoot, candidate, "backup stage directory");
const candidateStat = await lstat(candidate);
if (candidateStat.isSymbolicLink() || !candidateStat.isDirectory()) {
throw new Error("Backup stage entry must be a real directory");
}
const resolvedCandidate = await realpath(candidate);
assertContainedPath(extractRoot, resolvedCandidate, "backup stage directory");
return resolvedCandidate;
}
async function resolveContainedRegularFile(rootDir: string, relativePath: string, label: string): Promise<string> {
const root = await realpath(rootDir);
const candidate = resolve(root, relativePath);
assertContainedPath(root, candidate, label);
const resolvedCandidate = await realpath(candidate);
assertContainedPath(root, resolvedCandidate, label);
const candidateStat = await stat(resolvedCandidate);
if (!candidateStat.isFile()) {
throw new Error(`${label} must be a regular file`);
}
return resolvedCandidate;
}
function assertContainedPath(root: string, candidate: string, label: string): void {
const relativePath = relative(root, candidate);
if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
throw new Error(`${label} escapes the extracted backup directory`);
}
}
export async function verifyBackupComponent(
stageDir: string,
component: ComponentEntry,
label: string,
options: { verifySize?: boolean } = {},
): Promise<string> {
const componentPath = await resolveContainedRegularFile(stageDir, component.path, label);
const componentStat = await stat(componentPath);
if (options.verifySize !== false && componentStat.size !== component.sizeBytes) {
throw new Error(`${label} size mismatch: expected ${component.sizeBytes} bytes, got ${componentStat.size}`);
}
const hash = createHash("sha256");
for await (const chunk of createReadStream(componentPath)) {
hash.update(chunk as Buffer);
}
const actualChecksum = hash.digest("hex");
if (actualChecksum !== component.checksum.value) {
throw new Error(`${label} checksum mismatch`);
}
return componentPath;
}
async function rename(from: string, to: string): Promise<void> {
const fs = await import("node:fs/promises");
await fs.rename(from, to);
}
interface PgRestoreArgs {
connectionString: string;
dumpPath: string;
binary?: string;
spawnFn?: typeof spawn;
/** Optional `--schema` override used by `backup:verify` to isolate the restore. */
schemaOnly?: string;
}
export async function pgRestore(args: PgRestoreArgs): Promise<void> {
const spawner = args.spawnFn ?? spawn;
const binary = args.binary ?? "pg_restore";
const cliArgs = ["--clean", "--if-exists", "--no-owner", "--no-privileges", "--dbname", args.connectionString];
if (args.schemaOnly) {
cliArgs.push("--schema", args.schemaOnly);
}
cliArgs.push(args.dumpPath);
const spawnOptions: SpawnOptions = { stdio: ["ignore", "pipe", "pipe"] };
const child = spawner(binary, cliArgs, spawnOptions);
const stderrChunks: Buffer[] = [];
child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c));
const exitCode: number | null = await new Promise((resolve, reject) => {
child.once("error", reject);
child.once("close", (code: number | null) => resolve(code));
});
if (exitCode !== 0) {
throw new Error(`pg_restore exited with code ${exitCode ?? "<null>"}: ${Buffer.concat(stderrChunks).toString("utf8")}`);
}
}
export const restoreBackupCommand = defineCommand({
meta: {
name: "restore",
description: "Restore Postgres + Storage from a backup archive in S3.",
},
args: {
snapshot: { type: "positional", required: true, description: "S3 key of the backup archive." },
yes: { type: "boolean", description: "Skip confirmation prompt.", default: false },
"skip-storage": { type: "boolean", description: "Do not restore storage objects.", default: false },
"target-db": { type: "string", description: "Override Postgres DSN for the restore." },
},
async run({ args }) {
if (!args.yes) {
const confirmed = await consola.prompt(
`This will overwrite the target Postgres database with backup ${args.snapshot}. Continue?`,
{ type: "confirm" },
);
if (!confirmed) {
consola.warn("Restore cancelled.");
return;
}
}
const result = await runRestoreBackup({
snapshot: String(args.snapshot),
skipStorage: Boolean(args["skip-storage"]),
targetDatabaseUrl: args["target-db"] ? String(args["target-db"]) : undefined,
});
consola.success(`Restored ${result.manifest.backupId}.`);
},
});