Redis Implementation

Complete Redis client implementation details

This page documents the complete Redis client implementation for the pages-server Traefik plugin, built using only Go standard library for Yaegi interpreter compatibility.

Overview

The implementation provides a full-featured Redis client without external dependencies, ensuring compatibility with Traefik’s Yaegi interpreter.

Key Implementations

RESP Protocol Support

Implemented from scratch without external dependencies:

  • Simple Strings
  • Bulk Strings
  • Integers
  • Errors
  • Arrays
  • Nil Values

Redis Commands Implemented

The following commands are supported for distributed caching scenarios:

  • GET - Retrieve values
  • SET - Store values
  • SETEX - Store with expiration
  • DEL - Delete keys
  • FLUSHDB - Clear database
  • PING - Health check
  • AUTH - Authentication

Connection Management

Pool Configuration (v0.1.5+):

Parameter Default Description
redisPoolSize 10 Size of idle connection pool per cache instance
redisMaxConnections 20 Maximum total connections per cache instance
redisConnWaitTimeout 5 Seconds to wait when pool is exhausted

Connection Features:

  • Semaphore-based connection limiting prevents Redis exhaustion
  • Configurable pool size and max connections for tuning
  • Blocking with timeout when connections exhausted
  • Graceful fallback to in-memory cache on timeout
  • 5-second connection timeouts
  • Automatic reconnection
  • Connection pooling for performance
  • Health monitoring via PING

Note: The plugin creates 3 cache instances (content, custom domain, password), so total max Redis connections = 3 × redisMaxConnections (60 by default). Ensure your Redis maxclients setting accommodates this.

Error Handling

The system includes robust error handling:

  • Falls back to in-memory cache if Redis unavailable
  • Graceful fallback when connection wait times out (v0.1.5+)
  • Semaphore-based limiting prevents connection exhaustion (v0.1.5+)
  • Graceful degradation under high load
  • Detailed error logging
  • Connection retry logic

Files Modified/Created

cache.go

~365 lines implementing RedisCache struct and methods:

  • Connection pool management
  • RESP protocol implementation
  • Command execution
  • Error handling

cache_test.go

15 Redis-specific tests covering:

  • GET/SET operations
  • TTL expiration
  • Connection pooling
  • Binary data handling
  • Error scenarios
  • Connection limiting (v0.1.5+)
  • Connection wait timeout (v0.1.5+)
  • Fallback on connection exhaustion (v0.1.5+)

REDIS_TESTING.md

Comprehensive testing documentation including:

  • Setup instructions
  • Test scenarios
  • Performance benchmarks
  • Troubleshooting guides

test_redis_manual.sh

Bash script for manual integration testing with:

  • Automated test execution
  • Result validation
  • Performance measurement

Test Results

All tests pass successfully with approximately 7.7 seconds total execution time.

Redis tests fall back to in-memory cache when Redis is not available, ensuring tests always pass.

Performance Characteristics

The implementation targets:

  • Response Time: Sub-5ms for all operations
  • GET Operations: < 1ms typical
  • SET Operations: < 1ms typical
  • Connection Pool Access: < 0.1ms

Production Readiness

The implementation includes:

  • Connection pooling - Efficient resource usage with configurable pool size
  • Connection limiting - Semaphore-based max connection limit prevents Redis exhaustion (v0.1.5+)
  • Configurable timeouts - Tune wait timeout for your environment (v0.1.5+)
  • Graceful fallback - Falls back to in-memory cache under extreme load
  • Password authentication - Security support
  • TTL support - Automatic expiration
  • Binary data handling - Support for all data types
  • Extensive documentation - Complete usage guides

Architecture Benefits

The Redis implementation provides:

  • Distributed caching across multiple servers
  • Horizontal scaling capability
  • Persistent cache storage
  • Cache sharing between instances
  • Production-grade reliability

Compatibility

Built for:

  • Traefik v2.0+ plugin system
  • Yaegi interpreter compatibility
  • Go standard library only
  • No external dependencies

This ensures seamless integration with Traefik’s plugin architecture while maintaining high performance.