Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
⚡ refactor: Use in-memory cache for App MCP configs to avoid Redis SCAN (#12410)
Danny Avila359cc63b4138
diff --git a/packages/api/jest.config.mjs b/packages/api/jest.config.mjsindex df9cf6bcc2..976b794122 100644--- a/packages/api/jest.config.mjs+++ b/packages/api/jest.config.mjs@@ -8,6 +8,7 @@ export default {'\\.helper\\.ts$','\\.helper\\.d\\.ts$','/__tests__/helpers/',+ '\\.manual\\.spec\\.[jt]sx?$',],coverageReporters: ['text', 'cobertura'],testResultsProcessor: 'jest-junit',diff --git a/packages/api/package.json b/packages/api/package.jsonindex a4e74a7a3c..f09d946ec5 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -18,8 +18,8 @@"build:dev": "npm run clean && NODE_ENV=development rollup -c --bundleConfigAsCjs","build:watch": "NODE_ENV=development rollup -c -w --bundleConfigAsCjs","build:watch:prod": "rollup -c -w --bundleConfigAsCjs",- "test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/\"",- "test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/\"",+ "test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"",+ "test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"","test:cache-integration:core": "jest --testPathPatterns=\"src/cache/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false","test:cache-integration:cluster": "jest --testPathPatterns=\"src/cluster/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false --runInBand","test:cache-integration:mcp": "jest --testPathPatterns=\"src/mcp/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false",diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.tsindex 506f5b1baa..b9c1eb66f5 100644--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts@@ -2,8 +2,8 @@ import { Keyv } from 'keyv';import { logger } from '@librechat/data-schemas';import type { IServerConfigsRepositoryInterface } from './ServerConfigsRepositoryInterface';import type * as t from '~/mcp/types';+import { ServerConfigsCacheFactory, APP_CACHE_NAMESPACE } from './cache/ServerConfigsCacheFactory';import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';-import { ServerConfigsCacheFactory } from './cache/ServerConfigsCacheFactory';import { MCPServerInspector } from './MCPServerInspector';import { ServerConfigsDB } from './db/ServerConfigsDB';import { cacheConfig } from '~/cache/cacheConfig';@@ -33,7 +33,7 @@ export class MCPServersRegistry {constructor(mongoose: typeof import('mongoose'), allowedDomains?: string[] | null) {this.dbConfigsRepo = new ServerConfigsDB(mongoose);- this.cacheConfigsRepo = ServerConfigsCacheFactory.create('App', false);+ this.cacheConfigsRepo = ServerConfigsCacheFactory.create(APP_CACHE_NAMESPACE, false);this.allowedDomains = allowedDomains;const ttl = cacheConfig.MCP_REGISTRY_CACHE_TTL;diff --git a/packages/api/src/mcp/registry/cache/ServerConfigsCacheFactory.ts b/packages/api/src/mcp/registry/cache/ServerConfigsCacheFactory.tsindex ba0cec90ea..b9549629d6 100644--- a/packages/api/src/mcp/registry/cache/ServerConfigsCacheFactory.ts+++ b/packages/api/src/mcp/registry/cache/ServerConfigsCacheFactory.ts@@ -1,31 +1,51 @@-import { cacheConfig } from '~/cache';+import { ServerConfigsCacheRedisAggregateKey } from './ServerConfigsCacheRedisAggregateKey';import { ServerConfigsCacheInMemory } from './ServerConfigsCacheInMemory';import { ServerConfigsCacheRedis } from './ServerConfigsCacheRedis';+import { cacheConfig } from '~/cache';-export type ServerConfigsCache = ServerConfigsCacheInMemory | ServerConfigsCacheRedis;+export type ServerConfigsCache =+ | ServerConfigsCacheInMemory+ | ServerConfigsCacheRedis+ | ServerConfigsCacheRedisAggregateKey;/**- * Factory for creating the appropriate ServerConfigsCache implementation based on deployment mode.- * Automatically selects between in-memory and Redis-backed storage depending on USE_REDIS config.- * In single-instance mode (USE_REDIS=false), returns lightweight in-memory cache.- * In cluster mode (USE_REDIS=true), returns Redis-backed cache with distributed coordination.- * Provides a unified interface regardless of the underlying storage mechanism.+ * Namespace for YAML-loaded app-level MCP configs. When Redis is enabled, uses a single+ * aggregate key instead of per-server keys to avoid the costly SCAN + batch-GET pattern+ * in {@link ServerConfigsCacheRedis.getAll} that caused 60s+ stalls under concurrent+ * load (see GitHub #11624, #12408). When Redis is disabled, uses in-memory storage.+ */+export const APP_CACHE_NAMESPACE = 'App' as const;++/**+ * Factory for creating the appropriate ServerConfigsCache implementation based on+ * deployment mode and namespace.+ *+ * The {@link APP_CACHE_NAMESPACE} namespace uses {@link ServerConfigsCacheRedisAggregateKey}+ * when Redis is enabled — storing all configs under a single key so `getAll()` is one GET+ * instead of SCAN + N GETs. Cross-instance visibility is preserved: reinspection results+ * propagate through Redis automatically.+ *+ * Other namespaces use the standard {@link ServerConfigsCacheRedis} (per-key storage with+ * SCAN-based enumeration) when Redis is enabled.*/export class ServerConfigsCacheFactory {/*** Create a ServerConfigsCache instance.- * Returns Redis implementation if Redis is configured, otherwise in-memory implementation.*- * @param namespace - The namespace for the cache (e.g., 'App') - only used for Redis namespacing- * @param leaderOnly - Whether operations should only be performed by the leader (only applies to Redis)+ * @param namespace - The namespace for the cache. {@link APP_CACHE_NAMESPACE} uses+ * aggregate-key Redis storage (or in-memory when Redis is disabled).+ * @param leaderOnly - Whether write operations should only be performed by the leader.* @returns ServerConfigsCache instance*/static create(namespace: string, leaderOnly: boolean): ServerConfigsCache {- if (cacheConfig.USE_REDIS) {- return new ServerConfigsCacheRedis(namespace, leaderOnly);+ if (!cacheConfig.USE_REDIS) {+ return new ServerConfigsCacheInMemory();+ }++ if (namespace === APP_CACHE_NAMESPACE) {+ return new ServerConfigsCacheRedisAggregateKey(namespace, leaderOnly);}- // In-memory mode uses a simple Map - doesn't need namespace- return new ServerConfigsCacheInMemory();+ return new ServerConfigsCacheRedis(namespace, leaderOnly);}}diff --git a/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.ts b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.tsnew file mode 100644index 0000000000..12f423a1fb--- /dev/null+++ b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.ts@@ -0,0 +1,136 @@+import { logger } from '@librechat/data-schemas';+import type Keyv from 'keyv';+import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerConfigsRepositoryInterface';+import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';+import { BaseRegistryCache } from './BaseRegistryCache';+import { standardCache } from '~/cache';++/**+ * Redis-backed MCP server configs cache that stores all entries under a single aggregate key.+ *+ * Unlike {@link ServerConfigsCacheRedis} which uses SCAN + batch-GET for `getAll()`, this+ * implementation stores the entire config map as a single JSON value in Redis. This makes+ * `getAll()` a single O(1) GET regardless of keyspace size, eliminating the 60s+ stalls+ * caused by SCAN under concurrent load in large deployments (see GitHub #11624, #12408).+ *+ * Trade-offs:+ * - `add/update/remove` use a serialized read-modify-write on the aggregate key via a+ * promise-based mutex. This prevents concurrent writes from racing within a single+ * process (e.g., during `Promise.allSettled` initialization of multiple servers).+ * - The entire config map is serialized/deserialized on every operation. With typical MCP+ * deployments (~5-50 servers), the JSON payload is small (10-50KB).+ * - Cross-instance visibility is preserved: all instances read/write the same Redis key,+ * so reinspection results propagate automatically after readThroughCache TTL expiry.+ *+ * IMPORTANT: The promise-based writeLock serializes writes within a single Node.js process+ * only. Concurrent writes from separate instances race at the Redis level (last-write-wins).+ * This is acceptable because writes are performed exclusively by the leader during+ * initialization via {@link MCPServersInitializer}. `reinspectServer` is manual and rare.+ * Callers must enforce this single-writer invariant externally.+ */+const AGGREGATE_KEY = '__all__';++export class ServerConfigsCacheRedisAggregateKey+ extends BaseRegistryCache+ implements IServerConfigsRepositoryInterface+{+ protected readonly cache: Keyv;+ private writeLock: Promise<void> = Promise.resolve();++ constructor(namespace: string, leaderOnly: boolean) {+ super(leaderOnly);+ this.cache = standardCache(`${this.PREFIX}::Servers::${namespace}`);+ }++ /**+ * Serializes write operations to prevent concurrent read-modify-write races.+ * Reads (`get`, `getAll`) are not serialized — they can run concurrently.+ */+ private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {+ const previousLock = this.writeLock;+ let resolve!: () => void;+ this.writeLock = new Promise<void>((r) => {+ resolve = r;+ });+ try {+ await previousLock;+ return await fn();+ } finally {+ resolve();+ }+ }++ public async getAll(): Promise<Record<string, ParsedServerConfig>> {+ const startTime = Date.now();+ const result = (await this.cache.get(AGGREGATE_KEY)) as+ | Record<string, ParsedServerConfig>+ | undefined;+ const elapsed = Date.now() - startTime;+ logger.debug(+ `[ServerConfigsCacheRedisAggregateKey] getAll: fetched ${result ? Object.keys(result).length : 0} configs in ${elapsed}ms`,+ );+ return result ?? {};+ }++ public async get(serverName: string): Promise<ParsedServerConfig | undefined> {+ const all = await this.getAll();+ return all[serverName];+ }++ public async add(serverName: string, config: ParsedServerConfig): Promise<AddServerResult> {+ if (this.leaderOnly) await this.leaderCheck('add MCP servers');+ return this.withWriteLock(async () => {+ const all = await this.getAll();+ if (all[serverName]) {+ throw new Error(+ `Server "${serverName}" already exists in cache. Use update() to modify existing configs.`,+ );+ }+ const storedConfig = { ...config, updatedAt: Date.now() };+ all[serverName] = storedConfig;+ const success = await this.cache.set(AGGREGATE_KEY, all);+ this.successCheck(`add App server "${serverName}"`, success);+ return { serverName, config: storedConfig };+ });+ }++ public async update(serverName: string, config: ParsedServerConfig): Promise<void> {+ if (this.leaderOnly) await this.leaderCheck('update MCP servers');+ return this.withWriteLock(async () => {+ const all = await this.getAll();+ if (!all[serverName]) {+ throw new Error(+ `Server "${serverName}" does not exist in cache. Use add() to create new configs.`,+ );+ }+ all[serverName] = { ...config, updatedAt: Date.now() };+ const success = await this.cache.set(AGGREGATE_KEY, all);+ this.successCheck(`update App server "${serverName}"`, success);+ });+ }++ public async remove(serverName: string): Promise<void> {+ if (this.leaderOnly) await this.leaderCheck('remove MCP servers');+ return this.withWriteLock(async () => {+ const all = await this.getAll();+ if (!all[serverName]) {+ throw new Error(`Failed to remove server "${serverName}" in cache.`);+ }+ delete all[serverName];+ const success = await this.cache.set(AGGREGATE_KEY, all);+ this.successCheck(`remove App server "${serverName}"`, success);+ });+ }++ /**+ * Resets the aggregate key directly instead of using SCAN-based `cache.clear()`.+ * Only one key (`__all__`) ever exists in this namespace, so a targeted delete is+ * more efficient and consistent with the PR's goal of eliminating SCAN operations.+ */+ public override async reset(): Promise<void> {+ if (this.leaderOnly) {+ await this.leaderCheck('reset App MCP servers cache');+ }+ await this.cache.delete(AGGREGATE_KEY);+ }+}diff --git a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheFactory.test.ts b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheFactory.test.tsindex 7499ae127e..577b878cc7 100644--- a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheFactory.test.ts+++ b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheFactory.test.ts@@ -1,9 +1,11 @@-import { ServerConfigsCacheFactory } from '../ServerConfigsCacheFactory';+import { ServerConfigsCacheFactory, APP_CACHE_NAMESPACE } from '../ServerConfigsCacheFactory';+import { ServerConfigsCacheRedisAggregateKey } from '../ServerConfigsCacheRedisAggregateKey';import { ServerConfigsCacheInMemory } from '../ServerConfigsCacheInMemory';import { ServerConfigsCacheRedis } from '../ServerConfigsCacheRedis';import { cacheConfig } from '~/cache';// Mock the cache implementations+jest.mock('../ServerConfigsCacheRedisAggregateKey');jest.mock('../ServerConfigsCacheInMemory');jest.mock('../ServerConfigsCacheRedis');@@ -17,53 +19,48 @@ jest.mock('~/cache', () => ({describe('ServerConfigsCacheFactory', () => {beforeEach(() => {jest.clearAllMocks();+ cacheConfig.USE_REDIS = false;});describe('create()', () => {- it('should return ServerConfigsCacheRedis when USE_REDIS is true', () => {- // Arrange+ it('should return ServerConfigsCacheRedisAggregateKey for App namespace when USE_REDIS is true', () => {cacheConfig.USE_REDIS = true;- // Act- const cache = ServerConfigsCacheFactory.create('App', true);+ const cache = ServerConfigsCacheFactory.create(APP_CACHE_NAMESPACE, false);- // Assert- expect(cache).toBeInstanceOf(ServerConfigsCacheRedis);- expect(ServerConfigsCacheRedis).toHaveBeenCalledWith('App', true);+ expect(cache).toBeInstanceOf(ServerConfigsCacheRedisAggregateKey);+ expect(ServerConfigsCacheRedisAggregateKey).toHaveBeenCalledWith(APP_CACHE_NAMESPACE, false);+ expect(ServerConfigsCacheRedis).not.toHaveBeenCalled();+ expect(ServerConfigsCacheInMemory).not.toHaveBeenCalled();});- it('should return ServerConfigsCacheInMemory when USE_REDIS is false', () => {- // Arrange+ it('should return ServerConfigsCacheInMemory for App namespace when USE_REDIS is false', () => {cacheConfig.USE_REDIS = false;- // Act- const cache = ServerConfigsCacheFactory.create('App', false);+ const cache = ServerConfigsCacheFactory.create(APP_CACHE_NAMESPACE, false);- // Assertexpect(cache).toBeInstanceOf(ServerConfigsCacheInMemory);- expect(ServerConfigsCacheInMemory).toHaveBeenCalled();+ expect(ServerConfigsCacheInMemory).toHaveBeenCalledWith();+ expect(ServerConfigsCacheRedis).not.toHaveBeenCalled();+ expect(ServerConfigsCacheRedisAggregateKey).not.toHaveBeenCalled();});- it('should pass correct parameters to ServerConfigsCacheRedis', () => {- // Arrange+ it('should return ServerConfigsCacheRedis for non-App namespaces when USE_REDIS is true', () => {cacheConfig.USE_REDIS = true;- // Act- ServerConfigsCacheFactory.create('CustomNamespace', true);+ const cache = ServerConfigsCacheFactory.create('CustomNamespace', true);- // Assert+ expect(cache).toBeInstanceOf(ServerConfigsCacheRedis);expect(ServerConfigsCacheRedis).toHaveBeenCalledWith('CustomNamespace', true);+ expect(ServerConfigsCacheRedisAggregateKey).not.toHaveBeenCalled();});- it('should create ServerConfigsCacheInMemory without parameters when USE_REDIS is false', () => {- // Arrange+ it('should return ServerConfigsCacheInMemory for non-App namespaces when USE_REDIS is false', () => {cacheConfig.USE_REDIS = false;- // Act- ServerConfigsCacheFactory.create('App', false);+ const cache = ServerConfigsCacheFactory.create('CustomNamespace', false);- // Assert- // In-memory cache doesn't use namespace/leaderOnly parameters+ expect(cache).toBeInstanceOf(ServerConfigsCacheInMemory);expect(ServerConfigsCacheInMemory).toHaveBeenCalledWith();});});diff --git a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.perf_benchmark.manual.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.perf_benchmark.manual.spec.tsnew file mode 100644index 0000000000..1815d49fe0--- /dev/null+++ b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.perf_benchmark.manual.spec.ts@@ -0,0 +1,336 @@+/**+ * Performance benchmark for ServerConfigsCacheRedis.getAll()+ *+ * Requires a live Redis instance. Run manually (excluded from CI):+ * npx jest --config packages/api/jest.config.mjs --testPathPatterns="perf_benchmark" --coverage=false+ *+ * Set env vars as needed:+ * USE_REDIS=true REDIS_URI=redis://localhost:6379 npx jest ...+ *+ * This benchmark isolates the two phases of getAll() — SCAN (key discovery) and+ * batched GET (value retrieval) — to identify the actual bottleneck under load.+ * It also benchmarks alternative approaches (single aggregate key, MGET) against+ * the current SCAN+GET implementation.+ */+import { expect } from '@playwright/test';+import type { ParsedServerConfig } from '~/mcp/types';++describe('ServerConfigsCacheRedis Performance Benchmark', () => {+ let ServerConfigsCacheRedis: typeof import('../ServerConfigsCacheRedis').ServerConfigsCacheRedis;+ let keyvRedisClient: Awaited<typeof import('~/cache/redisClients')>['keyvRedisClient'];+ let standardCache: Awaited<typeof import('~/cache')>['standardCache'];++ const PREFIX = 'perf-bench';++ const makeConfig = (i: number): ParsedServerConfig =>+ ({+ type: 'stdio',+ command: `cmd-${i}`,+ args: [`arg-${i}`, `--flag-${i}`],+ env: { KEY: `value-${i}`, EXTRA: `extra-${i}` },+ requiresOAuth: false,+ tools: `tool_a_${i}, tool_b_${i}`,+ capabilities: `{"tools":{"listChanged":true}}`,+ serverInstructions: `Instructions for server ${i}`,+ }) as ParsedServerConfig;++ beforeAll(async () => {+ process.env.USE_REDIS = process.env.USE_REDIS ?? 'true';+ process.env.USE_REDIS_CLUSTER = process.env.USE_REDIS_CLUSTER ?? 'true';+ process.env.REDIS_URI =+ process.env.REDIS_URI ??+ 'redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003';+ process.env.REDIS_KEY_PREFIX = process.env.REDIS_KEY_PREFIX ?? 'perf-bench-test';++ const cacheModule = await import('../ServerConfigsCacheRedis');+ const redisClients = await import('~/cache/redisClients');+ const cacheFactory = await import('~/cache');++ ServerConfigsCacheRedis = cacheModule.ServerConfigsCacheRedis;+ keyvRedisClient = redisClients.keyvRedisClient;+ standardCache = cacheFactory.standardCache;++ if (!keyvRedisClient) throw new Error('Redis client is not initialized');+ await redisClients.keyvRedisClientReady;+ });++ afterAll(async () => {+ if (keyvRedisClient?.isOpen) await keyvRedisClient.disconnect();+ });++ /** Clean up all keys matching our test prefix */+ async function cleanupKeys(pattern: string): Promise<void> {+ if (!keyvRedisClient || !('scanIterator' in keyvRedisClient)) return;+ const keys: string[] = [];+ for await (const key of keyvRedisClient.scanIterator({ MATCH: pattern })) {+ keys.push(key);+ }+ if (keys.length > 0) {+ await Promise.all(keys.map((key) => keyvRedisClient!.del(key)));+ }+ }++ /** Populate a cache with N configs and return the cache instance */+ async function populateCache(+ namespace: string,+ count: number,+ ): Promise<InstanceType<typeof ServerConfigsCacheRedis>> {+ const cache = new ServerConfigsCacheRedis(namespace, false);+ for (let i = 0; i < count; i++) {+ await cache.add(`server-${i}`, makeConfig(i));+ }+ return cache;+ }++ /**+ * Benchmark 1: Isolate SCAN vs GET phases in current getAll()+ *+ * Measures time spent in each phase separately to identify the bottleneck.+ */+ describe('Phase isolation: SCAN vs batched GET', () => {+ const CONFIG_COUNTS = [5, 20, 50];++ for (const count of CONFIG_COUNTS) {+ it(`should measure SCAN and GET phases separately for ${count} configs`, async () => {+ const ns = `${PREFIX}-phase-${count}`;+ const cache = await populateCache(ns, count);++ try {+ // Get the Keyv cache instance namespace for pattern matching+ const keyvCache = standardCache(`MCP::ServersRegistry::Servers::${ns}`);+ const pattern = `*MCP::ServersRegistry::Servers::${ns}:*`;++ // Phase 1: SCAN only (key discovery)+ const scanStart = Date.now();+ const keys: string[] = [];+ for await (const key of keyvRedisClient!.scanIterator({ MATCH: pattern })) {+ keys.push(key);+ }+ const scanMs = Date.now() - scanStart;++ // Phase 2: Batched GET only (value retrieval via Keyv)+ const keyNames = keys.map((key) => key.substring(key.lastIndexOf(':') + 1));+ const BATCH_SIZE = 100;+ const getStart = Date.now();+ for (let i = 0; i < keyNames.length; i += BATCH_SIZE) {+ const batch = keyNames.slice(i, i + BATCH_SIZE);+ await Promise.all(batch.map((k) => keyvCache.get(k)));+ }+ const getMs = Date.now() - getStart;++ // Phase 3: Full getAll() (both phases combined)+ const fullStart = Date.now();+ const result = await cache.getAll();+ const fullMs = Date.now() - fullStart;++ console.log(+ `[${count} configs] SCAN: ${scanMs}ms | GET: ${getMs}ms | Full getAll: ${fullMs}ms | Keys found: ${keys.length}`,+ );++ expect(Object.keys(result).length).toBe(count);++ // Clean up the Keyv instance+ await keyvCache.clear();+ } finally {+ await cleanupKeys(`*${ns}*`);+ }+ });+ }+ });++ /**+ * Benchmark 2: SCAN cost scales with total Redis keyspace, not just matching keys+ *+ * Redis SCAN iterates the entire hash table and filters by pattern. With a large+ * keyspace (many non-matching keys), SCAN takes longer even if few keys match.+ * This test measures SCAN time with background noise keys.+ */+ describe('SCAN cost vs keyspace size', () => {+ it('should measure SCAN latency with background noise keys', async () => {+ const ns = `${PREFIX}-noise`;+ const targetCount = 10;++ // Add target configs+ const cache = await populateCache(ns, targetCount);++ // Add noise keys in a different namespace to inflate the keyspace+ const noiseCount = 500;+ const noiseCache = standardCache(`noise-namespace-${Date.now()}`);+ for (let i = 0; i < noiseCount; i++) {+ await noiseCache.set(`noise-${i}`, { data: `value-${i}` });+ }++ try {+ const pattern = `*MCP::ServersRegistry::Servers::${ns}:*`;++ // Measure SCAN with noise+ const scanStart = Date.now();+ const keys: string[] = [];+ for await (const key of keyvRedisClient!.scanIterator({ MATCH: pattern })) {+ keys.push(key);+ }+ const scanMs = Date.now() - scanStart;++ // Measure full getAll+ const fullStart = Date.now();+ const result = await cache.getAll();+ const fullMs = Date.now() - fullStart;++ console.log(+ `[${targetCount} configs + ${noiseCount} noise keys] SCAN: ${scanMs}ms | Full getAll: ${fullMs}ms`,+ );++ expect(Object.keys(result).length).toBe(targetCount);+ } finally {+ await noiseCache.clear();+ await cleanupKeys(`*${ns}*`);+ }+ });+ });++ /**+ * Benchmark 3: Concurrent getAll() calls (simulates the actual production bottleneck)+ *+ * Multiple users hitting /api/mcp/* simultaneously, all triggering getAll()+ * after the 5s TTL read-through cache expires.+ */+ describe('Concurrent getAll() under load', () => {+ const CONCURRENCY_LEVELS = [1, 10, 50, 100];+ const CONFIG_COUNT = 30;++ for (const concurrency of CONCURRENCY_LEVELS) {+ it(`should measure ${concurrency} concurrent getAll() calls with ${CONFIG_COUNT} configs`, async () => {+ const ns = `${PREFIX}-concurrent-${concurrency}`;+ const cache = await populateCache(ns, CONFIG_COUNT);++ try {+ const startTime = Date.now();+ const promises = Array.from({ length: concurrency }, () => cache.getAll());+ const results = await Promise.all(promises);+ const elapsed = Date.now() - startTime;++ console.log(+ `[${CONFIG_COUNT} configs x ${concurrency} concurrent] Total: ${elapsed}ms | Per-call avg: ${(elapsed / concurrency).toFixed(1)}ms`,+ );++ for (const result of results) {+ expect(Object.keys(result).length).toBe(CONFIG_COUNT);+ }+ } finally {+ await cleanupKeys(`*${ns}*`);+ }+ });+ }+ });++ /**+ * Benchmark 4: Alternative — Single aggregate key+ *+ * Instead of SCAN+GET, store all configs under one Redis key.+ * getAll() becomes a single GET + JSON parse.+ */+ describe('Alternative: Single aggregate key', () => {+ it('should compare aggregate key vs SCAN+GET for getAll()', async () => {+ const ns = `${PREFIX}-aggregate`;+ const configCount = 30;+ const cache = await populateCache(ns, configCount);++ // Build the aggregate object+ const aggregate: Record<string, ParsedServerConfig> = {};+ for (let i = 0; i < configCount; i++) {+ aggregate[`server-${i}`] = makeConfig(i);+ }++ // Store as single key+ const aggregateCache = standardCache(`aggregate-test-${Date.now()}`);+ await aggregateCache.set('all', aggregate);++ try {+ // Measure SCAN+GET approach+ const scanStart = Date.now();+ const scanResult = await cache.getAll();+ const scanMs = Date.now() - scanStart;++ // Measure single-key approach+ const aggStart = Date.now();+ const aggResult = (await aggregateCache.get('all')) as Record<string, ParsedServerConfig>;+ const aggMs = Date.now() - aggStart;++ console.log(+ `[${configCount} configs] SCAN+GET: ${scanMs}ms | Single key: ${aggMs}ms | Speedup: ${(scanMs / Math.max(aggMs, 1)).toFixed(1)}x`,+ );++ expect(Object.keys(scanResult).length).toBe(configCount);+ expect(Object.keys(aggResult).length).toBe(configCount);++ // Concurrent comparison+ const concurrency = 100;+ const scanConcStart = Date.now();+ await Promise.all(Array.from({ length: concurrency }, () => cache.getAll()));+ const scanConcMs = Date.now() - scanConcStart;++ const aggConcStart = Date.now();+ await Promise.all(Array.from({ length: concurrency }, () => aggregateCache.get('all')));+ const aggConcMs = Date.now() - aggConcStart;++ console.log(+ `[${configCount} configs x ${concurrency} concurrent] SCAN+GET: ${scanConcMs}ms | Single key: ${aggConcMs}ms | Speedup: ${(scanConcMs / Math.max(aggConcMs, 1)).toFixed(1)}x`,+ );+ } finally {+ await aggregateCache.clear();+ await cleanupKeys(`*${ns}*`);+ }+ });+ });++ /**+ * Benchmark 5: Alternative — Raw MGET (bypassing Keyv serialization overhead)+ *+ * Keyv wraps each value in { value, expires } JSON. Using raw MGET on the+ * Redis client skips the Keyv layer entirely.+ */+ describe('Alternative: Raw MGET vs Keyv batch GET', () => {+ it('should compare raw MGET vs Keyv GET for value retrieval', async () => {+ const ns = `${PREFIX}-mget`;+ const configCount = 30;+ const cache = await populateCache(ns, configCount);++ try {+ // First, discover keys via SCAN (same for both approaches)+ const pattern = `*MCP::ServersRegistry::Servers::${ns}:*`;+ const keys: string[] = [];+ for await (const key of keyvRedisClient!.scanIterator({ MATCH: pattern })) {+ keys.push(key);+ }++ // Approach 1: Keyv batch GET (current implementation)+ const keyvCache = standardCache(`MCP::ServersRegistry::Servers::${ns}`);+ const keyNames = keys.map((key) => key.substring(key.lastIndexOf(':') + 1));++ const keyvStart = Date.now();+ await Promise.all(keyNames.map((k) => keyvCache.get(k)));+ const keyvMs = Date.now() - keyvStart;++ // Approach 2: Raw MGET (no Keyv overhead)+ const mgetStart = Date.now();+ if ('mGet' in keyvRedisClient!) {+ const rawValues = await (+ keyvRedisClient as { mGet: (keys: string[]) => Promise<(string | null)[]> }+ ).mGet(keys);+ // Parse the Keyv-wrapped JSON values+ rawValues.filter(Boolean).map((v) => JSON.parse(v!));+ }+ const mgetMs = Date.now() - mgetStart;++ console.log(+ `[${configCount} configs] Keyv batch GET: ${keyvMs}ms | Raw MGET: ${mgetMs}ms | Speedup: ${(keyvMs / Math.max(mgetMs, 1)).toFixed(1)}x`,+ );++ // Clean up+ await keyvCache.clear();+ } finally {+ await cleanupKeys(`*${ns}*`);+ }+ });+ });+});diff --git a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.tsnew file mode 100644index 0000000000..cbb75609d1--- /dev/null+++ b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.ts@@ -0,0 +1,246 @@+import { expect } from '@playwright/test';+import type { ParsedServerConfig } from '~/mcp/types';++describe('ServerConfigsCacheRedisAggregateKey Integration Tests', () => {+ let ServerConfigsCacheRedisAggregateKey: typeof import('../ServerConfigsCacheRedisAggregateKey').ServerConfigsCacheRedisAggregateKey;+ let keyvRedisClient: Awaited<typeof import('~/cache/redisClients')>['keyvRedisClient'];++ let cache: InstanceType<+ typeof import('../ServerConfigsCacheRedisAggregateKey').ServerConfigsCacheRedisAggregateKey+ >;++ const mockConfig1 = {+ type: 'stdio',+ command: 'node',+ args: ['server1.js'],+ env: { TEST: 'value1' },+ } as ParsedServerConfig;++ const mockConfig2 = {+ type: 'stdio',+ command: 'python',+ args: ['server2.py'],+ env: { TEST: 'value2' },+ } as ParsedServerConfig;++ const mockConfig3 = {+ type: 'sse',+ url: 'http://localhost:3000',+ requiresOAuth: true,+ } as ParsedServerConfig;++ beforeAll(async () => {+ process.env.USE_REDIS = process.env.USE_REDIS ?? 'true';+ process.env.USE_REDIS_CLUSTER = process.env.USE_REDIS_CLUSTER ?? 'true';+ process.env.REDIS_URI =+ process.env.REDIS_URI ??+ 'redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003';+ process.env.REDIS_KEY_PREFIX = process.env.REDIS_KEY_PREFIX ?? 'AggregateKey-IntegrationTest';++ const cacheModule = await import('../ServerConfigsCacheRedisAggregateKey');+ const redisClients = await import('~/cache/redisClients');++ ServerConfigsCacheRedisAggregateKey = cacheModule.ServerConfigsCacheRedisAggregateKey;+ keyvRedisClient = redisClients.keyvRedisClient;++ if (!keyvRedisClient) throw new Error('Redis client is not initialized');+ await redisClients.keyvRedisClientReady;+ });++ beforeEach(() => {+ cache = new ServerConfigsCacheRedisAggregateKey('agg-test', false);+ });++ afterEach(async () => {+ await cache.reset();+ });++ afterAll(async () => {+ if (keyvRedisClient?.isOpen) await keyvRedisClient.disconnect();+ });++ describe('add and get operations', () => {+ it('should add and retrieve a server config', async () => {+ await cache.add('server1', mockConfig1);+ const result = await cache.get('server1');+ expect(result).toMatchObject(mockConfig1);+ });++ it('should return undefined for non-existent server', async () => {+ const result = await cache.get('non-existent');+ expect(result).toBeUndefined();+ });++ it('should throw error when adding duplicate server', async () => {+ await cache.add('server1', mockConfig1);+ await expect(cache.add('server1', mockConfig2)).rejects.toThrow(+ 'Server "server1" already exists in cache. Use update() to modify existing configs.',+ );+ });++ it('should handle multiple server configs', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);+ await cache.add('server3', mockConfig3);++ expect(await cache.get('server1')).toMatchObject(mockConfig1);+ expect(await cache.get('server2')).toMatchObject(mockConfig2);+ expect(await cache.get('server3')).toMatchObject(mockConfig3);+ });+ });++ describe('getAll operation', () => {+ it('should return empty object when no servers exist', async () => {+ const result = await cache.getAll();+ expect(result).toMatchObject({});+ });++ it('should return all server configs', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);+ await cache.add('server3', mockConfig3);++ const result = await cache.getAll();+ expect(result).toMatchObject({+ server1: mockConfig1,+ server2: mockConfig2,+ server3: mockConfig3,+ });+ });++ it('should reflect additions in getAll', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);++ let result = await cache.getAll();+ expect(Object.keys(result).length).toBe(2);++ await cache.add('server3', mockConfig3);+ result = await cache.getAll();+ expect(Object.keys(result).length).toBe(3);+ expect(result.server3).toMatchObject(mockConfig3);+ });+ });++ describe('update operation', () => {+ it('should update an existing server config', async () => {+ await cache.add('server1', mockConfig1);+ expect(await cache.get('server1')).toMatchObject(mockConfig1);++ await cache.update('server1', mockConfig2);+ const result = await cache.get('server1');+ expect(result).toMatchObject(mockConfig2);+ });++ it('should throw error when updating non-existent server', async () => {+ await expect(cache.update('non-existent', mockConfig1)).rejects.toThrow(+ 'Server "non-existent" does not exist in cache. Use add() to create new configs.',+ );+ });++ it('should reflect updates in getAll', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);++ await cache.update('server1', mockConfig3);+ const result = await cache.getAll();+ expect(result.server1).toMatchObject(mockConfig3);+ expect(result.server2).toMatchObject(mockConfig2);+ });+ });++ describe('remove operation', () => {+ it('should remove an existing server config', async () => {+ await cache.add('server1', mockConfig1);+ expect(await cache.get('server1')).toMatchObject(mockConfig1);++ await cache.remove('server1');+ expect(await cache.get('server1')).toBeUndefined();+ });++ it('should throw error when removing non-existent server', async () => {+ await expect(cache.remove('non-existent')).rejects.toThrow(+ 'Failed to remove server "non-existent" in cache.',+ );+ });++ it('should remove server from getAll results', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);++ let result = await cache.getAll();+ expect(Object.keys(result).length).toBe(2);++ await cache.remove('server1');+ result = await cache.getAll();+ expect(Object.keys(result).length).toBe(1);+ expect(result.server1).toBeUndefined();+ expect(result.server2).toMatchObject(mockConfig2);+ });++ it('should allow re-adding a removed server', async () => {+ await cache.add('server1', mockConfig1);+ await cache.remove('server1');+ await cache.add('server1', mockConfig3);++ const result = await cache.get('server1');+ expect(result).toMatchObject(mockConfig3);+ });+ });++ describe('concurrent write safety', () => {+ it('should handle concurrent add calls without data loss', async () => {+ const configCount = 20;+ const promises = Array.from({ length: configCount }, (_, i) =>+ cache.add(`server-${i}`, {+ type: 'stdio',+ command: `cmd-${i}`,+ args: [`arg-${i}`],+ } as ParsedServerConfig),+ );++ const results = await Promise.allSettled(promises);+ const failures = results.filter((r) => r.status === 'rejected');+ expect(failures).toHaveLength(0);++ const result = await cache.getAll();+ expect(Object.keys(result).length).toBe(configCount);+ for (let i = 0; i < configCount; i++) {+ expect(result[`server-${i}`]).toBeDefined();+ const config = result[`server-${i}`] as { command?: string };+ expect(config.command).toBe(`cmd-${i}`);+ }+ });++ it('should handle concurrent getAll calls', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);+ await cache.add('server3', mockConfig3);++ const concurrency = 50;+ const promises = Array.from({ length: concurrency }, () => cache.getAll());+ const results = await Promise.all(promises);++ for (const result of results) {+ expect(Object.keys(result).length).toBe(3);+ expect(result.server1).toMatchObject(mockConfig1);+ expect(result.server2).toMatchObject(mockConfig2);+ expect(result.server3).toMatchObject(mockConfig3);+ }+ });+ });++ describe('reset operation', () => {+ it('should clear all configs', async () => {+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);++ expect(Object.keys(await cache.getAll()).length).toBe(2);++ await cache.reset();++ const result = await cache.getAll();+ expect(Object.keys(result).length).toBe(0);+ });+ });+});