flocklease

Overview ¶

Package flocklease is the single-host port.SessionLease: cross-process single-writer enforcement for sessions sharing one machine (one store directory), backed by gofrs/flock advisory locks plus a small per-session record file. It is the lease analogue of the memory store's flock discipline (internal/adapter/memory/store.go), kept a SEPARATE package on purpose — the memory store's "one *Store per dir" invariant is about ONE sentinel guarding ONE document, whereas a per-session lease needs ONE lock file PER session id, so the two do not share a sentinel.

flock gives single-host exclusion AND free crash recovery: when a holder process dies, the OS releases its flock, so a survivor can take over without waiting for the TTL. flock has no TTL of its own, so the lease's owner/token/expiry semantics live in a JSON record file written under the held lock; the TTL covers the cross-HOST case the flock cannot (two machines over a shared NFS/EFS mount, where flock semantics are unreliable). Single-host is the honest guarantee; the multi-host story is the k8s/driver backends.

Layout per session id <safeID> under the lease dir:

• <safeID>.lock — the STABLE flock sentinel, never renamed.
• <safeID>.lease.json — {owner, token, expiry}, rewritten atomically under the lock (temp + rename).

<safeID> is a collision-free encoding (a sanitized prefix + a hash suffix) so two distinct ids never share a lock file and thus never falsely contend.

INVARIANT — at most ONE *Lease per dir per process (the composition discipline), mirroring the memory store. Per-id sentinels mean distinct sessions never cross-contend; the per-id flock fd is created per operation and closed before return, so there is no long-lived handle to self-deadlock.