zenith-ebpf 0.1.0

//! XDP 程序加载与管理
//!
//! 使用 libbpf-rs 实现 eBPF 加载方案：
//! 1. 预编译字节码通过 include_bytes! 嵌入
//! 2. libbpf-rs 加载 ELF 对象
//! 3. bpf_link API 实现原子挂载与零丢包热切换
//!
//! # API 说明（libbpf-rs 0.24）
//! - `ProgramMut::attach_xdp(ifindex)` 创建 bpf_link 并挂载 XDP 程序
//! - `Link::update_prog()` 实现原子程序替换（零丢包热更新核心）
//! - `Link::detach()` 分离程序；`Drop` 自动调用 `bpf_link__destroy`

use crate::error::{AttachError, LoadError};
use crate::xdp_attach::{
    XdpAttachMode, attach_xdp_raw, detach_xdp_raw, get_prog_fd, unpin,
};
use libbpf_rs::{ObjectBuilder, ProgramType, Link};
use ring::digest::{Context, SHA256};
use std::path::PathBuf;
// 恒定时间比较：委托 zenith-core 统一实现（AGENT.md §4.9 时序安全）
use zenith_foundation::ct_compare::constant_time_eq;

/// 预编译的 XDP 程序字节码
///
/// 这些字节码在构建时由 clang 编译，直接嵌入到二进制文件中。
const XDP_MAIN_BYTES: &[u8] = include_bytes!("../../../bpf/prebuilt/xdp_main.o");
const XDP_REDIRECT_BYTES: &[u8] = include_bytes!("../../../bpf/prebuilt/xdp_redirect.o");
const XDP_STATS_BYTES: &[u8] = include_bytes!("../../../bpf/prebuilt/xdp_stats.o");

// 构建时自动生成的 SHA-256 期望哈希值
// 由 build.rs 在编译期生成，存放在 generated/bpf_hashes.rs
include!("generated/bpf_hashes.rs");

/// XDP 程序名称标识
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum XdpProgramName {
    /// 主程序（最小化导流）
    Main,
    /// 重定向程序（Bank A）
    Redirect,
    /// 统计程序（Bank B）
    Stats,
}

impl XdpProgramName {
    /// 获取程序名称的字符串表示
    ///
    /// 返回与枚举变体对应的静态字符串，可用于日志、调试或显示。
    ///
    /// **该字符串同时是 `EXPECTED_HASHES`（build.rs 生成的 bpf_hashes.rs）
    /// 中的查找键**，二者必须严格一致，否则完整性校验会 fail-closed。
    pub fn as_str(&self) -> &'static str {
        match self {
            XdpProgramName::Main => "xdp_main",
            XdpProgramName::Redirect => "xdp_redirect",
            XdpProgramName::Stats => "xdp_stats",
        }
    }

    fn get_bytecode(&self) -> &'static [u8] {
        match self {
            XdpProgramName::Main => XDP_MAIN_BYTES,
            XdpProgramName::Redirect => XDP_REDIRECT_BYTES,
            XdpProgramName::Stats => XDP_STATS_BYTES,
        }
    }

    /// 验证字节码完整性（SHA-256）
    ///
    /// 计算字节码的 SHA-256 哈希并与预计算期望值比较，
    /// 防止内核态代码被篡改或注入。
    ///
    /// # Returns
    /// * `Ok(())` - 完整性验证通过
    /// * `Err(LoadError::VerificationFailed)` - 哈希不匹配或未注册期望哈希
    pub fn verify_integrity(&self) -> Result<(), LoadError> {
        let bytecode = self.get_bytecode();
        if bytecode.is_empty() {
            // 空字节码仅出现在 ZENITH_ALLOW_MISSING_BPF=1 开发模式，
            // 此时 load() 会以 EmptyBytecode 拒绝，校验直接放行。
            return Ok(());
        }
        verify_bytes_hash(self.as_str(), bytecode)
    }
}

