Eve library

Redis Usage Patterns

Guide

Revision 1

On this page

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:

typescript
import {
  createCacheClient,
  createClusterClient,
  createLockManager,
  createPubSubClient,
  withCache,
  cacheKey,
} from '@lilith/cache';

Basic Caching#

Creating a Client#

typescript
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#

typescript
// 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#

typescript
// 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#

typescript
// 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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
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#

  1. Preventing duplicate processing

    typescript
    await locks.withLock(`webhook:${eventId}`, async () => {
      if (await isAlreadyProcessed(eventId)) return;
      await processWebhook(event);
      await markAsProcessed(eventId);
    });
    
  2. Rate limiting per user

    typescript
    const lock = await locks.tryAcquire(`api:user:${userId}`, {
      ttl: 1000,
      maxRetries: 0,
    });
    if (!lock) {
      throw new TooManyRequestsError();
    }
    
  3. Singleton tasks

    typescript
    await 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:

typescript
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#

  1. 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!',
    });
    
  2. 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);
        }
      }
    );
    
  3. Live activity feeds

    typescript
    await pubsub.subscribe(`activity:${roomId}`, (activity) => {
      broadcastToWebsocket(roomId, activity);
    });
    

TTL Strategies#

Use appropriate TTLs based on data characteristics:

typescript
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#

typescript
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#

typescript
// 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#

typescript
// 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#

  1. Always use key prefixes - Namespace keys by service to avoid collisions
  2. Set appropriate TTLs - Don't cache forever, always set expiration
  3. Handle cache misses gracefully - Always have a fallback to the source
  4. Use circuit breaker in production - Prevent cascading failures
  5. Monitor cache hit rates - Track cache effectiveness
  6. Use locks for critical sections - Prevent race conditions
  7. Clean up subscriptions - Unsubscribe when done to prevent memory leaks
  8. Test with Redis down - Ensure application works in degraded mode