docs: Add Redis storage documentation

[bigboateng]

Redis Storage Documentation

Overview

The Redis storage provider allows storing browser state directly in Redis, making it suitable for high-performance, in-memory storage scenarios.

Installation

Since Redis storage is an optional feature, you need to install the ioredis package:

npm install ioredis

Configuration

interface RedisStorageOptions {
  // Basic connection options
  host: string;      // Redis server host
  port: number;      // Redis server port
  password?: string; // Redis server password (optional)
  db?: number;      // Redis database number (optional)
  tls?: {           // TLS configuration (optional)
    rejectUnauthorized?: boolean;
    ca?: string[];
    cert?: string;
    key?: string;
  };

  // Storage configuration
  keyPrefix?: string;  // Prefix for Redis keys (default: 'browserstate:')
  tempDir?: string;    // Temporary directory for file operations

  // Advanced options
  maxFileSize?: number;  // Maximum file size to store (default: 1MB)
  compression?: boolean; // Enable data compression (default: false)
  ttl?: number;         // Time to live in seconds for sessions
}

Usage Example

import { BrowserState } from 'browserstate';

const options = {
  storageType: 'redis',
  redisOptions: {
    host: 'localhost',
    port: 6379,
    // Optional: password: 'your-password',
    // Optional: db: 0,
    // Optional: keyPrefix: 'browserstate:',
    // Optional: maxFileSize: 1024 * 1024, // 1MB
    // Optional: compression: true,
    // Optional: ttl: 3600 // 1 hour
  }
};

const browserState = new BrowserState(options);

Features

• Compression: Optional data compression using zlib
• File Size Limits: Configurable maximum file size
• TTL Support: Optional time-to-live for sessions
• TLS Support: Secure connections with TLS
• Connection Retry: Built-in retry strategy for reliability
• Error Handling: Graceful error handling and initialization

Error Handling

The Redis storage provider includes robust error handling:

• Graceful initialization failures
• Clear error messages for missing dependencies
• Proper cleanup on errors
• Development vs production error handling

Best Practices

1. Use compression for large sessions
2. Set appropriate TTL values based on your use case
3. Configure maxFileSize based on your Redis memory limits
4. Use TLS for production environments
5. Consider using a connection pool for high-concurrency scenarios

Limitations

• Maximum file size limit (configurable)
• Memory usage depends on session size
• Requires Redis server to be available
• Network latency for remote Redis servers

Testing

To test Redis storage locally:

1. Start a Redis server
2. Configure connection options
3. Use the example code above
4. Monitor Redis memory usage

Dependencies

• ioredis (optional peer dependency)
• fs-extra (for file operations)
• zlib (for compression)

Migration

If you're migrating from another storage provider:

1. Install ioredis
2. Update your BrowserState configuration
3. Test with a small session first
4. Monitor Redis memory usage
5. Adjust settings as needed

Security Considerations

• Use TLS for production environments
• Set strong passwords
• Configure appropriate TTL values
• Monitor Redis memory usage
• Use separate Redis databases for different environments

Performance Tips

1. Enable compression for large sessions
2. Use appropriate TTL values
3. Monitor Redis memory usage
4. Consider using Redis cluster for high availability
5. Use connection pooling for high concurrency

Troubleshooting

Common issues and solutions:

1. Connection failures: Check Redis server status
2. Memory issues: Adjust maxFileSize
3. Performance issues: Enable compression
4. Initialization failures: Check ioredis installation
5. TLS issues: Verify certificate configuration

Future Improvements

• Add Redis cluster support
• Implement connection pooling
• Add monitoring hooks
• Support Redis streams for session events
• Add Redis Sentinel support
• Implement session migration tools
• Add Redis memory usage monitoring
• Support Redis ACLs
• Add Redis pub/sub for session updates
• Implement Redis backup/restore utilities