cache-valkey/docs/adr/index.md

Architecture Decision Records — cache-valkey

ADR-001: Flat package (no sub-packages)

Status: Accepted

All three adapters (PermissionCache, RateLimiterStore, Blacklist) wrap the same Provider object and cannot function without the connection. Splitting into sub-packages (e.g., cachevalkey/permcache) would add import verbosity without providing any isolation benefit — every caller still needs the Component from New() before constructing any adapter.

Consistent with auth-jwt (single concern, flat package).

---

ADR-002: Provider interface wraps common ops; Native() is the escape hatch

Status: Accepted

Provider exposes six operations using only standard Go types (string, bool, int64, time.Duration). Callers that need operations beyond this set call Native() vk.Client to access the full valkey-go client. This means:

• Code that only uses Provider methods does not need to import valkey-go.
• Code that calls Native() opts in to the valkey-go dependency explicitly.
• The Component interface extends Provider — pass the result of New() wherever a Provider is expected.

Pattern reference: micro-lib minio uses the same Client + Native() architecture.

---

ADR-003: Adapters take Provider, not vk.Client

Status: Accepted

Adapter constructors (NewPermissionCache, NewRateLimiterStore, NewBlacklist) accept Provider instead of vk.Client. Benefits:

1. Testability: adapter behavior is testable with a mockProvider in-process — no live Valkey server, no valkey-go mock library required.
2. Abstraction: adapters depend only on the six Provider methods, not on the full client API. If the underlying driver changes, adapters are unaffected.
3. Duck-typed wiring: in application code, Component satisfies Provider, so the result of New() is passed directly to adapter constructors:

vk := cachevalkey.New(logger, cfg)
permCache   := cachevalkey.NewPermissionCache(vk)             // → auth/rbac.Cache
rateLimiter := cachevalkey.NewRateLimiterStore(vk, time.Second, 100) // → web/mw.RateLimiterStore
blacklist   := cachevalkey.NewBlacklist(vk)                   // → auth-jwt.Blacklist

No cast, no glue interface. Go's structural typing handles the assignment.

---

ADR-004: IncrWithTTL uses Lua for atomic fixed-window rate limiting

Status: Accepted

The IncrWithTTL method implements the standard fixed-window counter via a Lua script:

local count = redis.call('INCR', KEYS[1])
if count == 1 then
  redis.call('EXPIRE', KEYS[1], ARGV[1])
end
return count

Lua scripts execute atomically in Valkey. The INCR + conditional EXPIRE pattern is race-free: the EXPIRE is set only on the first increment, preventing the window from being extended by racing requests.

Alternatives considered:

• MULTI/EXEC: achieves atomicity but is heavier and not pipeline-friendly.
• True sliding window with sorted sets: more accurate, but significantly higher memory and complexity for minimal real-world benefit in most rate-limiting scenarios.

---

ADR-005: Health priority LevelDegraded

Status: Accepted

Priority() returns observability.LevelDegraded, not LevelCritical. A Valkey outage degrades — it does not halt — the service:

• Rate limiting (RateLimiterStore) fails open (web/mw contract).
• Permission cache (PermissionCache) misses fall through to the base provider (rbac.CachedPermissionProvider degrades to uncached reads).
• Blacklist (Blacklist) errors propagate to authjwt.RefreshTokenPair, which returns the error to the caller (token refresh fails — safe outcome).

No case requires Valkey to be available for the service to process requests. Consistent with micro-lib valkey (health.LevelDegraded).