🏦 refactor: Centralize Caching & Redis Key Prefixing (#8457)

* 🔧 Overhauled caching feature:
- Refactored caching logic.
- Fixed redis prefix, namespace, tls, ttl, and cluster.
- Added REDIS_KEY_PREFIX_VAR

* # refactor: Rename redisCache to standardCache

* # Add Redis pinging mechanism to maintain connection.

* # docs: Add warning about Keyv Redis client prefix support

api/cache/cacheConfig.js

@@ -0,0 +1,33 @@
+const fs = require('fs');
+const { math, isEnabled } = require('@librechat/api');
+
+// To ensure that different deployments do not interfere with each other's cache, we use a prefix for the Redis keys.
+// This prefix is usually the deployment ID, which is often passed to the container or pod as an env var.
+// Set REDIS_KEY_PREFIX_VAR to the env var that contains the deployment ID.
+const REDIS_KEY_PREFIX_VAR = process.env.REDIS_KEY_PREFIX_VAR;
+const REDIS_KEY_PREFIX = process.env.REDIS_KEY_PREFIX;
+if (REDIS_KEY_PREFIX_VAR && REDIS_KEY_PREFIX) {
+  throw new Error('Only either REDIS_KEY_PREFIX_VAR or REDIS_KEY_PREFIX can be set.');
+}
+
+const USE_REDIS = isEnabled(process.env.USE_REDIS);
+if (USE_REDIS && !process.env.REDIS_URI) {
+  throw new Error('USE_REDIS is enabled but REDIS_URI is not set.');
+}
+
+const cacheConfig = {
+  USE_REDIS,
+  REDIS_URI: process.env.REDIS_URI,
+  REDIS_USERNAME: process.env.REDIS_USERNAME,
+  REDIS_PASSWORD: process.env.REDIS_PASSWORD,
+  REDIS_CA: process.env.REDIS_CA ? fs.readFileSync(process.env.REDIS_CA, 'utf8') : null,
+  REDIS_KEY_PREFIX: process.env[REDIS_KEY_PREFIX_VAR] || REDIS_KEY_PREFIX || '',
+  REDIS_MAX_LISTENERS: math(process.env.REDIS_MAX_LISTENERS, 40),
+
+  CI: isEnabled(process.env.CI),
+  DEBUG_MEMORY_CACHE: isEnabled(process.env.DEBUG_MEMORY_CACHE),
+
+  BAN_DURATION: math(process.env.BAN_DURATION, 7200000), // 2 hours
+};
+
+module.exports = { cacheConfig };

api/cache/cacheConfig.spec.js

@@ -0,0 +1,108 @@
+const fs = require('fs');
+
+describe('cacheConfig', () => {
+  let originalEnv;
+  let originalReadFileSync;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    originalReadFileSync = fs.readFileSync;
+
+    // Clear all related env vars first
+    delete process.env.REDIS_URI;
+    delete process.env.REDIS_CA;
+    delete process.env.REDIS_KEY_PREFIX_VAR;
+    delete process.env.REDIS_KEY_PREFIX;
+    delete process.env.USE_REDIS;
+
+    // Clear require cache
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    fs.readFileSync = originalReadFileSync;
+    jest.resetModules();
+  });
+
+  describe('REDIS_KEY_PREFIX validation and resolution', () => {
+    test('should throw error when both REDIS_KEY_PREFIX_VAR and REDIS_KEY_PREFIX are set', () => {
+      process.env.REDIS_KEY_PREFIX_VAR = 'DEPLOYMENT_ID';
+      process.env.REDIS_KEY_PREFIX = 'manual-prefix';
+
+      expect(() => {
+        require('./cacheConfig');
+      }).toThrow('Only either REDIS_KEY_PREFIX_VAR or REDIS_KEY_PREFIX can be set.');
+    });
+
+    test('should resolve REDIS_KEY_PREFIX from variable reference', () => {
+      process.env.REDIS_KEY_PREFIX_VAR = 'DEPLOYMENT_ID';
+      process.env.DEPLOYMENT_ID = 'test-deployment-123';
+
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_KEY_PREFIX).toBe('test-deployment-123');
+    });
+
+    test('should use direct REDIS_KEY_PREFIX value', () => {
+      process.env.REDIS_KEY_PREFIX = 'direct-prefix';
+
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_KEY_PREFIX).toBe('direct-prefix');
+    });
+
+    test('should default to empty string when no prefix is configured', () => {
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_KEY_PREFIX).toBe('');
+    });
+
+    test('should handle empty variable reference', () => {
+      process.env.REDIS_KEY_PREFIX_VAR = 'EMPTY_VAR';
+      process.env.EMPTY_VAR = '';
+
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_KEY_PREFIX).toBe('');
+    });
+
+    test('should handle undefined variable reference', () => {
+      process.env.REDIS_KEY_PREFIX_VAR = 'UNDEFINED_VAR';
+
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_KEY_PREFIX).toBe('');
+    });
+  });
+
+  describe('USE_REDIS and REDIS_URI validation', () => {
+    test('should throw error when USE_REDIS is enabled but REDIS_URI is not set', () => {
+      process.env.USE_REDIS = 'true';
+
+      expect(() => {
+        require('./cacheConfig');
+      }).toThrow('USE_REDIS is enabled but REDIS_URI is not set.');
+    });
+
+    test('should not throw error when USE_REDIS is enabled and REDIS_URI is set', () => {
+      process.env.USE_REDIS = 'true';
+      process.env.REDIS_URI = 'redis://localhost:6379';
+
+      expect(() => {
+        require('./cacheConfig');
+      }).not.toThrow();
+    });
+
+    test('should handle empty REDIS_URI when USE_REDIS is enabled', () => {
+      process.env.USE_REDIS = 'true';
+      process.env.REDIS_URI = '';
+
+      expect(() => {
+        require('./cacheConfig');
+      }).toThrow('USE_REDIS is enabled but REDIS_URI is not set.');
+    });
+  });
+
+  describe('REDIS_CA file reading', () => {
+    test('should be null when REDIS_CA is not set', () => {
+      const { cacheConfig } = require('./cacheConfig');
+      expect(cacheConfig.REDIS_CA).toBeNull();
+    });
+  });
+});

api/cache/cacheFactory.js

@@ -0,0 +1,66 @@
+const KeyvRedis = require('@keyv/redis').default;
+const { Keyv } = require('keyv');
+const { cacheConfig } = require('./cacheConfig');
+const { keyvRedisClient, ioredisClient, GLOBAL_PREFIX_SEPARATOR } = require('./redisClients');
+const { Time } = require('librechat-data-provider');
+const ConnectRedis = require('connect-redis').default;
+const MemoryStore = require('memorystore')(require('express-session'));
+const { violationFile } = require('./keyvFiles');
+const { RedisStore } = require('rate-limit-redis');
+
+/**
+ * Creates a cache instance using Redis or a fallback store. Suitable for general caching needs.
+ * @param {string} namespace - The cache namespace.
+ * @param {number} [ttl] - Time to live for cache entries.
+ * @param {object} [fallbackStore] - Optional fallback store if Redis is not used.
+ * @returns {Keyv} Cache instance.
+ */
+const standardCache = (namespace, ttl = undefined, fallbackStore = undefined) => {
+  if (cacheConfig.USE_REDIS) {
+    const keyvRedis = new KeyvRedis(keyvRedisClient);
+    const cache = new Keyv(keyvRedis, { namespace, ttl });
+    keyvRedis.namespace = cacheConfig.REDIS_KEY_PREFIX;
+    keyvRedis.keyPrefixSeparator = GLOBAL_PREFIX_SEPARATOR;
+    return cache;
+  }
+  if (fallbackStore) return new Keyv({ store: fallbackStore, namespace, ttl });
+  return new Keyv({ namespace, ttl });
+};
+
+/**
+ * Creates a cache instance for storing violation data.
+ * Uses a file-based fallback store if Redis is not enabled.
+ * @param {string} namespace - The cache namespace for violations.
+ * @param {number} [ttl] - Time to live for cache entries.
+ * @returns {Keyv} Cache instance for violations.
+ */
+const violationCache = (namespace, ttl = undefined) => {
+  return standardCache(`violations:${namespace}`, ttl, violationFile);
+};
+
+/**
+ * Creates a session cache instance using Redis or in-memory store.
+ * @param {string} namespace - The session namespace.
+ * @param {number} [ttl] - Time to live for session entries.
+ * @returns {MemoryStore | ConnectRedis} Session store instance.
+ */
+const sessionCache = (namespace, ttl = undefined) => {
+  namespace = namespace.endsWith(':') ? namespace : `${namespace}:`;
+  if (!cacheConfig.USE_REDIS) return new MemoryStore({ ttl, checkPeriod: Time.ONE_DAY });
+  return new ConnectRedis({ client: ioredisClient, ttl, prefix: namespace });
+};
+
+/**
+ * Creates a rate limiter cache using Redis.
+ * @param {string} prefix - The key prefix for rate limiting.
+ * @returns {RedisStore|undefined} RedisStore instance or undefined if Redis is not used.
+ */
+const limiterCache = (prefix) => {
+  if (!prefix) throw new Error('prefix is required');
+  if (!cacheConfig.USE_REDIS) return undefined;
+  prefix = prefix.endsWith(':') ? prefix : `${prefix}:`;
+  return new RedisStore({ sendCommand, prefix });
+};
+const sendCommand = (...args) => ioredisClient?.call(...args);
+
+module.exports = { standardCache, sessionCache, violationCache, limiterCache };

api/cache/cacheFactory.spec.js

@@ -0,0 +1,272 @@
+const { Time } = require('librechat-data-provider');
+
+// Mock dependencies first
+const mockKeyvRedis = {
+  namespace: '',
+  keyPrefixSeparator: '',
+};
+
+const mockKeyv = jest.fn().mockReturnValue({ mock: 'keyv' });
+const mockConnectRedis = jest.fn().mockReturnValue({ mock: 'connectRedis' });
+const mockMemoryStore = jest.fn().mockReturnValue({ mock: 'memoryStore' });
+const mockRedisStore = jest.fn().mockReturnValue({ mock: 'redisStore' });
+
+const mockIoredisClient = {
+  call: jest.fn(),
+};
+
+const mockKeyvRedisClient = {};
+const mockViolationFile = {};
+
+// Mock modules before requiring the main module
+jest.mock('@keyv/redis', () => ({
+  default: jest.fn().mockImplementation(() => mockKeyvRedis),
+}));
+
+jest.mock('keyv', () => ({
+  Keyv: mockKeyv,
+}));
+
+jest.mock('./cacheConfig', () => ({
+  cacheConfig: {
+    USE_REDIS: false,
+    REDIS_KEY_PREFIX: 'test',
+  },
+}));
+
+jest.mock('./redisClients', () => ({
+  keyvRedisClient: mockKeyvRedisClient,
+  ioredisClient: mockIoredisClient,
+  GLOBAL_PREFIX_SEPARATOR: '::',
+}));
+
+jest.mock('./keyvFiles', () => ({
+  violationFile: mockViolationFile,
+}));
+
+jest.mock('connect-redis', () => ({
+  default: mockConnectRedis,
+}));
+
+jest.mock('memorystore', () => jest.fn(() => mockMemoryStore));
+
+jest.mock('rate-limit-redis', () => ({
+  RedisStore: mockRedisStore,
+}));
+
+// Import after mocking
+const { standardCache, sessionCache, violationCache, limiterCache } = require('./cacheFactory');
+const { cacheConfig } = require('./cacheConfig');
+
+describe('cacheFactory', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // Reset cache config mock
+    cacheConfig.USE_REDIS = false;
+    cacheConfig.REDIS_KEY_PREFIX = 'test';
+  });
+
+  describe('redisCache', () => {
+    it('should create Redis cache when USE_REDIS is true', () => {
+      cacheConfig.USE_REDIS = true;
+      const namespace = 'test-namespace';
+      const ttl = 3600;
+
+      standardCache(namespace, ttl);
+
+      expect(require('@keyv/redis').default).toHaveBeenCalledWith(mockKeyvRedisClient);
+      expect(mockKeyv).toHaveBeenCalledWith(mockKeyvRedis, { namespace, ttl });
+      expect(mockKeyvRedis.namespace).toBe(cacheConfig.REDIS_KEY_PREFIX);
+      expect(mockKeyvRedis.keyPrefixSeparator).toBe('::');
+    });
+
+    it('should create Redis cache with undefined ttl when not provided', () => {
+      cacheConfig.USE_REDIS = true;
+      const namespace = 'test-namespace';
+
+      standardCache(namespace);
+
+      expect(mockKeyv).toHaveBeenCalledWith(mockKeyvRedis, { namespace, ttl: undefined });
+    });
+
+    it('should use fallback store when USE_REDIS is false and fallbackStore is provided', () => {
+      cacheConfig.USE_REDIS = false;
+      const namespace = 'test-namespace';
+      const ttl = 3600;
+      const fallbackStore = { some: 'store' };
+
+      standardCache(namespace, ttl, fallbackStore);
+
+      expect(mockKeyv).toHaveBeenCalledWith({ store: fallbackStore, namespace, ttl });
+    });
+
+    it('should create default Keyv instance when USE_REDIS is false and no fallbackStore', () => {
+      cacheConfig.USE_REDIS = false;
+      const namespace = 'test-namespace';
+      const ttl = 3600;
+
+      standardCache(namespace, ttl);
+
+      expect(mockKeyv).toHaveBeenCalledWith({ namespace, ttl });
+    });
+
+    it('should handle namespace and ttl as undefined', () => {
+      cacheConfig.USE_REDIS = false;
+
+      standardCache();
+
+      expect(mockKeyv).toHaveBeenCalledWith({ namespace: undefined, ttl: undefined });
+    });
+  });
+
+  describe('violationCache', () => {
+    it('should create violation cache with prefixed namespace', () => {
+      const namespace = 'test-violations';
+      const ttl = 7200;
+
+      // We can't easily mock the internal redisCache call since it's in the same module
+      // But we can test that the function executes without throwing
+      expect(() => violationCache(namespace, ttl)).not.toThrow();
+    });
+
+    it('should create violation cache with undefined ttl', () => {
+      const namespace = 'test-violations';
+
+      violationCache(namespace);
+
+      // The function should call redisCache with violations: prefixed namespace
+      // Since we can't easily mock the internal redisCache call, we test the behavior
+      expect(() => violationCache(namespace)).not.toThrow();
+    });
+
+    it('should handle undefined namespace', () => {
+      expect(() => violationCache(undefined)).not.toThrow();
+    });
+  });
+
+  describe('sessionCache', () => {
+    it('should return MemoryStore when USE_REDIS is false', () => {
+      cacheConfig.USE_REDIS = false;
+      const namespace = 'sessions';
+      const ttl = 86400;
+
+      const result = sessionCache(namespace, ttl);
+
+      expect(mockMemoryStore).toHaveBeenCalledWith({ ttl, checkPeriod: Time.ONE_DAY });
+      expect(result).toBe(mockMemoryStore());
+    });
+
+    it('should return ConnectRedis when USE_REDIS is true', () => {
+      cacheConfig.USE_REDIS = true;
+      const namespace = 'sessions';
+      const ttl = 86400;
+
+      const result = sessionCache(namespace, ttl);
+
+      expect(mockConnectRedis).toHaveBeenCalledWith({
+        client: mockIoredisClient,
+        ttl,
+        prefix: `${namespace}:`,
+      });
+      expect(result).toBe(mockConnectRedis());
+    });
+
+    it('should add colon to namespace if not present', () => {
+      cacheConfig.USE_REDIS = true;
+      const namespace = 'sessions';
+
+      sessionCache(namespace);
+
+      expect(mockConnectRedis).toHaveBeenCalledWith({
+        client: mockIoredisClient,
+        ttl: undefined,
+        prefix: 'sessions:',
+      });
+    });
+
+    it('should not add colon to namespace if already present', () => {
+      cacheConfig.USE_REDIS = true;
+      const namespace = 'sessions:';
+
+      sessionCache(namespace);
+
+      expect(mockConnectRedis).toHaveBeenCalledWith({
+        client: mockIoredisClient,
+        ttl: undefined,
+        prefix: 'sessions:',
+      });
+    });
+
+    it('should handle undefined ttl', () => {
+      cacheConfig.USE_REDIS = false;
+      const namespace = 'sessions';
+
+      sessionCache(namespace);
+
+      expect(mockMemoryStore).toHaveBeenCalledWith({
+        ttl: undefined,
+        checkPeriod: Time.ONE_DAY,
+      });
+    });
+  });
+
+  describe('limiterCache', () => {
+    it('should return undefined when USE_REDIS is false', () => {
+      cacheConfig.USE_REDIS = false;
+      const result = limiterCache('prefix');
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should return RedisStore when USE_REDIS is true', () => {
+      cacheConfig.USE_REDIS = true;
+      const result = limiterCache('rate-limit');
+
+      expect(mockRedisStore).toHaveBeenCalledWith({
+        sendCommand: expect.any(Function),
+        prefix: `rate-limit:`,
+      });
+      expect(result).toBe(mockRedisStore());
+    });
+
+    it('should add colon to prefix if not present', () => {
+      cacheConfig.USE_REDIS = true;
+      limiterCache('rate-limit');
+
+      expect(mockRedisStore).toHaveBeenCalledWith({
+        sendCommand: expect.any(Function),
+        prefix: 'rate-limit:',
+      });
+    });
+
+    it('should not add colon to prefix if already present', () => {
+      cacheConfig.USE_REDIS = true;
+      limiterCache('rate-limit:');
+
+      expect(mockRedisStore).toHaveBeenCalledWith({
+        sendCommand: expect.any(Function),
+        prefix: 'rate-limit:',
+      });
+    });
+
+    it('should pass sendCommand function that calls ioredisClient.call', () => {
+      cacheConfig.USE_REDIS = true;
+      limiterCache('rate-limit');
+
+      const sendCommandCall = mockRedisStore.mock.calls[0][0];
+      const sendCommand = sendCommandCall.sendCommand;
+
+      // Test that sendCommand properly delegates to ioredisClient.call
+      const args = ['GET', 'test-key'];
+      sendCommand(...args);
+
+      expect(mockIoredisClient.call).toHaveBeenCalledWith(...args);
+    });
+
+    it('should handle undefined prefix', () => {
+      cacheConfig.USE_REDIS = true;
+      expect(() => limiterCache()).toThrow('prefix is required');
+    });
+  });
+});

api/cache/getLogStores.js

@@ -1,113 +1,52 @@
+const { cacheConfig } = require('./cacheConfig');
 const { Keyv } = require('keyv');
-const { isEnabled, math } = require('@librechat/api');
 const { CacheKeys, ViolationTypes, Time } = require('librechat-data-provider');
-const { logFile, violationFile } = require('./keyvFiles');
-const keyvRedis = require('./keyvRedis');
+const { logFile } = require('./keyvFiles');
 const keyvMongo = require('./keyvMongo');
-
-const { BAN_DURATION, USE_REDIS, DEBUG_MEMORY_CACHE, CI } = process.env ?? {};
-
-const duration = math(BAN_DURATION, 7200000);
-const isRedisEnabled = isEnabled(USE_REDIS);
-const debugMemoryCache = isEnabled(DEBUG_MEMORY_CACHE);
-
-const createViolationInstance = (namespace) => {
-  const config = isRedisEnabled ? { store: keyvRedis } : { store: violationFile, namespace };
-  return new Keyv(config);
-};
-
-// Serve cache from memory so no need to clear it on startup/exit
-const pending_req = isRedisEnabled
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.PENDING_REQ });
-
-const config = isRedisEnabled
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.CONFIG_STORE });
-
-const roles = isRedisEnabled
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.ROLES });
-
-const mcpTools = isRedisEnabled
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.MCP_TOOLS });
-
-const audioRuns = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.TEN_MINUTES })
-  : new Keyv({ namespace: CacheKeys.AUDIO_RUNS, ttl: Time.TEN_MINUTES });
-
-const messages = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.ONE_MINUTE })
-  : new Keyv({ namespace: CacheKeys.MESSAGES, ttl: Time.ONE_MINUTE });
-
-const flows = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.TWO_MINUTES })
-  : new Keyv({ namespace: CacheKeys.FLOWS, ttl: Time.ONE_MINUTE * 3 });
-
-const tokenConfig = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.THIRTY_MINUTES })
-  : new Keyv({ namespace: CacheKeys.TOKEN_CONFIG, ttl: Time.THIRTY_MINUTES });
-
-const genTitle = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.TWO_MINUTES })
-  : new Keyv({ namespace: CacheKeys.GEN_TITLE, ttl: Time.TWO_MINUTES });
-
-const s3ExpiryInterval = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.THIRTY_MINUTES })
-  : new Keyv({ namespace: CacheKeys.S3_EXPIRY_INTERVAL, ttl: Time.THIRTY_MINUTES });
-
-const modelQueries = isEnabled(process.env.USE_REDIS)
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.MODEL_QUERIES });
-
-const abortKeys = isRedisEnabled
-  ? new Keyv({ store: keyvRedis })
-  : new Keyv({ namespace: CacheKeys.ABORT_KEYS, ttl: Time.TEN_MINUTES });
-
-const openIdExchangedTokensCache = isRedisEnabled
-  ? new Keyv({ store: keyvRedis, ttl: Time.TEN_MINUTES })
-  : new Keyv({ namespace: CacheKeys.OPENID_EXCHANGED_TOKENS, ttl: Time.TEN_MINUTES });
+const { standardCache, sessionCache, violationCache } = require('./cacheFactory');
 
 const namespaces = {
-  [CacheKeys.ROLES]: roles,
-  [CacheKeys.MCP_TOOLS]: mcpTools,
-  [CacheKeys.CONFIG_STORE]: config,
-  [CacheKeys.PENDING_REQ]: pending_req,
-  [ViolationTypes.BAN]: new Keyv({ store: keyvMongo, namespace: CacheKeys.BANS, ttl: duration }),
-  [CacheKeys.ENCODED_DOMAINS]: new Keyv({
+  [ViolationTypes.GENERAL]: new Keyv({ store: logFile, namespace: 'violations' }),
+  [ViolationTypes.LOGINS]: violationCache(ViolationTypes.LOGINS),
+  [ViolationTypes.CONCURRENT]: violationCache(ViolationTypes.CONCURRENT),
+  [ViolationTypes.NON_BROWSER]: violationCache(ViolationTypes.NON_BROWSER),
+  [ViolationTypes.MESSAGE_LIMIT]: violationCache(ViolationTypes.MESSAGE_LIMIT),
+  [ViolationTypes.REGISTRATIONS]: violationCache(ViolationTypes.REGISTRATIONS),
+  [ViolationTypes.TOKEN_BALANCE]: violationCache(ViolationTypes.TOKEN_BALANCE),
+  [ViolationTypes.TTS_LIMIT]: violationCache(ViolationTypes.TTS_LIMIT),
+  [ViolationTypes.STT_LIMIT]: violationCache(ViolationTypes.STT_LIMIT),
+  [ViolationTypes.CONVO_ACCESS]: violationCache(ViolationTypes.CONVO_ACCESS),
+  [ViolationTypes.TOOL_CALL_LIMIT]: violationCache(ViolationTypes.TOOL_CALL_LIMIT),
+  [ViolationTypes.FILE_UPLOAD_LIMIT]: violationCache(ViolationTypes.FILE_UPLOAD_LIMIT),
+  [ViolationTypes.VERIFY_EMAIL_LIMIT]: violationCache(ViolationTypes.VERIFY_EMAIL_LIMIT),
+  [ViolationTypes.RESET_PASSWORD_LIMIT]: violationCache(ViolationTypes.RESET_PASSWORD_LIMIT),
+  [ViolationTypes.ILLEGAL_MODEL_REQUEST]: violationCache(ViolationTypes.ILLEGAL_MODEL_REQUEST),
+  [ViolationTypes.BAN]: new Keyv({
     store: keyvMongo,
-    namespace: CacheKeys.ENCODED_DOMAINS,
-    ttl: 0,
+    namespace: CacheKeys.BANS,
+    ttl: cacheConfig.BAN_DURATION,
   }),
-  general: new Keyv({ store: logFile, namespace: 'violations' }),
-  concurrent: createViolationInstance('concurrent'),
-  non_browser: createViolationInstance('non_browser'),
-  message_limit: createViolationInstance('message_limit'),
-  token_balance: createViolationInstance(ViolationTypes.TOKEN_BALANCE),
-  registrations: createViolationInstance('registrations'),
-  [ViolationTypes.TTS_LIMIT]: createViolationInstance(ViolationTypes.TTS_LIMIT),
-  [ViolationTypes.STT_LIMIT]: createViolationInstance(ViolationTypes.STT_LIMIT),
-  [ViolationTypes.CONVO_ACCESS]: createViolationInstance(ViolationTypes.CONVO_ACCESS),
-  [ViolationTypes.TOOL_CALL_LIMIT]: createViolationInstance(ViolationTypes.TOOL_CALL_LIMIT),
-  [ViolationTypes.FILE_UPLOAD_LIMIT]: createViolationInstance(ViolationTypes.FILE_UPLOAD_LIMIT),
-  [ViolationTypes.VERIFY_EMAIL_LIMIT]: createViolationInstance(ViolationTypes.VERIFY_EMAIL_LIMIT),
-  [ViolationTypes.RESET_PASSWORD_LIMIT]: createViolationInstance(
-    ViolationTypes.RESET_PASSWORD_LIMIT,
+
+  [CacheKeys.OPENID_SESSION]: sessionCache(CacheKeys.OPENID_SESSION),
+  [CacheKeys.SAML_SESSION]: sessionCache(CacheKeys.SAML_SESSION),
+
+  [CacheKeys.ROLES]: standardCache(CacheKeys.ROLES),
+  [CacheKeys.MCP_TOOLS]: standardCache(CacheKeys.MCP_TOOLS),
+  [CacheKeys.CONFIG_STORE]: standardCache(CacheKeys.CONFIG_STORE),
+  [CacheKeys.PENDING_REQ]: standardCache(CacheKeys.PENDING_REQ),
+  [CacheKeys.ENCODED_DOMAINS]: new Keyv({ store: keyvMongo, namespace: CacheKeys.ENCODED_DOMAINS }),
+  [CacheKeys.ABORT_KEYS]: standardCache(CacheKeys.ABORT_KEYS, Time.TEN_MINUTES),
+  [CacheKeys.TOKEN_CONFIG]: standardCache(CacheKeys.TOKEN_CONFIG, Time.THIRTY_MINUTES),
+  [CacheKeys.GEN_TITLE]: standardCache(CacheKeys.GEN_TITLE, Time.TWO_MINUTES),
+  [CacheKeys.S3_EXPIRY_INTERVAL]: standardCache(CacheKeys.S3_EXPIRY_INTERVAL, Time.THIRTY_MINUTES),
+  [CacheKeys.MODEL_QUERIES]: standardCache(CacheKeys.MODEL_QUERIES),
+  [CacheKeys.AUDIO_RUNS]: standardCache(CacheKeys.AUDIO_RUNS, Time.TEN_MINUTES),
+  [CacheKeys.MESSAGES]: standardCache(CacheKeys.MESSAGES, Time.ONE_MINUTE),
+  [CacheKeys.FLOWS]: standardCache(CacheKeys.FLOWS, Time.ONE_MINUTE * 3),
+  [CacheKeys.OPENID_EXCHANGED_TOKENS]: standardCache(
+    CacheKeys.OPENID_EXCHANGED_TOKENS,
+    Time.TEN_MINUTES,
   ),
-  [ViolationTypes.ILLEGAL_MODEL_REQUEST]: createViolationInstance(
-    ViolationTypes.ILLEGAL_MODEL_REQUEST,
-  ),
-  logins: createViolationInstance('logins'),
-  [CacheKeys.ABORT_KEYS]: abortKeys,
-  [CacheKeys.TOKEN_CONFIG]: tokenConfig,
-  [CacheKeys.GEN_TITLE]: genTitle,
-  [CacheKeys.S3_EXPIRY_INTERVAL]: s3ExpiryInterval,
-  [CacheKeys.MODEL_QUERIES]: modelQueries,
-  [CacheKeys.AUDIO_RUNS]: audioRuns,
-  [CacheKeys.MESSAGES]: messages,
-  [CacheKeys.FLOWS]: flows,
-  [CacheKeys.OPENID_EXCHANGED_TOKENS]: openIdExchangedTokensCache,
 };
 
 /**
@@ -116,7 +55,10 @@ const namespaces = {
  */
 function getTTLStores() {
   return Object.values(namespaces).filter(
-    (store) => store instanceof Keyv && typeof store.opts?.ttl === 'number' && store.opts.ttl > 0,
+    (store) =>
+      store instanceof Keyv &&
+      parseInt(store.opts?.ttl ?? '0') > 0 &&
+      !store.opts?.store?.constructor?.name?.includes('Redis'), // Only include non-Redis stores
   );
 }
 
@@ -152,18 +94,18 @@ async function clearExpiredFromCache(cache) {
       if (data?.expires && data.expires <= expiryTime) {
         const deleted = await cache.opts.store.delete(key);
         if (!deleted) {
-          debugMemoryCache &&
+          cacheConfig.DEBUG_MEMORY_CACHE &&
             console.warn(`[Cache] Error deleting entry: ${key} from ${cache.opts.namespace}`);
           continue;
         }
         cleared++;
       }
     } catch (error) {
-      debugMemoryCache &&
+      cacheConfig.DEBUG_MEMORY_CACHE &&
         console.log(`[Cache] Error processing entry from ${cache.opts.namespace}:`, error);
       const deleted = await cache.opts.store.delete(key);
       if (!deleted) {
-        debugMemoryCache &&
+        cacheConfig.DEBUG_MEMORY_CACHE &&
           console.warn(`[Cache] Error deleting entry: ${key} from ${cache.opts.namespace}`);
         continue;
       }
@@ -172,7 +114,7 @@ async function clearExpiredFromCache(cache) {
   }
 
   if (cleared > 0) {
-    debugMemoryCache &&
+    cacheConfig.DEBUG_MEMORY_CACHE &&
       console.log(
         `[Cache] Cleared ${cleared} entries older than ${ttl}ms from ${cache.opts.namespace}`,
       );
@@ -213,7 +155,7 @@ async function clearAllExpiredFromCache() {
   }
 }
 
-if (!isRedisEnabled && !isEnabled(CI)) {
+if (!cacheConfig.USE_REDIS && !cacheConfig.CI) {
   /** @type {Set<NodeJS.Timeout>} */
   const cleanupIntervals = new Set();
 
@@ -224,7 +166,7 @@ if (!isRedisEnabled && !isEnabled(CI)) {
 
   cleanupIntervals.add(cleanup);
 
-  if (debugMemoryCache) {
+  if (cacheConfig.DEBUG_MEMORY_CACHE) {
     const monitor = setInterval(() => {
       const ttlStores = getTTLStores();
       const memory = process.memoryUsage();
@@ -245,13 +187,13 @@ if (!isRedisEnabled && !isEnabled(CI)) {
   }
 
   const dispose = () => {
-    debugMemoryCache && console.log('[Cache] Cleaning up and shutting down...');
+    cacheConfig.DEBUG_MEMORY_CACHE && console.log('[Cache] Cleaning up and shutting down...');
     cleanupIntervals.forEach((interval) => clearInterval(interval));
     cleanupIntervals.clear();
 
     // One final cleanup before exit
     clearAllExpiredFromCache().then(() => {
-      debugMemoryCache && console.log('[Cache] Final cleanup completed');
+      cacheConfig.DEBUG_MEMORY_CACHE && console.log('[Cache] Final cleanup completed');
       process.exit(0);
     });
   };

api/cache/ioredisClient.js

@@ -1,92 +0,0 @@
-const fs = require('fs');
-const Redis = require('ioredis');
-const { isEnabled } = require('~/server/utils');
-const logger = require('~/config/winston');
-
-const { REDIS_URI, USE_REDIS, USE_REDIS_CLUSTER, REDIS_CA, REDIS_MAX_LISTENERS } = process.env;
-
-/** @type {import('ioredis').Redis | import('ioredis').Cluster} */
-let ioredisClient;
-const redis_max_listeners = Number(REDIS_MAX_LISTENERS) || 40;
-
-function mapURI(uri) {
-  const regex =
-    /^(?:(?<scheme>\w+):\/\/)?(?:(?<user>[^:@]+)(?::(?<password>[^@]+))?@)?(?<host>[\w.-]+)(?::(?<port>\d{1,5}))?$/;
-  const match = uri.match(regex);
-
-  if (match) {
-    const { scheme, user, password, host, port } = match.groups;
-
-    return {
-      scheme: scheme || 'none',
-      user: user || null,
-      password: password || null,
-      host: host || null,
-      port: port || null,
-    };
-  } else {
-    const parts = uri.split(':');
-    if (parts.length === 2) {
-      return {
-        scheme: 'none',
-        user: null,
-        password: null,
-        host: parts[0],
-        port: parts[1],
-      };
-    }
-
-    return {
-      scheme: 'none',
-      user: null,
-      password: null,
-      host: uri,
-      port: null,
-    };
-  }
-}
-
-if (REDIS_URI && isEnabled(USE_REDIS)) {
-  let redisOptions = null;
-
-  if (REDIS_CA) {
-    const ca = fs.readFileSync(REDIS_CA);
-    redisOptions = { tls: { ca } };
-  }
-
-  if (isEnabled(USE_REDIS_CLUSTER)) {
-    const hosts = REDIS_URI.split(',').map((item) => {
-      var value = mapURI(item);
-
-      return {
-        host: value.host,
-        port: value.port,
-      };
-    });
-    ioredisClient = new Redis.Cluster(hosts, { redisOptions });
-  } else {
-    ioredisClient = new Redis(REDIS_URI, redisOptions);
-  }
-
-  ioredisClient.on('ready', () => {
-    logger.info('IoRedis connection ready');
-  });
-  ioredisClient.on('reconnecting', () => {
-    logger.info('IoRedis connection reconnecting');
-  });
-  ioredisClient.on('end', () => {
-    logger.info('IoRedis connection ended');
-  });
-  ioredisClient.on('close', () => {
-    logger.info('IoRedis connection closed');
-  });
-  ioredisClient.on('error', (err) => logger.error('IoRedis connection error:', err));
-  ioredisClient.setMaxListeners(redis_max_listeners);
-  logger.info(
-    '[Optional] IoRedis initialized for rate limiters. If you have issues, disable Redis or restart the server.',
-  );
-} else {
-  logger.info('[Optional] IoRedis not initialized for rate limiters.');
-}
-
-module.exports = ioredisClient;

api/cache/keyvRedis.js

@@ -1,109 +0,0 @@
-const fs = require('fs');
-const ioredis = require('ioredis');
-const KeyvRedis = require('@keyv/redis').default;
-const { isEnabled } = require('~/server/utils');
-const logger = require('~/config/winston');
-
-const { REDIS_URI, USE_REDIS, USE_REDIS_CLUSTER, REDIS_CA, REDIS_KEY_PREFIX, REDIS_MAX_LISTENERS } =
-  process.env;
-
-let keyvRedis;
-const redis_prefix = REDIS_KEY_PREFIX || '';
-const redis_max_listeners = Number(REDIS_MAX_LISTENERS) || 40;
-
-function mapURI(uri) {
-  const regex =
-    /^(?:(?<scheme>\w+):\/\/)?(?:(?<user>[^:@]+)(?::(?<password>[^@]+))?@)?(?<host>[\w.-]+)(?::(?<port>\d{1,5}))?$/;
-  const match = uri.match(regex);
-
-  if (match) {
-    const { scheme, user, password, host, port } = match.groups;
-
-    return {
-      scheme: scheme || 'none',
-      user: user || null,
-      password: password || null,
-      host: host || null,
-      port: port || null,
-    };
-  } else {
-    const parts = uri.split(':');
-    if (parts.length === 2) {
-      return {
-        scheme: 'none',
-        user: null,
-        password: null,
-        host: parts[0],
-        port: parts[1],
-      };
-    }
-
-    return {
-      scheme: 'none',
-      user: null,
-      password: null,
-      host: uri,
-      port: null,
-    };
-  }
-}
-
-if (REDIS_URI && isEnabled(USE_REDIS)) {
-  let redisOptions = null;
-  /** @type {import('@keyv/redis').KeyvRedisOptions} */
-  let keyvOpts = {
-    useRedisSets: false,
-    keyPrefix: redis_prefix,
-  };
-
-  if (REDIS_CA) {
-    const ca = fs.readFileSync(REDIS_CA);
-    redisOptions = { tls: { ca } };
-  }
-
-  if (isEnabled(USE_REDIS_CLUSTER)) {
-    const hosts = REDIS_URI.split(',').map((item) => {
-      var value = mapURI(item);
-
-      return {
-        host: value.host,
-        port: value.port,
-      };
-    });
-    const cluster = new ioredis.Cluster(hosts, { redisOptions });
-    keyvRedis = new KeyvRedis(cluster, keyvOpts);
-  } else {
-    keyvRedis = new KeyvRedis(REDIS_URI, keyvOpts);
-  }
-
-  const pingInterval = setInterval(
-    () => {
-      logger.debug('KeyvRedis ping');
-      keyvRedis.client.ping().catch((err) => logger.error('Redis keep-alive ping failed:', err));
-    },
-    5 * 60 * 1000,
-  );
-
-  keyvRedis.on('ready', () => {
-    logger.info('KeyvRedis connection ready');
-  });
-  keyvRedis.on('reconnecting', () => {
-    logger.info('KeyvRedis connection reconnecting');
-  });
-  keyvRedis.on('end', () => {
-    logger.info('KeyvRedis connection ended');
-  });
-  keyvRedis.on('close', () => {
-    clearInterval(pingInterval);
-    logger.info('KeyvRedis connection closed');
-  });
-  keyvRedis.on('error', (err) => logger.error('KeyvRedis connection error:', err));
-  keyvRedis.setMaxListeners(redis_max_listeners);
-  logger.info(
-    '[Optional] Redis initialized. If you have issues, or seeing older values, disable it or flush cache to refresh values.',
-  );
-} else {
-  logger.info('[Optional] Redis not initialized.');
-}
-
-module.exports = keyvRedis;

api/cache/logViolation.js

@@ -1,4 +1,5 @@
 const { isEnabled } = require('~/server/utils');
+const { ViolationTypes } = require('librechat-data-provider');
 const getLogStores = require('./getLogStores');
 const banViolation = require('./banViolation');
 
@@ -16,7 +17,7 @@ const logViolation = async (req, res, type, errorMessage, score = 1) => {
   if (!userId) {
     return;
   }
-  const logs = getLogStores('general');
+  const logs = getLogStores(ViolationTypes.GENERAL);
   const violationLogs = getLogStores(type);
   const key = isEnabled(process.env.USE_REDIS) ? `${type}:${userId}` : userId;
 

api/cache/redisClients.js

@@ -0,0 +1,57 @@
+const IoRedis = require('ioredis');
+const { cacheConfig } = require('./cacheConfig');
+const { createClient, createCluster } = require('@keyv/redis');
+
+const GLOBAL_PREFIX_SEPARATOR = '::';
+
+const urls = cacheConfig.REDIS_URI?.split(',').map((uri) => new URL(uri));
+const username = urls?.[0].username || cacheConfig.REDIS_USERNAME;
+const password = urls?.[0].password || cacheConfig.REDIS_PASSWORD;
+const ca = cacheConfig.REDIS_CA;
+
+/** @type {import('ioredis').Redis | import('ioredis').Cluster | null} */
+let ioredisClient = null;
+if (cacheConfig.USE_REDIS) {
+  const redisOptions = {
+    username: username,
+    password: password,
+    tls: ca ? { ca } : undefined,
+    keyPrefix: `${cacheConfig.REDIS_KEY_PREFIX}${GLOBAL_PREFIX_SEPARATOR}`,
+    maxListeners: cacheConfig.REDIS_MAX_LISTENERS,
+  };
+
+  ioredisClient =
+    urls.length === 1
+      ? new IoRedis(cacheConfig.REDIS_URI, redisOptions)
+      : new IoRedis.Cluster(cacheConfig.REDIS_URI, { redisOptions });
+
+  // Pinging the Redis server every 5 minutes to keep the connection alive
+  const pingInterval = setInterval(() => ioredisClient.ping(), 5 * 60 * 1000);
+  ioredisClient.on('close', () => clearInterval(pingInterval));
+  ioredisClient.on('end', () => clearInterval(pingInterval));
+}
+
+/** @type {import('@keyv/redis').RedisClient | import('@keyv/redis').RedisCluster | null} */
+let keyvRedisClient = null;
+if (cacheConfig.USE_REDIS) {
+  // ** WARNING ** Keyv Redis client does not support Prefix like ioredis above.
+  // The prefix feature will be handled by the Keyv-Redis store in cacheFactory.js
+  const redisOptions = { username, password, socket: { tls: ca != null, ca } };
+
+  keyvRedisClient =
+    urls.length === 1
+      ? createClient({ url: cacheConfig.REDIS_URI, ...redisOptions })
+      : createCluster({
+          rootNodes: cacheConfig.REDIS_URI.split(',').map((url) => ({ url })),
+          defaults: redisOptions,
+        });
+
+  keyvRedisClient.setMaxListeners(cacheConfig.REDIS_MAX_LISTENERS);
+
+  // Pinging the Redis server every 5 minutes to keep the connection alive
+  const keyvPingInterval = setInterval(() => keyvRedisClient.ping(), 5 * 60 * 1000);
+  keyvRedisClient.on('disconnect', () => clearInterval(keyvPingInterval));
+  keyvRedisClient.on('end', () => clearInterval(keyvPingInterval));
+}
+
+module.exports = { ioredisClient, keyvRedisClient, GLOBAL_PREFIX_SEPARATOR };