Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(api): POST /{index}/_cache/clear releases the index's rebuildable caches (#950) (#1009)

Vincenzo Lombardoa13d5eea98fa
diff --git a/engine/crates/xerj-api/src/es_compat.rs b/engine/crates/xerj-api/src/es_compat.rs
index 9bbe1d331..8f9e4acbe 100644
--- a/engine/crates/xerj-api/src/es_compat.rs
+++ b/engine/crates/xerj-api/src/es_compat.rs
@@ -29261,7 +29261,7 @@ pub async fn get_tasks(State(state): State<AppState>) -> impl IntoResponse {
}
// ─────────────────────────────────────────────────────────────────────────────
-// POST /{index}/_cache/clear — clear cache stub
+// POST /{index}/_cache/clear — release the index's rebuildable caches
// ─────────────────────────────────────────────────────────────────────────────
pub async fn clear_cache(
@@ -29269,14 +29269,19 @@ pub async fn clear_cache(
Path(index): Path<String>,
) -> impl IntoResponse {
// Resolve wildcard/comma/_all specs to every matching index (404 only
- // when a literal name doesn't exist). xerj has no separately-addressable
- // field/query cache to purge, so there is nothing to clear — but we
- // still report an honest _shards block sized to what actually matched.
+ // when a literal name doesn't exist). Clearing flushes each index and
+ // releases its hydrated per-segment caches (#950); the next read
+ // re-hydrates from disk, so this is a memory lever, never a data change.
let index = strip_remote_cluster_prefix(&index);
let handles = match resolve_indices_for_op(&state, &index).await {
Ok(h) => h,
Err(e) => return ApiError::new(e).into_response(),
};
+ let indices: Vec<_> = handles
+ .iter()
+ .map(|(_, idx)| std::sync::Arc::clone(idx))
+ .collect();
+ state.engine.release_rebuildable_memory(&indices).await;
let n = handles.len() as u32;
Json(json!({
"_shards": { "total": n, "successful": n, "failed": 0 }
diff --git a/engine/crates/xerj-api/tests/cache_clear_releases_memory.rs b/engine/crates/xerj-api/tests/cache_clear_releases_memory.rs
new file mode 100644
index 000000000..a727e2e06
--- /dev/null
+++ b/engine/crates/xerj-api/tests/cache_clear_releases_memory.rs
@@ -0,0 +1,110 @@
+//! Issue #950: `POST /{index}/_cache/clear` was a stub — it resolved the
+//! indices and reported an honest `_shards` block but freed nothing, so the
+//! one operator lever for a node pinned above its memory watermark was not
+//! connected to `Index::release_memory`. It must flush, release the hydrated
+//! per-segment caches, keep the response shape, and lose no data.
+
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use serde_json::{json, Value};
+use tower::ServiceExt;
+
+async fn call(app: &axum::Router, method: &str, path: &str, body: Value) -> (StatusCode, Value) {
+ let mut b = Request::builder().method(method).uri(path);
+ let body = if body.is_null() {
+ Body::empty()
+ } else {
+ b = b.header("content-type", "application/json");
+ Body::from(body.to_string())
+ };
+ let res = app.clone().oneshot(b.body(body).unwrap()).await.unwrap();
+ let status = res.status();
+ let bytes = axum::body::to_bytes(res.into_body(), usize::MAX)
+ .await
+ .unwrap();
+ (
+ status,
+ serde_json::from_slice(&bytes).unwrap_or(Value::Null),
+ )
+}
+
+/// FAIL-BEFORE: with the handler reverted to the stub, `after == 0` fails
+/// (the caches stay resident) and the unrefreshed doc count is unchanged only
+/// because nothing ran.
+#[tokio::test]
+async fn cache_clear_releases_hydrated_caches_and_loses_nothing() {
+ let dir = tempfile::tempdir().expect("tempdir");
+ let mut config = xerj_common::config::Config::default();
+ config.server.data_dir = dir.path().to_string_lossy().into_owned();
+ config.storage.wal_sync = xerj_common::config::WalSync::Async;
+ let metrics = xerj_common::metrics::Metrics::new().expect("metrics");
+ let engine = xerj_engine::Engine::new(config.clone()).expect("engine");
+ let state = xerj_api::state::AppState::new(config, engine, metrics);
+ let engine = state.engine.clone();
+ let app = xerj_api::router::build_es_compat_router(state);
+
+ call(
+ &app,
+ "PUT",
+ "/docs",
+ json!({"mappings":{"properties":{"body":{"type":"text"}}}}),
+ )
+ .await;
+ for i in 0..40 {
+ call(
+ &app,
+ "PUT",
+ &format!("/docs/_doc/d{i}"),
+ json!({"body": format!("document number {i}")}),
+ )
+ .await;
+ }
+ call(&app, "POST", "/docs/_refresh", Value::Null).await;
+ // Hydrate the per-segment caches with a size>0 search.
+ let (st, _) = call(
+ &app,
+ "POST",
+ "/docs/_search",
+ json!({"query":{"match":{"body":"document"}},"size":10}),
+ )
+ .await;
+ assert_eq!(st, StatusCode::OK);
+ let idx = engine.get_index("docs").expect("index");
+ let before = idx.total_cache_entries();
+ assert!(
+ before > 0,
+ "a query should have hydrated the caches, got {before}"
+ );
+
+ // A doc written but never refreshed must survive the clear (flush first).
+ call(
+ &app,
+ "PUT",
+ "/docs/_doc/late",
+ json!({"body": "document late"}),
+ )
+ .await;
+
+ let (st, body) = call(&app, "POST", "/docs/_cache/clear", Value::Null).await;
+ assert_eq!(st, StatusCode::OK);
+ assert_eq!(
+ body,
+ json!({"_shards": {"total": 1, "successful": 1, "failed": 0}})
+ );
+
+ let after = idx.total_cache_entries();
+ assert_eq!(
+ after, 0,
+ "#950: _cache/clear must release caches (was {before}, now {after})"
+ );
+
+ call(&app, "POST", "/docs/_refresh", Value::Null).await;
+ let (_, c) = call(
+ &app,
+ "POST",
+ "/docs/_count",
+ json!({"query":{"match_all":{}}}),
+ )
+ .await;
+ assert_eq!(c["count"], 41, "clear must lose no document: {c}");
+}
diff --git a/engine/crates/xerj-engine/src/engine.rs b/engine/crates/xerj-engine/src/engine.rs
index 494bab394..24f274d77 100644
--- a/engine/crates/xerj-engine/src/engine.rs
+++ b/engine/crates/xerj-engine/src/engine.rs
@@ -3883,24 +3883,31 @@ impl Engine {
/// new way to wedge. Returns the number of indexes drained; closed
/// indexes are skipped (their caches were already released at close).
pub async fn drain_rebuildable_memory(&self) -> usize {
- let mut drained = 0usize;
- for entry in self.indices.iter() {
- let idx = Arc::clone(entry.value());
- let name = entry.key();
- if self.closed_indices.contains_key(name.as_str()) {
- continue;
- }
+ let loaded: Vec<Arc<Index>> = self
+ .indices
+ .iter()
+ .filter(|e| !self.closed_indices.contains_key(e.key().as_str()))
+ .map(|e| Arc::clone(e.value()))
+ .collect();
+ self.release_rebuildable_memory(&loaded).await
+ }
+
+ /// Flush then release the rebuildable caches of exactly `indices`, then
+ /// purge the allocator (issue #950). The shared body of the
+ /// memory-pressure drain and of `POST /{index}/_cache/clear`, so the
+ /// operator-facing clear and the breaker's drain cannot drift apart: same
+ /// flush-first ordering as [`Self::close_index`], nothing closed, reads
+ /// re-hydrate from disk. Best-effort per index. Returns how many were
+ /// released.
+ pub async fn release_rebuildable_memory(&self, indices: &[Arc<Index>]) -> usize {
+ for idx in indices {
if idx.flush().await.is_err() {
- tracing::warn!(
- index = name.as_str(),
- "memory-pressure drain: flush failed, releasing caches anyway"
- );
+ tracing::warn!("memory release: flush failed, releasing caches anyway");
}
idx.release_memory();
- drained += 1;
}
purge_allocator_pages();
- drained
+ indices.len()
}
/// Spawn the background resource sampler (item 1/3): every