VALKEY Provider

The VALKEY provider uses Valkey as an in-memory data store for documents and sessions. Valkey is a Redis-compatible open-source alternative maintained by the Linux Foundation, ideal for cluster deployments where multiple webPDF Server nodes need to share document metadata and session data.

Overview

• Provider Name: VALKEY
• Supports: Document Storage, Session Storage
• Configuration File: provider-valkey.yaml (Redisson configuration format)
• Use Case: Cluster deployments, high-performance caching, distributed sessions
• Compatibility: Fully compatible with Redis protocol and configuration

Features

• ✓ High-performance in-memory data store
• ✓ 100% Redis protocol compatible
• ✓ Open-source (BSD 3-Clause license)
• ✓ 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 Valkey server

Prerequisites

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

Configuration

provider.json

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

provider-valkey.yaml

The configuration file uses the Redisson YAML format. Valkey is fully compatible with Redis protocol, so Redisson can be used seamlessly.

info

The provider-valkey.yaml file is a standard Redisson configuration file, not a webPDF-specific format. Use valkey:// protocol prefix in addresses. Refer to the Redisson documentation for all available configuration options.

Single Server Configuration

For standalone Valkey servers:

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

Cluster Configuration

For Valkey Cluster deployments:

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

NAT Mapper Configuration

For cluster deployments with NAT (e.g., Docker):

clusterServersConfig:
  nodeAddresses:
    - "valkey://localhost:7001"
    - "valkey://localhost:7002"
    - "valkey://localhost:7003"
  natMapper:
    class: "org.redisson.api.HostNatMapper"
    hostsMap:
      "172.24.5.1": "localhost"
      "172.24.5.2": "localhost"
      "172.24.5.3": "localhost"

Sentinel Configuration

For Valkey Sentinel high availability:

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

Configuration Attributes

Single Server Settings

Attribute	Type	Description	Default
address	string	Valkey server address (format: valkey://host:port)	-
password	string	Valkey authentication password	null
database	integer	Valkey 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	Valkey 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
natMapper	object	NAT mapping configuration for Docker/containerized deployments	-

Sentinel Server Settings

Attribute	Type	Description	Default
masterName	string	Name of the master server	-
sentinelAddresses	array	List of sentinel addresses	-
password	string	Valkey authentication password	null
database	integer	Valkey 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: "valkey://${VALKEY_HOST:localhost}:${VALKEY_PORT:6379}"
  password: "${VALKEY_PASSWORD}"
  database: ${VALKEY_DATABASE:0}

Health Checks

Health checks monitor Valkey connectivity and availability:

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

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

Namespace Support

Valkey 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.

Valkey vs Redis

Valkey is a fork of Redis that maintains full protocol compatibility:

Feature	Valkey	Redis
Protocol	✓ Compatible	✓ Native
License	BSD 3-Clause	SSPL/RSALv2
Governance	Linux Foundation	Redis Ltd.
Features	✓ All Redis features	✓ Native
Performance	✓ Equivalent	✓ Equivalent

tip

You can migrate from Redis to Valkey (or vice versa) without changing your webPDF configuration. Simply point to a different server and restart.

Security Considerations

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

warning

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

High Availability

For production deployments, consider:

1. Valkey Sentinel – Automatic failover and monitoring
2. Valkey Cluster – Horizontal scaling across multiple nodes
3. Replication – Master-replica 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 Valkey 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

Valkey Server Configuration

# valkey.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: "valkey://localhost:6379"
  connectionPoolSize: 256
  connectionMinimumIdleSize: 64
  subscriptionConnectionPoolSize: 50
  subscriptionConnectionMinimumIdleSize: 10
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000

Troubleshooting

Cannot Connect to Valkey

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

High Memory Usage

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

Slow Response Times

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

Migration

From REDIS to VALKEY

Migration between Redis and Valkey is seamless:

1. Set up Valkey server
2. Copy provider-redis.yaml to provider-valkey.yaml
3. Update protocol prefix from redis:// to valkey:// in addresses
4. Update provider.json to use VALKEY instead of REDIS
5. Optional: Migrate data using redis-cli --rdb and restore to Valkey
6. Restart webPDF Server

Examples

Basic Single Server Setup

singleServerConfig:
  address: "valkey://localhost:6379"

Valkey with Authentication

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

Valkey with SSL/TLS

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

Valkey Cluster Configuration

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

Valkey Cluster with NAT Mapper (Docker)

clusterServersConfig:
  nodeAddresses:
    - "valkey://localhost:7001"
    - "valkey://localhost:7002"
    - "valkey://localhost:7003"
  natMapper:
    class: "org.redisson.api.HostNatMapper"
    hostsMap:
      "172.24.5.1": "localhost"
      "172.24.5.2": "localhost"
      "172.24.5.3": "localhost"

Valkey Sentinel Configuration

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