zenith_foundation/
lib.rs

1//! Zenith Core - 核心基础设施、所有权、通用组件
2//!
3//! 本 crate 实现 Zenith 框架的核心基础设施，包括：
4//! - 统一错误类型与错误处理规范
5//! - 所有权令牌（FrameToken）
6//! - Frame 池管理
7//! - 分层资源账本
8//! - 基础工具：恒定时间比较、配置系统、时间戳
9//!
10//! # unsafe 边界声明
11//!
12//! 本 crate 顶层 `#![deny(unsafe_code)]`，全 crate 零 `unsafe`。
13//! （原 `buffer` 模块的 SPSC `RingBuffer` 例外已随死代码删除一并移除，
14//! AGENT.md §1.1 例外条款同步更新。）
15
16#![deny(unsafe_code)]
17#![deny(missing_debug_implementations)]
18#![warn(missing_docs)]
19
20pub mod backoff;
21pub mod error;
22pub mod token;
23pub mod frame;
24pub mod ledger;
25pub mod config;
26pub mod ct_compare;
27pub mod huffman;
28pub mod prefix_int;
29pub mod random;
30pub mod varint;
31pub mod sync;
32pub mod net;
33
34pub use backoff::{exponential_backoff, exponential_backoff_with_jitter};
35pub use config::{
36    CacheConfig, ConfigError, ObservabilityConfig, RuntimeConfig as RuntimeCfg,
37    SecurityConfig, ServerConfig, ZenithConfig,
38};
39pub use ct_compare::{
40    constant_time_all_pass, constant_time_contains, constant_time_contains_case_insensitive,
41    constant_time_eq, constant_time_eq_ascii_lower, constant_time_eq_case_insensitive,
42    constant_time_eq_u32, constant_time_eq_u64, constant_time_eq_u128, constant_time_starts_with,
43};
44pub use error::{CoreError, CoreResult};
45pub use frame::{FrameId, FramePool, FrameState, FrameInfo};
46pub use huffman::{HuffmanDecodeError, HuffmanDecoder, HuffmanEncoder, HUFFMAN_TABLE};
47pub use ledger::{ResourceLedger, LedgerQuota, LedgerType, ResourceType};
48pub use random::{
49    pseudo_random_bounded, pseudo_random_u64, random_u64, try_fill_random, try_random_u64,
50    Splitmix64,
51};
52pub use varint::{encode_varint, encode_varint_buf, parse_varint, MAX_VARINT_SIZE, MAX_VARINT_VALUE};
53pub use prefix_int::{decode_prefix_integer, encode_prefix_integer};
54pub use sync::{lock_recover, read_recover, write_recover};
55pub use token::FrameToken;
56
57/// 获取当前 Unix 时间戳（毫秒）
58///
59/// # 时钟回拨防护（fail-closed）
60/// 当系统时钟回拨到 Unix Epoch 之前（`SystemTime::now() < UNIX_EPOCH`）时，
61/// 饱和返回 0，禁止 panic 或返回错误值。
62#[inline]
63pub fn current_time_ms() -> u64 {
64    std::time::SystemTime::now()
65        .duration_since(std::time::UNIX_EPOCH)
66        .map(|d| d.as_millis() as u64)
67        .unwrap_or(0)
68}
69
70/// 字节切片 → 小写 hex 字符串（无依赖，逐字节 `{:02x}`）
71///
72/// 统一 workspace 内三处手写 hex 编码（zenith-ebpf/zenith-net/zenith-tls），
73/// 避免重复实现与格式分歧。
74pub fn hex_encode(bytes: &[u8]) -> String {
75    const HEX: &[u8; 16] = b"0123456789abcdef";
76    let mut s = String::with_capacity(bytes.len() * 2);
77    for &b in bytes {
78        s.push(HEX[(b >> 4) as usize] as char);
79        s.push(HEX[(b & 0xf) as usize] as char);
80    }
81    s
82}
83
84#[cfg(test)]
85mod tests {
86    use super::*;
87
88    #[test]
89    fn test_current_time_ms_reasonable() {
90        // 当前时间必然大于 2020-01-01（1577836800000 ms）
91        let now = current_time_ms();
92        assert!(now > 1_577_836_800_000, "current_time_ms 应返回合理的 Unix 毫秒时间戳");
93    }
94
95    #[test]
96    fn test_current_time_ms_monotonic_enough() {
97        // 连续两次调用，第二次不得小于第一次太多（允许时钟微小回拨，但不允许数量级错误）
98        let t1 = current_time_ms();
99        let t2 = current_time_ms();
100        assert!(t2 + 1000 >= t1, "连续调用的时间戳不应出现数量级回拨");
101    }
102}
zenith_foundation/lib.rs

zenith_foundation/
lib.rs
