🗃️ refactor: Separate Tool Cache Namespace for Blue/Green Deployments (#11738)

* 🔧 refactor: Introduce TOOL_CACHE for isolated caching of tools

- Added TOOL_CACHE key to CacheKeys enum for managing tool-related cache.
- Updated various services and controllers to utilize TOOL_CACHE instead of CONFIG_STORE for better separation of concerns in caching logic.
- Enhanced .env.example with comments on using in-memory cache for blue/green deployments.

* 🔧 refactor: Update cache configuration for in-memory storage handling

- Enhanced the handling of `FORCED_IN_MEMORY_CACHE_NAMESPACES` in `cacheConfig.ts` to default to `CONFIG_STORE` and `APP_CONFIG`, ensuring safer blue/green deployments.
- Updated `.env.example` with clearer comments regarding the usage of in-memory cache namespaces.
- Improved unit tests to validate the new default behavior and handling of empty strings for cache namespaces.

api/server/controllers/PluginController.js

@@ -8,7 +8,7 @@ const { getLogStores } = require('~/cache');
 
 const getAvailablePluginsController = async (req, res) => {
   try {
-    const cache = getLogStores(CacheKeys.CONFIG_STORE);
+    const cache = getLogStores(CacheKeys.TOOL_CACHE);
     const cachedPlugins = await cache.get(CacheKeys.PLUGINS);
     if (cachedPlugins) {
       res.status(200).json(cachedPlugins);
@@ -63,7 +63,7 @@ const getAvailableTools = async (req, res) => {
       logger.warn('[getAvailableTools] User ID not found in request');
       return res.status(401).json({ message: 'Unauthorized' });
     }
-    const cache = getLogStores(CacheKeys.CONFIG_STORE);
+    const cache = getLogStores(CacheKeys.TOOL_CACHE);
     const cachedToolsArray = await cache.get(CacheKeys.TOOLS);
 
     const appConfig = req.config ?? (await getAppConfig({ role: req.user?.role }));

api/server/controllers/PluginController.spec.js

@@ -1,3 +1,4 @@
+const { CacheKeys } = require('librechat-data-provider');
 const { getCachedTools, getAppConfig } = require('~/server/services/Config');
 const { getLogStores } = require('~/cache');
 
@@ -63,6 +64,28 @@ describe('PluginController', () => {
     });
   });
 
+  describe('cache namespace', () => {
+    it('getAvailablePluginsController should use TOOL_CACHE namespace', async () => {
+      mockCache.get.mockResolvedValue([]);
+      await getAvailablePluginsController(mockReq, mockRes);
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+    });
+
+    it('getAvailableTools should use TOOL_CACHE namespace', async () => {
+      mockCache.get.mockResolvedValue([]);
+      await getAvailableTools(mockReq, mockRes);
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+    });
+
+    it('should NOT use CONFIG_STORE namespace for tool/plugin operations', async () => {
+      mockCache.get.mockResolvedValue([]);
+      await getAvailablePluginsController(mockReq, mockRes);
+      await getAvailableTools(mockReq, mockRes);
+      const allCalls = getLogStores.mock.calls.flat();
+      expect(allCalls).not.toContain(CacheKeys.CONFIG_STORE);
+    });
+  });
+
   describe('getAvailablePluginsController', () => {
     it('should use filterUniquePlugins to remove duplicate plugins', async () => {
       // Add plugins with duplicates to availableTools

api/server/services/Config/__tests__/getCachedTools.spec.js

@@ -1,10 +1,92 @@
-const { ToolCacheKeys } = require('../getCachedTools');
+const { CacheKeys } = require('librechat-data-provider');
+
+jest.mock('~/cache/getLogStores');
+const getLogStores = require('~/cache/getLogStores');
+
+const mockCache = { get: jest.fn(), set: jest.fn(), delete: jest.fn() };
+getLogStores.mockReturnValue(mockCache);
+
+const {
+  ToolCacheKeys,
+  getCachedTools,
+  setCachedTools,
+  getMCPServerTools,
+  invalidateCachedTools,
+} = require('../getCachedTools');
+
+describe('getCachedTools', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    getLogStores.mockReturnValue(mockCache);
+  });
 
-describe('getCachedTools - Cache Isolation Security', () => {
   describe('ToolCacheKeys.MCP_SERVER', () => {
     it('should generate cache keys that include userId', () => {
       const key = ToolCacheKeys.MCP_SERVER('user123', 'github');
       expect(key).toBe('tools:mcp:user123:github');
     });
   });
+
+  describe('TOOL_CACHE namespace usage', () => {
+    it('getCachedTools should use TOOL_CACHE namespace', async () => {
+      mockCache.get.mockResolvedValue(null);
+      await getCachedTools();
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+    });
+
+    it('getCachedTools with MCP server options should use TOOL_CACHE namespace', async () => {
+      mockCache.get.mockResolvedValue({ tool1: {} });
+      await getCachedTools({ userId: 'user1', serverName: 'github' });
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+      expect(mockCache.get).toHaveBeenCalledWith(ToolCacheKeys.MCP_SERVER('user1', 'github'));
+    });
+
+    it('setCachedTools should use TOOL_CACHE namespace', async () => {
+      mockCache.set.mockResolvedValue(true);
+      const tools = { tool1: { type: 'function' } };
+      await setCachedTools(tools);
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+      expect(mockCache.set).toHaveBeenCalledWith(ToolCacheKeys.GLOBAL, tools, expect.any(Number));
+    });
+
+    it('setCachedTools with MCP server options should use TOOL_CACHE namespace', async () => {
+      mockCache.set.mockResolvedValue(true);
+      const tools = { tool1: { type: 'function' } };
+      await setCachedTools(tools, { userId: 'user1', serverName: 'github' });
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+      expect(mockCache.set).toHaveBeenCalledWith(
+        ToolCacheKeys.MCP_SERVER('user1', 'github'),
+        tools,
+        expect.any(Number),
+      );
+    });
+
+    it('invalidateCachedTools should use TOOL_CACHE namespace', async () => {
+      mockCache.delete.mockResolvedValue(true);
+      await invalidateCachedTools({ invalidateGlobal: true });
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+      expect(mockCache.delete).toHaveBeenCalledWith(ToolCacheKeys.GLOBAL);
+    });
+
+    it('getMCPServerTools should use TOOL_CACHE namespace', async () => {
+      mockCache.get.mockResolvedValue(null);
+      await getMCPServerTools('user1', 'github');
+      expect(getLogStores).toHaveBeenCalledWith(CacheKeys.TOOL_CACHE);
+      expect(mockCache.get).toHaveBeenCalledWith(ToolCacheKeys.MCP_SERVER('user1', 'github'));
+    });
+
+    it('should NOT use CONFIG_STORE namespace', async () => {
+      mockCache.get.mockResolvedValue(null);
+      await getCachedTools();
+      await getMCPServerTools('user1', 'github');
+      mockCache.set.mockResolvedValue(true);
+      await setCachedTools({ tool1: {} });
+      mockCache.delete.mockResolvedValue(true);
+      await invalidateCachedTools({ invalidateGlobal: true });
+
+      const allCalls = getLogStores.mock.calls.flat();
+      expect(allCalls).not.toContain(CacheKeys.CONFIG_STORE);
+      expect(allCalls.every((key) => key === CacheKeys.TOOL_CACHE)).toBe(true);
+    });
+  });
 });

api/server/services/Config/getCachedTools.js

@@ -20,7 +20,7 @@ const ToolCacheKeys = {
  * @returns {Promise<LCAvailableTools|null>} The available tools object or null if not cached
  */
 async function getCachedTools(options = {}) {
-  const cache = getLogStores(CacheKeys.CONFIG_STORE);
+  const cache = getLogStores(CacheKeys.TOOL_CACHE);
   const { userId, serverName } = options;
 
   // Return MCP server-specific tools if requested
@@ -43,7 +43,7 @@ async function getCachedTools(options = {}) {
  * @returns {Promise<boolean>} Whether the operation was successful
  */
 async function setCachedTools(tools, options = {}) {
-  const cache = getLogStores(CacheKeys.CONFIG_STORE);
+  const cache = getLogStores(CacheKeys.TOOL_CACHE);
   const { userId, serverName, ttl = Time.TWELVE_HOURS } = options;
 
   // Cache by MCP server if specified (requires userId)
@@ -65,7 +65,7 @@ async function setCachedTools(tools, options = {}) {
  * @returns {Promise<void>}
  */
 async function invalidateCachedTools(options = {}) {
-  const cache = getLogStores(CacheKeys.CONFIG_STORE);
+  const cache = getLogStores(CacheKeys.TOOL_CACHE);
   const { userId, serverName, invalidateGlobal = false } = options;
 
   const keysToDelete = [];
@@ -89,7 +89,7 @@ async function invalidateCachedTools(options = {}) {
  * @returns {Promise<LCAvailableTools|null>} The available tools for the server
  */
 async function getMCPServerTools(userId, serverName) {
-  const cache = getLogStores(CacheKeys.CONFIG_STORE);
+  const cache = getLogStores(CacheKeys.TOOL_CACHE);
   const serverTools = await cache.get(ToolCacheKeys.MCP_SERVER(userId, serverName));
 
   if (serverTools) {

api/server/services/Config/mcp.js

@@ -35,7 +35,7 @@ async function updateMCPServerTools({ userId, serverName, tools }) {
 
     await setCachedTools(serverTools, { userId, serverName });
 
-    const cache = getLogStores(CacheKeys.CONFIG_STORE);
+    const cache = getLogStores(CacheKeys.TOOL_CACHE);
     await cache.delete(CacheKeys.TOOLS);
     logger.debug(
       `[MCP Cache] Updated ${tools.length} tools for server ${serverName} (user: ${userId})`,
@@ -61,7 +61,7 @@ async function mergeAppTools(appTools) {
     const cachedTools = await getCachedTools();
     const mergedTools = { ...cachedTools, ...appTools };
     await setCachedTools(mergedTools);
-    const cache = getLogStores(CacheKeys.CONFIG_STORE);
+    const cache = getLogStores(CacheKeys.TOOL_CACHE);
     await cache.delete(CacheKeys.TOOLS);
     logger.debug(`Merged ${count} app-level tools`);
   } catch (error) {