Expand description
ยงMoonClient ๐
An enterprise-grade, resilient, and middleware-driven HTTP client framework engineered for high-concurrency API integrations, robust web scrapers, and mission-critical microservices.
ยง๐ Quick Start
Here is a complete, copy-paste-ready example demonstrating how to initialize MoonClient,
configure automatic rate limiting, construct endpoint URLs using build_url!, and deserialize
typed JSON payloads:
use moonclient::response::Json;
use moonclient::{build_url, ClientHook, MoonClient, Result};
use serde::Deserialize;
use std::time::Duration;
#[derive(Debug, Deserialize)]
struct UserProfile {
id: u64,
username: String,
is_active: bool,
}
// 1. Define a minimal lifecycle hook (or use an empty unit hook)
struct DefaultHook;
#[async_trait::async_trait]
impl ClientHook for DefaultHook {
type Error = std::convert::Infallible;
}
#[tokio::main]
async fn main() -> Result<()> {
// 2. Build the client with timeouts, rate limits, and hooks
let client = MoonClient::builder(DefaultHook)
.with_base_url("https://api.example.com/v1")
.with_app_name("MyProductionApp/1.0")
.with_timeout(Duration::from_secs(10))
.requests_per_second(5) // Autonomous 5 RPS Token Bucket
.build();
// 3. Construct the endpoint safely with zero heap allocations
let user_id = 42;
let endpoint = build_url!(client, "users", user_id, "profile")?;
// 4. Dispatch request and extract typed JSON in one expression
let request = client.get(endpoint);
let Json(profile): Json<UserProfile> = client.execute(request).await?;
println!("Successfully loaded user: {} (ID: {})", profile.username, profile.id);
Ok(())
}ยง๐๏ธ Architectural Pillars
- Middleware & Exponential Retries: Built-in fault tolerance powered by
reqwest-retryandreqwest-tracing. Features a hybrid retry middleware that transparently passes through non-cloneable streaming multipart file uploads without panics. - Autonomous Traffic Shaping (Rate Limiting): Multi-window Token Bucket rate limiting
powered by
governor. Supports granular millisecond-level time windows (std::time::Duration), pre-configured RPS/RPM quotas, and optional distributed coordination viaredisconnection pools. - Pluggable Lifecycle Hooks: Interceptor architecture via the
ClientHooktrait, enabling asynchronous pre-request header injection (e.g., Bearer tokens, dynamic HMAC signatures) and reactive401 Unauthorizedtoken renewal with automatic request replaying. - Memory Bomb Protection: Bounded response buffer decoders safeguarding host processes against memory exhaustion attacks (unbounded streams or multi-gigabyte error payloads).
- Extractor Pattern: Unified, strongly typed
.execute()pipeline automatically deserializing responses intoJson<T>,Xml<T>, streamingResponse, or empty()(void) unit types. - Zero-Allocation Routing: High-performance
build_url!macro converting arbitrary primitives and domain enums into safe URL paths via copy-on-write strings (std::borrow::Cow<'_, str>). - Project Fluent i18n: Native multi-language diagnostic engine powered by
fluent, supporting thread-safetokioTask-Local contexts and extensible external bundle registries.
ยง๐๏ธ Pipeline Execution Flow
Every outbound HTTP request dispatched through MoonClient::execute traverses an opinionated,
defensive pipeline designed to guarantee safety under extreme load:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MoonClient::execute(req) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1. Rate Limiting Gate (Token Bucket via governor or distributed Redis) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 2. Pre-Request Lifecycle Hook (ClientHook::pre_request - Auth / HMAC) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 3. Resilient Middleware Pipeline (reqwest-retry + reqwest-tracing) โ
โ โข Transparent retry with exponential backoff on transient 5xx / drops โ
โ โข Safe bypass for streaming multipart uploads (Zero-Panic Guarantee) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 4. Outbound Wire Transmission (reqwest + rustls) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 5. Post-Request Interceptor & Reactive Auth Recovery โ
โ โข Intercepts 401 Unauthorized -> ClientHook::handle_unauthorized() โ
โ โข Seamless background token refresh & automatic request replay โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 6. OOM-Safe Bounded Buffer Decoders (Max response capacity guards) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 7. Extractor Pattern (FromResponse) -> Json<T>, Xml<T>, Response, () โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโยง๐งฉ Feature Flags
Re-exportsยง
pub use client::MoonClient;pub use client::MoonClientBuilder;pub use error::MoonError;pub use error::Result;pub use hooks::ClientHook;pub use i18n::register_resource;pub use i18n::set_global_locale;pub use limiter::InMemoryLimiter;pub use limiter::RequestLimiter;pub use response::FromResponse;pub use limiter::RedisLimiter;pub use reqwest;pub use reqwest_middleware;pub use reqwest_tracing;
Modulesยง
- client
- Implementation of the universal MoonClient network core, builder, and resilience middleware.
- error
- Domain error models, failure representations, and error conversion mechanics.
- hooks
- Pluggable lifecycle hooks and interceptors for network transaction pipelines.
- i18n
- Dynamic internationalization (i18n) and diagnostic localization engine powered by Project Fluent.
- limiter
- Abstractions and implementations of outbound network traffic shaping and rate limiting.
- logger
- High-performance, multi-threaded diagnostic logging engine with split-file destination sinks.
- response
- Strongly typed response extractors and memory-safe bounded stream decoders.
Macrosยง
- build_
url - Global macro for safe, declarative, and zero-allocation construction of endpoint URLs.
- tr
- Primary declarative macro for translating and interpolating localized messages.
Traitsยง
- Into
Segment - Trait for automatically coercing arbitrary types into safe URL path segments.