Skip to content

fix(client): scope default cache partition to the connection - #1194

Open
e5l wants to merge 4 commits into
devcrocod/sep-2575-stateless-mcpfrom
fix/sep2575-cache-connection-scope
Open

e5l wants to merge 4 commits into
devcrocod/sep-2575-stateless-mcpfrom
fix/sep2575-cache-connection-scope

Conversation

@e5l

@e5l e5l commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

Follow-up to #985. Goal: a cached result is served only to the server connection and authorization context that fetched it. The spec says "Caches MUST NOT be shared across authorization contexts". Every client filed entries under the same empty partition, and the key carried no server identity. So a store shared by two clients served one server's tools/list to the other, a private entry reached another client, and a reconnect to a different server served the old server's listing. This resolves the two review comments on ResponseCache.kt:41 (r4588386105, r4588386174).

What changed

  • An empty ClientOptions.cachePartition, the default, now gets a fresh random value at each connect. Entries are confined to that connection: no other client sharing the store is served them, and neither is this client after a reconnect.
  • A non-empty partition is the caller naming one server and one authorization context, for example the server URL plus the token subject. Every client configured with it shares entries.
  • KDoc for cachePartition, CacheKey.partition and InMemoryResponseCacheStore now says this. The old text claimed the empty partition already meant "this client instance".

Scope

CacheKey, the store interface and the public API are unchanged, so the ABI dump is unchanged. Client-side only.

Tradeoffs

  • The server identity is not derived from serverInfo. The server controls that value, so on a shared store one server could write into another server's namespace. Sharing across connections takes an explicit partition.
  • With the default partition, a reconnect refetches what the earlier connection had cached. The earlier entries stay in the store, unreachable, until it is cleared. InMemoryResponseCacheStore was already unbounded.
  • Public entries are still not shared across partitions. The spec allows that sharing (MAY), so leaving it out is conservative and does not break the spec.

Blast Radius

Clients that set responseCache. Default-partition clients that share one store lose cross-client hits, which were the leak. Explicit partitions behave as before.

Verification

  • The third commit gives each sharing client its own Server instance with the same identity. Two sessions on one instance kept hanging at connect on CI. The client can't tell the two setups apart, and the private-entry test still fails without the fix.
  • ResponseCacheTest failed before the fix: clients sharing a store each get their own server's listing (expected:<bravo> but was:<alpha>), a private entry is not served to another client sharing the store (expected:<bob-private> but was:<alice-private>), a reconnect to another server does not serve the previous server's listing (expected:<second> but was:<first>). All pass after it. clients configured with the same partition share entries passes on both and guards against over-isolation.
  • Local: :kotlin-sdk-client:jvmTest, :integration-test:jvmTest, ktlintCheck detekt checkKotlinAbi green.
  • CI: Build https://github.com/modelcontextprotocol/kotlin-sdk/actions/runs/44305674500 (green on attempt 3), Conformance https://github.com/modelcontextprotocol/kotlin-sdk/actions/runs/44292603476 (green).
  • Failed attempts hit a hang the base already has. An in-memory connect in a base test waits the full 60s request timeout, and it does so across the stateless fix branches.

🤖 Generated with Claude Code

e5l and others added 4 commits November 18, 2026 09:35
Clients sharing a response cache store must each see their own
server's listing, a private entry must not reach another client on
the default partition, and a reconnect to another server must not
serve the previous server's listing. Clients that declare the same
partition still share entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every client filed cached results under the same empty partition, so a
store shared by two clients served one server's listing to the other,
a private entry crossed authorization contexts, and a reconnect served
the previous server's entries. An empty partition now gets a fresh
random value at each connect, confining entries to that connection. A
non-empty partition is the caller naming one server and one
authorization context, shared by every client configured with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On CI, a second session on one Server instance hung at connect until
the server/discover probe timed out, in both re-runs, while the tests
using one instance per client passed. The client cannot tell one
instance with two sessions from two instances with the same identity,
so each client now gets its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@e5l
e5l requested a review from devcrocod November 20, 2026 09:57

@devcrocod devcrocod left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm
look at comment about kdoc

* @throws IllegalStateException If the server's protocol version is not supported.
*/
@OptIn(ExperimentalMcpApi::class)
@OptIn(ExperimentalMcpApi::class, ExperimentalUuidApi::class)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

check experimental UUID in kotlin 2.3

* [CacheScope.Private] alike. Clients configured with the same partition share entries, so it
* must name both the server and the authorization context, such as the server URL and the
* access token's subject. Empty, the default, confines entries to the current connection:
* neither another client nor this one after a reconnect is served them.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Kdoc should be shortly
because it's not readable and I don't undestantand how to use this parameter

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants