LibreChat/packages/api/src/cache/cacheConfig.ts
Danny Avila 6bc75d24c8
⚡️ refactor: Migrate @librechat/api build to tsdown (#13595)
* ⚡️ refactor: Migrate @librechat/api build to tsdown

Replace Rollup with tsdown (rolldown + oxc isolated-declarations) for the
@librechat/api package build, mirroring the merged data-schemas migration.

- Add tsdown.config.mjs (cjs output, oxc dts, externalize all bare deps,
  bundle first-party `~/` + relative imports)
- Annotate exports for isolatedDeclarations (codefix-driven). Collapse the
  tokens.ts model->token maps to Record<string, Record<string, number>> and
  switch validation.ts's runtime `files` field from z.any() to z.unknown()
  so no explicit `any` is introduced
- Repoint package.json main/types/exports to tsdown's .cjs/.d.cts output
- Add src/telemetry.ts entry shim so the two index.ts entries don't collide
  in oxc's flat dts output (stable dist/telemetry.{cjs,d.cts})
- Delete rollup.config.js

Build time ~36s -> ~0.5s. No runtime behavior change: 5712 unit tests pass,
both entries load via require(), legacy /api consumes them unchanged.

* 👷 ci: Hash packages/api/tsdown.config.mjs in build-api cache keys

The build-api cache keys hashed `packages/api/server-rollup.config.js`,
which never existed (api used `rollup.config.js`, now removed) — a copy-paste
artifact from the data-provider key that matched no file. Replace it with the
new `packages/api/tsdown.config.mjs` so edits to the build config (entry,
format, externals) bust the api build cache, matching the data-schemas key.
2026-06-08 10:54:48 -04:00

220 lines
10 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import { readFileSync, existsSync } from 'fs';
import { logger } from '@librechat/data-schemas';
import { CacheKeys } from 'librechat-data-provider';
import { math, isEnabled } from '~/utils';
// 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.');
}
// USE_REDIS_STREAMS controls whether Redis is used for resumable stream job storage.
// Defaults to true if USE_REDIS is enabled but USE_REDIS_STREAMS is not explicitly set.
// Set to 'false' to use in-memory storage for streams while keeping Redis for other caches.
const USE_REDIS_STREAMS =
process.env.USE_REDIS_STREAMS !== undefined
? isEnabled(process.env.USE_REDIS_STREAMS)
: USE_REDIS;
// Comma-separated list of cache namespaces that should be forced to use in-memory storage
// even when Redis is enabled. This allows selective performance optimization for specific caches.
// Defaults to CONFIG_STORE,APP_CONFIG so YAML-derived config stays per-container.
// Set to empty string to force all namespaces through Redis.
const FORCED_IN_MEMORY_CACHE_NAMESPACES =
process.env.FORCED_IN_MEMORY_CACHE_NAMESPACES !== undefined
? process.env.FORCED_IN_MEMORY_CACHE_NAMESPACES.split(',')
.map((key) => key.trim())
.filter(Boolean)
: [CacheKeys.CONFIG_STORE, CacheKeys.APP_CONFIG];
// Validate against CacheKeys enum
if (FORCED_IN_MEMORY_CACHE_NAMESPACES.length > 0) {
const validKeys = Object.values(CacheKeys) as string[];
const invalidKeys = FORCED_IN_MEMORY_CACHE_NAMESPACES.filter((key) => !validKeys.includes(key));
if (invalidKeys.length > 0) {
throw new Error(
`Invalid cache keys in FORCED_IN_MEMORY_CACHE_NAMESPACES: ${invalidKeys.join(', ')}. Valid keys: ${validKeys.join(', ')}`,
);
}
}
/** Helper function to safely read Redis CA certificate from file
* @returns {string|null} The contents of the CA certificate file, or null if not set or on error
*/
const getRedisCA = (): string | null => {
const caPath = process.env.REDIS_CA;
if (!caPath) {
return null;
}
try {
if (existsSync(caPath)) {
return readFileSync(caPath, 'utf8');
} else {
logger.warn(`Redis CA certificate file not found: ${caPath}`);
return null;
}
} catch (error) {
logger.error(`Failed to read Redis CA certificate file '${caPath}':`, error);
return null;
}
};
const cacheConfig: {
FORCED_IN_MEMORY_CACHE_NAMESPACES: string[];
USE_REDIS: boolean;
USE_REDIS_STREAMS: boolean;
REDIS_URI: string | undefined;
REDIS_USERNAME: string | undefined;
REDIS_PASSWORD: string | undefined;
REDIS_CA: string | null;
REDIS_KEY_PREFIX: string;
GLOBAL_PREFIX_SEPARATOR: string;
REDIS_MAX_LISTENERS: number;
REDIS_PING_INTERVAL: number;
/** Max delay between reconnection attempts in ms */
REDIS_RETRY_MAX_DELAY: number;
/** Max number of reconnection attempts (0 = infinite) */
REDIS_RETRY_MAX_ATTEMPTS: number;
/** Connection timeout in ms */
REDIS_CONNECT_TIMEOUT: number;
/** Queue commands when disconnected */
REDIS_ENABLE_OFFLINE_QUEUE: boolean;
/** flag to modify redis connection by adding dnsLookup this is required when connecting to elasticache for ioredis
* see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis **/
REDIS_USE_ALTERNATIVE_DNS_LOOKUP: boolean;
/** Enable redis cluster without the need of multiple URIs */
USE_REDIS_CLUSTER: boolean;
/**
* Force cluster-safe (key-by-key) deletion even when connecting as a single-node Redis instance.
* Needed for managed services like ElastiCache Serverless that present a single endpoint
* but shard keys internally, causing CROSSSLOT errors on multi-key DEL commands.
* Has no effect when USE_REDIS_CLUSTER is already true.
*/
REDIS_CLUSTER_SAFE_DELETE: boolean;
CI: boolean;
DEBUG_MEMORY_CACHE: boolean;
BAN_DURATION: number; // 2 hours
/**
* Number of keys to delete in each batch during Redis DEL operations.
* In cluster mode, keys are deleted individually in parallel chunks to avoid CROSSSLOT errors.
* In single-node mode, keys are deleted in batches using DEL with arrays.
* Lower values reduce memory usage but increase number of Redis calls.
* @default 1000
*/
REDIS_DELETE_CHUNK_SIZE: number;
/**
* Number of keys to update in each batch during Redis SET operations.
* In cluster mode, keys are updated individually in parallel chunks to avoid CROSSSLOT errors.
* In single-node mode, keys are updated in batches using transactions (multi/exec).
* Lower values reduce memory usage but increase number of Redis calls.
* @default 1000
*/
REDIS_UPDATE_CHUNK_SIZE: number;
/**
* COUNT hint for Redis SCAN operations when scanning keys by pattern.
* This is a hint to Redis about how many keys to scan in each iteration.
* Higher values can reduce round trips but increase memory usage and latency per call.
* Note: Redis may return more or fewer keys than this count depending on internal heuristics.
* @default 1000
*/
REDIS_SCAN_COUNT: number;
/**
* TTL in milliseconds for MCP registry caches. Used by both:
* - `MCPServersRegistry` read-through caches (`readThroughCache`/`readThroughCacheAll`)
* - `ServerConfigsCacheRedisAggregateKey` local snapshot (avoids redundant Redis GETs)
*
* Both layers use this value, so the effective max cross-instance staleness is up
* to 2× this value in multi-instance deployments. Set to 0 to disable the local
* snapshot entirely (every `getAll()` hits Redis directly).
* @default 5000 (5 seconds)
*/
MCP_REGISTRY_CACHE_TTL: number;
} = {
FORCED_IN_MEMORY_CACHE_NAMESPACES,
USE_REDIS,
USE_REDIS_STREAMS,
REDIS_URI: process.env.REDIS_URI,
REDIS_USERNAME: process.env.REDIS_USERNAME,
REDIS_PASSWORD: process.env.REDIS_PASSWORD,
REDIS_CA: getRedisCA(),
REDIS_KEY_PREFIX: process.env[REDIS_KEY_PREFIX_VAR ?? ''] || REDIS_KEY_PREFIX || '',
GLOBAL_PREFIX_SEPARATOR: '::',
REDIS_MAX_LISTENERS: math(process.env.REDIS_MAX_LISTENERS, 40),
REDIS_PING_INTERVAL: math(process.env.REDIS_PING_INTERVAL, 0),
/** Max delay between reconnection attempts in ms */
REDIS_RETRY_MAX_DELAY: math(process.env.REDIS_RETRY_MAX_DELAY, 3000),
/** Max number of reconnection attempts (0 = infinite) */
REDIS_RETRY_MAX_ATTEMPTS: math(process.env.REDIS_RETRY_MAX_ATTEMPTS, 10),
/** Connection timeout in ms */
REDIS_CONNECT_TIMEOUT: math(process.env.REDIS_CONNECT_TIMEOUT, 10000),
/** Queue commands when disconnected */
REDIS_ENABLE_OFFLINE_QUEUE: isEnabled(process.env.REDIS_ENABLE_OFFLINE_QUEUE ?? 'true'),
/** flag to modify redis connection by adding dnsLookup this is required when connecting to elasticache for ioredis
* see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis **/
REDIS_USE_ALTERNATIVE_DNS_LOOKUP: isEnabled(process.env.REDIS_USE_ALTERNATIVE_DNS_LOOKUP),
/** Enable redis cluster without the need of multiple URIs */
USE_REDIS_CLUSTER: isEnabled(process.env.USE_REDIS_CLUSTER ?? 'false'),
/**
* Force cluster-safe (key-by-key) deletion even when connecting as a single-node Redis instance.
* Needed for managed services like ElastiCache Serverless that present a single endpoint
* but shard keys internally, causing CROSSSLOT errors on multi-key DEL commands.
* Has no effect when USE_REDIS_CLUSTER is already true.
*/
REDIS_CLUSTER_SAFE_DELETE: isEnabled(process.env.REDIS_CLUSTER_SAFE_DELETE ?? 'false'),
CI: isEnabled(process.env.CI),
DEBUG_MEMORY_CACHE: isEnabled(process.env.DEBUG_MEMORY_CACHE),
BAN_DURATION: math(process.env.BAN_DURATION, 7200000), // 2 hours
/**
* Number of keys to delete in each batch during Redis DEL operations.
* In cluster mode, keys are deleted individually in parallel chunks to avoid CROSSSLOT errors.
* In single-node mode, keys are deleted in batches using DEL with arrays.
* Lower values reduce memory usage but increase number of Redis calls.
* @default 1000
*/
REDIS_DELETE_CHUNK_SIZE: math(process.env.REDIS_DELETE_CHUNK_SIZE, 1000),
/**
* Number of keys to update in each batch during Redis SET operations.
* In cluster mode, keys are updated individually in parallel chunks to avoid CROSSSLOT errors.
* In single-node mode, keys are updated in batches using transactions (multi/exec).
* Lower values reduce memory usage but increase number of Redis calls.
* @default 1000
*/
REDIS_UPDATE_CHUNK_SIZE: math(process.env.REDIS_UPDATE_CHUNK_SIZE, 1000),
/**
* COUNT hint for Redis SCAN operations when scanning keys by pattern.
* This is a hint to Redis about how many keys to scan in each iteration.
* Higher values can reduce round trips but increase memory usage and latency per call.
* Note: Redis may return more or fewer keys than this count depending on internal heuristics.
* @default 1000
*/
REDIS_SCAN_COUNT: math(process.env.REDIS_SCAN_COUNT, 1000),
/**
* TTL in milliseconds for MCP registry caches. Used by both:
* - `MCPServersRegistry` read-through caches (`readThroughCache`/`readThroughCacheAll`)
* - `ServerConfigsCacheRedisAggregateKey` local snapshot (avoids redundant Redis GETs)
*
* Both layers use this value, so the effective max cross-instance staleness is up
* to 2× this value in multi-instance deployments. Set to 0 to disable the local
* snapshot entirely (every `getAll()` hits Redis directly).
* @default 5000 (5 seconds)
*/
MCP_REGISTRY_CACHE_TTL: math(process.env.MCP_REGISTRY_CACHE_TTL, 5000),
};
export { cacheConfig };