loadpace_tower/lib.rs
1//! Tower integration for adaptive client-side load balancing and backpressure.
2//!
3//! Use this crate when a Tower client balances requests across a changing fleet
4//! and needs each endpoint to adapt to its own capacity and latency. The
5//! adapter preserves Tower's backpressure, paces dispatch using a per-endpoint
6//! GCRA schedule, and exposes predicted completion cost for P2C selection.
7//!
8//! The adapter keeps Tower-specific readiness, discovery, and load-balancing
9//! concerns out of the runtime-independent `loadpace` crate.
10//!
11//! # Deployment scope
12//!
13//! This crate is intended for trusted microservice clients sharing private
14//! service endpoints. Its congestion-control and fairness behavior assumes
15//! that the other clients are cooperative and run compatible control logic.
16//! It cannot protect paced clients from an unpaced or malicious peer.
17//!
18//! Do not use it as the primary rate limit, quota, abuse-prevention mechanism,
19//! or DDoS defense for a general-purpose public API. Enforce those policies at
20//! the server or another trusted ingress boundary.
21//!
22//! # Where to start
23//!
24//! - Wrap one service with [`AdaptiveEndpoint`] or [`AdaptiveLayer`].
25//! - Wrap a dynamic discovery stream with [`AdaptiveDiscovery`] and pass it to
26//! `tower::balance::p2c::Balance`.
27//! - See the repository's
28//! [Tower how-to guide](https://github.com/conradludgate/loadpace/blob/main/docs/how-to/integrate-with-tower.md)
29//! and [adapter reference](https://github.com/conradludgate/loadpace/blob/main/docs/reference/tower.md)
30//! for complete integration details.
31
32#![forbid(unsafe_code)]
33#![warn(missing_docs)]
34
35mod service;
36
37pub use service::{AdaptiveDiscovery, AdaptiveEndpoint, AdaptiveLayer, LoadMetric, ResponseFuture};