distlock

type Driver ¶

type Driver interface {
	// SetNX attempts to acquire the lock for key with the given token and TTL.
	// Returns (true, nil) on success, (false, nil) when another holder owns the
	// key (not an error — caller interprets false as "busy"), and (false, err)
	// on I/O failure.
	SetNX(ctx context.Context, key, token string, ttl time.Duration) (acquired bool, err error)

	// Renew extends the TTL of an existing lock only if token still matches.
	// Returns (true, nil) on success, (false, nil) when the token no longer
	// matches (ownership lost — not an I/O error), and (false, err) on I/O failure.
	Renew(ctx context.Context, key, token string, ttl time.Duration) (held bool, err error)

	// Release deletes the lock key only if token still matches.
	// Returns nil on success or when the key is already gone (idempotent).
	// Returns a non-nil error only on I/O failure.
	Release(ctx context.Context, key, token string) error
}

Driver is the storage-backend contract for distributed locks. Implementations live in adapters/ (e.g. adapters/redis).

Three semantic primitives encapsulate all backend-specific logic (e.g. Lua scripts for Redis), keeping the runtime layer backend-agnostic.

ref: kubernetes/client-go tools/leaderelection/resourcelock/interface.go

— storage primitives shape adopted; GoCell collapses to 3 methods vs k8s 5
  because Get/Update/Create/Delete lifecycle is not needed here.

ref: go-redsync/redsync redsync.go — SetNX/Renew/Release semantics

type Lock ¶

type Lock struct {
	// contains filtered or unexported fields
}

Lock is a held distributed lock returned by Locker.Acquire.

Lock-as-Resource design ¶

Lock is intentionally NOT a context.Context. The caller-supplied context passed to Acquire is consumed only for the acquire RPC (SetNX); once the lock is held, its lifecycle is independent of the caller ctx. This matches the prevailing industry convention (bsm/redislock, go-redsync, etcd client/v3/concurrency, HashiCorp consul, Apache Curator): caller-ctx cancellation does NOT release a held lock; only explicit Release(), Orphan(), or renewal failure (ErrLockLost) will end it. (Explicit Locker.Shutdown is deferred to a future iteration — see ADR docs/architecture/202605200000-adr-distlock-lock-as-resource.md §"Out of scope".) Per-lock Orphan() now exists for graceful shutdown/handoff (bounded-TTL takeover, no release RPC). DISTLOCK-LOCKER-SHUTDOWN-01 tracks the deferred locker-level Shutdown/Close path.

Rationale: caller-ctx cancellation expresses "I no longer care about the outcome of THIS request" — it does NOT express "release the resource I acquired". Conflating the two (the previous Lock-as-Context design) caused GH #20: a forgotten caller could leave a held lock being renewed indefinitely, while a busy caller whose ctx happened to time out could suddenly lose its lock mid-critical-section.

Caller responsibility ¶

Acquire returns *Lock. Caller must:

lock, err := locker.Acquire(ctx, key, ttl)
if err != nil { return err }
defer lock.Release()

Process crash falls back to Redis-side TTL expiry. A living caller that forgets Release leaks the lock until process exit.

Why not context.Context ¶

Acquire could have returned a context.Context whose Done()/Cause() reflect lock-end events, but doing so invites the misuse pattern that GH #20 exposed: caller passes the lock ctx to db.QueryContext / http.NewRequest downstream, assuming caller-ctx semantics. By returning *Lock (which does not implement context.Context), the compiler rejects such misuse outright.

Values from the caller's ctx are still exposed via Lock.Value(key) — the underlying context.WithoutCancel(callerCtx).Value lookup preserves trace IDs and auth claims while shielding the lock from caller-ctx cancellation/deadline.

Callers should avoid stashing large objects, raw secrets, or request-scoped resources whose lifetime should not extend past the request as values on callerCtx before calling Acquire: every value reachable from callerCtx remains pinned through the captured valueLookup closure for the full held-lock duration (including any auto-renewal cycles) and is not eligible for GC until lock.Release() returns or the lock is lost. Trace IDs / auth claims / span contexts (small immutable objects) are the intended use; tokens and PII should be parameterized explicitly instead.

ref: GH #20 ; ADR docs/architecture/202605200000-adr-distlock-lock-as-resource.md

func (l *Lock) Cause() error

func (l *Lock) Done() <-chan struct{}

select {
case <-lock.Done():
    return fmt.Errorf("lock ended: %w", lock.Cause())
case result := <-doWork(...):
    return result
}

func (l *Lock) Orphan()

func (l *Lock) Release() error

func (l *Lock) Value(key any) any

type Locker ¶

type Locker interface {
	// Acquire blocks until the lock is granted or ctx is canceled.
	//
	// On success it returns a *Lock; caller MUST eventually end the lock via
	// lock.Release() (delete the backend key now) or lock.Orphan() (stop
	// renewal; the key expires on its lease TTL — ~1×TTL from the last
	// successful renewal, best-effort). Both are terminal and mutually
	// exclusive.
	//
	// Lock-end signals (lock.Done() closed; lock.Cause() reports):
	//   - ErrLockReleased — Release() was called (normal end-of-critical-section)
	//   - ErrLockLost     — renewal failed or backend reports ownership taken
	//   - ErrLockOrphaned — Orphan() was called (renewal stopped; key expires on its lease TTL — see Lock.Orphan)
	//
	// Notably absent: caller-ctx cancellation does NOT end the lock. If the
	// caller wants the lock to end when its ctx is canceled, the caller must
	// explicitly arrange a goroutine that does so.
	//
	// Per-lock Orphan() now exists for graceful shutdown/handoff (bounded-TTL
	// takeover, no release RPC). Locker.Shutdown/Close remains deferred
	// (DISTLOCK-LOCKER-SHUTDOWN-01).
	//
	// Idiomatic patterns for combining lock-end with caller-ctx:
	//
	//  // Pattern A — caller wants ctx cancel to also release the lock:
	//  lock, err := locker.Acquire(ctx, key, ttl)
	//  if err != nil { return err }
	//  defer lock.Release()
	//  go func() {
	//      // Wait for whichever ends first; the second case prevents the
	//      // goroutine from blocking on ctx forever after a normal Release
	//      // or a renewal-failure ends the lock.
	//      select {
	//      case <-ctx.Done():
	//          _ = lock.Release() // best-effort; idempotent.
	//      case <-lock.Done():
	//          // lock ended (Release / lost) — nothing more to do.
	//      }
	//  }()
	//
	//  // Pattern B — caller wants the *first* of (ctx-cancel | lock-lost) to abort:
	//  select {
	//  case <-ctx.Done():
	//      _ = lock.Release()
	//      return ctx.Err()
	//  case <-lock.Done():
	//      return fmt.Errorf("lock ended: %w", lock.Cause())
	//  }
	//
	// TTL is the only ceiling on a held-but-forgotten lock. Choose ttl
	// commensurate with the critical-section worst case (typically seconds
	// to minutes); avoid hour-scale TTLs unless the workload genuinely
	// runs that long, since a caller that aborts without Release leaves
	// peers blocked for the full ttl window. The fallback after process
	// crash is Redis-side TTL expiry.
	//
	// On failure it returns (nil, err) where err carries ErrLockTimeout when
	// another holder owns the key, or ctx.Err() (wrapped) if the parent was canceled.
	//
	// The lock is auto-renewed by a single shared manager goroutine (not per-lock)
	// until lock.Release() is called or renewal fails.
	// N active locks = 1 manager goroutine + O(N) heap. Zero per-lock goroutines.
	//
	// Driver.Release uses context.Background() with WithReleaseTimeout (default
	// 5s). lock.Release() blocks until the I/O completes and returns nil on
	// success or a wrapped error on I/O failure. lock.Release() is idempotent —
	// a second call returns the first call's result without contacting the backend.
	Acquire(ctx context.Context, key string, ttl time.Duration) (*Lock, error)

	// Stats reports observable state of the Locker for health checks and metrics.
	Stats() Stats
}

Locker acquires named distributed locks.

Lock-as-Resource design ¶

Acquire returns a *Lock — intentionally NOT a context.Context. Caller-ctx cancellation does NOT release a held lock; only explicit Release or renewal failure will end it. This matches the prevailing industry convention (bsm/redislock, go-redsync, etcd client/v3/concurrency, HashiCorp consul, Apache Curator) and prevents the misuse pattern that GH #20 exposed under the previous Lock-as-Context design. (Explicit Locker.Shutdown is deferred — see ADR docs/architecture/202605200000-adr-distlock-lock-as-resource.md §"Out of scope".)

Caller responsibility:

lock, err := locker.Acquire(ctx, key, ttl)
if err != nil { return err }
defer lock.Release()

ctx is consumed only for the acquire RPC (SetNX). Once the lock is held, caller-ctx cancellation is decoupled. Values from ctx (trace IDs, auth claims) are still exposed via Lock.Value via context.WithoutCancel.

ref: GH #20 ; ADR docs/architecture/202605200000-adr-distlock-lock-as-resource.md ref: go-redsync/redsync — caller-ctx scoped to acquire only ref: etcd client/v3/concurrency — session-scoped keepalive, decoupled from per-op ctx

func New(driver Driver, clk clock.Clock, opts ...Option) (Locker, error)

type Manager ¶

type Manager struct {
	// contains filtered or unexported fields
}

Manager runs a single shared goroutine that owns the renewal heap and calls Driver.Renew for all active locks.

The manager goroutine is the SOLE writer of the heap and locks map, which eliminates data races. External callers communicate exclusively through the events channel.

Lifecycle:

• lazy-started on first Acquire (via lockerImpl.add)
• manager exits when the last lock is removed
• started is closed once the manager enters its main select loop
• drained is closed once the manager exits after the last lock removal

ref: golang.org/x/tools/internal/event — single goroutine dispatch pattern

func (m *Manager) Drained() <-chan struct{}

func (m *Manager) RenewNotify() <-chan struct{}

func (m *Manager) Snapshot() ManagerSnapshot

func (m *Manager) Started() <-chan struct{}

type ManagerSnapshot ¶

type ManagerSnapshot struct {
	// Locks is the number of active locks currently tracked.
	Locks int
}

ManagerSnapshot is a read-only view of the manager's current state. Exported for testing only.

type Option ¶

type Option func(*config)

Option is a functional option for configuring a Locker.

func WithDriftFactor(f float64) Option

func WithMaxRenewAttempts(n int) Option

func WithReleaseTimeout(d time.Duration) Option

func WithRenewFraction(f float64) Option

type Stats ¶

type Stats struct {
	// ActiveLocks is the number of locks currently held and tracked by the manager.
	ActiveLocks int
}

Stats reports observable state of a Locker instance.