/// 校验指定字节码的 SHA-256 与 `EXPECTED_HASHES` 中注册的期望值是否一致
///
/// 独立为纯函数以便测试篡改场景（无需改动嵌入字节码）。
///
/// # Fail-Closed
/// - 哈希不匹配 → `Err`
/// - 程序键未注册期望哈希 → `Err`（禁止静默跳过校验）
fn verify_bytes_hash(prog_key: &str, bytecode: &[u8]) -> Result<(), LoadError> {
    let mut ctx = Context::new(&SHA256);
    ctx.update(bytecode);
    let digest = ctx.finish();

    let hash_str = hex_encode(digest.as_ref());

    let expected = EXPECTED_HASHES
        .iter()
        .find(|(name, _)| *name == prog_key)
        .map(|(_, hash)| *hash);

    match expected {
        Some(expected_hash) => {
            if constant_time_eq(hash_str.as_bytes(), expected_hash.as_bytes()) {
                Ok(())
            } else {
                Err(LoadError::VerificationFailed(format!(
                    "SHA-256 hash mismatch for {}: expected {}, got {}",
                    prog_key, expected_hash, hash_str
                )))
            }
        }
        None => Err(LoadError::VerificationFailed(format!(
            "no expected SHA-256 hash registered for program key '{}'",
            prog_key
        ))),
    }
}

// hex 编码：委托 zenith-core 统一实现（避免重复造轮子）
use zenith_foundation::hex_encode;

/// XDP 程序加载器
///
/// 封装 libbpf-rs 的加载逻辑，提供类型安全的接口。
/// 支持：
/// - 预编译字节码加载（零 C 重编译）
/// - bpf_link 原子挂载（零丢包热切换）
/// - BPF Map 访问
/// - **多模式 attach（HW/DRV/SKB 自动兼容切换）**
pub struct XdpLoader {
    /// 本次加载的程序标识（NET-016：用于校验 Bank 是否走 xdp_main 完整过滤链）
    program_name: XdpProgramName,
    /// libbpf 对象
    obj: libbpf_rs::Object,
    /// 当前活动的 XDP bpf_link
    /// 用于通过 `Link::update_prog()` 实现原子热替换
    active_link: Option<Link>,
    /// 多模式 attach 状态（使用 bpf_xdp_attach 时记录）
    attach_mode: Option<XdpAttachMode>,
    /// 已 attach 的网卡 ifindex（用于 detach）
    attached_ifindex: Option<i32>,
    /// 程序 fd（通过 pin 获取，用于 bpf_xdp_attach）
    prog_fd: Option<std::os::fd::OwnedFd>,
    /// pin 路径（用于 unpin 清理）
    pin_path: Option<PathBuf>,
}

impl XdpLoader {
    /// 从预编译字节码加载 XDP 程序
    ///
    /// # 参数
    /// * `name` - 程序名称
    ///
    /// # 返回
    /// * `Result<Self, LoadError>` - 加载成功的 XdpLoader 实例
    ///
    /// # 安全
    /// 加载前执行 SHA-256 完整性验证，防止字节码篡改。
    pub fn load(name: XdpProgramName) -> Result<Self, LoadError> {
        let bytecode = name.get_bytecode();

        if bytecode.is_empty() {
            return Err(LoadError::EmptyBytecode);
        }

        name.verify_integrity()?;

        let obj = ObjectBuilder::default()
            .open_memory(bytecode)
            .map_err(|e| LoadError::Libbpf(format!("Failed to open ELF: {}", e)))?
            .load()
            .map_err(|e| LoadError::Libbpf(format!("Failed to load object: {}", e)))?;

        Ok(Self {
            program_name: name,
            obj,
            active_link: None,
            attach_mode: None,
            attached_ifindex: None,
            prog_fd: None,
            pin_path: None,
        })
    }

    /// 获取本次加载的程序标识（NET-016）
    ///
    /// 用于判断该 loader 承载的是 `xdp_main`（完整 L2/L3/L4 过滤链）还是
    /// 仅最小导流的 `xdp_redirect` / `xdp_stats`。Bank 切换前必须校验活动
    /// 程序为 `xdp_main`，否则 fail-closed。
    pub fn program_name(&self) -> XdpProgramName {
        self.program_name
    }

