Chapter 7 — Lease: Time-Bounded Ownership
Chapter objective: After this chapter, a developer can express time-bounded shard ownership with acquire, renew, transfer, release, and fencing tokens.
Learning objectives
- Distinguish a current value from a current right to act.
- Explain the separate duties of TTL, epoch, and fencing token.
- Describe renewal, transfer, release, and expiry.
- Make an external resource reject an old holder.
Prerequisites
- Register conflict resolution is understood.
- Process pauses, network partitions, and time progression can leave an old owner running.
Case progress
A fulfillment worker claims shard orders-17. Only a
valid holder can commit scheduling results for the shard. Ownership
expires, and after a transfer the external write boundary rejects the
old worker.
Lifecycle and guardrail
lease.acquire("orders-17", acquireOptions).join();
lease.renew("orders-17", renewOptions).join();
lease.transfer("orders-17", "worker-b", transferOptions).join();
lease.release("orders-17", releaseOptions).join();TTL answers when ownership expires. A fencing token lets an external system identify an old holder. A successful transfer creates a higher token; a database, object store, or downstream executor stores the last accepted token and rejects lower values.
When an external resource ignores the token, an expired worker can still write. Additional DSM replication cannot repair that boundary.
Why a stable member view matters
Lease operations coordinate high-risk actions. Blind reassignment during an unstable member view can leave two workers believing that they own a shard. The API and runtime signals define the current implementation's rejection and mode boundaries; a business service cannot rely on a single local boolean.
Counterexample and fault injection
Worker A pauses after receiving token 7. The lease transfers to B
with token 8. A resumes and writes again. An executor that does not
compare tokens accepts the old owner. A useful experiment checks both
lease state and FencingExecutor rejection of token 7.
Experiment
cd submodule/dsm
mvn -q -pl dsm-integration-test -am \
-Dtest=RuntimeIntegrationTest#fencingExecutorRejectsStaleHolderAfterLeaseTransfer \
-Dsurefire.failIfNoSpecifiedTests=false testBesides checking the holder name, the test invokes the transferred resource with the old token to verify rejection at the external boundary.
Experiment acceptance card
| Field | Content |
|---|---|
| Command | The focused RuntimeIntegrationTest command above |
| Input or fault | A holds the lease, transfers it to B, then acts with its old token |
| Observable result | B receives a higher token; the fencing executor rejects the old token |
| Evidence level | E2: integration behavior in one Runtime |
| This experiment does not prove | A real membership split, cross-process pause behavior, or correct token checks in every external store |
Review
- A Lease represents a time-bounded right to act, not an ordinary latest value.
- TTL closes the ownership window; a fencing token protects the external side-effect boundary.
- Transfer advances the token monotonically because the old holder may still be alive.
- Complete fencing depends on token validation by the external resource.
Next
Chapter 8 lets every node update a counter locally and designs a mergeable state instead of selecting one owner.