feat(config): cache.backend=redis selects the shared cache

[EricAndrechek]

Part of #613. Stacked on #626 (feat/cache-redis), and it also merges #621 (feat/cache-flat-versions), so until #621 merges its commits show in this diff too.

What

cache.backend: redis now selects the shared cache from #626. It is configured by a new cache.redis boot-config block (WH_CACHE_REDIS_*).

key	env	default
cache.redis.addrs	WH_CACHE_REDIS_ADDRS (comma-separated)	required with backend: redis; host:port only (a URL is refused), exactly one in standalone mode
cache.redis.mode	WH_CACHE_REDIS_MODE	standalone (or cluster; sentinel is refused until #656)
cache.redis.username / password / db	WH_CACHE_REDIS_{USERNAME,PASSWORD,DB}	password is a secret: env only in practice, like clickhouse.password
cache.redis.tls.{enabled,ca_file,cert_file,key_file,server_name,insecure_skip_verify}	WH_CACHE_REDIS_TLS_*	off
cache.redis.key_prefix	WH_CACHE_REDIS_KEY_PREFIX	wh
cache.redis.timeout / dial_timeout	WH_CACHE_REDIS_{TIMEOUT,DIAL_TIMEOUT}	100ms / 1s, each at most 1s
cache.redis.max_value_bytes	WH_CACHE_REDIS_MAX_VALUE_BYTES	1048576
cache.redis.compress_min_bytes	WH_CACHE_REDIS_COMPRESS_MIN_BYTES	1024; 0 = never
cache.redis.version_ttl	WH_CACHE_REDIS_VERSION_TTL	168h

• internal/config/cache_redis.go: CacheRedisConfig + CacheRedisTLS, with the block's checks in Cache.validate(). Its defaults live in defaults() with the rest of the boot config (fix(config): keep an explicit false/0/"" from config.yaml #632's convention). CacheRedisTLS.Config() builds the *tls.Config from the file paths. Validate calls it, so an unreadable or unparsable file refuses boot.
• internal/config/backends.go: CacheRedis is added to cacheBackends. Warnings() gains two lines, emitted by a process with the api role like the others: tls.insecure_skip_verify, and a cache.redis.addrs set while the backend is local (the block is not read).
• internal/config/config.go: the refusal of api without ingest (or the reverse) over cache.backend: local, from feat(app): process roles #622, now names cache.backend=redis as the shared cache to set. Every split is still refused while mq.backend is embedded.
• internal/app/wire.go: wireCache has a redis case. redisConfig maps the block onto cache.RedisConfig (Load has already applied the defaults). Both backends share one component (close → Close) and perf(cache): flat version index, pruned per tenant #621's prune hook, which acts only on a pruner and so skips Redis.
• Boot with Redis down or refusing the password: kept as feat(cache): shared cache backend on Redis, Valkey and Dragonfly #626 built it. The process boots degraded, the cache is bypassed, and it keeps reconnecting. A rejected credential logs at ERROR on every attempt. This is documented in configuration.mdx, along with the separate runtime behavior: a rejected credential also trips the circuit breaker at once once connected, while a scoped NOPERM deliberately does not.

Decisions

