From 25e0f02f2fed68fa314177d354603eb7c278a01e Mon Sep 17 00:00:00 2001 From: He Yunhui Date: Sat, 21 Nov 2026 06:45:28 +0800 Subject: [PATCH] fix(client): use public cache after private expiry --- .../shared-cache-after-private-expiry.md | 5 ++ packages/client/src/client/responseCache.ts | 16 ++-- .../client/test/client/responseCache.test.ts | 73 +++++++++++++++++++ 3 files changed, 87 insertions(+), 7 deletions(-) create mode 100644 .changeset/shared-cache-after-private-expiry.md diff --git a/.changeset/shared-cache-after-private-expiry.md b/.changeset/shared-cache-after-private-expiry.md new file mode 100644 index 0000000000..c13333df6c --- /dev/null +++ b/.changeset/shared-cache-after-private-expiry.md @@ -0,0 +1,5 @@ +--- +'@modelcontextprotocol/client': patch +--- + +Use a held public cache entry after a private entry expires, so shared-store clients can reuse its response and tool metadata without an unnecessary request. Fresh private entries still take precedence, and stale private metadata remains available when no public entry is held. diff --git a/packages/client/src/client/responseCache.ts b/packages/client/src/client/responseCache.ts index e6103d34ce..735d591a48 100644 --- a/packages/client/src/client/responseCache.ts +++ b/packages/client/src/client/responseCache.ts @@ -377,8 +377,10 @@ export class ClientResponseCache { } /** - * Two-probe lookup: this client's own (private) partition first, then the - * connected server's shared (public) partition. The shared probe is gated + * Two-probe lookup: this client's fresh private entry first, then the + * connected server's shared (public) partition. A stale private entry is + * retained for derived metadata only when no public entry is held. + * The shared probe is gated * on `entry.scope === 'public'` — a co-tenant client that omits * `cachePartition` writes its `'private'`-scoped entries at the public * partition, and serving those to a correctly-partitioned client would @@ -391,11 +393,11 @@ export class ClientResponseCache { const key = { method, params: params ?? '' }; const ownPartition = this._partitionFor('private'); const own = await this._store.get({ ...key, partition: ownPartition }); - if (own !== undefined) return own; + if (own?.expiresAt !== undefined && own.expiresAt > this.now()) return own; const sharedPartition = this._partitionFor('public'); - if (sharedPartition === ownPartition) return undefined; + if (sharedPartition === ownPartition) return own; const shared = await this._store.get({ ...key, partition: sharedPartition }); - return shared?.scope === 'public' ? shared : undefined; + return shared?.scope === 'public' ? shared : own; } /** @@ -553,8 +555,8 @@ export class ClientResponseCache { /** * Serve the fresh cached result for `{method, params}`, or `undefined`. - * Lookup is the two-probe order (own-partition then this server's shared - * partition, gated on `scope === 'public'`); freshness is + * Lookup prefers a fresh private entry, then this server's shared + * partition, gated on `scope === 'public'`; freshness is * `entry.expiresAt > now()` (a missing `expiresAt` is never fresh), * checked BEFORE decoding so stale entries cost no parse. Every hit is * freshly parsed, so the caller owns the value outright. An entry whose diff --git a/packages/client/test/client/responseCache.test.ts b/packages/client/test/client/responseCache.test.ts index e2e2326705..6809a938c1 100644 --- a/packages/client/test/client/responseCache.test.ts +++ b/packages/client/test/client/responseCache.test.ts @@ -149,6 +149,39 @@ describe('InMemoryResponseCacheStore', () => { }); describe('ClientResponseCache', () => { + it('keeps the single-partition lookup to one probe when its entry is stale', async () => { + const store = new InMemoryResponseCacheStore(); + const get = store.get.bind(store); + let probes = 0; + store.get = key => { + probes++; + return get(key); + }; + const cache = new ClientResponseCache(store, true); + await cache.write('tools/list', { tools: [TOOL_A] }, cache.captureGeneration('tools/list')); + expect((await cache.toolDefinition('a'))?.name).toBe('a'); + expect(probes).toBe(1); + }); + + it.each([undefined, 'private'] as const)('retains stale private metadata when the shared entry has scope %s', async sharedScope => { + const store = new InMemoryResponseCacheStore(); + const cache = new ClientResponseCache(store, true, undefined, 'alice', () => 10); + cache.setServerIdentity('srv'); + store.set( + { method: 'tools/list', partition: part('alice', 'srv') }, + { value: JSON.stringify({ tools: [TOOL_A] }), expiresAt: 10, scope: 'private' } + ); + if (sharedScope !== undefined) { + store.set( + { method: 'tools/list', partition: part('', 'srv') }, + { value: JSON.stringify({ tools: [TOOL_B] }), expiresAt: 20, scope: sharedScope } + ); + } + expect(await cache.read('tools/list')).toBeUndefined(); + expect((await cache.toolDefinition('a'))?.name).toBe('a'); + expect(await cache.outputValidator('a', tool => tool.name)).toBe('a'); + }); + it('write skips when the captured generation moved (list_changed-during-walk guard)', async () => { const store = new InMemoryResponseCacheStore(); const cache = new ClientResponseCache(store, false); @@ -842,6 +875,46 @@ describe('Client honours cacheHints (SEP-2549)', () => { } }); + it('an expired private entry falls back to a fresh public entry and its tool metadata', async () => { + const store = new InMemoryResponseCacheStore(); + const a = await scriptedModernServer([[TOOL_A]], { listHint: { ttlMs: 10, cacheScope: 'private' } }); + const alice = modernClient(store, { cachePartition: 'alice' }); + await alice.connect(a.clientTx); + setNow(alice, 1_000_000); + await alice.listTools(); + expect((await toolDef(alice, 'a'))?.name).toBe('a'); + const compile = (tool: Tool): string => tool.name; + expect(await cacheOf(alice).outputValidator('a', compile)).toBe('a'); + + const b = await scriptedModernServer([[TOOL_B]], { listHint: { ttlMs: 60_000, cacheScope: 'public' } }); + const bob = modernClient(store, { cachePartition: 'bob' }); + await bob.connect(b.clientTx); + setNow(bob, 1_000_005); + await bob.listTools(); + expect(b.listCount()).toBe(1); + + setNow(alice, 1_000_005); + expect((await alice.listTools()).tools.map(t => t.name)).toEqual(['a']); + expect((await toolDef(alice, 'a'))?.name).toBe('a'); + expect(a.listCount()).toBe(1); + + setNow(alice, 1_000_010); + expect((await alice.listTools()).tools.map(t => t.name)).toEqual(['b']); + expect(a.listCount()).toBe(1); + expect((await toolDef(alice, 'b'))?.name).toBe('b'); + expect(await toolDef(alice, 'a')).toBeUndefined(); + expect(await cacheOf(alice).outputValidator('b', compile)).toBe('b'); + expect(await cacheOf(alice).outputValidator('a', compile)).toBeUndefined(); + expect(store.get({ method: 'tools/list', partition: part('alice') })).toBeDefined(); + + setNow(alice, 1_100_000); + expect(await cacheOf(alice).read('tools/list')).toBeUndefined(); + expect((await toolDef(alice, 'b'))?.name).toBe('b'); + expect(await cacheOf(alice).outputValidator('b', compile)).toBe('b'); + await alice.close(); + await bob.close(); + }); + it("different serverIdentity on a shared store: no cross-talk even for 'public' entries", async () => { const store = new InMemoryResponseCacheStore(); // Server X stamps public; client x writes under [x@1.0.0, ''].