lease

lease is a fenced, time-bounded distributed lease primitive for Go 1.26.6 and newer. It provides explicit owners, backend-anchored expiry, renewal, validation, compare-and-release, and monotonically increasing fencing tokens for native Valkey and PostgreSQL backends.

A lease does not stop expired work. Pass Handle.Token() into every protected write and reject tokens lower than the resource's last accepted fence. For reconstructible Valkey cache refreshes, valkey.Store.Guard exposes opaque coordinates from Handle.Snapshot() that pkg/cache can compare atomically with publication.

Five-minute start

Choose a backend guide:

• Valkey quickstart
• PostgreSQL quickstart

The core shape is:

policy, err := lease.NewPolicy(lease.PolicyOptions{
    TTL: 30 * time.Second, RenewEvery: 10 * time.Second,
    SafetyMargin: 5 * time.Second, Retry: 100 * time.Millisecond,
    Wait: 2 * time.Second, MaxAttempts: 20,
    OperationTimeout: 2 * time.Second,
})
handle, err := client.Acquire(ctx, key, policy)
if err != nil { return err }
managed, err := handle.StartManaged(ctx)
if err != nil { return err }
defer managed.Stop(context.WithoutCancel(ctx))
defer handle.Release(context.WithoutCancel(ctx))

if err := protectedWrite(ctx, handle.Token()); err != nil { return err }

Never infer successful release from cancellation or shutdown. Always inspect the returned error. No acquisition order or starvation guarantee is provided.

Packages

• root: model, policies, client, handles, managed renewal, observations
• memory: deterministic process-local reference backend, never distributed
• valkey: native valkey-go backend using backend-time Lua scripts
• postgres: native pgx backend and migrations schema
• leasequeue, leasescheduler, leaseservice: lifecycle integrations
• leasetest: deterministic clock and cross-backend conformance suite

See the documentation index, security policy, and changelog.

Ecosystem

Use the Golib documentation portal to choose companion packages, supported stacks, recipes, and operations guidance.