Skip to content

World's first open-source enterprise world model.

40.1 KB
Raw Blame
//! `utopia` — operator-facing command-line entry point.
//!
//! See `.roadmap-proposals/backup-restore.md` for the design rationale.
//! This is the draft PR (branch `feat/backup-restore`): `backup` is
//! implemented, `restore` is stubbed.

use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

use chrono::Utc;
use serde::{Deserialize, Serialize};
use tracing_subscriber::EnvFilter;
use utopia_core::config::AppConfig;

#[derive(Debug)]
enum Command2 {
    Backup(BackupArgs),
    Restore(RestoreArgs),
}

#[derive(Debug, Default)]
struct BackupArgs {
    output: Option<PathBuf>,
    include_data_dir: bool,
    /// Put `secret.key` in the archive too. Off by default: the dump carries
    /// credentials sealed with that key, and an archive is the one artifact that
    /// is copied between hosts and handed to whoever runs the restore. Both
    /// halves in one file is not an encrypted archive, it is no sealing at all.
    include_secret_key: bool,
    dry_run: bool,
    pg_dump: Option<PathBuf>,
    tar: Option<PathBuf>,
    migration_url: Option<String>,
}

#[derive(Debug, Default)]
struct RestoreArgs {
    from: Option<PathBuf>,
    target_data_dir: Option<PathBuf>,
    pg_restore: Option<PathBuf>,
    dry_run: bool,
    force: bool,
    yes: bool,
}

#[derive(Debug, Serialize, Deserialize)]
struct Manifest {
    schema_version: u32,
    utopia_version: String,
    created_at: String,
    components: ManifestComponents,
    checksums: HashMap<String, String>,
}

#[derive(Debug, Serialize, Deserialize)]
struct ManifestComponents {
    pg_dump: ManifestComponent,
    data_dir: ManifestDataDir,
}

#[derive(Debug, Serialize, Deserialize)]
struct ManifestComponent {
    path: String,
    format: String,
    bytes: u64,
}

#[derive(Debug, Serialize, Deserialize)]
struct ManifestDataDir {
    path: String,
    present: bool,
    /// Whether the sealing key is inside this archive, so that an archive can be
    /// audited without being unpacked and restore can say what it will install.
    #[serde(default)]
    secret_key: bool,
}

/// Manifest version the running binary writes. Restore refuses a manifest
/// whose `schema_version` is greater than this (forward-incompatible) and
/// warns when older. Kept as a constant — bumping is a deliberate decision,
/// not a side effect of a code change.
// 是迁移文件的**个数**,不是最大的编号(守卫 `schema_version_policy_compares_against_current`
// 按个数比):编号有空缺时两者不同——0071 由一个开放 PR 占着,0072 先落,个数是 71
const CURRENT_SCHEMA_VERSION: u32 = 104;

fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    tracing_subscriber::fmt()
        .with_env_filter(
            EnvFilter::try_from_default_env().unwrap_or_else(|_| "info,utopia=debug".into()),
        )
        .init();

    let args: Vec<String> = std::env::args().skip(1).collect();
    let cmd = parse(&args)?;
    match cmd {
        Command2::Backup(a) => run_backup(a),
        Command2::Restore(a) => run_restore(a),
    }
}

fn parse(args: &[String]) -> anyhow::Result<Command2> {
    let mut iter = args.iter();
    let sub = iter.next().ok_or_else(|| {
        anyhow::anyhow!(
            "usage: utopia <backup|restore> [flags]\nRun `utopia <subcommand> --help` for details."
        )
    })?;
    match sub.as_str() {
        "backup" => Ok(Command2::Backup(parse_backup(&mut iter)?)),
        "restore" => Ok(Command2::Restore(parse_restore(&mut iter)?)),
        "--help" | "-h" | "help" => {
            print_help();
            std::process::exit(0);
        }
        other => anyhow::bail!("unknown subcommand `{other}` (expected `backup` or `restore`)"),
    }
}

fn print_help() {
    eprintln!(
        "utopia — operator commands\n\
         \n\
         USAGE:\n  \
             utopia <backup|restore> [flags]\n\
         \n\
         SUBCOMMANDS:\n  \
             backup   Snapshot the Postgres database (and optionally the data dir) into a tarball.\n  \
             restore  Restore from a tarball produced by `utopia backup`. (TODO: stubbed in this PR.)\n"
    );
}

fn option_value<'a, I: Iterator<Item = &'a String>>(
    flag: &str,
    iter: &mut I,
) -> anyhow::Result<&'a String> {
    match iter.next() {
        Some(value) if !value.is_empty() && !value.starts_with('-') => Ok(value),
        _ => anyhow::bail!("{flag} requires a value"),
    }
}

