Skip to content

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

Rust

fix(web): hash the whole page response into its ETag

kevin9327dbb1dd05ecbf
diff --git a/crates/ai-memory-web/src/routes/api.rs b/crates/ai-memory-web/src/routes/api.rs
index ec9900ca..d2aaa922 100644
--- a/crates/ai-memory-web/src/routes/api.rs
+++ b/crates/ai-memory-web/src/routes/api.rs
@@ -189,25 +189,38 @@ async fn page_handler(
.read_page(meta.workspace_id, meta.project_id, &page_path)
.map_err(|_| not_found("page file not found"))?;
- // ETag is computed over the markdown body PLUS the resolved author
- // identity (P1.7). Author change without body change (e.g. operator
- // rotates a token then user A re-writes a previously-anonymous page)
- // must invalidate the cached response. SHA-256 over a stable
- // concatenation: body || "\n--\n" || username || "\n" || email.
- // The "\n--\n" separator prevents `body=foo, user=bar` from hashing
- // the same as `body=foobar, user=` if either ever happened to slide
- // empty.
- let mut hasher = Sha256::new();
- hasher.update(markdown.body.as_bytes());
- if let Some(author) = meta.author.as_ref() {
- hasher.update(b"\n--\n");
- hasher.update(author.username.as_bytes());
- hasher.update(b"\n");
- if let Some(email) = author.email.as_deref() {
- hasher.update(email.as_bytes());
- }
- }
- let digest = hasher.finalize();
+ let links = state
+ .reader
+ .page_links(meta.workspace_id, meta.project_id, meta.path.clone())
+ .await
+ .map_err(internal_error)?;
+
+ let page = ApiPage {
+ backlinks: links.backlinks,
+ body_markdown: markdown.body,
+ created_at: meta.created_at,
+ frontmatter: markdown.frontmatter,
+ kind: meta.kind,
+ links: links.links,
+ path: meta.path,
+ pinned: meta.pinned,
+ project: meta.project_name,
+ supersedes: meta.supersedes,
+ tier: meta.tier,
+ title: meta.title,
+ updated_at: meta.updated_at,
+ workspace: meta.workspace_name,
+ author: meta.author,
+ };
+ let json = serde_json::to_vec(&page).map_err(internal_error)?;
+
+ // The ETag is a SHA-256 of the JSON this route returns, so it changes
+ // whenever any of it does. It used to cover only the markdown body and
+ // the author (P1.7), but pinning a page, re-tiering or retitling it in
+ // frontmatter, and another page linking to it all change the response
+ // while the body stays byte-identical, and a client revalidating with
+ // the old tag was told 304 and kept the stale page.
+ let digest = Sha256::digest(&json);
let etag_hex = digest.iter().fold(String::with_capacity(64), |mut s, b| {
use std::fmt::Write as _;
let _ = write!(s, "{b:02x}");
@@ -217,7 +230,7 @@ async fn page_handler(
let etag_header = HeaderValue::from_str(&etag_value).expect("sha256 hex is always valid ASCII");
// If-None-Match: if the client sends back the exact ETag we issued,
- // return 304 with no body (no re-serialisation needed).
+ // return 304 with no body.
if let Some(inm) = headers
.get(header::IF_NONE_MATCH)
.and_then(|v| v.to_str().ok())
@@ -234,31 +247,15 @@ async fn page_handler(
return Ok(resp);
}
- let links = state
- .reader
- .page_links(meta.workspace_id, meta.project_id, meta.path.clone())
- .await
- .map_err(internal_error)?;
-
let mut resp = with_cache(
- Json(ApiPage {
- backlinks: links.backlinks,
- body_markdown: markdown.body,
- created_at: meta.created_at,
- frontmatter: markdown.frontmatter,
- kind: meta.kind,
- links: links.links,
- path: meta.path,
- pinned: meta.pinned,
- project: meta.project_name,
- supersedes: meta.supersedes,
- tier: meta.tier,
- title: meta.title,
- updated_at: meta.updated_at,
- workspace: meta.workspace_name,
- author: meta.author,
- })
- .into_response(),
+ (
+ [(
+ header::CONTENT_TYPE,
+ HeaderValue::from_static("application/json"),
+ )],
+ json,
+ )
+ .into_response(),
PAGE_CACHE_MAX_AGE,
);
resp.headers_mut().insert(header::ETAG, etag_header);
diff --git a/crates/ai-memory-web/tests/suite/routes.rs b/crates/ai-memory-web/tests/suite/routes.rs
index d87e6248..3bf6ba61 100644
--- a/crates/ai-memory-web/tests/suite/routes.rs
+++ b/crates/ai-memory-web/tests/suite/routes.rs
@@ -2661,6 +2661,76 @@ async fn api_page_handler_emits_etag_and_supports_if_none_match() {
assert!(body_bytes.is_empty(), "304 body must be empty");
}
+/// The ETag stands for the whole JSON page, not just its markdown. Pinning a
+/// page, retitling it in frontmatter, or another page linking to it changes
+/// what the route returns while the body stays byte-identical; a client that
+/// revalidated with the old tag was told 304 and kept the stale page.
+#[tokio::test]
+async fn api_page_etag_changes_when_metadata_or_backlinks_change_but_body_does_not() {
+ let (_tmp, store, wiki) = setup().await;
+ let ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "scratch", None)
+ .await
+ .unwrap();
+ let body = "# Deploy\n\nTag before pushing.";
+ wiki.write_page(wiki_req(ws, proj, "deploy.md", body))
+ .await
+ .unwrap();
+ let app = api_router(store.reader.clone(), wiki.clone());
+ let uri = "/workspaces/default/projects/scratch/pages/deploy.md";
+ let fetch = |etag: Option<String>| {
+ let app = app.clone();
+ async move {
+ let mut req = Request::builder().uri(uri);
+ if let Some(etag) = etag {
+ req = req.header(header::IF_NONE_MATCH, etag);
+ }
+ app.oneshot(req.body(Body::empty()).unwrap()).await.unwrap()
+ }
+ };
+ let first = fetch(None).await;
+ let etag = first.headers()[header::ETAG].to_str().unwrap().to_owned();
+ assert_eq!(
+ fetch(Some(etag.clone())).await.status(),
+ StatusCode::NOT_MODIFIED,
+ "an unchanged page still revalidates"
+ );
+
+ // Same body, now pinned.
+ let mut pinned = wiki_req(ws, proj, "deploy.md", body);
+ pinned.pinned = true;
+ wiki.write_page(pinned).await.unwrap();
+ let resp = fetch(Some(etag.clone())).await;
+ assert_eq!(
+ resp.status(),
+ StatusCode::OK,
+ "pinning must invalidate the ETag"
+ );
+ assert_eq!(json_body(resp).await["pinned"], true);
+ let etag = fetch(None).await.headers()[header::ETAG]
+ .to_str()
+ .unwrap()
+ .to_owned();
+
+ // Same body, but another page now links here.
+ wiki.write_page(wiki_req(ws, proj, "release.md", "See [[deploy]] first."))
+ .await
+ .unwrap();
+ let resp = fetch(Some(etag)).await;
+ assert_eq!(
+ resp.status(),
+ StatusCode::OK,
+ "a new backlink must invalidate the ETag"
+ );
+ assert_eq!(json_body(resp).await["backlinks"][0]["path"], "release.md");
+}
+
#[tokio::test]
async fn api_page_handler_etag_differs_per_page() {
let (_tmp, store, wiki) = setup().await;