kairos_rs/lib.rs
1//! # Kairos-rs API Gateway
2//!
3//! A high-performance, async HTTP API gateway built with Rust and Actix Web.
4//! Kairos-rs provides intelligent request routing, rate limiting, security features,
5//! and efficient upstream service communication for modern microservice architectures.
6//!
7//! ## Quick Start
8//!
9//! ```rust
10//! use kairos_rs::{
11//! config::settings::load_settings,
12//! services::http::RouteHandler,
13//! models::router::Router,
14//! };
15//!
16//! #[tokio::main]
17//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
18//! # use std::fs;
19//! # // Create a temporary config file for testing
20//! # let config_content = r#"{"version": 1, "routers": []}"#;
21//! # fs::write("./config.json", config_content).unwrap();
22//!
23//! // Load configuration
24//! let config = load_settings()?;
25//! config.validate()?;
26//!
27//! // Create route handler
28//! let handler = RouteHandler::new(config.routers, 30);
29//!
30//! // Handler is now ready to process requests
31//! # // Clean up
32//! # fs::remove_file("./config.json").ok();
33//! Ok(())
34//! }
35//! ```
36//!
37//! ## Core Features
38//!
39//! ### High-Performance Routing
40//! - **Static Routes**: O(1) hash map lookup for exact path matches
41//! - **Dynamic Routes**: Compiled regex patterns with parameter extraction
42//! - **Method Validation**: Configurable HTTP method restrictions per route
43//! - **Path Transformation**: Flexible mapping from external to internal paths
44//!
45//! ### Security & Reliability
46//! - **Rate Limiting**: Built-in rate limiting with configurable thresholds
47//! - **Security Headers**: Comprehensive security header middleware
48//! - **Request Timeout**: Configurable upstream request timeouts
49//! - **Input Validation**: Comprehensive configuration and request validation
50//!
51//! ### Observability
52//! - **Structured Logging**: Detailed request/response logging with timestamps
53//! - **Health Endpoints**: Kubernetes-compatible health, readiness, and liveness checks
54//! - **Error Tracking**: Structured error responses with unique request IDs
55//! - **Performance Metrics**: Built-in request timing and throughput monitoring
56//!
57//! ## Architecture Overview
58//!
59//! ```text
60//! ┌─────────────┐ ┌─────────────────┐ ┌──────────────────┐
61//! │ Client │──▶│ Kairos-rs │──▶│ Upstream │
62//! │ (Browser, │ │ Gateway │ │ Services │
63//! │ Mobile, │ │ │ │ (Microservices, │
64//! │ API) │ │ ┌──────────────┤ │ APIs, etc.) │
65//! └─────────────┘ │ │ Rate Limiter ││ └──────────────────┘
66//! │ ├──────────────┤│
67//! │ │ Route Matcher││
68//! │ ├──────────────┤│
69//! │ │ Load Balancer││
70//! │ ├──────────────┤│
71//! │ │ Circuit Break││
72//! │ └──────────────┘│
73//! └─────────────────┘
74//! ```
75//!
76//! ## Module Organization
77//!
78//! - **[`config`]** - Configuration management and file loading
79//! - **[`models`]** - Data models, domain types, and validation logic
80//! - **[`services`]** - Business logic and upstream service communication
81//! - **[`routes`]** - HTTP route definitions and handlers
82//! - **[`middleware`]** - Security, logging, and request processing middleware
83//! - **[`utils`]** - Utility functions and helper modules
84//! - **[`logs`]** - Logging configuration and structured output
85//!
86//! ## Configuration Example
87//!
88//! ```json
89//! {
90//! "version": 1,
91//! "routers": [
92//! {
93//! "host": "http://auth-service",
94//! "port": 8080,
95//! "external_path": "/auth/login",
96//! "internal_path": "/api/v1/authenticate",
97//! "methods": ["POST"]
98//! },
99//! {
100//! "host": "http://user-service",
101//! "port": 8080,
102//! "external_path": "/users/{id}",
103//! "internal_path": "/api/v1/user/{id}",
104//! "methods": ["GET", "PUT", "DELETE"]
105//! },
106//! {
107//! "host": "http://content-service",
108//! "port": 8080,
109//! "external_path": "/users/{user_id}/posts/{post_id}",
110//! "internal_path": "/api/v1/post/{post_id}?user={user_id}",
111//! "methods": ["GET", "PUT", "DELETE"]
112//! }
113//! ]
114//! }
115//! ```
116//!
117//! ## Environment Variables
118//!
119//! - `KAIROS_CONFIG_PATH`: Configuration file path (default: `./config.json`)
120//! - `KAIROS_HOST`: Server bind address (default: `0.0.0.0`)
121//! - `KAIROS_PORT`: Server port (default: `5900`)
122//! - `NO_COLOR`: Disable colored log output
123//!
124//! ## Performance Characteristics
125//!
126//! - **Throughput**: 50,000+ requests/second on modern hardware
127//! - **Latency**: Sub-millisecond routing overhead
128//! - **Memory**: Efficient memory usage with connection pooling
129//! - **Concurrency**: Full async/await support with Tokio runtime
130//!
131//! ## Use Cases
132//!
133//! - **API Gateway**: Central entry point for microservice architectures
134//! - **Reverse Proxy**: Load balancing and request forwarding
135//! - **Path Transformation**: Mapping legacy URLs to modern APIs
136//! - **Rate Limiting**: Protecting backend services from overload
137//! - **Security Layer**: Adding security headers and request validation
138
139pub mod config;
140pub mod logs;
141pub mod middleware;
142pub mod models;
143pub mod routes;
144pub mod services;
145pub mod utils;