iet-rate-limit-core

Defines the transport- and backend-neutral request admission contract.

How to use it

iet-rate-limit-core is the transport- and backend-neutral admission contract: RatePolicy (a validated prefix/limit/window), RateLimitConfig (per-route fixed or disabled), RateLimit (the check port), RateDecision, and the Unlimited default. The iet-rate-limit feature crate is the cache-backed implementation; this crate fixes the shape it must satisfy.

// crates/core/iet-rate-limit-core/src/lib.rs (contract used by crates/features/iet-rate-limit)
use iet_rate_limit_core::{RateDecision, RateLimit, RateLimitConfig, Unlimited};
use std::time::Duration;

// Registration validates limit/window; `None` means the route is not limited.
let policy = RateLimitConfig::fixed(120, Duration::from_secs(60))
    .policy("notes.http.ip")?
    .expect("fixed config yields a policy");
assert!(policy.limit() == 120 && policy.window() == Duration::from_secs(60));

// `Unlimited` is the fail-open default for a host with no limiter configured.
match Unlimited.check("ip:127.0.0.1").await? {
    RateDecision::Allowed { remaining, resets_in } => { /* admit; report headers */ }
    RateDecision::Denied { retry_after } => { /* reject with Retry-After */ }
}

• RatePolicy::new rejects an empty id, limit == 0, limit == u64::MAX, or a zero window with rate_limit.policy.
• RateLimitConfig::disabled() yields no policy; Default is fixed(120, 60s). The subject string must not contain credentials.

How it works

A typed RateLimitConfig is turned into a RatePolicy (or None when disabled); a RateLimit implementation consumes the policy and returns a RateDecision, with Unlimited as the always-allow default.

flowchart LR
  A["RateLimitConfig::fixed or disabled"] --> B["policy id"]
  B --> C["RatePolicy prefix limit window"]
  C --> D["RateLimit::check subject"]
  D --> E["RateDecision::Allowed"]
  D --> F["RateDecision::Denied"]
  G["Unlimited"] --> E

What it implements

• Defines the traits other crates implement: RateLimit.

What's inside

Modules

• src/lib.rs

Public API

(root)

• struct RatePolicy
• pub fn prefix(&self) -> &str
• pub fn limit(&self) -> u64
• pub fn window(&self) -> Duration
• pub fn new(id: impl Into<String>, limit: u64, window: Duration) -> AppResult<Self>
• struct RateLimitConfig
• const fn
• const fn
• pub fn policy(self, id: &str) -> AppResult<Option<RatePolicy>>
• enum RateDecision
• trait RateLimit

pub trait RateLimit: Clone + Send + Sync + 'static {
    fn with_policy(&self, policy: RatePolicy) -> Self;
    fn check(
        &self,
        subject: impl Display + Send,
    ) -> impl Future<Output = AppResult<RateDecision>> + Send;
}

• struct Unlimited

Impl map

• Default for RateLimitConfig
• RateLimit for Unlimited

Depends on

• iet-core

Used by

• iet-http-axum
• iet-rate-limit

In this repository

• Not used by a checked-in example yet.

Source: crates/core/iet-rate-limit-core