zenith-api 0.1.0

//! 规范化引擎
//!
//! 本模块提供 HTTP 请求/响应的单次规范化处理，
//! 确保所有协议（HTTP/1.1、HTTP/2、HTTP/3）生成一致的 CanonicalRequest。
//!
//! # 库内定位（全链路声明）
//!
//! 本模块是**公共规范化参考实现**：
//! - `normalize_path` / `percent_decode*`（含 `_into` 零拷贝变体）/ `is_valid_header_name`
//!   是全 workspace 唯一实现，被 zenith-web（三协议 normalize）、zenith-cache（键构造）、
//!   zenith-waf（WAF 解码）、zenith-ebpf 等生产路径真实复用；
//! - `normalize_request` / `normalize_request_with_config` / `normalize_headers` /
//!   `normalize_authority` / `normalize_query` 是面向外部集成方的一级规范化 API，
//!   语义基线由 `tests/cross_protocol_consistency.rs`（跨协议一致性全套集成测试）
//!   锁定；zenith-web 生产路径使用性能特化的 `normalize_http1/2/3_request`
//!   （同一规范化语义，零堆分配热路径），两条路径的语义一致性由该测试套件保证。
//!
//! # 规范化规则
//!
//! ## 路径规范化
//! - 点段折叠（. / .. 处理）
//! - 多余斜杠处理
//! - 大小写标准化（保留原始大小写）
//! - URL 解码（安全字符）
//!
//! ## Header 规范化
//! - 字段名小写
//! - 多值合并（同名 Header 合并为逗号分隔）
//! - 空白字符标准化
//! - 非法字符过滤
//!
//! ## Authority 规范化
//! - Host 与端口标准化
//! - 默认端口省略
//! - 大小写统一

use crate::{CanonicalRequest, Method, Protocol, Transport};

/// 规范化配置
#[derive(Debug, Clone, Copy)]
pub struct NormalizeConfig {
    /// 是否进行路径解码
    pub decode_path: bool,
    /// 是否合并同名 Header
    pub merge_headers: bool,
    /// 是否标准化大小写
    pub normalize_case: bool,
}

impl Default for NormalizeConfig {
    fn default() -> Self {
        Self {
            decode_path: true,
            merge_headers: true,
            normalize_case: true,
        }
    }
}

/// 规范化错误
#[derive(Debug, Clone)]
pub struct NormalizeError {
    /// 错误描述
    pub message: &'static str,
}

impl core::fmt::Display for NormalizeError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "NormalizeError: {}", self.message)
    }
}

/// 规范化 HTTP 请求
///
/// 将原始 HTTP 请求元素规范化为统一的 CanonicalRequest。
/// 此函数执行单次遍历，消除协议差分攻击风险。
///
/// # Arguments
/// * `method` - HTTP 方法
/// * `scheme` - URL 方案（http/https）
/// * `authority` - 授权主机（host:port）
/// * `path` - 请求路径
/// * `query` - 查询字符串
/// * `headers` - 请求头列表
/// * `protocol` - 协议类型
/// * `transport` - 传输层类型
///
/// # Returns
/// * `Ok(CanonicalRequest)` - 规范化后的请求
/// * `Err(NormalizeError)` - 规范化失败
#[allow(clippy::too_many_arguments)]
pub fn normalize_request(
    method: Method,
    scheme: &str,
    authority: &str,
    path: &str,
    query: &str,
    headers: &[(&str, &str)],
    protocol: Protocol,
    transport: Transport,
) -> Result<CanonicalRequest, NormalizeError> {
    let config = NormalizeConfig::default();
    normalize_request_with_config(
        method, scheme, authority, path, query, headers, protocol, transport, config,
    )
}

/// 使用自定义配置规范化 HTTP 请求
#[allow(clippy::too_many_arguments)]
pub fn normalize_request_with_config(
    method: Method,
    scheme: &str,
    authority: &str,
    path: &str,
    query: &str,
    headers: &[(&str, &str)],
    protocol: Protocol,
    transport: Transport,
    config: NormalizeConfig,
) -> Result<CanonicalRequest, NormalizeError> {
    let mut request = CanonicalRequest::empty();

    // 1. 设置方法
    request.method = method;
    request.protocol = protocol;
    request.transport = transport;

    // 2. 规范化方案
    let normalized_scheme = if config.normalize_case {
        scheme.to_lowercase()
    } else {
        scheme.to_string()
    };
    // fail-closed：超长拒绝整体报错，禁止静默截断后放行
    if !request.set_scheme(&normalized_scheme) {
        return Err(NormalizeError {
            message: "scheme too long",
        });
    }

    // 3. 规范化 Authority
    let normalized_authority = normalize_authority(authority, &normalized_scheme);
    if !request.set_authority(&normalized_authority) {
        return Err(NormalizeError {
            message: "authority too long",
        });
    }

    // 4. 规范化路径
    let normalized_path = normalize_path(path, config.decode_path)?;
    if !request.set_path(&normalized_path) {
        return Err(NormalizeError {
            message: "path too long",
        });
    }

    // 5. 规范化查询字符串
    let normalized_query = normalize_query(query, config.decode_path);
    if !request.set_query(&normalized_query) {
        return Err(NormalizeError {
            message: "query too long",
        });
    }

    // 6. 规范化 Headers
    normalize_headers(&mut request, headers, config)?;

    Ok(request)
}

/// 规范化路径
///
/// # 规则
/// - 折叠 "." 和 ".." 段
/// - 合并多余斜杠
/// - 保留前导斜杠
pub fn normalize_path(path: &str, decode: bool) -> Result<String, NormalizeError> {
    if path.is_empty() {
        return Ok("/".to_string());
    }

    let bytes = path.as_bytes();
    let mut result = Vec::with_capacity(path.len());

    // 记录原始输入是否以 '/' 结尾（RFC 3986 §5.2.4：尾斜杠是路径语义的一部分，
    // 区分目录与资源，丢弃会改变路由语义）
    let has_trailing_slash = bytes.ends_with(b"/");

    // 确定是否以斜杠开头
    let starts_with_slash = bytes[0] == b'/';
    if starts_with_slash {
        result.push(b'/');
    }

    let segments: Vec<&[u8]> = bytes
        .split(|&b| b == b'/')
        .filter(|s| !s.is_empty())
        .collect();

    // 先解码后折叠：点段判定必须作用于解码后的字节。
    // 若先按未解码字节折叠再解码，`%2e%2e` 会以编码形态绕过折叠，
    // 解码后残留的 `..` 直接形成路径穿越语义漏洞。
    // decode=false 时保持字面：不解码，编码形态的点段也不参与折叠。
    let mut stack: Vec<Vec<u8>> = Vec::with_capacity(segments.len());

    for segment in &segments {
        let decoded: Vec<u8> = if decode {
            // 安全解码：只解码 unreserved 字符（%2f 等 reserved 保持编码态，
            // %252e 等双重编码只解一层，解出的 %2e 与 . / .. 不相等，按字面入栈）
            safe_percent_decode(segment)
        } else {
            segment.to_vec()
        };
        match decoded.as_slice() {
            b"." => {
                // 当前目录，跳过
            }
            b".." => {
                // 上一级目录（栈空时 pop 为 no-op，停在根）
                stack.pop();
            }
            _ => {
                stack.push(decoded);
            }
        }
    }

    for (i, segment) in stack.iter().enumerate() {
        // 第一个元素不需要额外添加斜杠（starts_with_slash 已预先添加）
        if i > 0 {
            result.push(b'/');
        }
        result.extend_from_slice(segment);
    }

    // 如果没有任何内容，返回 "/"
    if result.is_empty() {
        result.push(b'/');
    }

    // RFC 3986 §5.2.4：保留尾斜杠语义。尾斜杠区分目录与资源，
    // 丢弃会改变路由语义（如 /a/b/ 与 /a/b 可能映射不同处理器）。
    // 仅在结果不以 '/' 结尾时追加（避免对 "/" 等已有尾斜杠的结果重复添加）。
    if has_trailing_slash && !result.ends_with(b"/") {
        result.push(b'/');
    }

    // 转换为字符串
    String::from_utf8(result).map_err(|_| NormalizeError {
        message: "invalid UTF-8 in path",
    })
}