    /// 该 loader 是否承载完整过滤链程序（`xdp_main`）
    ///
    /// `true`：活动 Bank 可安全用于生产数据面；`false`（Redirect/Stats）：
    /// 仅适用于已由上游完成准入的诊断场景，Bank 切换应 fail-closed 拒绝。
    #[inline]
    pub fn is_full_filter_chain(&self) -> bool {
        self.program_name == XdpProgramName::Main
    }

    /// 获取底层 Object 引用
    pub fn object(&self) -> &libbpf_rs::Object {
        &self.obj
    }

    /// 获取底层 Object 可变引用
    ///
    /// 用于需要可变访问的场景（如获取 ProgramMut）
    pub fn object_mut(&mut self) -> &mut libbpf_rs::Object {
        &mut self.obj
    }

    /// 获取 XDP 程序引用（不可变，用于查询）
    ///
    /// 返回 Object 中**第一个** XDP 类型程序；同一 `.o` 含多个 XDP 程序时
    /// （如 xdp_redirect.o 的主/备两个程序），请使用 [`Self::xdp_program_by_name`]
    /// 按 ELF 符号名显式选择。
    pub fn xdp_program(&self) -> Option<libbpf_rs::Program<'_>> {
        self.obj.progs().find(|p| {
            matches!(p.prog_type(), ProgramType::Xdp)
        })
    }

    /// 按 ELF 符号名获取 XDP 程序引用（不可变）
    ///
    /// 解决同一 Object 中多个 XDP 程序不可达的问题：名称对应 C 源码中的
    /// `SEC("xdp")` 函数名（如 `zenith_xdp_redirect` / `zenith_xdp_redirect_b`）。
    pub fn xdp_program_by_name(&self, name: &str) -> Option<libbpf_rs::Program<'_>> {
        self.obj
            .progs()
            .find(|p| p.name() == name && matches!(p.prog_type(), ProgramType::Xdp))
    }

    /// 获取 XDP 程序可变引用（用于 attach_xdp 等操作）
    ///
    /// libbpf-rs 0.24 中 `attach_xdp` 定义在 `ProgramMut` 上，
    /// 因此需要通过 `progs_mut()` 获取。
    /// 多程序 Object 请使用 [`Self::xdp_program_mut_by_name`]。
    pub fn xdp_program_mut(&mut self) -> Option<libbpf_rs::ProgramMut<'_>> {
        self.obj.progs_mut().find(|p| {
            matches!(p.prog_type(), ProgramType::Xdp)
        })
    }

    /// 按 ELF 符号名获取 XDP 程序可变引用
    pub fn xdp_program_mut_by_name(&mut self, name: &str) -> Option<libbpf_rs::ProgramMut<'_>> {
        self.obj
            .progs_mut()
            .find(|p| p.name() == name && matches!(p.prog_type(), ProgramType::Xdp))
    }

    /// 获取程序数量
    pub fn prog_count(&self) -> usize {
        self.obj.progs().count()
    }

    /// 获取 Map 数量
    pub fn map_count(&self) -> usize {
        self.obj.maps().count()
    }

    /// 获取当前活动的 bpf_link
    pub fn active_link(&self) -> Option<&Link> {
        self.active_link.as_ref()
    }

    /// **挂载 XDP 程序到网卡（首次挂载）**
    ///
    /// 使用 `ProgramMut::attach_xdp()` 创建 bpf_link 并挂载：
    /// - 调用内核 `bpf_program__attach_xdp` 创建 XDP 类型的 bpf_link
    /// - 返回的 Link 用于后续的热更新管理
    ///
    /// # 参数
    /// * `ifindex` - 网卡接口索引
    ///
    /// # 返回
    /// * `Result<(), AttachError>` - 挂载结果
    ///
    /// # 性能说明
    /// bpf_link 创建为内核级操作，挂载过程零丢包。
    pub fn attach_xdp(&mut self, ifindex: i32) -> Result<(), AttachError> {
        let prog = self
            .xdp_program_mut()
            .ok_or_else(|| AttachError::InterfaceNotFound("XDP program not found".to_string()))?;

        let link = prog
            .attach_xdp(ifindex)
            .map_err(|e| AttachError::Libbpf(format!("Failed to attach XDP: {}", e)))?;

        self.active_link = Some(link);
        Ok(())
    }

    /// **原子替换 XDP 程序（热更新）**
    ///
    /// 使用 `Link::update_prog()` 实现原子程序替换：
    /// - 内核级 `bpf_link__update_program` 确保零丢包切换
    /// - 新程序生效后旧程序自动解绑
    /// - 无需创建新的 bpf_link，在同一 Link 内完成替换
    ///
    /// # 参数
    /// * `ifindex` - 网卡接口索引（用于首次挂载回退）
    ///
    /// # 返回
    /// * `Result<(), AttachError>` - 替换结果
    ///
    /// # 性能说明
    /// 原子替换为内核级操作，切换过程零丢包、零重置连接。
    /// 对于已挂载的 Link，`update_prog` 直接在内核中替换程序引用。
    pub fn attach_xdp_replace(&mut self, ifindex: i32) -> Result<(), AttachError> {
        // 先提取 active_link 到局部变量，避免与 xdp_program_mut() 冲突
        let mut link_opt = self.active_link.take();

        if let Some(link) = link_opt.as_mut() {
            // 已有 Link：原子替换程序
            let prog = self
                .xdp_program_mut()
                .ok_or_else(|| AttachError::InterfaceNotFound("XDP program not found".to_string()))?;

            // 通过 bpf_link__update_program 实现零丢包热切换
            link.update_prog(&prog)
                .map_err(|e| AttachError::Libbpf(format!("Failed to atomically replace XDP: {}", e)))?;
        } else {
            // 无 Link：首次挂载
            let prog = self
                .xdp_program_mut()
                .ok_or_else(|| AttachError::InterfaceNotFound("XDP program not found".to_string()))?;

            let link = prog
                .attach_xdp(ifindex)
                .map_err(|e| AttachError::Libbpf(format!("Failed to attach XDP: {}", e)))?;
            link_opt = Some(link);
        }

        self.active_link = link_opt;
        Ok(())
    }

    /// **用另一个加载器中的 XDP 程序原子替换当前 Link 指向的程序**
    ///
    /// 这是双 Bank 热切换的内核态核心：调用 `bpf_link__update_program`，
    /// 将本加载器持有的 bpf_link 原子地指向 `new_prog_owner` 的 XDP 程序。
    ///
    /// # 前置条件
    /// - 本加载器已通过 `attach_xdp` / `attach_xdp_replace` 挂载（存在活动 Link）
    /// - `new_prog_owner` 已成功加载且包含 XDP 类型程序
    ///
    /// # 错误（Fail-Closed）
    /// - 本加载器无活动 Link → `AttachError::InterfaceNotFound`
    /// - 对方无 XDP 程序 → `AttachError::InterfaceNotFound`
    /// - 内核替换失败 → `AttachError::Libbpf`，**旧程序保持在线**
    pub fn update_link_prog(&mut self, new_prog_owner: &mut XdpLoader) -> Result<(), AttachError> {
        let prog = new_prog_owner.xdp_program().ok_or_else(|| {
            AttachError::InterfaceNotFound("standby XDP program not found".to_string())
        })?;
        let link = self.active_link.as_mut().ok_or_else(|| {
            AttachError::InterfaceNotFound("no active bpf_link to update".to_string())
        })?;
        link.update_prog(&prog).map_err(|e| {
            AttachError::Libbpf(format!(
                "bpf_link update_prog failed (old program still online): {}",
                e
            ))
        })
    }

    /// 取出当前活动 bpf_link 的所有权（双 Bank 切换后 Link 跟随活动 Bank）
    pub fn take_link(&mut self) -> Option<Link> {
        self.active_link.take()
    }

    /// 设置当前活动 bpf_link（与 `take_link` 配对使用）
    pub fn set_link(&mut self, link: Option<Link>) {
        self.active_link = link;
    }

    /// 分离 XDP 程序（保留 Link 用于后续热切换）
    ///
    /// 调用 `bpf_link__detach` 分离程序但保留 Link 结构。
    /// 分离后可以通过 `attach_xdp_replace` 重新挂载。
    ///
    /// **多模式支持**：如果使用 `attach_xdp_optimal()` 或 `attach_xdp_with_mode()` 挂载，
    /// 则调用 `bpf_xdp_detach()` 分离。
    pub fn detach_xdp(&mut self) -> Result<(), AttachError> {
        // 情况 1：使用 bpf_link 挂载（attach_xdp / attach_xdp_replace）
        if let Some(link) = self.active_link.take() {
            link.detach()
                .map_err(|e| AttachError::Libbpf(format!("Failed to detach XDP (bpf_link): {}", e)))?;
            return Ok(());
        }

        // 情况 2：使用 bpf_xdp_attach 挂载（attach_xdp_optimal / attach_xdp_with_mode）
        if let Some(mode) = self.attach_mode.take()
            && let Some(ifindex) = self.attached_ifindex.take() {
                detach_xdp_raw(ifindex, mode)?;
            }

        Ok(())
    }

    /// **自动选择最优 XDP attach 模式（HW → DRV → SKB 逐级回退）**
    ///
    /// 极端极限极致严格标准：自动兼容切换最优值
    ///
    /// 按 HW_MODE → DRV_MODE → SKB_MODE 顺序尝试，首次成功即锁定：
    /// 1. **HW_MODE**（硬件卸载）— 最快，网卡硬件执行 eBPF
    /// 2. **DRV_MODE**（驱动层）— 次快，零拷贝，需驱动支持
    /// 3. **SKB_MODE**（通用 SKB）— 兜底，所有网卡支持（包括 WSL2/容器）
    ///
    /// 与 `attach_xdp()` 不同，本方法使用 `bpf_xdp_attach()` 系统调用
    /// 并指定 XDP_FLAGS_* 模式，支持自动回退。
    ///
    /// # 参数
    /// * `ifindex` - 网卡接口索引
    ///
    /// # 返回
    /// 成功时返回实际使用的模式
    pub fn attach_xdp_optimal(&mut self, ifindex: i32) -> Result<XdpAttachMode, AttachError> {
        self.attach_xdp_with_mode(ifindex, XdpAttachMode::Auto)
    }

    /// **用指定模式 attach XDP 程序**
    ///
    /// # 参数
    /// * `ifindex` - 网卡接口索引
    /// * `mode` - attach 模式（Auto = HW→DRV→SKB 逐级回退）
    ///
    /// # 返回
    /// 成功时返回实际使用的模式（Auto 解析为具体模式）
    pub fn attach_xdp_with_mode(
        &mut self,
        ifindex: i32,
        mode: XdpAttachMode,
    ) -> Result<XdpAttachMode, AttachError> {
        // 查找 XDP 程序名称（先获取名称，再获取 fd，避免借用冲突）
        let prog_name = self
            .obj
            .progs()
            .find(|p| matches!(p.prog_type(), ProgramType::Xdp))
            .map(|p| p.name().to_str().unwrap_or("").to_string())
            .filter(|n| !n.is_empty())
            .ok_or_else(|| {
                AttachError::InterfaceNotFound("XDP program not found".to_string())
            })?;

        // 直接获取程序 fd（无 pin，消除 TOCTOU）
        let prog_fd = get_prog_fd(&mut self.obj, &prog_name)?;

        // 用指定模式 attach
        let actual_mode = attach_xdp_raw(ifindex, prog_fd, mode)?;

        // 记录 attach 状态
        self.attach_mode = Some(actual_mode);
        self.attached_ifindex = Some(ifindex);

        Ok(actual_mode)
    }

    /// 获取当前 attach 模式
    pub fn current_attach_mode(&self) -> Option<XdpAttachMode> {
        self.attach_mode
    }

    /// 销毁当前 Link（完全解绑，不可恢复）
    ///
    /// 释放 bpf_link 资源。`Link` 的 `Drop` 实现
    /// 会自动调用 `bpf_link__destroy`，确保资源正确释放。
    ///
    /// **多模式支持**：同时清理 bpf_xdp_attach 状态和 pin 文件。
    pub fn destroy_link(&mut self) -> Result<(), AttachError> {
        // 清理 bpf_link
        self.active_link = None;

        // 清理 bpf_xdp_attach 状态
        self.attach_mode = None;
        self.attached_ifindex = None;
        self.prog_fd = None;

        // 清理 pin 文件
        if let Some(path) = self.pin_path.take() {
            unpin(&path);
        }

        Ok(())
    }
}

