Skip to content

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

Rust

fix(cli): preserve backups when archive downloads fail

Rudy Celekli90147da341e8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4517043..98b797b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,9 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Fixed
+- Kept the previous backup or OKF export intact when an archive download is interrupted, and publish completed downloads atomically. Successful downloads replace destination symlinks with private files rather than changing their targets or inheriting their permissions.
+
## [3.1.1] - 2026-10-17
### Fixed
diff --git a/crates/ai-memory-cli/src/http_client.rs b/crates/ai-memory-cli/src/http_client.rs
index 59e70325..19cfeaf1 100644
--- a/crates/ai-memory-cli/src/http_client.rs
+++ b/crates/ai-memory-cli/src/http_client.rs
@@ -12,8 +12,6 @@
use std::fmt;
use std::io::{BufWriter, Write as _};
-#[cfg(unix)]
-use std::os::unix::fs::OpenOptionsExt as _;
use std::path::Path;
use std::time::Duration;
@@ -530,7 +528,11 @@ async fn probe_server_with_timeout(endpoint: &ServerEndpoint, timeout: Duration)
///
/// Intended for routes whose response is binary (e.g. `POST /admin/backup`
/// returns an `application/gzip` tarball). On non-2xx the response body is
-/// consumed and returned as an error string. Returns bytes written.
+/// consumed and returned as an error string. Returns bytes written. A completed
+/// download atomically replaces the destination path; a destination symlink is
+/// replaced rather than modifying the file it points to. Replacement symlinks
+/// and new destinations use private permissions; only existing regular files
+/// retain their permissions.
///
/// # Errors
/// Returns an error when the connection fails, the response is non-2xx,
@@ -544,9 +546,10 @@ pub async fn post_to_file(endpoint: &ServerEndpoint, path: &str, dest: &Path) ->
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
let mut resp = require_success(reqwest::Method::POST, resp).await?;
- let file = private_output_file(dest)
- .with_context(|| format!("creating output file {}", dest.display()))?;
- let mut writer = BufWriter::new(file);
+ let permissions = checked_output_permissions(dest)?;
+ let mut temporary = private_output_file(dest)
+ .with_context(|| format!("creating temporary output beside {}", dest.display()))?;
+ let mut writer = BufWriter::new(temporary.as_file_mut());
let mut written = 0_u64;
while let Some(chunk) = resp
.chunk()
@@ -561,18 +564,72 @@ pub async fn post_to_file(endpoint: &ServerEndpoint, path: &str, dest: &Path) ->
writer
.flush()
.with_context(|| format!("flushing {}", dest.display()))?;
+ drop(writer);
+ // A failed response must leave the previous archive usable. The temporary
+ // file stays private until the entire response has arrived.
+ if let Some(permissions) = permissions {
+ temporary
+ .as_file()
+ .set_permissions(permissions)
+ .with_context(|| format!("preserving permissions for {}", dest.display()))?;
+ }
+ temporary
+ .as_file()
+ .sync_all()
+ .with_context(|| format!("syncing temporary output beside {}", dest.display()))?;
+ let persisted = temporary
+ .persist(dest)
+ .map_err(|error| error.error)
+ .with_context(|| format!("replacing output file {}", dest.display()))?;
+ persisted
+ .sync_all()
+ .with_context(|| format!("syncing output file {}", dest.display()))?;
+ if let Ok(directory) = std::fs::File::open(output_parent(dest)) {
+ let _ = directory.sync_all();
+ }
Ok(written)
}
-/// Open a downloaded backup output file with private permissions before the
-/// first response bytes are written. Existing user-selected output files keep
-/// their existing permissions when overwritten.
-fn private_output_file(path: &Path) -> std::io::Result<std::fs::File> {
- let mut options = std::fs::OpenOptions::new();
- options.write(true).create(true).truncate(true);
- #[cfg(unix)]
- options.mode(0o600);
- options.open(path)
+/// Atomic replacement still requires permission to write an existing regular
+/// file. Opening without create or truncate checks OS permissions and ACLs
+/// without changing the archive before the response is complete.
+fn checked_output_permissions(dest: &Path) -> Result<Option<std::fs::Permissions>> {
+ match std::fs::symlink_metadata(dest) {
+ Ok(metadata) if metadata.file_type().is_symlink() => Ok(None),
+ Ok(metadata) if metadata.is_file() => {
+ let probe = std::fs::OpenOptions::new()
+ .write(true)
+ .open(dest)
+ .with_context(|| {
+ format!(
+ "checking output file write permission for {}",
+ dest.display()
+ )
+ })?;
+ drop(probe);
+ Ok(Some(metadata.permissions()))
+ }
+ Ok(metadata) if metadata.is_dir() => {
+ anyhow::bail!("output path is a directory: {}", dest.display());
+ }
+ Ok(_) => anyhow::bail!("output path is not a regular file: {}", dest.display()),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+ Err(error) => Err(error).context("reading output file permissions"),
+ }
+}
+
+/// Download beside the destination so publication is an atomic rename on the
+/// same filesystem. NamedTempFile removes an incomplete response on every exit.
+fn private_output_file(path: &Path) -> std::io::Result<tempfile::NamedTempFile> {
+ tempfile::Builder::new()
+ .prefix(".ai-memory-download.")
+ .tempfile_in(output_parent(path))
+}
+
+fn output_parent(path: &Path) -> &Path {
+ path.parent()
+ .filter(|parent| !parent.as_os_str().is_empty())
+ .unwrap_or_else(|| Path::new("."))
}
#[cfg(test)]
@@ -599,6 +656,19 @@ mod tests {
)));
}
+ #[test]
+ fn output_write_permission_probe_never_truncates_existing_bytes() {
+ let temp = tempfile::tempdir().unwrap();
+ let output = temp.path().join("backup.tar.gz");
+ std::fs::write(&output, b"previous usable archive").unwrap();
+ assert!(
+ super::checked_output_permissions(&output)
+ .unwrap()
+ .is_some()
+ );
+ assert_eq!(std::fs::read(&output).unwrap(), b"previous usable archive");
+ }
+
#[cfg(unix)]
#[test]
fn downloaded_backup_output_is_private_when_created() {
@@ -606,9 +676,13 @@ mod tests {
let temp = tempfile::tempdir().unwrap();
let output = temp.path().join("backup.tar.gz");
- private_output_file(&output).unwrap();
+ let temporary = private_output_file(&output).unwrap();
+ assert!(
+ !output.exists(),
+ "download is not published before completion"
+ );
assert_eq!(
- std::fs::metadata(output).unwrap().permissions().mode() & 0o777,
+ temporary.as_file().metadata().unwrap().permissions().mode() & 0o777,
0o600
);
}
diff --git a/crates/ai-memory-cli/tests/suite/backup_download.rs b/crates/ai-memory-cli/tests/suite/backup_download.rs
new file mode 100644
index 00000000..8b55a73f
--- /dev/null
+++ b/crates/ai-memory-cli/tests/suite/backup_download.rs
@@ -0,0 +1,278 @@
+//! Exercise archive download failures through the shipped CLI and a real HTTP connection.
+
+use std::io::{Read as _, Write as _};
+use std::net::{Shutdown, TcpListener};
+use std::path::Path;
+use std::process::Output;
+use std::time::{Duration, Instant};
+
+use super::e2e_support::hermetic;
+
+const BIN: &str = env!("CARGO_BIN_EXE_ai-memory");
+const BODY: &[u8] = b"complete archive bytes";
+
+fn download(home: &Path, dest: &Path, export: bool, complete: bool) -> Output {
+ let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+ let address = listener.local_addr().unwrap();
+ listener.set_nonblocking(true).unwrap();
+ let server = std::thread::spawn(move || {
+ let deadline = Instant::now() + Duration::from_secs(10);
+ let mut socket = loop {
+ match listener.accept() {
+ Ok((socket, _)) => break socket,
+ Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+ assert!(Instant::now() < deadline, "CLI never requested its archive");
+ std::thread::sleep(Duration::from_millis(10));
+ }
+ Err(error) => panic!("accepting archive request: {error}"),
+ }
+ };
+ socket
+ .set_read_timeout(Some(Duration::from_secs(10)))
+ .unwrap();
+ let mut request = Vec::new();
+ while !request.ends_with(b"\r\n\r\n") {
+ let mut byte = [0];
+ socket.read_exact(&mut byte).unwrap();
+ request.push(byte[0]);
+ }
+ let request = String::from_utf8(request).unwrap();
+ assert!(
+ request.starts_with(if export {
+ "POST /admin/export-okf?"
+ } else {
+ "POST /admin/backup "
+ }),
+ "{request}"
+ );
+ let length = if complete {
+ BODY.len()
+ } else {
+ BODY.len() + 100
+ };
+ let mut response =
+ format!("HTTP/1.1 200 OK\r\nContent-Length: {length}\r\nConnection: close\r\n\r\n")
+ .into_bytes();
+ response.extend_from_slice(BODY);
+ socket.write_all(&response).unwrap();
+ socket.shutdown(Shutdown::Write).unwrap();
+ });
+ let mut command = hermetic(BIN);
+ command
+ .current_dir(home)
+ .env("HOME", home)
+ .env("USERPROFILE", home)
+ .env("AI_MEMORY_SERVER_URL", format!("http://{address}"))
+ .arg("--data-dir")
+ .arg(home.join("data"));
+ if export {
+ command.args(["export-okf", "--project", "archive-fixture"]);
+ } else {
+ command.arg("backup");
+ }
+ let output = command.arg("--to").arg(dest).output().unwrap();
+ server.join().unwrap();
+ output
+}
+
+#[test]
+fn interrupted_archive_download_preserves_previous_output() {
+ assert_interrupted_download(true);
+}
+
+#[test]
+fn interrupted_archive_download_leaves_no_partial_output() {
+ assert_interrupted_download(false);
+}
+
+fn assert_interrupted_download(existing: bool) {
+ for export in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let archives = home.path().join("archives");
+ std::fs::create_dir(&archives).unwrap();
+ let dest = archives.join("backup.tar.gz");
+ if existing {
+ std::fs::write(&dest, b"previous usable archive").unwrap();
+ }
+ let output = download(home.path(), &dest, export, false);
+ assert!(!output.status.success(), "truncated HTTP body must fail");
+ assert!(
+ String::from_utf8_lossy(&output.stderr).contains("reading response chunk"),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ if existing {
+ assert_eq!(std::fs::read(&dest).unwrap(), b"previous usable archive");
+ } else {
+ assert!(
+ !dest.exists(),
+ "failed download must not publish a partial archive"
+ );
+ }
+ let names: Vec<_> = std::fs::read_dir(&archives)
+ .unwrap()
+ .map(|entry| entry.unwrap().file_name())
+ .collect();
+ assert_eq!(
+ names.len(),
+ usize::from(existing),
+ "temporary archive leaked: {names:?}"
+ );
+ }
+}
+
+#[test]
+fn successful_archive_download_replaces_output_and_preserves_permissions() {
+ for export in [false, true] {
+ for existing in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let dest = home.path().join("backup.tar.gz");
+ if existing {
+ std::fs::write(&dest, b"previous usable archive").unwrap();
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt as _;
+ std::fs::set_permissions(&dest, std::fs::Permissions::from_mode(0o640))
+ .unwrap();
+ }
+ }
+ let output = download(home.path(), &dest, export, true);
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ assert_eq!(std::fs::read(&dest).unwrap(), BODY);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt as _;
+ assert_eq!(
+ std::fs::metadata(&dest).unwrap().permissions().mode() & 0o777,
+ if existing { 0o640 } else { 0o600 }
+ );
+ }
+ }
+ }
+}
+
+#[cfg(unix)]
+#[test]
+fn successful_archive_download_replaces_a_symlink_privately_without_altering_its_target() {
+ use std::os::unix::fs::{PermissionsExt as _, symlink};
+ for export in [false, true] {
+ for directory_target in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let target = home.path().join("previous");
+ let dest = home.path().join("backup.tar.gz");
+ if directory_target {
+ std::fs::create_dir(&target).unwrap();
+ std::fs::write(target.join("keep"), b"untouched directory").unwrap();
+ } else {
+ std::fs::write(&target, b"previous usable archive").unwrap();
+ }
+ let mode = if directory_target { 0o755 } else { 0o644 };
+ std::fs::set_permissions(&target, std::fs::Permissions::from_mode(mode)).unwrap();
+ symlink(&target, &dest).unwrap();
+ let output = download(home.path(), &dest, export, true);
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ assert!(
+ !std::fs::symlink_metadata(&dest)
+ .unwrap()
+ .file_type()
+ .is_symlink()
+ );
+ assert_eq!(std::fs::read(&dest).unwrap(), BODY);
+ assert_eq!(
+ std::fs::metadata(&dest).unwrap().permissions().mode() & 0o777,
+ 0o600
+ );
+ assert_eq!(
+ std::fs::metadata(&target).unwrap().permissions().mode() & 0o777,
+ mode
+ );
+ if directory_target {
+ assert_eq!(
+ std::fs::read(target.join("keep")).unwrap(),
+ b"untouched directory"
+ );
+ } else {
+ assert_eq!(std::fs::read(&target).unwrap(), b"previous usable archive");
+ }
+ }
+ }
+}
+
+#[test]
+fn archive_download_refuses_a_directory_without_creating_a_temporary_output() {
+ for export in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let archives = home.path().join("archives");
+ std::fs::create_dir(&archives).unwrap();
+ let dest = archives.join("backup.tar.gz");
+ std::fs::create_dir(&dest).unwrap();
+ std::fs::write(dest.join("keep"), b"untouched directory").unwrap();
+ let output = download(home.path(), &dest, export, true);
+ assert!(!output.status.success());
+ assert!(String::from_utf8_lossy(&output.stderr).contains("output path is a directory"));
+ assert_eq!(
+ std::fs::read(dest.join("keep")).unwrap(),
+ b"untouched directory"
+ );
+ assert_eq!(std::fs::read_dir(&archives).unwrap().count(), 1);
+ }
+}
+
+#[cfg(unix)]
+#[test]
+fn archive_download_refuses_a_read_only_regular_file_without_touching_it() {
+ use std::os::unix::fs::PermissionsExt as _;
+ for export in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let archives = home.path().join("archives");
+ std::fs::create_dir(&archives).unwrap();
+ let dest = archives.join("backup.tar.gz");
+ std::fs::write(&dest, b"previous usable archive").unwrap();
+ std::fs::set_permissions(&dest, std::fs::Permissions::from_mode(0o400)).unwrap();
+ let output = download(home.path(), &dest, export, true);
+ assert!(!output.status.success());
+ assert!(
+ String::from_utf8_lossy(&output.stderr)
+ .contains("checking output file write permission")
+ );
+ assert_eq!(std::fs::read(&dest).unwrap(), b"previous usable archive");
+ assert_eq!(
+ std::fs::metadata(&dest).unwrap().permissions().mode() & 0o777,
+ 0o400
+ );
+ assert_eq!(std::fs::read_dir(&archives).unwrap().count(), 1);
+ }
+}
+
+#[cfg(unix)]
+#[test]
+fn interrupted_archive_download_preserves_the_destination_symlink_and_target() {
+ use std::os::unix::fs::symlink;
+ for export in [false, true] {
+ let home = tempfile::tempdir().unwrap();
+ let archives = home.path().join("archives");
+ std::fs::create_dir(&archives).unwrap();
+ let target = home.path().join("previous.tar.gz");
+ let dest = archives.join("backup.tar.gz");
+ std::fs::write(&target, b"previous usable archive").unwrap();
+ symlink(&target, &dest).unwrap();
+ let output = download(home.path(), &dest, export, false);
+ assert!(!output.status.success());
+ assert!(
+ std::fs::symlink_metadata(&dest)
+ .unwrap()
+ .file_type()
+ .is_symlink()
+ );
+ assert_eq!(std::fs::read(&target).unwrap(), b"previous usable archive");
+ assert_eq!(std::fs::read_dir(&archives).unwrap().count(), 1);
+ }
+}
diff --git a/crates/ai-memory-cli/tests/suite/main.rs b/crates/ai-memory-cli/tests/suite/main.rs
index dd310c88..b99afe4e 100644
--- a/crates/ai-memory-cli/tests/suite/main.rs
+++ b/crates/ai-memory-cli/tests/suite/main.rs
@@ -12,6 +12,7 @@ mod backfill_e2e;
mod backfill_failures;
mod backfill_member;
mod backup_agents;
+mod backup_download;
mod completions;
mod cross_origin_e2e;
mod doctor_e2e;
diff --git a/docs/okf.md b/docs/okf.md
index 3e0da10d..a360c1da 100644
--- a/docs/okf.md
+++ b/docs/okf.md
@@ -18,6 +18,12 @@ standardized. The files are greppable, open in Obsidian, and import into
anything OKF-aware. Nothing is locked in: the export is a validated copy of
the files ai-memory already stores its memory in.
+Backup and OKF export downloads replace their output only after the whole
+response arrives. An interrupted download keeps the previous archive intact.
+New files and replacement symlinks are private; existing regular files keep
+their permissions and still require write access. Read-only files and
+directory destinations are refused. A symlink target is never changed.
+
The rest of this page is the design: how conformance is enforced and
how existing stores migrate.