dblock

package
v0.0.0-...-df0d7b6 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package dblock runs a piece of work on at most one process at a time, using a PostgreSQL session advisory lock as the mutual exclusion primitive.

It exists for supervisors that are safe to run everywhere but wasteful to run everywhere — the JMAP inbox consumer being the first (spec 2026-08-22-01). Advisory locks are the right size of hammer here: every replica already shares one Postgres, so leader election needs no new component, no quorum and no lease bookkeeping. What it is NOT is a correctness mechanism: the holder can lose the lock at any instant (its connection dies, the process pauses), and a second holder can be running before the first has noticed. Whatever runs under RunExclusive must still be correct when two copies overlap.

Advisory-lock key registry

Keys are hand-allocated from the table below rather than hashed from a string, so a collision is impossible by construction and `grep <key>` finds every user of it. All keys use the single-argument bigint form of pg_advisory_lock. The numbering is 0x5001_0000 + sequence, where 0x5001 ("SP" 01) namespaces SolidPing's keys away from anything else that might share the database:

0x50010001  KeyJMAPInbox  single active JMAP inbox consumer

To add one: take the next free sequence number, define the constant here with a one-line purpose, and leave the old numbers alone even if their feature is removed — reusing a retired key risks two unrelated features silently excluding each other during a rolling deploy.

Two-int4 lock classes

Per-key transaction locks hash a string key, so they cannot be hand-allocated. They use the TWO-ARGUMENT int4 form, pg_advisory_xact_lock(class, hashtext(key)), whose key space Postgres keeps apart from the single-bigint keys above (pg_locks.objsubid 2 versus 1), so they can never exclude a supervisor. The class id is hand-allocated, from 0x5002_0000 + sequence ("SP 02"). A hash collision inside a class only serializes two unrelated keys; it never breaks correctness:

0x50020001  ClassGlobalCounter      per-key BumpGlobalCounter / RaiseGlobalCounter serialization
0x50020002  ClassDiscoveryScanStart per-org discovery scan start (guard + quota + job)

This convention is also written down in wiki/conventions/database.md.

Index

Constants

View Source
const ClassDiscoveryScanStart int32 = 0x5002_0002

ClassDiscoveryScanStart is the two-int4 advisory-lock class under which a discovery scan start re-checks the already-running guard and the daily agent quota, then creates its job (spec 2026-10-22-04): pg_advisory_xact_lock(ClassDiscoveryScanStart, hashtext(orgUID)).

View Source
const ClassGlobalCounter int32 = 0x5002_0001

ClassGlobalCounter is the two-int4 advisory-lock class under which db.Service.BumpGlobalCounter (and RaiseGlobalCounter) serializes writes of one global counter key (spec 2026-10-16-13): pg_advisory_xact_lock(ClassGlobalCounter, hashtext(key)).

View Source
const DefaultRetryInterval = 30 * time.Second

DefaultRetryInterval is how often a non-holder re-contends for the lock. It doubles as the failover delay when a holder dies, so it is short enough that inbound email is not stalled for long and long enough that a fleet of replicas is not hammering the database.

View Source
const KeyJMAPInbox int64 = 0x5001_0001

KeyJMAPInbox is the advisory-lock key for the JMAP inbox consumer: only one replica should hold a JMAP session against the shared mailbox at a time.

Variables

View Source
var ErrNilDB = errors.New("dblock: nil database")

ErrNilDB is returned when RunExclusive is handed no database handle.

Functions

func RunExclusive

func RunExclusive(
	ctx context.Context,
	database *bun.DB,
	key int64,
	retryInterval time.Duration,
	logger *slog.Logger,
	work func(context.Context) error,
) error

RunExclusive runs work while this process holds the advisory lock for key, and blocks until ctx is canceled.

On SQLite it simply runs work: a SQLite deployment is one process by construction, so there is nothing to exclude and no shared lock manager to do it with.

On Postgres it acquires the lock on a DEDICATED connection — session advisory locks live and die with the connection that took them, so the lock must never be taken through the pool where a recycled connection would drop it invisibly — then runs work on a context derived from ctx. When the lock is unavailable it retries every retryInterval; that same loop is the failover path when a holder dies. If the holding connection breaks, work's context is canceled and the loop goes back to contending. The lock is released on graceful shutdown.

work returning an error is not fatal to the loop's ownership: the error is logged, the lock released, and the loop re-contends after retryInterval, so a crashing supervisor hands the work to another replica instead of sitting on the lock.

Types

This section is empty.

Jump to

Keyboard shortcuts

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