Expand description
Framework-neutral contracts shared by Runlimit storage backends.
This crate defines anchored fixed-window and GCRA policies, opaque subject keys, checks, and backend-independent decisions. It deliberately contains no async runtime, transport framework, or persistence integration.
Applications own subject normalization and policy selection. Raw subjects
should be converted to SubjectKey values with KeyHasher before they
cross into a storage backend.
Async application adapters can use Limiter for generic dispatch across
storage backends without requiring boxed futures.
The optional serde feature provides validated policy and response-metadata
wire types. Opaque SubjectKey, CounterKey, and
PolicyFingerprint values intentionally remain non-serializable.
Structs§
- Admission
Observation - Metadata for one completed admission operation.
- Capacity
Observation - Local capacity use reported by a bounded backend.
- Check
- One proposed quota charge against a policy and opaque subject.
- Cleanup
Observation - Metadata for one bounded cleanup pass.
- Counter
Key - The complete logical identity of one stored rate-limit counter.
- Decision
- The outcome of evaluating one check.
- Fixed
Window Policy - An anchored fixed-window rate-limit policy.
- Gcra
Policy - A generic-cell-rate-algorithm policy.
- KeyHasher
- Derives opaque subject keys using HMAC-SHA-256.
- Policy
Fingerprint - A deterministic digest of a policy’s identity, scope, and configuration.
- Policy
Id - A stable application-defined rate-limit policy identifier.
- ScopeId
- A stable application-defined scope within a rate-limit policy.
- Subject
Key - An opaque, fixed-width subject identifier used by storage backends.
Enums§
- Admission
Operation - Whether an admission evaluated one check or an atomic batch.
- Admission
Outcome - Classification of a completed admission operation.
- Batch
Decision - The atomic outcome of evaluating checks in caller-supplied order.
- Batch
Error - A backend-independent invalid atomic batch.
- Check
Error - An invalid check cost.
- Consumption
Status - What a caller can know about quota consumption after an operation.
- Denial
- Structured details for a denied check.
- Gcra
Policy Error - An invalid GCRA policy configuration.
- Identifier
Error - An invalid policy or scope identifier.
- KeyHasher
Error - An invalid subject-key hasher configuration.
- Observation
- A backend-neutral operational observation.
- Policy
Error - An invalid fixed-window policy configuration.
- Quota
Mode - Whether quota exhaustion is enforced or reported in shadow mode.
Constants§
- MAX_
IDENTIFIER_ LENGTH - Maximum encoded length of a policy or scope identifier.
- MAX_
LIMIT - Largest quota or immediate capacity supported by built-in policies.
- MAX_
WINDOW - Largest policy duration supported by built-in policies.
- MAX_
WINDOW_ MILLIS - Largest whole-millisecond policy duration supported by built-in policies.
Traits§
- Limiter
- An asynchronous, backend-independent rate limiter.
- Observer
- Receives synchronous, backend-neutral operational observations.
- Rate
Limit Policy - Backend-independent policy metadata required to construct a check.
Functions§
- validate_
batch - Validates backend-independent structural requirements for an atomic batch.