Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
24.2 KB
Raw Blame
//! Pre-migration backup of the entire data directory (docs/okf.md).
//!
//! The OKF migration's first step — and its gate: no verified archive,
//! no migration. The archive lands OUTSIDE the data dir, in the user's
//! home (`AI_MEMORY_BACKUP_DIR` overrides the destination for machines
//! where home is small), and a receipt is recorded at
//! `<data_dir>/pre-migration-backup.json` so the wiki homepage can show
//! where it is until the user deletes it.
// Backups are written outside the wiki tree and are not part of its history.
#![allow(clippy::disallowed_methods)]

use std::fs::File;
use std::io::{BufReader, BufWriter, Write};
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::error::{WikiError, WikiResult};

/// File name of the receipt inside the data dir.
pub const BACKUP_RECEIPT_FILE: &str = "pre-migration-backup.json";

/// What the backup step produced; persisted as the receipt.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BackupReceipt {
    /// Absolute path of the archive.
    pub archive_path: PathBuf,
    /// Archive size in bytes.
    pub size_bytes: u64,
    /// Entries in the archive (files archived).
    pub entries: usize,
    /// ISO-8601 creation instant.
    pub created_at: String,
    /// What the backup was taken for (e.g. "okf-v0.2-migration").
    pub label: String,
    /// Free space on the destination filesystem right after the archive was
    /// written, in bytes. `None` when it could not be read (e.g. an
    /// unsupported filesystem) — never fails the backup on its own. A
    /// verified archive next to a nearly-full disk is the exact shape of
    /// the outage that motivated this field: the WAL had nowhere left to
    /// extend minutes after a backup that "succeeded".
    pub dest_free_bytes: Option<u64>,
}

impl BackupReceipt {
    /// Read the receipt from `data_dir`, if one exists and parses.
    #[must_use]
    pub fn load(data_dir: &Path) -> Option<Self> {
        let raw = std::fs::read(data_dir.join(BACKUP_RECEIPT_FILE)).ok()?;
        serde_json::from_slice(&raw).ok()
    }

    /// Whether the archive the receipt points at still exists on disk.
    #[must_use]
    pub fn archive_present(&self) -> bool {
        self.archive_path.exists()
    }
}

/// Whether this process runs inside a container. Same signals as the
/// serve handler: the official image sets `AI_MEMORY_IN_CONTAINER`;
/// `/.dockerenv` (Docker) and `/run/.containerenv` (Podman) cover
/// images that do not.
#[must_use]
pub fn running_in_container() -> bool {
    if std::env::var("AI_MEMORY_IN_CONTAINER").is_ok_and(|v| !v.trim().is_empty()) {
        return true;
    }
    Path::new("/.dockerenv").exists() || Path::new("/run/.containerenv").exists()
}

/// Destination directory for archives.
///
/// - the explicit override wins (callers read `AI_MEMORY_BACKUP_DIR`);
/// - **in a container, the user's home is ephemeral** — it lives in the
///   container layer and is destroyed on the next recreation, which
///   would silently lose the safety archive. The only storage
///   guaranteed to persist is the data-dir volume, so the default there
///   is `<data_dir>/backups/` (excluded from the archive itself);
/// - otherwise the user's home.
///
/// The destination may live inside the data dir (the archive protects
/// against the MIGRATION corrupting content, not against disk loss, and
/// the walk excludes it), but never the data dir root itself.
fn destination_dir(
    dest_override: Option<&Path>,
    data_dir: &Path,
    in_container: bool,
) -> WikiResult<PathBuf> {
    let dest = if let Some(dir) = dest_override {
        dir.to_path_buf()
    } else if in_container {
        data_dir.join("backups")
    } else {
        dirs::home_dir().ok_or_else(|| {
            WikiError::Io(std::io::Error::other(
                "no home directory found for the pre-migration backup; \
                 set AI_MEMORY_BACKUP_DIR to a directory outside the data dir",
            ))
        })?
    };
    // Canonicalize both sides before comparing: `<data_dir>/.` or a
    // symlinked spelling must not defeat the root guard (or the walk's
    // self-exclusion, which compares against the path returned here).
    // The dest is created first so it ALWAYS canonicalizes — an
    // uncanonical spelling of a not-yet-existing dest defeated the
    // self-exclusion on the very first backup.
    std::fs::create_dir_all(&dest)?;
    let canonical_data = data_dir
        .canonicalize()
        .unwrap_or_else(|_| data_dir.to_path_buf());
    let canonical_dest = dest.canonicalize().unwrap_or_else(|_| dest.clone());
    if canonical_dest == canonical_data {
        return Err(WikiError::Io(std::io::Error::other(
            "the backup destination must not be the data dir root itself; \
             use a subdirectory (e.g. <data_dir>/backups) or a path outside it",
        )));
    }
    Ok(canonical_dest)
}