fn parse_backup<'a, I: Iterator<Item = &'a String>>(iter: &mut I) -> anyhow::Result<BackupArgs> {
    let mut a = BackupArgs::default();
    while let Some(flag) = iter.next() {
        match flag.as_str() {
            "--output" => a.output = Some(PathBuf::from(option_value(flag, iter)?)),
            "--include-data-dir" => a.include_data_dir = true,
            "--include-secret-key" => a.include_secret_key = true,
            "--dry-run" => a.dry_run = true,
            "--pg-dump" => a.pg_dump = Some(PathBuf::from(option_value(flag, iter)?)),
            "--tar" => a.tar = Some(PathBuf::from(option_value(flag, iter)?)),
            "--migration-url" => a.migration_url = Some(option_value(flag, iter)?.clone()),
            "--help" | "-h" => {
                eprintln!(
                    "utopia backup — snapshot the database (and optionally the data dir)\n\
                     \n\
                     FLAGS:\n      \
                         --output <path>            Final tarball path (default: ./utopia-backup-<utc>.tar.gz).\n      \
                         --include-data-dir         Add UTOPIA_DATA_DIR (files/ + index/) to the tarball.\n      \
                         --dry-run                  Plan only; print every step, write nothing.\n      \
                         --pg-dump <path>           Override the pg_dump binary (default: PATH lookup).\n      \
                         --tar <path>               Override the tar binary (default: PATH lookup).\n      \
                         --migration-url <url>      Connect as the migration role for the dump.\n"
                );
                std::process::exit(0);
            }
            other => anyhow::bail!("unknown flag `{other}` for `utopia backup`"),
        }
    }
    Ok(a)
}

fn parse_restore<'a, I: Iterator<Item = &'a String>>(iter: &mut I) -> anyhow::Result<RestoreArgs> {
    let mut a = RestoreArgs::default();
    while let Some(flag) = iter.next() {
        match flag.as_str() {
            "--from" => a.from = Some(PathBuf::from(option_value(flag, iter)?)),
            "--target-data-dir" => {
                a.target_data_dir = Some(PathBuf::from(option_value(flag, iter)?))
            }
            "--pg-restore" => a.pg_restore = Some(PathBuf::from(option_value(flag, iter)?)),
            "--dry-run" => a.dry_run = true,
            "--force" => a.force = true,
            "--yes" => a.yes = true,
            "--help" | "-h" => {
                eprintln!(
                    "utopia restore — restore from a backup tarball\n\
                     \n\
                     FLAGS:\n      \
                         --from <path>              Path to a tarball produced by `utopia backup`.\n      \
                         --target-data-dir <path>   Where to place the restored data dir.\n      \
                         --pg-restore <path>        Override the pg_restore binary.\n      \
                         --dry-run                  Plan only.\n      \
                         --force                    Required if target database is non-empty.\n      \
                         --yes                      Skip the confirmation prompt.\n"
                );
                std::process::exit(0);
            }
            other => anyhow::bail!("unknown flag `{other}` for `utopia restore`"),
        }
    }
    if a.from.is_none() {
        anyhow::bail!("`utopia restore` requires --from <path>");
    }
    Ok(a)
}

// ---------------------------------------------------------------------------
// backup
// ---------------------------------------------------------------------------

fn run_backup(args: BackupArgs) -> anyhow::Result<()> {
    let cfg = AppConfig::load()?;
    let pg_dump_bin = args
        .pg_dump
        .clone()
        .unwrap_or_else(|| PathBuf::from("pg_dump"));
    let tar_bin = args.tar.clone().unwrap_or_else(|| PathBuf::from("tar"));

    let conn = args
        .migration_url
        .clone()
        .unwrap_or_else(|| cfg.migration_url().to_string());

    let data_dir = PathBuf::from(&cfg.data_dir);
    let stamp = Utc::now().format("%Y-%m-%dT%H-%M-%SZ").to_string();
    let output = args
        .output
        .clone()
        .unwrap_or_else(|| PathBuf::from(format!("utopia-backup-{stamp}.tar.gz")));

    // Plan: what we'd do, in order, with the actual resolved values.
    let plan = format!(
        "[dry-run] pg_dump binary:       {}\n[dry-run] tar binary:           {}\n[dry-run] database host:        {}\n[dry-run] data dir:             {}\n[dry-run] output tarball:       {}\n[dry-run] include data dir:     {}\n",
        pg_dump_bin.display(),
        tar_bin.display(),
        redact_url_host(&conn),
        data_dir.display(),
        output.display(),
        args.include_data_dir,
    );

    if args.dry_run {
        print!("{plan}");
        // Resolve the preconditions anyway so a bad plan returns non-zero.
        preflight_backup(
            &pg_dump_bin,
            &tar_bin,
            &output,
            &data_dir,
            args.include_data_dir,
        )?;
        eprintln!("[dry-run] plan resolved cleanly; no files written.");
        return Ok(());
    }

    preflight_backup(
        &pg_dump_bin,
        &tar_bin,
        &output,
        &data_dir,
        args.include_data_dir,
    )?;

    // Stage: dump Postgres to a temp file we control.
    let stage = tempdir_in(std::env::current_dir()?.as_path())?;
    let pg_dump_path = stage.join("pg_dump.custom");
    tracing::info!(path = %pg_dump_path.display(), "running pg_dump -Fc");
    run_pg_dump(&pg_dump_bin, &conn, &pg_dump_path)?;

    // Build tarball.
    tracing::info!(path = %output.display(), "writing tarball");
    build_tarball(
        &tar_bin,
        &output,
        &pg_dump_path,
        &data_dir,
        args.include_data_dir,
        args.include_secret_key,
        &conn,
    )?;

    let _ = std::fs::remove_dir_all(&stage);
    tracing::info!(path = %output.display(), "backup complete");
    Ok(())
}

