Crate tollgate_admission 

The per-request admission pipeline.

The staged path performs, in order:

1. snapshot lookup by Principal (in-memory map, negative-cached),
2. account status / staleness / permission checks,
3. batch-cap check and cost quote (direct-indexed table),
4. request-count and weighted local rate-token consumption (governor),
5. principal and account concurrency acquisition,
6. lease debit, opening the typed pending state.

Nothing in this crate performs I/O, takes a blocking lock on the request path, or reads a wall/business clock for a policy decision: now is an argument. Misses deny — resolution is the background plane’s job (INVARIANTS.md GL-5).

Two dependencies do their own bookkeeping underneath that, and the budget counts it rather than pretending it away. governor reads its own monotonic clock for bucket arithmetic. MokaSnapshotMap reads one too, and roughly every sixty-fourth lookup its housekeeper takes a non-blocking try_lock and drains its read log inline — updating the frequency sketch, and evicting when the cache is at capacity. Neither is a source of snapshot or lease truth, and neither can block a request; both are measured mechanism costs, carried by the admission/snapshot_lookup_* rows and by moka_reads_stay_within_their_amortized_allocation_budget. ArcSwapSnapshotMap takes no lock on a read at all.

That prohibition covers logging too, so what this plane reports about itself is a tally rather than an event stream: every outcome lands in AdmissionCounters, indexed by reason, and an embedder exports it from off the request path.

AdmissionEngine::begin owns the lookup and returns a generation-pinned RequestContext; RequestContext::admit consumes it after body decoding without another map lookup.

Two interchangeable snapshot-map implementations exist behind SnapshotMap — MokaSnapshotMap and ArcSwapSnapshotMap — because the design review deliberately treats the cache choice as an empirical question for the perf gate, not a foregone conclusion.

Re-exports

pub use capacity::CapacityConfigError;

pub use capacity::CapacityEvidence;

pub use capacity::CapacityGate;

pub use capacity::CapacityOccupancy;

pub use capacity::CapacityPermit;

pub use capacity::ExecutionCapacityGate;

pub use capacity::ExecutionCapacityMode;

pub use capacity::ExecutionPermit;

pub use capacity::NoCapacityPermit;

pub use capacity::NoGate;

pub use counters::AdmissionCounters;

pub use counters::CommitRefusal;

pub use counters::CountersSnapshot;

pub use engine::AdmissionEngine;

pub use engine::Committed;

pub use engine::Pending;

pub use engine::ReadyToStart;

pub use engine::Released;

pub use engine::RequestContext;

pub use generation_model::Watermark;

pub use generation_model::accept_positive;

pub use generation_model::accept_revoked;

pub use generation_model::accept_unknown;

pub use maps::ArcSwapSnapshotMap;

pub use maps::MokaSnapshotMap;

pub use state::AccountAdmissionState;

pub use state::LeaseSlot;

pub use state::MapEntry;

pub use state::PublishableSnapshotUpdate;

pub use state::SnapshotMap;

pub use state::SnapshotUpdate;

Modules

capacity

Execution-capacity admission: whether this instance should start an already-valid request with the compute it has right now (GL-99).

counters

What the request path is allowed to say about itself.

engine

The admission pipeline itself.

generation_model

Pure generation-ordering model shared by the cache implementations.

maps

The two candidate snapshot-map implementations.

state

Per-account admission state and the snapshot-map abstraction.

Structs

CancelHandle

The asynchronous waiter’s half of a SharedCharge.

Principal

The request path’s lookup key: an opaque fingerprint of an already-verified credential. How it is derived (API-key HMAC, capability subject, session id) is the embedding service’s concern — by the time it reaches admission, verification has happened.

RefreshBatch

Reservation changes are reported even if the ensuing source reads fail.

Refreshed

An authoritative read and the retained incarnation it started against. No public constructor can attach a new fence to an old result.

SnapshotHistoryStats

Current control-plane retention occupancy, including pending source reads.

SnapshotRefresh

A reserved slot whose source read has not yet started.

Enums

PublicationError

A publication could not safely replace the current cache state.