tollgate_core/
lib.rs

1//! Zero-I/O, clock-free domain layer for quota admission and accounting.
2//!
3//! This crate is the request hot path. Its rules, in order:
4//!
5//! - **No I/O, no clock reads.** Every operation is a function of its
6//!   arguments; callers pass `now`. This is what makes the layer benchmarkable
7//!   in isolation and embeddable in a service whose whole request budget is a
8//!   few microseconds.
9//! - **Fail closed.** Unknown, expired, exhausted, or overflowing states deny;
10//!   nothing here ever falls back to a slower path, because there is no slower
11//!   path to fall back to.
12//! - **Checked arithmetic only.** Cost math never wraps (INVARIANTS.md GL-11).
13//! - **Domain-agnostic.** Cost units, operations, and permissions are generic;
14//!   consumers (e.g. FerroRisk) map their own vocabulary onto them at startup.
15//!
16//! The pieces compose in request order: an [`AccountSnapshot`] admits the
17//! principal, a [`CostTable`] quotes the work, a [`LocalLease`] reserves the
18//! units, and the resulting [`Reservation`] either commits at execution start
19//! or releases for zero charge — producing a [`UsageEvent`] only when
20//! committed. See `INVARIANTS.md` at the workspace root.
21//!
22//! Tollgate releases the workspace as one unit: every published crate carries
23//! the same version, and the crates depend on each other at exactly that
24//! version.
25
26pub mod budget;
27pub mod cost_table;
28pub mod deny;
29pub mod ids;
30pub mod lease;
31pub mod reservation;
32pub mod sharding;
33pub mod snapshot;
34pub mod units;
35pub mod usage;
36
37pub use budget::{
38    BalanceExhaustion, BalanceShortfall, BudgetSchedule, BudgetView, Period, Rollover,
39};
40pub use cost_table::{CostQuote, CostTable, CostTableBuilder, OpIndex, QuoteError};
41pub use deny::{DenyReason, Retry};
42pub use ids::{
43    AccountId, FencingToken, Generation, KeyId, LeaseId, ParseIdError, PolicyRevision, Principal,
44    RequestId,
45};
46pub use lease::{AccountOverage, LeaseGrant, LocalLease, RefillSignal, RefillVerdict};
47pub use reservation::{
48    CancelHandle, CancelOutcome, CommitError, CommitFunding, Reservation, SharedCharge,
49};
50pub use sharding::{LocalSharding, Locality, ShardOccupancy};
51pub use snapshot::{
52    AccountRatePolicy, AccountSnapshot, AccountSnapshotBuilder, AccountStatus, CapacityClass,
53    EnforcementMode, PermissionBits, PublishableSnapshot, RequestRateLimit, ResolvedLimits,
54    ResolvedLimitsError, SnapshotValidationError, WeightedRateLimit,
55};
56pub use units::CostUnits;
57pub use usage::{DiscardedUsage, DiscardedUsageSlot, UsageEvent, UsageSlot, UsageSource};
58
59// Compiles and runs the README's examples as doctests without adding them to
60// the rendered documentation, so the README cannot drift from the API.
61#[doc = include_str!("../README.md")]
62#[cfg(doctest)]
63pub struct ReadmeDoctests;
tollgate_core/lib.rs

tollgate_core/
lib.rs
