# Redis Usage Patterns

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