• timeout and dial_timeout are each capped at 1s. Boot waits out one dial, and so does the cache's Close when a reconnect is in flight (rueidis.NewClient takes no context). A dial is a connect plus a handshake, each bounded by dial_timeout. In cluster mode it also includes a topology read, which feat(cache): shared cache backend on Redis, Valkey and Dragonfly #626 bounds by max(dial_timeout, timeout). At the caps a dial takes at most 3s, inside the 5s ReleaseTimeout that the cache's close shares with the queue, dedupe and ClickHouse released after it (the breaker's own background probe runs in an untracked goroutine and does not affect this arithmetic). A 2s dial cap would have allowed 6s. The defaults are unchanged.
• Sentinel is refused, and sentinel_master is removed rather than kept and refused. A key that no config can use would clutter the reference, and the strict loader now reports it (and WH_CACHE_REDIS_SENTINEL_MASTER) as unknown, so nobody sets it believing it works. bug(cache): a demoted Redis primary reads as healthy; Sentinel mode is unconfigured #656 can bring it back together with the sentinel credentials and topology refresh it needs.
• standalone takes exactly one address. rueidis's single client dials only the first, so a second one (a replica, say) used to be silently ignored. Several addresses are a cluster's seeds, and a port must be 1–65535.
• A URL-style address is refused without echoing it. WH_CACHE_REDIS_ADDRS=redis://default:s3cret@redis:6379 used to fail with the password quoted twice in the boot error. An address containing :// or @ is now refused by its position, with a pointer to username, password and tls.enabled.
• compress_min_bytes: 0 means never compress, which is the backend's own meaning. fix(config): keep an explicit false/0/"" from config.yaml #632 fixed bug(config): an explicit false/0 in config.yaml is replaced by the field's env-default #631, so a 0 in config.yaml is kept, and the -1 sentinel this PR used to need is gone.
• Config validation duplicates some of cache.RedisConfig's checks (address syntax, mode, cluster db, prefix braces, version_ttl ≥ 2s). This way the errors name the WH_* variable, and internal/config stays a leaf package with no rueidis import.
• The struct type is CacheRedisConfig, since the backend constant is already CacheRedis.
• A TLS key set while tls.enabled is off refuses boot, rather than connecting in plaintext.
• The e2e suite runs on Redis. The orchestrator starts a pinned redis:8.10.2-alpine (tmpfs /data, no persistence). tests/e2e/fixtures/config.yaml sets cache.backend: redis with timeout: 1s, so a loaded runner doesn't bypass a lookup that the HIT assertions depend on. The e2e gate's cache-related excludes are internal/cache/pending.go (the retry of an invalidation the server did not take, which needs an outage), internal/config/cache_redis.go (the block's own rejection paths) and internal/cache/(local|version_manager).go (the local backend, which e2e no longer runs) — the unit suite covers them, and so does the integration suite, whose own app runs cache.backend: local and now asserts its hit, insert and fresh-miss lifecycle (TestLocalCache_IngestInvalidates).
• The ingest worker logs an invalidation that did not land at WARN, not ERROR, and so does the reconcile hook's InvalidateTenant failure. The shared backend defers and retries it, so a Redis outage used to log an ERROR for every batch; this only lowers the level, and volume stays at one WARN per batch during an outage. wavehouse_cache_invalidations_pending is the signal to alert on.

Tests

• Config (internal/config/cache_redis_test.go, defaults_test.go, roles_test.go):
  • defaults, every key via env (including the TLS files), and YAML;
  • a YAML compress_min_bytes: 0 kept as never;
  • cache.redis.* zero cases in fix(config): keep an explicit false/0/"" from config.yaml #632's tables, and configuration.mdx rows checked against defaults();
  • unknown sub-block keys (sentinel_master included) and unbound env vars;
  • a blank WH_CACHE_REDIS_ADDRS=;
  • URL-style addresses in 4 forms, where the error contains neither the address nor the secret;
  • a validation table covering sentinel refused, the 1s caps, and a negative compression size;
  • ignored-unless-selected, warnings, and the split-roles refusal with a redis cache.
• App wiring (internal/app/app_test.go):
  • It boots with backend: redis against a closed port. The cache is a *cache.RedisCache, bypassed: a lookup misses and a fill is a no-op. A reload's prune hook skips it.
  • An unreadable TLS file refuses boot.
  • TestRedisConfig_FromLoadedDefaults drives redisConfig from config.Load and compares the result with cache.Default*. A WH_CACHE_REDIS_COMPRESS_MIN_BYTES=0 reaches the backend as 0.
  • TestRedisConfig_UsernameDBTLSMapped (new): the defaults test leaves Username, DB and TLS at their zero value on both sides, so deleting any of their three mapping lines in redisConfig wouldn't fail it. This one drives all three to a non-zero value through config.Load and asserts on them directly. Mutation-checked: deleting each of the three lines in redisConfig fails it (the TLS line fails to compile instead, since dropping it leaves a local variable unused — still a build failure).
• Integration (tests/integration/shared_cache_test.go, pinned redis:8.10.2-alpine):
  • TestSharedCache_IngestOnOneInstanceInvalidatesAnother: two app.New instances over one Redis and the suite's ClickHouse. Mutation-checked: with RedisCache.Invalidate as a no-op, it fails.
  • TestSharedCache_RedisDownQueriesBypass: Redis paused. Queries succeed as MISS, and a row ingested meanwhile is served. After the pause, queries turn back to HITs.
  • TestLocalCache_IngestInvalidates (new): the same lifecycle on the suite's own local app. Mutation-checked: with LocalCache.Invalidate as a no-op, it fails (the row landed 10.0s after the fill, every round).
• make ci is green: unit 91.8%, integration 53.5%, e2e 60.3% (on Redis), Go total 94.9%, ts-total 82.28%.

Metrics

These are unchanged from #626. They are emitted from the first process that sets cache.backend: redis. Meter wavehouse-cache, every series labeled backend="redis", no tenant label: wavehouse_cache_lookups_total{result}, wavehouse_cache_op_duration_seconds{op}, wavehouse_cache_breaker_open, wavehouse_cache_invalidations_total{result} (ok and deferred overlap — a retried landing counts ok again), wavehouse_cache_invalidations_pending, wavehouse_cache_value_bytes, wavehouse_cache_oversize_total, wavehouse_cache_set_failures_total{reason}. No monitored deployment sets the backend yet.

Deliberately left to later PRs

• A later PR: the near-cache (cache.redis.near_cache.*). The key is refused as unknown until then.
• Sentinel (bug(cache): a demoted Redis primary reads as healthy; Sentinel mode is unconfigured #656): refused at validation until the backend authenticates to the sentinels, refreshes their topology and has a test.
• pool_size: not added. feat(cache): shared cache backend on Redis, Valkey and Dragonfly #626 did not implement it, and a knob that does nothing would mislead.
• bug(pipes): mutation pipe results are cached and coalesced — the write silently drops on repeat calls #386 / bug(query): admin mutations via /v1/admin/query don't invalidate the structured-query cache — stale reads for up to an hour #394: a shared cache widens both from one pod to the fleet (both are in deployment.md). bug(pipes): mutation pipe results are cached and coalesced — the write silently drops on repeat calls #386 should be fixed before any real deployment sets backend: redis.

🤖 Generated with Claude Code

https://claude.ai/code/session_017aS7rLrH1RKkUMem7X4ckd

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 767be85a-11d8-4df6-a8c8-bf5df467bcb0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}