cache

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)
• func NormalizeRoute(route string) string
• func ResolveTagNames(r *http.Request, specs []CacheTagSpec) ([]string, error)
• type CacheInvalidateConfig
• type CacheReadConfig
• type CacheTagLiteral
• type CacheTagSpec
  • func PrepareTagSpecs(specs []CacheTagSpec) []CacheTagSpec
• type CacheVaryBy
• type CachedResponse
• type Manager
  • func NewManager(client redis.UniversalClient, cfg ManagerConfig) (*Manager, error)
  • func (m *Manager) BuildReadKey(ctx context.Context, r *http.Request, route string, cfg CacheReadConfig) (string, error)
  • func (m *Manager) BuildReadKeyWithTemplate(ctx context.Context, r *http.Request, route string, template ReadKeyTemplate) (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
• type ReadKeyTemplate
  • func PrepareReadKeyTemplate(cfg CacheReadConfig) ReadKeyTemplate

Functions

func CheckHealth

func CheckHealth(ctx context.Context, client *redis.Client, timeout time.Duration) error

CheckHealth performs a bounded Redis ping health check.

func NewRedisClient

func NewRedisClient(ctx context.Context, cfg config.RedisConfig) (*redis.Client, error)

NewRedisClient builds and validates a Redis client from runtime config.

func NormalizeRoute

func NormalizeRoute(route string) string

NormalizeRoute returns a canonical low-cardinality route label used by cache keys.

func ResolveTagNames

func ResolveTagNames(r *http.Request, specs []CacheTagSpec) ([]string, error)

ResolveTagNames resolves runtime tag names from a request and prepared specs.

Types

type CacheInvalidateConfig

type CacheInvalidateConfig struct {
	// TagSpecs identifies invalidation scopes to bump on successful writes.
	TagSpecs []CacheTagSpec
	// 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
	// TagSpecs identifies invalidation scopes resolved from request/auth context.
	TagSpecs []CacheTagSpec
	// 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 CacheTagLiteral

type CacheTagLiteral struct {
	Key   string
	Value string
}

CacheTagLiteral is a constant key/value dimension appended to a resolved tag.

type CacheTagSpec

type CacheTagSpec struct {
	// Name is the base tag family name (for example, "project" or "project-list").
	Name string
	// PathParams appends selected path params (for example, "id") to scope invalidation.
	PathParams []string
	// TenantID appends auth tenant id to scope invalidation.
	TenantID bool
	// UserID appends auth user id to scope invalidation.
	UserID bool
	// Literals appends constant dimensions to distinguish related scopes.
	Literals []CacheTagLiteral
}

CacheTagSpec defines how a route-level tag should be resolved at runtime.

func PrepareTagSpecs

func PrepareTagSpecs(specs []CacheTagSpec) []CacheTagSpec

PrepareTagSpecs normalizes tag specs for stable request-time resolution.

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) BuildReadKeyWithTemplate

func (m *Manager) BuildReadKeyWithTemplate(ctx context.Context, r *http.Request, route string, template ReadKeyTemplate) (string, error)

BuildReadKeyWithTemplate builds a deterministic read key using a precomputed template.

func (*Manager) BumpTags

func (m *Manager) BumpTags(ctx context.Context, tags []string) error

BumpTags increments tag versions used for cache invalidation.

func (*Manager) DefaultMaxBytes

func (m *Manager) DefaultMaxBytes() int

DefaultMaxBytes returns manager-level fallback cache size cap.

func (*Manager) Get

func (m *Manager) Get(ctx context.Context, key string) (CachedResponse, bool, error)

Get fetches and decodes a cached response by key.

func (*Manager) Observe

func (m *Manager) Observe(route, outcome string)

Observe emits cache operation signals to configured observer.

func (*Manager) ResolveFailOpen

func (m *Manager) ResolveFailOpen(override *bool) bool

ResolveFailOpen resolves route override or manager default fail-open policy.

func (*Manager) Set

func (m *Manager) Set(ctx context.Context, key string, value CachedResponse, ttl time.Duration) error

Set stores a cached response for the given key and TTL.

func (*Manager) TagVersionToken

func (m *Manager) TagVersionToken(ctx context.Context, tags []string) (string, error)

TagVersionToken returns a stable token representing current tag versions.

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
	// TagVersionCacheTTL controls in-process cache duration for tag version tokens.
	TagVersionCacheTTL time.Duration
	// 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.

type ReadKeyTemplate

type ReadKeyTemplate struct {
	RoutePart          string
	Method             bool
	TenantID           bool
	UserID             bool
	Role               bool
	PathParams         []string
	QueryParams        []string
	Headers            []string
	TagSpecs           []CacheTagSpec
	AllowAuthenticated bool
}

ReadKeyTemplate stores precomputed static key-building dimensions for a route.

func PrepareReadKeyTemplate

func PrepareReadKeyTemplate(cfg CacheReadConfig) ReadKeyTemplate

PrepareReadKeyTemplate precomputes static route cache key dimensions.