/// 规范化查询字符串
///
/// 主要处理：
/// - 移除所有前导 `?`
/// - 保留完整 query（`?` 是 query 中的合法数据字符，
///   按 `?` 切分丢尾会静默丢失信息，禁止）
/// - Unicode 空白字符统一映射为 ASCII 空格
/// - `decode=true`：与路径相同的 unreserved-only 安全解码
///   （`%41` → `A`，`%2f` 等 reserved 保持编码态）；
///   `decode=false`：保留原始编码
pub fn normalize_query(query: &str, decode: bool) -> String {
    if query.is_empty() {
        return String::new();
    }

    // 移除所有前导 '?'，保留剩余完整内容（包括中间的 '?'）
    let trimmed = query.trim_start_matches('?');

    // 规范化空白字符
    let normalized: String = trimmed
        .chars()
        .map(|c| if c.is_whitespace() { ' ' } else { c })
        .collect();

    if !decode {
        return normalized;
    }

    // 与 normalize_path 相同的 unreserved-only 解码语义。
    // safe_percent_decode 仅把合法 %XX 序列替换为 unreserved 集合内的
    // ASCII 字节，其余字节原样透传，故合法 UTF-8 输入解码后必然仍是
    // 合法 UTF-8；from_utf8 失败分支理论不可达，保底返回未解码串，
    // 绝不 panic、绝不产出非法字符串。
    match String::from_utf8(safe_percent_decode(normalized.as_bytes())) {
        Ok(decoded) => decoded,
        Err(_) => normalized,
    }
}

/// 规范化 Authority（host:port）
///
/// # 规则
/// - 默认端口省略（http:80, https:443）
/// - Host 小写化
/// - 处理 IPv6 地址
///
/// # 与 [`normalize_host_key`] 的分工差异（设计使然，禁止"统一"两者行为）
/// 本函数是**请求 authority 的 RFC 语义**规范化，面向路由/转发；
/// [`normalize_host_key`] 是**缓存键等值折叠**规范化。具体差异：
/// - 默认端口判定：本函数 **scheme 感知**，仅 http 省略 `:80`、https 省略
///   `:443`（http 下 `:443` 原样保留）；`normalize_host_key` 不感知 scheme，
///   `:80`/`:443` 一律剥离。
/// - FQDN 尾点：本函数**保留**尾点（`example.com.` → `example.com.`）；
///   `normalize_host_key` 剥离尾点（→ `example.com`）。
/// - 空白：本函数不 trim；`normalize_host_key` 会 trim 两端空白。
pub fn normalize_authority(authority: &str, scheme: &str) -> String {
    if authority.is_empty() {
        return String::new();
    }

    let (host, port) = if let Some(bracket_start) = authority.find('[') {
        // IPv6 地址（fail-closed：`]` 必须位于 `[` 之后，
        // 括号不成对/反向时视为非 IPv6 形式，禁止切片反转 panic；
        // 对端可控字段不得触发字节范围 panic（§4.4））
        match authority.find(']') {
            Some(bracket_end) if bracket_end > bracket_start => {
                let host = &authority[bracket_start..=bracket_end];
                let port_part = authority.get(bracket_end + 1..).unwrap_or("");
                let port = port_part.trim_start_matches(':');
                // 与非 IPv6 分支一致：端口必须为合法 u16 数字，
                // 否则视为无端口（`[::1]:abc` → 仅保留 `[::1]`，避免保留非法端口）
                if port.is_empty() || port.parse::<u16>().is_ok() {
                    (host.to_string(), port.to_string())
                } else {
                    (host.to_string(), String::new())
                }
            }
            _ => (authority.to_string(), String::new()),
        }
    } else if let Some(colon_pos) = authority.rfind(':') {
        // 可能是 host:port
        let host = &authority[..colon_pos];
        let port = &authority[colon_pos + 1..];
        // 验证端口是否为数字
        if port.parse::<u16>().is_ok() {
            (host.to_string(), port.to_string())
        } else {
            (authority.to_string(), String::new())
        }
    } else {
        (authority.to_string(), String::new())
    };

    let normalized_host = host.to_lowercase();

    // 检查默认端口
    let default_port = match scheme {
        "http" => Some("80"),
        "https" => Some("443"),
        _ => None,
    };

    if !port.is_empty() {
        if let Some(default) = default_port
            && port == default
        {
            // 默认端口，省略
            return normalized_host;
        }
        format!("{}:{}", normalized_host, port)
    } else {
        normalized_host
    }
}

/// 规范化 Host 用于缓存键等值折叠（scheme 无关策略）。
///
/// # 规则（缓存键专用，区别于 [`normalize_authority`] 的 RFC authority 语义）
/// - `trim` + 小写化
/// - 去 FQDN 尾点（`example.com.` → `example.com`）
/// - **无条件**去除默认端口（`:80` / `:443`，不感知 scheme）——缓存键
///   要求"同一监听服务"折叠；严格 URL authority 语义请用
///   [`normalize_authority`]（scheme 感知）。
/// - IPv6 方括号保留；`]:` 之侧仅数字视作端口
///
/// # 统一实现约定
/// 本函数是全 workspace 唯一的缓存键 host 规范化实现
/// （zenith-cache 经此接口规范化，禁止第二份副本）。
///
/// # 与 [`normalize_authority`] 的分工差异（设计使然，禁止"统一"两者行为）
/// - 默认端口：本函数**不感知 scheme**，`:80`/`:443` 一律剥离（缓存键要求
///   "同一监听服务"折叠）；`normalize_authority` 仅按 scheme 省略
///   （http→80、https→443）。
/// - FQDN 尾点：本函数剥离（`example.com.` → `example.com`）；
///   `normalize_authority` 保留尾点。
/// - 空白：本函数 trim 两端空白；`normalize_authority` 不 trim。
pub fn normalize_host_key(host: &str) -> String {
    let h = host.trim();
    if h.is_empty() {
        return String::new();
    }
    let (name, port) = split_host_port(h);
    let mut name = name.to_lowercase();
    // 去尾部点（FQDN 尾点，如 example.com.）
    while name.ends_with('.') {
        name.pop();
    }
    // 去默认端口；非默认端口保留
    match port {
        Some("80") | Some("443") => name,
        Some(p) => format!("{name}:{p}"),
        None => name,
    }
}

/// 拆分 `host[:port]`，处理 IPv6 方括号字面量（`[addr]` / `[addr]:port`）。
///
/// 返回 (host部分, 可选端口)。IPv6 的 host 部分含方括号；端口仅当
/// 段内全为 ASCII 数字时成立。
///
/// # 公开为单一实现源
///
/// `normalize_host_key`、zenith-web `IdentityMiddleware::extract_host`、
/// zenith-web SNI/Host 一致性检查共享本实现（禁止第二份副本）：统一
/// IPv6 方括号/裸主机/带端口的切分语义，杜绝 `split(':')` 一类对
/// IPv6 字面量的截断失误。
pub fn split_host_port(h: &str) -> (&str, Option<&str>) {
    if let Some(end) = h.strip_prefix('[').and_then(|s| s.find(']')) {
        // IPv6：']' 在 h 中的索引为 end+1（s 比 h 少前导 '['）
        let addr = &h[..=end + 1]; // 含方括号
        let rest = &h[end + 2..];
        match rest.strip_prefix(':') {
            Some(p) if !p.is_empty() => (addr, Some(p)),
            _ => (addr, None),
        }
    } else if let Some(idx) = h.rfind(':') {
        // 普通 host:port：仅当 ':' 后全为数字才视为端口
        let (name, p) = h.split_at(idx);
        let p = &p[1..];
        if !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()) {
            (name, Some(p))
        } else {
            (h, None)
        }
    } else {
        (h, None)
    }
}

/// 剥离 IPv6 字面量外层的方括号（authority → SNI 形对齐）
///
/// `split_host_port` 对 IPv6 authority 返回含括号 host（`"[::1]"`），
/// 而 RFC 6066 SNI host_name 不允许括号（`"::1"`）——SNI/Host 一致性、
/// 白名单比对等场景需要在比较前统一剥括号使两侧同形。
///
/// # 语义
/// - 合法可配对方括号 `[x]` → 返回 `x`
/// - 任意其他输入（空、单边括号、无括号）→ 原样返回（fail-closed，
///   不产生收缩，由下游比对决定匹配性）
#[inline]
pub fn unbracket_ipv6(h: &str) -> &str {
    h.strip_prefix('[')
        .and_then(|s| s.strip_suffix(']'))
        .unwrap_or(h)
}

