zenith_stack/

lib.rs

//! # Zenith — 全协议栈高性能网络框架
//!
//! Zenith 是一个面向极端性能场景的全协议栈网络框架，集成：
//! - **AF_XDP + eBPF**：零拷贝数据面、bpf_link 原子挂载、双 Bank 热更新
//! - **TLS 1.3**：rustls 集成、证书代际管理、SNI/ALPN 路由
//! - **HTTP/1.1 / HTTP/2 / HTTP/3**：RFC 7230 / 7540 / 9114 全协议实现
//! - **Web 框架**：编译期 Trie 路由、类型化 Extractor、中间件 DAG
//! - **Proxy / Cache / WAF / Forward**：反向代理、缓存、Web 应用防火墙、L4 转发
//! - **Runtime**：三级 Supervisor、ChangeSet 热切换、RuntimeGraph 拓扑规划
//!
//! ## 按需导入
//!
//! Zenith 采用 **feature-gated facade** 设计，默认仅启用最小核心（`api` + `core`），
//! 其余能力按需开启，避免拖入不必要的重依赖（如 `libbpf-rs`、`rustls`、`ring`）。
//!
//! ### 最小依赖（仅类型定义）
//!
//! ```toml
//! [dependencies]
//! zenith = { path = "...", default-features = false, features = ["api"] }
//! ```
//!
//! ### 仅 Web 框架（不拖入 AF_XDP / eBPF）
//!
//! ```toml
//! [dependencies]
//! zenith = { path = "...", default-features = false, features = ["web"] }
//! ```
//!
//! ### 仅 HTTP 协议解析（无 Linux 数据面）
//!
//! ```toml
//! [dependencies]
//! zenith = { path = "...", default-features = false, features = ["http"] }
//! ```
//!
//! ### 完整生产协议栈
//!
//! ```toml
//! [dependencies]
//! zenith = { path = "...", features = ["full-stack"] }
//! ```
//!
//! ### 全部能力（含测试工具）
//!
//! ```toml
//! [dependencies]
//! zenith = { path = "...", features = ["full"] }
//! ```
//!
//! ## Feature 矩阵
//!
//! | Feature | 启用能力 | 拉入重依赖 |
//! |---|---|---|
//! | `api` | 公共类型定义（CanonicalRequest/Response 等） | 无 |
//! | `core` | 核心基础设施（FramePool/Ledger/时间轮） | `thiserror` |
//! | `net` | L2-L4 协议解析、TCP/UDP/QUIC 状态机 | 无（`linux` 默认关闭） |
//! | `linux` | AF_XDP Socket、UMEM、四环操作 | `libbpf-rs`、`libc` |
//! | `ebpf` | eBPF 程序加载、双 Bank 热更新 | `libbpf-rs`、`libc`、`nix`（经 `libbpf-sys`） |
//! | `tls` | TLS 1.3 引擎、证书代际管理 | `rustls`、`ring` |
//! | `http1` / `http2` / `http3` | HTTP 协议解析器 | 依赖 `net` |
//! | `web` | 最小 Web 框架（路由/中间件/静态文件/H1-H2-H3/TLS/WAF/缓存/代理）；不含 runtime/linux/ebpf（实测不拖入 libbpf/io_uring/tokio）；启用 `runtime` 特性自动升级为 full（AF_XDP 桥 + Supervisor + ChangeSet + WAF 卸载闭环） | `serde`、`serde_json`、`rustls` |
//! | `proxy` | 反向代理、负载均衡、熔断器 | 无 |
//! | `cache` | HTTP 缓存层 | 无 |
//! | `waf` | Web 应用防火墙 | 无 |
//! | `forward` | L4 转发 | 无 |
//! | `runtime` | 全链路数据面运行时 | 依赖 `net` + `linux` + `ebpf` |
//! | `capability` | 硬件/内核能力检测 | 无 |
//! | `observability` | 指标、tracing、健康检查 | 无 |
//! | `testkit` | 测试工具、Demo、压力测试 | 依赖 `full` |
//! | `http` | 组合：http1 + http2 + http3 | — |
//! | `full-stack` | 组合：完整生产协议栈 | — |
//! | `full` | 组合：全部能力 | — |
//!
//! # 设计原则
//! - 热路径零堆分配（固定容量数组替代 String/Vec）
//! - 单线程本地存储、无锁访问
//! - 编译期路由注册、运行期零开销分发
//! - 所有 unsafe 封装在 `zenith-linux` 内部，上层零 unsafe

