Adding `rat_engine` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add rat_engine

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

rat_engine = "1.2.0"

The rat_engine library will be automatically available globally. Read the rat_engine library documentation.

Back to the crate overview.

Readme

RAT Engine 🚀

高性能的 Rust HTTP 服务器引擎核心库，专注于提供高效的异步网络处理和系统优化功能。

📄 许可证

本项目采用 GNU Lesser General Public License v3.0 (LGPL-3.0) 许可证。

LGPL-3.0 要点

库使用: 您可以自由地将此库链接到您的项目中，无论是开源还是商业项目
修改分享: 如果您修改了库的源代码，您需要公开这些修改
动态链接: 允许与专有软件进行动态链接，不会污染您的专有代码
静态链接: 如果进行静态链接，需要提供目标文件以便用户可以重新链接修改后的版本
专利授权: 提供明确的专利授权保护

完整许可证

请查看 LICENSE 文件获取完整的许可证条款和条件。

特性 ✨

🚀 高性能: 基于 Tokio 和 Hyper 的异步架构
🔧 硬件自适应: 自动检测 CPU 核心数并优化线程配置
🛣️ 灵活路由: 支持 HTTP 方法和路径的精确匹配，自动路径参数提取
🔄 HEAD 回退: 自动将 HEAD 请求回退到 GET 处理器（可配置白名单）
📡 SSE 支持: 全局 Server-Sent Events 管理器，支持实时通信和连接管理
📊 内置监控: 请求日志、性能指标、健康检查
⚡ 工作窃取: 高效的任务调度和负载均衡算法
🧠 内存池: 智能内存管理，减少分配开销
⚙️ 配置管理: 支持 TOML/JSON 配置文件和环境变量
🎨 结构化日志: 彩色输出、emoji 支持、多级别日志
🧪 全面测试: 单元测试、集成测试、性能测试
🐍 Python 绑定: 通过 PyO3 提供 Python 接口

快速开始 🏃‍♂️

安装

Windows 环境编译 ⚠️

本项目支持两种编译模式，针对不同的使用场景优化：

开发模式（快速编译，使用预编译OpenSSL）：

# 开发环境快速编译（约2-3分钟）
cargo build
cargo run

生产模式（静态编译，无依赖问题）：

# 设置环境变量（重要！）
export CFLAGS="-O2 -fPIC"
export CXXFLAGS="-O2 -fPIC"

# 静态编译（约25-30分钟，首次编译需要下载和编译OpenSSL源码）
cargo build --release --features static-openssl

Windows 环境注意事项：

推荐使用 MSYS2 + MinGW64 环境
首次静态编译需要较长时间（25-30分钟），请耐心等待
编译超时建议设置为 40 分钟以上
静态编译后的可执行文件无外部依赖，便于分发

🔧 Windows MSYS2 + MinGW64 环境搭建指南

第1步：安装 MSYS2

访问 MSYS2 官网
下载适合您系统的安装程序（64位推荐）
运行安装程序，选择安装路径（建议使用默认路径 C:\msys64）
完成安装后，启动 "MSYS2 MINGW64" 终端

第2步：更新软件包 在 MSYS2 MINGW64 终端中执行：

# 更新软件包数据库和基础包
pacman -Syu

# 如果提示重启终端，请关闭并重新打开终端，然后继续更新
pacman -Su

第3步：安装必要的编译工具

# 安装 MinGW-w64 工具链
pacman -S --needed base-devel mingw-w64-x86_64-toolchain

# 安装 Git
pacman -S git

# 安装 OpenSSL 开发包（用于静态编译）
pacman -S mingw-w64-x86_64-openssl

第4步：安装 Rust

# 通过 rustup 安装 Rust（推荐）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 或者使用 pacman 安装
pacman -S mingw-w64-x86_64-rust

第5步：验证环境

# 检查编译器
gcc --version
g++ --version

# 检查 Rust
rustc --version
cargo --version

# 检查 Git
git --version

第6步：配置环境变量 在项目构建前设置编译标志：

# 设置兼容的编译标志（重要！）
export CFLAGS="-O2 -fPIC"
export CXXFLAGS="-O2 -fPIC"

故障排除：

