load_balancer/
lib.rs

1//! # Load Balancer Library
2//!
3//! This library provides a set of generic load balancer implementations for distributing
4//! workloads across multiple targets, such as clients, network endpoints, or resources.
5//!
6//! ## Traits
7//!
8//! ### `LoadBalancer<T>`
9//!
10//! A generic trait for asynchronous or synchronous load balancing. Implementors provide
11//! methods to allocate a resource from the pool.
12//!
13//! ```rust
14//! use std::future::Future;
15//!
16//! pub trait LoadBalancer<T>: Send + Sync + Clone + 'static {
17//!     /// Asynchronously allocate a resource.
18//!     fn alloc(&self) -> impl Future<Output = T> + Send;
19//!
20//!     /// Attempt to allocate a resource synchronously without awaiting.
21//!     fn try_alloc(&self) -> Option<T>;
22//! }
23//! ```
24//!
25//! ### `FilteredLoadBalancer<T>`
26//!
27//! A trait for load balancers that support predicate-based filtering.  Unlike
28//! [`LoadBalancer`], filter methods return `(usize, T)` — the entry index
29//! alongside the value — so callers can identify the allocated entry.
30//!
31//! ```rust
32//! use std::future::Future;
33//!
34//! pub trait FilteredLoadBalancer<T>: Send + Sync + Clone + 'static {
35//!     /// Asynchronously allocate an entry that satisfies the given predicate.
36//!     fn alloc_filter(
37//!         &self,
38//!         predicate: impl FnMut((usize, &T)) -> bool,
39//!     ) -> impl Future<Output = (usize, T)> + Send;
40//!
41//!     /// Attempt to allocate an entry that satisfies the predicate without awaiting.
42//!     fn try_alloc_filter(
43//!         &self,
44//!         predicate: impl FnMut((usize, &T)) -> bool,
45//!     ) -> Option<(usize, T)>;
46//! }
47//! ```
48
49/// Cooldown-based load balancer with per-entry reuse intervals.
50pub mod cooldown;
51/// Fault-tolerant load balancer with error tracking and auto-disabling.
52pub mod fault_tolerant;
53/// Proxy pool with health checking and latency-based sorting.
54pub mod proxy_pool;
55/// Random selection load balancer.
56pub mod random;
57/// Fixed-window rate limiter (single + per-key map).
58pub mod rate_limit;
59/// Round-robin sequential load balancer.
60pub mod round_robin;
61/// Sliding-window load balancer with per-entry rate limits.
62pub mod window;
63
64pub use anyhow;
65pub use dashmap;
66pub use reqwest;
67
68/// A generic load balancer trait for allocating resources from a pool.
69///
70/// Implementors manage a collection of items and distribute them according to
71/// their specific strategy (round-robin, random, cooldown, etc.).
72pub trait LoadBalancer<T>: Send + Sync + Clone + 'static {
73    /// Asynchronously allocate a resource from the pool.
74    fn alloc(&self) -> impl Future<Output = T> + Send;
75    /// Attempt to allocate a resource synchronously without awaiting.
76    fn try_alloc(&self) -> Option<T>;
77}
78
79/// A load balancer that supports predicate-based filtering during allocation.
80///
81/// Unlike [`LoadBalancer`], filter methods return `(usize, T)` so callers
82/// can identify the allocated entry (e.g. for error feedback).
83pub trait FilteredLoadBalancer<T>: Send + Sync + Clone + 'static {
84    /// Asynchronously allocate an entry that satisfies the given predicate.
85    fn alloc_filter(
86        &self,
87        predicate: impl FnMut((usize, &T)) -> bool + Send,
88    ) -> impl Future<Output = (usize, T)> + Send;
89    /// Attempt to allocate an entry that satisfies the predicate without awaiting.
90    fn try_alloc_filter(&self, predicate: impl FnMut((usize, &T)) -> bool) -> Option<(usize, T)>;
91}
load_balancer/lib.rs

load_balancer/
lib.rs
