Models

Data models for rate limit configuration and status.

Limit

Limit dataclass

Limit(name, capacity, burst, refill_amount, refill_period_seconds)

Token bucket rate limit configuration.

Refill rate is stored as a fraction (refill_amount / refill_period_seconds) to avoid floating point precision issues.

Attributes:

Name	Type	Description
name	str	Unique identifier for this limit type (e.g., "rpm", "tpm")
capacity	int	Max tokens that refill over the period (sustained rate)
burst	int	Max tokens in bucket (>= capacity, allows bursting)
refill_amount	int	Numerator of refill rate
refill_period_seconds	int	Denominator of refill rate

refill_rate property

refill_rate

Tokens per second (for display/debugging).

per_second classmethod

per_second(name, capacity, burst=None)

Create a limit that refills capacity tokens per second.

per_minute classmethod

per_minute(name, capacity, burst=None)

Create a limit that refills capacity tokens per minute.

per_hour classmethod

per_hour(name, capacity, burst=None)

Create a limit that refills capacity tokens per hour.

per_day classmethod

per_day(name, capacity, burst=None)

Create a limit that refills capacity tokens per day.

custom classmethod

custom(name, capacity, refill_amount, refill_period_seconds, burst=None)

Create a custom limit with explicit refill rate.

Sustain 100/sec with burst of 1000

Limit.custom("requests", capacity=100, refill_amount=100, refill_period_seconds=1, burst=1000)

to_dict

to_dict()

Serialize to dictionary for storage.

from_dict classmethod

from_dict(data)

Deserialize from dictionary.

Entity

Entity dataclass

Entity(id, name=None, parent_id=None, metadata=dict(), created_at=None)

An entity that can have rate limits applied.

Entities can be parents (projects) or children (API keys). Children have a parent_id reference.

Note: This model does not validate in post_init to support DynamoDB deserialization and avoid performance overhead. Validation is performed in Repository.create_entity() at the API boundary.

is_parent property

is_parent

True if this entity has no parent (is a root/project).

is_child property

is_child

True if this entity has a parent.

LimitStatus

LimitStatus dataclass

LimitStatus(entity_id, resource, limit_name, limit, available, requested, exceeded, retry_after_seconds)

Status of a specific limit check.

Returned in RateLimitExceeded to provide full visibility into all limits that were checked.

Note: This is an internal model created by the limiter from validated inputs. No validation is performed here to avoid performance overhead.

deficit property

deficit

How many tokens short we are (0 if not exceeded).

BucketState

BucketState dataclass

BucketState(entity_id, resource, limit_name, tokens_milli, last_refill_ms, capacity_milli, burst_milli, refill_amount_milli, refill_period_ms)

Internal state of a token bucket.

All token values are stored in millitokens (x1000) for precision.

Note: This is an internal model. Validation is performed in from_limit() for user-provided inputs, not in post_init to support DynamoDB deserialization and avoid performance overhead on frequent operations.

tokens property

tokens

Current tokens (not millitokens).

capacity property

capacity

Capacity (not millitokens).

burst property

burst

Burst (not millitokens).

from_limit classmethod

from_limit(entity_id, resource, limit, now_ms)

Create a new bucket at full capacity from a Limit.

Note: This is an internal factory method. Validation of entity_id and resource is performed at the API boundary (RateLimiter public methods) before calling this method.

Parameters:

Name	Type	Description	Default
entity_id	str	Entity identifier (pre-validated by caller)	required
resource	str	Resource name (pre-validated by caller)	required
limit	Limit	Limit configuration (validated via post_init)	required
now_ms	int	Current time in milliseconds	required

AuditEvent

AuditEvent dataclass

AuditEvent(event_id, timestamp, action, entity_id, principal=None, resource=None, details=dict())

Security audit event for tracking modifications.

Audit events are logged for security-sensitive operations: - Entity creation and deletion - Limit configuration changes

Attributes:

Name	Type	Description
event_id	str	Unique identifier for the event (timestamp-based)
timestamp	str	ISO timestamp when the event occurred
action	str	Type of action (see AuditAction constants)
entity_id	str	ID of the entity affected
principal	str | None	Caller identity who performed the action (optional)
resource	str | None	Resource name for limit-related actions (optional)
details	dict[str, Any]	Additional action-specific details

to_dict

to_dict()

Serialize to dictionary for storage.

from_dict classmethod

from_dict(data)

Deserialize from dictionary.

AuditAction

AuditAction

Audit action type constants.