worklease

worklease

worklease is a Go library for lease-based work coordination in distributed systems.

It is not a distributed lock library.

Distributed locks answer: who owns this resource right now? worklease answers a different question: when ownership changes, what does the new owner need to continue the work the previous owner started?

Installation

go get github.com/aetomala/worklease

Requires Go 1.26 or later; CI tests Go 1.26 and 1.27. The PostgreSQL backend is tested on PostgreSQL 16 with github.com/lib/pq (see Backends).

Quick start

This program runs the same work ID twice on the in-memory backend. The second run reads what the first one left behind. It needs no database.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/aetomala/worklease"
	"github.com/aetomala/worklease/backend/memory"
	"github.com/aetomala/worklease/worker"
)

func main() {
	lease, err := worklease.New(memory.New(), worklease.Config{
		TTL:      30 * time.Second,
		HolderID: "worker-1", // required: identifies this process and must not be empty
	})
	if err != nil {
		log.Fatal(err)
	}

	runner, err := worker.NewRunner(worker.RunnerConfig{
		Lease: lease,
		WorkFn: func(ctx context.Context, token worklease.Token, prior worklease.Checkpoint) ([]byte, error) {
			fmt.Printf("previous exit: %s, saved state: %q\n", prior.PrevExit, prior.State)
			return []byte("step 1 done"), nil // the checkpoint the next holder reads
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	for i := 0; i < 2; i++ {
		if err := runner.Run(context.Background(), "billing-run-2026-10"); err != nil {
			log.Fatal(err)
		}
	}
}

It prints:

previous exit: none, saved state: ""
previous exit: finished, saved state: "step 1 done"

For production, replace memory.New() with postgres.New(db) (see Backends). Usage shows the same lifecycle step by step, and Higher-level packages covers leader and pool.

The Problem

Worker A acquires a lease, begins processing a multi-step job, makes partial progress, then crashes. Worker B acquires the lease — and starts from scratch.

Depending on the operation, this means duplicated writes, lost progress, or inconsistent state. Idempotency helps only if restarting from the beginning is cheap. For long-running work — provider onboarding, async lifecycle management, batch processing with intermediate state — it isn't.

The correct fix is checkpointed lease handoff: the outgoing owner writes progress state atomically with its last lease renewal. The incoming owner reads that state before starting work. Fencing tokens prevent zombie writes from expired owners corrupting the checkpoint after they've been superseded.

Every Go distributed locking library (distlock, pglock, dynamodb-lock-go, etcd leases, client-go/leaderelection) solves presence — mutual exclusion, TTL expiry, heartbeat renewal. None solve continuity. worklease fills that gap.

Is worklease the right fit?

worklease is designed for a specific shape of work: stateful, multi-step operations where restarting from scratch is expensive or incorrect, and where adopting a full workflow engine is not the right trade-off.

It is a good fit if you are running Go workers with PostgreSQL already in the stack, doing long-running jobs with meaningful intermediate state, and need correct handoff semantics without restructuring your application.

It is not the right fit if your jobs are small enough to restart cheaply — a job queue (River, Asynq, FOR UPDATE SKIP LOCKED) is simpler and sufficient. If your work is complex enough to need replay semantics and activity scheduling, Temporal is the right tool.

Prior Art

This pattern is not new. AWS's Kinesis Client Library has implemented it since 2013 via its LeaseRefresher. KCL maintains a DynamoDB table where each lease entry holds an explicit checkpoint column and a leaseCounter for fencing. A worker atomically renews its lease while writing its progress checkpoint. When a worker's lease expires, the successor reads the checkpoint column and resumes from exactly that point. Fencing is enforced via conditional writes on leaseCounter — structurally identical to worklease's fencing_token.

The pattern is proven and has been running production Kinesis workloads at AWS scale for over a decade.

What KCL doesn't provide:

• A Go-native implementation (KCL Go is a thin wrapper over a Java MultiLangDaemon process — not idiomatic)
• General-purpose work coordination (its checkpoint is a stream sequence number; the entire model assumes Kinesis shard processing)
• Portability outside AWS (DynamoDB backend, CloudWatch metrics, IAM — AWS-only)

worklease extracts the same semantics into a general-purpose Go primitive — no AWS dependency, no Kinesis assumption, pluggable backends.

What worklease does not solve

These are intentional scope boundaries, not gaps.

External side effects are not fenced. ErrFenced stops stale checkpoint writes to the lease store. It does not stop a zombie worker from calling Stripe, sending an email, or writing to S3 before it discovers it has been superseded. Callers must make every external mutation idempotent, use an outbox pattern, or enforce idempotency keys at downstream systems. This is an inherent property of any coordination primitive — the library fences what it owns.

The window between checkpoints is at-least-once. If Worker A executes a step and crashes before checkpointing, Worker B will re-execute that step from the previous checkpoint. worklease provides a resumable progress marker, not exactly-once step execution.

Recovery logic is yours. The library delivers the checkpoint bytes and how the previous holder exited (PrevExit). What those bytes mean, how to validate partial state, and how to reconcile external effects that happened before a crash are application concerns.

Release expires the lease immediately. Release records the exit mode you declare and sets the lease expiration to the past, making the work item immediately available. A successor using WithWaitForLease acquires on its next poll; a fail-fast successor can call Acquire immediately after. The TTL governs crash detection only — it does not add latency to handoffs.

Concepts

Lease — A time-limited claim on a named unit of work. Expires if not renewed. When it expires, another worker can acquire it. In code, a lease is the worklease.Lease interface: worklease.New(backend, cfg) returns one, and you call Acquire, ReadCheckpoint, Checkpoint, Renew, Release, Forget, and StartRenewal on it.

Holder ID — Config.HolderID names this process. It must not be empty: worklease.New returns an error that matches ErrConfigInvalid. Use a value that is unique per process, such as a pod name. A lease is not re-entrant: acquiring a lease that your own HolderID still holds returns ErrLeaseHeld, so a restarted process with a stable ID waits for the old lease to expire (up to the TTL) unless the previous run released it.

Fencing token — A monotonically incrementing integer issued on every acquisition. A worker's writes to the lease store are rejected if a higher token has been issued — preventing zombie workers from corrupting the checkpoint after their lease expires. Tokens are monotonic but not contiguous, so never assume consecutive values: gaps are expected and have no operational significance. On PostgreSQL every Acquire attempt draws from the sequence, including attempts that return ErrLeaseHeld. The in-memory backend advances one counter per instance, only on a successful Acquire, so the tokens of one work ID still skip whenever another work ID acquires in between.

Checkpoint — Progress state written atomically with lease renewal. If the worker is making progress, it proves liveness and saves state in one operation. The last checkpoint survives to the next owner. Checkpoint and Renew are distinct: Checkpoint writes state and extends the TTL atomically; Renew extends the TTL without updating state.

Handoff vs crash recovery — Two distinct acquisition paths. If the previous owner called Release explicitly, the checkpoint contains final state and the successor knows the work was cleanly surrendered. If the lease expired without a release, the checkpoint contains the last known progress and the successor resumes from partial state. These are different situations and callers handle them differently. The library makes the distinction explicit.

Usage

Acquiring a lease and checkpointing progress

b := memory.New() // in production: postgres.New(db), see Backends

lease, err := worklease.New(b, worklease.Config{
    TTL:      30 * time.Second,
    HolderID: os.Getenv("WORKER_ID"), // required and unique per process; New rejects an empty value
})
if err != nil {
    return err
}

token, err := lease.Acquire(ctx, "billing-run-2026-10")
if err != nil {
    return err // worklease.ErrLeaseHeld: another holder has it
}

prior, err := lease.ReadCheckpoint(ctx, token)
if err != nil {
    return err
}

switch prior.PrevExit {
case worklease.ExitNone:
    // First run: start from scratch.
case worklease.ExitFinished:
    // The previous run completed; prior.State is its final state.
case worklease.ExitRetired:
    // This work is done for good. Hand the lease back unchanged.
    return lease.Release(ctx, token, worklease.ExitRetired)
default:
    // ExitAbandoned, ExitExpired, or a mode this code does not know:
    // prior.State is partial. Validate it before resuming.
}

renewCtx, stopRenewal := lease.StartRenewal(ctx, token)
defer stopRenewal()

state, workErr := run(renewCtx, token, prior.State)
stopRenewal()

if errors.Is(workErr, worklease.ErrFenced) || errors.Is(context.Cause(renewCtx), worklease.ErrFenced) {
    return worklease.ErrFenced // a successor holds the lease or its record was removed; record nothing
}

if errors.Is(context.Cause(renewCtx), worklease.ErrLeaseWindowExhausted) {
    // The lease lapsed before a renewal succeeded. Do not Checkpoint or Release it:
    // the successor sees ExitExpired and the last good checkpoint.
    return errors.Join(workErr, worklease.ErrLeaseWindowExhausted)
}

// Final writes must survive cancellation of ctx without hanging shutdown.
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
defer cancel()

mode := worklease.ExitFinished // use worklease.ExitRetired for one-shot work
if workErr != nil {
    mode = worklease.ExitAbandoned
}
if state != nil {
    if err := lease.Checkpoint(cleanupCtx, token, state); err != nil {
        return errors.Join(workErr, err)
    }
}
if err := lease.Release(cleanupCtx, token, mode); err != nil {
    return errors.Join(workErr, err) // ErrLeaseExpired: the successor sees ExitExpired
}
return workErr

Rows released with ExitFinished are kept as resume points for work that runs again, and Vacuum.Sweep never deletes them. Release one-shot work with ExitRetired; otherwise its row is never eligible for cleanup. worker.Runner, leader.Elect, and pool do all of the above for you.

Renewing without checkpointing

If the worker is healthy but not at a checkpointable boundary yet:

if err := lease.Renew(ctx, token); err != nil {
    // ErrFenced: a higher token has been issued or the record is gone — stop working.
    return err
}

Checkpoint and Renew are separate because they mean different things. Renew says "I'm alive." Checkpoint says "I'm alive and here's where I am."

Fresh acquisition

ReadCheckpoint returns a nil state (not an error) when this is the first worker to acquire this lease, and also after a Checkpoint with a nil or empty state, on every backend:

prior, err := lease.ReadCheckpoint(ctx, token)
if err != nil {
    return err
}
if prior.State == nil {
    // First acquisition — start from the beginning.
    progress = OnboardingProgress{}
}

Managing renewal directly

StartRenewal starts a managed renewal goroutine and returns a derived context and a stop function. worker.Runner and leader.Elect handle this lifecycle automatically; use StartRenewal directly only when you need fine-grained control.

Two requirements apply when calling StartRenewal directly:

1. Call stopRenewal() before Release — the goroutine must exit before ownership is surrendered. Register defer stopRenewal() immediately as a panic-safety net, then call it explicitly before Release (the defer becomes a no-op on the clean path).
2. Pass the original ctx to Release, not renewCtx — renewCtx may already be cancelled (by fencing or window exhaustion) when Release is called; using it causes Release to fail with a context error.

renewCtx, stopRenewal := lease.StartRenewal(ctx, token)
defer stopRenewal() // panic-safety net

if err := doWork(renewCtx, ...); err != nil {
    return err // stopRenewal fires via defer; do not Release if fenced
}

stopRenewal()             // explicit stop before Release
lease.Release(ctx, token, worklease.ExitFinished) // use the original ctx, not renewCtx

stopRenewal returns without waiting for an in-flight Renew call, and the renewal context is cancelled when the lease window closes, even if a Renew call is stalled. Work code can read the window with worklease.LeaseWindow:

if deadline, ok := worklease.LeaseWindow(renewCtx); ok && time.Until(deadline) < 5*time.Second {
    return errNotEnoughLease // too little guaranteed lease left for this step
}

LeaseWindow works on renewCtx and on any context derived from it, advances with each successful renewal, and, under a constant clock offset, never exceeds the true expiry. It returns ok == false outside a renewal context and once renewCtx is done. Token.ExpiresAt() is the expiry recorded at acquisition and never moves.

Error Reference

The four backend sentinels (ErrFenced, ErrLeaseHeld, ErrLeaseExpired, ErrInvalidExitMode) are defined in package backend and re-exported from worklease as the same values, so errors.Is matches either name. Acquire with an empty work ID returns a plain error that matches no sentinel.

Match sentinels with errors.Is. The text of an error message is not part of the compatibility promise and may change in a minor release; such changes are listed under ### Changed in CHANGELOG.md.

ErrFenced is the critical one. When Checkpoint, Renew, Release, ReadCheckpoint, or Forget returns ErrFenced, a successor has already acquired the lease or its record was removed, and this worker is a zombie. Stop immediately — any further writes to the lease store will be rejected. Note that ErrFenced does not cancel in-flight external calls the worker may have already initiated; those must be made idempotent at the application layer.

Upgrading

UPGRADING.md has the steps for each version, including the schema migrations that v0.5.0 and v0.6.0 required. From v0.8.0 to v1.0.0 there is no schema change, and the module requires Go 1.26.

Higher-level packages

worker — Lifecycle management

worker.Runner handles the acquire / ReadCheckpoint / StartRenewal / WorkFn / Release lifecycle so callers implement only the work function:

import "github.com/aetomala/worklease/worker"

r, err := worker.NewRunner(worker.RunnerConfig{
    Lease:  lease,
    WorkFn: func(ctx context.Context, token worklease.Token, prior worklease.Checkpoint) ([]byte, error) {
        // prior.State is the last checkpoint; prior.PrevExit says how the previous holder exited (ExitNone on first acquisition).
        // Return updated checkpoint bytes, or nil to leave the checkpoint unchanged.
        return processWork(ctx, prior)
    },
})
if err != nil { ... }
if err := r.Run(ctx, "onboarding:tenant-abc"); err != nil { ... }

Runner picks the exit mode from your work function's result: nil releases with ExitFinished, an error wrapping worklease.ErrRetire releases with ExitRetired and Run returns nil, and any other error releases with ExitAbandoned. It does not release when fenced or when the lease window ran out; the next holder sees ExitExpired. The final Checkpoint and Release run on a context that survives cancellation of yours, bounded by RunnerConfig.CleanupTimeout (default 5s). leader.Elect applies the same mapping to fn, and calls OnRelinquished only after ExitFinished or ExitRetired.

leader — Simplified leadership

leader.Elect acquires a work ID, starts managed lease renewal, calls fn under the renewal context, stops renewal, and releases. Suitable for single-leader patterns where one process should be active at a time:

import "github.com/aetomala/worklease/leader"

err := leader.Elect(ctx, lease, "scheduler:primary", leader.Config{}, func(ctx context.Context) error {
    // ctx is cancelled if the lease is fenced or renewal fails.
    // Return when the work is done; leader.Elect will release.
    return runScheduler(ctx)
})

Without worklease.WithWaitForLease(), Elect returns ErrLeaseHeld when another process leads, after waiting leader.Config.IdleInterval (default 1s, up to 20% jitter), so a follower can call Elect in a loop without spinning against the backend. Any other Acquire error, such as a database outage, is returned after BackoffInterval, and a context error at once. BackoffInterval also applies after every non-fencing return that follows a successful Acquire, including a clean finish. Its zero value means no sleep, so a loop that retries on every error must set it: with the database unreachable, a loop of Elect calls with leader.Config{} spins (tens of thousands of Acquire calls per second on a development machine), and with BackoffInterval: time.Second it makes one call per second. Pass worklease.WithWaitForLease() in leader.Config.AcquireOptions to block until leadership is available instead.

leader.Config also accepts optional lifecycle callbacks — OnElected, OnLost, and OnRelinquished — for observing leadership transitions; none of them fires when Acquire fails:

cfg := leader.Config{
    BackoffInterval: time.Second, // pace retries after errors other than ErrLeaseHeld
    OnElected: func(ctx context.Context, token worklease.Token) {
        log.Printf("elected: %v", token)
    },
    OnLost: func(ctx context.Context, token worklease.Token) {
        log.Printf("lost the lease: %v", token) // fenced, or the lease window ran out
    },
    OnRelinquished: func(ctx context.Context, token worklease.Token) {
        log.Printf("released: %v", token) // after ExitFinished or ExitRetired
    },
}

pool — Distributed work distribution

pool.Pool distributes a fixed set of work IDs across competing processes. Multiple Pool instances — one per process — collectively cover the full work ID set. Rebalancing is emergent from lease acquisition races:

import "github.com/aetomala/worklease/pool"

p, err := pool.New(lease, pool.Config{
    WorkIDs: []string{"shard-0", "shard-1", "shard-2", "shard-3"},
}, func(ctx context.Context, workID string, token worklease.Token, prior worklease.Checkpoint) ([]byte, error) {
    return processShard(ctx, workID, prior)
})
if err != nil { ... }

// Blocks until ctx is cancelled; all active slots complete before Run returns.
if err := p.Run(ctx); err != nil { ... }

Return worklease.ErrRetire (or wrap it) from the work function to retire the work ID: the slot releases with ExitRetired, calls OnSlotRetired, and stops. Return a PermanentError to drop a slot without reacquisition — implement the interface on a custom type, or wrap an error with pool.Permanent(err); the slot releases with ExitAbandoned. When every slot exits through a PermanentError, Run returns pool.ErrAllSlotsDead; if any slot retired, it returns nil. ErrAllSlotsDead requires every slot to be counted dead: a slot that observes cancellation of ctx before its PermanentError check exits uncounted, so if ctx is cancelled at the same moment the last slot fails, Run may return nil instead. A slot whose work ID another process holds waits Config.IdleInterval (default 1s, up to 20% jitter); a slot whose work function returned nil waits Config.RerunInterval (default 1s, up to 20% jitter) before running again; a slot whose work function failed waits Config.BackoffInterval (default 1s) and calls OnSlotBackoff. Set pool.Config.Observer to a pool.Observer to receive slot lifecycle events (OnSlotAcquired / OnSlotLost / OnSlotBackoff / OnSlotDead / OnSlotRetired), and call ActiveSlots() for a point-in-time view of slots currently executing their work function. Construction errors are distinct sentinels (ErrLeaseRequired / ErrEmptyWorkIDs / ErrEmptyWorkID / ErrDuplicateWorkID / ErrWithWaitForLeaseProhibited / ErrWorkFnRequired) that all satisfy errors.Is(err, pool.ErrConfigInvalid) and errors.Is(err, worklease.ErrConfigInvalid); every work ID must be non-empty and unique.

checkpoint — Typed serialization helpers

checkpoint.Codec and the generic Encode[T] / Decode[T] helpers add typed serialization on top of the raw []byte checkpoint layer. checkpoint.JSON() returns a JSONCodec backed by encoding/json. The codec must not be nil. Decode returns the zero value for nil data without calling the codec, and a backend returns a nil State when there is no checkpoint, so a first acquisition decodes to the zero value.

Observability — LeaseObserver

Set worklease.Config.Observer to a LeaseObserver to receive a synchronous callback after every lease operation — OnAcquire, OnCheckpoint, OnRenew, OnRelease, OnReadCheckpoint, and OnForget — each with an event struct carrying the Token, the error, and a Duration for the backend call. OnFenced fires in addition when Checkpoint, Renew, Release, or Forget is fenced. nil installs a no-op, so observability is fully opt-in. Vacuum is observed separately: set worklease.VacuumConfig.Observer to a VacuumObserver to receive OnSweep with each sweep's options, rows deleted, duration, and error. See examples/observability for a stdlib-only implementation of both.

Embedding a no-op observer

worklease.NoopObserver, worklease.NoopVacuumObserver, and pool.NoopObserver discard every event. Embed one in your own observer to implement only the methods you need; your type keeps compiling when a later release adds an observer method. The same pattern applies to all three: embed the no-op type that matches the interface you implement.

type acquireCounter struct {
	worklease.NoopObserver
	n atomic.Int64
}

func (c *acquireCounter) OnAcquire(_ context.Context, _ worklease.AcquireEvent) {
	c.n.Add(1)
}

Pass &acquireCounter{} as worklease.Config.Observer. A runnable version is ExampleNoopObserver in the package documentation. FencedEvent.Operation prints as Checkpoint, Renew, Release, or Forget when formatted with %v.

Exit modes and handoff

Every holder declares how it leaves; the next holder reads it as Checkpoint.PrevExit.

Release accepts only ExitFinished, ExitAbandoned, and ExitRetired; anything else returns worklease.ErrInvalidExitMode. Once a lease has expired, Release returns worklease.ErrLeaseExpired and records nothing, so a holder that lost its lease cannot vouch for its work. Treat any mode your code does not recognize as ExitExpired; later releases may add modes. "Crash recovery" in these docs means handling ExitExpired.

prior, err := lease.ReadCheckpoint(ctx, token)
if err != nil {
    return err
}
log.Printf("previous holder %q exited %s", prior.PrevHolderID, prior.PrevExit)

Retiring work

Return worklease.ErrRetire from a worker, leader, or pool work function when its work ID is complete for good. The lease is released with ExitRetired, Run and Elect report success, and a pool slot stops. A later holder of the same work ID sees ExitRetired.

WorkFn: func(ctx context.Context, token worklease.Token, prior worklease.Checkpoint) ([]byte, error) {
    if prior.PrevExit == worklease.ExitRetired {
        return prior.State, worklease.ErrRetire // already done: keep it retired
    }
    state, err := migrateTenant(ctx, prior.State)
    if err != nil {
        return state, err // ExitAbandoned: the next holder resumes from state
    }
    return state, worklease.ErrRetire // ExitRetired: Run returns nil
},

Row lifecycle: Forget and Vacuum

Lease rows outlive their holders so that successors can read them. Two calls remove them:

// Delete one row now. Forget matches the holder and the token, so it also works
// after your own Release.
if err := lease.Forget(ctx, token); err != nil {
    return err // ErrFenced: the lease moved on, or the row is already gone
}

// Periodically delete retired rows last updated more than a week ago.
vacuum, err := worklease.NewVacuum(b, worklease.VacuumConfig{})
if err != nil {
    return err // ErrNilBackend
}
n, err := vacuum.Sweep(ctx, worklease.SweepOptions{
    Retention: 7 * 24 * time.Hour,
})
if err != nil {
    return err
}
log.Printf("deleted %d retired rows", n)

Sweep deletes rows released with ExitRetired once they are older than Retention. With IncludeExpired: true it also deletes rows whose lease expired with no declared exit, which discards the partial state a successor would have recovered from. Rows released with ExitFinished or ExitAbandoned, and rows currently held, are never deleted. Retention is how long a retired or expired row is kept after its last update; it is not tied to the TTL. After Forget or Sweep, the next holder sees ExitNone, and a holder whose row was removed gets ErrFenced. Do not run Sweep while v0.5 processes still share the table (see UPGRADING.md).

Forget is reported to LeaseObserver.OnForget, and each Sweep that reaches the backend to VacuumConfig.Observer.

Configuration errors are matchable: every error worklease.New returns, ErrNilBackend from NewVacuum and Vacuum.Sweep, and ErrRetentionRequired from Vacuum.Sweep satisfy errors.Is(err, worklease.ErrConfigInvalid). So do the pool configuration sentinels (including pool.ErrConfigInvalid), worker.ErrLeaseRequired, worker.ErrWorkFnRequired, leader.ErrLeaseRequired, and leader.ErrFnRequired.

Backends

PostgreSQL

import (
    "database/sql"

    _ "github.com/lib/pq" // any database/sql PostgreSQL driver; the backend does not register one

    "github.com/aetomala/worklease/backend/postgres"
)

db, _ := sql.Open("postgres", dsn)
backend, _ := postgres.New(db)

lease, _ := worklease.New(backend, worklease.Config{
    TTL:      30 * time.Second,
    HolderID: os.Getenv("WORKER_ID"),
})

Run the migration before first use (canonical source: backend/postgres/schema.sql). Without it, the first Acquire fails with an error that wraps the driver's relation "worklease_leases" does not exist and matches no worklease sentinel; the statements are idempotent, so run them and retry:

-- canonical: backend/postgres/schema.sql
CREATE SEQUENCE IF NOT EXISTS worklease_fencing_seq;

CREATE TABLE IF NOT EXISTS worklease_leases (
    work_id         TEXT        PRIMARY KEY,
    holder_id       TEXT        NOT NULL,
    fencing_token   BIGINT      NOT NULL DEFAULT nextval('worklease_fencing_seq'),
    expires_at      TIMESTAMPTZ NOT NULL,
    checkpoint      BYTEA,
    exit_mode       TEXT,
    prev_exit_mode  TEXT        NOT NULL DEFAULT 'none',
    prev_holder_id  TEXT,
    acquired_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT worklease_leases_exit_mode_check
        CHECK (exit_mode IS NULL OR exit_mode IN ('finished', 'abandoned', 'retired')),
    CONSTRAINT worklease_leases_prev_exit_mode_check
        CHECK (prev_exit_mode IN ('none', 'expired', 'finished', 'abandoned', 'retired'))
);

CREATE INDEX IF NOT EXISTS idx_worklease_leases_updated_at
    ON worklease_leases (updated_at);

The atomic checkpoint operation is a single UPDATE ... WHERE fencing_token = $n. Zero rows updated means the token is stale (ErrFenced) or that this holder already declared an exit with Release (ErrLeaseExpired); a follow-up query tells them apart. There is no Lua script, no optimistic retry loop, no distributed clock dependency. The checkpoint column is NULL until state is written, and again after a Checkpoint of a nil or empty state; ReadCheckpoint returns a nil State for it.

The backend requires the READ COMMITTED isolation level, the PostgreSQL default. Under REPEATABLE READ or SERIALIZABLE, a contended Acquire fails with a serialization error (SQLSTATE 40001) instead of returning ErrLeaseHeld. If your database or role defaults to another level, pin it for the role worklease connects as: ALTER ROLE worklease_role SET default_transaction_isolation = 'read committed';. The schema drops the deprecated clean_handoff column as of v0.7; existing databases drop it with the step in UPGRADING.md. A statement cancelled or timed out by its context returns an error that wraps both the driver error and ctx.Err() (#113); the Backend contract requires custom backends to match ctx.Err() the same way.

The backend is tested on PostgreSQL 16 with github.com/lib/pq. The backend suite also passes on pgx v5 (github.com/jackc/pgx/v5/stdlib), apart from two specs that look for lib/pq's *pq.Error type.

In-memory (testing)

import "github.com/aetomala/worklease/backend/memory"

backend := memory.New()
lease, _ := worklease.New(backend, worklease.Config{
    TTL:      5 * time.Second,
    HolderID: "test-worker",
})

Suitable for unit tests within a single process. It passes the same conformance suite as the PostgreSQL backend. Its fencing tokens come from a per-instance counter that advances only on a successful Acquire, while PostgreSQL uses one sequence per database that every attempt advances. Not safe for concurrent use across processes.

Comparison

Why not Temporal, Inngest, or DBOS?

These tools sit at the high-guarantee, high-adoption-cost end of the spectrum. They solve the failure mode — but the adoption unit is your entire application architecture.

Temporal requires rewriting business logic as Workflows and Activities, running a Temporal server, and accepting deterministic replay constraints. Inngest is a fully managed platform with its own execution model. DBOS restructures your entire application around a framework.

Teams already running Go workers with PostgreSQL don't need to restructure their application to get correct lease handoff semantics. They need a library primitive they can drop into the system they already have.

Distributed locks sit at the opposite end — low adoption cost, wrong abstraction. They tell you who holds the resource; they don't help the new holder continue what the old holder started.

The gap between these two ends is where worklease lives. The only prior art in that gap is KCL, which is Java-only and Kinesis-specific.

Stability

From v1.0.0 worklease follows semantic versioning, and ADR-0020 records what that covers:

• A change to an exported identifier outside internal/ is breaking, with exceptions for implementers: Lease and the observer interfaces may gain methods in a minor release (embed worklease.NoopObserver, worklease.NoopVacuumObserver, or pool.NoopObserver, or embed the Lease interface in a wrapper). The backend.Backend method set is fixed for all of v1.
• Match sentinels with errors.Is. Error message text is not promised.
• A default marked tunable in ADR-0020 may change in a minor release when the CHANGELOG lists it; set a value explicitly if you depend on it.
• A minor release may add tables, nullable columns, and indexes to the PostgreSQL schema, never drop or rename a column. Applying and migrating the schema stays your job.
• The supported Go versions are the two latest releases, and the go directive is raised only in a minor release.
• An identifier is deprecated for at least one minor release before a major release removes it.
• Nothing under internal/ is promised, and backend/conformance tightens the backend contract only in a major release.

Status

CHANGELOG.md lists every release, and UPGRADING.md has the steps between versions. The core lease model (Lease, Token, fencing, options, sentinels) and the worker, leader, pool, and checkpoint packages are covered by the promise above.

Roadmap

A Redis backend and an etcd backend are possible additions (unscheduled).

Examples

Runnable examples covering crash recovery, checkpoint resume, cluster leadership, partition processing, observability, and the renewal and acquire lifecycle. No infrastructure required — all examples run against the in-memory backend.

See examples/ for the full list with descriptions and run instructions.

License

Apache 2.0 — see LICENSE and NOTICE.