zenith-foundation 0.1.0

//! Zenith Core - 核心基础设施、所有权、通用组件
//!
//! 本 crate 实现 Zenith 框架的核心基础设施，包括：
//! - 统一错误类型与错误处理规范
//! - 所有权令牌（FrameToken）
//! - Frame 池管理
//! - 分层资源账本
//! - 基础工具：恒定时间比较、配置系统、时间戳
//!
//! # unsafe 边界声明
//!
//! 本 crate 顶层 `#![deny(unsafe_code)]`，全 crate 零 `unsafe`。
//! （原 `buffer` 模块的 SPSC `RingBuffer` 例外已随死代码删除一并移除，
//! AGENT.md §1.1 例外条款同步更新。）

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

pub mod backoff;
pub mod error;
pub mod token;
pub mod frame;
pub mod ledger;
pub mod config;
pub mod ct_compare;
pub mod huffman;
pub mod prefix_int;
pub mod random;
pub mod varint;
pub mod sync;
pub mod net;

pub use backoff::{exponential_backoff, exponential_backoff_with_jitter};
pub use config::{
    CacheConfig, ConfigError, ObservabilityConfig, RuntimeConfig as RuntimeCfg,
    SecurityConfig, ServerConfig, ZenithConfig,
};
pub use ct_compare::{
    constant_time_all_pass, constant_time_contains, constant_time_contains_case_insensitive,
    constant_time_eq, constant_time_eq_ascii_lower, constant_time_eq_case_insensitive,
    constant_time_eq_u32, constant_time_eq_u64, constant_time_eq_u128, constant_time_starts_with,
};
pub use error::{CoreError, CoreResult};
pub use frame::{FrameId, FramePool, FrameState, FrameInfo};
pub use huffman::{HuffmanDecodeError, HuffmanDecoder, HuffmanEncoder, HUFFMAN_TABLE};
pub use ledger::{ResourceLedger, LedgerQuota, LedgerType, ResourceType};
pub use random::{
    pseudo_random_bounded, pseudo_random_u64, random_u64, try_fill_random, try_random_u64,
    Splitmix64,
};
pub use varint::{encode_varint, encode_varint_buf, parse_varint, MAX_VARINT_SIZE, MAX_VARINT_VALUE};
pub use prefix_int::{decode_prefix_integer, encode_prefix_integer};
pub use sync::{lock_recover, read_recover, write_recover};
pub use token::FrameToken;

/// 获取当前 Unix 时间戳（毫秒）
///
/// # 时钟回拨防护（fail-closed）
/// 当系统时钟回拨到 Unix Epoch 之前（`SystemTime::now() < UNIX_EPOCH`）时，
/// 饱和返回 0，禁止 panic 或返回错误值。
#[inline]
pub fn current_time_ms() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
}

/// 字节切片 → 小写 hex 字符串（无依赖，逐字节 `{:02x}`）
///
/// 统一 workspace 内三处手写 hex 编码（zenith-ebpf/zenith-net/zenith-tls），
/// 避免重复实现与格式分歧。
pub fn hex_encode(bytes: &[u8]) -> String {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut s = String::with_capacity(bytes.len() * 2);
    for &b in bytes {
        s.push(HEX[(b >> 4) as usize] as char);
        s.push(HEX[(b & 0xf) as usize] as char);
    }
    s
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_current_time_ms_reasonable() {
        // 当前时间必然大于 2020-01-01（1577836800000 ms）
        let now = current_time_ms();
        assert!(now > 1_577_836_800_000, "current_time_ms 应返回合理的 Unix 毫秒时间戳");
    }

    #[test]
    fn test_current_time_ms_monotonic_enough() {
        // 连续两次调用，第二次不得小于第一次太多（允许时钟微小回拨，但不允许数量级错误）
        let t1 = current_time_ms();
        let t2 = current_time_ms();
        assert!(t2 + 1000 >= t1, "连续调用的时间戳不应出现数量级回拨");
    }
}