Configuration

The configuration section key is cache. Values are read from YAML, environment variables (QK_CACHE__*), or passed directly to CacheConfig(...).

Root: CacheConfig

Key	Type	Default	Env Var	Description
enabled	bool	True	QK_CACHE__ENABLED	Enable caching
version	str	"1.0.0"	QK_CACHE__VERSION	Config version
environment	str	"development"	QK_CACHE__ENVIRONMENT	Runtime environment
debug	bool	False	QK_CACHE__DEBUG	Debug mode
backends	list[CacheBackendConfig]	[]	—	Backend configurations
service	CacheServiceConfig	(see below)	—	Service-level settings

backends[]: CacheBackendConfig

Common fields shared across all backend types:

Key	Type	Default	Env Var	Description
name	str	(required)	—	Unique backend identifier
type	BackendType	(required)	—	memory, redis, or memcached
default	bool	False	—	Exactly one backend must be default
enabled	bool	True	—	Enable this backend
default_ttl	int	None	—	Default TTL in seconds
key_prefix	str	""	—	Key prefix for namespace isolation

Memory-specific Fields

Key	Type	Default	Description
max_size	int	None	Max entries before eviction
cleanup_interval	int	60	Cleanup interval in seconds
enable_metrics	bool	True	Enable metrics collection

Redis-specific Fields

Key	Type	Default	Env Var	Description
redis_host	str	"localhost"	QK_CACHE__BACKENDS__0__REDIS_HOST	Redis host
redis_port	int	6379	QK_CACHE__BACKENDS__0__REDIS_PORT	Redis port
redis_db	int	0	QK_CACHE__BACKENDS__0__REDIS_DB	Redis database
redis_password	str	None	QK_CACHE__BACKENDS__0__REDIS_PASSWORD	Redis password
redis_url	str	None	QK_CACHE__BACKENDS__0__REDIS_URL	Full Redis URL
redis_ssl	bool	False	QK_CACHE__BACKENDS__0__REDIS_SSL	Enable SSL/TLS
redis_pool_size	int	10	QK_CACHE__BACKENDS__0__REDIS_POOL_SIZE	Connection pool size

Memcached-specific Fields

Key	Type	Default	Env Var	Description
memcached_host	str	"localhost"	—	Memcached host
memcached_port	int	11211	—	Memcached port
memcached_servers	list[str]	None	—	Server list (host:port)

service: CacheServiceConfig

Key	Type	Default	Env Var	Description
enable_protection	bool	True	QK_CACHE__SERVICE__ENABLE_PROTECTION	Stampede protection
enable_metrics	bool	True	QK_CACHE__SERVICE__ENABLE_METRICS	Service-level metrics
enable_health_checks	bool	True	QK_CACHE__SERVICE__ENABLE_HEALTH_CHECKS	Health checks
protection_lock_ttl	int	30	QK_CACHE__SERVICE__PROTECTION_LOCK_TTL	Lock TTL (seconds)
protection_max_wait	float	10.0	QK_CACHE__SERVICE__PROTECTION_MAX_WAIT	Max lock wait
protection_retry_interval	float	0.1	QK_CACHE__SERVICE__PROTECTION_RETRY_INTERVAL	Lock retry interval
default_backend	str	None	QK_CACHE__SERVICE__DEFAULT_BACKEND	Default backend name
circuit_breaker_enabled	bool	False	QK_CACHE__SERVICE__CIRCUIT_BREAKER_ENABLED	Circuit breaker
circuit_breaker_threshold	int	5	QK_CACHE__SERVICE__CIRCUIT_BREAKER_THRESHOLD	Failure threshold
default_serializer	str	"json"	QK_CACHE__SERVICE__DEFAULT_SERIALIZER	Serializer type

YAML Example

cache:
  backends:
    - name: "hot"
      type: memory
      default: true
      max_size: 10000
      default_ttl: 300
    - name: "persistent"
      type: redis
      host: "${REDIS_HOST}"
      port: 6379
      redis_password: "${REDIS_PASSWORD}"
      redis_ssl: true
      key_prefix: "myapp"
      default_ttl: 3600
    - name: "fast"
      type: memcached
      host: "${MEMCACHED_HOST}"
      port: 11211
      default_ttl: 60

  service:
    enable_protection: true
    protection_lock_ttl: 30
    protection_max_wait: 10.0
    default_serializer: "json"

Environment Variables

# Backend list (indexed by _0_, _1_, etc.)
export QK_CACHE__BACKENDS__0__NAME="hot"
export QK_CACHE__BACKENDS__0__TYPE="memory"
export QK_CACHE__BACKENDS__0__DEFAULT=true
export QK_CACHE__BACKENDS__1__NAME="persistent"
export QK_CACHE__BACKENDS__1__TYPE="redis"
export QK_CACHE__BACKENDS__1__REDIS_HOST="redis.example.com"
export QK_CACHE__BACKENDS__1__REDIS_PORT=6379
export QK_CACHE__BACKENDS__1__REDIS_PASSWORD="${REDIS_PASSWORD}"

# Service settings
export QK_CACHE__SERVICE__ENABLE_PROTECTION=true
export QK_CACHE__SERVICE__DEFAULT_SERIALIZER="json"

# Top-level
export QK_CACHE__ENABLED=true
export QK_CACHE__ENVIRONMENT="production"