219 lines
8.8 KiB
TypeScript
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}.`);
|
|
},
|
|
});
|