cache

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 4 Imported by: 0

README

gas/cache

Test Go Reference Go Version License

Part of the Gas monorepo · Documentation · All modules

Key-value caching for the Gas framework, with two interchangeable stores that keep one contract: in-memory with LRU eviction, and Valkey (Redis-compatible) with key prefixes, per-command timeouts, TLS and ACL users.

Implements gas.CacheProvider.

go get github.com/gasmod/gas/cache
gas.WithSingletonService[gas.CacheProvider](cachemem.New()),

Both stores take gas.ConfigProvider and gas.Logger from the container and read the cache section, or take their configuration from WithConfig; the Valkey store requires cache.addr. Each store's Config() returns the configuration its last successful Init resolved.

Package Provides
cache The shared contract and sentinel errors
cache/memory In-process store, for development, tests and single-instance apps
cache/valkey Valkey store, for apps that share a cache across instances
cache/cachetest Recording mock of gas.CacheProvider

Documentation

The full documentation is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.

License

MIT

Documentation

Overview

Package cache defines what every cache store of the module promises: the keys it accepts, how it copies values, how a TTL works, how it honors a context, its lifecycle, and the errors it returns.

The stores implement gas.CacheProvider and gas.Service, and each lives in its own package:

  • gas/cache/memory: a map in the process's memory, with an entry limit and least-recently-used eviction.
  • gas/cache/valkey: a Valkey server, or any server that speaks its protocol, such as Redis.
  • gas/cache/cachetest: a mock for tests.

Usage

Each store's New returns a constructor in the shape the gas container expects, so a store is registered as gas.CacheProvider:

gas.WithSingletonService[gas.CacheProvider](memory.New())

A handler then reads through the cache:

b, err := c.Get(ctx, "user:42")
if errors.Is(err, cache.ErrKeyNotFound) {
	b = loadUser(ctx, 42)
	err = c.Set(ctx, "user:42", b, 5*time.Minute)
}
if err != nil {
	return err
}

After this the cache holds `user:42` for five minutes, unless a store evicts it first.

Contract

Every store, and any gas.CacheProvider that wants to be one, keeps the rules of the sections Keys and values, TTL, Context and Lifecycle. The module's conformance tests run every store through these rules, with identical expectations.

A method checks its arguments first, the key and then the TTL, then the store's state, then the context, and returns the first failure.

Keys and values

The methods read, write and remove values by key:

  • Get returns the value of a key, or an error wrapping ErrKeyNotFound when the store holds no live value under it.
  • Exists reports whether Get would find one.
  • Delete removes a key. Deleting a key the store does not hold is not an error.

A key is any non-empty string, of any bytes; keys are compared byte for byte. The empty key is ErrInvalidKey, from every method, as CheckKey reports it.

Values are bytes and are copied: Set keeps a copy of what it is given, and Get returns a copy of what the store keeps, so the caller may change either slice afterwards. A nil value is stored as empty, and Get returns an empty value as an empty, non-nil slice.

TTL

Set replaces the value of a key and its TTL. The TTL works like this:

  • A TTL above zero makes the value expire once that time has passed, rounded up to a whole millisecond, so `500µs` lives a millisecond, as Valkey counts TTLs. EffectiveTTL computes the rounded TTL.
  • A TTL of zero takes the store's DefaultTTL setting, where zero means no expiry.
  • A negative TTL is ErrInvalidTTL, as CheckTTL reports it, and stores nothing.

A TTL within a millisecond of the largest time.Duration is rounded down to a whole millisecond instead, since rounding up would overflow.

An expired value is a miss for Get and for Exists, whether or not the store has removed it yet.

Context

Every method returns the context's error, wrapped, when its context has ended before it starts. A store that does I/O honors the context during the call too. Close is the exception: it always closes.

Lifecycle

A store is initialized with Init and closed with Close:

  • Before its first successful Init, every method but Init and Close returns ErrNotInitialized.
  • Init on an initialized store returns ErrAlreadyInitialized and changes nothing.
  • After Close, until Init succeeds again, every method but Init and Close returns ErrClosed.
  • Close on a store that is not initialized returns nil.

Close then Init restarts the store. Close waits for the goroutines the store started.

Security

Cache keys often carry user identifiers or session and token hashes, and values are application data. So the stores keep them out of what they report:

  • No error the stores make holds a key or a value.
  • No error or log holds a server's address, a user name or a password.

A store's errors name the operation instead.

Concurrency

Every store is safe for concurrent use, as each store's package describes. The mock is too, except for setting its fields while it is called.

Errors

Every error a store returns starts with its service name, such as `gas/cache/memory`, then the operation, such as `get`, then what failed. It wraps one of these sentinels, to be tested with errors.Is:

The errors of this package's checks, as returned, before a store adds its service name and the operation:

invalid key: empty
invalid TTL: negative

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrKeyNotFound indicates that a store holds no live value under the
	// key: it was never set, was deleted, or expired.
	ErrKeyNotFound = errors.New("key not found")
	// ErrInvalidKey indicates that a key is not one a store accepts: it
	// is empty.
	ErrInvalidKey = errors.New("invalid key")
	// ErrInvalidTTL indicates that a TTL is negative.
	ErrInvalidTTL = errors.New("invalid TTL")
	// ErrNotInitialized indicates that a method was called before the
	// store's first successful Init.
	ErrNotInitialized = errors.New("service not initialized")
	// ErrAlreadyInitialized indicates that Init was called on a store that
	// is initialized.
	ErrAlreadyInitialized = errors.New("service already initialized")
	// ErrClosed indicates that a method was called after Close, before
	// Init succeeded again, or that Close ran while the call was in
	// progress.
	ErrClosed = errors.New("service closed")
	// ErrNilLogger indicates that a store's constructor was given a nil
	// logger.
	ErrNilLogger = errors.New("logger is nil")
	// ErrNilConfig indicates that WithConfig was given a nil
	// configuration.
	ErrNilConfig = errors.New("config is nil")
	// ErrNoConfigProvider indicates that there is neither a configuration
	// given to WithConfig nor a ConfigProvider to bind one from.
	ErrNoConfigProvider = errors.New("no config provider")
	// ErrInvalidConfig indicates that the configuration failed to bind,
	// failed its validate tags, or broke one of the store's rules.
	ErrInvalidConfig = errors.New("invalid config")
)

The sentinel errors every store of the module shares, as described in the package documentation. A store's errors start with its own service name and the operation, and wrap one of these.

Functions

func CheckKey added in v0.6.0

func CheckKey(key string) error

CheckKey returns nil for a key every store accepts, any non-empty string, and otherwise an error wrapping ErrInvalidKey. The error never holds the key.

func CheckTTL added in v0.6.0

func CheckTTL(ttl time.Duration) error

CheckTTL returns nil for a TTL every store accepts, zero or positive, and otherwise an error wrapping ErrInvalidTTL. The error never holds the TTL.

func EffectiveTTL added in v0.6.0

func EffectiveTTL(ttl, defaultTTL time.Duration) time.Duration

EffectiveTTL returns how long a value set with ttl lives, as described in the package documentation: defaultTTL in place of a zero ttl, rounded up to a whole millisecond, with 0 for no expiry. It is for a ttl that CheckTTL accepts and a defaultTTL that is not negative.

Types

This section is empty.

Directories

Path Synopsis
Package cachetest holds a mock of gas.CacheProvider, MockCache, for tests of code that uses a cache.
Package cachetest holds a mock of gas.CacheProvider, MockCache, for tests of code that uses a cache.
internal
configsrc
Package configsrc resolves a store's configuration: from a copy of the one given to the store's WithConfig option, or else by binding the store's defaults from a gas.ConfigProvider.
Package configsrc resolves a store's configuration: from a copy of the one given to the store's WithConfig option, or else by binding the store's defaults from a gas.ConfigProvider.
conformance
Package conformance holds the tests every store of the module runs: the contract of the cache package, checked with identical expectations against a store built by the caller.
Package conformance holds the tests every store of the module runs: the contract of the cache package, checked with identical expectations against a store built by the caller.
Package memory is a cache held in the process's memory, as a gas.CacheProvider.
Package memory is a cache held in the process's memory, as a gas.CacheProvider.
Package valkey is a cache on a Valkey server, as a gas.CacheProvider.
Package valkey is a cache on a Valkey server, as a gas.CacheProvider.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址