zentinel_proxy/
lib.rs

1// Allow lints for work-in-progress features and code patterns
2#![allow(dead_code)]
3#![allow(unused_variables)]
4#![allow(unused_imports)]
5#![allow(clippy::too_many_arguments)]
6#![allow(clippy::match_like_matches_macro)]
7#![allow(clippy::manual_strip)]
8#![allow(clippy::only_used_in_recursion)]
9#![allow(clippy::type_complexity)]
10#![allow(clippy::manual_try_fold)]
11#![allow(private_interfaces)]
12
13//! Zentinel Proxy Library
14//!
15//! A security-first reverse proxy built on Pingora with sleepable ops at the edge.
16//!
17//! This library provides the core components for building a production-grade
18//! reverse proxy with:
19//!
20//! - **Routing**: Flexible path-based and header-based routing
21//! - **Upstream Management**: Load balancing, health checking, circuit breakers
22//! - **Static File Serving**: Compression, caching, range requests
23//! - **Validation**: JSON Schema validation for API requests/responses
24//! - **Error Handling**: Customizable error pages per service type
25//! - **Hot Reload**: Configuration changes without restarts
26//!
27//! # Example
28//!
29//! ```ignore
30//! use zentinel_proxy::{StaticFileServer, ErrorHandler, SchemaValidator};
31//! use zentinel_config::{StaticFileConfig, ServiceType};
32//!
33//! // Create a static file server
34//! let config = StaticFileConfig::default();
35//! let server = StaticFileServer::new(config);
36//!
37//! // Create an error handler for API responses
38//! let handler = ErrorHandler::new(ServiceType::Api, None);
39//! ```
40
41// ============================================================================
42// Module Declarations
43// ============================================================================
44
45pub mod acme;
46pub mod agents;
47pub mod app;
48pub mod builtin_handlers;
49pub mod cache;
50pub mod decompression;
51pub mod discovery;
52pub mod disk_cache;
53pub mod distributed_rate_limit;
54pub mod errors;
55pub mod hybrid_cache;
56pub mod memcached_rate_limit;
57
58// Kubernetes kubeconfig parsing (requires kubernetes feature)
59pub mod geo_filter;
60pub mod grpc_health;
61pub mod health;
62pub mod http_helpers;
63pub mod inference;
64#[cfg(feature = "kubernetes")]
65pub mod kubeconfig;
66pub mod logging;
67pub mod memory_cache;
68pub mod metrics;
69pub mod metrics_server;
70pub mod otel;
71pub mod proxy;
72pub mod rate_limit;
73pub mod reload;
74pub mod routing;
75pub mod scoped_circuit_breaker;
76pub mod scoped_rate_limit;
77pub mod scoped_routing;
78pub mod shadow;
79pub mod static_files;
80pub mod tls;
81pub mod tls_metrics;
82pub mod trace_id;
83pub mod upstream;
84pub mod validation;
85pub mod websocket;
86
87// Bundle management (agent installation)
88pub mod bundle;
89
90// ============================================================================
91// Public API Re-exports
92// ============================================================================
93
94// Error handling
95pub use errors::ErrorHandler;
96
97// Static file serving
98pub use static_files::{CacheStats, CachedFile, FileCache, StaticFileServer};
99
100// Request validation
101pub use validation::SchemaValidator;
102
103// Routing
104pub use routing::{RequestInfo, RouteMatch, RouteMatcher};
105pub use scoped_routing::{ScopedRouteMatch, ScopedRouteMatcher};
106
107// Upstream management
108pub use upstream::{
109    LoadBalancer, PoolConfigSnapshot, PoolStats, RequestContext, ShadowTarget, TargetSelection,
110    UpstreamPool, UpstreamTarget,
111};
112
113// Health checking
114pub use health::{ActiveHealthChecker, PassiveHealthChecker, TargetHealthInfo};
115
116// Agents
117pub use agents::{AgentAction, AgentCallContext, AgentDecision, AgentManager};
118
119// Hot reload
120pub use reload::{ConfigManager, ReloadEvent, ReloadTrigger, SignalManager, SignalType};
121
122// Application state
123pub use app::AppState;
124
125// Proxy core
126pub use proxy::ZentinelProxy;
127
128// Built-in handlers
129pub use builtin_handlers::{
130    execute_handler, BuiltinHandlerState, CachePurgeRequest, TargetHealthStatus, TargetStatus,
131    UpstreamHealthSnapshot, UpstreamStatus,
132};
133
134// HTTP helpers
135pub use http_helpers::{
136    extract_request_info, get_or_create_trace_id, write_error, write_json_error, write_response,
137    write_text_error, OwnedRequestInfo,
138};
139
140// Trace ID generation (TinyFlake)
141pub use trace_id::{
142    generate_for_format, generate_tinyflake, generate_uuid, TraceIdFormat, TINYFLAKE_LENGTH,
143};
144
145// OpenTelemetry tracing
146pub use otel::{
147    create_traceparent, generate_span_id, generate_trace_id, get_tracer, init_tracer,
148    shutdown_tracer, OtelError, OtelTracer, RequestSpan, TraceContext, TRACEPARENT_HEADER,
149    TRACESTATE_HEADER,
150};
151
152// TLS / SNI support
153pub use tls::{
154    build_server_config, build_upstream_tls_config, load_client_ca, validate_tls_config,
155    validate_upstream_tls_config, CertificateReloader, HotReloadableSniResolver, OcspCacheEntry,
156    OcspStapler, SniResolver, TlsError,
157};
158
159// Logging
160pub use logging::{
161    AccessLogEntry, AccessLogFormat, AuditEventType, AuditLogEntry, ErrorLogEntry, LogManager,
162    SharedLogManager,
163};
164
165// Rate limiting
166pub use rate_limit::{
167    RateLimitConfig, RateLimitManager, RateLimitOutcome, RateLimitResult, RateLimiterPool,
168};
169
170// Scoped rate limiting
171pub use scoped_rate_limit::{ScopedRateLimitManager, ScopedRateLimitResult};
172
173// Scoped circuit breakers
174pub use scoped_circuit_breaker::{ScopedBreakerStatus, ScopedCircuitBreakerManager};
175
176// Traffic mirroring / shadowing
177pub use shadow::{buffer_request_body, clone_body_for_shadow, should_buffer_method, ShadowManager};
178
179// GeoIP filtering
180pub use geo_filter::{
181    GeoDatabaseWatcher, GeoFilterManager, GeoFilterPool, GeoFilterResult, GeoLookupError,
182};
183
184// Body decompression with ratio limits
185pub use decompression::{
186    decompress_body, decompress_body_with_stats, is_supported_encoding, parse_content_encoding,
187    DecompressionConfig, DecompressionError, DecompressionResult, DecompressionStats,
188};
189
190// Distributed rate limiting - Redis
191#[cfg(feature = "distributed-rate-limit")]
192pub use distributed_rate_limit::{
193    create_redis_rate_limiter, DistributedRateLimitStats, RedisRateLimiter,
194};
195
196// Distributed rate limiting - Memcached
197#[cfg(feature = "distributed-rate-limit-memcached")]
198pub use memcached_rate_limit::{
199    create_memcached_rate_limiter, MemcachedRateLimitStats, MemcachedRateLimiter,
200};
201
202// HTTP caching
203pub use cache::{
204    configure_cache, get_cache_eviction, get_cache_lock, get_cache_storage, init_disk_cache_state,
205    is_cache_enabled, save_disk_cache_state, CacheConfig, CacheManager, HttpCacheStats,
206};
207
208// Memory caching
209pub use memory_cache::{
210    MemoryCacheConfig, MemoryCacheManager, MemoryCacheStats, RouteMatchEntry, TypedCache,
211};
212
213// Prometheus metrics
214pub use metrics::{MetricsManager, MetricsResponse};
215
216// Service discovery
217pub use discovery::{
218    ConsulDiscovery, DiscoveryConfig, DiscoveryManager, DnsDiscovery, KubernetesDiscovery,
219};
220
221// Kubernetes kubeconfig parsing
222#[cfg(feature = "kubernetes")]
223pub use kubeconfig::{KubeAuth, Kubeconfig, KubeconfigError, ResolvedKubeConfig};
224
225// Re-export common error types for convenience
226pub use zentinel_common::errors::{LimitType, ZentinelError, ZentinelResult};
zentinel_proxy/lib.rs

zentinel_proxy/
lib.rs
