# Redis Integration Guide

This document explains how Redis has been integrated into the Schematics Backend application.

## Overview

Redis has been integrated to provide:

- **Caching**: Improve response times for frequently accessed data
- **Session Management**: Store user sessions with TTL
- **Rate Limiting**: Implement API rate limiting using Redis counters
- **Data Storage**: Temporary storage for application data
- **Performance Monitoring**: Track application metrics

## Features

### 1. Redis Client Configuration

- **Location**: `src/lib/redis.ts`
- **Features**:
  - Connection pooling and retry logic
  - Event handling (connect, ready, error, close, reconnecting)
  - Graceful shutdown handling
  - Development mode singleton pattern

### 2. Redis Utilities

- **Location**: `src/utils/redis.ts`
- **Features**:
  - Key-value operations (set, get, del, exists)
  - TTL management (expire, ttl)
  - Counter operations (incr, decr)
  - Session management
  - User cache management
  - Rate limiting utilities
  - Health checks

### 3. Redis Middleware

- **Location**: `src/middleware/redisMiddleware.ts`
- **Features**:
  - Response caching middleware
  - Rate limiting middleware
  - Session middleware
  - Health check middleware
  - Cache clearing middleware

### 4. Redis Admin Controller

- **Location**: `src/controllers/Admin/RedisController.ts`
- **Features**:
  - Redis information and statistics
  - Memory usage monitoring
  - Key management (get, set, delete)
  - Cache statistics
  - Database operations (flush, ping, dbsize)

## Environment Variables

Add these variables to your `.env` file to match the Docker Compose configuration:

```env
# Redis Configuration (matches docker-compose.yaml)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=redis_password_123
REDIS_DB=0
```

### Docker Compose Configuration

The Redis service is already configured in `docker-compose.yaml`:

```yaml
redis:
  image: redis:latest
  environment:
    REDIS_PASSWORD: redis_password_123
    REDIS_DB: 0
  ports:
    - 6379:6379
  volumes:
    - redis-data:/data
```

To start Redis with Docker Compose:

```bash
docker-compose up redis
```

### Quick Setup

1. **Setup Redis environment variables**:

   ```bash
   npm run setup:redis
   ```

2. **Test Redis connection**:
   ```bash
   npm run test:redis
   ```

## Installation

### Option 1: Using Docker Compose (Recommended)

1. **Install Redis Dependencies**:

   ```bash
   npm install redis ioredis
   npm install --save-dev @types/redis
   ```

2. **Start Redis with Docker Compose**:

   ```bash
   # Start only Redis
   docker-compose up redis

   # Or start all services (PostgreSQL + Redis)
   docker-compose up
   ```

### Option 2: Local Installation

1. **Install Redis Dependencies**:

   ```bash
   npm install redis ioredis
   npm install --save-dev @types/redis
   ```

2. **Install Redis Server**:

   **Windows**:
   - Download from: https://github.com/microsoftarchive/redis/releases
   - Or use WSL2 with Ubuntu

   **macOS**:

   ```bash
   brew install redis
   ```

   **Ubuntu/Debian**:

   ```bash
   sudo apt update
   sudo apt install redis-server
   ```

3. **Start Redis Server**:
   ```bash
   redis-server
   ```

## Usage Examples

### Basic Redis Operations

```typescript
import RedisUtils from './utils/redis';

// Set a value with TTL
await RedisUtils.set(
  'user:123',
  { name: 'John', email: 'john@example.com' },
  { ttl: 3600 }
);

// Get a value
const user = await RedisUtils.get('user:123');

// Delete a key
await RedisUtils.del('user:123');

// Check if key exists
const exists = await RedisUtils.exists('user:123');
```

### Session Management

```typescript
import RedisUtils from './utils/redis';

// Store session
await RedisUtils.setSession('session-id', {
  userId: '123',
  email: 'user@example.com',
  role: 'user',
});

// Get session
const session = await RedisUtils.getSession('session-id');

// Delete session
await RedisUtils.deleteSession('session-id');
```

