fix(client): complete response cache semantics

Author: github-actions[bot]

crates/rmcp/src/service/client.rs

@@ -285,22 +285,26 @@ const RESOURCE_TEMPLATE_LIST_CACHE_PREFIX: &str = "resources/templates/list:";
 const RESOURCE_READ_CACHE_PREFIX: &str = "resources/read:";
 
 fn list_response_cache_key(prefix: &str, params: &Option<PaginatedRequestParams>) -> String {
-    let cursor = params.as_ref().and_then(|params| params.cursor.as_deref());
-    let cursor = serde_json::to_string(&cursor)
-        .expect("serializing an optional pagination cursor cannot fail");
-    format!("{prefix}{cursor}")
+    let params = serde_json::to_string(params)
+        .expect("serializing pagination request parameters cannot fail");
+    format!("{prefix}{params}")
 }
 
 fn resource_read_cache_key(params: &ReadResourceRequestParams) -> Option<String> {
     if params.input_responses.is_some() || params.request_state.is_some() {
         return None;
     }
-    Some(resource_read_cache_key_for_uri(&params.uri))
+    let serialized =
+        serde_json::to_string(params).expect("serializing resource request parameters cannot fail");
+    Some(format!(
+        "{}{serialized}",
+        resource_read_cache_prefix_for_uri(&params.uri)
+    ))
 }
 
-fn resource_read_cache_key_for_uri(uri: &str) -> String {
+fn resource_read_cache_prefix_for_uri(uri: &str) -> String {
     let uri = serde_json::to_string(uri).expect("serializing a resource URI cannot fail");
-    format!("{RESOURCE_READ_CACHE_PREFIX}{uri}")
+    format!("{RESOURCE_READ_CACHE_PREFIX}{uri}:")
 }
 
 fn request_uses_cursor(params: &Option<PaginatedRequestParams>) -> bool {
@@ -433,7 +437,7 @@ impl Peer<RoleClient> {
     }
 
     pub(crate) async fn invalidate_resource_read_cache(&self, uri: &str) {
-        self.invalidate_cached_response(&resource_read_cache_key_for_uri(uri))
+        self.invalidate_cached_responses(&resource_read_cache_prefix_for_uri(uri))
             .await;
     }
 
@@ -1292,6 +1296,27 @@ mod tests {
         ));
     }
 
+    #[tokio::test]
+    async fn changing_ttl_policy_invalidates_existing_entries() {
+        let peer = disconnected_peer();
+        let key = list_response_cache_key(TOOL_LIST_CACHE_PREFIX, &None);
+        peer.cache_response(
+            key.clone(),
+            ServerResult::ListToolsResult(tools_result(Some(60_000), Some(CacheScope::Public))),
+            Some(60_000),
+            Some(CacheScope::Public),
+        )
+        .await;
+        assert!(peer.cached_response(&key).await.is_some());
+
+        peer.set_response_cache_config(
+            ClientCacheConfig::default().with_max_ttl(Duration::from_millis(1)),
+        )
+        .await;
+
+        assert!(peer.cached_response(&key).await.is_none());
+    }
+
     #[tokio::test]
     async fn private_entries_are_isolated_between_client_peers() {
         let first = disconnected_peer();
@@ -1381,6 +1406,36 @@ mod tests {
         );
     }
 
