feat(cache-valkey): initial implementation — Provider, adapters (v1.0.0)

Introduces code.nochebuena.dev/einherjar/cache-valkey — the Valkey cache starter
for the Einherjar framework. Absorbs the valkey package from micro-lib and adds
three duck-typed adapters that wire directly into auth, web, and auth-jwt.

Core:
- Provider interface — Get, Set, Del, Exists, Expire, IncrWithTTL, Native()
- Component interface — lifecycle.Component + observability.Checkable + Provider
- Config struct (EINHERJAR_VALKEY_* env vars)
- New(logger, cfg) Component — creates valkey-go client in OnInit;
  PING in OnStart; logs "valkey: connected"
- IncrWithTTL implemented with Lua script (atomic INCR + conditional EXPIRE);
  race-free fixed-window semantics with no MULTI/EXEC overhead
- Priority: LevelDegraded — Valkey outage degrades, does not halt the service

Adapters (duck-typed — no import of auth, web, or auth-jwt):
- PermissionCache — Get/Set int64 bitmasks as string; satisfies auth/rbac.Cache
- RateLimiterStore — fixed-window via IncrWithTTL; satisfies web/mw.RateLimiterStore
- Blacklist — Exists/Set "1" with TTL; satisfies auth-jwt.Blacklist

Compliance test verifies CT-6, duck-type shape assignments, and full adapter
behavioural coverage with a mockProvider (no live server required).

- Component interface embeds observability.Identifiable; identifiable.go implements
  ModulePath and ModuleVersion via runtime/debug.ReadBuildInfo() — prints in launcher banner
This commit is contained in:
2026-05-29 15:58:56 +00:00
commit df7aa63e5c
21 changed files with 2105 additions and 0 deletions

49
permission_cache.go Normal file
View File

@@ -0,0 +1,49 @@
package cachevalkey
import (
"context"
"strconv"
"time"
"code.nochebuena.dev/einherjar/core/xerrors"
)
// rbacCacheShape mirrors auth/rbac.Cache for compile-time duck-type verification.
// Cache-valkey must not import auth/rbac (D-1), so the shape is defined locally.
type rbacCacheShape interface {
Get(ctx context.Context, key string) (int64, bool, error)
Set(ctx context.Context, key string, value int64, ttl time.Duration) error
}
var _ rbacCacheShape = (*PermissionCache)(nil)
// PermissionCache is a Valkey-backed cache for int64 permission bitmasks.
// Satisfies auth/rbac.Cache via duck typing — no import of that package required.
//
// Values are stored as decimal strings and parsed back to int64 on read.
type PermissionCache struct {
provider Provider
}
// NewPermissionCache returns a PermissionCache backed by p.
func NewPermissionCache(p Provider) *PermissionCache {
return &PermissionCache{provider: p}
}
// Get retrieves a permission bitmask. Returns (0, false, nil) on cache miss.
func (c *PermissionCache) Get(ctx context.Context, key string) (int64, bool, error) {
val, ok, err := c.provider.Get(ctx, key)
if err != nil || !ok {
return 0, ok, err
}
n, err := strconv.ParseInt(val, 10, 64)
if err != nil {
return 0, false, xerrors.Internal("valkey: permission cache: corrupted value for key %q", key).WithError(err)
}
return n, true, nil
}
// Set stores a permission bitmask with the given TTL.
func (c *PermissionCache) Set(ctx context.Context, key string, value int64, ttl time.Duration) error {
return c.provider.Set(ctx, key, strconv.FormatInt(value, 10), ttl)
}