### Caching Middleware

```typescript
import { redisCache } from './middleware/redisMiddleware';

// Cache route responses for 5 minutes
app.get('/api/users', redisCache({ ttl: 300 }), (req, res) => {
  // Route handler
});

// Cache with custom key
app.get(
  '/api/user/:id',
  redisCache({
    ttl: 600,
    key: (req) => `user:${req.params.id}`,
  }),
  (req, res) => {
    // Route handler
  }
);
```

### Rate Limiting

```typescript
import { redisRateLimit } from './middleware/redisMiddleware';

// Rate limit: 100 requests per 15 minutes per IP
app.use(
  '/api/',
  redisRateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // limit each IP to 100 requests per windowMs
  })
);
```

## API Endpoints

### Health Check

- `GET /health` - Check Redis connection status

### Redis Admin (requires authentication)

- `GET /v1/redis/info` - Get Redis information
- `GET /v1/redis/memory` - Get memory usage
- `GET /v1/redis/keys` - List keys with pattern matching
- `GET /v1/redis/keys/:key` - Get key value
- `POST /v1/redis/keys/:key` - Set key value
- `DELETE /v1/redis/keys/:key` - Delete key
- `POST /v1/redis/cache/clear` - Clear cache by prefix
- `GET /v1/redis/cache/stats` - Get cache statistics
- `GET /v1/redis/dbsize` - Get database size
- `GET /v1/redis/ping` - Ping Redis server
- `POST /v1/redis/flush` - Flush all data (dangerous)

## Monitoring

### Health Check Response

```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "services": {
    "redis": "connected"
  },
  "redis": {
    "connected": true,
    "info": "available"
  }
}
```

### Cache Statistics

```json
{
  "success": true,
  "data": {
    "cache": {
      "count": 150,
      "keys": ["cache:user:123", "cache:user:456"]
    },
    "auth": {
      "count": 25,
      "keys": ["auth:session:abc", "auth:session:def"]
    },
    "api": {
      "count": 75,
      "keys": ["api:ratelimit:192.168.1.1"]
    },
    "total": 250
  }
}
```

## Best Practices

1. **Key Naming**: Use prefixes to organize keys (e.g., `cache:`, `auth:`, `api:`)
2. **TTL Management**: Always set appropriate TTL for cached data
3. **Error Handling**: Redis operations are wrapped in try-catch blocks
4. **Connection Management**: The client handles reconnection automatically
5. **Memory Management**: Monitor memory usage and set appropriate limits

## Troubleshooting

### Common Issues

1. **Connection Refused**:
   - Ensure Redis server is running
   - Check host and port configuration
   - Verify firewall settings

2. **Memory Issues**:
   - Monitor Redis memory usage
   - Set appropriate maxmemory policy
   - Use TTL for temporary data

3. **Performance Issues**:
   - Use appropriate key patterns
   - Avoid large value sizes
   - Monitor slow queries

### Debug Mode

Enable debug logging by setting:

```env
NODE_ENV=development
```

This will show Redis connection events and errors in the console.

## Security Considerations

1. **Authentication**: Use Redis password in production
2. **Network Security**: Restrict Redis access to application servers
3. **Data Encryption**: Consider Redis encryption for sensitive data
4. **Access Control**: Limit admin endpoints to authorized users

## Performance Tips

1. **Connection Pooling**: The client handles connection pooling automatically
2. **Pipelining**: Use Redis pipelining for bulk operations
3. **Key Expiration**: Use TTL to automatically clean up old data
4. **Memory Optimization**: Use appropriate data structures and compression

## Migration from Memory Storage

If you're migrating from in-memory storage to Redis:

1. Replace memory objects with Redis operations
2. Update session management to use Redis
3. Implement proper error handling for Redis failures
4. Add health checks for Redis connectivity
5. Update rate limiting to use Redis counters

## Support

For Redis-related issues:

1. Check the Redis logs
2. Verify connection settings
3. Monitor memory usage
4. Review the application logs for Redis errors