Crate ratelock 

A minimal, auditable, lock-free token bucket rate limiter.

Design goals

• Zero dependencies
• Zero heap allocations
• No unsafe
• no_std compatible core
• Deterministic tests via custom Clock implementations

Behavior guarantees

• RateLimiter::remaining is always bounded by capacity
• RateLimiter::allow_n is atomic for token deduction
• If time goes backwards (now < last_refill), refill is skipped
• All public operations are panic-free

Example (std)

use ratelock::RateLimiter;

let limiter = RateLimiter::new(10, 5);
assert!(limiter.allow());
assert_eq!(limiter.remaining(), 9);

Example (no_std compatible API)

use ratelock::{Clock, RateLimiter};

struct FixedClock(u64);
impl Clock for FixedClock {
    fn now_ns(&self) -> u64 {
        self.0
    }
}

let clock = FixedClock(0);
let limiter = RateLimiter::with_clock(3, 0, clock);
assert!(limiter.allow());
assert!(limiter.allow());
assert!(limiter.allow());
assert!(!limiter.allow());

Structs

RateLimiter

Non-allocating lock-free token bucket.

ShardedRateLimiter

A fixed-size shard set of independent RateLimiter instances.

Snapshot

Best-effort state snapshot for observability.

StdClock

std clock implementation backed by std::time::Instant.

Traits

Clock

Monotonic time source used by crate::RateLimiter.