iet-rate-limit

First-hit fixed windows over the cache contract; the backend determines enforcement scope.

How to use it

iet-rate-limit is a cache-backed RateLimit: it counts first-hit fixed windows in any iet_cache::Cache<Value = u64> and returns a RateDecision. The meaning of a subject (peer IP, principal) and the enforcement scope come from the cache backend you select, and transport adapters such as iet-http-axum call check per request.

// examples/handbook-notes/src/main.rs
use iet_cache_memory::MemoryCache;
use iet_rate_limit::{RateDecision, RateLimiter, RatePolicy};
use std::time::Duration;

// Fixed windows over any `Cache<Value = u64>`; process-local here.
let limiter = RateLimiter::new(
    MemoryCache::<u64>::new(4096)?,
    RatePolicy::new("notes.http.ip", 120, Duration::from_secs(60))?,
);

// The subject names its identity kind and scope; never pass credentials.
match limiter.check(format!("ip:{}", peer_addr)).await? {
    RateDecision::Allowed { remaining, .. } => { /* serve */ }
    RateDecision::Denied { retry_after } => { /* 429 + Retry-After */ }
}

• RatePolicy::new(id, limit, window) rejects zero limits and windows; the policy id is part of the cache key, so version it.
• Attempts are counted even when downstream work fails, and an unknown window starts on first hit.
• RateLimit::with_policy lets a transport override a policy per route; Unlimited is the explicit no-op default.

How it works

check builds a key from the policy prefix and the subject, then asks the cache to atomically increment the fixed window; the returned count decides allowed versus denied.

sequenceDiagram
  participant C as "Caller"
  participant L as "RateLimiter"
  participant K as "Cache"
  C->>L: "check subject"
  L->>L: "key = policy prefix plus subject"
  L->>K: "increment_window key window"
  K-->>L: "CounterWindow count expires_in"
  alt "count <= limit"
    L-->>C: "Allowed remaining resets_in"
  else "count > limit"
    L-->>C: "Denied retry_after"
  end

What it implements

• Implements iet_rate_limit_core::RateLimit from iet-rate-limit-core.

What's inside

Modules

• src/lib.rs

Public API

(root)

• struct RateLimiter
• pub fn new(cache: C, policy: RatePolicy) -> Self

Impl map

• RateLimit for RateLimiter<C>

Depends on

• iet-telemetry
• iet-rate-limit-core
• iet-core
• iet-cache

Used by

• No other framework crate depends on it directly.

In this repository

• examples/handbook-notes
• examples/htmx-starter

Source: crates/features/iet-rate-limit