cachecfg

Documentation

Index

• Constants
• func NewCache[T any](ctx context.Context, cfg *Config, opts ...Option) (cache.Cache[T], error)
• type Config
  • func (cfg *Config) ValidateWithContext(ctx context.Context) error
• type Option
  • func WithLogger(logger logging.Logger) Option
  • func WithMetricsProvider(metricsProvider metrics.Provider) Option
  • func WithPillars(p *observability.Pillars) Option
  • func WithTracerProvider(tracerProvider tracing.TracerProvider) Option

Constants

const (
	// ProviderMemory is the memory provider.
	ProviderMemory = "memory"
	// ProviderRedis is the redis provider.
	ProviderRedis = "redis"
)

Functions

func NewCache

func NewCache[T any](ctx context.Context, cfg *Config, opts ...Option) (cache.Cache[T], error)

NewCache provides a Cache.

Types

type Config

type Config struct {
	Redis          *redis.Config             `env:",init"    envPrefix:"REDIS_"            json:"redis,omitempty"               yaml:"redis,omitempty"`
	Provider       string                    `env:"PROVIDER" json:"provider,omitempty"     yaml:"provider,omitempty"`
	CircuitBreaker circuitbreakingcfg.Config `env:",init"    envPrefix:"CIRCUIT_BREAKING_" json:"circuitBreakerConfig,omitzero" yaml:"circuitBreakerConfig,omitempty"`
	// Expiry is the default expiry for writes that don't specify one via
	// cache.WithExpiry; a non-positive value means entries never expire by
	// default.
	Expiry time.Duration `env:"EXPIRY" envDefault:"1h" json:"expiry,omitempty" yaml:"expiry,omitempty"`
	// JanitorInterval is how often the memory provider sweeps expired
	// entries. It is ignored by every other provider, which expire entries
	// in the backing store rather than in this process. A non-positive
	// value disables the sweep, leaving the memory provider's lazy
	// eviction as the only reclaim path — see memory.WithJanitor for why
	// that is rarely what a long-lived cache wants.
	JanitorInterval time.Duration `env:"JANITOR_INTERVAL" envDefault:"5m" json:"janitorInterval,omitempty" yaml:"janitorInterval,omitempty"`
}

Config is the configuration for the cache.

func (*Config) ValidateWithContext

func (cfg *Config) ValidateWithContext(ctx context.Context) error

ValidateWithContext validates a Config struct.

type Option

type Option func(*options)

Option configures how NewCache assembles its cache.

The observability dependencies are options rather than parameters because every one of them is genuinely optional: an absent logger logs nowhere, an absent tracer provider traces nowhere, and an absent metrics provider records nothing. Requiring them positionally made a caller that wanted none of the three name all three anyway, usually as noops.

It carries no type parameter even though NewCache does. Go cannot infer a type argument from a call's result type, so an Option[T] would force every call site to spell the cached type out by hand — WithLogger[MyValue](l) — forever.

func WithLogger

func WithLogger(logger logging.Logger) Option

WithLogger attaches a logger. An absent logger logs nowhere.

func WithMetricsProvider

func WithMetricsProvider(metricsProvider metrics.Provider) Option

WithMetricsProvider attaches a metrics provider for the cache's counters and latency histogram. An absent provider records nothing.

func WithPillars

func WithPillars(p *observability.Pillars) Option

WithPillars attaches a logger, tracer provider, and metrics provider in one go, for the common case where a caller has already built them together. A nil Pillars attaches nothing.

It is applied in order with the individual options, so a caller can hand over its pillars and then override one of them:

cachecfg.NewCache[Session](ctx, cfg,
	cachecfg.WithPillars(pillars),
	cachecfg.WithMetricsProvider(nil), // this cache stays unmetered
)

func WithTracerProvider

func WithTracerProvider(tracerProvider tracing.TracerProvider) Option

WithTracerProvider attaches a tracer provider, enabling spans on every cache operation. An absent tracer provider traces nowhere.