zeroae / zeroae/zae-limiter

Docs: Add Lease Lifecycle section explaining two-phase commit model

Open Beginner friendly
#384 0 comments 0 reactions 0 assignees View on GitHub

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 atomic UpdateItem per 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.