fn preflight_backup(
    pg_dump_bin: &Path,
    tar_bin: &Path,
    output: &Path,
    data_dir: &Path,
    include_data_dir: bool,
) -> anyhow::Result<()> {
    if !binary_works(pg_dump_bin) {
        anyhow::bail!(
            "pg_dump not found or not executable: {}. Install postgresql-client or pass --pg-dump <path>.",
            pg_dump_bin.display()
        );
    }
    if !binary_works(tar_bin) {
        anyhow::bail!(
            "tar not found or not executable: {}. Pass --tar <path>.",
            tar_bin.display()
        );
    }
    if output.exists() {
        anyhow::bail!(
            "refusing to overwrite existing output: {}. Move it aside or pick --output <new path>.",
            output.display()
        );
    }
    if include_data_dir && !data_dir.exists() {
        anyhow::bail!(
            "--include-data-dir was set but UTOPIA_DATA_DIR does not exist: {}",
            data_dir.display()
        );
    }
    Ok(())
}

fn binary_works(bin: &Path) -> bool {
    Command::new(bin)
        .arg("--version")
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status()
        .map(|s| s.success())
        .unwrap_or(false)
}

fn run_pg_dump(bin: &Path, conn: &str, out: &Path) -> anyhow::Result<()> {
    let status = Command::new(bin)
        .arg("-Fc")
        .arg("--dbname")
        .arg(conn)
        .arg("--file")
        .arg(out)
        .stdin(Stdio::null())
        .status()?;
    if !status.success() {
        anyhow::bail!(
            "pg_dump exited with status {}; check credentials and that the database is reachable",
            status
        );
    }
    Ok(())
}

#[allow(clippy::too_many_arguments)]
fn build_tarball(
    tar_bin: &Path,
    output: &Path,
    pg_dump_path: &Path,
    data_dir: &Path,
    include_data_dir: bool,
    include_secret_key: bool,
    conn: &str,
) -> anyhow::Result<()> {
    // Write manifest.json next to the dump inside a staging dir, then tar
    // the staging dir into the final tarball.
    let stage = output
        .parent()
        .map(Path::to_path_buf)
        .unwrap_or_else(|| PathBuf::from("."))
        .join(format!(
            ".utopia-backup-stage-{}",
            Utc::now().timestamp_millis()
        ));
    std::fs::create_dir_all(&stage)?;
    let manifest_path = stage.join("manifest.json");
    let manifest = Manifest {
        schema_version: CURRENT_SCHEMA_VERSION,
        utopia_version: env!("CARGO_PKG_VERSION").to_string(),
        created_at: Utc::now().to_rfc3339(),
        components: ManifestComponents {
            pg_dump: ManifestComponent {
                path: "pg_dump.custom".to_string(),
                format: "pg_dump -Fc".to_string(),
                bytes: std::fs::metadata(pg_dump_path)
                    .map(|m| m.len())
                    .unwrap_or(0),
            },
            data_dir: ManifestDataDir {
                path: "data".to_string(),
                present: include_data_dir,
                secret_key: include_secret_key,
            },
        },
        checksums: HashMap::from([(
            "pg_dump.custom".to_string(),
            format!("sha256:{}", sha256_file(pg_dump_path)?),
        )]),
    };
    std::fs::write(&manifest_path, serde_json::to_vec_pretty(&manifest)?)?;
    // Move the dump into the stage.
    std::fs::copy(pg_dump_path, stage.join("pg_dump.custom"))?;
    if include_data_dir {
        copy_dir_recursive(data_dir, &stage.join("data"), include_secret_key)?;
        if !include_secret_key && data_dir.join(SECRET_KEY_FILE).exists() {
            tracing::info!(
                "left {SECRET_KEY_FILE} out of the archive; pass --include-secret-key to carry it,                  or set UTOPIA_SECRET_KEY on the host that restores"
            );
        }
    }
    // tar -C <stage> -czf <output> .
    let status = Command::new(tar_bin)
        .arg("-C")
        .arg(&stage)
        .arg("-czf")
        .arg(output)
        .arg(".")
        .stdin(Stdio::null())
        .status()?;
    let _ = std::fs::remove_dir_all(&stage);
    if !status.success() {
        anyhow::bail!("tar exited with status {}", status);
    }
    // Touch the connection-string metadata via tracing; not embedded in the
    // archive on purpose (the dump file may be enough).
    tracing::debug!(conn_host = %redact_url_host(conn), "tarball built");
    Ok(())
}

/// The file the server seals credentials with (`utopia-server`'s `secret_key_file`).
const SECRET_KEY_FILE: &str = "secret.key";

/// Copy a directory into the staging area. `with_secret_key` off leaves the
/// sealing key behind: everything else in `data/` is content, that one file is
/// the key to the dump's ciphertext.
fn copy_dir_recursive(src: &Path, dst: &Path, with_secret_key: bool) -> anyhow::Result<()> {
    std::fs::create_dir_all(dst)?;
    for entry in std::fs::read_dir(src)? {
        let entry = entry?;
        let from = entry.path();
        if !with_secret_key && entry.file_name() == SECRET_KEY_FILE {
            continue;
        }
        let to = dst.join(entry.file_name());
        let ty = entry.file_type()?;
        if ty.is_dir() {
            copy_dir_recursive(&from, &to, with_secret_key)?;
        } else if ty.is_symlink() {
            // Skip symlinks — they don't survive backup/restore in a portable way.
            tracing::warn!(path = %from.display(), "skipping symlink in data dir");
        } else {
            std::fs::copy(&from, &to)?;
        }
    }
    Ok(())
}

fn tempdir_in(parent: &Path) -> anyhow::Result<PathBuf> {
    let name = format!(".utopia-backup-{}", Utc::now().timestamp_millis());
    let p = parent.join(name);
    std::fs::create_dir_all(&p)?;
    Ok(p)
}

/// Replace everything after the `://` up to the next `@` with `***`.
fn redact_url_host(conn: &str) -> String {
    match (conn.find("://"), conn.find('@')) {
        (Some(scheme), Some(at)) if at > scheme => {
            let mut out = String::with_capacity(conn.len());
            out.push_str(&conn[..scheme + 3]);
            out.push_str("***");
            out.push_str(&conn[at..]);
            out
        }
        _ => "<no host>".to_string(),
    }
}

fn sha256_file(path: &Path) -> anyhow::Result<String> {
    use sha2::{Digest, Sha256};
    let bytes = std::fs::read(path)?;
    let mut hasher = Sha256::new();
    hasher.update(&bytes);
    let digest = hasher.finalize();
    Ok(hex_encode(&digest))
}

fn hex_encode(bytes: &[u8]) -> String {
    const HEX: &[u8] = b"0123456789abcdef";
    let mut s = String::with_capacity(bytes.len() * 2);
    for b in bytes {
        s.push(HEX[(b >> 4) as usize] as char);
        s.push(HEX[(b & 0x0f) as usize] as char);
    }
    s
}

// ---------------------------------------------------------------------------
// restore (stubbed)
// ---------------------------------------------------------------------------

fn run_restore(args: RestoreArgs) -> anyhow::Result<()> {
    let cfg = AppConfig::load()?;
    let from = args
        .from
        .as_ref()
        .ok_or_else(|| anyhow::anyhow!("--from <path> is required"))?;
    if !from.exists() {
        anyhow::bail!("backup archive does not exist: {}", from.display());
    }

    let pg_restore_bin = args
        .pg_restore
        .clone()
        .unwrap_or_else(|| PathBuf::from("pg_restore"));
    let tar_bin = PathBuf::from("tar");
    let target_db = cfg.migration_url().to_string();
    let target_data_dir = args
        .target_data_dir
        .clone()
        .unwrap_or_else(|| PathBuf::from(&cfg.data_dir));

    // Stage: extract the tarball into a tempdir we own. The cleanup at the
    // end of every path uses `let _ = remove_dir_all(&stage)` so a panic or
    // early return doesn't leave a half-written data dir behind.
    let stage = tempdir_in(std::env::current_dir()?.as_path())?;
    let manifest_path = stage.join("manifest.json");

    let manifest = match extract_and_verify(&tar_bin, from, &stage, &manifest_path) {
        Ok(m) => m,
        Err(e) => {
            let _ = std::fs::remove_dir_all(&stage);
            return Err(e);
        }
    };

    // Manifest version policy: refuse forward, warn older. Forward refusal
    // is fatal because restoring into an older server with a newer schema
    // will silently drop tables or, worse, produce a working schema with
    // missing columns. Older manifests are accepted with a warning because
    // a newer server can usually still load them (the schema migrations are
    // forward-only; older files just exercise older code paths).
    if manifest.schema_version > CURRENT_SCHEMA_VERSION {
        let _ = std::fs::remove_dir_all(&stage);
        anyhow::bail!(
            "manifest schema_version {} is newer than this binary's {}; refusing to restore an incompatible backup",
            manifest.schema_version,
            CURRENT_SCHEMA_VERSION
        );
    }
    if manifest.schema_version < CURRENT_SCHEMA_VERSION {
        eprintln!(
            "[warn] manifest schema_version {} is older than this binary's {}; continuing",
            manifest.schema_version, CURRENT_SCHEMA_VERSION
        );
    }

    let plan = format!(
        "Restore plan:\n  \
         source archive:         {}\n  \
         manifest schema:        {} (current {})\n  \
         manifest utopia build:  {}\n  \
         manifest created:       {}\n  \
         target database:        {}\n  \
         target data dir:        {}\n  \
         force:                  {}\n  \
         dry-run:                {}\n",
        from.display(),
        manifest.schema_version,
        CURRENT_SCHEMA_VERSION,
        manifest.utopia_version,
        manifest.created_at,
        redact_url_host(&target_db),
        target_data_dir.display(),
        args.force,
        args.dry_run,
    );

    if args.dry_run {
        print!("{plan}");
        let _ = std::fs::remove_dir_all(&stage);
        // Verify pre-flight so a bad plan still exits non-zero.
        preflight_restore(&pg_restore_bin, &target_data_dir, &manifest)?;
        eprintln!("[dry-run] plan resolved cleanly; no changes made.");
        return Ok(());
    }

    preflight_restore(&pg_restore_bin, &target_data_dir, &manifest)?;

    if !args.yes {
        eprint!(
            "{plan}\nAbout to drop and recreate the target database, then restore from the archive. Continue? [y/N] "
        );
        let mut buf = String::new();
        std::io::stdin().read_line(&mut buf)?;
        if !matches!(buf.trim().to_ascii_lowercase().as_str(), "y" | "yes") {
            let _ = std::fs::remove_dir_all(&stage);
            anyhow::bail!("aborted by user");
        }
    }

    if let Err(e) = apply_restore(
        &pg_restore_bin,
        &target_db,
        &target_data_dir,
        &stage,
        &manifest,
    ) {
        let _ = std::fs::remove_dir_all(&stage);
        return Err(e);
    }

    let _ = std::fs::remove_dir_all(&stage);
    tracing::info!(path = %from.display(), "restore complete");
    Ok(())
}

