redis

type Cache ¶

type Cache struct {
	// contains filtered or unexported fields
}

Cache provides a typed key-value cache backed by Redis. All keys are prefixed with the constructor-injected KeyNamespace, giving each owner (cell or shared role) an isolated keyspace.

func NewCache(client *Client, ns KeyNamespace) (*Cache, error)

func (c *Cache) Delete(ctx context.Context, key string) error

func (c *Cache) Get(ctx context.Context, key string) (string, error)

func (c *Cache) Set(ctx context.Context, key string, value string, ttl time.Duration) error

type CachingSessionStore ¶

type CachingSessionStore struct {
	// contains filtered or unexported fields
}

CachingSessionStore is a read-through Redis cache decorator over a runtime/auth/session.Store. The wrapped (inner) store remains the system of record; the Redis cache only accelerates Get. Construction-time fail-fast ensures wiring misconfigurations surface at startup, not at the first request.

Behavior summary (T5/AUTH-CACHE-01 plan; #794 metrics; #796 after-commit DEL):

• Get: cache hit → unmarshal sessionCacheEntry → entry.validate(id). On validation failure: slog.Warn + synchronous cache.Delete (best-effort, Delete errors logged at Warn) + fall through to inner.Get. Miss / Redis error / corrupt JSON → slog.Warn + synchronous cache.Delete (same best-effort contract) + fall through to inner.Get. On inner success only active (RevokedAt == nil) views are lazily populated into the cache (Set error is also swallowed). Every Get records exactly one hit or miss metric; every cache-access error additionally records an error metric.
• Create: delegated to inner. No cache write — the first Get after Create primes the cache via the read-through path (avoids "created then revoked" edge thinking and removes a method's worth of code).
• Revoke: delegates to inner, then registers a post-commit cache-DEL via persistence.RegisterAfterCommit (#796). The DEL fires AFTER the revoke commit is durable, so it cannot race with concurrent re-population from a still-uncommitted PG row (the 2×TTL race that the rejected in-transaction cache.Delete suffered). This drives the single-session stale-cache window to near-zero (the commit→hook gap) rather than the prior full-TTL floor. Contract: Revoke MUST be called within a RunInTx scope (sessionlogout wraps it — see §Threat model); calling it outside an active tx panics via RegisterAfterCommit (programmer error). The hook is a pure transient side effect (cache.Delete only) — archtest AFTERCOMMIT-HOOK-PURE-TRANSIENT-01 forbids it from touching the tx/outbox, and archtest CACHING-SESSION-REVOKE-AFTERCOMMIT-DEL-01 forbids any cache mutation in the Revoke body OUTSIDE the after-commit hook (relocating, not removing, the 2×TTL protection).
• RevokeForSubject: delegated to inner with NO cache operation. The only caller is credentialinvalidate.Apply (archtest CREDENTIAL-INVALIDATE-FUNNEL-01) which co-tx bumps users.authz_epoch. Any stale cached ValidateView is rejected by sessionvalidate's epoch invariant (user.AuthzEpoch != view.AuthzEpochAtIssue → fail-closed 401). user.AuthzEpoch is intentionally NOT cached, so this path needs no after-commit DEL — the epoch bump is its near-zero invalidation already. Hard-locked delegate-only by archtest CACHING-SESSION-REVOKE-DELEGATE-ONLY-01. (Subject-wide cache purge for the future case where user state IS cached is the deferred AUTH-CACHE-SUBJECT-REVERSE-INDEX-01 / gh #793.)
• RepoReady: delegated to inner. Redis liveness is independently surfaced by adapters/redis Client.Checkers (probe redis_ready).

All cache.{Get,Set,Delete} read-path errors are fail-safe: the wrapper logs at Warn (and records a session_cache_errors_total metric) and falls through to / continues with the inner result. Only inner errors propagate to callers, preserving sessionvalidate's KindUnavailable → 503 semantics for genuine session-store outages.

Threat model ¶

• Stale-cache revoke window (single-session sessionlogout): Revoke now registers an after-commit cache.Delete hook (#796), so the cached entry is purged immediately after the revoke commit becomes durable. The residual window is the commit→hook gap (near-zero — the hook runs synchronously on the committing goroutine before RunInTx returns), NOT a full TTL. The earlier in-transaction cache.Delete was rejected (PR #524 → fix PR) because it raced with concurrent re-population from the still-uncommitted PG row (a Get arriving between inner Revoke and commit would lazyPopulate a fresh full-TTL entry), potentially extending the window to 2×TTL; firing the DEL after commit removes that race because the row is already revoked when the hook runs, so any concurrent lazyPopulate reads the revoked state and skips the write (revoked views are never cached). The TTL remains a fail-safe backstop: if the after-commit DEL itself fails (best-effort, logged at Warn + counted as session_cache_revoke_del_errors_total) the entry still expires at TTL — a stale ≤ TTL window that is the accepted degraded behavior on this path (single-session Revoke does not bump the epoch, so TTL is the only floor). RevokeForSubject paths (credentialinvalidate.Apply) have an independent, equally-near-zero floor — the co-tx user.AuthzEpoch bump fails the cached AuthzEpochAtIssue check in sessionvalidate.go regardless of cache state.
• Redis keyspace enumeration: cache keys take the form accesscore:session:<rawSessionID>; anyone with redis-cli KEYS / SCAN access can enumerate active session identifiers. Operators MUST gate Redis with ACL so only ops accounts can enumerate the keyspace; the cache itself does not hash the session ID (consistent with PG which also stores raw sessions.id).
• JSON wire schema: a dedicated sessionCacheEntry struct (not the full session.ValidateView) is the on-wire shape. Adding a sensitive field to ValidateView does NOT automatically propagate into Redis — the copy is explicit, providing an audit gate. The flip side of that gate (alexedwards/scs store contract: a cache projection must stay equivalent to the source-of-record for every field the validate path consumes): an authentication-DECISION field added to ValidateView MUST also land in sessionCacheEntry, or a cache HIT silently degrades the decision. TenantID (#1337 PR-3b: the RLS scope carrier) is such a field and is cached.

Ops guidance ¶

Single-session logout invalidates the cache near-instantly via the after-commit DEL (#796) — the residual stale window is only the commit→hook gap (effectively zero; the hook runs synchronously on the committing goroutine before RunInTx returns). Any concurrent Get that arrives between inner.Revoke and commit cannot re-populate the cache (the row is still uncommitted) and will fall through to inner; a Get after commit reads the revoked row and skips lazyPopulate.

DEL-failure backstop is TTL, not epoch. Should the after-commit DEL itself fail (best-effort, logged at Warn + counted as session_cache_revoke_del_errors_total), the logged-out session's cached active ValidateView can still satisfy sessionvalidate (RevokedAt == nil, epoch unchanged) and be served on a cache HIT until the entry expires at TTL. Single-session Revoke does NOT bump users.authz_epoch, so the epoch-based fail-closed net does NOT apply on this path — that net is exclusive to RevokeForSubject / credential invalidation (which bumps the epoch co-tx, see §Threat model). The bounded residual (stale ≤ TTL, capped by GOCELL_SESSION_CACHE_TTL) is the accepted degraded behavior of #796's TTL backstop; operators alert on session_cache_revoke_del_errors_total to detect sustained DEL failures (docs/ops/alerting-rules.md). For zero-tolerance stale cache requirements (e.g. an ongoing breach investigation where every session must be invalidated atomically), disable the cache by leaving GOCELL_SESSION_CACHE_TTL empty — this removes the cache entirely from the trust path.

ref: alexedwards/scs redisstore/redisstore.go@master (PEXPIREAT object-level expiry alignment — we use fixed Duration TTL because ValidateView hides ExpiresAt by design, see runtime/auth/session.Session.ExpiresAt godoc). ref: go-redis/cache cache.go@v9 (fail-open model). ref: spring-tx TransactionSynchronization.afterCommit (post-commit cache eviction); kernel/persistence.RegisterAfterCommit is the GoCell analog.

func NewCachingSessionStore(
	inner session.Store, cache *Cache, ttl time.Duration, logger *slog.Logger, recorder cacheMetricsRecorder,
) (*CachingSessionStore, error)

func (s *CachingSessionStore) Create(ctx context.Context, t tenant.TenantID, sess *session.Session) error

func (s *CachingSessionStore) Get(ctx context.Context, id string) (*session.ValidateView, error)

func (s *CachingSessionStore) RepoReady(ctx context.Context) error

func (s *CachingSessionStore) Revoke(ctx context.Context, id string) error

func (s *CachingSessionStore) RevokeForSubject(
	ctx context.Context, subjectID string, event session.CredentialEvent, tok credentialfence.FenceToken,
) error

type Client ¶

type Client struct {
	// contains filtered or unexported fields
}

Client wraps a go-redis universal client and provides health checking and lifecycle management.

func NewClient(ctx context.Context, cfg Config) (*Client, error)

func NewClientForTest(rdb goredis.UniversalClient) *Client

func (c *Client) Close(ctx context.Context) error

func (c *Client) Config() Config

func (c *Client) Health(ctx context.Context) error

func (c *Client) PoolStats() PoolStats

func (c *Client) Probes() []healthz.Probe

func (c *Client) Statter(name string) poolstats.Statter

func (c *Client) Worker() worker.Worker

type Config ¶

type Config struct {
	// Addr is the address of the standalone Redis instance (e.g. "localhost:6379").
	Addr string

	// SentinelAddrs is the list of Sentinel addresses for Sentinel mode.
	SentinelAddrs []string

	// SentinelMaster is the name of the master instance for Sentinel mode.
	SentinelMaster string

	// ClusterAddrs is the list of Redis Cluster node addresses for Cluster mode.
	// Plain "host:port" or "rediss://host:port" URL forms are accepted; they
	// must not be mixed within a single cluster definition. DB must be 0 in
	// Cluster mode (no SELECT command).
	ClusterAddrs []string

	// Mode selects standalone, sentinel, or cluster. Defaults to ModeStandalone.
	Mode Mode

	// Password is the auth password, if any.
	Password string

	// DB is the database number. Defaults to 0.
	DB int

	// DialTimeout is the connection dial timeout. Defaults to 5s.
	DialTimeout time.Duration

	// ReadTimeout is the read timeout. Defaults to 3s.
	ReadTimeout time.Duration

	// WriteTimeout is the write timeout. Defaults to ReadTimeout.
	WriteTimeout time.Duration

	// DistLockTTL is the default TTL for distributed locks. Defaults to 30s.
	DistLockTTL time.Duration

	// PoolSize is the maximum number of connections go-redis is allowed to
	// maintain. Zero applies a per-mode default mirroring go-redis: 10×GOMAXPROCS
	// for standalone/sentinel and 5×GOMAXPROCS for cluster (where the same
	// PoolSize applies *per node* — total cluster connections = nodes × PoolSize,
	// so the per-node default is halved to keep aggregate sizing comparable).
	// Set this explicitly for workloads whose steady-state checkouts would exceed
	// the library default — required for meaningful db.client.connection.max
	// emissions on the pool stats collector.
	PoolSize int

	// AllowUnsafeNoPassword is the explicit dev/test escape hatch for an
	// empty Password. The default (false) makes validateConfig reject any
	// configuration that would silently connect to an unauthenticated Redis,
	// closing B2-A-28's fail-open hole. Composition root sets this to true
	// only when bootstrap.Topology.RequireProductionControlPlane() is false
	// (i.e. dev / single-pod / non-production deployments).
	AllowUnsafeNoPassword bool
}

Config holds connection and behavioral settings for the Redis adapter.

func (c Config) LogValue() slog.Value

type HTTPIdempotencyStore ¶

type HTTPIdempotencyStore struct {
	// contains filtered or unexported fields
}

HTTPIdempotencyStore implements idemhttp.Store using a three-key Lua script model that stores the full HTTP response blob for replay plus the request fingerprint for key-reuse detection.

Consistency: L1 (LocalTx) — each Lua script executes atomically within Redis.

• <store-ns>:<req-ns>:{key}:lease — SET NX with leaseTTL, value = random token. Indicates "processing".
• <store-ns>:<req-ns>:{key}:resp — SET with doneTTL, value = MarshalRecordedResponse blob. Indicates "completed".
• <store-ns>:<req-ns>:{key}:fp — SET with leaseTTL while processing; Record extends it to doneTTL. Value = body fingerprint; flags same-key/different-body reuse.

The key prefix has two segments, both OUTSIDE the hashtag:

• <store-ns> = the construction-time KeyNamespace (s.ns), the owner dimension — e.g. "_runtime" for the shared corebundle store — following the same owner-prefix convention as the other adapters/redis primitives (see KeyNamespace doc).
• <req-ns> = the request-time ns passed to Claim (caller TenantID or the "_notenant" sentinel), the tenant sub-partition.

Cluster: keys are wrapped in a Redis Cluster hashtag so CRC16 hashes only the business-key portion; the lease, resp, and fp keys all colocate on the same slot, keeping multi-KEY EVAL safe under Cluster mode. Both prefix segments sit outside the hashtag, so slot colocality is preserved regardless of either namespace value.

Claim compares fp only while resp or lease is active. With resp present it returns ClaimDone+replay after validating fp; with lease present it returns ClaimBusy after validating fp; when neither exists it acquires lease and stores fp for the leaseTTL. Record sets resp + extends fp to doneTTL + deletes lease. Release deletes lease + fp (token-guarded); there is no response to protect.

func NewHTTPIdempotencyStore(client *Client, ns KeyNamespace) (*HTTPIdempotencyStore, error)

func (s *HTTPIdempotencyStore) Claim(
	ctx context.Context, k idemhttp.IdempotencyKey, fingerprint string, leaseTTL time.Duration,
) (idempotency.ClaimState, *idemhttp.RecordedResponse, idemhttp.Receipt, error)

<store-ns>:<ns>:{<key>}:lease  and  …:resp  and  …:fp

func (s *HTTPIdempotencyStore) ReadyCheck(ctx context.Context) error

type IdempotencyClaimer ¶

type IdempotencyClaimer struct {
	// contains filtered or unexported fields
}

IdempotencyClaimer implements idempotency.Claimer using a dual-key Lua script model:

Consistency: L1 (LocalTx) — each Lua script executes atomically within Redis.

• <ns>:{key}:lease — SET NX with leaseTTL, value = random token. Indicates "processing".
• <ns>:{key}:done — SET with doneTTL, value = "1". Indicates "completed".

Cluster: the business key is wrapped in a Redis Cluster hashtag so CRC16 hashes only the key portion; lease and done keys colocate on the same slot, keeping multi-KEY EVAL safe under Cluster mode (B10 PR-V1-REDIS-CLUSTER). The KeyNamespace prefix sits outside the hashtag so slot colocality is preserved regardless of namespace value.

Claim checks done first (ClaimDone), then attempts lease (ClaimAcquired or ClaimBusy). Commit sets done + deletes lease. Release deletes lease (token-guarded).

func NewIdempotencyClaimer(client *Client, ns KeyNamespace) (*IdempotencyClaimer, error)

func (c *IdempotencyClaimer) Claim(
	ctx context.Context, key string, leaseTTL, doneTTL time.Duration,
) (idempotency.ClaimState, idempotency.Receipt, error)

func (c *IdempotencyClaimer) Kind() idempotency.ClaimerKind

type KeyNamespace ¶

type KeyNamespace string

KeyNamespace scopes every Redis key produced by the four primitives in this adapter (Cache, IdempotencyClaimer, NonceStore, RedisDriver) under a constructor-injected prefix.

Convention:

• Per-cell resources (e.g. a cache owned by accesscore) use the cell ID as the namespace, e.g. KeyNamespace("accesscore").

• Shared infrastructure constructed at composition root (cmd/corebundle) uses an explicit role label or the "_runtime" sentinel:

  newRedisNonceStore -> KeyNamespace("servicetoken-nonce") newRedisIdempotencyClaimer -> KeyNamespace("_runtime")

Validation forbids characters that would break Redis Cluster hashtag boundaries ('{', '}'), the prefix/key separator (':'), and other ambiguous punctuation. The first character may be a lowercase letter or underscore (the underscore lets sentinel namespaces like "_runtime" be visually distinct from cell IDs, which are constrained to lowercase letters by the no-dash policy on cell.yaml IDs).

ref: launchdarkly/go-server-sdk-redis-go-redis Builder.Prefix (constructor-injected prefix pattern) ref: dapr/components-contrib state appID prefix (constructor-injected tenancy) ref: cockroachdb/cockroach pkg/keys MakeTenantPrefix (lint-guarded tenant boundary)

func (n KeyNamespace) Validate() error

type Mode ¶

type Mode string

Mode represents the Redis deployment topology.

const (
	// ModeStandalone connects to a single Redis instance.
	ModeStandalone Mode = "standalone"
	// ModeSentinel connects via Redis Sentinel for high availability.
	ModeSentinel Mode = "sentinel"
	// ModeCluster connects to a Redis Cluster (sharded keyspace).
	// AWS ElastiCache Cluster, Azure Cache Cluster and self-hosted Redis
	// Cluster deployments use this mode. DB selection is unavailable on
	// Cluster (no SELECT command); multi-KEY operations require all keys
	// to share a hashtag (B10 PR-V1-REDIS-CLUSTER).
	ModeCluster Mode = "cluster"
)

type NonceStore ¶

type NonceStore struct {
	// contains filtered or unexported fields
}

NonceStore implements kauth.NonceStore using Redis SET NX EX semantics. It is safe for multi-pod service-token replay protection because every first-use claim is coordinated by Redis.

Keys land under the constructor-injected KeyNamespace, e.g. `servicetoken-nonce:<nonce>`. The namespace replaces the previous hard-coded `servicetoken:nonce:` prefix; layering namespace + role constant added no information beyond what KeyNamespace itself encodes.

func NewNonceStore(client *Client, ns KeyNamespace, ttl time.Duration) (*NonceStore, error)

func (s *NonceStore) CheckAndMark(ctx context.Context, nonce string) error

func (*NonceStore) Kind() kauth.NonceStoreKind

type PoolStats ¶

type PoolStats struct {
	Hits       uint32 `json:"hits"`       // times free connection was found in pool
	Misses     uint32 `json:"misses"`     // times free connection was NOT found in pool
	Timeouts   uint32 `json:"timeouts"`   // times a wait timeout occurred
	TotalConns uint32 `json:"totalConns"` // total connections in pool
	IdleConns  uint32 `json:"idleConns"`  // idle connections in pool
	StaleConns uint32 `json:"staleConns"` // stale connections removed from pool
}

PoolStats holds structured connection pool statistics.

ref: go-redis PoolStats / redisprometheus — adopted same field set.

type RedisDriver ¶

type RedisDriver struct {
	// contains filtered or unexported fields
}

RedisDriver implements runtime/distlock.Driver using Redis SET NX EX and two Lua scripts for atomic renew and release operations. All lock keys are prefixed with the constructor-injected KeyNamespace so per-cell or per-role driver instances cannot collide.

func NewRedisDriver(client *Client, ns KeyNamespace) (*RedisDriver, error)

func (d *RedisDriver) Release(ctx context.Context, key, token string) error

func (d *RedisDriver) Renew(ctx context.Context, key, token string, ttl time.Duration) (bool, error)

func (d *RedisDriver) SetNX(ctx context.Context, key, token string, ttl time.Duration) (bool, error)

type RedisReconcileElector ¶

type RedisReconcileElector struct {
	// contains filtered or unexported fields
}

RedisReconcileElector implements reconcile.LeaderElector using Redis SET NX PX for the holder lease and an INCR'd epoch key for the monotonic fencing token. Release reuses the package's ownership-guarded releaseLockScript (the epoch key is never deleted on release so a subsequent holder always observes a strictly higher epoch); acquire/renew use the reconcile-specific scripts above.

Both keys are KeyNamespace-prefixed AND share a {reconcilerID} hash tag so they colocate on one Redis Cluster slot: the holder key is "<ns>:{<rid>}:lease" and the epoch key is "<ns>:{<rid>}:epoch".

func NewRedisReconcileElector(
	client *Client, ns KeyNamespace, leaseDuration time.Duration, clk clock.Clock,
) (*RedisReconcileElector, error)

func (e *RedisReconcileElector) AcquireLease(ctx context.Context, reconcilerID string) (reconcile.LeaseToken, error)

func (e *RedisReconcileElector) ReleaseLease(ctx context.Context, token reconcile.LeaseToken) error

func (e *RedisReconcileElector) RenewLease(ctx context.Context, token reconcile.LeaseToken) error