/// 规范化 Headers
///
/// # 规则
/// - 字段名小写
/// - 合并同名 Header（用逗号分隔值）
/// - 拒绝非法 header 名（fail-closed，不静默丢弃）
pub fn normalize_headers(
    request: &mut CanonicalRequest,
    headers: &[(&str, &str)],
    config: NormalizeConfig,
) -> Result<(), NormalizeError> {
    if headers.is_empty() {
        return Ok(());
    }

    // 如果启用合并，使用临时存储
    if config.merge_headers {
        let mut merged: Vec<(String, Vec<String>)> = Vec::new();

        for (name, value) in headers {
            // 过滤 HTTP/2/3 伪头部（以 ':' 开头）
            if name.starts_with(':') {
                continue;
            }

            let normalized_name = if config.normalize_case {
                name.to_lowercase()
            } else {
                name.to_string()
            };

            // 拒绝非法 header 名（fail-closed）：不静默丢弃，整体返回错误
            if !is_valid_header_name(&normalized_name) {
                return Err(NormalizeError {
                    message: "invalid header name",
                });
            }

            // 规范化值（去除前后空白）
            let normalized_value = value.trim().to_string();

            // 查找是否已存在
            if let Some(entry) = merged.iter_mut().find(|(n, _)| n == &normalized_name) {
                entry.1.push(normalized_value);
            } else {
                merged.push((normalized_name, vec![normalized_value]));
            }
        }

        // 添加合并后的 Headers
        for (name, values) in &merged {
            let combined_value = values.join(", ");
            // SYS-026：合并前预检合并后总长，超限返回**精确错误**（"header value too long"），
            // 而非原实现把所有 add_header 失败一律映射为"header count exceeded"——
            // 后者掩盖了真实原因，且大量合法 header 聚合超限会被误报为数量超限。
            if combined_value.len() > crate::MAX_HEADER_VALUE_LEN {
                return Err(NormalizeError {
                    message: "header value too long",
                });
            }
            request
                .add_header(name.as_bytes(), combined_value.as_bytes())
                .map_err(|msg| NormalizeError { message: msg })?;
        }
    } else {
        // 不合并，直接添加
        for (name, value) in headers {
            // 过滤 HTTP/2/3 伪头部（以 ':' 开头）
            if name.starts_with(':') {
                continue;
            }

            let normalized_name = if config.normalize_case {
                name.to_lowercase()
            } else {
                name.to_string()
            };

            if !is_valid_header_name(&normalized_name) {
                return Err(NormalizeError {
                    message: "invalid header name",
                });
            }

            let normalized_value = value.trim();
            request
                .add_header(normalized_name.as_bytes(), normalized_value.as_bytes())
                .map_err(|msg| NormalizeError { message: msg })?;
        }
    }

    Ok(())
}

/// 检查 Header 名是否合法（RFC 7230 token 定义）
///
/// token = 1*tchar
/// tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
///         "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
pub fn is_valid_header_name(name: &str) -> bool {
    if name.is_empty() {
        return false;
    }
    name.chars().all(|c| {
        c.is_ascii_alphanumeric()
            || matches!(
                c,
                '!' | '#' | '$' | '%' | '&' | '\'' | '*' | '+' | '-' | '.' | '^' | '_' | '`' | '|' | '~'
            )
    })
}

/// 非法百分号序列处理策略
///
/// 统一 WAF 与应用层（extractor / cache）的百分号解码语义，
/// 消除"同一输入各层解码结果不同"的协议差分攻击面。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InvalidSequencePolicy {
    /// 遇非法 `%` 序列整体拒绝（fail-closed，返回 `None`），
    /// 禁止部分解码后放行
    Reject,
    /// 非法 `%` 序列按原字节保留（`%ZZ` → `%ZZ`），
    /// 保留的字节仍参与后续模式匹配，不会丢失攻击特征
    Preserve,
}

/// 百分号解码（fail-closed）
///
/// 将 `%XX` 序列解码为对应字节；`plus_as_space` 为 `true` 时把 `+`
/// 解码为空格（`application/x-www-form-urlencoded` 语义）。
///
/// 语义等价于 `percent_decode_with_policy(input, plus_as_space, Reject)`。
///
/// # Returns
/// * `Some(String)` - 解码成功
/// * `None` - 非法输入：`%` 后不足两位十六进制字符，或解码结果不是合法 UTF-8
///   （fail-closed：非法序列整体拒绝，禁止部分解码后放行）
pub fn percent_decode(input: &str, plus_as_space: bool) -> Option<String> {
    percent_decode_with_policy(input, plus_as_space, InvalidSequencePolicy::Reject)
}

/// 带非法序列策略的百分号解码（字符串级统一入口）
///
/// 将 `%XX` 序列解码为对应字节；`plus_as_space` 为 `true` 时把 `+`
/// 解码为空格（`application/x-www-form-urlencoded` 语义）。
///
/// # 策略
/// - [`InvalidSequencePolicy::Reject`]：遇非法 `%` 序列整体返回 `None`
/// - [`InvalidSequencePolicy::Preserve`]：非法 `%` 序列按原字节保留
///
/// 无论哪种策略，解码结果不是合法 UTF-8 时均返回 `None`
/// （字符串级 API 必须保证输出是合法 `String`）。
///
/// # Returns
/// * `Some(String)` - 解码成功
/// * `None` - 策略为 Reject 且遇非法序列，或解码结果不是合法 UTF-8
pub fn percent_decode_with_policy(
    input: &str,
    plus_as_space: bool,
    policy: InvalidSequencePolicy,
) -> Option<String> {
    let mut out = Vec::with_capacity(input.len());
    decode_percent_vec(input.as_bytes(), plus_as_space, policy, &mut out)?;
    // 解码结果必须是合法 UTF-8，否则整体拒绝
    String::from_utf8(out).ok()
}

/// 字节级百分号解码（Preserve 策略，分配 `Vec`）
///
/// 非法 `%` 序列按原字节保留；`plus_as_space` 为 `true` 时 `+` 解码为空格。
/// 不做 UTF-8 校验，输入/输出均为字节序列，
/// 用于 body 等不保证 UTF-8 的场景。
///
/// Preserve 策略下解码永不失败，故直接返回 `Vec<u8>`。
pub fn percent_decode_bytes(input: &[u8], plus_as_space: bool) -> Vec<u8> {
    let mut out = Vec::with_capacity(input.len());
    // Preserve 策略不会返回 None（非法序列按原字节保留）
    let _ = decode_percent_vec(input, plus_as_space, InvalidSequencePolicy::Preserve, &mut out);
    out
}

/// 字节级百分号解码，结果写入调用方缓冲区（Preserve 策略，零堆分配）
///
/// 非法 `%` 序列按原字节保留；`plus_as_space` 为 `true` 时 `+` 解码为空格。
/// 不做 UTF-8 校验（调用方按需自行校验）。
/// 供 WAF 等零堆分配热路径使用。
///
/// # Returns
/// * `Some(&buf[..n])` - 解码结果（借用调用方缓冲区）
/// * `None` - 缓冲区不足（fail-closed，禁止截断后放行）
pub fn percent_decode_bytes_into<'a>(
    input: &[u8],
    buf: &'a mut [u8],
    plus_as_space: bool,
) -> Option<&'a [u8]> {
    let mut i = 0usize;
    let mut j = 0usize;

    while i < input.len() {
        // 边界检查：输出超出缓冲区容量则 fail-closed
        if j >= buf.len() {
            return None;
        }
        match input[i] {
            b'%' => {
                // 用 get 而非算术索引，杜绝越界
                let hi = input.get(i + 1).copied().and_then(hex_value);
                let lo = input.get(i + 2).copied().and_then(hex_value);
                match (hi, lo) {
                    (Some(h), Some(l)) => {
                        // h/l <= 15，(h << 4) | l <= 255，不会溢出
                        buf[j] = (h << 4) | l;
                        j += 1;
                        i += 3;
                    }
                    // Preserve：非法转义按原字节保留（仍参与模式匹配）
                    _ => {
                        buf[j] = b'%';
                        j += 1;
                        i += 1;
                    }
                }
            }
            b'+' if plus_as_space => {
                buf[j] = b' ';
                j += 1;
                i += 1;
            }
            b => {
                buf[j] = b;
                j += 1;
                i += 1;
            }
        }
    }

    Some(&buf[..j])
}

