Documentation
¶
Overview ¶
Package cache implements Redis-backed response caching and cache key generation utilities.
Index ¶
- func CheckHealth(ctx context.Context, client *redis.Client, timeout time.Duration) error
- func NewRedisClient(ctx context.Context, cfg config.RedisConfig) (*redis.Client, error)
- type CacheInvalidateConfig
- type CacheReadConfig
- type CacheVaryBy
- type CachedResponse
- type Manager
- func (m *Manager) BuildReadKey(ctx context.Context, r *http.Request, route string, cfg CacheReadConfig) (string, error)
- func (m *Manager) BumpTags(ctx context.Context, tags []string) error
- func (m *Manager) DefaultMaxBytes() int
- func (m *Manager) Get(ctx context.Context, key string) (CachedResponse, bool, error)
- func (m *Manager) Observe(route, outcome string)
- func (m *Manager) ResolveFailOpen(override *bool) bool
- func (m *Manager) Set(ctx context.Context, key string, value CachedResponse, ttl time.Duration) error
- func (m *Manager) TagVersionToken(ctx context.Context, tags []string) (string, error)
- type ManagerConfig
- type ObserveFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckHealth ¶
CheckHealth performs a bounded Redis ping health check.
func NewRedisClient ¶
NewRedisClient builds and validates a Redis client from runtime config.
Types ¶
type CacheInvalidateConfig ¶
type CacheInvalidateConfig struct {
// Tags identifies invalidation groups to bump on successful writes.
Tags []string
// FailOpen overrides manager-level fail-open policy when set.
FailOpen *bool
}
CacheInvalidateConfig defines route-level cache invalidation behavior.
type CacheReadConfig ¶
type CacheReadConfig struct {
// Key optionally overrides route pattern as cache key route segment.
Key string
// TTL defines cache entry lifetime and must be greater than zero.
TTL time.Duration
// MaxBytes limits cacheable response body bytes for this route.
MaxBytes int
// Tags identifies invalidation groups used by CacheInvalidate.
Tags []string
// Methods limits cache reads to selected methods (GET/HEAD by default).
Methods []string
// CacheStatuses limits cache writes to selected HTTP statuses (200 by default).
CacheStatuses []int
// VaryBy defines dynamic cache key dimensions.
VaryBy CacheVaryBy
// FailOpen overrides manager-level fail-open policy when set.
FailOpen *bool
// AllowAuthenticated marks authenticated responses as cache-eligible when safely varied.
AllowAuthenticated bool
}
CacheReadConfig defines route-level read-cache behavior.
type CacheVaryBy ¶
type CacheVaryBy struct {
// Method includes HTTP method in cache key.
Method bool
// TenantID includes principal tenant in cache key.
TenantID bool
// UserID includes principal user in cache key.
UserID bool
// Role includes principal role in cache key.
Role bool
// PathParams includes selected route params in cache key.
PathParams []string
// QueryParams includes selected query params in cache key.
QueryParams []string
// Headers includes selected request headers in cache key.
Headers []string
}
CacheVaryBy controls which request dimensions participate in cache key generation.
type CachedResponse ¶
type CachedResponse struct {
// Status is the cached HTTP status code.
Status int `json:"status"`
// Body is the cached HTTP response body.
Body []byte `json:"body"`
// ContentType is the cached Content-Type header value.
ContentType string `json:"content_type,omitempty"`
}
CachedResponse stores serialized HTTP response data in Redis.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager encapsulates Redis-backed cache operations and key building.
func NewManager ¶
func NewManager(client redis.UniversalClient, cfg ManagerConfig) (*Manager, error)
NewManager constructs a cache manager with validated defaults.
func (*Manager) BuildReadKey ¶
func (m *Manager) BuildReadKey(ctx context.Context, r *http.Request, route string, cfg CacheReadConfig) (string, error)
BuildReadKey builds a deterministic read key for route cache lookup.
Notes: - Uses low-cardinality route patterns - Supports selected vary dimensions only - Includes tag version token for O(1) invalidation
func (*Manager) DefaultMaxBytes ¶
DefaultMaxBytes returns manager-level fallback cache size cap.
func (*Manager) ResolveFailOpen ¶
ResolveFailOpen resolves route override or manager default fail-open policy.
type ManagerConfig ¶
type ManagerConfig struct {
// Env namespaces cache keys by environment.
Env string
// FailOpen controls whether read/write failures should bypass instead of failing requests.
FailOpen bool
// DefaultMaxBytes sets fallback response size cap when route does not override MaxBytes.
DefaultMaxBytes int
// Observe receives cache outcome signals for metrics.
Observe ObserveFunc
}
ManagerConfig configures cache manager defaults.
type ObserveFunc ¶
type ObserveFunc func(route, outcome string)
ObserveFunc records cache operation outcomes for metrics integration.
Source Files