REDIS Provider

The REDIS provider uses Redis as an in-memory data store for documents and sessions. Redis is ideal for cluster deployments where multiple webPDF Server nodes need to share document metadata and session data.

Overview

• Provider Name: REDIS
• Supports: Document Storage, Session Storage
• Configuration File: provider-redis.yaml (Redisson configuration format)
• Use Case: Cluster deployments, high-performance caching, distributed sessions

Features

• ✓ High-performance in-memory data store
• ✓ Cluster-ready with shared state
• ✓ Persistence options (RDB, AOF)
• ✓ Replication and high availability support
• ✓ Low latency access
• ✓ Batch operations for optimized performance
• ✓ Distributed locking with watchdog mechanism
• ✓ Namespace-based key isolation
• ✓ JSON serialization with Java time support
• ✓ Connection health monitoring
• ✓ Event manager integration for async operations
• ✓ Session reconciliation and expiration processing
• ✗ Limited by available RAM
• ✗ Requires external Redis server

Prerequisites

• Redis server 6.0 or later
• Network connectivity from webPDF Server to Redis
• Redis connection details (host, port, credentials)

Configuration

provider.json

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  },
  "sessionStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  }
}

provider-redis.yaml

The configuration file uses the Redisson YAML format. Redisson is a Redis client that provides advanced features for distributed applications.

info

The provider-redis.yaml file is a standard Redisson configuration file, not a webPDF-specific format. Refer to the Redisson documentation for all available configuration options.

Single Server Configuration

For standalone Redis servers:

singleServerConfig:
  address: "redis://localhost:6379"
  password: "your-password"
  database: 0
  connectionPoolSize: 64
  connectionMinimumIdleSize: 24
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500

Cluster Configuration

For Redis Cluster deployments:

clusterServersConfig:
  nodeAddresses:
    - "redis://redis-node1:6379"
    - "redis://redis-node2:6379"
    - "redis://redis-node3:6379"
  password: "your-password"
  scanInterval: 1000
  readMode: "SLAVE"
  subscriptionMode: "MASTER"

Sentinel Configuration

For Redis Sentinel high availability:

sentinelServersConfig:
  masterName: "mymaster"
  sentinelAddresses:
    - "redis://sentinel1:26379"
    - "redis://sentinel2:26379"
    - "redis://sentinel3:26379"
  password: "your-password"
  database: 0

Configuration Attributes

Single Server Settings

Attribute	Type	Description	Default
address	string	Redis server address (format: redis://host:port)	-
password	string	Redis authentication password	null
database	integer	Redis database number (0-15)	0
connectionPoolSize	integer	Connection pool size	64
connectionMinimumIdleSize	integer	Minimum idle connections	24
idleConnectionTimeout	integer	Idle connection timeout (ms)	10000
connectTimeout	integer	Connection timeout (ms)	10000
timeout	integer	Command timeout (ms)	3000
retryAttempts	integer	Number of retry attempts	3
retryInterval	integer	Retry interval (ms)	1500

Cluster Server Settings

Attribute	Type	Description	Default
nodeAddresses	array	List of cluster node addresses	-
password	string	Redis authentication password	null
scanInterval	integer	Cluster topology scan interval (ms)	1000
readMode	string	Read mode: SLAVE, MASTER, MASTER_SLAVE	SLAVE
subscriptionMode	string	Subscription mode: MASTER, SLAVE	MASTER

Sentinel Server Settings

Attribute	Type	Description	Default
masterName	string	Name of the master server	-
sentinelAddresses	array	List of sentinel addresses	-
password	string	Redis authentication password	null
database	integer	Redis database number	0

Environment Variables

Since the configuration uses Redisson YAML format, environment variables can be used within the YAML file using standard YAML syntax:

singleServerConfig:
  address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
  password: "${REDIS_PASSWORD}"
  database: ${REDIS_DATABASE:0}

Health Checks

Health checks monitor Redis connectivity and availability:

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  }
}

• enabled: Enable health checks (recommended: true)
• interval: Check interval in milliseconds (recommended: 5000 - 10000)

Namespace Support

Redis keys are automatically prefixed with a namespace to support multi-tenancy and prevent key collisions. The namespace is derived from cluster settings and follows a hierarchical structure.

Key Structure

Keys follow this pattern:

<namespace>:<domain>:<type>:<identifier>

Where:

• namespace: Generated from namespace configuration (e.g., acme:webpdf:prod:v10-0)
• domain: Key domain (session, document, event, history)
• type: Key type (data, index, lock)
• identifier: Unique ID (session ID, document ID, etc.)

Key Domains

Domain	Purpose	Example Keys
session	Session management	<ns>:session:data:<sessionId>
document	Document storage	<ns>:document:data:<sessionId>:<documentId>
event	Event notifications	<ns>:event
history	Document history	<ns>:history:data:<sessionId>:<documentId>

Index Keys

Index keys are used for listing and searching:

<namespace>:session:index
<namespace>:document:index

Lock Keys

Distributed locks use dedicated keys:

<namespace>:session:lock:<sessionId>
<namespace>:session:lock:expiration
<namespace>:session:lock:reconciliation
<namespace>:document:lock:<sessionId>:<documentId>

See Namespace Configuration for more details on configuring namespaces.

Security Considerations

1. Authentication – Always use Redis authentication (requirepass in Redis config)
2. TLS/SSL – Enable SSL for connections over untrusted networks
3. Network Security – Use firewalls to restrict Redis access
4. Password Strength – Use strong, randomly generated passwords
5. Database Separation – Use different database numbers for documents and sessions

warning

Never store Redis passwords in configuration files. Use environment variables or secure configuration management.

High Availability

For production deployments, consider:

1. Redis Sentinel – Automatic failover and monitoring
2. Redis Cluster – Horizontal scaling across multiple nodes
3. Replication – Master-slave replication for read scaling
4. Persistence – Enable RDB or AOF for data durability

Performance Tuning

Batch Operations

The provider uses batch operations to optimize performance for multiple operations:

• Batch Execution: Multiple Redis commands are grouped and executed together
• Reduced Latency: Minimizes network round trips
• Atomic Operations: Batch operations are executed atomically
• Use Case: Document retrieval, session cleanup, bulk operations

Distributed Locking

Distributed locks ensure data consistency across cluster nodes:

• Lock Timeout: 2000 milliseconds (default)
• Lock Lease Time: -1 (watchdog enabled for automatic extension)
• Lock Keys: Separate locks for sessions and documents
• Global Locks: Used for expiration processing and reconciliation

The watchdog mechanism automatically extends lock lease time as long as the lock-holding thread is alive, preventing premature lock release.

Data Serialization

JSON serialization with Java time support:

• Format: JSON with type information
• Codec: JSON codec with JavaTimeModule
• Benefits: Human-readable data, cross-platform compatibility
• Types: Supports all Java time types (Instant, LocalDateTime, etc.)

Connection Health Monitoring

Automatic connection monitoring:

• Connection Listeners: Monitor connection status changes
• Health Status: Real-time connection state tracking
• Reconnection: Automatic reconnection on failure
• Health Checks: Scheduled health check validation

Event Manager Integration

Asynchronous event processing:

• Async Operations: Non-blocking event notifications
• Event Queue: Decoupled event processing
• Performance: Operations don't wait for event processing
• Use Case: Notifications, logging, monitoring

Session Management

Advanced session handling:

• Session Reconciliation: Periodic consistency checks across cluster
• Expiration Processing: Automated cleanup of expired sessions
• Session ID Generation: Snowflake-based ID generation for uniqueness
• Session Table: Maintains session metadata and state

Redis Server Configuration

# redis.conf optimizations
maxmemory 4gb
maxmemory-policy allkeys-lru
tcp-backlog 511
timeout 300
tcp-keepalive 60

Connection Pool Tuning

Adjust pool settings in the Redisson configuration based on load:

singleServerConfig:
  address: "redis://localhost:6379"
  connectionPoolSize: 256
  connectionMinimumIdleSize: 64
  subscriptionConnectionPoolSize: 50
  subscriptionConnectionMinimumIdleSize: 10
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000

Troubleshooting

Cannot Connect to Redis

1. Verify Redis is running: redis-cli ping
2. Check network connectivity: telnet redis-host 6379
3. Verify credentials are correct
4. Check firewall rules

High Memory Usage

1. Monitor Redis memory: redis-cli info memory
2. Adjust maxmemory policy
3. Review data retention policies
4. Consider increasing Redis server memory

Slow Response Times

1. Check Redis server load: redis-cli info stats
2. Monitor network latency
3. Review slow log: redis-cli slowlog get 10
4. Optimize connection pool settings

Examples

Basic Single Server Setup

singleServerConfig:
  address: "redis://localhost:6379"

Redis with Authentication

singleServerConfig:
  address: "redis://redis.example.com:6379"
  password: "secure-password"
  database: 0
  connectionPoolSize: 64
  connectionMinimumIdleSize: 24

Redis with SSL/TLS

singleServerConfig:
  address: "rediss://redis.example.com:6380"
  password: "secure-password"
  database: 0
  sslEnableEndpointIdentification: true

Redis Cluster Configuration

clusterServersConfig:
  nodeAddresses:
    - "redis://redis-node1:6379"
    - "redis://redis-node2:6379"
    - "redis://redis-node3:6379"
  password: "secure-password"
  scanInterval: 1000
  readMode: "SLAVE"
  subscriptionMode: "MASTER"

Redis Sentinel Configuration

sentinelServersConfig:
  masterName: "mymaster"
  sentinelAddresses:
    - "redis://sentinel1.example.com:26379"
    - "redis://sentinel2.example.com:26379"
    - "redis://sentinel3.example.com:26379"
  password: "secure-password"
  database: 0