#![deny(unsafe_code)]
#![deny(missing_debug_implementations)]
#![warn(missing_docs)]

// ─────────────────────────────────────────────────────────────────────────────
// 公共 API 类型（默认启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith 公共 API 与类型定义
#[cfg(feature = "api")]
pub extern crate zenith_api;

/// Zenith 公共 API 重导出
///
/// 通过 `zenith_stack::api` 可访问所有公共类型，等价于直接使用 `zenith_api` crate。
#[cfg(feature = "api")]
pub mod api {
    pub use zenith_api::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// 核心基础设施（默认启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith 核心基础设施
#[cfg(feature = "core")]
pub extern crate zenith_foundation;

/// Zenith 核心基础设施重导出
#[cfg(feature = "core")]
pub mod core {
    pub use zenith_foundation::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// 网络协议层（按需启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith 网络地址与传输层抽象
#[cfg(feature = "net")]
pub extern crate zenith_net;

/// Zenith 网络层重导出
#[cfg(feature = "net")]
pub mod net {
    pub use zenith_net::*;
}

/// Zenith Linux 平台抽象层（AF_XDP / UMEM / Ring）
#[cfg(all(feature = "linux", target_os = "linux"))]
pub extern crate zenith_linux;

/// Zenith Linux 平台重导出
#[cfg(all(feature = "linux", target_os = "linux"))]
pub mod linux {
    pub use zenith_linux::*;
}

/// Zenith eBPF 程序管理
#[cfg(all(feature = "ebpf", target_os = "linux"))]
pub extern crate zenith_ebpf;

/// Zenith eBPF 重导出
#[cfg(all(feature = "ebpf", target_os = "linux"))]
pub mod ebpf {
    pub use zenith_ebpf::*;
}

/// Zenith TLS 1.3 安全引擎
#[cfg(feature = "tls")]
pub extern crate zenith_tls;

/// Zenith TLS 重导出
#[cfg(feature = "tls")]
pub mod tls {
    pub use zenith_tls::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// HTTP 协议层（按需启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith HTTP/1.1 协议解析器
#[cfg(feature = "http1")]
pub extern crate zenith_http1;

/// Zenith HTTP/1.1 重导出
#[cfg(feature = "http1")]
pub mod http1 {
    pub use zenith_http1::*;
}

/// Zenith HTTP/2 协议实现
#[cfg(feature = "http2")]
pub extern crate zenith_http2;

/// Zenith HTTP/2 重导出
#[cfg(feature = "http2")]
pub mod http2 {
    pub use zenith_http2::*;
}

/// Zenith HTTP/3 协议实现
#[cfg(feature = "http3")]
pub extern crate zenith_http3;

/// Zenith HTTP/3 重导出
#[cfg(feature = "http3")]
pub mod http3 {
    pub use zenith_http3::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// 应用层（按需启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith Web 应用框架
#[cfg(feature = "web")]
pub extern crate zenith_web;

/// Zenith Web 框架重导出
#[cfg(feature = "web")]
pub mod web {
    pub use zenith_web::*;
}

/// Zenith 反向代理
#[cfg(feature = "proxy")]
pub extern crate zenith_proxy;

/// Zenith 代理重导出
#[cfg(feature = "proxy")]
pub mod proxy {
    pub use zenith_proxy::*;
}

/// Zenith HTTP 缓存层
#[cfg(feature = "cache")]
pub extern crate zenith_cache;

/// Zenith 缓存重导出
#[cfg(feature = "cache")]
pub mod cache {
    pub use zenith_cache::*;
}

/// Zenith Web 应用防火墙
#[cfg(feature = "waf")]
pub extern crate zenith_waf;

/// Zenith WAF 重导出
#[cfg(feature = "waf")]
pub mod waf {
    pub use zenith_waf::*;
}

/// Zenith L4 转发层
#[cfg(feature = "forward")]
pub extern crate zenith_forward;

/// Zenith 转发重导出
#[cfg(feature = "forward")]
pub mod forward {
    pub use zenith_forward::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// 运行时与治理（按需启用）
// ─────────────────────────────────────────────────────────────────────────────

/// Zenith 全链路数据面运行时
#[cfg(feature = "runtime")]
pub extern crate zenith_runtime;

/// Zenith 运行时重导出
#[cfg(feature = "runtime")]
pub mod runtime {
    pub use zenith_runtime::*;
}

/// Zenith 能力检测
#[cfg(feature = "capability")]
pub extern crate zenith_capability;

/// Zenith 能力检测重导出
#[cfg(feature = "capability")]
pub mod capability {
    pub use zenith_capability::*;
}

/// Zenith 可观测性
#[cfg(feature = "observability")]
pub extern crate zenith_observability;

/// Zenith 可观测性重导出
#[cfg(feature = "observability")]
pub mod observability {
    pub use zenith_observability::*;
}

/// Zenith 测试工具箱
#[cfg(feature = "testkit")]
pub extern crate zenith_testkit;

/// Zenith 测试工具重导出
#[cfg(feature = "testkit")]
pub mod testkit {
    pub use zenith_testkit::*;
}

/// Zenith 全链路指纹识别与阻断
#[cfg(feature = "fingerprint")]
pub extern crate zenith_fingerprint;

/// Zenith 指纹识别重导出
#[cfg(feature = "fingerprint")]
pub mod fingerprint {
    pub use zenith_fingerprint::*;
}

// ─────────────────────────────────────────────────────────────────────────────
// 全局便捷 API（启用 runtime feature 时可用）
// ─────────────────────────────────────────────────────────────────────────────

/// 全局 Tokio 异步运行时便捷函数（feature = `runtime`）
///
/// 消除跨 crate 传递 `Handle` / 每个二进制重复写 `Builder::new_multi_thread()` 的样板代码。
/// 所有函数 Fail-Closed：未初始化时自动按 `RuntimeConfig::auto()` 懒加载。
///
/// # 示例
/// ```ignore
/// use zenith_stack::{spawn, block_on};
///
/// // 无需显式构建 Runtime，任何位置都能直接 spawn
/// let task = spawn(async { 42 });
/// let result = block_on(task);
/// assert_eq!(result, Ok(42));
/// ```
#[cfg(feature = "runtime")]
pub mod rt {
    /// 显式初始化全局运行时（幂等、线程安全、可重入）。
    /// 若全局已被其他线程先初始化，本次 config 被忽略，返回已存在引用。
    pub use zenith_runtime::init_global;
    /// 获取全局运行时引用（自动懒加载）
    pub use zenith_runtime::global_runtime;
    /// 获取全局 Tokio Handle（Clone 零成本）
    pub use zenith_runtime::handle;
    /// 在全局运行时上 [`tokio::spawn`]（无需传 Handle）
    pub use zenith_runtime::spawn;
    /// 用全局运行时 `block_on` 执行 Future
    pub use zenith_runtime::block_on;
    /// 全局运行时类型
    pub use zenith_runtime::GlobalRuntime;
    /// 运行时配置（worker_threads / enable_io / enable_time / stack_size）
    pub use zenith_runtime::RuntimeConfig;
}

// ─────────────────────────────────────────────────────────────────────────────
// Prelude：常用类型一键导入
// ─────────────────────────────────────────────────────────────────────────────

/// Prelude 模块：按启用的特性提供常用类型一键导入
///
/// # 用法
///
/// ```no_run
/// use zenith_stack::prelude::*;
/// ```
pub mod prelude {
    #[cfg(feature = "api")]
    pub use zenith_api::{
        CanonicalRequest, CanonicalResponse, Method, Protocol, Transport,
    };

    #[cfg(feature = "core")]
    pub use zenith_foundation::{CoreError, CoreResult, FrameId, FramePool, FrameToken};

    #[cfg(feature = "web")]
    pub use zenith_web::{App, WebError};

    /// 启用 runtime 时，prelude 直接导出 spawn/block_on/handle 零配置使用
    #[cfg(feature = "runtime")]
    pub use zenith_runtime::{block_on, handle, spawn};
}

#[cfg(test)]
mod tests {
    // 仅验证 facade 在默认特性下可编译
    #[test]
    fn facade_compiles_with_default_features() {
        #[cfg(feature = "api")]
        let _ = zenith_api::Method::Get;

        #[cfg(feature = "core")]
        let _ = zenith_foundation::CoreError::internal("test");
    }
}