/// 核心解码循环：结果追加到 `out`，按策略处理非法 `%` 序列
///
/// - Reject：遇非法序列返回 `None`
/// - Preserve：非法序列按原字节保留，永不失败
fn decode_percent_vec(
    input: &[u8],
    plus_as_space: bool,
    policy: InvalidSequencePolicy,
    out: &mut Vec<u8>,
) -> Option<()> {
    let mut i = 0usize;

    while i < input.len() {
        match input[i] {
            b'%' => {
                // 用 get 而非算术索引，杜绝越界
                let hi = input.get(i + 1).copied().and_then(hex_value);
                let lo = input.get(i + 2).copied().and_then(hex_value);
                match (hi, lo) {
                    (Some(h), Some(l)) => {
                        // h/l <= 15，(h << 4) | l <= 255，不会溢出
                        out.push((h << 4) | l);
                        i += 3;
                    }
                    _ => match policy {
                        // fail-closed：非法序列整体拒绝，禁止部分解码后放行
                        InvalidSequencePolicy::Reject => return None,
                        // 非法序列按原字节保留
                        InvalidSequencePolicy::Preserve => {
                            out.push(b'%');
                            i += 1;
                        }
                    },
                }
            }
            b'+' if plus_as_space => {
                out.push(b' ');
                i += 1;
            }
            b => {
                out.push(b);
                i += 1;
            }
        }
    }

    Some(())
}

/// 十六进制字符 → 数值（0-15），非十六进制返回 None
const fn hex_value(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
}

/// 安全百分号编码解码
///
/// 只解码 unreserved 字符（RFC 3986）：
/// A-Z a-z 0-9 - _ . ~
fn safe_percent_decode(input: &[u8]) -> Vec<u8> {
    let mut result = Vec::with_capacity(input.len());
    let mut i = 0;

    while i < input.len() {
        if input[i] == b'%' && i + 2 < input.len() {
            // 检查是否为合法百分号编码
            let hex = &input[i + 1..i + 3];
            if let Ok(byte) = u8::from_str_radix(
                core::str::from_utf8(hex).unwrap_or(""),
                16,
            ) {
                // 只解码 unreserved 字符
                if is_unreserved(byte) {
                    result.push(byte);
                    i += 3;
                    continue;
                }
            }
        }
        result.push(input[i]);
        i += 1;
    }

    result
}

