Skip to content

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

Rust

feat(admission): non-blocking webhooks (blocking=false, fire-and-forget)

Djalma Júniorca114e672432
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 52af6286..3df3c76c 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -2166,6 +2166,7 @@ mod tests {
timeout_ms: 2_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage, AdmissionOp::PurgeProject],
+ blocking: true,
}])
.unwrap();
let wiki = Wiki::new(tmp.path(), store.writer.clone())
diff --git a/crates/ai-memory-wiki/src/admission.rs b/crates/ai-memory-wiki/src/admission.rs
index 4bd71fb5..33fd8a49 100644
--- a/crates/ai-memory-wiki/src/admission.rs
+++ b/crates/ai-memory-wiki/src/admission.rs
@@ -87,6 +87,10 @@ fn default_timeout_ms() -> u64 {
2_000
}
+fn default_blocking() -> bool {
+ true
+}
+
/// One webhook entry in the chain. Loaded from operator config
/// (`[[admission_webhooks]]`).
#[derive(Debug, Clone, Serialize, Deserialize)]
@@ -104,6 +108,15 @@ pub struct WebhookConfig {
/// Subset of [`AdmissionOp`] this webhook subscribes to. If empty,
/// the webhook is effectively disabled (it'll never fire).
pub events: Vec<AdmissionOp>,
+ /// When `true` (default), the webhook runs **synchronously** inside the
+ /// write path — it can mutate the page (`run`) and a `Reject` failure
+ /// aborts the write. When `false`, it's dispatched **fire-and-forget**
+ /// AFTER the page has landed: the engine doesn't wait for it and ignores
+ /// its response (so it can't mutate or reject). Use `false` for pure
+ /// observers/mirrors (e.g. `git-mirror`) so a slow/down backup never adds
+ /// latency to writes.
+ #[serde(default = "default_blocking")]
+ pub blocking: bool,
}
/// Per-write context passed to each webhook. Cheap to construct
@@ -243,6 +256,12 @@ impl AdmissionChain {
if !hook.events.contains(&ctx.op) {
continue;
}
+ // Non-blocking webhooks are fired fire-and-forget after the write
+ // (see `dispatch_async`); they never run in the synchronous,
+ // mutation-capable path.
+ if !hook.blocking {
+ continue;
+ }
let payload = WebhookRequestBody {
page: WebhookPagePayload {
@@ -356,6 +375,9 @@ impl AdmissionChain {
if !hook.events.contains(&ctx.op) {
continue;
}
+ if !hook.blocking {
+ continue;
+ }
let payload = WebhookRequestBody {
page: WebhookPagePayload {
path: page_path.unwrap_or(""),
@@ -400,6 +422,69 @@ impl AdmissionChain {
}
Ok(())
}
+
+ /// Fire the chain's **non-blocking** webhooks for this op WITHOUT awaiting
+ /// them. Called AFTER the page has landed on disk + in the index, so these
+ /// are pure observers/mirrors: each is spawned fire-and-forget and its
+ /// response is ignored (a non-blocking webhook can't mutate or reject).
+ /// Honours the skip-list and op-subscription. For a write the caller passes
+ /// the FINAL (post-mutation) page; for a delete/purge, an empty body.
+ pub fn dispatch_async(
+ &self,
+ page_path: Option<&str>,
+ frontmatter: &serde_json::Value,
+ body: &str,
+ ctx: &AdmissionContext,
+ ) {
+ for hook in self.webhooks.iter() {
+ if hook.blocking {
+ continue;
+ }
+ if ctx.skip_webhooks.iter().any(|n| n == &hook.name) {
+ continue;
+ }
+ if !hook.events.contains(&ctx.op) {
+ continue;
+ }
+ let client = self.client.clone();
+ let url = hook.url.clone();
+ let name = hook.name.clone();
+ let timeout = hook.timeout_ms;
+ let op = ctx.op;
+ let owned_ctx = ctx.clone();
+ let path = page_path.map(str::to_string);
+ let frontmatter = frontmatter.clone();
+ let body = body.to_string();
+ tokio::spawn(async move {
+ let payload = WebhookRequestBody {
+ page: WebhookPagePayload {
+ path: path.as_deref().unwrap_or(""),
+ frontmatter: &frontmatter,
+ body: &body,
+ },
+ ctx: &owned_ctx,
+ };
+ match client
+ .post(&url)
+ .header("X-Memory-Op", op.as_header_value())
+ .timeout(Duration::from_millis(timeout))
+ .json(&payload)
+ .send()
+ .await
+ {
+ Ok(resp) if resp.status().is_success() => {
+ tracing::debug!(webhook = %name, op = op.as_header_value(), "admission async ok");
+ }
+ Ok(resp) => {
+ tracing::warn!(webhook = %name, status = %resp.status(), "admission async error response");
+ }
+ Err(e) => {
+ tracing::warn!(webhook = %name, error = %e, "admission async request failed");
+ }
+ }
+ });
+ }
+ }
}
#[cfg(test)]
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 47a7661b..efd42bbf 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -238,6 +238,7 @@ impl Wiki {
self.resolve_admission_names(workspace_id, project_id, &mut ctx)
.await;
chain.notify(Some(path.as_str()), &ctx).await?;
+ chain.dispatch_async(Some(path.as_str()), &serde_json::Value::Null, "", &ctx);
}
let abs = self.abs_path(workspace_id, project_id, path);
match std::fs::remove_file(&abs) {
@@ -274,6 +275,7 @@ impl Wiki {
self.resolve_admission_names(workspace_id, project_id, &mut ctx)
.await;
chain.notify(None, &ctx).await?;
+ chain.dispatch_async(None, &serde_json::Value::Null, "", &ctx);
}
let root = self.project_root(workspace_id, project_id);
match std::fs::remove_dir_all(&root) {
@@ -447,7 +449,7 @@ impl Wiki {
// frontmatter/body here propagate to both the on-disk markdown
// (via emit below) and the store's `frontmatter_json` / `body`
// (via the upsert below) atomically. See `crate::admission`.
- if let Some(chain) = &self.admission_chain {
+ let resolved_ctx = if let Some(chain) = &self.admission_chain {
let mut ctx = admission_ctx.unwrap_or_default();
// Single identity source: the webhook actor is the same
// `ActorContext` used for on-disk attribution (req.actor),
@@ -471,8 +473,12 @@ impl Wiki {
ctx.project = name;
}
}
+ // Blocking webhooks run synchronously (they may mutate / reject).
chain.run(&path, &mut markdown, &ctx).await?;
- }
+ Some(ctx)
+ } else {
+ None
+ };
// Re-derive title + links from the (possibly mutated) markdown.
// We do this after the chain so explicit title overrides survive
@@ -491,6 +497,18 @@ impl Wiki {
}
atomic::write_atomic(&abs, emitted.as_bytes())?;
+ // Non-blocking webhooks fire-and-forget AFTER the page has landed on
+ // disk (the markdown-in-git source of truth). They only observe/mirror
+ // the final page — never block the write or mutate it.
+ if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
+ chain.dispatch_async(
+ Some(path.as_str()),
+ &markdown.frontmatter,
+ &markdown.body,
+ ctx,
+ );
+ }
+
let Markdown {
frontmatter: final_frontmatter,
body: final_body,
@@ -1030,6 +1048,7 @@ mod tests {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
diff --git a/crates/ai-memory-wiki/tests/admission.rs b/crates/ai-memory-wiki/tests/admission.rs
index 8a868ed2..79e3d901 100644
--- a/crates/ai-memory-wiki/tests/admission.rs
+++ b/crates/ai-memory-wiki/tests/admission.rs
@@ -71,6 +71,7 @@ async fn webhook_mutating_frontmatter_is_applied() {
timeout_ms: 2_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -96,6 +97,7 @@ async fn webhook_204_is_noop() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -123,6 +125,7 @@ async fn failure_policy_ignore_swallows_error() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -150,6 +153,7 @@ async fn failure_policy_reject_aborts_write() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Reject,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -184,6 +188,7 @@ async fn skip_webhooks_short_circuits_named_hook() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -221,6 +226,7 @@ async fn op_filter_skips_webhook_not_subscribed_to_event() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::Consolidate],
+ blocking: true,
}])
.unwrap();
@@ -274,6 +280,7 @@ async fn chain_runs_in_order_each_sees_previous_mutation() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
},
WebhookConfig {
name: "second".into(),
@@ -281,6 +288,7 @@ async fn chain_runs_in_order_each_sees_previous_mutation() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
},
])
.unwrap();
@@ -324,6 +332,7 @@ async fn x_memory_op_header_is_sent() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::Consolidate],
+ blocking: true,
}])
.unwrap();
@@ -358,6 +367,7 @@ async fn actor_context_is_propagated_in_payload() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -401,6 +411,7 @@ async fn webhook_can_mutate_body_too() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -426,6 +437,7 @@ async fn chain_rejects_more_than_max_admission_webhooks() {
timeout_ms: 100,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
})
.collect();
let err = AdmissionChain::new(too_many).expect_err("should refuse");
@@ -456,6 +468,7 @@ async fn oversized_response_is_treated_as_noop() {
timeout_ms: 5_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -494,6 +507,7 @@ async fn workspace_and_project_names_propagate_in_payload() {
timeout_ms: 1_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -540,6 +554,7 @@ async fn notify_delete_sends_op_and_path() {
timeout_ms: 2_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::Delete],
+ blocking: true,
}])
.unwrap();
@@ -565,6 +580,7 @@ async fn notify_purge_has_op_and_no_path() {
timeout_ms: 2_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::PurgeProject],
+ blocking: true,
}])
.unwrap();
@@ -592,6 +608,7 @@ async fn notify_respects_op_subscription() {
timeout_ms: 2_000,
failure_policy: FailurePolicy::Ignore,
events: vec![AdmissionOp::WritePage],
+ blocking: true,
}])
.unwrap();
@@ -606,3 +623,63 @@ async fn notify_respects_op_subscription() {
"delete must not reach a write-only webhook"
);
}
+
+#[tokio::test]
+async fn non_blocking_webhook_skipped_by_run_but_dispatched_async() {
+ // A `blocking: false` webhook must NOT run in the synchronous `run`
+ // path (it can't mutate/reject and shouldn't add write latency), and
+ // MUST fire via `dispatch_async` after the page has landed.
+ let fired = Arc::new(AtomicBool::new(false));
+ let fired_in_handler = fired.clone();
+ let app = Router::new().route(
+ "/sync",
+ post(move || {
+ let fired = fired_in_handler.clone();
+ async move {
+ fired.store(true, Ordering::SeqCst);
+ StatusCode::NO_CONTENT
+ }
+ }),
+ );
+ let base = spawn_server(app).await;
+ let chain = AdmissionChain::new(vec![WebhookConfig {
+ name: "mirror".into(),
+ url: format!("{base}/sync"),
+ timeout_ms: 1_000,
+ failure_policy: FailurePolicy::Ignore,
+ events: vec![AdmissionOp::WritePage],
+ blocking: false,
+ }])
+ .unwrap();
+
+ let (path, mut md) = page();
+
+ // run() must NOT fire a non-blocking webhook.
+ chain
+ .run(&path, &mut md, &AdmissionContext::default())
+ .await
+ .unwrap();
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ assert!(
+ !fired.load(Ordering::SeqCst),
+ "run() must skip a non-blocking webhook"
+ );
+
+ // dispatch_async fires it (fire-and-forget; poll for the spawned task).
+ chain.dispatch_async(
+ Some(path.as_str()),
+ &md.frontmatter,
+ &md.body,
+ &AdmissionContext::default(),
+ );
+ for _ in 0..40 {
+ if fired.load(Ordering::SeqCst) {
+ break;
+ }
+ tokio::time::sleep(Duration::from_millis(25)).await;
+ }
+ assert!(
+ fired.load(Ordering::SeqCst),
+ "dispatch_async must fire the non-blocking webhook"
+ );
+}
diff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.md
index c013c740..1ee37e38 100644
--- a/docs/admission-webhooks.md
+++ b/docs/admission-webhooks.md
@@ -187,15 +187,34 @@ url = "http://contributors.memory.svc.cluster.local:8080/enrich"
timeout_ms = 2000 # per request
failure_policy = "ignore" # ignore | reject
events = ["write_page", "consolidate"]
+blocking = true # runs synchronously; may mutate / reject
[[admission_webhooks]]
name = "git-mirror"
url = "http://git-mirror.memory.svc.cluster.local:8080/sync"
timeout_ms = 2000
failure_policy = "ignore"
-events = ["write_page", "consolidate"]
+events = ["write_page", "consolidate", "delete", "purge_project"]
+blocking = false # fire-and-forget after the write; never blocks it
```
+### `blocking` (default `true`)
+
+A webhook is either **blocking** or **non-blocking**:
+
+- **`blocking = true`** (default) — runs *synchronously* inside the write path.
+ It can mutate the page (`write_page`/`consolidate`), and a `reject` failure
+ aborts the write. The write waits for it (up to `timeout_ms`). Use for
+ enrichers/validators (e.g. `contributors`, `validate-no-secrets`).
+- **`blocking = false`** — dispatched *fire-and-forget* **after** the page has
+ landed on disk. The engine does not wait for it and ignores its response, so
+ it **cannot mutate or reject** — it only observes/mirrors the final page. Use
+ for pure backups/mirrors (e.g. `git-mirror`) so a slow or down sink never adds
+ latency to writes. Still honours `events` and the skip list.
+
+Since the blocking chain is sequential, total worst-case write latency is
+`Σ timeout_ms` over the **blocking** webhooks only; non-blocking ones add none.
+
Env override (figment env layer):
```bash