rate_limit library

⏱️ JetLeaf Rate Limiting Library

This library provides a comprehensive rate-limiting system for JetLeaf applications, enabling fine-grained control over method calls, API access, and other resources.

It supports annotations, method interceptors, storage backends, event tracking, metrics, and pluggable resolvers.

🔑 Key Concepts

  • Rate-Limit Operations: control access frequency per resource or method.
  • Storage Backends: persist rate-limit state with optional rollback support.
  • Metrics: track allowed, denied, and reset events for monitoring.
  • Events: observe rate-limiting lifecycle events in real-time.
  • Resolvers & Managers: dynamically determine applicable limits.
  • Annotations: declarative, method-level rate limiting.

📦 Exports Overview

⚙ Core

  • RateLimitAnnotationMethodInterceptor — intercepts annotated methods
  • RateLimitComponentRegistrar — registers rate-limit components
  • RateLimitOperationContext / DefaultRateLimitOperationContext — runtime operation metadata

📊 Metrics

  • RateLimitMetrics — interface for tracking metrics
  • SimpleRateLimitMetrics — default implementation for monitoring events

🏗 Managers

  • RateLimitManager — primary orchestrator of rate-limiting rules
  • RateLimitManagerRegistry — manages multiple managers
  • SimpleRateLimitManager — default implementation

🔍 Resolvers

  • RateLimitResolver — determines applicable limits dynamically
  • RateLimitResolverRegistry — registry for multiple resolvers
  • SimpleRateLimitResolver — default implementation

🗄 Storage

  • RateLimitStorage — storage interface for rate-limit entries
  • RateLimitStorageRegistry — manage multiple storage backends
  • ConfigurableRateLimitStorage — custom-configurable storage
  • DefaultRateLimitStorage — standard in-memory implementation
  • RollBackCapableRateLimitStorage — supports rollback operations
  • RateLimitResource — resource representation
  • RateLimitEntry / SimpleRateLimitEntry — stored rate-limit state

📝 Events

  • RateLimitEvent — base event type
  • RateLimitAllowedEvent — emitted when a call passes
  • RateLimitDeniedEvent — emitted when a call is blocked
  • RateLimitResetEvent — emitted when counters reset
  • RateLimitClearEvent — emitted when cache or storage is cleared

🏷 Annotations & Config

  • annotations.dart — declarative, method-level rate limiting
  • RateLimitConfigurer — programmatic configuration
  • RateLimitResult — encapsulates the result of a rate-limited operation

🎯 Intended Usage

Import this library to enable full rate-limiting capabilities:

import 'package:jetleaf_resource/rate_limit.dart';

@RateLimited(maxCalls: 5, duration: Duration(minutes: 1))
void fetchData() {
  // method code
}

Supports pluggable storage, metrics, events, and error handling.

© 2025 Hapnium & JetLeaf Contributors

Classes

ConfigurableRateLimitStorage
Represents a configurable rate-limit storage that allows runtime tuning of critical operational parameters, primarily the time zone used for window tracking and expiration calculations.
DefaultRateLimitOperationContext<T>
Internal implementation of RateLimitOperationContext used to encapsulate runtime metadata, dependency access, and execution context for a rate-limited method invocation.
DefaultRateLimitStorage
A thread-safe, in-memory rate-limit storage implementation backed by a concurrent RateLimitResource.
RateLimit
Annotation that marks a method to be subject to rate limiting.
RateLimitAllowedEvent
Event published when a request is allowed under the configured rate limit.
RateLimitAnnotationMethodInterceptor
A composite ConditionalMethodInterceptor that transparently applies rate limiting behavior based on JetLeaf @RateLimit annotations.
RateLimitClearEvent
Event published when all request counters for a given rate limit bucket or storage have been cleared.
RateLimitComponentRegistrar
A specialized RateLimitAnnotationMethodInterceptor that integrates rate-limit enforcement with the JetLeaf application lifecycle.
RateLimitConfigurer
Defines the programmatic configuration entry point for the rate-limiting subsystem.
RateLimitDeniedEvent
Event published when a request is denied due to exceeding the configured rate limit.
RateLimitEntry
Represents a single tracked rate limit record within a RateLimitStorage.
RateLimitEvent
Base class for all rate limit events in JetLeaf.
RateLimitManager
The RateLimitManager interface defines the orchestration layer for managing multiple RateLimitStorage instances within JetLeaf’s traffic control subsystem.
RateLimitManagerRegistry
Registry for managing and exposing RateLimitManager instances.
RateLimitMetrics
Defines the contract for recording and reporting rate limit activity metrics.
RateLimitOperationContext<T>
Context object representing the state and behavior of a rate-limited method invocation or resource access.
RateLimitResetEvent
Event published when a rate limit window has been reset for a particular entity.
RateLimitResolver
The RateLimitResolver defines the strategy contract for resolving one or more RateLimitStorage instances for a specific RateLimit operation.
RateLimitResolverRegistry
Registry for managing RateLimitResolver instances.
RateLimitResource
A thread-safe in-memory resource for storing rate limit entries.
RateLimitResult
Represents the outcome of a rate-limit check for a specific identifier.
RateLimitStorage
The RateLimitStorage interface defines the abstraction for JetLeaf’s rate-limiting persistence and quota tracking mechanism.
RateLimitStorageRegistry
Central registry for managing RateLimitStorage instances.
RollbackCapableRateLimitStorage
An in-memory rate-limit storage variant that supports best-effort rollback of a prior successful consume.
SimpleRateLimitEntry
Internal implementation of RateLimitEntry representing a single rate limit tracking window for a specific key.
SimpleRateLimitManager
A composite RateLimitManager implementation that manages discovery, registration, and resolution of RateLimitStorage instances.
SimpleRateLimitMetrics
Concrete implementation of RateLimitMetrics that tracks operational statistics for a specific rate-limited resource or bucket.
SimpleRateLimitResolver
A simple, composite RateLimitResolver implementation that delegates storage resolution to a chain of configured resolvers and a primary RateLimitManager fallback.

Typedefs

RateLimitStorageCreator = FutureOr<RateLimitStorage?> Function(String name)
A factory function capable of creating a new RateLimitStorage instance when a requested storage name is not already registered in the RateLimitStorageRegistry.