/// 检查是否为可安全解码的字符
///
/// 包括 unreserved 字符（RFC 3986）和其他在 URL 路径中安全的字符：
/// A-Z a-z 0-9 - _ . ~ SP %。
/// '%' 可解码是有意设计：使双重编码 `%252e` 单趟解一层为字面 `%2e`
/// （单趟解码不回扫输出，故解出的 `%2e` 不会再被解码折叠成 `.`），
/// 与 normalize_path 的"先解码后折叠"语义配套——保证 `%2e%2e` 能被
/// 折叠为 `..` 消除，而 `%252e%252e` 保持单层编码字面残留。
fn is_unreserved(b: u8) -> bool {
    b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'~' | b'%')
}

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

    /// 单一实现源锁定：`split_host_port` + `unbracket_ipv6` 的
    /// IPv6/端口语义矩阵（zenith-web IdentityMiddleware 与 SNI/Host
    /// 一致性检查共同消费）。
    #[test]
    fn split_host_port_and_unbracket_ipv6_matrix() {
        // 普通 host:port / 无端口
        assert_eq!(split_host_port("example.com:8443"), ("example.com", Some("8443")));
        assert_eq!(split_host_port("example.com"), ("example.com", None));
        // 非数字尾段不是端口
        assert_eq!(split_host_port("example.com:abc"), ("example.com:abc", None));
        // IPv6 方括号（含/不含端口）
        assert_eq!(split_host_port("[::1]"), ("[::1]", None));
        assert_eq!(split_host_port("[::1]:8443"), ("[::1]", Some("8443")));
        // IPv6 zone id 与含点混合地址
        assert_eq!(split_host_port("[fe80::ff]:443"), ("[fe80::ff]", Some("443")));
        assert_eq!(split_host_port("[::ffff:1.2.3.4]"), ("[::ffff:1.2.3.4]", None));

        // unbracket_ipv6：成对方括号剥掉；单边/无括号输入原样返回
        assert_eq!(unbracket_ipv6("[::1]"), "::1");
        assert_eq!(unbracket_ipv6("[a]"), "a");
        assert_eq!(unbracket_ipv6("::1"), "::1");
        assert_eq!(unbracket_ipv6("example.com"), "example.com");
        assert_eq!(unbracket_ipv6("[::"), "[::");
        assert_eq!(unbracket_ipv6("a]"), "a]");
        assert_eq!(unbracket_ipv6(""), "");
    }

    #[test]
    fn test_normalize_path_simple() {
        let result = normalize_path("/simple/path", true).unwrap();
        assert_eq!(result, "/simple/path");
    }

    #[test]
    fn test_normalize_path_dot_segments() {
        let result = normalize_path("/a/./b/../c", true).unwrap();
        assert_eq!(result, "/a/c");
    }

    #[test]
    fn test_normalize_path_double_dot() {
        let result = normalize_path("/a/b/c/../../d", true).unwrap();
        assert_eq!(result, "/a/d");
    }

    #[test]
    fn test_normalize_path_root() {
        let result = normalize_path("/", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_empty() {
        let result = normalize_path("", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_multiple_slashes() {
        let result = normalize_path("//a///b", true).unwrap();
        assert_eq!(result, "/a/b");
    }

    #[test]
    fn test_normalize_path_percent_decode() {
        // %7E (~) 是 unreserved，decode=true 时解码为字面字符
        let result = normalize_path("/hello%7Eworld", true).unwrap();
        assert_eq!(result, "/hello~world");
    }

    #[test]
    fn test_normalize_path_no_decode() {
        let result = normalize_path("/hello%20world", false).unwrap();
        assert_eq!(result, "/hello%20world");
    }

    // ─────────────────────────────────────────────
    // 编码点段折叠回归（先解码后折叠，路径穿越漏洞修复）
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_path_encoded_dot_segments_folded() {
        // 回归：%2e%2e 解码为 .. 后必须参与折叠，禁止残留 .. 输出
        assert_eq!(normalize_path("/a/%2e%2e/b", true).unwrap(), "/b");
        assert_eq!(normalize_path("/a/%2e/b", true).unwrap(), "/a/b");
        // 越过根目录的 .. 弹出空栈为 no-op，停在根
        assert_eq!(
            normalize_path("/%2e%2e/etc/passwd", true).unwrap(),
            "/etc/passwd"
        );
        // 双重编码只解一层：%252e → %2e（字面入栈），不递归解码折叠
        assert_eq!(
            normalize_path("/a/%252e%252e/b", true).unwrap(),
            "/a/%2e%2e/b"
        );
    }

    #[test]
    fn test_normalize_path_encoded_dot_segments_mixed_case() {
        // 大小写混合十六进制同样折叠
        assert_eq!(normalize_path("/a/%2E%2e/b", true).unwrap(), "/b");
        assert_eq!(normalize_path("/a/%2e%2E/b", true).unwrap(), "/b");
        assert_eq!(normalize_path("/a/%2E/b", true).unwrap(), "/a/b");
    }

    #[test]
    fn test_normalize_path_encoded_dot_segments_reserved_kept() {
        // %2f 为 reserved，不解码：编码斜杠不引入新分段
        assert_eq!(
            normalize_path("/a%2f..%2fb", true).unwrap(),
            "/a%2f..%2fb"
        );
        // 段内非精确点段（解出 ... ）按字面保留
        assert_eq!(normalize_path("/a/..%2e/b", true).unwrap(), "/a/.../b");
    }

    #[test]
    fn test_normalize_path_encoded_dot_segments_no_decode() {
        // decode=false：编码点段保持字面，不参与折叠（新逻辑仅作用于 decode=true）
        assert_eq!(
            normalize_path("/a/%2e%2e/b", false).unwrap(),
            "/a/%2e%2e/b"
        );
        assert_eq!(
            normalize_path("/%2e%2e/etc/passwd", false).unwrap(),
            "/%2e%2e/etc/passwd"
        );
    }

    #[test]
    fn test_normalize_query() {
        let result = normalize_query("key=value&foo=bar", true);
        assert_eq!(result, "key=value&foo=bar");
    }

    #[test]
    fn test_normalize_query_with_leading_question() {
        let result = normalize_query("?key=value", true);
        assert_eq!(result, "key=value");
    }

    #[test]
    fn test_normalize_query_empty() {
        let result = normalize_query("", true);
        assert!(result.is_empty());
    }

    #[test]
    fn test_normalize_host_key_cache_semantics() {
        // 小写 + trim
        assert_eq!(normalize_host_key("  ExAmPLE.com  "), "example.com");
        // FQDN 尾点折叠
        assert_eq!(normalize_host_key("example.com."), "example.com");
        assert_eq!(normalize_host_key("example.com.."), "example.com");
        // 无条件去默认端口（scheme 无关，缓存键折叠语义）
        assert_eq!(normalize_host_key("example.com:80"), "example.com");
        assert_eq!(normalize_host_key("example.com:443"), "example.com");
        // 非默认端口保留
        assert_eq!(normalize_host_key("example.com:8080"), "example.com:8080");
        // IPv6 字面量：方括号保留，外置端口按规则处理
        assert_eq!(normalize_host_key("[::1]:8080"), "[::1]:8080");
        assert_eq!(normalize_host_key("[::1]:443"), "[::1]");
        assert_eq!(normalize_host_key("[2001:db8::a]"), "[2001:db8::a]");
        // 非数字端口段不视为端口（保留整体原样，fail-closed 语义）
        assert_eq!(normalize_host_key("example.com:abc"), "example.com:abc");
        // 空输入
        assert_eq!(normalize_host_key(""), "");
    }

    #[test]
    fn test_normalize_authority_reverse_brackets_no_panic() {
        // 回归（fuzz 实证缺陷）：`]` 先于 `[` 时禁止切片反转 panic
        // （对端可控 Host 字段不得触发 DoS）
        let _ = normalize_authority("]x[", "https");
        let _ = normalize_authority("]:80[abc", "http");
        let _ = normalize_authority("[]", "https");
        // IPv6 合法形式仍正确
        assert_eq!(normalize_authority("[::1]:4444", "https"), "[::1]:4444");
        assert_eq!(normalize_authority("[::1]:443", "https"), "[::1]");
    }

    #[test]
    fn test_normalize_authority() {
        let result = normalize_authority("Example.COM:443", "https");
        assert_eq!(result, "example.com");
    }

    #[test]
    fn test_normalize_authority_non_default_port() {
        let result = normalize_authority("example.com:8080", "http");
        assert_eq!(result, "example.com:8080");
    }

    #[test]
    fn test_normalize_authority_http_default() {
        let result = normalize_authority("example.com:80", "http");
        assert_eq!(result, "example.com");
    }

    #[test]
    fn test_normalize_authority_ipv6() {
        let result = normalize_authority("[::1]:8080", "http");
        assert_eq!(result, "[::1]:8080");
    }

    #[test]
    fn test_normalize_headers_basic() {
        let headers = [("Content-Type", "application/json"), ("Accept", "text/html")];
        let result = normalize_request(
            Method::Get,
            "https",
            "example.com",
            "/test",
            "",
            &headers,
            Protocol::Http1,
            Transport::Tls13,
        )
        .unwrap();

        assert_eq!(result.find_header("content-type").unwrap().value_str(), "application/json");
        assert_eq!(result.find_header("accept").unwrap().value_str(), "text/html");
    }

    #[test]
    fn test_normalize_headers_merge() {
        let headers = [
            ("X-Custom", "value1"),
            ("x-custom", "value2"),
            ("Accept", "text/html"),
        ];
        let result = normalize_request(
            Method::Get,
            "https",
            "example.com",
            "/test",
            "",
            &headers,
            Protocol::Http1,
            Transport::Tls13,
        )
        .unwrap();

        // 合并后应该只有 2 个 header
        assert_eq!(result.header_count(), 2);
        // X-Custom 应该被合并
        let custom = result.find_header("x-custom").unwrap();
        assert!(custom.value_str().contains("value1"));
        assert!(custom.value_str().contains("value2"));
    }

    #[test]
    fn test_normalize_headers_merged_value_overlong_precise_error() {
        // SYS-026 回归：多个同名 header 聚合后总长超 MAX_HEADER_VALUE_LEN 时，
        // 必须返回精确错误 "header value too long"（原实现统一映射为
        // "header count exceeded"，掩盖超长合并这一 DoS 面）。
        let v100 = "a".repeat(100);
        let headers = [
            ("X-Big", v100.as_str()),
            ("x-big", v100.as_str()),
            ("X-BIG", v100.as_str()),
        ];
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
        );
        let err = result.expect_err("合并总长超限必须报错");
        assert_eq!(
            err.message, "header value too long",
            "合并超长必须返回精确错误而非 header count exceeded"
        );
    }

    #[test]
    fn test_normalize_headers_invalid_name() {
        let headers = [("Invalid Header!", "value"), ("Valid", "ok")];
        let result = normalize_request(
            Method::Get,
            "https",
            "example.com",
            "/test",
            "",
            &headers,
            Protocol::Http1,
            Transport::Tls13,
        );

        // 无效 header 名应导致整体规范化失败（fail-closed，不静默丢弃）
        let err = result.expect_err("invalid header name should be rejected");
        assert_eq!(err.message, "invalid header name");
    }

    #[test]
    fn test_is_valid_header_name() {
        assert!(is_valid_header_name("content-type"));
        assert!(is_valid_header_name("x-custom-header"));
        assert!(is_valid_header_name("Authorization"));
        assert!(!is_valid_header_name("invalid header"));
        assert!(!is_valid_header_name("header\r\n"));
    }

    #[test]
    fn test_full_normalize() {
        let headers = [
            ("Content-Type", "application/json"),
            ("Host", "Example.COM"),
        ];
        let result = normalize_request(
            Method::Post,
            "HTTPS",
            "Example.COM:443",
            "/Api/Test/./..",
            "?key=value",
            &headers,
            Protocol::Http2,
            Transport::Tls13,
        )
        .unwrap();

        assert_eq!(result.method, Method::Post);
        assert_eq!(result.scheme_str(), "https");
        assert_eq!(result.authority_str(), "example.com");
        // /Api/Test/./.. -> . 跳过, .. 弹出 Test, 结果为 /Api
        assert_eq!(result.path_str(), "/Api");
        assert_eq!(result.query_str(), "key=value");
        assert_eq!(result.find_header("content-type").unwrap().value_str(), "application/json");
        assert_eq!(result.find_header("host").unwrap().value_str(), "Example.COM");
    }

    #[test]
    fn test_safe_percent_decode() {
        let result = safe_percent_decode(b"hello%7Eworld");
        assert_eq!(result, b"hello~world");

        // 非 unreserved 字符不解码
        let result = safe_percent_decode(b"test%2Fpath");
        assert_eq!(result, b"test%2Fpath"); // 斜杠不解码
    }

    // ─────────────────────────────────────────────
    // 路径规范化 - 更多边界情况
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_path_trailing_slash() {
        // RFC 3986 §5.2.4：尾斜杠必须保留，区分目录与资源
        let result = normalize_path("/a/b/", true).unwrap();
        assert_eq!(result, "/a/b/");
    }

    #[test]
    fn test_normalize_path_only_dots() {
        // 全部是 .. 的情况，应该停在根
        let result = normalize_path("/../../../..", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_single_dot_root() {
        let result = normalize_path("/.", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_double_dot_root() {
        let result = normalize_path("/..", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_complex_dots() {
        let result = normalize_path("/a/b/c/./d/../e/../../f", true).unwrap();
        assert_eq!(result, "/a/b/f");
    }

    #[test]
    fn test_normalize_path_multiple_dots_in_segment() {
        // 段内的点不应该被当作 . 或 ..
        let result = normalize_path("/..hidden/.bashrc/test..", true).unwrap();
        assert_eq!(result, "/..hidden/.bashrc/test..");
    }

    #[test]
    fn test_normalize_path_no_leading_slash() {
        let result = normalize_path("a/b/c", true).unwrap();
        assert_eq!(result, "a/b/c");
    }

    #[test]
    fn test_normalize_path_single_segment() {
        let result = normalize_path("/test", true).unwrap();
        assert_eq!(result, "/test");
    }

    #[test]
    fn test_normalize_path_only_slashes() {
        let result = normalize_path("///", true).unwrap();
        assert_eq!(result, "/");
    }

    #[test]
    fn test_normalize_path_many_slashes() {
        let result = normalize_path("/a///b//c////d", true).unwrap();
        assert_eq!(result, "/a/b/c/d");
    }

    // ─────────────────────────────────────────────
    // 百分号解码 - 边界情况
    // ─────────────────────────────────────────────

    #[test]
    fn test_percent_decode_mixed_case_hex() {
        // 大小写混合的十六进制都应该能解码
        let result = safe_percent_decode(b"test%2fdata");
        assert_eq!(result, b"test%2fdata"); // %2f 是斜杠，属于保留字符，不解码

        let result = safe_percent_decode(b"hello%7eworld");
        assert_eq!(result, b"hello~world"); // %7e 是 ~，属于 unreserved
    }

    #[test]
    fn test_percent_decode_uppercase_hex() {
        let result = safe_percent_decode(b"hello%7Eworld");
        assert_eq!(result, b"hello~world");
    }

    #[test]
    fn test_percent_decode_incomplete_sequence() {
        // % 后面不足两位
        let result = safe_percent_decode(b"test%2");
        assert_eq!(result, b"test%2");

        let result = safe_percent_decode(b"test%");
        assert_eq!(result, b"test%");
    }

    #[test]
    fn test_percent_decode_invalid_hex() {
        // 非十六进制字符
        let result = safe_percent_decode(b"test%ZZdata");
        assert_eq!(result, b"test%ZZdata");
    }

    #[test]
    fn test_percent_decode_unreserved_chars() {
        // 测试所有 unreserved 字符的解码
        // A-Z, a-z, 0-9, -, _, ., ~
        let result = safe_percent_decode(b"%41%5A%61%7A%30%39%2D%5F%2E%7E");
        assert_eq!(result, b"AZaz09-_.~");
    }

    #[test]
    fn test_percent_decode_reserved_chars_kept() {
        // 保留字符应该保持编码状态
        let result = safe_percent_decode(b"%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D");
        assert_eq!(result, b"%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D");
    }

    #[test]
    fn test_percent_decode_multiple_sequences() {
        let result = safe_percent_decode(b"%7E%7Ehello%7Eworld%7E%7E");
        assert_eq!(result, b"~~hello~world~~");
    }

    #[test]
    fn test_percent_decode_empty_input() {
        let result = safe_percent_decode(b"");
        assert_eq!(result, b"");
    }

    // ─────────────────────────────────────────────
    // percent_decode（fail-closed 公开 API）
    // ─────────────────────────────────────────────

    #[test]
    fn test_percent_decode_pub_basic() {
        assert_eq!(percent_decode("hello%20world", false).unwrap(), "hello world");
        assert_eq!(percent_decode("%41%42%43", false).unwrap(), "ABC");
        assert_eq!(percent_decode("plain", false).unwrap(), "plain");
        assert_eq!(percent_decode("", false).unwrap(), "");
    }

    #[test]
    fn test_percent_decode_pub_plus_as_space() {
        // plus_as_space=true：'+' 解码为空格（表单语义）
        assert_eq!(percent_decode("a+b+c", true).unwrap(), "a b c");
        // plus_as_space=false：'+' 原样保留
        assert_eq!(percent_decode("a+b", false).unwrap(), "a+b");
        // %2B 始终解码为 '+'，与 plus_as_space 无关
        assert_eq!(percent_decode("a%2Bb", true).unwrap(), "a+b");
    }

    #[test]
    fn test_percent_decode_pub_invalid_sequences() {
        // '%' 在末尾（不足两位）→ None
        assert!(percent_decode("test%", false).is_none());
        assert!(percent_decode("test%2", false).is_none());
        // 非十六进制字符 → None
        assert!(percent_decode("test%ZZdata", false).is_none());
        assert!(percent_decode("%2g", false).is_none());
        assert!(percent_decode("%g2", false).is_none());
        // 解码结果非合法 UTF-8 → None
        assert!(percent_decode("%FF%FE", false).is_none());
    }

    #[test]
    fn test_percent_decode_pub_mixed_case_hex() {
        assert_eq!(percent_decode("%7e", false).unwrap(), "~");
        assert_eq!(percent_decode("%7E", false).unwrap(), "~");
        assert_eq!(percent_decode("%2f", false).unwrap(), "/");
        assert_eq!(percent_decode("%2F", false).unwrap(), "/");
    }

    // ─────────────────────────────────────────────
    // percent_decode_with_policy（统一解码 API）
    // ─────────────────────────────────────────────

    #[test]
    fn test_policy_reject_delegates_percent_decode() {
        // Reject 策略必须与 percent_decode 语义完全一致
        let cases = [
            "hello%20world",
            "a+b",
            "test%",
            "test%2",
            "test%ZZdata",
            "%FF%FE",
            "%41%42%43",
            "",
        ];
        for case in cases {
            for plus in [false, true] {
                assert_eq!(
                    percent_decode_with_policy(case, plus, InvalidSequencePolicy::Reject),
                    percent_decode(case, plus),
                    "Reject 策略与 percent_decode 不一致: {:?} (plus={})",
                    case,
                    plus
                );
            }
        }
    }

    #[test]
    fn test_policy_preserve_invalid_sequences() {
        // 非法 % 序列按原字节保留
        assert_eq!(
            percent_decode_with_policy("test%ZZdata", false, InvalidSequencePolicy::Preserve).unwrap(),
            "test%ZZdata"
        );
        assert_eq!(
            percent_decode_with_policy("%", false, InvalidSequencePolicy::Preserve).unwrap(),
            "%"
        );
        assert_eq!(
            percent_decode_with_policy("%2", false, InvalidSequencePolicy::Preserve).unwrap(),
            "%2"
        );
        // 混合：合法序列正常解码，非法序列保留
        assert_eq!(
            percent_decode_with_policy("100%+pure", true, InvalidSequencePolicy::Preserve).unwrap(),
            "100% pure"
        );
        // 保留后仍可能形成新的合法序列边界：%2 后跟 Z 不消费 Z
        assert_eq!(
            percent_decode_with_policy("%2Z%41", false, InvalidSequencePolicy::Preserve).unwrap(),
            "%2ZA"
        );
    }

    #[test]
    fn test_policy_preserve_invalid_utf8_rejected() {
        // Preserve 策略下非法 UTF-8 仍整体拒绝（字符串级 API 约束）
        assert!(percent_decode_with_policy("%FF", false, InvalidSequencePolicy::Preserve).is_none());
        assert!(percent_decode_with_policy("%FF%FE", true, InvalidSequencePolicy::Preserve).is_none());
    }

    #[test]
    fn test_policy_preserve_plus_as_space() {
        assert_eq!(
            percent_decode_with_policy("a+b+c", true, InvalidSequencePolicy::Preserve).unwrap(),
            "a b c"
        );
        assert_eq!(
            percent_decode_with_policy("a+b", false, InvalidSequencePolicy::Preserve).unwrap(),
            "a+b"
        );
    }

    // ─────────────────────────────────────────────
    // 字节级解码（percent_decode_bytes / percent_decode_bytes_into）
    // ─────────────────────────────────────────────

    #[test]
    fn test_percent_decode_bytes_basic() {
        assert_eq!(percent_decode_bytes(b"hello%20world", false), b"hello world");
        assert_eq!(percent_decode_bytes(b"a+b", true), b"a b");
        assert_eq!(percent_decode_bytes(b"a+b", false), b"a+b");
        // 非法序列保留
        assert_eq!(percent_decode_bytes(b"%ZZ", false), b"%ZZ");
        assert_eq!(percent_decode_bytes(b"%", false), b"%");
        assert_eq!(percent_decode_bytes(b"%2", false), b"%2");
        // 字节级不做 UTF-8 校验
        assert_eq!(percent_decode_bytes(b"%FF", false), b"\xFF");
        assert_eq!(percent_decode_bytes(b"", false), b"");
    }

    #[test]
    fn test_percent_decode_bytes_into_basic() {
        let mut buf = [0u8; 64];
        assert_eq!(
            percent_decode_bytes_into(b"id=%27+OR+%271%27%3D%271", &mut buf, true),
            Some(&b"id=' OR '1'='1"[..])
        );
        // 非 UTF-8 字节允许存在
        assert_eq!(
            percent_decode_bytes_into(b"%FF", &mut buf, true),
            Some(&b"\xFF"[..])
        );
        // 非法序列保留
        assert_eq!(
            percent_decode_bytes_into(b"%ZZ", &mut buf, true),
            Some(&b"%ZZ"[..])
        );
    }

    #[test]
    fn test_percent_decode_bytes_into_buffer_overflow_fail_closed() {
        // 输出超过缓冲区容量 → fail-closed 返回 None（禁止截断放行）
        let mut tiny = [0u8; 2];
        assert_eq!(percent_decode_bytes_into(b"abcdef", &mut tiny, true), None);
        // 恰好填满缓冲区 → 成功
        let mut exact = [0u8; 6];
        assert_eq!(
            percent_decode_bytes_into(b"abcdef", &mut exact, true),
            Some(&b"abcdef"[..])
        );
        // 空输入 + 空缓冲区 → 成功（无输出需求）
        let mut empty: [u8; 0] = [];
        assert_eq!(
            percent_decode_bytes_into(b"", &mut empty, true),
            Some(&b""[..])
        );
    }

    #[test]
    fn test_hex_value_all() {
        assert_eq!(hex_value(b'0'), Some(0));
        assert_eq!(hex_value(b'9'), Some(9));
        assert_eq!(hex_value(b'a'), Some(10));
        assert_eq!(hex_value(b'f'), Some(15));
        assert_eq!(hex_value(b'A'), Some(10));
        assert_eq!(hex_value(b'F'), Some(15));
        assert_eq!(hex_value(b'g'), None);
        assert_eq!(hex_value(b'G'), None);
        assert_eq!(hex_value(b' '), None);
        assert_eq!(hex_value(b'%'), None);
    }

    // ─────────────────────────────────────────────
    // 查询字符串规范化 - 更多边界
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_query_multiple_question_marks() {
        // 前导 '?' 全部移除；query 中间的 '?' 是合法数据字符，必须保留完整
        let result = normalize_query("??key=value??foo=bar", true);
        assert_eq!(result, "key=value??foo=bar");
    }

    #[test]
    fn test_normalize_query_whitespace_normalization() {
        // Unicode 空白 → ASCII 空格保留；%20 非 unreserved（RFC 3986），decode=true 也不解码
        let result = normalize_query("key=hello%20world\t\n", true);
        assert_eq!(result, "key=hello%20world  ");
    }

    #[test]
    fn test_normalize_query_decode_true_unreserved_only() {
        // decode=true：与路径相同的 unreserved-only 解码
        assert_eq!(normalize_query("a=%41%2e%2e&b=%7E", true), "a=A..&b=~");
        // reserved 字符保持编码态
        assert_eq!(normalize_query("p=%2f%3F%23", true), "p=%2f%3F%23");
        // 非法 % 序列按字节透传（safe_percent_decode 语义）
        assert_eq!(normalize_query("q=100%+pure", true), "q=100%+pure");
    }

    #[test]
    fn test_normalize_query_decode_false_passthrough() {
        // decode=false：保留原始编码（现状行为不变）
        assert_eq!(normalize_query("a=%41%2e&b=%2f", false), "a=%41%2e&b=%2f");
        // 空白映射不受 decode 开关影响
        assert_eq!(normalize_query("a=b\tc", false), "a=b c");
    }

    #[test]
    fn test_normalize_query_only_question_marks() {
        let result = normalize_query("???", true);
        assert_eq!(result, "");
    }

    #[test]
    fn test_normalize_query_complex() {
        let result = normalize_query("?a=1&b=2&c=3", true);
        assert_eq!(result, "a=1&b=2&c=3");
    }

    // ─────────────────────────────────────────────
    // Authority 规范化 - 更多边界
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_authority_empty() {
        let result = normalize_authority("", "http");
        assert_eq!(result, "");
    }

    #[test]
    fn test_normalize_authority_no_port_http() {
        let result = normalize_authority("example.com", "http");
        assert_eq!(result, "example.com");
    }

    #[test]
    fn test_normalize_authority_no_port_https() {
        let result = normalize_authority("example.com", "https");
        assert_eq!(result, "example.com");
    }

    #[test]
    fn test_normalize_authority_host_lowercase() {
        let result = normalize_authority("EXAMPLE.COM", "http");
        assert_eq!(result, "example.com");
    }

    #[test]
    fn test_normalize_authority_mixed_case() {
        let result = normalize_authority("My-Host.Example.COM:8080", "http");
        assert_eq!(result, "my-host.example.com:8080");
    }

    #[test]
    fn test_normalize_authority_non_numeric_port() {
        // 非数字端口应该被当作主机名的一部分
        let result = normalize_authority("example.com:http", "http");
        assert_eq!(result, "example.com:http");
    }

    #[test]
    fn test_normalize_authority_ipv6_no_port() {
        let result = normalize_authority("[::1]", "http");
        assert_eq!(result, "[::1]");
    }

    #[test]
    fn test_normalize_authority_ipv6_default_port() {
        let result = normalize_authority("[::1]:443", "https");
        assert_eq!(result, "[::1]");
    }

    #[test]
    fn test_normalize_authority_ipv6_unclosed_bracket() {
        let result = normalize_authority("[::1:8080", "http");
        assert_eq!(result, "[::1:8080");
    }

    #[test]
    fn test_normalize_authority_unknown_scheme() {
        // 未知协议不省略任何端口
        let result = normalize_authority("example.com:1234", "ftp");
        assert_eq!(result, "example.com:1234");
    }

    // ─────────────────────────────────────────────
    // Header 规范化 - 更多场景
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_headers_pseudo_headers_filtered() {
        let headers = [
            (":method", "GET"),
            (":path", "/test"),
            (":scheme", "https"),
            ("content-type", "application/json"),
        ];
        let result = normalize_request(
            Method::Get,
            "https",
            "example.com",
            "/test",
            "",
            &headers,
            Protocol::Http2,
            Transport::Tls13,
        )
        .unwrap();

        // 伪头部应该被过滤掉
        assert_eq!(result.header_count(), 1);
        assert!(result.find_header("content-type").is_some());
    }

    #[test]
    fn test_normalize_headers_value_trim() {
        let headers = [("X-Test", "  hello world  ")];
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
        )
        .unwrap();

        let hdr = result.find_header("x-test").unwrap();
        assert_eq!(hdr.value_str(), "hello world");
    }

    #[test]
    fn test_normalize_headers_empty_value() {
        let headers = [("X-Empty", ""), ("X-Normal", "value")];
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
        )
        .unwrap();

        assert_eq!(result.header_count(), 2);
        assert_eq!(result.find_header("x-empty").unwrap().value_str(), "");
    }

    #[test]
    fn test_normalize_headers_no_merge_mode() {
        let config = NormalizeConfig {
            merge_headers: false,
            ..NormalizeConfig::default()
        };
        let headers = [("X-Custom", "v1"), ("x-custom", "v2")];
        let result = normalize_request_with_config(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
            config,
        )
        .unwrap();

        // 不合并模式下，同名 header 保留两个
        assert_eq!(result.header_count(), 2);
    }

    #[test]
    fn test_normalize_headers_no_normalize_case() {
        let config = NormalizeConfig {
            normalize_case: false,
            ..NormalizeConfig::default()
        };
        let headers = [("Content-Type", "application/json")];
        let result = normalize_request_with_config(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
            config,
        )
        .unwrap();

        // 不规范化大小写：存储保留原始大小写；
        // find_header 按 RFC 7230 §3.2 大小写不敏感，两种写法都能命中
        assert!(result.find_header("Content-Type").is_some());
        assert!(result.find_header("content-type").is_some());
        let hdr = result.find_header("content-type").unwrap();
        assert_eq!(hdr.name_str(), "Content-Type");
    }

    #[test]
    fn test_normalize_headers_all_config_off() {
        let config = NormalizeConfig {
            decode_path: false,
            merge_headers: false,
            normalize_case: false,
        };
        let headers = [("X-Test", "A"), ("x-test", "B")];
        let result = normalize_request_with_config(
            Method::Get,
            "HTTP",
            "Example.COM",
            "/hello%20world",
            "",
            &headers,
            Protocol::Http1,
            Transport::Plaintext,
            config,
        )
        .unwrap();

        // scheme 不规范化
        assert_eq!(result.scheme_str(), "HTTP");
        // 路径不解码
        assert_eq!(result.path_str(), "/hello%20world");
        // header 不合并，大小不变
        assert_eq!(result.header_count(), 2);
    }

    #[test]
    fn test_normalize_headers_header_count_exceeded() {
        let mut header_names: Vec<String> = Vec::new();
        for i in 0..100 {
            header_names.push(format!("X-Header-{}", i));
        }
        let header_refs: Vec<(&str, &str)> = header_names.iter().map(|k| (k.as_str(), "value")).collect();

        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            "/",
            "",
            &header_refs,
            Protocol::Http1,
            Transport::Plaintext,
        );

        // 超过最大 header 数量应该失败
        assert!(result.is_err());
    }

    // ─────────────────────────────────────────────
    // is_valid_header_name 更多边界
    // ─────────────────────────────────────────────

    #[test]
    fn test_is_valid_header_name_all_special_chars() {
        // 所有允许的特殊字符
        assert!(is_valid_header_name("!#$%&'*+-.^_`|~"));
    }

    #[test]
    fn test_is_valid_header_name_empty() {
        assert!(!is_valid_header_name(""));
    }

    #[test]
    fn test_is_valid_header_name_with_spaces() {
        assert!(!is_valid_header_name("content type"));
    }

    #[test]
    fn test_is_valid_header_name_with_colon() {
        assert!(!is_valid_header_name("content-type:"));
    }

    #[test]
    fn test_is_valid_header_name_with_newline() {
        assert!(!is_valid_header_name("content\r\ntype"));
    }

    #[test]
    fn test_is_valid_header_name_with_null() {
        assert!(!is_valid_header_name("content\0type"));
    }

    // ─────────────────────────────────────────────
    // NormalizeError Display 测试
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_error_display() {
        let err = NormalizeError {
            message: "test error message",
        };
        assert_eq!(
            format!("{}", err),
            "NormalizeError: test error message"
        );
    }

    // ─────────────────────────────────────────────
    // NormalizeConfig 默认值测试
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_config_default() {
        let config = NormalizeConfig::default();
        assert!(config.decode_path);
        assert!(config.merge_headers);
        assert!(config.normalize_case);
    }

    // ─────────────────────────────────────────────
    // 完整规范化 - 各种协议组合
    // ─────────────────────────────────────────────

    #[test]
    fn test_full_normalize_http1_plaintext() {
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com:80",
            "/path/../to/./resource",
            "?q=test",
            &[("Host", "example.com"), ("Accept", "text/html")],
            Protocol::Http1,
            Transport::Plaintext,
        )
        .unwrap();

        assert_eq!(result.method, Method::Get);
        assert_eq!(result.protocol, Protocol::Http1);
        assert_eq!(result.transport, Transport::Plaintext);
        assert_eq!(result.scheme_str(), "http");
        assert_eq!(result.authority_str(), "example.com");
        assert_eq!(result.path_str(), "/to/resource");
        assert_eq!(result.query_str(), "q=test");
    }

    #[test]
    fn test_full_normalize_http2_tls() {
        let result = normalize_request(
            Method::Post,
            "https",
            "api.example.com:443",
            "/api/v1/data",
            "verbose=true",
            &[
                (":method", "POST"),
                (":scheme", "https"),
                (":path", "/api/v1/data"),
                ("content-type", "application/json"),
                ("content-type", "text/plain"),
            ],
            Protocol::Http2,
            Transport::Tls13,
        )
        .unwrap();

        assert_eq!(result.protocol, Protocol::Http2);
        assert_eq!(result.transport, Transport::Tls13);
        // 伪头部被过滤
        assert_eq!(result.header_count(), 1);
        // 同名 header 被合并
        let ct = result.find_header("content-type").unwrap();
        assert!(ct.value_str().contains("application/json"));
        assert!(ct.value_str().contains("text/plain"));
    }

    #[test]
    fn test_full_normalize_http3() {
        let result = normalize_request(
            Method::Get,
            "https",
            "quic.example.com",
            "/",
            "",
            &[("user-agent", "test-agent")],
            Protocol::Http3,
            Transport::Tls13,
        )
        .unwrap();

        assert_eq!(result.protocol, Protocol::Http3);
        assert_eq!(result.transport, Transport::Tls13);
        assert_eq!(result.path_str(), "/");
    }

    // ─────────────────────────────────────────────
    // 方法规范化（通过 normalize_request）
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_all_methods() {
        let methods = [
            Method::Get,
            Method::Post,
            Method::Put,
            Method::Delete,
            Method::Patch,
            Method::Head,
            Method::Options,
            Method::Connect,
            Method::Trace,
        ];

        for method in methods.iter() {
            let result = normalize_request(
                *method,
                "http",
                "example.com",
                "/",
                "",
                &[],
                Protocol::Http1,
                Transport::Plaintext,
            )
            .unwrap();
            assert_eq!(result.method, *method);
        }
    }

    // ─────────────────────────────────────────────
    // normalize_request 链路 fail-closed（超长拒绝，禁止静默截断）
    // ─────────────────────────────────────────────

    #[test]
    fn test_normalize_request_overlong_path_rejected() {
        let long_path = format!("/{}", "a".repeat(crate::MAX_PATH_LEN + 1));
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            &long_path,
            "",
            &[],
            Protocol::Http1,
            Transport::Plaintext,
        );
        let err = result.expect_err("超长路径必须报错");
        assert_eq!(err.message, "path too long");
    }

    #[test]
    fn test_normalize_request_overlong_query_rejected() {
        let long_query = "a".repeat(crate::MAX_QUERY_LEN + 1);
        let result = normalize_request(
            Method::Get,
            "http",
            "example.com",
            "/",
            &long_query,
            &[],
            Protocol::Http1,
            Transport::Plaintext,
        );
        let err = result.expect_err("超长 query 必须报错");
        assert_eq!(err.message, "query too long");
    }

    #[test]
    fn test_normalize_request_overlong_authority_rejected() {
        let long_authority = "a".repeat(crate::MAX_AUTHORITY_LEN + 1);
        let result = normalize_request(
            Method::Get,
            "http",
            &long_authority,
            "/",
            "",
            &[],
            Protocol::Http1,
            Transport::Plaintext,
        );
        let err = result.expect_err("超长 authority 必须报错");
        assert_eq!(err.message, "authority too long");
    }

    #[test]
    fn test_normalize_request_overlong_scheme_rejected() {
        // scheme 固定容量 8 字节，超长整体拒绝
        let result = normalize_request(
            Method::Get,
            "superlongscheme",
            "example.com",
            "/",
            "",
            &[],
            Protocol::Http1,
            Transport::Plaintext,
        );
        let err = result.expect_err("超长 scheme 必须报错");
        assert_eq!(err.message, "scheme too long");
    }

    // ─────────────────────────────────────────────
    // normalize_authority 与 normalize_host_key 语义对照（锁定既定分工）
    // ─────────────────────────────────────────────

    #[test]
    fn test_authority_vs_host_key_semantics_lock() {
        // 默认端口策略：authority scheme 感知；host_key 无条件剥 80/443
        // http 下 443 非默认端口
        assert_eq!(
            normalize_authority("Example.COM:443", "http"),
            "example.com:443"
        );
        assert_eq!(normalize_host_key("Example.COM:443"), "example.com");
        // https 下两者都省略 443
        assert_eq!(
            normalize_authority("Example.COM:443", "https"),
            "example.com"
        );

        // FQDN 尾点：authority 保留，host_key 剥离
        assert_eq!(normalize_authority("example.com.", "http"), "example.com.");
        assert_eq!(normalize_host_key("example.com."), "example.com");

        // IPv6：http 下 443 非默认 → authority 保留；host_key 无条件剥离
        assert_eq!(normalize_authority("[::1]:443", "http"), "[::1]:443");
        assert_eq!(normalize_host_key("[::1]:443"), "[::1]");
        // https 下 authority 同样省略
        assert_eq!(normalize_authority("[::1]:443", "https"), "[::1]");

        // 空白：host_key trim，authority 不 trim
        assert_eq!(normalize_host_key("  example.com  "), "example.com");
        assert_eq!(
            normalize_authority("  example.com  ", "http"),
            "  example.com  "
        );
    }
}