fn extract_and_verify(
    tar_bin: &Path,
    archive: &Path,
    stage: &Path,
    manifest_path: &Path,
) -> anyhow::Result<Manifest> {
    let status = Command::new(tar_bin)
        .arg("-xzf")
        .arg(archive)
        .arg("-C")
        .arg(stage)
        .stdin(Stdio::null())
        .status()?;
    if !status.success() {
        anyhow::bail!("tar exited with status {}; archive may be corrupt", status);
    }
    if !manifest_path.exists() {
        anyhow::bail!("archive did not contain a manifest.json at the root — not a utopia backup?");
    }
    // Verify each checksummed component. pg_dump.custom is the only one
    // today; data_dir is a directory tree so it's not hashed. Refusing on
    // mismatch is loud — restoring a half-corrupted archive would be a
    // silent failure mode nobody catches.
    let manifest: Manifest = serde_json::from_slice(&std::fs::read(manifest_path)?)?;
    for (name, expected) in &manifest.checksums {
        let path = stage.join(name);
        if !path.exists() {
            anyhow::bail!("manifest references `{name}` but the archive did not contain it");
        }
        let Some(expected_sha) = expected.strip_prefix("sha256:") else {
            anyhow::bail!("unsupported checksum scheme for `{name}`: {expected}");
        };
        let actual = sha256_file(&path)?;
        if actual != expected_sha {
            anyhow::bail!(
                "checksum mismatch for `{name}`: manifest says {expected_sha}, file is {actual}"
            );
        }
    }
    Ok(manifest)
}

fn preflight_restore(
    pg_restore_bin: &Path,
    target_data_dir: &Path,
    _manifest: &Manifest,
) -> anyhow::Result<()> {
    if !binary_works(pg_restore_bin) {
        anyhow::bail!(
            "pg_restore not found or not executable: {}. Install postgresql-client or pass --pg-restore <path>.",
            pg_restore_bin.display()
        );
    }
    // Data dir may not exist yet — restore creates it. Don't preflight its
    // existence; that's not a precondition failure.
    let _ = target_data_dir;
    Ok(())
}

