Docs: Add Lease Lifecycle section explaining two-phase commit model
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 51m
- Merged PRs (30d)
- 104
Description
Problem
The current documentation doesn't clearly explain how lease.adjust() works internally. A reader could reasonably assume that adjust() immediately writes to DynamoDB, or that the commit on context exit is non-atomic. In reality:
adjust()accumulates deltas in memory only (no DynamoDB calls)_commit_adjustments()writes a single atomicUpdateItemper entity on successful context exit_rollback()refunds initial consumption via compensating writes on exception
This two-phase model is a key correctness property that should be prominently documented.
Suggested Content
Add a "Lease Lifecycle" section to the getting-started or API docs:
## Lease Lifecycle
1. `acquire()` → initial tokens consumed (written to DynamoDB)
2. `adjust()` → deltas accumulated in memory (NO DynamoDB calls)
3. Context exit (success) → `_commit_adjustments()` writes one
atomic UpdateItem per entity
4. Context exit (exception) → `_rollback()` refunds initial
consumption via compensating writes
Note: If `_rollback()` itself fails (e.g., DynamoDB unavailable),
the failure is logged but does not mask the original exception.
A sequence diagram showing the DynamoDB operations at each phase would also help.
Why This Matters
Without this documentation, users integrating zae-limiter into latency-sensitive pipelines (e.g., LLM proxies) may incorrectly assume adjust() adds network round-trips, or may not trust the atomicity guarantees and add unnecessary defensive code.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the getting-started or API documentation and trace the lease.adjust(), _commit_adjustments(), and _rollback() entry points to confirm the documented lifecycle. Done means a Lease Lifecycle section explains the DynamoDB operations, atomic commit, compensating rollback, and original-exception behavior; a sequence diagram is optional.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100