rusty-agent-server 0.12.0

The durable agent runtime built in Rust — HTTP/SSE server: an Agent-Protocol subset with threads, background runs, checkpoints, and resumable streaming.
Documentation
//! JSON-file persistence for Flight Recorder journal snapshots.
//!
//! One file per run at `{store_path}/journals/{run_id}.json`, rewritten as
//! the run's journal grows (once per checkpoint boundary and once at run
//! completion). The run id is server-minted (UUID v4), never client-chosen,
//! so no id validation is needed at this layer. Writes are atomic
//! (temp file + rename), mirroring the checkpointer's durability discipline.

use std::io;
use std::path::{Path, PathBuf};

use rusty_agent_runtime::journal::JournalSnapshot;

/// The journals directory under the store root. `journals` is a reserved
/// layout name (see [`crate::RESERVED_NAMES`]): client-chosen thread ids may
/// not claim it.
pub(crate) fn dir(root: &Path) -> PathBuf {
    root.join("journals")
}

/// Persist `snapshot`, replacing any earlier snapshot of the same run.
pub(crate) async fn persist(root: &Path, snapshot: &JournalSnapshot) -> io::Result<()> {
    let dir = dir(root);
    tokio::fs::create_dir_all(&dir).await?;
    let bytes = serde_json::to_vec_pretty(snapshot)
        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
    let path = dir.join(format!("{}.json", snapshot.run_id));
    // Unique temp name per write: two concurrent persists of the same
    // journal (a settlement hook racing a reconcile-on-read, say) must
    // not share a temp file — the loser's rename would find its temp
    // gone and surface ENOENT as a 500. The rename onto `path` stays
    // atomic, so crash-safety is unchanged; last writer wins.
    let tmp = dir.join(format!(".{}.{}.tmp", snapshot.run_id, uuid::Uuid::new_v4()));
    tokio::fs::write(&tmp, bytes).await?;
    tokio::fs::rename(&tmp, path).await
}

/// Load the snapshot stored for `run_id`; `None` when none was persisted
/// (a queued run, or one that failed before its first checkpoint boundary).
pub(crate) async fn get(root: &Path, run_id: &str) -> io::Result<Option<JournalSnapshot>> {
    let path = dir(root).join(format!("{run_id}.json"));
    let bytes = match tokio::fs::read(&path).await {
        Ok(bytes) => bytes,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };
    let snapshot = serde_json::from_slice(&bytes)
        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
    Ok(Some(snapshot))
}

/// Load every persisted snapshot, in file-name (run-id) order. A file
/// that fails to parse is skipped with a warning rather than failing the
/// listing — the health board reads journals to *derive* state, and one
/// corrupt file must not blind it to everything else (the corrupt file's
/// own read path still surfaces the error).
pub(crate) async fn list(root: &Path) -> io::Result<Vec<JournalSnapshot>> {
    let dir = dir(root);
    let mut entries = match tokio::fs::read_dir(&dir).await {
        Ok(entries) => entries,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(e),
    };
    let mut snapshots: Vec<JournalSnapshot> = Vec::new();
    while let Some(entry) = entries.next_entry().await? {
        let name = entry.file_name().to_string_lossy().into_owned();
        if !name.ends_with(".json") || name.starts_with('.') {
            continue;
        }
        let bytes = tokio::fs::read(entry.path()).await?;
        match serde_json::from_slice::<JournalSnapshot>(&bytes) {
            Ok(snapshot) => snapshots.push(snapshot),
            Err(e) => tracing::warn!("skipping unparsable journal file {name}: {e}"),
        }
    }
    snapshots.sort_by(|a, b| a.run_id.cmp(&b.run_id));
    Ok(snapshots)
}

#[cfg(test)]
mod tests {
    use super::*;
    use rusty_agent_runtime::journal::{Clock, EventDraft, Journal};
    use rusty_agent_runtime::record::{Effect, RunEventKind};

    #[tokio::test]
    async fn persist_then_get_round_trips_the_snapshot() {
        let root =
            std::env::temp_dir().join(format!("rusty-journals-test-{}", uuid::Uuid::new_v4()));
        let journal = Journal::new("run-1", "thread-1", Clock::System);
        journal.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
        journal.record(
            EventDraft::new(RunEventKind::CheckpointWritten, Effect::Pure).parent("run-1:0"),
        );

        persist(&root, &journal.snapshot()).await.unwrap();
        let loaded = get(&root, "run-1")
            .await
            .unwrap()
            .expect("snapshot persisted");
        assert_eq!(loaded.run_id, "run-1");
        assert_eq!(loaded.events.len(), 2);
        assert_eq!(loaded.head_hash, journal.head_hash());

        // A later snapshot of the same run replaces the earlier file.
        journal.record(EventDraft::new(RunEventKind::SuperStepEnd, Effect::Pure));
        persist(&root, &journal.snapshot()).await.unwrap();
        let loaded = get(&root, "run-1")
            .await
            .unwrap()
            .expect("snapshot persisted");
        assert_eq!(loaded.events.len(), 3);

        assert!(get(&root, "never-written").await.unwrap().is_none());
        let _ = std::fs::remove_dir_all(root);
    }

    #[tokio::test]
    async fn concurrent_persists_of_one_journal_never_race_on_the_temp_file() {
        let root =
            std::env::temp_dir().join(format!("rusty-journals-test-{}", uuid::Uuid::new_v4()));
        let journal = Journal::new("run-1", "thread-1", Clock::System);
        journal.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
        let snapshot = journal.snapshot();

        // A settlement hook and a reconcile-on-read can persist the same
        // journal in the same instant; a shared temp path made the loser
        // fail with ENOENT. Every writer must succeed; last writer wins.
        let mut writers = tokio::task::JoinSet::new();
        for _ in 0..8 {
            let root = root.clone();
            let snapshot = snapshot.clone();
            writers.spawn(async move { persist(&root, &snapshot).await });
        }
        while let Some(outcome) = writers.join_next().await {
            outcome.expect("writer joined").expect("persist succeeds");
        }
        let loaded = get(&root, "run-1")
            .await
            .unwrap()
            .expect("snapshot persisted");
        assert_eq!(loaded.head_hash, snapshot.head_hash);
        // No temp files survive a completed write.
        let leftovers = std::fs::read_dir(dir(&root))
            .unwrap()
            .filter_map(|e| e.ok())
            .filter(|e| e.file_name().to_string_lossy().ends_with(".tmp"))
            .count();
        assert_eq!(leftovers, 0);
        let _ = std::fs::remove_dir_all(root);
    }
}