/// Compress `data_dir` into a timestamped tar.gz in the destination dir,
/// verify the archive is readable and complete, write the receipt, and
/// return it. Any failure aborts (the caller must not migrate).
pub fn create_pre_migration_backup(
    data_dir: &Path,
    label: &str,
    dest_override: Option<&Path>,
) -> WikiResult<BackupReceipt> {
    create_pre_migration_backup_inner(data_dir, label, dest_override, running_in_container())
}

fn create_pre_migration_backup_inner(
    data_dir: &Path,
    label: &str,
    dest_override: Option<&Path>,
    in_container: bool,
) -> WikiResult<BackupReceipt> {
    crate::confinement::inspect_tree_if_present(&data_dir.join("wiki"))?;
    // One spelling for every comparison below: `destination_dir` returns a
    // canonical path, so the walk must produce canonical paths too or the
    // self-exclusion guards (`path == dest_dir`, `path == archive_path`)
    // silently miss under a symlinked data-dir spelling (macOS /var ->
    // /private/var; observed tarring the half-written archive itself).
    let data_dir = &data_dir
        .canonicalize()
        .unwrap_or_else(|_| data_dir.to_path_buf());
    crate::confinement::inspect_tree(data_dir)?;
    let dest_dir = destination_dir(dest_override, data_dir, in_container)?;
    let stamp = jiff::Timestamp::now().strftime("%Y%m%d-%H%M%S").to_string();
    let (archive_path, archive_file) = reserve_archive(&dest_dir, label, &stamp)?;

    // The migration runs at server startup before any traffic, so the
    // SQLite files (db + WAL/SHM) are quiescent and archived as a set.
    let mut expected = 0usize;
    {
        let file = BufWriter::new(archive_file);
        let enc = flate2::write::GzEncoder::new(file, flate2::Compression::default());
        let mut tar = tar::Builder::new(enc);
        tar.follow_symlinks(false);
        let mut stack = vec![data_dir.to_path_buf()];
        while let Some(dir) = stack.pop() {
            for entry in std::fs::read_dir(&dir)? {
                let entry = entry?;
                let path = entry.path();
                let rel = path
                    .strip_prefix(data_dir)
                    .map_err(|e| WikiError::Io(std::io::Error::other(e)))?;
                let metadata = std::fs::symlink_metadata(&path)?;
                if crate::confinement::is_link_like(&metadata) {
                    return Err(WikiError::Confinement {
                        path,
                        reason: "symbolic links and reparse points are not allowed in backups",
                    });
                }
                if metadata.is_dir() {
                    // Never archive the destination itself (a container
                    // default of <data_dir>/backups, or an override
                    // pointed inside the data dir) — self-inclusion
                    // would tar the half-written archive.
                    if path == dest_dir {
                        continue;
                    }
                    stack.push(path);
                } else if metadata.is_file() {
                    let file_name = path.file_name().and_then(|n| n.to_str());
                    if path == archive_path
                        || file_name == Some("pre-migration-backup.json.tmp")
                        // The single-instance serve lock and its holder-info
                        // sidecar. On Windows the exclusive LockFileEx is
                        // mandatory, so the same serve process that owns the
                        // migration also holds `.serve.lock` and cannot read
                        // it back from the walk (os error 33). Keep in sync
                        // with crates/ai-memory-cli/src/commands/serve.rs
                        // `SERVE_LOCK_FILE`.
                        || file_name.is_some_and(|n| n.starts_with(".serve.lock"))
                    {
                        continue;
                    }
                    tar.append_path_with_name(&path, rel)?;
                    expected += 1;
                }
            }
        }
        // The verify pass below re-reads the page cache, so it cannot tell an
        // archive on stable storage from one that is not. This archive is the
        // gate for a destructive in-place migration, so it has to survive a
        // crash: fsync the file, then its directory entry. The admin backup
        // endpoints sync after `finish` for the same reason.
        finish_archive(tar)?.sync_all()?;
        File::open(&dest_dir)
            .and_then(|dir| dir.sync_all())
            .unwrap_or_else(|e| {
                tracing::debug!(
                    dest = %dest_dir.display(),
                    error = %e,
                    "could not fsync the backup destination directory"
                );
            });
    }

    // Verify: re-open and count entries; a torn or unreadable archive
    // fails here and the caller aborts the migration.
    let mut counted = 0usize;
    {
        let file = BufReader::new(File::open(&archive_path)?);
        let dec = flate2::read::GzDecoder::new(file);
        let mut ar = tar::Archive::new(dec);
        for entry in ar.entries()? {
            entry?;
            counted += 1;
        }
    }
    let size_bytes = std::fs::metadata(&archive_path)?.len();
    if counted != expected || size_bytes == 0 {
        let _ = std::fs::remove_file(&archive_path);
        return Err(WikiError::Io(std::io::Error::other(format!(
            "backup verification failed: archived {expected} files but the \
             archive lists {counted} (size {size_bytes}); refusing to migrate"
        ))));
    }

    // A signal only: the backup itself already succeeded and verified, so a
    // free-space read that fails (unsupported filesystem, transient error)
    // must not turn a good archive into a failed migration.
    let dest_free_bytes = match fs2::available_space(&dest_dir) {
        Ok(bytes) => Some(bytes),
        Err(e) => {
            tracing::debug!(
                dest = %dest_dir.display(),
                error = %e,
                "could not read destination free space"
            );
            None
        }
    };

    let receipt = BackupReceipt {
        archive_path,
        size_bytes,
        entries: counted,
        created_at: jiff::Timestamp::now()
            .strftime("%Y-%m-%dT%H:%M:%SZ")
            .to_string(),
        label: label.to_string(),
        dest_free_bytes,
    };
    let tmp = data_dir.join(format!("{BACKUP_RECEIPT_FILE}.tmp"));
    std::fs::write(&tmp, serde_json::to_vec_pretty(&receipt)?)?;
    std::fs::rename(&tmp, data_dir.join(BACKUP_RECEIPT_FILE))?;
    Ok(receipt)
}

