Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(api-keys): bypass S3FS stat cache for key-store change signature (#4192)

dingben45c329594553
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index 9436527f3..42eba817a 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -1040,14 +1040,19 @@ fn py_to_json_value(v: &Bound<'_, PyAny>) -> PyResult<serde_json::Value> {
/// When the dict contains `"disable_auto_pathlock": "true"`, the `PathLockWrappedFS` auto-lock
/// layer is suppressed so callers that already hold a pathlock lease can safely delegate to the
/// inner filesystem without double-locking.
+///
+/// When the dict contains `"bypass_cache": "true"`, plugin-local metadata caches (e.g. the S3FS
+/// stat cache) are bypassed so the operation observes fresh backend state.
fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {
let mut account_id = String::new();
let mut disable_auto_pathlock = false;
let mut lease_ref: Option<String> = None;
+ let mut bypass_cache = false;
if let Some(m) = &ctx {
account_id = m.get("account_id").cloned().unwrap_or_default();
disable_auto_pathlock = m.get("disable_auto_pathlock").map(|s| s == "true").unwrap_or(false);
lease_ref = m.get("lease_ref").cloned();
+ bypass_cache = m.get("bypass_cache").map(|s| s == "true").unwrap_or(false);
}
let pathlock = if disable_auto_pathlock || lease_ref.is_some() {
Some(PathLockContext {
@@ -1057,7 +1062,10 @@ fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {
} else {
None
};
- Arc::new(FsContextInner::with_pathlock(account_id, pathlock.unwrap_or_default()))
+ Arc::new(
+ FsContextInner::with_pathlock(account_id, pathlock.unwrap_or_default())
+ .with_bypass_cache(bypass_cache),
+ )
}
/// Convert an OwnedPathLockLease to a Python dict.
diff --git a/crates/ragfs/src/core/context.rs b/crates/ragfs/src/core/context.rs
index 3587a13e3..fbe9f4634 100644
--- a/crates/ragfs/src/core/context.rs
+++ b/crates/ragfs/src/core/context.rs
@@ -33,6 +33,7 @@ pub struct PathLockContext {
pub struct FsContextInner {
account_id: String,
pathlock: Option<PathLockContext>,
+ bypass_cache: bool,
}
impl FsContextInner {
@@ -41,6 +42,7 @@ impl FsContextInner {
Self {
account_id: account_id.into(),
pathlock: None,
+ bypass_cache: false,
}
}
@@ -52,9 +54,16 @@ impl FsContextInner {
Self {
account_id: account_id.into(),
pathlock: Some(pathlock),
+ bypass_cache: false,
}
}
+ /// Return a context copy that forces plugin-local caches to serve fresh reads.
+ pub fn with_bypass_cache(mut self, bypass_cache: bool) -> Self {
+ self.bypass_cache = bypass_cache;
+ self
+ }
+
/// Tenant identifier (account_id == tenant).
pub fn account_id(&self) -> &str {
&self.account_id
@@ -65,6 +74,11 @@ impl FsContextInner {
self.pathlock.as_ref()
}
+ /// Whether plugin-local caches must be bypassed for this operation.
+ pub fn bypass_cache(&self) -> bool {
+ self.bypass_cache
+ }
+
/// Return a context copy that preserves identity and lease while disabling automatic PathLock.
pub fn with_auto_pathlock_disabled(&self) -> Self {
let mut pathlock = self.pathlock.clone().unwrap_or_default();
@@ -72,6 +86,7 @@ impl FsContextInner {
Self {
account_id: self.account_id.clone(),
pathlock: Some(pathlock),
+ bypass_cache: self.bypass_cache,
}
}
}
@@ -117,6 +132,14 @@ impl FsContextView {
.map(|p| p.disable_auto_pathlock)
.unwrap_or(false)
}
+
+ /// Whether plugin-local caches must be bypassed for the current operation.
+ pub fn bypass_cache(&self) -> bool {
+ self.inner
+ .as_ref()
+ .map(|c| c.bypass_cache())
+ .unwrap_or(false)
+ }
}
#[cfg(test)]
@@ -161,4 +184,18 @@ mod tests {
// Outside the scope it is unset again.
assert_eq!(FsContextView::current().account_id(), None);
}
+
+ #[tokio::test]
+ async fn bypass_cache_defaults_false_and_round_trips() {
+ assert!(!FsContextInner::new("t").bypass_cache());
+
+ let ctx = Arc::new(FsContextInner::new("t").with_bypass_cache(true));
+ FS_CTX
+ .scope(ctx, async {
+ assert!(FsContextView::current().bypass_cache());
+ })
+ .await;
+ // Unset context reports no bypass.
+ assert!(!FsContextView::current().bypass_cache());
+ }
}
diff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rs
index d059ce15d..eeec24015 100644
--- a/crates/ragfs/src/plugins/s3fs/mod.rs
+++ b/crates/ragfs/src/plugins/s3fs/mod.rs
@@ -28,6 +28,7 @@ use futures::stream::{self, StreamExt};
use regex::Regex;
use std::sync::atomic::{AtomicUsize, Ordering};
+use crate::core::context::FsContextView;
use crate::core::filesystem::{relative_depth, relative_match_file, sort_directory_entries};
use crate::core::glob::PreparedGlob;
use crate::core::{
@@ -736,9 +737,16 @@ impl FileSystem for S3FileSystem {
});
}
+ // Bypass the stat cache when the caller demands fresh backend metadata
+ // (e.g. read replicas polling the API-key store for writer-side changes).
+ // The sliding-TTL cache would otherwise pin stale size/modTime forever.
+ let bypass_cache = FsContextView::current().bypass_cache();
+
// Check stat cache
- if let Some(cached) = self.stat_cache.get(&normalized).await {
- return cached.ok_or_else(|| Error::not_found(&normalized));
+ if !bypass_cache {
+ if let Some(cached) = self.stat_cache.get(&normalized).await {
+ return cached.ok_or_else(|| Error::not_found(&normalized));
+ }
}
let key = self.client.build_key(&normalized);
diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.py
index 5182f2b71..494bbabf0 100644
--- a/openviking/pyagfs/async_client.py
+++ b/openviking/pyagfs/async_client.py
@@ -166,8 +166,15 @@ class AsyncAGFSClient:
kwargs["force"] = force
return await self.run("rm", path, **kwargs, ctx=_fs_ctx_or_default(path, fs_ctx))
- async def stat(self, path: str, *, fs_ctx: Dict[str, str] | None = None) -> Dict[str, Any]:
- return await self.run("stat", path, ctx=_fs_ctx_or_default(path, fs_ctx))
+ async def stat(
+ self, path: str, *, fs_ctx: Dict[str, str] | None = None, bypass_cache: bool = False
+ ) -> Dict[str, Any]:
+ ctx = dict(_fs_ctx_or_default(path, fs_ctx))
+ if bypass_cache:
+ # Force plugin-local metadata caches (e.g. S3FS stat cache) to serve
+ # fresh backend state so pollers observe writer-side changes.
+ ctx["bypass_cache"] = "true"
+ return await self.run("stat", path, ctx=ctx)
async def mv(
self, old_path: str, new_path: str, *, fs_ctx: Dict[str, str] | None = None
diff --git a/openviking/server/api_keys/legacy.py b/openviking/server/api_keys/legacy.py
index 442105d13..806aa758e 100644
--- a/openviking/server/api_keys/legacy.py
+++ b/openviking/server/api_keys/legacy.py
@@ -234,7 +234,9 @@ class LegacyAPIKeyManager:
async def _stat_signature(self, path: str) -> tuple:
"""Return a (path, size, mod_time) tuple for one file; missing/error yields a sentinel."""
try:
- info = await self._async_agfs.stat(path)
+ # Bypass plugin-local stat caches: on S3 the sliding-TTL stat cache
+ # would otherwise pin stale metadata and mask writer-side changes.
+ info = await self._async_agfs.stat(path, bypass_cache=True)
except AGFSNotFoundError:
return (path, None, None)
except Exception:
diff --git a/tests/server/test_api_key_manager.py b/tests/server/test_api_key_manager.py
index 9a36bc1aa..966639321 100644
--- a/tests/server/test_api_key_manager.py
+++ b/tests/server/test_api_key_manager.py
@@ -1070,3 +1070,30 @@ async def test_store_signature_stable_without_changes(manager_service):
first = await writer.compute_store_signature()
second = await writer.compute_store_signature()
assert first == second
+
+
+async def test_store_signature_stats_bypass_cache(manager_service, monkeypatch):
+ """Signature stats must bypass plugin-local caches so S3 metadata stays fresh.
+
+ Without bypass_cache the S3FS sliding-TTL stat cache pins stale (size, modTime)
+ and the watcher never observes writer-side changes.
+ """
+ writer = APIKeyManager(root_key=ROOT_KEY, viking_fs=manager_service.viking_fs)
+ await writer.load()
+ acct = _uid()
+ await writer.create_account(acct, "alice")
+
+ real_stat = writer._legacy._async_agfs.stat
+ seen_bypass: list = []
+
+ async def _spy_stat(path, *, fs_ctx=None, bypass_cache=False):
+ seen_bypass.append(bypass_cache)
+ return await real_stat(path, fs_ctx=fs_ctx, bypass_cache=bypass_cache)
+
+ monkeypatch.setattr(writer._legacy._async_agfs, "stat", _spy_stat)
+
+ await writer.compute_store_signature()
+
+ # accounts.json + one users.json were stat'd, all with bypass_cache=True.
+ assert seen_bypass
+ assert all(seen_bypass)