postrust_proxy/
lib.rs

1//! # Postrust Proxy
2//!
3//! High-performance reverse proxy module for Postrust with:
4//! - HTTP/1.1 and HTTP/2 support
5//! - Load balancing (round-robin, random, least-connections, weighted, sticky)
6//! - Active health checking
7//! - Rate limiting
8//! - Automatic TLS via Let's Encrypt (ACME)
9//! - Zero-downtime configuration updates
10//!
11//! ## Architecture
12//!
13//! The proxy is built on vendored code from [rust-rpxy](https://github.com/junkurihara/rust-rpxy),
14//! with additional features for database-backed configuration, health checking, and rate limiting.
15//!
16//! ```text
17//! ┌─────────────────────────────────────────────────────────────┐
18//! │                     Postrust Proxy                          │
19//! ├─────────────────────────────────────────────────────────────┤
20//! │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
21//! │  │   Config    │  │   Health    │  │     Rate Limit      │  │
22//! │  │ TOML + DB   │  │   Checker   │  │    Token Bucket     │  │
23//! │  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
24//! │         │                │                    │              │
25//! │         └────────────────┼────────────────────┘              │
26//! │                          │                                   │
27//! │              ┌───────────▼───────────┐                       │
28//! │              │    Vendored Core      │                       │
29//! │              │  (from rust-rpxy)     │                       │
30//! │              │  - Proxy handler      │                       │
31//! │              │  - Load balancer      │                       │
32//! │              │  - HTTP forwarding    │                       │
33//! │              └───────────────────────┘                       │
34//! └─────────────────────────────────────────────────────────────┘
35//! ```
36
37#![warn(clippy::all)]
38// `postrust-proxy` is a beta module with wiring still in progress. The following
39// lints are relaxed until it stabilizes (tighten before GA):
40// - missing_docs / dead_code: some public items and scaffolding are not yet wired up.
41// - result_large_err / large_enum_variant: rooted in the rich `ProxyError` enum.
42// - type_complexity: a few internal signatures pending refactor into type aliases.
43#![allow(missing_docs)]
44#![allow(dead_code)]
45#![allow(clippy::result_large_err)]
46#![allow(clippy::large_enum_variant)]
47#![allow(clippy::type_complexity)]
48
49pub mod admin;
50pub mod config;
51pub mod health;
52pub mod ratelimit;
53pub mod saas;
54pub mod tls;
55pub mod vendored;
56
57mod error;
58
59pub use error::{ProxyError, ProxyResult};
60
61// Re-export key types for convenience
62pub use config::{Backend, ProxyConfig, Route, Upstream};
63pub use health::HealthChecker;
64pub use ratelimit::RateLimiter;
65
66/// Proxy server state shared across handlers.
67pub struct ProxyState {
68    /// Database connection pool
69    pub pool: sqlx::PgPool,
70    /// Current proxy configuration
71    pub config: std::sync::Arc<tokio::sync::RwLock<ProxyConfig>>,
72    /// Health checker instance
73    pub health_checker: std::sync::Arc<HealthChecker>,
74    /// Rate limiter instance
75    pub rate_limiter: std::sync::Arc<RateLimiter>,
76    /// Configuration reloader
77    pub config_reloader: std::sync::Arc<config::ConfigReloader>,
78}
79
80impl ProxyState {
81    /// Create a new proxy state.
82    pub async fn new(pool: sqlx::PgPool, config: ProxyConfig) -> ProxyResult<Self> {
83        let rate_limit_defaults = config.rate_limit.clone();
84        let config = std::sync::Arc::new(tokio::sync::RwLock::new(config));
85        let health_checker = std::sync::Arc::new(HealthChecker::new(pool.clone()));
86        let rate_limiter = std::sync::Arc::new(RateLimiter::new(rate_limit_defaults));
87        let config_reloader = std::sync::Arc::new(config::ConfigReloader::new(config.clone()));
88
89        Ok(Self {
90            pool,
91            config,
92            health_checker,
93            rate_limiter,
94            config_reloader,
95        })
96    }
97}
postrust_proxy/lib.rs

postrust_proxy/
lib.rs