如果遇到权限问题，请以管理员身份运行 MSYS2 终端
如果网络连接有问题，可以尝试更换镜像源
如果编译失败，确保所有软件包都是最新版本

常用命令：

# 清理编译缓存
cargo clean

# 查看安装的软件包
pacman -Qs mingw-w64

# 搜索可用软件包
pacman -Ss 搜索关键词

Linux/macOS 环境

# 开发编译
cargo build

# 生产编译（推荐，避免依赖问题）
export CFLAGS="-O2 -fPIC"
export CXXFLAGS="-O2 -fPIC"
cargo build --release --features static-openssl

基本使用

使用构建器模式（唯一推荐方式）

use rat_engine::{RatEngine, Router, Method, Response, StatusCode, Full, Bytes};
use rat_engine::server::http_request::HttpRequest;
use std::sync::Arc;
use std::pin::Pin;
use std::future::Future;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建路由器并添加路由
    let mut router = Router::new();

    // 添加 Hello World 路由
    router.add_route(Method::GET, "/hello", |_req: HttpRequest| {
        Box::pin(async {
            Ok(Response::builder()
                .status(StatusCode::OK)
                .header("Content-Type", "application/json")
                .body(Full::new(Bytes::from(r#"{"message":"Hello, World!"}"#)))
                .unwrap())
        })
    });

    // 使用构建器创建引擎（唯一正确的入口）
    let engine = RatEngine::builder()
        .worker_threads(4)
        .router(router)
        .build()?;

    // 启动服务器
    engine.start("127.0.0.1".to_string(), 8080).await?;

    Ok(())
}

重要说明: RatEngine 结构体本身是一个空实现，所有功能必须通过 RatEngine::builder() 创建构建器来访问。

HEAD 请求自动回退机制

RAT Engine 支持 HEAD 请求自动回退到 GET 处理器 的功能，这是 HTTP/1.1 规范的最佳实践：

功能特点

自动回退: 当没有显式定义 HEAD 路由时，自动使用对应的 GET 处理器
安全控制: 可配置白名单，限制哪些路径允许 HEAD 回退
性能优化: 无需为每个 GET 路由手动添加对应的 HEAD 路由
兼容性: 显式定义的 HEAD 路由优先级高于自动回退

使用示例

use rat_engine::{RatEngine, Router, Method, Response, StatusCode, Full, Bytes};
use rat_engine::server::http_request::HttpRequest;
use std::collections::HashSet;
use std::pin::Pin;
use std::future::Future;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut router = Router::new();

    // 添加 GET 路由
    router.add_route(Method::GET, "/api/users", |_req: HttpRequest| {
        Box::pin(async {
            Ok(Response::builder()
                .status(StatusCode::OK)
                .header("Content-Type", "application/json")
                .body(Full::new(Bytes::from(r#"{"users":[]}"#)))
                .unwrap())
        })
    });

    // 配置 HEAD 回退功能
    let mut whitelist = HashSet::new();
    whitelist.insert("/api".to_string());  // 只允许 /api 路径使用 HEAD 回退

    // 启用 HEAD 回退，但限制在白名单内
    router.enable_head_fallback(true, Some(whitelist));

    let engine = RatEngine::builder()
        .router(router)
        .build()?;

    engine.start("127.0.0.1".to_string(), 8080).await?;
    Ok(())
}

测试命令

# HEAD 请求会自动回退到 GET 处理器
curl -I http://127.0.0.1:8080/api/users

# 等价于
curl -X GET http://127.0.0.1:8080/api/users

安全说明

白名单机制: 默认情况下，HEAD 回退是启用的但没有限制
建议配置: 在生产环境中，建议通过白名单明确指定允许 HEAD 回退的路径
显式路由: 如果需要特殊处理，可以显式定义 HEAD 路由，它会覆盖自动回退

📖 完整示例: examples/head_fallback_demo.rs

特性系统

项目使用Cargo特性进行功能模块化：

默认特性

tls: TLS/SSL支持（默认启用），支持HTTP/2和gRPC

客户端功能

client: 组合特性，包含HTTP和gRPC客户端功能
grpc-client: 仅gRPC客户端功能
reqwest: 独立HTTP客户端支持

缓存功能

cache: L1内存缓存
cache-full: L1+L2缓存（包含持久化存储）

压缩功能

compression: 基础压缩（gzip + lz4）
compression-full: 完整压缩（包含 brotli + zstd）
compression-br: 基础压缩 + Brotli
compression-zstd: 基础压缩 + Zstd

证书和安全

acme: ACME自动证书申请
static-openssl: 静态编译OpenSSL（避免运行时依赖）

Python绑定

python: Python绑定支持（需要PyO3）

其他

full: 包含所有可选特性（client、cache-full、compression-full、acme）
dev: 开发环境特性（空特性组）

特性组合示例

# 启用缓存和压缩
cargo build --features cache,compression

# 启用所有功能
cargo build --features full

# Python绑定开发
cargo build --features python

# 静态编译（避免运行时依赖）
cargo build --release --features static-openssl

路径参数支持

RAT Engine 支持强大的路径参数自动提取功能，支持多种参数类型：

整数: <id> 或 <int:id> - 默认为整数类型
字符串: <str:id>, <string:id>, <uuid:id> - 支持 UUID 等字符串
浮点数: <float:price> - 支持小数
路径: <path:file_path> - 可包含斜杠的完整路径

使用便捷的 API 自动提取参数，无需手动解析：

完整示例

use rat_engine::{RatEngine, Router, Method, Response, StatusCode, Full, Bytes};
use rat_engine::server::http_request::HttpRequest;
use std::pin::Pin;
use std::future::Future;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut router = Router::new();

    // 添加带有路径参数的路由
    router.add_route(Method::GET, "/users/<id>/posts/<post_id>", |req: HttpRequest| {
        Box::pin(async move {
            // 提取路径参数
            let user_id = req.param_as_i64("id").unwrap_or(0);
            let post_id = req.param_as_i64("post_id").unwrap_or(0);

            let response_data = format!(r#"{{"user_id": {}, "post_id": {}}}"#, user_id, post_id);

            Ok(Response::builder()
                .status(StatusCode::OK)
                .header("Content-Type", "application/json")
                .body(Full::new(Bytes::from(response_data)))
                .unwrap())
        })
    });

    let engine = RatEngine::builder()
        .router(router)
        .build()?;

    engine.start("127.0.0.1".to_string(), 8080).await?;
    Ok(())
}

参数提取方法

// 在路由处理器内部使用这些方法
let user_id = req.param_as_i64("id").unwrap_or(0);          // 获取整数参数
let user_uuid = req.param("uuid").unwrap_or("default");     // 获取字符串参数
let price = req.param_as_f64("price").unwrap_or(0.0);       // 获取浮点参数
let file_path = req.param("file_path").unwrap_or("");       // 获取路径参数

📖 完整示例请查看:

examples/dynamic_routes_demo.rs - 基础路径参数示例
examples/advanced_path_params_demo.rs - 高级参数类型演示
examples/streaming_demo.rs - 流式响应和全局SSE管理器演示
examples/streaming_response_test.rs - 流式响应功能测试，验证HTTP状态码、JSON响应、SSE参数验证
examples/sse_chat/ - 完整的多房间SSE聊天室示例，展示实时通信应用

运行示例

项目提供了多个功能示例：

# 运行构建器模式示例
cargo run --example builder_pattern_example

# 运行流式处理示例
cargo run --example streaming_demo

# 运行流式响应测试示例（验证HTTP状态码和SSE参数验证）
cargo run --example streaming_response_test

# 运行 SSE 聊天室示例
cargo run --example sse_chat

# 运行 gRPC 综合示例
cargo run --example grpc_comprehensive_example

# 运行缓存性能测试
cargo run --example cache_compression_performance_test

# 运行 gRPC 客户端示例
cargo run --example grpc_client_bidirectional_example

# 运行 ACME 证书管理示例
cargo run --example acme_sandbox_demo

# 运行 HEAD 回退功能演示
cargo run --example head_fallback_demo

# 运行动态路由示例（需要 reqwest 特性）
cargo run --example dynamic_routes_demo --features reqwest

# 运行高级路径参数示例（需要 reqwest 特性）
cargo run --example advanced_path_params_demo --features reqwest

核心模块 🏗️

引擎模块 (Engine)

内存池: 高效的内存分配和回收机制
工作窃取: 智能任务调度算法，最大化 CPU 利用率
指标收集: 实时性能监控和统计
拥塞控制: 网络流量控制算法
智能传输: 数据传输优化

服务器模块 (Server)

配置管理: 灵活的服务器配置选项
性能优化: 自动硬件检测和优化
路由系统: 高效的 HTTP 路由匹配
流式处理: 支持分块传输、SSE 和 JSON 流式响应
缓存中间件: 多版本缓存系统
压缩中间件: 内容压缩支持
证书管理: TLS/MTLS 证书管理
gRPC 支持: gRPC 协议处理

客户端模块 (Client)

gRPC 客户端: 高性能 gRPC 客户端，支持双向流和连接池
独立HTTP客户端: 基于 reqwest 的高性能 HTTP 客户端（需要 reqwest 特性）
连接池: gRPC 连接复用管理
下载管理: gRPC 断点续传和元数据管理

Python API 模块

Python 绑定: 通过 PyO3 提供 Python 接口
Flask 风格 API: 熟悉的 Web 框架接口
异步支持: 完整的 async/await 支持

项目结构 📁

src/
├── lib.rs              # 库入口
├── error.rs            # 错误处理
├── error_i18n.rs       # 多语言错误信息
├── cache/              # 缓存模块
│   ├── mod.rs
│   └── builder.rs      # 缓存构建器
├── compression/        # 压缩模块
│   ├── mod.rs
│   ├── compressor.rs   # 压缩器实现
│   ├── config.rs       # 压缩配置
│   ├── types.rs        # 压缩类型
│   └── utils.rs        # 压缩工具
├── engine/             # 核心引擎模块
│   ├── mod.rs         # RatEngine 空实现，通过 builder 访问
│   ├── memory.rs       # 内存池管理
│   ├── work_stealing.rs # 工作窃取算法
│   ├── metrics.rs      # 性能指标收集
│   ├── congestion_control.rs # 拥塞控制
│   ├── smart_transfer.rs # 智能传输
│   └── network.rs      # 网络处理
├── server/             # 服务器核心
│   ├── mod.rs
│   ├── config.rs       # 服务器配置
│   ├── router.rs       # 路由系统
│   ├── cache_middleware.rs # 缓存中间件
│   ├── cache_version_manager.rs # 缓存版本管理
│   ├── cert_manager/   # 证书管理模块
│   ├── grpc_handler/   # gRPC 处理模块
│   ├── streaming.rs    # 流式处理
│   └── performance.rs  # 性能管理
├── client/             # 客户端模块
│   ├── mod.rs
│   ├── grpc_client/    # gRPC 客户端目录
│   ├── grpc_builder.rs # gRPC 客户端构建器
│   ├── independent_http_client.rs # 独立HTTP客户端（基于reqwest）
│   ├── connection_pool.rs # 连接池管理
│   ├── download_metadata.rs # 下载元数据管理
│   └── types.rs        # 客户端类型定义
├── python_api/         # Python 绑定
│   ├── mod.rs
│   ├── server.rs       # Python 服务器接口
│   ├── client.rs       # Python 客户端接口
│   ├── engine_builder.rs # Python 引擎构建器
│   ├── handlers.rs     # Python 处理器
│   ├── compression.rs  # Python 压缩接口
│   ├── cert_manager.rs # Python 证书管理
│   ├── streaming.rs    # Python 流式处理
│   ├── codec.rs        # 编解码器
│   ├── response_converter.rs # 响应转换器
│   ├── grpc_queue_bridge.rs # gRPC 队列桥接
│   ├── http_queue_bridge.rs # HTTP 队列桥接
│   ├── smart_transfer.rs # Python 智能传输
│   ├── congestion_control.rs # Python 拥塞控制
│   └── http/          # Python HTTP 模块
│       ├── mod.rs
│       ├── core.rs
│       ├── request.rs
│       ├── response.rs
│       └── http_converter.rs
├── utils/              # 工具模块
│   ├── mod.rs
│   ├── logger.rs       # 日志系统
│   ├── sys_info.rs     # 系统信息
│   ├── ip_extractor.rs # IP 提取
│   ├── crypto_provider.rs # 加密提供者
│   └── feature_check.rs # 特性检查
└── common/             # 公共模块
    ├── mod.rs
    └── path_params.rs  # 路径参数处理

examples/              # 示例文件
├── 基础示例
│   ├── builder_pattern_example.rs # 构建器模式示例
│   ├── streaming_demo.rs   # 流式处理示例
│   ├── streaming_response_test.rs # 流式响应功能测试示例
│   └── head_fallback_demo.rs # HEAD 请求回退演示
├── gRPC 示例
│   ├── grpc_comprehensive_example.rs # gRPC 综合示例
│   ├── grpc_client_bidirectional_example.rs # 双向流gRPC客户端
│   ├── grpc_client_bidirectional_tls_example.rs # TLS双向流gRPC
│   ├── grpc_client_bidirectional_mtls_example.rs # MTLS双向流gRPC
│   └── grpc_resumable_download.rs # gRPC断点续传下载
├── 路由和参数
│   ├── dynamic_routes_demo.rs # 动态路由示例（需要 reqwest 特性）
│   ├── advanced_path_params_demo.rs # 高级路径参数示例（需要 reqwest 特性）
│   └── route_conflict_demo.rs # 路由冲突解决演示
├── 缓存和性能
│   ├── cache_compression_performance_test.rs # 缓存性能测试
│   ├── router_high_speed_cache_example.rs # 路由器高速缓存演示
│   ├── test_direct_l1_cache.rs # L1缓存测试
│   └── test_direct_l2_cache.rs # L2缓存测试
├── 中间件和协议
│   ├── cors_example.rs # CORS跨域资源共享演示
│   ├── https_redirect.rs # HTTPS重定向演示
│   └── simple_protocol_detection.rs # 协议检测演示
├── 证书和安全
│   ├── acme_sandbox_demo.rs # ACME证书自动签发演示
│   └── chunked_upload_demo.rs # 分块上传演示
├── 开发和测试
│   ├── sse_chat/ # SSE聊天室示例
│   │   ├── main.rs
│   │   ├── login.html
│   │   └── chat.html
│   ├── logging_example.rs # 日志系统使用演示
│   ├── independent_http_client_test.rs # 独立HTTP客户端测试
│   └── test_cache_version_manager.rs # 缓存版本管理测试

开发指南 🛠️

运行测试

# 运行所有测试
cargo test

# 运行库测试
cargo test --lib

# 运行集成测试
cargo test integration_tests

# 显示测试输出
cargo test -- --nocapture

# 运行特定模块测试
cargo test engine::memory
cargo test engine::work_stealing
cargo test server::router

代码规范

使用 cargo fmt 格式化代码
使用 cargo clippy 检查代码质量
添加适当的文档注释
确保所有测试通过

性能指标 📈

⚠️ 注意: 以下性能数据基于 MacBook Air M1 芯片组测试获得，仅供参考。实际性能会根据硬件配置、网络环境和使用场景有所差异。

测试环境

设备: MacBook Air M1
芯片: Apple M1 (8核CPU，8核GPU)
内存: 16GB 统一内存
操作系统: macOS

性能数据

吞吐量: ~50,000 RPS（基于MacBook Air M1测试）
延迟: < 1ms (P99)
内存使用: ~50MB（基础配置）
CPU 使用: 自适应负载均衡

⚠️ 重要说明: 这些性能数据仅供参考，基于特定硬件和测试环境。实际性能会因以下因素而异：

硬件配置（CPU、内存、存储）
网络环境（延迟、带宽）
请求类型和负载模式
并发连接数
业务逻辑复杂度

版本信息

当前版本: 1.2.0
支持Rust版本: 2024 Edition
许可证: LGPL-3.0
维护状态: 活跃开发中

贡献指南

欢迎提交Issue和Pull Request！

开发流程

Fork本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建Pull Request

代码规范

遵循Rust官方代码规范
使用 cargo fmt 格式化代码
使用 cargo clippy 检查代码质量
添加适当的文档注释
确保所有测试通过

许可证

本项目采用 LGPL-3.0 许可证。

致谢

感谢所有为这个项目做出贡献的开发者！

Adding rat_engine library as a dependency

Adding `rat_engine` library as a dependency