wisegate_core/lib.rs
1//! WiseGate Core - Reusable reverse proxy components
2//!
3//! This crate provides the core functionality for building reverse proxies with:
4//! - Rate limiting with sliding window algorithm
5//! - IP filtering and blocking
6//! - HTTP method and URL pattern filtering
7//! - Trusted proxy validation (RFC 7239 compliant)
8//!
9//! # Overview
10//!
11//! `wisegate-core` is designed to be framework-agnostic and can be integrated
12//! into any Rust application. Configuration is provided via the [`ConfigProvider`]
13//! trait, allowing flexible configuration from any source.
14//!
15//! # Quick start
16//!
17//! [`DefaultConfig`] pre-implements every configuration trait, so a minimal
18//! setup needs no boilerplate. Mutate its public fields to customize behaviour:
19//!
20//! ```
21//! use std::time::Duration;
22//! use wisegate_core::{DefaultConfig, RateLimiter};
23//!
24//! let mut config = DefaultConfig::default();
25//! config.rate_limit.max_requests = 200;
26//! config.rate_limit.window_duration = Duration::from_secs(30);
27//! config.blocked_methods = vec!["TRACE".into(), "CONNECT".into()];
28//!
29//! let _limiter = RateLimiter::new();
30//! ```
31//!
32//! When you need finer control, implement the composable traits directly
33//! ([`RateLimitingProvider`], [`ProxyProvider`], [`FilteringProvider`],
34//! [`ConnectionProvider`], [`AuthenticationProvider`]). See [`types`] for
35//! a worked example of bespoke implementations.
36//!
37//! # Wiring it into hyper
38//!
39//! [`request_handler::handle_request`] is async and expects a Tokio runtime —
40//! call it from inside `#[tokio::main]` or any other Tokio executor. It takes
41//! an `Arc<C: ConfigProvider>` so the same configuration can be cloned cheaply
42//! across spawned tasks.
43//!
44//! # Modules
45//!
46//! - [`types`] - Core types and the [`ConfigProvider`] trait
47//! - [`error`] - Error types and result aliases
48//! - [`headers`] - HTTP header constants
49//! - [`ip_filter`] - IP validation, extraction, and filtering
50//! - [`rate_limiter`] - Rate limiting implementation
51//! - [`request_handler`] - HTTP request processing and forwarding
52
53#![forbid(unsafe_code)]
54
55pub mod auth;
56pub mod default_config;
57pub mod defaults;
58pub mod error;
59pub mod headers;
60pub mod ip_filter;
61pub mod rate_limiter;
62pub mod request_handler;
63#[cfg(test)]
64pub mod test_utils;
65pub mod types;
66
67// Re-export commonly used items at crate root
68pub use auth::{Credential, Credentials, check_basic_auth, check_bearer_token};
69pub use default_config::DefaultConfig;
70pub use error::WiseGateError;
71pub use types::{
72 // Composable configuration traits
73 AuthenticationProvider,
74 // Aggregated configuration trait
75 ConfigProvider,
76 ConnectionProvider,
77 FilteringProvider,
78 // Configuration structs
79 ProxyConfig,
80 ProxyProvider,
81 RateLimitCleanupConfig,
82 RateLimitConfig,
83 // Rate limiting types
84 RateLimitEntry,
85 RateLimiter,
86 RateLimitingProvider,
87};