/// Different data dirs can migrate in the same second and share a destination
/// (the default is the user's home). Reserve a new path atomically so neither
/// archive can replace the other's only pre-migration snapshot.
fn reserve_archive(dest: &Path, label: &str, stamp: &str) -> WikiResult<(PathBuf, File)> {
    for suffix in 0_u32..=u32::MAX {
        let suffix = if suffix == 0 {
            String::new()
        } else {
            format!("-{suffix}")
        };
        let path = dest.join(format!("ai-memory-backup-{label}-{stamp}{suffix}.tar.gz"));
        match File::options().write(true).create_new(true).open(&path) {
            Ok(file) => return Ok((path, file)),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(error) => return Err(error.into()),
        }
    }
    Err(WikiError::Io(std::io::Error::new(
        std::io::ErrorKind::AlreadyExists,
        "could not reserve a unique pre-migration archive path",
    )))
}

/// End the gzip stream and flush the buffer, returning the underlying writer.
///
/// `GzEncoder::finish` hands back the `BufWriter`; dropping it would write the
/// buffered tail from `Drop`, which discards the error, and a backup on a full
/// disk would then reach the verify pass as if it had been written.
fn finish_archive<W: Write>(
    tar: tar::Builder<flate2::write::GzEncoder<BufWriter<W>>>,
) -> std::io::Result<W> {
    tar.into_inner()?
        .finish()?
        .into_inner()
        .map_err(std::io::IntoInnerError::into_error)
}

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

    /// A destination that takes no bytes, like a full disk.
    struct FullDisk;

    impl Write for FullDisk {
        fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
            Err(std::io::ErrorKind::StorageFull.into())
        }

        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    /// The whole small archive sits in the `BufWriter` until `finish`, so the
    /// write that fails is the one flushing that tail; it must reach the
    /// caller instead of being dropped with the buffer.
    #[test]
    fn a_failed_final_flush_fails_the_archive() {
        let enc =
            flate2::write::GzEncoder::new(BufWriter::new(FullDisk), flate2::Compression::default());
        let mut tar = tar::Builder::new(enc);
        let body = b"page body";
        let mut header = tar::Header::new_gnu();
        header.set_size(body.len() as u64);
        header.set_cksum();
        tar.append_data(&mut header, "wiki/page.md", &body[..])
            .unwrap();

        let error = finish_archive(tar).err().expect("a full disk must fail");
        assert_eq!(error.kind(), std::io::ErrorKind::StorageFull);
    }

    fn data_dir_with_content() -> TempDir {
        let tmp = TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("wiki/ws/proj/notes")).unwrap();
        std::fs::write(tmp.path().join("wiki/ws/proj/notes/a.md"), "---\n---\nbody").unwrap();
        std::fs::write(tmp.path().join("db.sqlite"), b"not really a db").unwrap();
        tmp
    }

    #[cfg(unix)]
    #[test]
    fn a_pre_migration_backup_refuses_a_linked_wiki_tree_without_an_archive() {
        let data = data_dir_with_content();
        let outside = TempDir::new().unwrap();
        std::fs::write(outside.path().join("canary.md"), "outside canary").unwrap();
        std::os::unix::fs::symlink(outside.path(), data.path().join("wiki/linked")).unwrap();
        let dest = TempDir::new().unwrap();

        assert!(matches!(
            create_pre_migration_backup(data.path(), "test", Some(dest.path())),
            Err(WikiError::Confinement { .. })
        ));
        assert_eq!(std::fs::read_dir(dest.path()).unwrap().count(), 0);
        assert_eq!(
            std::fs::read_to_string(outside.path().join("canary.md")).unwrap(),
            "outside canary"
        );
    }

    #[test]
    fn a_backup_archives_everything_and_writes_a_receipt() {
        let data = data_dir_with_content();
        let dest = TempDir::new().unwrap();
        let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();
        // TempDir spellings differ from canonical on macOS (/var vs
        // /private/var); the backup works in canonical space.
        assert!(
            receipt
                .archive_path
                .starts_with(dest.path().canonicalize().unwrap())
        );
        assert_eq!(receipt.entries, 2);
        assert!(receipt.size_bytes > 0);
        assert!(receipt.archive_present());
        let loaded = BackupReceipt::load(data.path()).unwrap();
        assert_eq!(loaded.archive_path, receipt.archive_path);
    }

    #[test]
    fn separate_installs_keep_their_own_pre_migration_archives() {
        let first_data = data_dir_with_content();
        let second_data = data_dir_with_content();
        std::fs::write(second_data.path().join("db.sqlite"), b"another install").unwrap();
        let dest = TempDir::new().unwrap();
        let first =
            create_pre_migration_backup(first_data.path(), "test", Some(dest.path())).unwrap();
        let original = std::fs::read(&first.archive_path).unwrap();
        let second =
            create_pre_migration_backup(second_data.path(), "test", Some(dest.path())).unwrap();

        assert_ne!(first.archive_path, second.archive_path);
        assert_eq!(std::fs::read(&first.archive_path).unwrap(), original);
        assert_eq!(
            BackupReceipt::load(first_data.path()).unwrap().archive_path,
            first.archive_path
        );
        assert_eq!(
            BackupReceipt::load(second_data.path())
                .unwrap()
                .archive_path,
            second.archive_path
        );
    }

    #[test]
    fn archive_reservations_at_the_same_timestamp_preserve_existing_files() {
        let dest = TempDir::new().unwrap();
        let stamp = "20261028-120000";
        let first = dest
            .path()
            .join(format!("ai-memory-backup-test-{stamp}.tar.gz"));
        let second = dest
            .path()
            .join(format!("ai-memory-backup-test-{stamp}-1.tar.gz"));
        std::fs::write(&first, b"first snapshot").unwrap();
        std::fs::write(&second, b"second snapshot").unwrap();

        let (third, mut file) = reserve_archive(dest.path(), "test", stamp).unwrap();
        file.write_all(b"third snapshot").unwrap();
        drop(file);

        assert_eq!(std::fs::read(&first).unwrap(), b"first snapshot");
        assert_eq!(std::fs::read(&second).unwrap(), b"second snapshot");
        assert_eq!(std::fs::read(&third).unwrap(), b"third snapshot");
        assert_eq!(
            third.file_name().unwrap(),
            format!("ai-memory-backup-test-{stamp}-2.tar.gz").as_str()
        );
    }

    /// The signal this field exists for: a verified archive next to a
    /// nearly-full disk. A temp dir always reports some free space, and the
    /// receipt (round-tripped through the JSON file) must carry it.
    #[test]
    fn the_receipt_carries_destination_free_space() {
        let data = data_dir_with_content();
        let dest = TempDir::new().unwrap();
        let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();
        let free = receipt
            .dest_free_bytes
            .expect("free space should be readable for a real temp dir");
        assert!(free > 0);
        let loaded = BackupReceipt::load(data.path()).unwrap();
        assert_eq!(loaded.dest_free_bytes, receipt.dest_free_bytes);
    }

    #[test]
    fn an_unwritable_destination_aborts_instead_of_falling_back() {
        let data = data_dir_with_content();
        let dest = TempDir::new().unwrap();
        let blocked = dest.path().join("blocked-file");
        std::fs::write(&blocked, b"a file, not a dir").unwrap();
        let err = create_pre_migration_backup(data.path(), "test", Some(&blocked));
        assert!(err.is_err(), "backup must fail when it cannot write");
        assert!(
            BackupReceipt::load(data.path()).is_none(),
            "no receipt without an archive"
        );
    }

    /// In a container the home dir is ephemeral (destroyed on the next
    /// recreation), so the default destination is the data-dir volume's
    /// backups/ subdir — and the archive must not swallow itself.
    #[test]
    fn in_a_container_the_archive_lands_on_the_data_volume() {
        let data = data_dir_with_content();
        let receipt = create_pre_migration_backup_inner(data.path(), "test", None, true).unwrap();
        assert!(
            receipt
                .archive_path
                .starts_with(data.path().canonicalize().unwrap().join("backups"))
        );
        // The two data files, not the archive or receipt.
        assert_eq!(receipt.entries, 2);
        assert!(receipt.archive_present());
    }

    /// A destination inside the data dir (container default or an
    /// override) is excluded from the walk: entry counts match the
    /// verification pass and a second backup does not tar the first.
    #[test]
    fn a_destination_inside_the_data_dir_is_never_self_included() {
        let data = data_dir_with_content();
        let dest = data.path().join("backups");
        let first = create_pre_migration_backup(data.path(), "test", Some(&dest)).unwrap();
        assert_eq!(first.entries, 2);
        // Receipt now exists in the data dir; a second run must archive
        // it (a real file) but never the prior archive in backups/.
        let second = create_pre_migration_backup(data.path(), "test", Some(&dest)).unwrap();
        assert_eq!(second.entries, 3, "data files + first receipt");
    }

    /// Reproduces the macOS matrix failure on any Unix: hand the backup a
    /// symlinked spelling of the data dir (as macOS's /var -> /private/var
    /// does implicitly) and prove the self-exclusion still holds — a second
    /// run must not descend into backups/ or tar the first archive.
    #[cfg(unix)]
    #[test]
    fn self_exclusion_survives_a_symlinked_data_dir_spelling() {
        let real = data_dir_with_content();
        let outer = TempDir::new().unwrap();
        let alias = outer.path().join("alias");
        std::os::unix::fs::symlink(real.path(), &alias).unwrap();
        let dest = alias.join("backups");
        let first = create_pre_migration_backup(&alias, "test", Some(&dest)).unwrap();
        assert_eq!(first.entries, 2);
        let second = create_pre_migration_backup(&alias, "test", Some(&dest)).unwrap();
        assert_eq!(
            second.entries, 3,
            "data files + first receipt, never the archive"
        );
    }

    #[test]
    fn the_data_dir_root_is_refused_as_a_destination() {
        let data = data_dir_with_content();
        let err = create_pre_migration_backup(data.path(), "test", Some(data.path()));
        assert!(err.is_err(), "data dir root must be refused");
    }

    #[test]
    fn a_deleted_archive_is_reported_absent() {
        let data = data_dir_with_content();
        let dest = TempDir::new().unwrap();
        let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();
        std::fs::remove_file(&receipt.archive_path).unwrap();
        assert!(!receipt.archive_present());
    }

    /// The pre-migration backup runs in the same process as `serve`, which
    /// holds `.serve.lock` under an exclusive LockFileEx. On Windows that
    /// lock is mandatory, so the walk cannot read the file back. The walk
    /// must skip `.serve.lock` and its `.serve.lock.holder` sidecar by name,
    /// exactly as it already skips the archive and the receipt tmp. Simulated
    /// here on all platforms because the skip is by name, independent of OS
    /// lock semantics; a Windows CI running the real lock would hit the same
    /// path after this guard.
    #[test]
    fn the_backup_skips_the_serve_lock_and_its_holder_sidecar() {
        let data = data_dir_with_content();
        std::fs::write(data.path().join(".serve.lock"), b"").unwrap();
        std::fs::write(data.path().join(".serve.lock.holder"), b"pid=1").unwrap();
        let dest = TempDir::new().unwrap();
        let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();
        assert_eq!(
            receipt.entries, 2,
            "only the two data files; serve lock and holder never archived"
        );
        let file = std::fs::File::open(&receipt.archive_path).unwrap();
        let dec = flate2::read::GzDecoder::new(file);
        let mut ar = tar::Archive::new(dec);
        for entry in ar.entries().unwrap() {
            let name = entry
                .unwrap()
                .path()
                .unwrap()
                .to_string_lossy()
                .into_owned();
            assert!(
                !name.starts_with(".serve.lock"),
                "archive must not contain serve lock entry: {name:?}"
            );
        }
    }
}