Crate limiteron 

Limiteron - Unified Flow Control Framework

Provides rate limiting, quota management, circuit breaking, and ban control.

API Layers

Prelude (Quick Start)

Use use limiteron::prelude::*; to import all commonly used types.

Core API

• Governor - Main controller for flow control
• FlowControlConfig - Configuration for flow control
• Decision - Decision result from flow control checks
• LimiteronError - Error types

Matchers

Identifier extractors: IP, User ID, Device ID, API Key, etc.

Limiters

Low-level rate limiting algorithms: Token bucket, sliding window, fixed window.

Extensions (feature-gated)

• Ban management (requires ban-manager feature)
• Circuit breaker (requires circuit-breaker feature)
• Quota control (requires quota-control feature)
• Macros (requires macros feature)
• Distributed rate limiting (requires distributed feature)
• trait-kit AsyncKit integration (requires kit feature)
• Internationalization (requires i18n feature)
• inklog structured logging (requires inklog feature)

Examples

use limiteron::prelude::*;
use limiteron::limiters::{TokenBucketLimiter, Limiter};

#[tokio::main]
async fn main() {
    // 创建一个简单的令牌桶限流器
    let limiter = TokenBucketLimiter::new(100, 10);

    // 检查请求是否被允许
    let decision = limiter.allow(1).await.unwrap();
    assert!(decision);
}

Features

• Multiple rate limiting algorithms: Token bucket, sliding window, fixed window, concurrency control
• Ban management: Automatic and manual ban management with priority support
• Quota control: Periodic quota allocation and alerting
• Circuit breaker: Automatic failover and state recovery
• Declarative macros: Use #[flow_control] macro to simplify rate limiting configuration
• Monitoring: Integrated Prometheus metrics and OpenTelemetry tracing
• High performance: Zero runtime overhead through compile-time optimization
• Distributed rate limiting: DistributedLimiter trait + InMemoryDistributedLimiter implementation (requires distributed feature)
• trait-kit integration: AsyncKit LimiteronModule (requires kit feature)
• Internationalization: Locale-aware number/date/plural/sort formatting (requires i18n feature)
• inklog logging: inklog structured logging integration (requires inklog feature)

Re-exports

pub use authorization::AuthorizationProvider;

pub use authorization::SimpleAuthorizationProvider;

pub use config::ConfigLoader;

pub use config::ActionConfig;

pub use config::ChangeSource;

pub use config::ConfigChangeRecord;

pub use config::ConfigHistory;

pub use config::ConfigMatcher;

pub use config::FlowControlConfig;

pub use config::LimiterConfig;

pub use config::Rule as ConfigRule;

pub use decision_chain::ChainStats;

pub use decision_chain::DecisionChain;

pub use decision_chain::DecisionChainBuilder;

pub use decision_chain::DecisionNode;

pub use error::BanInfo;

pub use error::CircuitBreakerStats;

pub use error::CircuitState;

pub use error::ConsumeResult;

pub use error::Decision;

pub use error::LimiteronError;

pub use error::LimiteronResult;

pub use error::StorageError;

pub use error::BanSafeError;

pub use error::ConfigSafeError;

pub use error::ErrorMessageAbstraction;

pub use error::GeneralSafeError;

pub use error::LimitSafeError;

pub use error::SafeErrorMessage;

pub use error::StorageSafeError;

pub use error::ValidationSafeError;

pub use limiters::Limiter;

pub use matchers::custom::CustomMatcher;

pub use matchers::custom::CustomMatcherRegistry;

pub use matchers::custom::CustomMatcherRegistryBuilder;

pub use matchers::custom::HeaderMatcher;

pub use matchers::custom::HeaderMatcherBuilder;

pub use matchers::custom::TimeWindowMatcher;

pub use matchers::custom::TimeWindowMatcherBuilder;

pub use matchers::ApiKeyExtractor;

pub use matchers::ApiKeyExtractorBuilder;

pub use matchers::CompositeCondition;

pub use matchers::CompositeExtractor;

pub use matchers::ConditionEvaluator;

pub use matchers::CustomExtractor;

pub use matchers::DeviceIdExtractor;

pub use matchers::DeviceIdExtractorBuilder;

pub use matchers::Identifier;

pub use matchers::IdentifierExtractor;

pub use matchers::IpExtractor;

pub use matchers::IpExtractorBuilder;

pub use matchers::IpRange;

pub use matchers::LogicalOperator;

pub use matchers::MacExtractor;

pub use matchers::MacExtractorBuilder;

pub use matchers::MatchCondition;

pub use matchers::MatcherStats;

pub use matchers::RequestContext;

pub use matchers::Rule;

pub use matchers::RuleMatcher;

pub use matchers::UserIdExtractor;

pub use matchers::UserIdExtractorBuilder;

pub use storage::BanHistory;

pub use storage::BanRecord;

pub use storage::BanStorage;

pub use storage::BanTarget;

pub use storage::QuotaInfo;

pub use storage::QuotaStorage;

pub use storage::Storage;

pub use logging::redact_basic;

pub use logging::redact_email;

pub use logging::redact_ip;

pub use logging::redact_user_id;

pub use oxcache;

pub use async_trait;

pub use chrono;

pub use tokio;

Modules

authorization

封禁操作授权模块

config

配置模块

decision_chain

决策链模块

error

错误类型定义

limiters

限流器模块

logging

日志安全模块

matchers

匹配器模块

prelude

Prelude module - Commonly used types for quick imports

storage

Storage trait definitions

validation

统一验证模块

Structs

Governor

Governor 主控制器

GovernorStats

Governor 统计信息

HealthStatus

Governor 健康状态

L1Cache

L1 本地缓存

L1CacheConfig

L1 本地缓存配置

MockClock

模拟时钟实现

RateLimitCacheKey

限流缓存键生成器

RuleBuilder

规则构建器

StatsManager

统计管理器

StatsSnapshot

统计信息快照

SystemClock

系统时钟实现

Traits

Clock

时钟 trait