fn apply_restore(
    pg_restore_bin: &Path,
    target_db: &str,
    target_data_dir: &Path,
    stage: &Path,
    manifest: &Manifest,
) -> anyhow::Result<()> {
    let pg_dump_path = stage.join(&manifest.components.pg_dump.path);
    if !pg_dump_path.exists() {
        anyhow::bail!(
            "manifest references pg_dump at `{}` but the archive did not contain it",
            manifest.components.pg_dump.path
        );
    }
    tracing::info!(
        archive_pg_dump = %pg_dump_path.display(),
        "running pg_restore --clean --if-exists"
    );
    let status = Command::new(pg_restore_bin)
        .arg("--clean")
        .arg("--if-exists")
        .arg("--dbname")
        .arg(target_db)
        .arg(&pg_dump_path)
        .stdin(Stdio::null())
        .status()?;
    if !status.success() {
        anyhow::bail!(
            "pg_restore exited with status {}; database may be in a partial state — verify with a follow-up pg_dump",
            status
        );
    }

    if manifest.components.data_dir.present {
        let archive_data_dir = stage.join(&manifest.components.data_dir.path);
        if archive_data_dir.exists() {
            tracing::info!(
                target = %target_data_dir.display(),
                "restoring data dir"
            );
            // Drop the existing target dir if it's non-empty so the copy
            // below doesn't merge two worlds. This is what `--force`
            // guards upstream — if `--force` is missing and the target
            // already has files, fail loud.
            if target_data_dir.exists() && std::fs::read_dir(target_data_dir)?.next().is_some() {
                anyhow::bail!(
                    "target data dir {} is non-empty; pass --force to overwrite",
                    target_data_dir.display()
                );
            }
            // 恢复时照搬压缩包里有的:包里没有密钥,是打包那一步的决定,不是这里的
            copy_dir_recursive(&archive_data_dir, target_data_dir, true)?;
            if !manifest.components.data_dir.secret_key {
                // 没有钥匙,库里那些封存的凭据就打不开。与其让人在服务起来之后
                // 看见一串解不开的错误,不如现在说清楚该做什么
                tracing::warn!(
                    "this archive carries no {SECRET_KEY_FILE}: sealed credentials (model keys,                      source credentials) will not open. Set UTOPIA_SECRET_KEY on this host to the                      key the backup was taken with, or re-enter them after starting the server"
                );
            }
        } else {
            tracing::warn!(
                path = %archive_data_dir.display(),
                "manifest says data_dir is present but the archive did not contain it; skipping"
            );
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parses_backup_minimal() {
        let args = vec!["backup".to_string()];
        let cmd = parse(&args).expect("parses");
        match cmd {
            Command2::Backup(b) => {
                assert!(b.output.is_none());
                assert!(!b.include_data_dir);
                assert!(!b.dry_run);
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn parses_backup_full() {
        let args = vec![
            "backup".to_string(),
            "--output".to_string(),
            "/tmp/b.tar.gz".to_string(),
            "--include-data-dir".to_string(),
            "--dry-run".to_string(),
            "--pg-dump".to_string(),
            "/opt/pg/bin/pg_dump".to_string(),
            "--tar".to_string(),
            "/bin/tar".to_string(),
            "--migration-url".to_string(),
            "postgres://u:***@h/db".to_string(),
        ];
        let cmd = parse(&args).expect("parses");
        match cmd {
            Command2::Backup(b) => {
                assert_eq!(b.output, Some(PathBuf::from("/tmp/b.tar.gz")));
                assert!(b.include_data_dir);
                assert!(b.dry_run);
                assert_eq!(b.pg_dump, Some(PathBuf::from("/opt/pg/bin/pg_dump")));
                assert_eq!(b.tar, Some(PathBuf::from("/bin/tar")));
                assert_eq!(b.migration_url.as_deref(), Some("postgres://u:***@h/db"));
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn parses_restore_requires_from() {
        let args = vec!["restore".to_string()];
        assert!(parse(&args).is_err());
    }

    /// 备份包里默认没有封存密钥。库里存的凭据是用它加密的,两样装在同一个
    /// 压缩包里,封存就等于没有——而压缩包恰恰是那个会被拷来拷去、交给别人去
    /// 恢复的东西
    #[test]
    fn the_sealing_key_stays_out_of_the_archive_unless_asked() {
        let src = std::env::temp_dir().join(format!("utopia-seckey-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&src);
        std::fs::create_dir_all(src.join("files")).unwrap();
        std::fs::write(src.join(SECRET_KEY_FILE), b"not-a-real-key").unwrap();
        std::fs::write(src.join("files").join("a.bin"), b"content").unwrap();

        let without = src.with_extension("without");
        let _ = std::fs::remove_dir_all(&without);
        copy_dir_recursive(&src, &without, false).unwrap();
        assert!(
            !without.join(SECRET_KEY_FILE).exists(),
            "默认把密钥带进去了"
        );
        assert!(
            without.join("files").join("a.bin").exists(),
            "别的内容不该少"
        );

        let with = src.with_extension("with");
        let _ = std::fs::remove_dir_all(&with);
        copy_dir_recursive(&src, &with, true).unwrap();
        assert!(with.join(SECRET_KEY_FILE).exists(), "说了要带却没带");

        for d in [src, without, with] {
            let _ = std::fs::remove_dir_all(d);
        }
    }

    #[test]
    fn parses_restore_full() {
        let args = vec![
            "restore".to_string(),
            "--from".to_string(),
            "/tmp/b.tar.gz".to_string(),
            "--target-data-dir".to_string(),
            "/var/lib/utopia/data".to_string(),
            "--force".to_string(),
            "--yes".to_string(),
            "--dry-run".to_string(),
        ];
        let cmd = parse(&args).expect("parses");
        match cmd {
            Command2::Restore(r) => {
                assert_eq!(r.from, Some(PathBuf::from("/tmp/b.tar.gz")));
                assert_eq!(
                    r.target_data_dir,
                    Some(PathBuf::from("/var/lib/utopia/data"))
                );
                assert!(r.force);
                assert!(r.yes);
                assert!(r.dry_run);
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn rejects_unknown_subcommand() {
        let args = vec!["frobnicate".to_string()];
        assert!(parse(&args).is_err());
    }

    #[test]
    fn redact_url_host_keeps_userinfo_at_host() {
        let r = redact_url_host("postgres://utopia:secret@db:5432/utopia");
        assert_eq!(r, "postgres://***@db:5432/utopia");
    }

    #[test]
    fn redact_url_host_handles_no_at() {
        let r = redact_url_host("not a url");
        assert_eq!(r, "<no host>");
    }

    #[test]
    fn hex_encode_known_value() {
        // SHA256 of "abc"
        assert_eq!(
            hex_encode(&[
                0xba, 0x78, 0x16, 0xbf, 0x8f, 0x01, 0xcf, 0xea, 0x41, 0x41, 0x40, 0xde, 0x5d, 0xae,
                0x22, 0x23, 0xb0, 0x03, 0x61, 0xa3, 0x96, 0x17, 0x7a, 0x9c, 0xb4, 0x10, 0xff, 0x61,
                0xf2, 0x00, 0x15, 0xad,
            ]),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
    }

    /// Manifest round-trips: serialize → deserialize produces the same shape
    /// on the read side. Today `backup` writes with `Serialize`, `restore`
    /// reads with `Deserialize` — if either side drops or renames a field,
    /// this is the test that catches it.
    #[test]
    fn manifest_round_trip() {
        let mut checksums = HashMap::new();
        checksums.insert("pg_dump.custom".to_string(), "sha256:deadbeef".to_string());
        let written = Manifest {
            schema_version: CURRENT_SCHEMA_VERSION,
            utopia_version: "0.1.0".to_string(),
            created_at: "2026-09-17T09:00:00Z".to_string(),
            components: ManifestComponents {
                pg_dump: ManifestComponent {
                    path: "pg_dump.custom".to_string(),
                    format: "pg_dump -Fc".to_string(),
                    bytes: 12345,
                },
                data_dir: ManifestDataDir {
                    path: "data".to_string(),
                    present: true,
                    secret_key: false,
                },
            },
            checksums,
        };
        let json = serde_json::to_string(&written).unwrap();
        let read: Manifest = serde_json::from_str(&json).unwrap();
        assert_eq!(read.schema_version, CURRENT_SCHEMA_VERSION);
        assert_eq!(read.utopia_version, "0.1.0");
        assert_eq!(read.components.pg_dump.bytes, 12345);
        assert!(read.components.data_dir.present);
        assert_eq!(
            read.checksums.get("pg_dump.custom").map(String::as_str),
            Some("sha256:deadbeef")
        );
    }

    /// Forward-incompatible manifest: schema_version > CURRENT. Restore must
    /// bail before touching the live database. The actual gate is inside
    /// `run_restore`; this test pins the version-policy behaviour at the
    /// constant level so a future bump that changes the comparison shape
    /// (e.g. switching to a rangeset) gets caught at compile-test time, not
    /// in production.
    #[test]
    fn schema_version_policy_compares_against_current() {
        // Same shape as `run_restore`'s gate. If the rule changes here,
        // change it there too.
        let current = CURRENT_SCHEMA_VERSION;
        assert!(
            current + 1 > current,
            "newer manifests must compare > current"
        );
        assert!(
            current - 1 < current,
            "older manifests must compare < current"
        );
        // And the constant itself must stay in lockstep with the highest
        // applied migration in `migrations/` — bumping a migration file
        // without bumping this is a silent schema-version skew. The
        // `migrations/` dir is a sibling of `crates/utopia-cli/`; resolve
        // from CARGO_MANIFEST_DIR so the test works regardless of cwd.
        let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
        let migrations_dir = manifest_dir
            .parent()
            .and_then(|p| p.parent())
            .map(|p| p.join("migrations"))
            .expect("workspace root has a migrations/ dir");
        let applied = std::fs::read_dir(&migrations_dir)
            .unwrap_or_else(|e| {
                panic!(
                    "migrations dir {} unreadable: {e}",
                    migrations_dir.display()
                )
            })
            .filter_map(|e| e.ok())
            .filter(|e| e.path().extension().map(|x| x == "sql").unwrap_or(false))
            .count() as u32;
        assert_eq!(
            current, applied,
            "CURRENT_SCHEMA_VERSION must match the count of applied migrations; \
             bump it when you add a migration"
        );
    }

    /// `extract_and_verify` against an archive without a manifest.json:
    /// should fail loudly with "not a utopia backup?" rather than running
    /// pg_restore against an empty stage. Build a fake tarball in a temp
    /// dir so the path is exercised end-to-end.
    #[test]
    fn extract_fails_when_archive_has_no_manifest() {
        let stage = tempdir_for_test("no_manifest");
        // Stage must already exist for `tar -C`. Create a fake archive
        // containing exactly one file inside a fresh staging dir, then run
        // extract_and_verify against a different stage.
        let src = tempdir_for_test("src");
        std::fs::write(src.join("unrelated.txt"), b"not a backup").unwrap();
        let archive = src.join("fake.tar.gz");
        let status = Command::new("tar")
            .arg("-czf")
            .arg(&archive)
            .arg("-C")
            .arg(&src)
            .arg("unrelated.txt")
            .stdin(Stdio::null())
            .status()
            .expect("tar available");
        assert!(status.success(), "host tar is required for this test");
        let manifest_path = stage.join("manifest.json");
        let result = extract_and_verify(Path::new("tar"), &archive, &stage, &manifest_path);
        let _ = std::fs::remove_dir_all(&stage);
        let _ = std::fs::remove_dir_all(&src);
        let err = result.unwrap_err().to_string();
        assert!(
            err.contains("not a utopia backup"),
            "want a clear error, got: {err}"
        );
    }

    /// Checksum mismatch: stage contains a `pg_dump.custom` whose bytes
    /// don't match the manifest's sha256. `extract_and_verify` must refuse
    /// rather than pass a corrupted archive on to pg_restore.
    #[test]
    fn extract_fails_on_checksum_mismatch() {
        let src = tempdir_for_test("mismatch_src");
        // Real pg_dump bytes we can corrupt at will.
        std::fs::write(src.join("pg_dump.custom"), b"original-bytes").unwrap();
        let archive = src.join("mismatch.tar.gz");
        let status = Command::new("tar")
            .arg("-czf")
            .arg(&archive)
            .arg("-C")
            .arg(&src)
            .arg("pg_dump.custom")
            .stdin(Stdio::null())
            .status()
            .expect("tar available");
        assert!(status.success());
        let manifest_json = serde_json::json!({
            "schema_version": CURRENT_SCHEMA_VERSION,
            "utopia_version": "0.1.0",
            "created_at": "2026-09-17T00:00:00Z",
            "components": {
                "pg_dump": {
                    "path": "pg_dump.custom",
                    "format": "pg_dump -Fc",
                    "bytes": 14
                },
                "data_dir": { "path": "data", "present": false }
            },
            // SHA256 of "tampered" — neither the file nor the empty archive
            // matches this, so verification must fail.
            "checksums": { "pg_dump.custom": "sha256:0000000000000000000000000000000000000000000000000000000000000000" }
        })
        .to_string();
        std::fs::write(src.join("manifest.json"), manifest_json).unwrap();
        // Re-pack with both files so the archive contains manifest + dump.
        let archive2 = src.join("mismatch2.tar.gz");
        let status = Command::new("tar")
            .arg("-czf")
            .arg(&archive2)
            .arg("-C")
            .arg(&src)
            .arg("manifest.json")
            .arg("pg_dump.custom")
            .stdin(Stdio::null())
            .status()
            .unwrap();
        assert!(status.success());

        let stage = tempdir_for_test("mismatch_stage");
        let manifest_path = stage.join("manifest.json");
        let result = extract_and_verify(Path::new("tar"), &archive2, &stage, &manifest_path);
        let _ = std::fs::remove_dir_all(&stage);
        let _ = std::fs::remove_dir_all(&src);
        let err = result.unwrap_err().to_string();
        assert!(
            err.contains("checksum mismatch"),
            "want a checksum error, got: {err}"
        );
    }

    /// Create a uniquely-named temp directory under the process's CWD. Test
    /// cleanup is the caller's responsibility — keeps the helper
    /// dependency-free (no tempfile crate). Mirrors the shape of
    /// `tempdir_in` used by the production paths.
    fn tempdir_for_test(label: &str) -> PathBuf {
        let name = format!(
            ".utopia-cli-test-{label}-{}",
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        );
        let p = std::env::current_dir().unwrap().join(name);
        std::fs::create_dir_all(&p).unwrap();
        p
    }
}

#[cfg(test)]
mod option_value_regressions {
    use super::*;

    #[test]
    fn backup_value_options_do_not_fall_back_when_missing() {
        for flag in ["--output", "--pg-dump", "--tar", "--migration-url"] {
            for suffix in [vec![], vec!["--dry-run"], vec![""]] {
                let mut args = vec!["backup", flag];
                args.extend(suffix);
                let args: Vec<String> = args.into_iter().map(str::to_string).collect();
                assert!(parse(&args).is_err(), "accepted {args:?}");
            }
        }
    }

    #[test]
    fn restore_value_options_do_not_consume_other_flags() {
        for flag in ["--from", "--target-data-dir", "--pg-restore"] {
            for suffix in [vec![], vec!["--dry-run"], vec![""]] {
                let mut args = vec!["restore", "--from", "archive.tar.gz", flag];
                args.extend(suffix);
                let args: Vec<String> = args.into_iter().map(str::to_string).collect();
                assert!(parse(&args).is_err(), "accepted {args:?}");
            }
        }
    }
}