Skip to content

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

@sodre

Description

@sodre

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions