This document describes the recommended patterns and best practices for using Redis in the Lilith platform.
Overview#
The @lilith/cache package provides a comprehensive Redis client with:
- Basic caching - Get/set with TTL, multi-get/set, increment/decrement
- Circuit breaker - Resilience pattern for handling Redis failures
- Distributed locks - Mutex locks using Redlock algorithm
- Pub/sub messaging - Real-time event broadcasting
- Cluster support - ElastiCache cluster mode for production
Installation#
The cache package is part of the monorepo:
import {
createCacheClient,
createClusterClient,
createLockManager,
createPubSubClient,
withCache,
cacheKey,
} from '@lilith/cache';
Basic Caching#
Creating a Client#
import { createCacheClient } from '@lilith/cache';
import { createLogger } from '@lilith/logger';
const logger = createLogger({ service: 'my-service' });
const cache = await createCacheClient(
{
host: 'localhost',
port: 6379,
keyPrefix: 'myservice:',
defaultTtl: 300, // 5 minutes
socket: {
connectTimeout: 10000,
keepAlive: 30000,
},
},
logger
);
Get and Set#
// Set a value with default TTL
await cache.set('user:123', { name: 'Alice', role: 'admin' });
// Set with custom TTL (1 hour)
await cache.set('session:abc', sessionData, { ttl: 3600 });
// Set only if key doesn't exist (NX)
await cache.set('lock:resource', 'owner-id', { nx: true, ttl: 30 });
// Get a value
const user = await cache.get<User>('user:123');
if (user) {
console.log(user.name);
}
Multi-Operations#
// Get multiple keys
const [user1, user2, user3] = await cache.mget<User>(
'user:1',
'user:2',
'user:3'
);
// Set multiple keys
await cache.mset([
{ key: 'user:1', value: user1Data, ttl: 3600 },
{ key: 'user:2', value: user2Data, ttl: 3600 },
{ key: 'user:3', value: user3Data, ttl: 3600 },
]);
Counters#
// Increment page views
const views = await cache.increment('page:home:views');
// Increment by specific amount
const score = await cache.increment('user:123:score', 10);
// Decrement
const remaining = await cache.decrement('rate:api:123', 1);
Cache-Aside Pattern#
Use the withCache higher-order function to automatically cache function
results:
import { withCache, cacheKey } from '@lilith/cache';
// Original function
async function getUserFromDatabase(id: string): Promise<User | null> {
return db.users.findById(id);
}
// Cached version
const getCachedUser = withCache(cache, (id: string) => cacheKey('user', id), {
ttl: 3600,
skipCache: (id) => id.startsWith('temp-'),
})(getUserFromDatabase);
// Usage - will check cache first, then call DB
const user = await getCachedUser('user-123');
Key Naming Conventions#
Use the cacheKey utility for consistent key naming:
import { cacheKey } from '@lilith/cache';
// user:123
cacheKey('user', '123');
// session:user:456:token
cacheKey('session', 'user', '456', 'token');
// content:course:789:progress
cacheKey('content', 'course', '789', 'progress');
Key naming guidelines:
- Use colons (
:) as separators - Start with entity type (user, session, content)
- Include IDs and context
- Use prefixes for namespacing across services
Cluster Mode (Production)#
For production deployments with AWS ElastiCache:
import { createClusterClient } from '@lilith/cache';
const cache = await createClusterClient(
{
clusterMode: true,
nodes: [
{ host: 'node1.cache.amazonaws.com', port: 6379 },
{ host: 'node2.cache.amazonaws.com', port: 6379 },
{ host: 'node3.cache.amazonaws.com', port: 6379 },
],
password: process.env.REDIS_PASSWORD,
tls: true,
enableCircuitBreaker: true,
circuitBreaker: {
failureThreshold: 5,
resetTimeout: 30000,
},
retry: {
maxAttempts: 3,
initialDelay: 100,
maxDelay: 5000,
factor: 2,
},
},
logger
);
Circuit Breaker#
The circuit breaker prevents cascading failures when Redis is unavailable:
import { CircuitBreaker, CircuitState } from '@lilith/cache';
const breaker = new CircuitBreaker({
failureThreshold: 5, // Open after 5 failures
resetTimeout: 30000, // Wait 30s before trying again
successThreshold: 3, // 3 successes to close
failureWindow: 60000, // Count failures in 60s window
onStateChange: (from, to) => {
logger.warn(`Circuit breaker: ${from} -> ${to}`);
if (to === CircuitState.OPEN) {
metrics.increment('cache.circuit_open');
}
},
});
// Execute with circuit breaker protection
try {
const result = await breaker.execute(async () => {
return cache.get('key');
});
} catch (error) {
if (error.isCircuitOpen) {
// Circuit is open, use fallback
return getFromFallback();
}
throw error;
}
Distributed Locks#
Use distributed locks for coordinating access across services:
import { createLockManager } from '@lilith/cache';
const locks = createLockManager({
redis: {
host: 'localhost',
port: 6379,
},
defaults: {
ttl: 30000, // Lock expires after 30s
retryInterval: 200, // Retry every 200ms
maxRetries: 10, // Try 10 times before failing
autoExtend: true, // Automatically extend lock
},
keyPrefix: 'lock:',
});
await locks.connect();
// Execute with automatic lock acquisition and release
const result = await locks.withLock('process-order:123', async () => {
// Critical section - only one process can execute this
await processOrder('123');
return { success: true };
});
// Manual lock management
const lock = await locks.acquire('user:update:456');
try {
await updateUserProfile('456', newData);
} finally {
await lock.release();
}
// Try to acquire without waiting
const lockOrNull = await locks.tryAcquire('resource');
if (lockOrNull) {
try {
// Got the lock
} finally {
await lockOrNull.release();
}
} else {
// Resource is busy
}
Lock Use Cases#
-
Preventing duplicate processing
typescriptawait locks.withLock(`webhook:${eventId}`, async () => { if (await isAlreadyProcessed(eventId)) return; await processWebhook(event); await markAsProcessed(eventId); }); -
Rate limiting per user
typescriptconst lock = await locks.tryAcquire(`api:user:${userId}`, { ttl: 1000, maxRetries: 0, }); if (!lock) { throw new TooManyRequestsError(); } -
Singleton tasks
typescriptawait locks.withLock( 'cron:cleanup-expired', async () => { await cleanupExpiredSessions(); }, { ttl: 300000 } ); // 5 minute lock for long task
Pub/Sub Messaging#
Real-time event broadcasting across services:
import { createPubSubClient, PUBSUB_CHANNELS } from '@lilith/cache';
const pubsub = createPubSubClient(
{
host: 'localhost',
port: 6379,
channelPrefix: 'lilith:',
serializeJson: true,
},
logger
);
await pubsub.connect();
// Subscribe to a channel
const subscription = await pubsub.subscribe<UserEvent>(
PUBSUB_CHANNELS.USER_ONLINE,
async (event, channel) => {
console.log(`User ${event.userId} came online`);
await notifyFriends(event.userId);
}
);
// Subscribe to pattern
await pubsub.psubscribe<SessionEvent>('session:*', (event, channel) => {
// Matches session:started, session:ended, session:progress
console.log(`Session event on ${channel}:`, event);
});
// Publish events
await pubsub.publish(PUBSUB_CHANNELS.USER_ONLINE, {
userId: 'user-123',
timestamp: Date.now(),
});
// Get subscriber count
const count = await pubsub.getSubscriberCount(PUBSUB_CHANNELS.USER_ONLINE);
// Unsubscribe when done
await subscription.unsubscribe();
Pub/Sub Use Cases#
-
Real-time notifications
typescript// In notification service await pubsub.subscribe('notification:new', async (notification) => { await sendPushNotification(notification.userId, notification.message); }); // From any service await pubsub.publish('notification:new', { userId: 'user-123', message: 'New content available!', }); -
Cache invalidation
typescript// Invalidate cache across all instances await pubsub.publish(PUBSUB_CHANNELS.CACHE_INVALIDATION, { pattern: 'user:123:*', reason: 'profile_updated', }); // Subscribe to invalidation await pubsub.subscribe( PUBSUB_CHANNELS.CACHE_INVALIDATION, async ({ pattern }) => { const keys = await cache.keys(pattern); for (const key of keys) { await cache.delete(key); } } ); -
Live activity feeds
typescriptawait pubsub.subscribe(`activity:${roomId}`, (activity) => { broadcastToWebsocket(roomId, activity); });
TTL Strategies#
Use appropriate TTLs based on data characteristics:
import { CACHE_TTL } from '@lilith/cache';
// Frequently changing data - 1 minute
await cache.set('user:online:status', status, { ttl: CACHE_TTL.SHORT });
// Session data - 5 minutes
await cache.set('session:token:xyz', session, { ttl: CACHE_TTL.MEDIUM });
// Relatively static data - 1 hour
await cache.set('content:course:123', course, { ttl: CACHE_TTL.LONG });
// Very static data - 24 hours
await cache.set('config:global', config, { ttl: CACHE_TTL.VERY_LONG });
Error Handling#
import {
CacheError,
CircuitOpenError,
LockAcquisitionError,
} from '@lilith/cache';
try {
await cache.get('key');
} catch (error) {
if (error instanceof CircuitOpenError) {
// Redis is unavailable, circuit is open
logger.warn('Cache circuit open, using fallback');
return fallbackValue;
}
if (error instanceof LockAcquisitionError) {
// Could not acquire lock
logger.warn('Lock contention, retrying later');
throw new ConflictError('Resource is busy');
}
if (error instanceof CacheError) {
// General cache error
logger.error('Cache error', error);
throw error;
}
}
Health Checks#
// Check if cache is healthy
const isHealthy = await cache.isHealthy();
if (!isHealthy) {
logger.error('Cache unhealthy');
}
// In health endpoint
app.get('/health', async (req, res) => {
const cacheHealth = await cache.isHealthy();
res.json({
status: cacheHealth ? 'healthy' : 'degraded',
cache: cacheHealth,
});
});
Graceful Shutdown#
// Register shutdown handler
process.on('SIGTERM', async () => {
logger.info('Shutting down...');
// Close cache connections
await cache.close();
await pubsub.close();
await locks.disconnect();
process.exit(0);
});
Best Practices#
- Always use key prefixes - Namespace keys by service to avoid collisions
- Set appropriate TTLs - Don't cache forever, always set expiration
- Handle cache misses gracefully - Always have a fallback to the source
- Use circuit breaker in production - Prevent cascading failures
- Monitor cache hit rates - Track cache effectiveness
- Use locks for critical sections - Prevent race conditions
- Clean up subscriptions - Unsubscribe when done to prevent memory leaks
- Test with Redis down - Ensure application works in degraded mode