+    #[test]
+    fn result_affecting_metadata_is_part_of_cache_keys() {
+        let mut first_meta = crate::model::Meta::new();
+        first_meta.insert("variant".into(), serde_json::json!("a"));
+        let mut second_meta = crate::model::Meta::new();
+        second_meta.insert("variant".into(), serde_json::json!("b"));
+
+        let first_page = Some(PaginatedRequestParams {
+            meta: Some(first_meta.clone()),
+            cursor: Some("page".into()),
+        });
+        let second_page = Some(PaginatedRequestParams {
+            meta: Some(second_meta.clone()),
+            cursor: Some("page".into()),
+        });
+        assert_ne!(
+            list_response_cache_key(TOOL_LIST_CACHE_PREFIX, &first_page),
+            list_response_cache_key(TOOL_LIST_CACHE_PREFIX, &second_page)
+        );
+
+        let first_resource =
+            ReadResourceRequestParams::new("file:///example").with_meta(first_meta);
+        let second_resource =
+            ReadResourceRequestParams::new("file:///example").with_meta(second_meta);
+        assert_ne!(
+            resource_read_cache_key(&first_resource),
+            resource_read_cache_key(&second_resource)
+        );
+    }
+
     #[tokio::test]
     async fn list_invalidation_discards_every_cached_page() {
         let peer = disconnected_peer();
@@ -1408,11 +1463,17 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn resource_update_invalidates_only_the_matching_uri() {
+    async fn resource_update_invalidates_every_metadata_variant_for_the_matching_uri() {
         let peer = disconnected_peer();
-        let first_key = resource_read_cache_key_for_uri("file:///first");
-        let second_key = resource_read_cache_key_for_uri("file:///second");
-        for key in [&first_key, &second_key] {
+        let first_plain = ReadResourceRequestParams::new("file:///first");
+        let mut meta = crate::model::Meta::new();
+        meta.insert("variant".into(), serde_json::json!("a"));
+        let first_with_meta = ReadResourceRequestParams::new("file:///first").with_meta(meta);
+        let second = ReadResourceRequestParams::new("file:///second");
+        let first_plain_key = resource_read_cache_key(&first_plain).unwrap();
+        let first_meta_key = resource_read_cache_key(&first_with_meta).unwrap();
+        let second_key = resource_read_cache_key(&second).unwrap();
+        for key in [&first_plain_key, &first_meta_key, &second_key] {
             peer.cache_response(
                 key.clone(),
                 ServerResult::ReadResourceResult(
@@ -1428,7 +1489,8 @@ mod tests {
 
         peer.invalidate_resource_read_cache("file:///first").await;
 
-        assert!(peer.cached_response(&first_key).await.is_none());
+        assert!(peer.cached_response(&first_plain_key).await.is_none());
+        assert!(peer.cached_response(&first_meta_key).await.is_none());
         assert!(peer.cached_response(&second_key).await.is_some());
     }
 
@@ -1485,8 +1547,10 @@ mod tests {
         let peer = disconnected_peer();
         peer.set_response_cache_config(ClientCacheConfig::default().with_max_entries(1))
             .await;
-        let first = resource_read_cache_key_for_uri("file:///first");
-        let second = resource_read_cache_key_for_uri("file:///second");
+        let first =
+            resource_read_cache_key(&ReadResourceRequestParams::new("file:///first")).unwrap();
+        let second =
+            resource_read_cache_key(&ReadResourceRequestParams::new("file:///second")).unwrap();
         peer.cache_response(
             first.clone(),
             ServerResult::ReadResourceResult(ReadResourceResult::new(Vec::new())),

crates/rmcp/src/service/client/cache.rs

@@ -319,11 +319,13 @@ impl Peer<RoleClient> {
         let mut cache = self.response_cache.write().await;
         let config_changed = cache.config != config;
         let partition_changed = cache.config.private_partition != config.private_partition;
+        let ttl_policy_changed = cache.config.default_ttl != config.default_ttl
+            || cache.config.max_ttl != config.max_ttl;
         cache.config = config;
         if config_changed {
             cache.generation = cache.generation.wrapping_add(1);
         }
-        if !cache.config.enabled {
+        if !cache.config.enabled || ttl_policy_changed {
             cache.entries.clear();
         } else if partition_changed {
             cache

crates/rmcp/tests/test_tool_disable_notification.rs

@@ -9,7 +9,7 @@ use std::sync::{
 use rmcp::{
     ClientHandler, RoleClient, RoleServer, ServerHandler, ServiceExt,
     handler::server::{router::tool::ToolRoute, tool::ToolCallContext},
-    model::{CallToolResponse, CallToolResult, ServerCapabilities, ServerInfo, Tool},
+    model::{CacheScope, CallToolResponse, CallToolResult, ServerCapabilities, ServerInfo, Tool},
     service::{MaybeSendFuture, NotificationContext},
 };
 use tokio::sync::{Notify, RwLock};
@@ -19,6 +19,7 @@ struct TestToolServer {
     router: Arc<RwLock<rmcp::handler::server::router::tool::ToolRouter<Self>>>,
     trigger_disable: Arc<Notify>,
     trigger_enable: Arc<Notify>,
+    list_count: Arc<AtomicUsize>,
 }
 
 impl TestToolServer {
@@ -36,6 +37,7 @@ impl TestToolServer {
             router: Arc::new(RwLock::new(tool_router)),
             trigger_disable: Arc::new(Notify::new()),
             trigger_enable: Arc::new(Notify::new()),
+            list_count: Arc::new(AtomicUsize::new(0)),
         }
     }
 }
@@ -60,11 +62,14 @@ impl ServerHandler for TestToolServer {
         _request: Option<rmcp::model::PaginatedRequestParams>,
         _context: rmcp::service::RequestContext<RoleServer>,
     ) -> Result<rmcp::model::ListToolsResult, rmcp::ErrorData> {
+        self.list_count.fetch_add(1, Ordering::SeqCst);
         let router = self.router.read().await;
         Ok(rmcp::model::ListToolsResult {
             tools: router.list_all(),
             ..Default::default()
-        })
+        }
+        .with_ttl_ms(60_000)
+        .with_cache_scope(CacheScope::Public))
     }
 
     fn on_initialized(
@@ -128,6 +133,7 @@ async fn test_disable_enable_sends_tool_list_changed() {
     let server = TestToolServer::new();
     let trigger_disable = server.trigger_disable.clone();
     let trigger_enable = server.trigger_enable.clone();
+    let list_count = server.list_count.clone();
 
     let client = TestToolClient::new();
     let notification_count = client.notification_count.clone();
@@ -140,6 +146,11 @@ async fn test_disable_enable_sends_tool_list_changed() {
 
     let tools = client_service.peer().list_tools(None).await.unwrap();
     assert_eq!(tools.tools.len(), 2);
+    assert_eq!(list_count.load(Ordering::SeqCst), 1);
+
+    let cached_tools = client_service.peer().list_tools(None).await.unwrap();
+    assert_eq!(cached_tools.tools.len(), 2);
+    assert_eq!(list_count.load(Ordering::SeqCst), 1);
 
     trigger_disable.notify_one();
     tokio::time::timeout(std::time::Duration::from_secs(5), client_notify.notified())
@@ -150,6 +161,7 @@ async fn test_disable_enable_sends_tool_list_changed() {
     let tools = client_service.peer().list_tools(None).await.unwrap();
     assert_eq!(tools.tools.len(), 1);
     assert_eq!(tools.tools[0].name, "tool_b");
+    assert_eq!(list_count.load(Ordering::SeqCst), 2);
 
     trigger_enable.notify_one();
     tokio::time::timeout(std::time::Duration::from_secs(5), client_notify.notified())
@@ -159,6 +171,7 @@ async fn test_disable_enable_sends_tool_list_changed() {
 
     let tools = client_service.peer().list_tools(None).await.unwrap();
     assert_eq!(tools.tools.len(), 2);
+    assert_eq!(list_count.load(Ordering::SeqCst), 3);
 
     client_service.cancel().await.unwrap();
     server_handle.abort();

docs/CLIENT_CACHING.md

@@ -34,9 +34,10 @@ Use `ClientCacheConfig::disabled()` to disable cache reads and writes, or
 `with_max_entries()` bounds the in-memory store; the default is 512 entries and
 a value of zero removes the limit.
 
-Cache keys include the method and result-affecting parameters: the cursor for
-paginated list methods and the URI for resource reads. MRTR retries containing
-`inputResponses` or `requestState` are never cached. List-change notifications
+Cache keys include the method and all currently result-affecting parameters: the
+cursor and `_meta` for paginated list methods, and the URI plus `_meta` for resource
+reads. MRTR retries containing `inputResponses` or `requestState` are never cached.
+A response that omits `cacheScope` is treated as private rather than made shareable. List-change notifications
 invalidate every cached page for the corresponding method, while resource
 update notifications invalidate only the matching URI. When a cursor request
 fails, all cached pages for that list method are discarded so the next walk can