impl std::fmt::Debug for XdpLoader {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("XdpLoader")
            .field("program_name", &self.program_name)
            .field("prog_count", &self.prog_count())
            .field("map_count", &self.map_count())
            .field("has_active_link", &self.active_link.is_some())
            .field("attach_mode", &self.attach_mode)
            .field("attached_ifindex", &self.attached_ifindex)
            .finish()
    }
}

/// 自动清理资源：detach XDP 程序 + unpin bpffs 文件
impl Drop for XdpLoader {
    fn drop(&mut self) {
        // 尝试 detach（忽略错误，Drop 中不能 panic）
        let _ = self.detach_xdp();
        // 清理 pin 文件
        if let Some(path) = self.pin_path.take() {
            unpin(&path);
        }
    }
}

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

    /// 判断当前环境是否支持真实 eBPF 加载。
    ///
    /// # 设计原则（极端严格标准）
    /// 旧实现使用 `if let Ok(...)` 静默跳过加载失败，掩盖了致命问题
    /// （如 vmlinux.h 枚举错误导致内核验证器拒绝）。新实现：
    /// - Linux + 有 BPF 权限：必须严格 `assert!(loader.is_ok())`
    /// - 无内核/无权限环境：通过显式环境变量 `ZENITH_SKIP_BPF_LOAD_TEST=1` 跳过
    ///   并打印明确跳过原因，禁止静默通过
    fn should_skip_bpf_load() -> bool {
        // 非 Linux 平台无 BPF 子系统，明确跳过
        if cfg!(not(target_os = "linux")) {
            eprintln!("[SKIP] 非 Linux 平台，跳过 eBPF 加载测试");
            return true;
        }
        // 显式跳过开关（用于无 CAP_BPF 权限的 CI 环境）
        if std::env::var("ZENITH_SKIP_BPF_LOAD_TEST")
            .map(|v| v == "1" || v == "true")
            .unwrap_or(false)
        {
            eprintln!("[SKIP] ZENITH_SKIP_BPF_LOAD_TEST=1，跳过 eBPF 加载测试");
            return true;
        }
        false
    }

    /// 宏：严格加载 eBPF 程序，失败即 panic 暴露根本性问题
    macro_rules! require_load {
        ($name:expr) => {{
            if should_skip_bpf_load() {
                return;
            }
            match XdpLoader::load($name) {
                Ok(loader) => loader,
                Err(e) => panic!(
                    "XdpLoader::load({:?}) 必须成功。eBPF 加载失败说明字节码无法通过内核验证器，\
                     可能原因：vmlinux.h 枚举错误、map_type 数值与内核不匹配、\
                     clang 版本不兼容。错误: {:?}",
                    $name, e
                ),
            }
        }};
    }

    #[test]
    fn test_xdp_program_name_as_str() {
        assert_eq!(XdpProgramName::Main.as_str(), "xdp_main");
        assert_eq!(XdpProgramName::Redirect.as_str(), "xdp_redirect");
        assert_eq!(XdpProgramName::Stats.as_str(), "xdp_stats");
    }

    /// 哈希查找键必须与 build.rs 生成的 EXPECTED_HASHES 键严格一致
    #[test]
    fn test_hash_lookup_keys_match_expected_hashes() {
        for name in [
            XdpProgramName::Main,
            XdpProgramName::Redirect,
            XdpProgramName::Stats,
        ] {
            let found = EXPECTED_HASHES.iter().any(|(k, _)| *k == name.as_str());
            assert!(
                found,
                "EXPECTED_HASHES 必须包含键 '{}'（bpf_hashes.rs 由 build.rs 生成）",
                name.as_str()
            );
        }
    }

    /// 篡改字节码必须校验失败（fail-closed，禁止静默放行）
    #[test]
    fn test_tampered_bytecode_fails_verification() {
        let tampered = b"tampered-bytecode-not-the-real-elf";
        let result = verify_bytes_hash(XdpProgramName::Main.as_str(), tampered);
        assert!(result.is_err(), "篡改字节码必须校验失败");
        let err = result.err();
        assert!(
            matches!(err, Some(LoadError::VerificationFailed(_))),
            "错误类型必须为 VerificationFailed，实际: {:?}",
            err
        );
    }

    /// 未注册期望哈希的程序键必须校验失败（None 分支 fail-closed）
    #[test]
    fn test_unknown_program_key_fails_verification() {
        let result = verify_bytes_hash("xdp_nonexistent", b"whatever");
        assert!(result.is_err(), "未注册键必须校验失败");
        assert!(
            matches!(result.err(), Some(LoadError::VerificationFailed(_))),
            "错误类型必须为 VerificationFailed"
        );
    }

    /// 真实嵌入字节码必须通过完整性校验（开发模式空字节码除外）
    #[test]
    fn test_embedded_bytecode_passes_verification() {
        let allow_missing = std::env::var("ZENITH_ALLOW_MISSING_BPF")
            .map(|v| v == "1" || v == "true")
            .unwrap_or(false);
        for name in [
            XdpProgramName::Main,
            XdpProgramName::Redirect,
            XdpProgramName::Stats,
        ] {
            if allow_missing && name.get_bytecode().is_empty() {
                continue;
            }
            assert!(
                name.verify_integrity().is_ok(),
                "嵌入字节码 {:?} 必须通过 SHA-256 完整性校验",
                name
            );
        }
    }

    #[test]
    fn test_xdp_program_name_get_bytecode() {
        let main_bytes = XdpProgramName::Main.get_bytecode();
        let redirect_bytes = XdpProgramName::Redirect.get_bytecode();
        let stats_bytes = XdpProgramName::Stats.get_bytecode();

        // 预编译产物必须非空（除非 ZENITH_ALLOW_MISSING_BPF=1 开发模式）
        let allow_missing = std::env::var("ZENITH_ALLOW_MISSING_BPF")
            .map(|v| v == "1" || v == "true")
            .unwrap_or(false);
        if !allow_missing {
            assert!(!main_bytes.is_empty(), "xdp_main.o 字节码不能为空");
            assert!(!redirect_bytes.is_empty(), "xdp_redirect.o 字节码不能为空");
            assert!(!stats_bytes.is_empty(), "xdp_stats.o 字节码不能为空");
        }
        let _ = (main_bytes, redirect_bytes, stats_bytes);
    }

    #[test]
    fn test_xdp_loader_creation() {
        // 严格断言：加载必须成功（除非显式跳过环境）
        let loader = require_load!(XdpProgramName::Main);
        // 加载后必须包含 XDP 程序
        assert!(
            loader.xdp_program().is_some(),
            "加载后必须包含 XDP 类型程序"
        );
        assert!(loader.prog_count() >= 1, "程序数必须 >= 1");
    }

    /// NET-016：loader 必须记录程序标识，用于校验 Bank 活动程序为 xdp_main
    #[test]
    fn test_xdp_loader_program_name() {
        let loader = require_load!(XdpProgramName::Main);
        assert_eq!(loader.program_name(), XdpProgramName::Main);
        assert!(
            loader.is_full_filter_chain(),
            "xdp_main 必须被视为完整过滤链程序"
        );
    }

    #[test]
    fn test_xdp_loader_link_management() {
        let mut loader = require_load!(XdpProgramName::Redirect);
        // 未挂载前 active_link 必须为 None
        assert!(loader.active_link().is_none());

        // destroy_link 应安全处理 None
        let result = loader.destroy_link();
        assert!(result.is_ok());
        assert!(loader.active_link().is_none());
    }

    #[test]
    fn test_xdp_loader_detach_without_attach() {
        let mut loader = require_load!(XdpProgramName::Stats);
        // detach 应安全处理 None（未挂载时不应 panic）
        let result = loader.detach_xdp();
        assert!(result.is_ok());
    }

    #[test]
    fn test_xdp_program_mut_access() {
        let mut loader = require_load!(XdpProgramName::Redirect);
        // xdp_program_mut() 必须返回 Some
        let prog = loader.xdp_program_mut();
        assert!(prog.is_some(), "xdp_program_mut() 必须返回 Some");
    }

    #[test]
    fn test_xdp_program_name_debug() {
        let debug_str = format!("{:?}", XdpProgramName::Main);
        assert!(!debug_str.is_empty());
        let debug_str = format!("{:?}", XdpProgramName::Redirect);
        assert!(!debug_str.is_empty());
        let debug_str = format!("{:?}", XdpProgramName::Stats);
        assert!(!debug_str.is_empty());
    }

    #[test]
    fn test_xdp_program_name_clone_copy() {
        let a = XdpProgramName::Main;
        let b = a;
        assert_eq!(a, b);
        assert_eq!(a.as_str(), b.as_str());
    }

    #[test]
    fn test_xdp_program_name_eq() {
        assert_eq!(XdpProgramName::Main, XdpProgramName::Main);
        assert_eq!(XdpProgramName::Redirect, XdpProgramName::Redirect);
        assert_eq!(XdpProgramName::Stats, XdpProgramName::Stats);
        assert_ne!(XdpProgramName::Main, XdpProgramName::Redirect);
        assert_ne!(XdpProgramName::Main, XdpProgramName::Stats);
        assert_ne!(XdpProgramName::Redirect, XdpProgramName::Stats);
    }

    #[test]
    fn test_xdp_program_name_unique() {
        let names = [
            XdpProgramName::Main,
            XdpProgramName::Redirect,
            XdpProgramName::Stats,
        ];
        for (i, a) in names.iter().enumerate() {
            for (j, b) in names.iter().enumerate() {
                if i != j {
                    assert_ne!(a, b);
                } else {
                    assert_eq!(a, b);
                }
            }
        }
    }

    #[test]
    fn test_xdp_loader_debug() {
        let loader = require_load!(XdpProgramName::Main);
        let debug_str = format!("{:?}", loader);
        assert!(!debug_str.is_empty());
        assert!(debug_str.contains("XdpLoader"));
    }

    #[test]
    fn test_xdp_loader_object_access() {
        let loader = require_load!(XdpProgramName::Main);
        let _obj = loader.object();
        // prog_count 与 map_count 返回 usize，恒为非负，无需断言非负性。
        let _ = (loader.prog_count(), loader.map_count());
    }

    #[test]
    fn test_xdp_loader_object_mut_access() {
        let mut loader = require_load!(XdpProgramName::Main);
        let _obj = loader.object_mut();
    }

    #[test]
    fn test_xdp_program_name_all_variants() {
        let variants = [
            XdpProgramName::Main,
            XdpProgramName::Redirect,
            XdpProgramName::Stats,
        ];
        assert_eq!(variants.len(), 3);
        for v in variants.iter() {
            assert!(!v.as_str().is_empty());
        }
    }

    #[test]
    fn test_attach_error_display() {
        use crate::error::AttachError;
        let e = AttachError::InterfaceNotFound("eth0".to_string());
        assert!(format!("{}", e).contains("Interface not found"));
    }

    #[test]
    fn test_load_error_display() {
        use crate::error::LoadError;
        let e = LoadError::EmptyBytecode;
        assert!(format!("{}", e).contains("Bytecode is empty"));
    }

    /// 真实加载三个程序的端到端验证（极端严格标准）
    ///
    /// 此测试是 eBPF 闭环可用性的"金丝雀"：任何一个程序加载失败
    /// 都会立即 panic 并打印详细错误，防止问题被静默掩盖。
    #[test]
    fn test_all_programs_load_into_kernel() {
        if should_skip_bpf_load() {
            return;
        }
        for name in [
            XdpProgramName::Main,
            XdpProgramName::Redirect,
            XdpProgramName::Stats,
        ] {
            let result = XdpLoader::load(name);
            assert!(
                result.is_ok(),
                "eBPF 程序 {:?} 必须能加载到内核。错误: {:?}\
                 \n可能原因：vmlinux.h 枚举与内核不匹配、clang 编译参数错误、\
                 map_type 数值错误、内核版本不兼容",
                name,
                result.err()
            );
            let loader = result.unwrap();
            assert!(
                loader.prog_count() >= 1,
                "程序 {:?} 加载后必须包含至少 1 个 BPF 程序",
                name
            );
        }
    }
}