Lease
Ce contenu n’est pas encore disponible dans votre langue.
Defined in: src/coordination/Lease.ts:21
Abstract distributed lease. A lease is owned by a single holder for a bounded duration; renewed periodically by the holder to keep ownership.
Four-method contract:
acquire()tries to claim the lease; returns true on success.release()voluntarily drops ownership.checkAlive()is a cheap “do I still own this lease?” check used by failure-detection logic.onLost(cb)registers a callback fired if ownership is lost unexpectedly (TTL expired, another holder took over, etc.).
Different backends implement the contract differently — see
InMemoryLease (reference + tests) and KubernetesLease (production).
Backends MAY additionally implement acquireWithToken() for fencing-
token support — see the method comment below. Consumers that need
fencing (e.g. LeaseMajority split-brain protection) feature-detect
the method and fall back to plain acquire() when it’s absent.
Methods
Section titled “Methods”acquire()
Section titled “acquire()”acquire():
Promise<boolean>
Defined in: src/coordination/Lease.ts:23
Try to acquire the lease. Resolves true on success, false on contention.
Returns
Section titled “Returns”Promise<boolean>
acquireWithToken()?
Section titled “acquireWithToken()?”
optionalacquireWithToken():Promise<{token:string; } |null>
Defined in: src/coordination/Lease.ts:49
Optional: acquire the lease and return a backend-issued fencing
token on success. Returns null on contention (semantic
equivalent of acquire() returning false).
A fencing token is a value that an external observer can use to
order two acquires against the same lease — typically backed by the
coordination service’s own optimistic-concurrency primitive
(Kubernetes Lease’s resourceVersion + leaseTransitions, Redis
SETNX with an incrementing counter, etcd revision, etc.).
Why both methods exist: acquire() is sufficient for the common
“did I win the race?” question, and is the minimum contract every
backend must implement. acquireWithToken() is for callers that
also need to detect a stale acquire result. Without a token,
a late-arriving acquire() → true from a previously-timed-out
attempt is indistinguishable from a fresh successful acquire; with
a token, the caller compares the token against the current holder
to decide whether the result still reflects reality.
Tokens are opaque strings — comparison must be exact-string. Backends should choose a representation that’s monotonic per acquire (so callers can detect “newer acquire happened after mine”).
Returns
Section titled “Returns”Promise<{ token: string; } | null>
checkAlive()
Section titled “checkAlive()”checkAlive():
boolean
Defined in: src/coordination/Lease.ts:55
True if this process currently owns the lease. Purely local — no IO.
Returns
Section titled “Returns”boolean
onLost()
Section titled “onLost()”onLost(
handler): () =>void
Defined in: src/coordination/Lease.ts:58
Register a handler fired when ownership is lost unexpectedly.
Parameters
Section titled “Parameters”handler
Section titled “handler”(reason) => void
Returns
Section titled “Returns”() => void
release()
Section titled “release()”release():
Promise<void>
Defined in: src/coordination/Lease.ts:52
Release the lease voluntarily. No-op if not held.
Returns
Section titled “Returns”Promise<void>