Documentation
¶
Overview ¶
Package lock builds a config-selected core/interfaces.Locker — a DistributedLock (keyed, token-fenced, best-effort) plus Hold, the managed acquire-with-watchdog helper a single-active-operation guard depends on.
NewFromConfig chooses a backend from a Kind string — local (in-process, dev / replica=1; the default) or redis (cross-pod, staging/prod) — and wraps it in a Locker (NewLocker). The redis backend reuses a shared go-redis client (Deps.Redis), so no second connection pool is opened.
Hold acquires a key and keeps its lease alive with a background watchdog; the context it returns is cancelled the instant the lease is lost, so a losing pod's in-flight work is stopped rather than left running under a lock it no longer owns. Key naming is the caller's.
Every backend operation runs through the client tier (Decorate), wired by NewFromConfig from the Config collaborators.
Scope boundary: this package ships both backends, the factory, the client-tier decoration, and Hold. Wiring them (config + shared redis client + observability/resilience deps → Locker) and choosing the call sites and key names belong to the consumer's composition root.
Index ¶
- Constants
- func Decorate(base interfaces.DistributedLock, decs decorate.Decorations, name string, ...) (interfaces.DistributedLock, error)
- func NewFromConfig(ctx context.Context, cfg Config, deps Deps) (interfaces.Locker, error)
- func NewLocker(lock interfaces.DistributedLock, renewInterval time.Duration) interfaces.Locker
- type Config
- type Deps
Constants ¶
const ( // KindLocal is the in-process backend: correct for a single replica (dev / // replica=1), no external dependency. The default. KindLocal client.Kind = "local" // KindRedis is the cross-pod backend over a shared Redis client // (staging/prod, multi-replica). KindRedis client.Kind = "redis" )
Variables ¶
This section is empty.
Functions ¶
func Decorate ¶ added in v0.0.7
func Decorate( base interfaces.DistributedLock, decs decorate.Decorations, name string, opts ...client.Option, ) (interfaces.DistributedLock, error)
Decorate runs every operation of base through the client tier as the client named name, one operation per method of its contract.
func NewFromConfig ¶
NewFromConfig builds the configured Locker: the backend cfg.Kind selects, run through the client tier, with Hold renewing on RenewInterval. A non-positive TTL or RenewInterval, a RenewInterval above TTL/3, an unknown kind, or KindRedis without Deps.Redis is CodeInvalidInput.
func NewLocker ¶
func NewLocker( lock interfaces.DistributedLock, renewInterval time.Duration, ) interfaces.Locker
NewLocker wraps a DistributedLock with the renewal cadence Hold uses, yielding a Locker. Exposed so callers (and tests) can compose Hold over any DistributedLock — e.g. a mock or a backend built directly; NewFromConfig builds one over the config-selected backend.
Types ¶
type Config ¶
type Config struct {
// Kind selects the backend; empty means KindLocal.
Kind client.Kind `yaml:"kind" mapstructure:"kind"`
// Name labels the client in decoration overrides, metrics, spans and logs; empty
// uses the family name ("lock").
Name string `yaml:"name" mapstructure:"name"`
// TTL is the lease duration applied on Acquire and extended by Renew.
TTL time.Duration `yaml:"ttl" mapstructure:"ttl"`
// RenewInterval is the watchdog's renew cadence in Hold.
RenewInterval time.Duration `yaml:"renew_interval" mapstructure:"renew_interval"`
}
Config selects and tunes the lock. TTL is the lease a holder gets on Acquire (and Renew extends); RenewInterval is how often Hold's watchdog renews, at most TTL/3 so a couple of missed renew ticks cannot expire a live lease.
type Deps ¶ added in v0.0.7
type Deps struct {
// Decorations decorates the client from the decoration config (decoration.clients)
// and supplies its observability.
decorate.Decorations
// Redis is the shared go-redis client KindRedis requires.
Redis *goredis.Client
}
Deps carries the lock's runtime collaborators.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package local provides an in-process DistributedLock backend for single-pod deployments (dev / replica=1), where cross-process coordination is unnecessary.
|
Package local provides an in-process DistributedLock backend for single-pod deployments (dev / replica=1), where cross-process coordination is unnecessary. |
|
Package redis provides a cross-pod DistributedLock backend over Redis, for multi-replica deployments (staging/prod).
|
Package redis provides a cross-pod DistributedLock backend over Redis, for multi-replica deployments (staging/prod). |