Skip to main content

​
Overview

The Redis backend stores all IP pool state in Redis, enabling multiple Proxy Hopper instances to share a single pool. Each IP is delivered to exactly one instance at a time using BLPOP atomicity. Quarantine expiry uses ZRANGEBYSCORE + ZREM to prevent double-release across instances.

​
Install

The Redis backend is a separate Docker image: 
docker pull ghcr.io/cams-data/proxy-hopper:latest-redis

​
Configure

proxy-hopper run --config config.yaml --backend redis --redis-url redis://redis:6379/0
Or in config.yaml: 
server:
  backend: redis
  redisUrl: redis://redis:6379/0
Or via environment variable: 
PROXY_HOPPER_BACKEND=redis
PROXY_HOPPER_REDIS_URL=redis://redis:6379/0

​
Characteristics

PropertyDetail
DependenciesRedis 6+
State persistenceSurvives restarts
Multi-instanceFully supported — shared pool state
PerformanceSmall added latency per pool operation (~1ms on local Redis)

​
How it works

  • IP queue — each pool’s available IPs are stored as a Redis list. BLPOP atomically dequeues one IP per request, guaranteeing exclusive delivery to one instance.
  • Quarantine — quarantined IPs are stored in a sorted set keyed by expiry timestamp. A background sweep uses ZRANGEBYSCORE to find expired entries and ZREM to atomically return them to the pool.
  • Cooldown — after each request, an IP is held with a Redis key that expires after minRequestInterval. Once expired, the IP is returned to the queue.

​
Deployment

See Docker Compose with Redis and Kubernetes for full deployment examples.

​
Production considerations

  • Use a managed Redis service (AWS ElastiCache, GCP Memorystore, Redis Cloud) rather than a self-hosted instance for production workloads
  • Enable Redis persistence (RDB or AOF) if pool state must survive a Redis restart
  • Set maxmemory and maxmemory-policy to prevent Redis from consuming unbounded memory