zenith-net 0.1.0

//! zenith-net QUIC 服务器（RFC 9000 完整传输层）
//!
//! 基于 zenith-tls QuicCryptoSession + std::net::UdpSocket 提供真实的 QUIC 传输层：
//! - Long Header (Initial / Handshake) 解析与构造
//! - Short Header (1-RTT) 解析与构造
//! - Header Protection 移除 / 应用
//! - Packet Protection (AEAD) 解密 / 加密
//! - CRYPTO / STREAM / ACK / PADDING 帧解析与构造
//! - TLS 1.3 握手完整驱动（通过 zenith-tls::QuicCryptoSession）
//! - 单连接阻塞模式（demo 友好）
//!
//! # 数据流
//! ```text
//! UdpSocket::recv_from → QuicServer::handle_packet
//!     → parse_long_header → derive Initial keys (QuicCryptoSession)
//!     → remove HP + AEAD decrypt → CRYPTO frames → rustls::read_hs
//!     → rustls::write_hs → ServerHello + Cert + Finished + Handshake keys
//!     → AEAD encrypt + apply HP → build Long Header Handshake packet
//!     → UdpSocket::send_to
//! ```
//!
//! # 安全保证
//! - 所有 rustls crypto 调用包装为 Result
//! - 1-RTT keys 在握手完成前不可用（fail-closed）
//! - 包号单调递增（防重放）
//! - 防放大：发送字节数 ≤ 3 × 接收字节数（RFC 9000 §8.1）

use std::collections::VecDeque;
use std::net::{SocketAddr, UdpSocket};
use std::sync::Arc;
use std::time::{Duration, Instant};

use rustc_hash::{FxHashMap, FxHashSet};

use super::quic::CongestionController;
// parse_varint 已迁移至 quic 模块共享；re-export 以保持
// mod.rs 的 `use quic_server::parse_varint` 及本文件内引用有效
pub use super::quic::parse_varint;

use zenith_tls::quic::{
    apply_header_protection, decrypt_packet, remove_header_protection,
    QuicCryptoError, QuicCryptoSession, QuicVersion,
};
use zenith_tls::CertGeneration;
use zenith_tls::fingerprint::Ja3Fingerprint;

use rustls::quic::Keys;

/// QUIC v1 版本号
pub const QUIC_VERSION_V1: u32 = 0x00000001;
/// QUIC v2 版本号
pub const QUIC_VERSION_V2: u32 = 0x6b3343cf;

/// QUIC Long Header Fixed Bits 标志（bit 7 = 1）
pub const LONG_HEADER_FLAG: u8 = 0x80;

/// Long Header Initial 类型（bits 6-5 = 00）
pub const LONG_TYPE_INITIAL: u8 = 0x00;
/// Long Header 0-RTT 类型（bits 6-5 = 01）
pub const LONG_TYPE_0RTT: u8 = 0x20;
/// Long Header Handshake 类型（bits 6-5 = 10）
pub const LONG_TYPE_HANDSHAKE: u8 = 0x40;
/// Long Header Retry 类型（bits 6-5 = 11）
pub const LONG_TYPE_RETRY: u8 = 0x60;

/// 帧类型常量（RFC 9000 §19）：PADDING 帧，用于填充包体以达最小包长
pub const FRAME_PADDING: u64 = 0x00;
/// PING 帧，用于保持连接活跃或探查对端可达性
pub const FRAME_PING: u64 = 0x01;
/// ACK 帧，向对端确认已接收的数据包号
pub const FRAME_ACK: u64 = 0x02;
/// 带 ECN 反馈的 ACK 帧，携带 ECN 计数信息
pub const FRAME_ACK_ECN: u64 = 0x03;
/// RESET_STREAM 帧，主动中止某个流的发送方向
pub const FRAME_RESET_STREAM: u64 = 0x04;
/// STOP_SENDING 帧，请求对端停止向指定流发送数据
pub const FRAME_STOP_SENDING: u64 = 0x05;
/// CRYPTO 帧，承载 TLS 握手字节流
pub const FRAME_CRYPTO: u64 = 0x06;
/// NEW_TOKEN 帧，向客户端下发地址验证令牌
pub const FRAME_NEW_TOKEN: u64 = 0x07;
/// STREAM 帧，承载应用层流数据
pub const FRAME_STREAM: u64 = 0x08;
/// MAX_DATA 帧，提升连接级数据流量上限
pub const FRAME_MAX_DATA: u64 = 0x10;
/// MAX_STREAM_DATA 帧，提升单个流的数据流量上限
pub const FRAME_MAX_STREAM_DATA: u64 = 0x11;
/// MAX_STREAMS 帧双向流上限，提升可建立的双向流总数
pub const FRAME_MAX_STREAMS_BIDI: u64 = 0x12;
/// MAX_STREAMS 帧单向流上限，提升可建立的单向流总数
pub const FRAME_MAX_STREAMS_UNI: u64 = 0x13;
/// DATA_BLOCKED 帧，连接级流量受限通知
pub const FRAME_DATA_BLOCKED: u64 = 0x14;
/// STREAM_DATA_BLOCKED 帧，单流流量受限通知
pub const FRAME_STREAM_DATA_BLOCKED: u64 = 0x15;
/// STREAMS_BLOCKED 帧双向流受限通知
pub const FRAME_STREAMS_BLOCKED_BIDI: u64 = 0x16;
/// STREAMS_BLOCKED 帧单向流受限通知
pub const FRAME_STREAMS_BLOCKED_UNI: u64 = 0x17;
/// NEW_CONNECTION_ID 帧，向对端提供新的连接 ID 及其重置令牌
pub const FRAME_NEW_CONNECTION_ID: u64 = 0x18;
/// RETIRE_CONNECTION_ID 帧，通知对端退役某个连接 ID
pub const FRAME_RETIRE_CONNECTION_ID: u64 = 0x19;
/// PATH_CHALLENGE 帧，路径连通性探测请求
pub const FRAME_PATH_CHALLENGE: u64 = 0x1a;
/// PATH_RESPONSE 帧，对 PATH_CHALLENGE 的应答
pub const FRAME_PATH_RESPONSE: u64 = 0x1b;
/// CONNECTION_CLOSE 帧，因传输层错误关闭连接
pub const FRAME_CONNECTION_CLOSE: u64 = 0x1c;
/// CONNECTION_CLOSE 帧（应用层错误码），因应用层错误关闭连接
pub const FRAME_CONNECTION_CLOSE_APP: u64 = 0x1d;
/// HANDSHAKE_DONE 帧，服务端确认握手完成
pub const FRAME_HANDSHAKE_DONE: u64 = 0x1e;

/// CRYPTO 流重组缓冲区最大大小（65536 字节，防止恶意 CRYPTO 帧耗尽内存）
const MAX_CRYPTO_BUFFER_SIZE: usize = 65536;

/// QUIC 服务器错误
#[derive(Debug, thiserror::Error)]
pub enum QuicServerError {
    /// 加密错误
    #[error("crypto error: {0}")]
    Crypto(#[from] QuicCryptoError),
    /// rustls 错误
    #[error("rustls error: {0}")]
    Rustls(#[from] rustls::Error),
    /// IO 错误
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
    /// 包格式错误
    #[error("packet parse error: {0}")]
    PacketParse(String),
    /// 握手未完成
    #[error("handshake not complete")]
    HandshakeNotComplete,
    /// 接收超时
    #[error("recv timeout")]
    Timeout,
    /// 连接已关闭
    #[error("connection closed")]
    ConnectionClosed,
    /// 流控超限（RFC 9000 §4 FLOW_CONTROL_ERROR）
    #[error("flow control error: {0}")]
    FlowControl(String),
    /// 加密安全随机源不可用
    ///
    /// CSPRNG 失败时 fail-closed：拒绝构造配置，绝不回退为可预测的
    /// 全零/固定 SCID（可枚举 SCID 会导致连接 ID 猜测与会话劫持）。
    #[error("secure random source unavailable: {0}")]
    RandomUnavailable(String),
}

/// QUIC Long Header 包号长度（low 2 bits of first byte + 1）
#[inline]
fn packet_number_len(first_byte: u8) -> usize {
    ((first_byte & 0x03) + 1) as usize
}

/// 编码 QUIC 变长整数（RFC 9000 §16，最小长度编码）
///
/// **唯一实现约定**：编码实现统一自 [`zenith_foundation::varint::encode_varint`]
/// （全 workspace 唯一实现，§16 语义经 RFC 9000 §A.1 已知值在
/// zenith_foundation::varint 测试锁定；≥2^62 严格拒绝）。
/// 解码来源为 [`super::quic::parse_varint`]（本文件顶部 re-export 为
/// [`parse_varint`]）。
///
/// 值域契约：QUIC 头构造字段（包号 / stream id / offset / length / error
/// code）受协议不变量约束必 < 2^62（对端值经 8 字节 varint 解析天然满足），
/// 故本函数以 `assert!` 断言该内部不变量，而非运行时载荷分支。
pub fn encode_varint(v: u64) -> Vec<u8> {
    assert!(
        v <= zenith_foundation::varint::MAX_VARINT_VALUE,
        "QUIC varint 值域契约违反: {v} >= 2^62"
    );
    let mut out = Vec::with_capacity(zenith_foundation::varint::MAX_VARINT_SIZE);
    // 内部不变量保证成功；assert! 在 release 构建同样拦截违约值，
    // 绝不产生截断的高位编码
    let _ = zenith_foundation::varint::encode_varint(v, &mut out);
    out
}

/// 追加 QUIC varint 编码到 out（RFC 9000 §16 最小长度编码，栈缓冲零堆分配）
///
/// 与 [`encode_varint`] 同语义、同值域契约（内部不变量 v < 2^62，
/// `assert!` 断言）；供帧构造热路径复用，消除逐 varint `Vec` 堆分配。
#[inline]
fn push_varint(out: &mut Vec<u8>, v: u64) {
    assert!(
        v <= zenith_foundation::varint::MAX_VARINT_VALUE,
        "QUIC varint 值域契约违反: {v} >= 2^62"
    );
    let mut buf = [0u8; zenith_foundation::varint::MAX_VARINT_SIZE];
    if let Ok(n) = zenith_foundation::varint::encode_varint_buf(v, &mut buf) {
        out.extend_from_slice(&buf[..n]);
    }
}

/// 解析后的 QUIC Long Header
#[derive(Debug, Clone)]
pub struct ParsedLongHeader {
    /// 第一字节
    pub first_byte: u8,
    /// 版本
    pub version: u32,
    /// DCID
    pub dcid: Vec<u8>,
    /// SCID
    pub scid: Vec<u8>,
    /// Token (仅 Initial)
    pub token: Vec<u8>,
    /// 长度字段值
    pub length: u64,
    /// 包号（已从 4 字节还原，但还需 HP 移除）
    pub packet_number_raw: u64,
    /// 包号字节数
    pub packet_number_len: usize,
    /// 包号字段在原始包中的字节偏移
    pub pn_offset: usize,
    /// 加密 payload 偏移（包号之后）
    pub payload_offset: usize,
    /// 加密 payload 长度
    pub payload_len: usize,
    /// Long Frame Type (Initial/Handshake/0-RTT/Retry)
    pub long_frame: u8,
}

/// 解析 Long Header 完整信息
pub fn parse_long_header_full(buf: &[u8]) -> Result<ParsedLongHeader, QuicServerError> {
    if buf.len() < 6 {
        return Err(QuicServerError::PacketParse("packet too short".into()));
    }
    let first = buf[0];
    if (first & 0x80) == 0 {
        return Err(QuicServerError::PacketParse("not a long header".into()));
    }
    let version = u32::from_be_bytes([buf[1], buf[2], buf[3], buf[4]]);
    // RFC 9000 §17.2：Fixed Bit (0x40) 必须为 1。
    // 唯一例外是 Version Negotiation 包（version == 0，首字节 Unused 位全 0）。
    // 攻击者若篡改该位为 0，应 fail-closed 丢弃，而非继续解析。
    if version != 0 && (first & 0x40) == 0 {
        return Err(QuicServerError::PacketParse(
            "long header fixed bit (0x40) must be set".into(),
        ));
    }
    let mut off = 5;

    // DCID
    if off >= buf.len() {
        return Err(QuicServerError::PacketParse("dcid len missing".into()));
    }
    let dcid_len = buf[off] as usize;
    off += 1;
    // checked 算术：dcid_len 为攻击者可控字节，溢出即 fail-closed（§4.4）
    let dcid_end = off
        .checked_add(dcid_len)
        .ok_or_else(|| QuicServerError::PacketParse("dcid offset overflow".into()))?;
    if dcid_len > 20 || dcid_end > buf.len() {
        return Err(QuicServerError::PacketParse("dcid out of bounds".into()));
    }
    let dcid = buf[off..dcid_end].to_vec();
    off = dcid_end;

    // SCID
    if off >= buf.len() {
        return Err(QuicServerError::PacketParse("scid len missing".into()));
    }
    let scid_len = buf[off] as usize;
    off += 1;
    // checked 算术：scid_len 为攻击者可控字节，溢出即 fail-closed（§4.4）
    let scid_end = off
        .checked_add(scid_len)
        .ok_or_else(|| QuicServerError::PacketParse("scid offset overflow".into()))?;
    if scid_len > 20 || scid_end > buf.len() {
        return Err(QuicServerError::PacketParse("scid out of bounds".into()));
    }
    let scid = buf[off..scid_end].to_vec();
    off = scid_end;

    // Long Frame Type
    let long_frame = (first & 0x30) >> 4; // 0=Initial, 1=0-RTT, 2=Handshake, 3=Retry

    // Token (仅 Initial)
    let mut token = Vec::new();
    if long_frame == 0 && version != 0 {
        // Initial：first byte bit 5 (0x20) 表示有 Token
        // 实际上 Token 字段总是存在（变长长度可能为 0）
        if off >= buf.len() {
            return Err(QuicServerError::PacketParse("token len missing".into()));
        }
        let (token_len, token_len_bytes) = parse_varint(&buf[off..])
            .ok_or_else(|| QuicServerError::PacketParse("token varint parse failed".into()))?;
        off += token_len_bytes;
        // checked 算术：token_len 为攻击者可控 varint（最大 2^62-1），溢出即 fail-closed
        let token_end = off
            .checked_add(token_len as usize)
            .ok_or_else(|| QuicServerError::PacketParse("token offset overflow".into()))?;
        if token_end > buf.len() {
            return Err(QuicServerError::PacketParse("token out of bounds".into()));
        }
        token = buf[off..token_end].to_vec();
        off = token_end;
    }

    // Length 字段（变长）
    if off >= buf.len() {
        return Err(QuicServerError::PacketParse("length missing".into()));
    }
    let (length, length_bytes) = parse_varint(&buf[off..])
        .ok_or_else(|| QuicServerError::PacketParse("length varint parse failed".into()))?;
    off += length_bytes;

    // Packet Number（1-4 字节，长度由 first & 0x03 决定）
    let pn_len = packet_number_len(first);
    let pn_end = off
        .checked_add(pn_len)
        .ok_or_else(|| QuicServerError::PacketParse("pn offset overflow".into()))?;
    if pn_end > buf.len() {
        return Err(QuicServerError::PacketParse("pn out of bounds".into()));
    }
    let mut pn: u64 = 0;
    // 切片迭代替代 off + i 索引加法（pn_end 已校验 ≤ buf.len()）
    for &b in &buf[off..pn_end] {
        pn = (pn << 8) | (b as u64);
    }
    let pn_offset = off;
    off = pn_end;

    // Payload（加密的，长度为 length - pn_len）
    let length_usize = length as usize;
    if length_usize < pn_len {
        return Err(QuicServerError::PacketParse("length less than pn_len".into()));
    }
    let payload_len = length_usize - pn_len;
    let payload_end = off
        .checked_add(payload_len)
        .ok_or_else(|| QuicServerError::PacketParse("payload offset overflow".into()))?;
    if payload_end > buf.len() {
        return Err(QuicServerError::PacketParse("payload out of bounds".into()));
    }

    Ok(ParsedLongHeader {
        first_byte: first,
        version,
        dcid,
        scid,
        token,
        length,
        packet_number_raw: pn,
        packet_number_len: pn_len,
        pn_offset,
        payload_offset: off,
        payload_len,
        long_frame,
    })
}

/// 解析后的 Short Header (1-RTT)
#[derive(Debug, Clone)]
pub struct ParsedShortHeader {
    /// 第一字节
    pub first_byte: u8,
    /// DCID
    pub dcid: Vec<u8>,
    /// 包号字段偏移
    pub pn_offset: usize,
    /// 包号字节数
    pub packet_number_len: usize,
    /// 包号（已还原，需 HP 移除）
    pub packet_number_raw: u64,
    /// 加密 payload 偏移
    pub payload_offset: usize,
}

/// 解析 Short Header
///
/// dcid_len 由调用方提供（服务端知道自己的 DCID 长度）
pub fn parse_short_header(
    buf: &[u8],
    dcid_len: usize,
) -> Result<ParsedShortHeader, QuicServerError> {
    if buf.is_empty() {
        return Err(QuicServerError::PacketParse("empty short header".into()));
    }
    let first = buf[0];
    if (first & 0x80) != 0 {
        return Err(QuicServerError::PacketParse("not a short header".into()));
    }
    let pn_len = packet_number_len(first);
    let mut off: usize = 1;
    // checked 算术：off + 长度一律 checked_add，溢出即 fail-closed（§4.4）
    let dcid_end = off
        .checked_add(dcid_len)
        .ok_or_else(|| QuicServerError::PacketParse("dcid offset overflow".into()))?;
    if dcid_end > buf.len() {
        return Err(QuicServerError::PacketParse("dcid out of bounds".into()));
    }
    let dcid = buf[off..dcid_end].to_vec();
    off = dcid_end;
    let pn_end = off
        .checked_add(pn_len)
        .ok_or_else(|| QuicServerError::PacketParse("pn offset overflow".into()))?;
    if pn_end > buf.len() {
        return Err(QuicServerError::PacketParse("pn out of bounds".into()));
    }
    let mut pn: u64 = 0;
    // 切片迭代替代 off + i 索引加法（pn_end 已校验 ≤ buf.len()）
    for &b in &buf[off..pn_end] {
        pn = (pn << 8) | (b as u64);
    }
    let pn_offset = off;
    off = pn_end;

    Ok(ParsedShortHeader {
        first_byte: first,
        dcid,
        pn_offset,
        packet_number_len: pn_len,
        packet_number_raw: pn,
        payload_offset: off,
    })
}

/// 还原完整 62-bit packet number（基于期望的最大包号）
///
/// RFC 9000 §17.1.1: Packet Number Encoding and Decoding
///
/// 参数 `largest_pn` 是目前在此空间中观测到的最大包号。
/// 内部按 RFC 9000 §A.3 使用 `expected_pn = largest_pn + 1`。
pub fn decode_packet_number(
    truncated: u64,
    pn_len: usize,
    largest_pn: u64,
) -> u64 {
    // RFC 9000 §A.3: expected_pn = largest_pn + 1
    let expected_pn = largest_pn + 1;
    let pn_nbits = pn_len * 8;
    let pn_win = 1u64 << pn_nbits;
    let pn_hwin = pn_win / 2;
    let pn_mask = pn_win - 1;

    let candidate_pn = (expected_pn & !pn_mask) | (truncated & pn_mask);

    if candidate_pn + pn_hwin <= expected_pn && candidate_pn < (1u64 << 62) - pn_win {
        candidate_pn + pn_win
    } else if candidate_pn > expected_pn + pn_hwin && candidate_pn >= pn_win {
        candidate_pn - pn_win
    } else {
        candidate_pn
    }
}

/// QUIC 帧解析（流式）
#[derive(Debug, Clone)]
pub enum QuicFrame {
    /// PADDING 帧，填充字节以凑齐最小包长
    Padding,
    /// PING 帧，保持连接活跃或探查对端可达性
    Ping,
    /// ACK 帧，向对端确认已接收的数据包号区间
    Ack {
        /// 已确认的最大数据包号
        largest_acked: u64,
        /// ACK 延迟（微秒，按 ack_delay_exponent 解码前）
        ack_delay: u64,
        /// 已确认的数据包号区间列表（升序，每项为 [low, high]）
        ack_ranges: Vec<(u64, u64)>,
    },
    /// RESET_STREAM 帧，发送方主动中止某个流
    ResetStream {
        /// 被重置的流 ID
        stream_id: u64,
        /// 重置原因的错误码
        error_code: u64,
        /// 流的最终字节数（含此前已发送数据）
        final_size: u64,
    },
    /// STOP_SENDING 帧，请求对端停止向指定流发送数据
    StopSending {
        /// 请求停止发送的流 ID
        stream_id: u64,
        /// 触发请求的错误码
        error_code: u64,
    },
    /// CRYPTO 帧，承载 TLS 握手字节流
    Crypto {
        /// 该帧在 CRYPTO 字节流中的偏移
        offset: u64,
        /// CRYPTO 数据负载
        data: Vec<u8>,
    },
    /// NEW_TOKEN 帧，服务端向客户端下发的地址验证令牌
    NewToken {
        /// 下发的令牌字节
        token: Vec<u8>,
    },
    /// STREAM 帧，承载应用层流数据
    Stream {
        /// 该数据所属的流 ID
        stream_id: u64,
        /// 数据在流中的字节偏移
        offset: u64,
        /// 是否带 FIN 标志（流发送方向结束）
        fin: bool,
        /// 流数据负载
        data: Vec<u8>,
    },
    /// MAX_DATA 帧，提升连接级数据流量上限
    MaxData {
        /// 连接级允许发送的最大字节数
        max_data: u64,
    },
    /// MAX_STREAM_DATA 帧，提升单个流的数据流量上限
    MaxStreamData {
        /// 受限的流 ID
        stream_id: u64,
        /// 该流允许发送的最大字节数
        max_stream_data: u64,
    },
    /// MAX_STREAMS 帧（双向流），提升可建立的双向流总数上限
    MaxStreamsBidi {
        /// 允许的最大双向流总数
        max_streams: u64,
    },
    /// MAX_STREAMS 帧（单向流），提升可建立的单向流总数上限
    MaxStreamsUni {
        /// 允许的最大单向流总数
        max_streams: u64,
    },
    /// DATA_BLOCKED 帧，连接级流量受限通知
    DataBlocked {
        /// 当前连接级数据流量上限
        limit: u64,
    },
    /// STREAM_DATA_BLOCKED 帧，单流流量受限通知
    StreamDataBlocked {
        /// 受限的流 ID
        stream_id: u64,
        /// 该流当前的数据流量上限
        limit: u64,
    },
    /// STREAMS_BLOCKED 帧（双向流），双向流总数受限通知
    StreamsBlockedBidi {
        /// 当前允许的最大双向流总数
        limit: u64,
    },
    /// STREAMS_BLOCKED 帧（单向流），单向流总数受限通知
    StreamsBlockedUni {
        /// 当前允许的最大单向流总数
        limit: u64,
    },
    /// NEW_CONNECTION_ID 帧，向对端提供新连接 ID 及其重置令牌
    NewConnectionId {
        /// 该连接 ID 的序号
        sequence_number: u64,
        /// 在提供此 ID 前要求对端退役的序号上限
        retire_prior_to: u64,
        /// 新的连接 ID 字节
        connection_id: Vec<u8>,
        /// 关联的无状态重置令牌（16 字节）
        stateless_reset_token: [u8; 16],
    },
    /// RETIRE_CONNECTION_ID 帧，通知对端退役某个连接 ID
    RetireConnectionId {
        /// 待退役的连接 ID 序号
        sequence_number: u64,
    },
    /// PATH_CHALLENGE 帧，路径连通性探测请求
    PathChallenge {
        /// 8 字节随机探测数据
        data: [u8; 8],
    },
    /// PATH_RESPONSE 帧，对 PATH_CHALLENGE 的应答
    PathResponse {
        /// 回显的 8 字节探测数据
        data: [u8; 8],
    },
    /// CONNECTION_CLOSE 帧，因传输层错误关闭连接
    ConnectionClose {
        /// 关闭原因的错误码
        error_code: u64,
        /// 触发关闭的帧类型（0 表示未知）
        frame_type: u64,
        /// 关闭原因描述（字节序列）
        reason: Vec<u8>,
    },
    /// HANDSHAKE_DONE 帧，服务端确认握手完成
    HandshakeDone,
    /// 未识别的帧类型，保留原始负载以便扩展
    Unknown {
        /// 未识别的帧类型编码
        frame_type: u64,
        /// 原始帧负载字节
        data: Vec<u8>,
    },
}

/// 解析单个 QUIC 帧
///
/// 返回 (frame, consumed_bytes)
pub fn parse_frame(buf: &[u8]) -> Option<(QuicFrame, usize)> {
    if buf.is_empty() {
        return None;
    }
    let (frame_type, ft_len) = parse_varint(buf)?;
    let mut off = ft_len;
    let frame = match frame_type {
        FRAME_PADDING => {
            // PADDING：连续 0x00 字节直到下一个非 0x00 字节
            // 这里解析为单个 PADDING 帧
            QuicFrame::Padding
        }
        FRAME_PING => QuicFrame::Ping,
        FRAME_ACK | FRAME_ACK_ECN => {
            let (largest_acked, n) = parse_varint(&buf[off..])?;
            off += n;
            let (ack_delay, n) = parse_varint(&buf[off..])?;
            off += n;
            let (ack_range_count, n) = parse_varint(&buf[off..])?;
            off += n;
            let (first_ack_range, n) = parse_varint(&buf[off..])?;
            off += n;
            // 解析 ack ranges（fail-closed：若对端给的 first_ack_range/gap/
            // range_len 超出语义范围，checked_sub 返回 None（§4.4），
            // 坚决禁止减法下溢 panic（远程 DoS 向量））
            let mut ack_ranges = Vec::new();
            let mut lowest = largest_acked.checked_sub(first_ack_range)?;
            ack_ranges.push((lowest, largest_acked));
            for _ in 0..ack_range_count {
                let (gap, n) = parse_varint(&buf[off..])?;
                off += n;
                let (range_len, n) = parse_varint(&buf[off..])?;
                off += n;
                let high = lowest.checked_sub(gap)?.checked_sub(2)?;
                let low = high.checked_sub(range_len)?;
                ack_ranges.push((low, high));
                lowest = low;
            }
            // 如果是 ACK_ECN，跳过 3 个 ECN 计数字段
            if frame_type == FRAME_ACK_ECN {
                for _ in 0..3 {
                    let (_, n) = parse_varint(&buf[off..])?;
                    off += n;
                }
            }
            QuicFrame::Ack {
                largest_acked,
                ack_delay,
                ack_ranges,
            }
        }
        FRAME_RESET_STREAM => {
            let (stream_id, n) = parse_varint(&buf[off..])?;
            off += n;
            let (error_code, n) = parse_varint(&buf[off..])?;
            off += n;
            let (final_size, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::ResetStream {
                stream_id,
                error_code,
                final_size,
            }
        }
        FRAME_STOP_SENDING => {
            let (stream_id, n) = parse_varint(&buf[off..])?;
            off += n;
            let (error_code, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::StopSending { stream_id, error_code }
        }
        FRAME_CRYPTO => {
            let (offset, n) = parse_varint(&buf[off..])?;
            off += n;
            let (length, n) = parse_varint(&buf[off..])?;
            off += n;
            // CRYPTO 帧最大长度限制 (RFC 9000: CRYPTO frame data 不应超过 2^14 字节)
            const MAX_CRYPTO_FRAME_LEN: usize = 16384;
            let length_usize = usize::try_from(length)
                .ok()
                .filter(|&l| l <= MAX_CRYPTO_FRAME_LEN)
                .unwrap_or(MAX_CRYPTO_FRAME_LEN);
            let end = match off.checked_add(length_usize) {
                Some(e) if e <= buf.len() => e,
                _ => return None,
            };
            let data = buf[off..end].to_vec();
            off = end;
            QuicFrame::Crypto { offset, data }
        }
        FRAME_NEW_TOKEN => {
            let (length, n) = parse_varint(&buf[off..])?;
            off += n;
            if off + length as usize > buf.len() {
                return None;
            }
            let token = buf[off..off + length as usize].to_vec();
            off += length as usize;
            QuicFrame::NewToken { token }
        }
        t if (0x08..=0x0f).contains(&t) => {
            // STREAM frame (bits: FIN=1, LEN=1, OFF=1)
            let has_fin = (t & 0x01) != 0;
            let has_len = (t & 0x02) != 0;
            let has_off = (t & 0x04) != 0;
            let (stream_id, n) = parse_varint(&buf[off..])?;
            off += n;
            let offset = if has_off {
                let (o, n) = parse_varint(&buf[off..])?;
                off += n;
                o
            } else {
                0
            };
            let length = if has_len {
                let (l, n) = parse_varint(&buf[off..])?;
                off += n;
                l as usize
            } else {
                buf.len() - off
            };
            if off + length > buf.len() {
                return None;
            }
            let data = buf[off..off + length].to_vec();
            off += length;
            QuicFrame::Stream {
                stream_id,
                offset,
                fin: has_fin,
                data,
            }
        }
        FRAME_MAX_DATA => {
            let (max_data, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::MaxData { max_data }
        }
        FRAME_MAX_STREAM_DATA => {
            let (stream_id, n) = parse_varint(&buf[off..])?;
            off += n;
            let (max_stream_data, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::MaxStreamData {
                stream_id,
                max_stream_data,
            }
        }
        FRAME_MAX_STREAMS_BIDI => {
            let (max_streams, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::MaxStreamsBidi { max_streams }
        }
        FRAME_MAX_STREAMS_UNI => {
            let (max_streams, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::MaxStreamsUni { max_streams }
        }
        FRAME_DATA_BLOCKED => {
            let (limit, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::DataBlocked { limit }
        }
        FRAME_STREAM_DATA_BLOCKED => {
            let (stream_id, n) = parse_varint(&buf[off..])?;
            off += n;
            let (limit, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::StreamDataBlocked { stream_id, limit }
        }
        FRAME_STREAMS_BLOCKED_BIDI => {
            let (limit, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::StreamsBlockedBidi { limit }
        }
        FRAME_STREAMS_BLOCKED_UNI => {
            let (limit, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::StreamsBlockedUni { limit }
        }
        FRAME_NEW_CONNECTION_ID => {
            let (sequence_number, n) = parse_varint(&buf[off..])?;
            off += n;
            let (retire_prior_to, n) = parse_varint(&buf[off..])?;
            off += n;
            if off >= buf.len() {
                return None;
            }
            let cid_len = buf[off] as usize;
            off += 1;
            if off + cid_len > buf.len() {
                return None;
            }
            let connection_id = buf[off..off + cid_len].to_vec();
            off += cid_len;
            if off + 16 > buf.len() {
                return None;
            }
            let mut stateless_reset_token = [0u8; 16];
            stateless_reset_token.copy_from_slice(&buf[off..off + 16]);
            off += 16;
            QuicFrame::NewConnectionId {
                sequence_number,
                retire_prior_to,
                connection_id,
                stateless_reset_token,
            }
        }
        FRAME_RETIRE_CONNECTION_ID => {
            let (sequence_number, n) = parse_varint(&buf[off..])?;
            off += n;
            QuicFrame::RetireConnectionId { sequence_number }
        }
        FRAME_PATH_CHALLENGE => {
            if off + 8 > buf.len() {
                return None;
            }
            let mut data = [0u8; 8];
            data.copy_from_slice(&buf[off..off + 8]);
            off += 8;
            QuicFrame::PathChallenge { data }
        }
        FRAME_PATH_RESPONSE => {
            if off + 8 > buf.len() {
                return None;
            }
            let mut data = [0u8; 8];
            data.copy_from_slice(&buf[off..off + 8]);
            off += 8;
            QuicFrame::PathResponse { data }
        }
        FRAME_CONNECTION_CLOSE | FRAME_CONNECTION_CLOSE_APP => {
            let (error_code, n) = parse_varint(&buf[off..])?;
            off += n;
            let frame_type_field: u64 = if frame_type == FRAME_CONNECTION_CLOSE {
                let (ft, n) = parse_varint(&buf[off..])?;
                off += n;
                ft
            } else {
                0
            };
            let (reason_len, n) = parse_varint(&buf[off..])?;
            off += n;
            if off + reason_len as usize > buf.len() {
                return None;
            }
            let reason = buf[off..off + reason_len as usize].to_vec();
            off += reason_len as usize;
            QuicFrame::ConnectionClose {
                error_code,
                frame_type: frame_type_field,
                reason,
            }
        }
        FRAME_HANDSHAKE_DONE => QuicFrame::HandshakeDone,
        _ => {
            // 未知帧类型，无法解析（不知道长度）
            // 实际场景下需要跳过整个包
            return None;
        }
    };
    Some((frame, off))
}

/// 解析包内所有帧
pub fn parse_frames(mut buf: &[u8]) -> Vec<QuicFrame> {
    let mut frames = Vec::new();
    while !buf.is_empty() {
        match parse_frame(buf) {
            Some((frame, consumed)) => {
                frames.push(frame);
                buf = &buf[consumed..];
            }
            None => break,
        }
    }
    frames
}

/// 构造 CRYPTO 帧
pub fn build_crypto_frame(offset: u64, data: &[u8]) -> Vec<u8> {
    let mut out = Vec::new();
    out.push(0x06); // CRYPTO frame type
    push_varint(&mut out, offset);
    push_varint(&mut out, data.len() as u64);
    out.extend_from_slice(data);
    out
}

/// 解析 ClientHello 扩展类型列表（RFC 8446 §4.1.2 严格偏移）
///
/// 仅用于诊断：确认客户端是否提供 psk_kex_modes(0x002d)，
/// rustls 在客户端未提供时设 send_tickets=0（tls13.rs "Client unwilling to resume"）。
/// 输入必须是从 handshake message 头开始的完整 ClientHello。
fn scan_client_hello_extensions(ch: &[u8]) -> Vec<u16> {
    let mut exts = Vec::new();
    // 跳过：4B handshake 头 + 2B legacy_version + 32B random
    let mut p = 4 + 2 + 32;
    if ch.len() < p + 1 {
        return exts;
    }
    // legacy_session_id
    let sid_len = ch[p] as usize;
    p += 1 + sid_len;
    if ch.len() < p + 2 {
        return exts;
    }
    // cipher_suites
    let cs_len = ((ch[p] as usize) << 8) | (ch[p + 1] as usize);
    p += 2 + cs_len;
    if ch.len() < p + 1 {
        return exts;
    }
    // legacy_compression_methods
    let comp_len = ch[p] as usize;
    p += 1 + comp_len;
    if ch.len() < p + 2 {
        return exts;
    }
    // extensions 块
    let ext_total = ((ch[p] as usize) << 8) | (ch[p + 1] as usize);
    p += 2;
    let end = (p + ext_total).min(ch.len());
    while p + 4 <= end {
        let et = ((ch[p] as u16) << 8) | (ch[p + 1] as u16);
        let el = ((ch[p + 2] as usize) << 8) | (ch[p + 3] as usize);
        exts.push(et);
        p += 4 + el;
    }
    exts
}

/// 构造 ACK 帧（最简形式：单 ack range）
pub fn build_ack_frame(largest_acked: u64, ack_delay: u64, ack_range: u64) -> Vec<u8> {
    let mut out = Vec::new();
    out.push(0x02); // ACK
    push_varint(&mut out, largest_acked);
    push_varint(&mut out, ack_delay);
    push_varint(&mut out, 0); // ack range count = 0
    push_varint(&mut out, ack_range); // first ack range
    out
}

/// 构造 STREAM 帧（带 FIN + LEN + OFF）
pub fn build_stream_frame(stream_id: u64, offset: u64, fin: bool, data: &[u8]) -> Vec<u8> {
    let mut out = Vec::new();
    // frame type: 0x08 | FIN(1) | LEN(2) | OFF(4)
    let mut frame_type: u8 = 0x08 | 0x02 | 0x04; // LEN + OFF
    if fin {
        frame_type |= 0x01;
    }
    out.push(frame_type);
    push_varint(&mut out, stream_id);
    push_varint(&mut out, offset);
    push_varint(&mut out, data.len() as u64);
    out.extend_from_slice(data);
    out
}

/// 构造 HANDSHAKE_DONE 帧
pub fn build_handshake_done_frame() -> Vec<u8> {
    vec![0x1e]
}

/// 构造 PATH_CHALLENGE 帧（RFC 9000 §8.2，路径验证请求）
pub fn build_path_challenge_frame(data: &[u8; 8]) -> Vec<u8> {
    let mut out = Vec::with_capacity(9);
    out.push(FRAME_PATH_CHALLENGE as u8);
    out.extend_from_slice(data);
    out
}

/// 构造 PATH_RESPONSE 帧（RFC 9000 §8.2，回显 PATH_CHALLENGE 的 8 字节）
pub fn build_path_response_frame(data: &[u8; 8]) -> Vec<u8> {
    let mut out = Vec::with_capacity(9);
    out.push(FRAME_PATH_RESPONSE as u8);
    out.extend_from_slice(data);
    out
}

/// 构造 CONNECTION_CLOSE 帧（应用层）
pub fn build_connection_close_app(error_code: u64, reason: &str) -> Vec<u8> {
    let mut out = Vec::new();
    out.push(0x1d); // APPLICATION_CLOSE
    push_varint(&mut out, error_code);
    push_varint(&mut out, reason.len() as u64);
    out.extend_from_slice(reason.as_bytes());
    out
}

/// 构造 CONNECTION_CLOSE 帧（传输层，RFC 9000 §19.19）
///
/// type=0x1c 携带 frame_type 字段（触发错误的帧类型，0 表示未知）。
/// 用于 QUIC 传输层协议错误（FLOW_CONTROL_ERROR / STREAM_LIMIT_ERROR / ...）。
pub fn build_connection_close_transport(error_code: u64, frame_type: u64, reason: &str) -> Vec<u8> {
    let mut out = Vec::new();
    out.push(0x1c); // TRANSPORT_CLOSE
    push_varint(&mut out, error_code);
    push_varint(&mut out, frame_type);
    push_varint(&mut out, reason.len() as u64);
    out.extend_from_slice(reason.as_bytes());
    out
}

/// 构造 PADDING 帧
pub fn build_padding_frame(n: usize) -> Vec<u8> {
    vec![0u8; n]
}

/// 构造 PING 帧
pub fn build_ping_frame() -> Vec<u8> {
    vec![0x01]
}

/// QUIC 服务器配置
#[derive(Clone)]
pub struct QuicServerConfig {
    /// 绑定地址
    pub bind_addr: SocketAddr,
    /// rustls ServerConfig (ALPN h3 + 证书)
    pub rustls_config: Arc<rustls::ServerConfig>,
    /// QUIC 版本
    pub version: QuicVersion,
    /// 服务端 SCID 长度（建议 8）
    pub scid_len: usize,
    /// 服务端 SCID（自定义）
    pub scid: Vec<u8>,
    /// 初始 idle timeout (ms)
    pub idle_timeout_ms: u64,
    /// 最大接收字节数
    pub max_recv_bytes: usize,
}

impl std::fmt::Debug for QuicServerConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("QuicServerConfig")
            .field("bind_addr", &self.bind_addr)
            .field("version", &self.version)
            .field("scid_len", &self.scid_len)
            .field("idle_timeout_ms", &self.idle_timeout_ms)
            .finish()
    }
}

impl QuicServerConfig {
    /// 创建新的 QUIC 服务器配置
    ///
    /// 服务端 SCID 由 `zenith_foundation::random::try_fill_random`（OS CSPRNG）
    /// 填充 `scid_len` 随机字节。
    ///
    /// # Fail-Closed
    /// CSPRNG 失败时返回 [`QuicServerError::RandomUnavailable`]，拒绝构造
    /// 配置（panic-free）：绝不回退为全零/固定 SCID——可枚举的连接 ID
    /// 会使会话在握手即被劫持。
    pub fn new(
        bind_addr: SocketAddr,
        rustls_config: Arc<rustls::ServerConfig>,
        version: QuicVersion,
    ) -> Result<Self, QuicServerError> {
        let scid_len = 8usize;
        let mut scid = vec![0u8; scid_len];
        if !zenith_foundation::random::try_fill_random(&mut scid) {
            return Err(QuicServerError::RandomUnavailable(
                "CSPRNG 填充服务端 SCID 失败".into(),
            ));
        }
        Ok(Self {
            bind_addr,
            rustls_config,
            version,
            scid_len,
            scid,
            idle_timeout_ms: 10_000,
            max_recv_bytes: 65535,
        })
    }

    /// 从 PEM 证书 + 私钥字节构造 QUIC 服务器配置（隐藏 rustls，供 demo 使用）
    ///
    /// - `bind_addr`: 监听地址
    /// - `cert_pem`: PEM 编码的证书链字节
    /// - `key_pem`: PEM 编码的私钥字节
    /// - `alpn`: ALPN 协议列表（如 `b"h3"`）
    /// - `version`: QUIC 版本
    pub fn from_pem(
        bind_addr: SocketAddr,
        cert_pem: &[u8],
        key_pem: &[u8],
        alpn: Vec<Vec<u8>>,
        version: QuicVersion,
    ) -> Result<Self, QuicServerError> {
        let generation = CertGeneration::from_pem(cert_pem, key_pem)
            .map_err(|e| QuicServerError::PacketParse(format!("cert load: {e}")))?;
        let rustls_config = generation
            .to_server_config(alpn)
            .map_err(|e| QuicServerError::PacketParse(format!("server config: {e}")))?;
        // SCID 随机化 fail-closed 经 ? 传播（CSPRNG 失败拒绝构造配置）
        Self::new(bind_addr, rustls_config, version)
    }
}

/// QUIC 服务器状态
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QuicServerState {
    /// 等待 Initial
    WaitInitial,
    /// 已发送 ServerHello + Handshake 包
    HandshakeSent,
    /// 已收到客户端 Finished
    HandshakeDone,
    /// 1-RTT 数据传输中
    Established,
    /// 连接关闭
    Closed,
}

/// 已发送待确认的 1-RTT 包（用于拥塞控制的 ACK 驱动与 RTT 估计）
#[derive(Debug, Clone, Copy)]
pub struct SentPacket {
    /// 包号
    pub pn: u64,
    /// 发送字节数（加密后整包）
    pub bytes: u64,
    /// 发送时刻（用于 RTT 测量）
    pub sent_at: Instant,
    /// 是否 ack-eliciting（STREAM 等为 true；纯 ACK 包为 false）
    pub ack_eliciting: bool,
}

/// STREAM 接收重组缓冲（RFC 9000 §2.2：流是有序字节流，接收方必须按 offset
/// 重组后交付；重传/乱序分段按 offset 去重裁剪，禁止简单 append 产生重复数据）
#[derive(Debug, Default)]
pub struct StreamRecv {
    /// 未交付的分段（offset → data），BTreeMap 按 offset 升序
    segments: std::collections::BTreeMap<u64, Vec<u8>>,
    /// 已交付终点（delivered_end 之前的字节已连续交付给上层）
    delivered_end: u64,
    /// FIN 到达的最终 offset（Some = 对端已关闭发送方向）
    fin_offset: Option<u64>,
    /// FIN 是否已被上层消费（take_stream_fin 一次性语义）
    fin_delivered: bool,
}

impl StreamRecv {
    /// 插入一个 STREAM 分段（自动裁剪与已交付/已有分段的重叠部分）
    ///
    /// # 返回
    /// - `true`：有新字节被缓冲（含部分重传但含新数据）
    /// - `false`：完全重传/重复（无任何新字节）——调用方据此触发响应重发
    ///   （RFC 9002：对端重传已交付数据 = 对端未收到本端响应）
    fn insert(&mut self, offset: u64, data: &[u8]) -> bool {
        let mut start = offset;
        let mut chunk = data;
        // 裁剪已交付部分（重传旧数据直接丢弃）
        if start < self.delivered_end {
            let skip = (self.delivered_end - start) as usize;
            if skip >= chunk.len() {
                return false;
            }
            chunk = &chunk[skip..];
            start = self.delivered_end;
        }
        // 裁剪与前驱分段的重叠
        if let Some((&prev_off, prev)) = self.segments.range(..=start).next_back() {
            let prev_end = prev_off + prev.len() as u64;
            if prev_end > start {
                let overlap = (prev_end - start) as usize;
                if overlap >= chunk.len() {
                    return false;
                }
                chunk = &chunk[overlap..];
                start = prev_end;
            }
        }
        // 裁剪与后继分段的重叠（本分段尾部截断）
        let mut end = start + chunk.len() as u64;
        if let Some((&next_off, _)) = self.segments.range(start..).next()
            && next_off < end
        {
            end = next_off;
        }
        if end > start {
            self.segments
                .insert(start, chunk[..(end - start) as usize].to_vec());
            true
        } else {
            false
        }
    }

    /// 取出从 delivered_end 开始的连续数据（增量交付；有空洞则不交付尾部）
    fn take_contiguous(&mut self) -> Option<Vec<u8>> {
        let mut out = Vec::new();
        while let Some((&off, _)) = self.segments.range(..=self.delivered_end).next_back() {
            let Some(data) = self.segments.remove(&off) else {
                // range 守卫后 remove 失败（理论不可达，fail-closed）
                break;
            };
            let seg_end = off + data.len() as u64;
            if seg_end <= self.delivered_end {
                continue; // 完全已交付（防御：insert 已裁剪）
            }
            let skip = (self.delivered_end - off) as usize;
            out.extend_from_slice(&data[skip..]);
            self.delivered_end = seg_end;
        }
        if out.is_empty() {
            None
        } else {
            Some(out)
        }
    }

    /// FIN 已到达且全部数据已连续交付 → 消费并返回 true（一次性）
    fn take_fin(&mut self) -> bool {
        if self.fin_delivered {
            return false;
        }
        if let Some(fin_off) = self.fin_offset
            && self.delivered_end >= fin_off
        {
            self.fin_delivered = true;
            return true;
        }
        false
    }
}

/// QUIC 单连接状态（服务端侧，含加密会话与流重组）
pub struct QuicConnection {
    /// 客户端地址
    pub client_addr: SocketAddr,
    /// 客户端的 SCID（即服务端的 DCID）
    pub client_scid: Vec<u8>,
    /// 客户端的 DCID（即服务端的 SCID）
    pub client_dcid: Vec<u8>,
    /// 服务端 SCID
    pub server_scid: Vec<u8>,
    /// 服务端 DCID（用于接收 Short Header）
    pub server_dcid: Vec<u8>,
    /// 加密会话
    pub crypto_session: QuicCryptoSession,
    /// Initial keys (server side)
    pub initial_keys: Keys,
    /// Handshake keys (server side, if available)
    pub handshake_keys: Option<Keys>,
    /// 1-RTT keys (server side, if handshake complete)
    pub one_rtt_keys: Option<Keys>,
    /// 协议错误时预发的 ACK 包（需与 CONNECTION_CLOSE 合并发送）
    pub pending_err_ack: Option<Vec<u8>>,
    /// 当前状态
    pub state: QuicServerState,
    /// 服务端发送包号计数器（Initial）
    pub next_initial_pn: u64,
    /// 服务端发送包号计数器（Handshake）
    pub next_handshake_pn: u64,
    /// 服务端发送包号计数器（1-RTT）
    pub next_1rtt_pn: u64,
    /// 客户端最大已收 Initial 包号
    pub largest_initial_pn: u64,
    /// 客户端最大已收 Handshake 包号
    pub largest_handshake_pn: u64,
    /// 客户端最大已收 1-RTT 包号
    pub largest_1rtt_pn: u64,
    /// 已收 Initial CRYPTO 数据（按 offset 重组的累积缓冲区）
    pub initial_crypto_rx: Vec<u8>,
    /// 已喂给 rustls 的 Initial CRYPTO 字节数
    pub initial_crypto_consumed: usize,
    /// 已收 Handshake CRYPTO 数据（按 offset 重组）
    pub handshake_crypto_rx: Vec<u8>,
    /// 已喂给 rustls 的 Handshake CRYPTO 字节数
    pub handshake_crypto_consumed: usize,
    /// 服务端已发送的 Initial CRYPTO 字节累计偏移（RFC 9000 §18.1）
    pub initial_crypto_tx_offset: u64,
    /// 服务端已发送的 Handshake CRYPTO 字节累计偏移（RFC 9000 §18.1）
    pub handshake_crypto_tx_offset: u64,
    /// 已收 1-RTT 流数据（stream_id → 重组缓冲，按 offset 有序交付）
    pub stream_rx: FxHashMap<u64, StreamRecv>,
    /// 服务端已打开/发送过的流 ID 集合（server-initiated: mod 4 ∈ {1,3} 及任何已发送流）
    ///
    /// 用于 RFC 9000 §19.5/§19.10：STOP_SENDING / MAX_STREAM_DATA 指向"服务端未打开的
    /// 本地发起流"时应返回 STREAM_STATE_ERROR。真实客户端（curl/nghttp3）仅对已打开的
    /// 服务端流发送这两类帧，因此不会误伤正常连接。
    pub server_opened_streams: FxHashSet<u64>,
    /// 已建立时间
    pub established_at: Option<Instant>,
    /// HANDSHAKE_DONE 是否已发送（防止重复发送）
    pub handshake_done_sent: bool,
    /// 拥塞控制器（RFC 9002 简化版：ACK 驱动 cwnd 增长 + RTT 估计）
    pub congestion: CongestionController,
    /// 已发送待确认的 1-RTT 包队列（按包号升序，ACK 到达时移除）
    pub sent_1rtt: VecDeque<SentPacket>,
    /// 最大在途包跟踪容量（防内存膨胀，超出丢弃最旧）
    pub max_tracked_sent: usize,
    /// 流控：每流已消费的最高 end offset（stream_id → max(offset+len)）
    pub fc_stream_end: FxHashMap<u64, u64>,
    /// 流控：连接级已消费字节数（所有流 end 增长量之和）
    pub fc_conn_consumed: u64,
    /// 已接收待消费的 PATH_RESPONSE 数据（RFC 9000 §9 路径验证，供上层迁移判定）
    pub pending_path_response: Vec<[u8; 8]>,
    /// 1-RTT CRYPTO 流已发送字节偏移（NewSessionTicket 等 post-handshake 数据）
    pub one_rtt_crypto_tx_offset: u64,
    /// 0-RTT 解密密钥缓存（RFC 9001 §5.7，从 rustls early_secret 派生一次后缓存）
    pub zero_rtt_keys: Option<rustls::quic::DirectionalKeys>,
    /// 已收 0-RTT 早期流数据（stream_id → 重组缓冲，与 1-RTT 严格分离防混淆）
    pub early_stream_rx: FxHashMap<u64, StreamRecv>,
    /// 当前 1-RTT 密钥相位（RFC 9001 §6：false=相位0初始，每次密钥更新翻转）
    pub key_phase: bool,
    /// 已执行的密钥更新次数（RFC 9001 §6.5 频率审计）
    pub key_update_count: u64,
    /// Initial 阶段响应航班缓存（ServerHello 航班：Initial 包 + Handshake 包）。
    /// RFC 9002 被动重传：对端未收到响应会重传 CRYPTO（相同 offset 新包号），
    /// 本端检测到纯重传（consumed 未推进）时重发本航班。
    pub initial_flight: Vec<Vec<u8>>,
    /// Handshake 阶段数据包航班缓存（Handshake CRYPTO 包 + HANDSHAKE_DONE + ticket，
    /// 不含纯 ACK 包）。Finished 重传时随新 ACK 一起重发。
    pub handshake_flight: Vec<Vec<u8>>,
    /// 本轮收到纯重传 STREAM 数据的流列表（zenith-web 据此重发响应缓存）。
    /// 每轮 process_streams 取走后清空。
    pub dup_stream_sids: Vec<u64>,
    /// 客户端 SNI（RFC 6066，从 Initial CRYPTO 流首个 ClientHello 提取一次后缓存）。
    /// §4.5 四元身份一致性校验的传输层身份来源（zenith-web 据此比对 :authority/Host）。
    pub sni: Option<String>,
    /// 客户端 TLS 指纹（JA3/JA4，从 Initial CRYPTO 流首个 ClientHello 提取一次后缓存），
    /// 供 zenith-web 对 HTTP/3 连接做指纹识别与阻断（与 TCP/TLS 路径一致）。
    pub client_fingerprint: Option<Ja3Fingerprint>,
}

impl std::fmt::Debug for QuicConnection {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("QuicConnection")
            .field("client_addr", &self.client_addr)
            .field("client_scid_len", &self.client_scid.len())
            .field("client_dcid_len", &self.client_dcid.len())
            .field("server_scid_len", &self.server_scid.len())
            .field("server_dcid_len", &self.server_dcid.len())
            .field("state", &self.state)
            .field("next_initial_pn", &self.next_initial_pn)
            .field("next_handshake_pn", &self.next_handshake_pn)
            .field("next_1rtt_pn", &self.next_1rtt_pn)
            .field("handshake_done", &self.crypto_session.is_handshake_done())
            .finish()
    }
}

impl QuicConnection {
    /// 流控：连接级最大数据（与 transport param initial_max_data=0x04 一致，1MB）
    const FC_MAX_DATA: u64 = 1_048_576;
    /// 流控：流级最大数据（与 transport param initial_max_stream_data_bidi_remote=0x06 一致，256KB）
    const FC_MAX_STREAM_DATA: u64 = 262_144;
    /// 流控：最大并发双向流 ID 上限（initial_max_streams_bidi=100 → 流 ID < 400）
    const FC_MAX_STREAM_ID: u64 = 400;

    /// 创建新的 QUIC 连接（服务端）
    pub fn new(
        client_addr: SocketAddr,
        client_scid: Vec<u8>,
        client_dcid: Vec<u8>,
        server_scid: Vec<u8>,
        rustls_config: Arc<rustls::ServerConfig>,
        version: QuicVersion,
    ) -> Result<Self, QuicServerError> {
        // 创建 QuicCryptoSession + Initial keys
        // transport_params 必须包含 original_destination_connection_id(=client_dcid)
        // 和 initial_source_connection_id(=server_scid)，否则客户端校验失败
        let transport_params = build_default_transport_params(&client_dcid, &server_scid);
        let (crypto_session, initial_keys) = QuicCryptoSession::new(
            rustls_config,
            version,
            &client_dcid,
            transport_params,
        )?;

        Ok(Self {
            client_addr,
            client_scid,
            client_dcid,
            server_scid: server_scid.clone(),
            server_dcid: server_scid, // 服务端 DCID = 服务端 SCID
            crypto_session,
            initial_keys,
            handshake_keys: None,
            one_rtt_keys: None,
            pending_err_ack: None,
            state: QuicServerState::WaitInitial,
            next_initial_pn: 0,
            next_handshake_pn: 0,
            next_1rtt_pn: 0,
            largest_initial_pn: 0,
            largest_handshake_pn: 0,
            largest_1rtt_pn: 0,
            initial_crypto_rx: Vec::new(),
            initial_crypto_consumed: 0,
            handshake_crypto_rx: Vec::new(),
            handshake_crypto_consumed: 0,
            initial_crypto_tx_offset: 0,
            handshake_crypto_tx_offset: 0,
            stream_rx: FxHashMap::default(),
            server_opened_streams: FxHashSet::default(),
            established_at: None,
            handshake_done_sent: false,
            congestion: CongestionController::new(),
            sent_1rtt: VecDeque::new(),
            max_tracked_sent: 1024,
            fc_stream_end: FxHashMap::default(),
            fc_conn_consumed: 0,
            pending_path_response: Vec::new(),
            one_rtt_crypto_tx_offset: 0,
            zero_rtt_keys: None,
            early_stream_rx: FxHashMap::default(),
            key_phase: false,
            key_update_count: 0,
            initial_flight: Vec::new(),
            handshake_flight: Vec::new(),
            dup_stream_sids: Vec::new(),
            sni: None,
            client_fingerprint: None,
        })
    }

    /// 是否握手完成
    pub fn is_handshake_done(&self) -> bool {
        self.crypto_session.is_handshake_done()
    }

    /// 客户端 SNI（若 ClientHello 已完整到达且含 server_name 扩展）
    ///
    /// 提取时机：Initial CRYPTO 流首个 ClientHello 完整到达时一次性提取并缓存，
    /// 此后不可变（RFC 6066：SNI 仅在 ClientHello 中出现一次）。
    #[inline]
    pub fn sni(&self) -> Option<&str> {
        self.sni.as_deref()
    }

    /// 取走客户端 TLS 指纹（JA3/JA4），供 zenith-web 绑定到 HTTP/3 连接。
    /// 仅可消费一次（与 `sni` 生命周期一致，ClientHello 提取后缓存）。
    pub fn take_client_fingerprint(&mut self) -> Option<Ja3Fingerprint> {
        self.client_fingerprint.take()
    }

    /// 是否已建立（1-RTT 数据可传输）
    pub fn is_established(&self) -> bool {
        self.state == QuicServerState::Established
    }

    /// 处理 Initial 包
    ///
    /// 返回需要发送给客户端的字节（可能是多个包拼接）
    pub fn handle_initial_packet(
        &mut self,
        packet: &[u8],
    ) -> Result<Vec<Vec<u8>>, QuicServerError> {
        let first_byte_raw = packet.first().copied().unwrap_or(0);
        tracing::debug!(len = packet.len(), first_byte = format_args!("{first_byte_raw:#04x}"), "QUIC Initial recv");
        let parsed = parse_long_header_full(packet)?;
        tracing::debug!(
            version = format_args!("{:#010x}", parsed.version),
            dcid = ?parsed.dcid, scid = ?parsed.scid, token_len = parsed.token.len(),
            length = parsed.length, pn_len = parsed.packet_number_len,
            payload_offset = parsed.payload_offset, payload_len = parsed.payload_len,
            "QUIC Initial parsed"
        );
        if parsed.long_frame != 0 {
            return Err(QuicServerError::PacketParse(format!(
                "not an Initial packet: long_frame={}",
                parsed.long_frame
            )));
        }

        // Length 字段值 = pn_len + ciphertext_len，所以 packet_end = pn_offset + length_value
        let pn_offset = parsed.pn_offset;
        let length_value = parsed.length as usize;
        // checked 算术：攻击者可控的 length/pn_offset 溢出即 fail-closed
        let packet_end = pn_offset
            .checked_add(length_value)
            .ok_or_else(|| QuicServerError::PacketParse("packet_end overflow".into()))?;
        if packet_end > packet.len() {
            return Err(QuicServerError::PacketParse("payload out of bounds".into()));
        }
        let mut buf = packet[..packet_end].to_vec();

        // RFC 9001 §5.4.1: HP sample 永远从 pn_offset + 4（MAX_PKT_NUM_LEN）开始
        // 不是 pn_offset + pn_len！因为 pn_len 在 HP 移除前是加密的
        let hp_key = &*self.initial_keys.remote.header;
        let sample_len = hp_key.sample_len();
        let sample_start = pn_offset
            .checked_add(4) // MAX_PKT_NUM_LEN = 4
            .ok_or_else(|| QuicServerError::PacketParse("sample_start overflow".into()))?;
        let sample_end = sample_start
            .checked_add(sample_len)
            .ok_or_else(|| QuicServerError::PacketParse("sample_end overflow".into()))?;
        if sample_end > buf.len() {
            return Err(QuicServerError::PacketParse("hp sample too short".into()));
        }
        let sample = buf[sample_start..sample_end].to_vec();

        // PN 切片也必须传 4 字节（MAX_PKT_NUM_LEN），rustls 内部用 take(pn_len) 只 XOR 真实长度
        let mut first_byte = buf[0];
        {
            let pn_bytes = &mut buf[pn_offset..sample_start];
            remove_header_protection(hp_key, &sample, &mut first_byte, pn_bytes)?;
        }
        buf[0] = first_byte;

        // HP 移除后，从解密后的 first_byte 读取真实 pn_len
        let real_pn_len = ((first_byte & 0x03) as usize) + 1;
        let header_end = pn_offset
            .checked_add(real_pn_len)
            .ok_or_else(|| QuicServerError::PacketParse("header_end overflow".into()))?;
        // fail-closed：解密出的 pn_len 可能超出 Length 字段声明范围
        if header_end > packet_end {
            return Err(QuicServerError::PacketParse("header_end out of bounds".into()));
        }

        // 读取明文 PN
        let mut pn_plain: u64 = 0;
        for i in 0..real_pn_len {
            pn_plain = (pn_plain << 8) | (buf[pn_offset + i] as u64);
        }
        let pn = decode_packet_number(
            pn_plain,
            real_pn_len,
            self.largest_initial_pn,
        );
        self.largest_initial_pn = pn;

        // AEAD 解密：AAD = 明文 header[0..header_end]，ciphertext = buf[header_end..packet_end]
        let ciphertext_len = packet_end
            .checked_sub(header_end)
            .ok_or_else(|| QuicServerError::PacketParse("ciphertext_len underflow".into()))?;
        let (header, payload) = buf.split_at_mut(header_end);
        let header: &[u8] = header;
        let payload = &mut payload[..ciphertext_len];
        tracing::debug!(aad_len = header.len(), ciphertext_len, "QUIC Initial AEAD decrypt");

        let decrypted = decrypt_packet(
            &*self.initial_keys.remote.packet,
            pn,
            header,
            payload,
        ).map_err(|e| {
            tracing::warn!(error = ?e, "QUIC Initial decrypt failed");
            e
        })?;

        // 解析帧
        let frames = parse_frames(decrypted);
        let had_crypto = frames.iter().any(|f| matches!(f, QuicFrame::Crypto { .. }));
        tracing::debug!(frame_count = frames.len(), "QUIC Initial frames parsed");

        // 按 offset 重组 Initial CRYPTO 流（RFC 9000 §17.2 / RFC 9001 §5.1）
        // CRYPTO 帧可能分片/乱序到达，必须按 offset 写入累积缓冲区，
        // 然后把从 consumed 开始的新增连续数据喂给 rustls。
        // 错误做法（之前）：忽略 offset 直接拼接 → 分片时 rustls 收到错乱字节，
        //   把片段开头当 handshake message header，length 字段读到巨大值 → HandshakePayloadTooLarge
        for frame in &frames {
            if let QuicFrame::Crypto { offset, data } = frame {
                let off = *offset as usize;
                // checked 算术：CRYPTO offset 攻击者可控，溢出即 fail-closed
                let end = off
                    .checked_add(data.len())
                    .ok_or_else(|| QuicServerError::PacketParse("crypto offset overflow".into()))?;
                if end > self.initial_crypto_rx.len() {
                    if end > MAX_CRYPTO_BUFFER_SIZE {
                        return Err(QuicServerError::PacketParse(
                            "CRYPTO buffer exceeds maximum size".into(),
                        ));
                    }
                    self.initial_crypto_rx.resize(end, 0);
                }
                self.initial_crypto_rx[off..end].copy_from_slice(data);
            }
        }

        // 把从 consumed 开始的新增连续数据喂给 rustls
        let prev_consumed = self.initial_crypto_consumed;
        let consumed = self.initial_crypto_consumed;
        let available = self.initial_crypto_rx.len();
        if available > consumed {
            let new_data = &self.initial_crypto_rx[consumed..available];
            tracing::debug!(crypto_offset = consumed, len = new_data.len(), "QUIC Initial feed rustls");
            // 诊断：ClientHello 完整到达后扫描扩展列表，
            // 确认 psk_kex_modes(0x002d) 是否存在（rustls 据此决定是否签发 session ticket）
            if self.initial_crypto_rx.len() >= 4 && self.initial_crypto_rx[0] == 0x01 {
                let ch_len = ((self.initial_crypto_rx[1] as usize) << 16)
                    | ((self.initial_crypto_rx[2] as usize) << 8)
                    | (self.initial_crypto_rx[3] as usize);
                if let Some(ch_end) = 4usize.checked_add(ch_len)
                    && self.initial_crypto_rx.len() >= ch_end {
                        let exts = scan_client_hello_extensions(&self.initial_crypto_rx[..ch_end]);
                        tracing::debug!(extensions = format_args!("{exts:04x?}"), "QUIC ClientHello extensions");
                        // RFC 9001 §8.2：ClientHello 必须携带 quic_transport_parameters 扩展
                        // (0x0039)，缺失时服务端必须以 missing_extension(109) 告警中止握手。
                        // h3spec 依此校验（[TLS 8.2]）；rustls QUIC 模式本应由其强制，但此处
                        // 显式校验以确保错误码正确送达（missing_extension → 0x016D）。
                        if !exts.contains(&0x0039) {
                            return Err(QuicServerError::Crypto(
                                QuicCryptoError::KeyDerivation(
                                    "missing_extension: client hello lacks quic_transport_parameters extension (0x0039)".into(),
                                ),
                            ));
                        }
                        // §4.5 四元身份一致性：ClientHello 完整到达即一次性提取 SNI 并缓存，
                        // 供 zenith-web 比对 :authority/Host（QUIC 裸 handshake，无 TLS record 层）。
                        if self.sni.is_none()
                            && let Some(sni) = zenith_tls::TlsAcceptor::peek_sni_quic(
                                &self.initial_crypto_rx[..ch_end],
                            ) {
                                tracing::debug!(sni, "QUIC ClientHello SNI extracted");
                                self.sni = Some(sni.to_ascii_lowercase());
                            }
                        // TLS 指纹（JA3/JA4）：ClientHello 完整到达即一次性计算并缓存，
                        // 供 zenith-web 对 HTTP/3 连接做指纹识别与阻断（与 TCP/TLS 路径一致）。
                        // QUIC 裸 handshake 无 record 层，必须用 from_quic_client_hello。
                        if self.client_fingerprint.is_none()
                            && let Some(fp) = Ja3Fingerprint::from_quic_client_hello(
                                &self.initial_crypto_rx[..ch_end],
                            ) {
                                tracing::debug!(
                                    ja3 = %fp.ja3_hash, ja4 = %fp.ja4_hash,
                                    "QUIC ClientHello JA3/JA4 fingerprint captured"
                                );
                                self.client_fingerprint = Some(fp);
                            }
                    }
            }
            self.crypto_session.process_handshake_data(new_data)?;
            self.initial_crypto_consumed = available;
        }

        // 取出 rustls 想要发送的数据 + 可能的新 keys
        let mut output_packets = Vec::new();
        // 提取版本号为本地变量（Copy），避免循环中与 &mut self.next_*_pn 冲突
        let version = self.version();

        // 保存 Initial PN（RFC 9000 §17.1: 首个 Initial 包 PN=0）
        // 如果 write_handshake 失败，恢复 PN 以确保 CC 包 PN=0
        let saved_initial_pn = self.next_initial_pn;

        // 循环 write_hs 直到没有更多数据
        loop {
            let result = match self.crypto_session.write_handshake() {
                Ok(r) => r,
                Err(e) => {
                    // write_handshake 失败：恢复 Initial PN，确保后续 CC 包 PN=0
                    // RFC 9000 §17.1: "The first Initial packet sent by a server MUST have PN=0"
                    self.next_initial_pn = saved_initial_pn;
                    return Err(e.into());
                }
            };
            match result {
                Some((tls_data, new_keys)) => {
                    tracing::debug!(
                        tls_data_len = tls_data.len(),
                        has_new_keys = new_keys.is_some(),
                        "QUIC Initial write_hs"
                    );
                    if !tls_data.is_empty() {
                        // 把 TLS 数据封装成 CRYPTO 帧
                        // 如果有 Handshake keys，用 Handshake 加密；否则用 Initial
                        if let Some(keys) = new_keys {
                            // 这是从 Initial → Handshake 的过渡
                            // 1. 先用 Initial keys 发送剩余的 CRYPTO (EncryptedExtensions, Cert, CertVerify, Finished)
                            //    但是这些 TLS 数据属于 Handshake space（来自 write_hs 后）
                            // 实际上：rustls 的 write_hs 返回的 KeyChange::Handshake 表示
                            // "接下来的数据应该用 Handshake keys 加密"
                            // 但当前 tls_data 是 ServerHello + EncryptedExtensions + Cert + CertVerify + Finished
                            // ServerHello 应该用 Initial keys 发送
                            // EncryptedExtensions + Cert + CertVerify + Finished 应该用 Handshake keys 发送
                            // 但 rustls 把它们打包在一起，需要我们自己分割...
                            //
                            // 简化处理：把整个 tls_data 都用 Initial keys 发送
                            // （包括 ServerHello 和 Handshake 数据）
                            // 这在 RFC 9001 §5.3 中是允许的：
                            // "The server's first flight includes ServerHello, EncryptedExtensions,
                            //  Certificate, CertificateVerify, and Finished.
                            //  ServerHello is sent in Initial packet.
                            //  The others are sent in Handshake packets."
                            //
                            // 但实际客户端（quiche / ngtcp2）要求严格：
                            // ServerHello 必须在 Initial 包，其余必须在 Handshake 包。
                            //
                            // 由于 rustls 的 write_hs 返回的是合并的 TLS 数据，
                            // 我们无法知道 ServerHello 结束在哪里。
                            //
                            // 简化策略：把 tls_data 分成两部分
                            // - ServerHello (1+3+2+N handshake_len)
                            // - 剩下的用 Handshake keys 发送
                            //
                            // 但这需要解析 TLS handshake message header...
                            //
                            // 最简方案：把整个 tls_data 当作 Initial CRYPTO 发送
                            // 然后再发送一个空的 Handshake 包（建立 Handshake keys）
                            // 实际测试发现：rustls 第一次 write_hs 后返回 Handshake keys
                            // 表示后续数据用 Handshake keys。
                            // 第一次的 tls_data 是 ServerHello + EncryptedExtensions + Cert + CertVerify + Finished
                            // 我们分割为 ServerHello 和剩下的部分。

                            // TLS handshake record: 1 byte type + 3 bytes length + data
                            // 在 QUIC 中没有 TLS record layer，直接是 handshake messages
                            // handshake message: 1 byte type + 3 bytes length + data
                            if tls_data.len() < 4 {
                                return Err(QuicServerError::PacketParse("tls_data too short".into()));
                            }
                            let _msg_type = tls_data[0];
                            let msg_len = ((tls_data[1] as usize) << 16)
                                | ((tls_data[2] as usize) << 8)
                                | (tls_data[3] as usize);
                            // checked 算术：TLS 消息长度来自对端，溢出即 fail-closed
                            let server_hello_end = 4usize
                                .checked_add(msg_len)
                                .ok_or_else(|| QuicServerError::PacketParse("ServerHello len overflow".into()))?;
                            if server_hello_end > tls_data.len() {
                                return Err(QuicServerError::PacketParse(
                                    "ServerHello out of bounds".into(),
                                ));
                            }
                            let server_hello = &tls_data[..server_hello_end];
                            let remaining = &tls_data[server_hello_end..];

                            tracing::debug!(
                                server_hello_len = server_hello.len(),
                                remaining_len = remaining.len(),
                                "QUIC Initial split ServerHello"
                            );

                            // 1. 用 Initial keys 发送 ServerHello (CRYPTO frame, 累计偏移)
                            // RFC 9000 §13.1: MUST ACK client's Initial in server's Initial
                            let init_off = self.initial_crypto_tx_offset;
                            let crypto_frame = build_crypto_frame(init_off, server_hello);
                            self.initial_crypto_tx_offset = self
                                .initial_crypto_tx_offset
                                .checked_add(server_hello.len() as u64)
                                .ok_or_else(|| QuicServerError::PacketParse("initial crypto tx offset overflow".into()))?;
                            let ack_frame = build_ack_frame(self.largest_initial_pn, 0, 0);
                            let mut init_payload = Vec::with_capacity(ack_frame.len() + crypto_frame.len());
                            init_payload.extend_from_slice(&ack_frame);
                            init_payload.extend_from_slice(&crypto_frame);
                            let initial_packet = QuicConnection::build_long_packet(
                                version,
                                &self.client_scid,
                                &self.server_scid,
                                0, // Initial long_frame
                                &self.initial_keys,
                                &mut self.next_initial_pn,
                                &init_payload,
                            )?;
                            output_packets.push(initial_packet);

                            // 2. 保存 Handshake keys
                            self.handshake_keys = Some(keys);

                            // 3. 如果有 remaining 数据，用 Handshake keys 发送（累计偏移）
                            if !remaining.is_empty() {
                                let hs_off = self.handshake_crypto_tx_offset;
                                let crypto_frame = build_crypto_frame(hs_off, remaining);
                                self.handshake_crypto_tx_offset = self
                                    .handshake_crypto_tx_offset
                                    .checked_add(remaining.len() as u64)
                                    .ok_or_else(|| QuicServerError::PacketParse("handshake crypto tx offset overflow".into()))?;
                                let handshake_packet = QuicConnection::build_long_packet(
                                    version,
                                    &self.client_scid,
                                    &self.server_scid,
                                    2, // Handshake long_frame
                                    self.handshake_keys
                                        .as_ref()
                                        .ok_or(QuicServerError::HandshakeNotComplete)?,
                                    &mut self.next_handshake_pn,
                                    &crypto_frame,
                                )?;
                                output_packets.push(handshake_packet);
                            }

                            // 更新状态
                            self.state = QuicServerState::HandshakeSent;
                        } else {
                            // 没有 key change：根据是否已有 Handshake keys 选择加密空间。
                            // rustls 的 write_hs 行为：
                            //   第一次 → (ServerHello, Some(Handshake keys))：ServerHello 属 Initial space
                            //   第二次 → (EE+Cert+CertVerify+Finished, None)：属 Handshake space
                            // 因此若 handshake_keys 已就绪，本次 tls_data 必为 Handshake space，
                            // 必须用 Handshake keys 加密；否则客户端无法解密（客户端已丢弃 Initial keys）。
                            if let Some(hs_keys) = self.handshake_keys.as_ref() {
                                let hs_off = self.handshake_crypto_tx_offset;
                                let crypto_frame = build_crypto_frame(hs_off, &tls_data);
                                let handshake_packet = QuicConnection::build_long_packet(
                                    version,
                                    &self.client_scid,
                                    &self.server_scid,
                                    2, // Handshake long_frame
                                    hs_keys,
                                    &mut self.next_handshake_pn,
                                    &crypto_frame,
                                )?;
                                self.handshake_crypto_tx_offset = self
                                    .handshake_crypto_tx_offset
                                    .checked_add(tls_data.len() as u64)
                                    .ok_or_else(|| QuicServerError::PacketParse("handshake crypto tx offset overflow".into()))?;
                                output_packets.push(handshake_packet);
                            } else {
                                // 还在 Initial space（首次握手中）
                                // RFC 9000 §13.1: ACK client's Initial
                                let init_off = self.initial_crypto_tx_offset;
                                let crypto_frame = build_crypto_frame(init_off, &tls_data);
                                self.initial_crypto_tx_offset = self
                                    .initial_crypto_tx_offset
                                    .checked_add(tls_data.len() as u64)
                                    .ok_or_else(|| QuicServerError::PacketParse("initial crypto tx offset overflow".into()))?;
                                let ack_frame = build_ack_frame(self.largest_initial_pn, 0, 0);
                                let mut init_payload = Vec::with_capacity(ack_frame.len() + crypto_frame.len());
                                init_payload.extend_from_slice(&ack_frame);
                                init_payload.extend_from_slice(&crypto_frame);
                                let initial_packet = QuicConnection::build_long_packet(
                                    version,
                                    &self.client_scid,
                                    &self.server_scid,
                                    0,
                                    &self.initial_keys,
                                    &mut self.next_initial_pn,
                                    &init_payload,
                                )?;
                                output_packets.push(initial_packet);
                            }
                        }
                    }
                }
                None => break,
            }
        }

        // 提取 1-RTT keys（rustls 在 KeyChange::OneRtt 时存入 crypto_session）。
        // 注意：此处仅提取 keys，不发送 HANDSHAKE_DONE。
        // RFC 9001 §4.9: 服务器必须在收到并验证客户端 Finished 后才能发送 HANDSHAKE_DONE。
        // HANDSHAKE_DONE 由 handle_handshake_packet 在 is_handshaking() == false 时发送。
        if self.one_rtt_keys.is_none()
            && let Some(keys) = self.crypto_session.take_one_rtt_keys()
        {
            // 先存 keys：即使后续传输参数校验失败，也需要 1-RTT keys
            // 构造 CONNECTION_CLOSE 帧（h3spec 已丢弃 Initial keys，
            // 用 Initial keys 发的 CC 帧会被忽略）
            self.one_rtt_keys = Some(keys);
            // RFC 9000 §18.2：校验客户端传输参数
            // h3spec Transport 7.3/18.2：缺失/非法参数 → TRANSPORT_PARAMETER_ERROR
            if let Some(tp) = self.crypto_session.peer_transport_params() {
                if let Err(e) = validate_peer_transport_params(tp) {
                    tracing::warn!("peer transport params invalid: {}", e);
                    return Err(QuicServerError::PacketParse(format!(
                        "TRANSPORT_PARAMETER_ERROR: {e}"
                    )));
                }
            }
            tracing::debug!("QUIC 1-RTT keys extracted (waiting for client Finished)");
        }

        // RFC 9002 被动重传：CRYPTO 全部为重传（consumed 未推进）且本端无新输出时，
        // 说明对端未收到本端响应航班而重传 CRYPTO——必须重发缓存航班，
        // 否则对端握手超时（响应包在路径上丢失的唯一恢复途径）。
        let crypto_advanced = self.initial_crypto_consumed > prev_consumed;
        if crypto_advanced && !output_packets.is_empty() {
            // 新数据产生新航班：更新缓存（后续重传以此为准）
            self.initial_flight = output_packets.clone();
        } else if had_crypto && !crypto_advanced && !self.initial_flight.is_empty() {
            tracing::debug!(
                flight_len = self.initial_flight.len(),
                "QUIC Initial CRYPTO retransmission detected → retransmit initial flight"
            );
            output_packets = self.initial_flight.clone();
        }

        Ok(output_packets)
    }

    /// 处理 0-RTT 包（RFC 9001 §5.7 + RFC 8446 §4.2.10）
    ///
    /// # 安全模型（fail-closed）
    /// - 无 early_secret（客户端未提供有效 PSK）→ 静默丢弃（返回空 vec）
    /// - AEAD 解密失败 → 错误向上传播（上层记日志并丢弃，不杀连接）
    /// - 帧类型白名单：0-RTT 包仅允许 PADDING/PING/STREAM 等应用帧；
    ///   CRYPTO/ACK/CONNECTION_CLOSE/HANDSHAKE_DONE 出现即协议错误（RFC 9001 §5.7）
    /// - 0-RTT 流数据与 1-RTT 严格分离（early_stream_rx），
    ///   应用层必须实施防重放策略（H3 层仅接受幂等方法）
    ///
    /// # 包号空间
    /// 0-RTT 与 1-RTT 共享包号空间（RFC 9000 §12.3），
    /// 使用 largest_1rtt_pn 解码；0-RTT 包不单独 ACK（握手完成后在 1-RTT 空间确认）。
    pub fn handle_0rtt_packet(
        &mut self,
        packet: &[u8],
    ) -> Result<Vec<Vec<u8>>, QuicServerError> {
        let parsed = parse_long_header_full(packet)?;
        if parsed.long_frame != 1 {
            return Err(QuicServerError::PacketParse(format!(
                "not a 0-RTT packet: long_frame={}",
                parsed.long_frame
            )));
        }

        // 首次 0-RTT 包到达时派生并缓存 keys（rustls 内部不缓存，避免重复派生）
        if self.zero_rtt_keys.is_none() {
            match self.crypto_session.zero_rtt_keys() {
                Some(keys) => {
                    self.zero_rtt_keys = Some(keys);
                    tracing::debug!("QUIC 0-RTT keys derived (client attempting early data)");
                }
                None => {
                    // 无 early_secret：客户端未提供有效 PSK，0-RTT 包无法解密。
                    // RFC 9001 §5.7：静默丢弃，不视为错误（可能是中间人注入）。
                    tracing::debug!("QUIC 0-RTT packet dropped: no early secret");
                    return Ok(Vec::new());
                }
            }
        }
        let keys = self
            .zero_rtt_keys
            .as_ref()
            .ok_or_else(|| QuicServerError::PacketParse("0-RTT keys unavailable".into()))?;

        let pn_offset = parsed.pn_offset;
        let length_value = parsed.length as usize;
        let packet_end = pn_offset
            .checked_add(length_value)
            .ok_or_else(|| QuicServerError::PacketParse("packet_end overflow".into()))?;
        if packet_end > packet.len() {
            return Err(QuicServerError::PacketParse("payload out of bounds".into()));
        }

        let mut buf = packet[..packet_end].to_vec();
        let hp_key = &*keys.header;
        let sample_len = hp_key.sample_len();
        let sample_start = pn_offset
            .checked_add(4) // MAX_PKT_NUM_LEN = 4
            .ok_or_else(|| QuicServerError::PacketParse("sample_start overflow".into()))?;
        let sample_end = sample_start
            .checked_add(sample_len)
            .ok_or_else(|| QuicServerError::PacketParse("sample_end overflow".into()))?;
        if sample_end > buf.len() {
            return Err(QuicServerError::PacketParse("hp sample too short".into()));
        }
        let sample = buf[sample_start..sample_end].to_vec();
        let mut first_byte = buf[0];
        {
            let pn_bytes = &mut buf[pn_offset..sample_start];
            remove_header_protection(hp_key, &sample, &mut first_byte, pn_bytes)?;
        }
        buf[0] = first_byte;

        let real_pn_len = ((first_byte & 0x03) as usize) + 1;
        let header_end = pn_offset
            .checked_add(real_pn_len)
            .ok_or_else(|| QuicServerError::PacketParse("header_end overflow".into()))?;
        if header_end > packet_end {
            return Err(QuicServerError::PacketParse("header_end out of bounds".into()));
        }

        let mut pn_plain: u64 = 0;
        for i in 0..real_pn_len {
            pn_plain = (pn_plain << 8) | (buf[pn_offset + i] as u64);
        }
        // 0-RTT 与 1-RTT 共享包号空间（RFC 9000 §12.3）
        let pn = decode_packet_number(pn_plain, real_pn_len, self.largest_1rtt_pn);
        // RFC 9000 §A.3：largest 为最大已认证包号，乱序到达禁止回退
        self.largest_1rtt_pn = self.largest_1rtt_pn.max(pn);

        let ciphertext_len = packet_end
            .checked_sub(header_end)
            .ok_or_else(|| QuicServerError::PacketParse("ciphertext_len underflow".into()))?;
        let (header, payload) = buf.split_at_mut(header_end);
        let header: &[u8] = header;
        let payload = &mut payload[..ciphertext_len];
        let decrypted = decrypt_packet(&*keys.packet, pn, header, payload)?;

        let frames = parse_frames(decrypted);
        tracing::debug!(pn, decrypted_len = decrypted.len(), frame_count = frames.len(), "QUIC 0-RTT packet");

        for frame in &frames {
            match frame {
                QuicFrame::Stream {
                    stream_id,
                    offset,
                    fin,
                    data,
                } => {
                    let sid = *stream_id;
                    // 流控强制与 1-RTT 一致（RFC 9000 §4 对 early data 同样适用）
                    let end = offset.saturating_add(data.len() as u64);
                    if end > Self::FC_MAX_STREAM_DATA {
                        return Err(QuicServerError::FlowControl(format!(
                            "0-RTT stream {sid} end={end} > max_stream_data={}",
                            Self::FC_MAX_STREAM_DATA
                        )));
                    }
                    let prev_end = self.fc_stream_end.get(&sid).copied().unwrap_or(0);
                    if end > prev_end {
                        self.fc_conn_consumed =
                            self.fc_conn_consumed.saturating_add(end - prev_end);
                        self.fc_stream_end.insert(sid, end);
                    }
                    if self.fc_conn_consumed > Self::FC_MAX_DATA {
                        return Err(QuicServerError::FlowControl(format!(
                            "0-RTT connection consumed={} > max_data={}",
                            self.fc_conn_consumed,
                            Self::FC_MAX_DATA
                        )));
                    }
                    let stream_buf = self.early_stream_rx.entry(sid).or_default();
                    stream_buf.insert(*offset, data);
                    if *fin {
                        stream_buf.fin_offset = Some(end);
                    }
                    tracing::debug!(stream_id = sid, offset = *offset, data_len = data.len(), fin = *fin, "QUIC 0-RTT STREAM");
                }
                // RFC 9001 §5.7 允许的非 STREAM 帧：PADDING/PING 直接忽略
                QuicFrame::Padding | QuicFrame::Ping => {}
                // 其余帧类型在 0-RTT 包中非法（CRYPTO/ACK/CONNECTION_CLOSE/HANDSHAKE_DONE 等）
                other => {
                    return Err(QuicServerError::PacketParse(format!(
                        "illegal frame in 0-RTT packet: {other:?} (RFC 9001 §5.7)"
                    )));
                }
            }
        }

        // 0-RTT 包不产生直接响应（ACK 在握手完成后于 1-RTT 空间发送）
        Ok(Vec::new())
    }

    /// 取出 0-RTT 早期流数据（take 语义：取出即清除）
    ///
    /// 防重放第一道：同一份 early data 只允许被消费一次；
    /// 重放的 0-RTT 包（相同包号）由包号跟踪天然去重。
    pub fn take_early_stream_data(&mut self, stream_id: u64) -> Option<Vec<u8>> {
        self.early_stream_rx
            .get_mut(&stream_id)
            .and_then(StreamRecv::take_contiguous)
    }

    /// 取出 0-RTT 流 FIN 状态（take 语义）
    pub fn take_early_stream_fin(&mut self, stream_id: u64) -> bool {
        self.early_stream_rx
            .get_mut(&stream_id)
            .is_some_and(StreamRecv::take_fin)
    }

    /// 处理 Handshake 包（来自客户端）
    pub fn handle_handshake_packet(
        &mut self,
        packet: &[u8],
    ) -> Result<Vec<Vec<u8>>, QuicServerError> {
        let keys = self
            .handshake_keys
            .as_ref()
            .ok_or(QuicServerError::PacketParse("no handshake keys".into()))?;
        let parsed = parse_long_header_full(packet)?;
        if parsed.long_frame != 2 {
            return Err(QuicServerError::PacketParse(format!(
                "not a Handshake packet: long_frame={}",
                parsed.long_frame
            )));
        }
        // RFC 9000 §17.2: reserved bits 检查移到 HP 移除后（见 L2021）

        let pn_offset = parsed.pn_offset;
        let length_value = parsed.length as usize;
        // checked 算术：攻击者可控的 length/pn_offset 溢出即 fail-closed
        let packet_end = pn_offset
            .checked_add(length_value)
            .ok_or_else(|| QuicServerError::PacketParse("packet_end overflow".into()))?;
        if packet_end > packet.len() {
            return Err(QuicServerError::PacketParse("payload out of bounds".into()));
        }

        let mut buf = packet[..packet_end].to_vec();
        let hp_key = &*keys.remote.header;
        let sample_len = hp_key.sample_len();
        let sample_start = pn_offset
            .checked_add(4) // MAX_PKT_NUM_LEN = 4
            .ok_or_else(|| QuicServerError::PacketParse("sample_start overflow".into()))?;
        let sample_end = sample_start
            .checked_add(sample_len)
            .ok_or_else(|| QuicServerError::PacketParse("sample_end overflow".into()))?;
        if sample_end > buf.len() {
            return Err(QuicServerError::PacketParse("hp sample too short".into()));
        }
        let sample = buf[sample_start..sample_end].to_vec();
        let mut first_byte = buf[0];
        {
            let pn_bytes = &mut buf[pn_offset..sample_start];
            remove_header_protection(hp_key, &sample, &mut first_byte, pn_bytes)?;
        }
        buf[0] = first_byte;

        let real_pn_len = ((first_byte & 0x03) as usize) + 1;
        // RFC 9000 §17.2: Long Header reserved bits (bits 3-2) must be 0 (HP 移除后检查)
        if first_byte & 0x0C != 0 {
            return Err(QuicServerError::PacketParse(
                "PROTOCOL_VIOLATION: reserved bits in Handshake header are non-zero".into(),
            ));
        }
        let header_end = pn_offset
            .checked_add(real_pn_len)
            .ok_or_else(|| QuicServerError::PacketParse("header_end overflow".into()))?;
        // fail-closed：解密出的 pn_len 可能超出 Length 字段声明范围
        if header_end > packet_end {
            return Err(QuicServerError::PacketParse("header_end out of bounds".into()));
        }

        let mut pn_plain: u64 = 0;
        for i in 0..real_pn_len {
            pn_plain = (pn_plain << 8) | (buf[pn_offset + i] as u64);
        }
        let pn = decode_packet_number(
            pn_plain,
            real_pn_len,
            self.largest_handshake_pn,
        );
        self.largest_handshake_pn = pn;

        let ciphertext_len = packet_end
            .checked_sub(header_end)
            .ok_or_else(|| QuicServerError::PacketParse("ciphertext_len underflow".into()))?;
        let (header, payload) = buf.split_at_mut(header_end);
        let header: &[u8] = header;
        let payload = &mut payload[..ciphertext_len];
        let decrypted = decrypt_packet(&*keys.remote.packet, pn, header, payload)?;

        let frames = parse_frames(decrypted);
        let had_crypto = frames.iter().any(|f| matches!(f, QuicFrame::Crypto { .. }));
        tracing::debug!(pn, decrypted_len = decrypted.len(), frame_count = frames.len(), "QUIC Handshake packet");

        // RFC 9000 §17.2.4: PATH_CHALLENGE 不得出现在 Handshake 包中 → PROTOCOL_VIOLATION
        if frames.iter().any(|f| matches!(f, QuicFrame::PathChallenge { .. })) {
            return Err(QuicServerError::PacketParse(
                "PROTOCOL_VIOLATION: PATH_CHALLENGE in Handshake packet".into(),
            ));
        }

        // 按 offset 重组 Handshake CRYPTO 流（与 Initial 同理）
        for frame in &frames {
            if let QuicFrame::Crypto { offset, data } = frame {
                let off = *offset as usize;
                // checked 算术：CRYPTO offset 攻击者可控，溢出即 fail-closed
                let end = off
                    .checked_add(data.len())
                    .ok_or_else(|| QuicServerError::PacketParse("crypto offset overflow".into()))?;
                if end > self.handshake_crypto_rx.len() {
                    if end > MAX_CRYPTO_BUFFER_SIZE {
                        return Err(QuicServerError::PacketParse(
                            "CRYPTO buffer exceeds maximum size".into(),
                        ));
                    }
                    self.handshake_crypto_rx.resize(end, 0);
                }
                self.handshake_crypto_rx[off..end].copy_from_slice(data);
            }
        }

        let prev_hs_consumed = self.handshake_crypto_consumed;
        let hs_consumed = self.handshake_crypto_consumed;
        let hs_available = self.handshake_crypto_rx.len();
        if hs_available > hs_consumed {
            let new_data = &self.handshake_crypto_rx[hs_consumed..hs_available];
            self.crypto_session.process_handshake_data(new_data)?;
            self.handshake_crypto_consumed = hs_available;
        }

        let mut output_packets = Vec::new();
        let version = self.version();

        // 循环 write_hs 把 rustls 想发的数据全部取出。
        // 注意：KeyChange::OneRtt 时 rustls 把 1-RTT keys 存到 crypto_session 内部
        // 并返回 new_keys=None（见 zenith-tls/src/quic.rs::write_handshake），
        // 因此这里不再依赖 new_keys 判断握手完成。
        loop {
            let result = self.crypto_session.write_handshake()?;
            // rustls 在处理完客户端 Finished 的同一次 write_hs 中返回
            // NewSessionTicket（1-RTT 级数据）并派生 OneRtt keys（zenith-tls 存内部）。
            // 必须检测此转换：该数据只能以 1-RTT 短包发送，而非 Handshake 包
            // （否则 ngtcp2 视其为握手完成后 Handshake 级 CRYPTO，协议违规）。
            if self.one_rtt_keys.is_none()
                && let Some(keys) = self.crypto_session.take_one_rtt_keys()
            {
                    self.one_rtt_keys = Some(keys);
                    tracing::debug!("QUIC HS 1-RTT keys taken");
                    // HANDSHAKE_DONE 必须先于 ticket 发出（RFC 9001 §4.9）
                    if !self.handshake_done_sent && !self.crypto_session.is_handshaking() {
                        self.state = QuicServerState::HandshakeDone;
                        let hd_frame = build_handshake_done_frame();
                        tracing::debug!(pn = self.next_1rtt_pn, "QUIC handshake complete, sending HANDSHAKE_DONE");
                        let packet = QuicConnection::build_short_packet(
                            &self.client_scid,
                            self.one_rtt_keys
                                .as_ref()
                                .ok_or(QuicServerError::HandshakeNotComplete)?,
                            &mut self.next_1rtt_pn,
                            &hd_frame,
                            self.key_phase,
                        )?;
                        output_packets.push(packet);
                        self.handshake_done_sent = true;
                    }
            }
            // 握手完成后 write_hs 只产生 post-handshake 数据（ticket/KeyUpdate），
            // 全部属于 1-RTT 级。
            let use_one_rtt =
                self.one_rtt_keys.is_some() && !self.crypto_session.is_handshaking();
            match result {
                Some((tls_data, _new_keys)) => {
                    if !tls_data.is_empty() {
                        if use_one_rtt {
                            // 1-RTT 级：NewSessionTicket（RFC 8446 §4.6.1）
                            let crypto_frame =
                                build_crypto_frame(self.one_rtt_crypto_tx_offset, &tls_data);
                            self.one_rtt_crypto_tx_offset = self
                                .one_rtt_crypto_tx_offset
                                .checked_add(tls_data.len() as u64)
                                .ok_or_else(|| QuicServerError::PacketParse("1rtt crypto tx offset overflow".into()))?;
                            tracing::debug!(len = tls_data.len(), "QUIC issuing NewSessionTicket in 1-RTT CRYPTO");
                            let packet = QuicConnection::build_short_packet(
                                &self.client_scid,
                                self.one_rtt_keys
                                    .as_ref()
                                    .ok_or(QuicServerError::HandshakeNotComplete)?,
                                &mut self.next_1rtt_pn,
                                &crypto_frame,
                                self.key_phase,
                            )?;
                            output_packets.push(packet);
                        } else {
                            // Handshake 级：用 Handshake keys 发送（累计偏移）
                            let hs_off = self.handshake_crypto_tx_offset;
                            let crypto_frame = build_crypto_frame(hs_off, &tls_data);
                            self.handshake_crypto_tx_offset = self
                                .handshake_crypto_tx_offset
                                .checked_add(tls_data.len() as u64)
                                .ok_or_else(|| QuicServerError::PacketParse("handshake crypto tx offset overflow".into()))?;
                            let handshake_packet = QuicConnection::build_long_packet(
                                version,
                                &self.client_scid,
                                &self.server_scid,
                                2,
                                self.handshake_keys
                                    .as_ref()
                                    .ok_or(QuicServerError::HandshakeNotComplete)?,
                                &mut self.next_handshake_pn,
                                &crypto_frame,
                            )?;
                            output_packets.push(handshake_packet);
                        }
                    }
                }
                None => break,
            }
        }

        // 握手完成后取 1-RTT keys 并发送 HANDSHAKE_DONE
        // RFC 9001 §4.9: 服务器必须在收到并验证客户端 Finished 后才能发送 HANDSHAKE_DONE。
        // is_handshaking() 返回 false 表示 rustls 已处理完客户端 Finished，握手真正完成。
        if self.one_rtt_keys.is_none()
            && let Some(keys) = self.crypto_session.take_one_rtt_keys()
        {
            self.one_rtt_keys = Some(keys);
            tracing::debug!("QUIC HS 1-RTT keys taken");
        }
        if !self.handshake_done_sent && self.one_rtt_keys.is_some() && !self.crypto_session.is_handshaking() {
            self.state = QuicServerState::HandshakeDone;
            let hd_frame = build_handshake_done_frame();
            let one_rtt_keys = self
                .one_rtt_keys
                .as_ref()
                .ok_or(QuicServerError::HandshakeNotComplete)?;
            tracing::debug!(pn = self.next_1rtt_pn, "QUIC handshake complete, sending HANDSHAKE_DONE");
            let packet = QuicConnection::build_short_packet(
                &self.client_scid,
                one_rtt_keys,
                &mut self.next_1rtt_pn,
                &hd_frame,
                self.key_phase,
            )?;
            output_packets.push(packet);
            self.handshake_done_sent = true;
        }

        // 握手完成后签发 NewSessionTicket（RFC 8446 §4.6.1，经 1-RTT CRYPTO 帧）。
        // rustls 在握手完成且 send_tls13_tickets>0 时将 ticket 排队到 write_hs；
        // 循环取出所有排队数据（rustls 可能分多次/延迟生成），逐一以 1-RTT CRYPTO 帧发送。
        if self.handshake_done_sent && self.one_rtt_keys.is_some() {
            loop {
                match self.crypto_session.write_handshake() {
                    Ok(Some((tls_data, _))) if !tls_data.is_empty() => {
                        let crypto_frame =
                            build_crypto_frame(self.one_rtt_crypto_tx_offset, &tls_data);
                        self.one_rtt_crypto_tx_offset = self
                            .one_rtt_crypto_tx_offset
                            .checked_add(tls_data.len() as u64)
                            .ok_or_else(|| QuicServerError::PacketParse("1rtt crypto tx offset overflow".into()))?;
                        tracing::debug!(len = tls_data.len(), "QUIC issuing NewSessionTicket in 1-RTT CRYPTO");
                        let packet = QuicConnection::build_short_packet(
                            &self.client_scid,
                            self.one_rtt_keys
                                .as_ref()
                                .ok_or(QuicServerError::HandshakeNotComplete)?,
                            &mut self.next_1rtt_pn,
                            &crypto_frame,
                            self.key_phase,
                        )?;
                        output_packets.push(packet);
                    }
                    _ => break,
                }
            }
        }

        // RFC 9002 被动重传：本包 CRYPTO 全部为重传（consumed 未推进）时，
        // 对端未收到本端数据航班（Handshake CRYPTO/HANDSHAKE_DONE/ticket），
        // 重发缓存航班（随后附加新 ACK 确认本包）。
        let hs_crypto_advanced = self.handshake_crypto_consumed > prev_hs_consumed;
        if hs_crypto_advanced && !output_packets.is_empty() {
            // 新数据航班：更新缓存（不含尾部纯 ACK——ACK 在下方统一生成）
            self.handshake_flight = output_packets.clone();
        } else if had_crypto && !hs_crypto_advanced && !self.handshake_flight.is_empty() {
            tracing::debug!(
                flight_len = self.handshake_flight.len(),
                "QUIC Handshake CRYPTO retransmission detected → retransmit handshake flight"
            );
            output_packets = self.handshake_flight.clone();
        }

        // 对收到的 Handshake 包回 ACK（使用 Handshake keys 加密）
        // 客户端需要 ACK 来确认其 Handshake 包已收到，否则会重传
        let ack_frame = build_ack_frame(pn, 0, 0);
        let ack_packet = QuicConnection::build_long_packet(
            version,
            &self.client_scid,
            &self.server_scid,
            2, // Handshake
            self.handshake_keys
                .as_ref()
                .ok_or(QuicServerError::HandshakeNotComplete)?,
            &mut self.next_handshake_pn,
            &ack_frame,
        )?;
        output_packets.push(ack_packet);

        Ok(output_packets)
    }

    /// 处理 1-RTT 包（来自客户端的 Short Header）
    pub fn handle_short_packet(
        &mut self,
        packet: &[u8],
    ) -> Result<Vec<Vec<u8>>, QuicServerError> {
        // RFC 9000 §17.3: Short Header reserved bits (bits 3-2 of first byte) must be 0
        // 但只能在 HP 移除后检查（reserved bits 在 HP 后才可见）
        let pn_offset = parse_short_header(packet, self.server_dcid.len())?.pn_offset;
        let mut buf = packet.to_vec();
        let mut first_byte = buf[0];
        // HP 移除（短作用域借用；HP keys 在密钥更新中不变，RFC 9001 §6.1）
        {
            let keys = self
                .one_rtt_keys
                .as_ref()
                .ok_or(QuicServerError::HandshakeNotComplete)?;
            let hp_key = &*keys.remote.header;
            let sample_len = hp_key.sample_len();
            // checked 算术：pn_offset 来自包解析，溢出即 fail-closed
            let sample_start = pn_offset
                .checked_add(4) // MAX_PKT_NUM_LEN = 4
                .ok_or_else(|| QuicServerError::PacketParse("sample_start overflow".into()))?;
            let sample_end = sample_start
                .checked_add(sample_len)
                .ok_or_else(|| QuicServerError::PacketParse("sample_end overflow".into()))?;
            if sample_end > buf.len() {
                return Err(QuicServerError::PacketParse("hp sample too short".into()));
            }
            let sample = buf[sample_start..sample_end].to_vec();
            let pn_bytes = &mut buf[pn_offset..sample_start];
            remove_header_protection(hp_key, &sample, &mut first_byte, pn_bytes)?;
        }
        buf[0] = first_byte;

        // Key Phase 检测（RFC 9001 §6.1）：相位翻转 = 对端已发起密钥更新，
        // 本端必须派生下一代 keys 才能解密（MUST support key updates）。
        // HP keys 不更新，仅 packet keys 替换（local/remote 同代推进）。
        let packet_key_phase = (first_byte & 0x04) != 0;
        if packet_key_phase != self.key_phase {
            let new_keys = self.crypto_session.next_packet_keys()?;
            let keys_mut = self
                .one_rtt_keys
                .as_mut()
                .ok_or(QuicServerError::HandshakeNotComplete)?;
            keys_mut.local.packet = new_keys.local;
            keys_mut.remote.packet = new_keys.remote;
            self.key_phase = packet_key_phase;
            self.key_update_count = self
                .key_update_count
                .checked_add(1)
                .ok_or_else(|| QuicServerError::PacketParse("key update count overflow".into()))?;
            tracing::debug!(
                count = self.key_update_count,
                phase = self.key_phase,
                "QUIC key update (peer initiated)"
            );
        }

        let real_pn_len = ((first_byte & 0x03) as usize) + 1;
        // RFC 9000 §17.3: Short Header reserved bits (bits 3-2) must be 0 (HP 移除后检查)
        if first_byte & 0x0C != 0 {
            let ack_frame = build_ack_frame(0, 0, 0);
            self.pending_err_ack = Some(ack_frame);
            return Err(QuicServerError::PacketParse(
                "PROTOCOL_VIOLATION: reserved bits in Short header are non-zero".into(),
            ));
        }
        let header_end = pn_offset
            .checked_add(real_pn_len)
            .ok_or_else(|| QuicServerError::PacketParse("header_end overflow".into()))?;
        // fail-closed：解密出的 pn_len 可能超出包边界
        if header_end > buf.len() {
            return Err(QuicServerError::PacketParse("header_end out of bounds".into()));
        }

        let mut pn_plain: u64 = 0;
        for i in 0..real_pn_len {
            pn_plain = (pn_plain << 8) | (buf[pn_offset + i] as u64);
        }
        let pn = decode_packet_number(
            pn_plain,
            real_pn_len,
            self.largest_1rtt_pn,
        );
        // RFC 9000 §A.3：largest 为最大已认证包号，乱序到达禁止回退
        self.largest_1rtt_pn = self.largest_1rtt_pn.max(pn);

        let (header, payload) = buf.split_at_mut(header_end);
        let header: &[u8] = header;
        // 解密（密钥更新后重新借用，使用当前相位 keys）
        let keys = self
            .one_rtt_keys
            .as_ref()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        let decrypted = decrypt_packet(&*keys.remote.packet, pn, header, payload)?;

        let frames = parse_frames(decrypted);

        // RFC 9000 §12.4：检测未解析完的帧字节（未知帧类型/截断帧）
        let mut total_consumed = 0usize;
        let mut tmp_buf: &[u8] = decrypted;
        loop {
            match parse_frame(tmp_buf) {
                Some((_, c)) => { total_consumed += c; tmp_buf = &tmp_buf[c..]; }
                None => break,
            }
        }
        let unparsed = decrypted.len() - total_consumed;
        let has_unparsed_error = unparsed > 0
            && !decrypted[total_consumed..].iter().all(|&b| b == 0x00);

        {
            // 诊断：帧类型单字符统计
            let mut kinds = String::with_capacity(64);
            let mut padding = 0u32;
            for f in &frames {
                match f {
                    QuicFrame::Stream { .. } => kinds.push('S'),
                    QuicFrame::Ack { .. } => kinds.push('A'),
                    QuicFrame::Padding => padding += 1,
                    QuicFrame::Ping => kinds.push('P'),
                    QuicFrame::Crypto { .. } => kinds.push('C'),
                    QuicFrame::HandshakeDone => kinds.push('H'),
                    QuicFrame::ConnectionClose { .. } => kinds.push('X'),
                    QuicFrame::PathChallenge { .. } => kinds.push('c'),
                    QuicFrame::PathResponse { .. } => kinds.push('r'),
                    _ => kinds.push('?'),
                }
            }
            tracing::debug!(pn, frames = %kinds, padding, "QUIC 1-RTT pkt frames");
        }

        let mut output_packets = Vec::new();

        // 处理每个帧
        let mut needs_ack = false;
        for frame in &frames {
            match frame {
                QuicFrame::Stream {
                    stream_id,
                    offset,
                    fin,
                    data,
                } => {
                    let sid = *stream_id;
                    // RFC 9000 §19.8：stream ID 超出 initial_max_streams 上限 →
                    // STREAM_LIMIT_ERROR（h3spec Transport 4.1）
                    if sid >= Self::FC_MAX_STREAM_ID {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(format!(
                            "STREAM_LIMIT_ERROR: stream_id={sid} >= max_stream_id={}",
                            Self::FC_MAX_STREAM_ID
                        )));
                    }
                    // RFC 9000 §19.8：STREAM frame 对 send-only stream（服务端发起的单向流）
                    // 由客户端发出（客户端是 receiver），server 不应收到 → STREAM_STATE_ERROR
                    // server-initiated uni stream: sid % 4 == 3（mod 4 = 3 is server server-side uni）
                    if sid % 4 == 3 {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(format!(
                            "STREAM_STATE_ERROR: STREAM frame on send-only stream {sid}"
                        )));
                    }
                    // RFC 9000 §19.8：STREAM frame 对未完成初始化的本地发起流（client 发起的 bidi
                    // 我方 server 端本地没有打开该流）→ STREAM_STATE_ERROR
                    // mod 4=2 是 client-initiated uni, mod 4=0 是 client-initiated bidi ✓ OK
                    // mod 4=1 是 server-initiated bidi → STREAM_STATE_ERROR（未注册/不存在的流）
                    if sid % 4 == 1 && !self.stream_rx.contains_key(&sid) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(format!(
                            "STREAM_STATE_ERROR: STREAM on locally-initiated non-existing stream {sid}"
                        )));
                    }
                    // RFC 9000 §4 流控强制：按 offset 跟踪每流最高 end，连接级增量累加。
                    // 重传/乱序的同 offset 数据不重复计数（end 不增则不计）。
                    let end = offset.saturating_add(data.len() as u64);
                    if end > Self::FC_MAX_STREAM_DATA {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::FlowControl(format!(
                            "stream {sid} end={end} > max_stream_data={}",
                            Self::FC_MAX_STREAM_DATA
                        )));
                    }
                    let prev_end = self.fc_stream_end.get(&sid).copied().unwrap_or(0);
                    if end > prev_end {
                        self.fc_conn_consumed =
                            self.fc_conn_consumed.saturating_add(end - prev_end);
                        self.fc_stream_end.insert(sid, end);
                    }
                    if self.fc_conn_consumed > Self::FC_MAX_DATA {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::FlowControl(format!(
                            "connection consumed={} > max_data={}",
                            self.fc_conn_consumed,
                            Self::FC_MAX_DATA
                        )));
                    }
                    // 收到 stream 数据（按 offset 重组，重传/乱序去重裁剪）
                    let stream_buf = self.stream_rx.entry(sid).or_default();
                    if !stream_buf.insert(*offset, data) {
                        // 纯重传（无新字节）：对端未收到本端响应，标记供响应重发
                        if !self.dup_stream_sids.contains(&sid) {
                            self.dup_stream_sids.push(sid);
                        }
                    }
                    if *fin {
                        stream_buf.fin_offset = Some(end);
                    }
                    tracing::debug!(stream_id = sid, offset = *offset, data_len = data.len(), fin = *fin, "QUIC 1-RTT STREAM");
                    needs_ack = true;
                }
                QuicFrame::Crypto { data, .. } => {
                    // RFC 9000 §19.5: 1-RTT CRYPTO（客户端不允许只发 CRYPTO 在 1-RTT;
                    // 如果 rustls 报错（如 unexpected message / EndOfEarlyData），
                    // 必须传播为连接错误，否则 h3spec 期望的 TLS alert/CC 不会触发）
                    if let Err(e) = self.crypto_session.process_handshake_data(data) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(e.into());
                    }
                    needs_ack = true;
                }
                QuicFrame::HandshakeDone => {
                    // RFC 9000 §19.20：HANDSHAKE_DONE 仅服务端发送，客户端发 → PROTOCOL_VIOLATION
                    // 先发 ACK（h3spec 期望 PN 窗口前进后再收 CONNECTION_CLOSE）
                    let ack_frame = build_ack_frame(pn, 0, 0);
                    self.pending_err_ack = Some(ack_frame);
                    return Err(QuicServerError::PacketParse(
                        "PROTOCOL_VIOLATION: client must not send HANDSHAKE_DONE".into(),
                    ));
                }
                QuicFrame::ConnectionClose {
                    error_code,
                    frame_type,
                    reason,
                } => {
                    tracing::debug!(
                        "QUIC 1-RTT CONNECTION_CLOSE received from peer: error_code=0x{error_code:x} ({error_code}), frame_type=0x{frame_type:x}, reason={:?}",
                        String::from_utf8_lossy(reason)
                    );
                    self.state = QuicServerState::Closed;
                    return Ok(Vec::new());
                }
                QuicFrame::NewToken { .. } => {
                    // RFC 9000 §19.7：NEW_TOKEN 仅服务端发送，客户端发 → PROTOCOL_VIOLATION
                    let ack_frame = build_ack_frame(pn, 0, 0);
                    self.pending_err_ack = Some(ack_frame);
                    return Err(QuicServerError::PacketParse(
                        "PROTOCOL_VIOLATION: client must not send NEW_TOKEN".into(),
                    ));
                }
                QuicFrame::Ping => {
                    needs_ack = true;
                }
                QuicFrame::Ack { ack_ranges, .. } => {
                    // ACK 帧：驱动拥塞控制（移除已确认包 + cwnd 增长 + RTT 估计）。
                    // 纯 ACK 不具 ack-eliciting，自身不再触发 ACK（防 ACK 乒乓）。
                    self.process_1rtt_ack(ack_ranges);
                }
                QuicFrame::PathChallenge { data } => {
                    // RFC 9000 §8.2：对 PATH_CHALLENGE 必须回以 PATH_RESPONSE（回显 8 字节）。
                    // 这是对端验证本端路径可达性的唯一机制，缺失会导致迁移失败。
                    tracing::debug!(data = ?data, "QUIC 1-RTT PATH_CHALLENGE → PATH_RESPONSE");
                    let resp_frame = build_path_response_frame(data);
                    let pkt = QuicConnection::build_short_packet(
                        &self.client_scid,
                        self.one_rtt_keys
                            .as_ref()
                            .ok_or(QuicServerError::HandshakeNotComplete)?,
                        &mut self.next_1rtt_pn,
                        &resp_frame,
                        self.key_phase,
                    )?;
                    output_packets.push(pkt);
                    needs_ack = true; // PATH_CHALLENGE 为 ack-eliciting
                }
                QuicFrame::PathResponse { data } => {
                    // RFC 9000 §9：收到 PATH_RESPONSE，记录供上层做迁移路径验证。
                    self.pending_path_response.push(*data);
                }
                QuicFrame::ResetStream { stream_id, .. } => {
                    let sid = *stream_id;
                    // RFC 9000 §19.4: RESET_STREAM 仅对 bidirectional streams 有效.
                    // sid%4=2: client uni, sid%4=3: server uni → 都是单向流, RESET_STREAM → STREAM_STATE_ERROR
                    if sid % 4 >= 2 {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("STREAM_STATE_ERROR: RESET_STREAM on unidirectional stream {sid}"),
                        ));
                    }
                    needs_ack = true;
                }
                QuicFrame::StopSending { stream_id, .. } => {
                    let sid = *stream_id;
                    // RFC 9000 §19.5：STOP_SENDING 由接收方发给发送方，请求停止发送。
                    // 本端（server）可发送的流：bidi（mod 4=0/1）与本端发起的 uni（mod 4=3）。
                    // mod 4=2（client 发起的 uni）：client 是发送方而非接收方，client 发
                    // STOP_SENDING 语义错误 → STREAM_STATE_ERROR。
                    if sid % 4 == 2 {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("STREAM_STATE_ERROR: STOP_SENDING on send-only stream {sid}"),
                        ));
                    }
                    // RFC 9000 §19.5：STOP_SENDING 指向"本端（server）未打开的本地发起流"
                    // （server-initiated uni mod 4=3 / server bidi mod 4=1）→ STREAM_STATE_ERROR。
                    // client-initiated bidi（mod 4=0）由对端隐式打开，始终接受。
                    if sid % 4 != 0 && !self.server_opened_streams.contains(&sid) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("STREAM_STATE_ERROR: STOP_SENDING on non-existing stream {sid}"),
                        ));
                    }
                    needs_ack = true;
                }
                QuicFrame::MaxStreamData { stream_id, .. } => {
                    let sid = *stream_id;
                    // RFC 9000 §19.10：MAX_STREAM_DATA 由接收方发给发送方，增加发送方向
                    // 流控窗口。本端（server）可发送的流：bidi（mod 4=0/1）与本端发起的
                    // uni（mod 4=3）。
                    if sid % 4 == 2 {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("STREAM_STATE_ERROR: MAX_STREAM_DATA on send-only stream {sid}"),
                        ));
                    }
                    // RFC 9000 §19.10：MAX_STREAM_DATA 指向"本端（server）未打开的本地发起流"
                    // → STREAM_STATE_ERROR。client-initiated bidi（mod 4=0）的流由对端先行
                    // 通告窗口（curl/nghttp3 在 STREAM 帧前先发 MAX_STREAM_DATA）必须接受。
                    if sid % 4 != 0 && !self.server_opened_streams.contains(&sid) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("STREAM_STATE_ERROR: MAX_STREAM_DATA on non-existing stream {sid}"),
                        ));
                    }
                    needs_ack = true;
                }
                f @ QuicFrame::MaxStreamsBidi { .. } | f @ QuicFrame::MaxStreamsUni { .. } => {
                    // RFC 9000 §19.11: MAX_STREAMS 值超过 2^60 → FRAME_ENCODING_ERROR
                    let max_streams = match &f {
                        QuicFrame::MaxStreamsBidi { max_streams } => *max_streams,
                        QuicFrame::MaxStreamsUni { max_streams } => *max_streams,
                        _ => 0,
                    };
                    if max_streams > (1u64 << 60) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            "FRAME_ENCODING_ERROR: MAX_STREAMS value exceeds 2^60".into(),
                        ));
                    }
                    needs_ack = true;
                }
                f @ QuicFrame::StreamsBlockedBidi { .. } | f @ QuicFrame::StreamsBlockedUni { .. } => {
                    // RFC 9000 §19.14: STREAMS_BLOCKED 值超过 2^60 → FRAME_ENCODING_ERROR
                    let limit = match &f {
                        QuicFrame::StreamsBlockedBidi { limit } => *limit,
                        QuicFrame::StreamsBlockedUni { limit } => *limit,
                        _ => 0,
                    };
                    if limit > (1u64 << 60) {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            "FRAME_ENCODING_ERROR: STREAMS_BLOCKED value exceeds 2^60".into(),
                        ));
                    }
                    needs_ack = true;
                }
                QuicFrame::NewConnectionId { sequence_number, retire_prior_to, connection_id, .. } => {
                    // RFC 9000 §19.15: Retire_Prior_To > Sequence_Number → FRAME_ENCODING_ERROR
                    if retire_prior_to > sequence_number {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            format!("FRAME_ENCODING_ERROR: NEW_CONNECTION_ID Retire_Prior_To {retire_prior_to} > Sequence_Number {sequence_number}"),
                        ));
                    }
                    // RFC 9000 §19.15: CID 长度不能为 0
                    if connection_id.is_empty() {
                        let ack_frame = build_ack_frame(pn, 0, 0);
                        self.pending_err_ack = Some(ack_frame);
                        return Err(QuicServerError::PacketParse(
                            "FRAME_ENCODING_ERROR: NEW_CONNECTION_ID with 0-byte CID".into(),
                        ));
                    }
                    needs_ack = true;
                }
                _ => {
                    // RFC 9000 §12.4：未知帧类型静默跳过（已由 parse_frame 处理）
                    needs_ack = true;
                }
            }
        }

        // RFC 9000 §12.4：未解析帧字节 → FRAME_ENCODING_ERROR
        if has_unparsed_error {
            let ack_frame = build_ack_frame(pn, 0, 0);
            self.pending_err_ack = Some(ack_frame);
            return Err(QuicServerError::PacketParse(
                "FRAME_ENCODING_ERROR: unparsed frame bytes".into(),
            ));
        }
        // RFC 9000 §12.4：无帧（空包或纯 PADDING）→ PROTOCOL_VIOLATION
        if frames.is_empty() {
            let ack_frame = build_ack_frame(pn, 0, 0);
            self.pending_err_ack = Some(ack_frame);
            return Err(QuicServerError::PacketParse(
                "PROTOCOL_VIOLATION: no frames in 1-RTT packet".into(),
            ));
        }

        // 如果状态是 HandshakeDone，升级到 Established
        if self.state == QuicServerState::HandshakeDone {
            self.state = QuicServerState::Established;
            self.established_at = Some(Instant::now());
        }

        // 发送 ACK
        if needs_ack {
            let ack_frame = build_ack_frame(pn, 0, 0);
            let ack_packet = QuicConnection::build_short_packet(
                &self.client_scid,
                self.one_rtt_keys
                    .as_ref()
                    .ok_or(QuicServerError::HandshakeNotComplete)?,
                &mut self.next_1rtt_pn,
                &ack_frame,
                self.key_phase,
            )?;
            output_packets.push(ack_packet);
        }

        Ok(output_packets)
    }

    /// 构造 Long Header 包（Initial 或 Handshake）
    ///
    /// long_frame: 0=Initial, 2=Handshake
    ///
    /// 关联函数（非 &self 方法），允许调用方同时传入 `&mut self.next_*_pn`
    /// 而不与 `&self.client_scid` / `&self.server_scid` 冲突（disjoint field borrows）。
    pub fn build_long_packet(
        version: u32,
        client_scid: &[u8],
        server_scid: &[u8],
        long_frame: u8,
        keys: &Keys,
        next_pn: &mut u64,
        payload: &[u8],
    ) -> Result<Vec<u8>, QuicServerError> {
        let pn = *next_pn;
        // checked 算术：包号单调递增，溢出即 fail-closed（防回绕重放）
        *next_pn = pn
            .checked_add(1)
            .ok_or_else(|| QuicServerError::PacketParse("packet number overflow".into()))?;

        // 包号长度 4 字节（最大）
        let pn_len: usize = 4;
        let pn_bytes: [u8; 4] = (pn as u32).to_be_bytes();

        // CRYPTO 帧（payload）
        let payload_len = payload.len();
        let tag_len = keys.local.packet.tag_len();

        // 长度字段 = pn_len + payload_len + tag_len
        let length_field = pn_len
            .checked_add(payload_len)
            .and_then(|v| v.checked_add(tag_len))
            .ok_or_else(|| QuicServerError::PacketParse("length field overflow".into()))?;

        // first_byte：1 + Long Frame Type bits + 0x40 (Quic Bit) + pn_len - 1 (low 2 bits)
        // Actually: Long Header bit 7=1, bit 6 (Quic Bit)=1 (must be 1)
        // bits 5-4: Long Frame Type (00=Initial, 10=Handshake, 01=0-RTT, 11=Retry)
        // bits 3-2: Reserved (must be 0)
        // bits 1-0: Packet Number length - 1
        let mut first_byte: u8 = 0x80 | 0x40; // Long + Quic Bit
        first_byte |= (long_frame & 0x03) << 4; // Long Frame Type
        first_byte |= ((pn_len - 1) as u8) & 0x03; // PN length - 1

        // 构造 header（不含 HP 应用）
        let mut header = Vec::new();
        header.push(first_byte);
        header.extend_from_slice(&version.to_be_bytes());
        // DCID = client's SCID
        header.push(client_scid.len() as u8);
        header.extend_from_slice(client_scid);
        // SCID = server's SCID
        header.push(server_scid.len() as u8);
        header.extend_from_slice(server_scid);
        // Token (仅 Initial)
        if long_frame == 0 {
            header.push(0); // Token length = 0 (varint)
        }
        // Length field (varint)
        push_varint(&mut header, length_field as u64);
        // Packet number
        header.extend_from_slice(&pn_bytes);

        // 构造明文 payload（payload + tag_len 字节预留）
        let mut plaintext = Vec::with_capacity(payload_len + tag_len);
        plaintext.extend_from_slice(payload);
        plaintext.extend(std::iter::repeat_n(0u8, tag_len));

        // AEAD 加密（在 plaintext[..payload_len] 上加密，追加 tag 到 [payload_len..]）
        // fail-closed：AEAD 失败向上传播，禁止 panic
        let tag = keys
            .local
            .packet
            .encrypt_in_place(pn, &header, &mut plaintext[..payload_len])?;
        // 把 tag 写入 plaintext[payload_len..]
        let tag_end = payload_len
            .checked_add(tag_len)
            .ok_or_else(|| QuicServerError::PacketParse("tag end overflow".into()))?;
        plaintext[payload_len..tag_end].copy_from_slice(tag.as_ref());

        // 现在 plaintext = 加密的 payload + tag

        // 应用 Header Protection
        let mut packet = header.clone();
        packet.extend_from_slice(&plaintext);

        // HP sample 取自加密 payload 的前 16 字节
        let hp_key = &*keys.local.header;
        let sample_len = hp_key.sample_len();
        let sample_start = header.len(); // 加密 payload 起始位置
        let sample_end = sample_start
            .checked_add(sample_len)
            .ok_or_else(|| QuicServerError::PacketParse("sample end overflow".into()))?;
        if sample_end <= packet.len() {
            let sample = packet[sample_start..sample_end].to_vec();
            // 应用 HP 到 first_byte 和 packet_number
            let pn_offset_in_packet = header.len() - pn_len;
            let mut first_byte = packet[0];
            let pn_end = pn_offset_in_packet
                .checked_add(pn_len)
                .ok_or_else(|| QuicServerError::PacketParse("pn end overflow".into()))?;
            {
                let pn_bytes = &mut packet[pn_offset_in_packet..pn_end];
                let _ = apply_header_protection(hp_key, &sample, &mut first_byte, pn_bytes);
            }
            packet[0] = first_byte;
        } else {
            // fail-closed：HP 未应用的包不得发出（否则对端无法解密且违反 RFC 9001 §5.4）
            return Err(QuicServerError::PacketParse(
                "hp sample too short, refuse to send unprotected packet".into(),
            ));
        }

        tracing::debug!(long_frame, pn, packet_len = packet.len(), payload_len, "QUIC build long packet");

        Ok(packet)
    }

    /// 构造 Short Header 包（1-RTT）
    ///
    /// 关联函数（非 &self 方法），允许 disjoint field borrows。
    ///
    /// `key_phase`：当前密钥相位（RFC 9001 §6），写入 first_byte bit 2 (0x04)，
    /// 对端据此选择对应相位的解密密钥。
    pub fn build_short_packet(
        server_scid: &[u8],
        keys: &Keys,
        next_pn: &mut u64,
        payload: &[u8],
        key_phase: bool,
    ) -> Result<Vec<u8>, QuicServerError> {
        let pn = *next_pn;
        // checked 算术：包号单调递增，溢出即 fail-closed（防回绕重放）
        *next_pn = pn
            .checked_add(1)
            .ok_or_else(|| QuicServerError::PacketParse("packet number overflow".into()))?;

        let pn_len = 4;
        let pn_bytes: [u8; 4] = (pn as u32).to_be_bytes();

        tracing::debug!(pn, payload = %format!("{:02x?}", payload), "QUIC SEND 1-RTT plaintext");

        let payload_len = payload.len();
        let tag_len = keys.local.packet.tag_len();

        // first_byte: bit 7=0 (Short), bit 6=1 (Fixed Bit), bit 5=0 (no spin bit),
        //             bit 4=Reserved(0), bit 3=Key Phase, bits 1-0=pn_len-1
        let mut first_byte: u8 = 0x40; // Fixed Bit = 1 (must be 1 in v1)
        if key_phase {
            first_byte |= 0x04; // Key Phase bit（RFC 9001 §6.1）
        }
        first_byte |= ((pn_len - 1) as u8) & 0x03;

        let mut header = Vec::new();
        header.push(first_byte);
        // DCID = server's SCID (client uses server's SCID as DCID)
        header.extend_from_slice(server_scid);
        // Packet number
        header.extend_from_slice(&pn_bytes);

        // 加密 payload + tag
        let mut plaintext = Vec::with_capacity(payload_len + tag_len);
        plaintext.extend_from_slice(payload);
        plaintext.extend(std::iter::repeat_n(0u8, tag_len));

        // fail-closed：AEAD 失败向上传播，禁止 panic
        let tag = keys
            .local
            .packet
            .encrypt_in_place(pn, &header, &mut plaintext[..payload_len])?;
        let tag_end = payload_len
            .checked_add(tag_len)
            .ok_or_else(|| QuicServerError::PacketParse("tag end overflow".into()))?;
        plaintext[payload_len..tag_end].copy_from_slice(tag.as_ref());

        let mut packet = header.clone();
        packet.extend_from_slice(&plaintext);

        // HP
        let hp_key = &*keys.local.header;
        let sample_len = hp_key.sample_len();
        let header_len = packet.len() - plaintext.len();
        let sample_start = header_len;
        let sample_end = sample_start
            .checked_add(sample_len)
            .ok_or_else(|| QuicServerError::PacketParse("sample end overflow".into()))?;
        if sample_end <= packet.len() {
            let sample = packet[sample_start..sample_end].to_vec();
            let pn_offset_in_packet = header_len - pn_len;
            let mut first_byte = packet[0];
            let pn_end = pn_offset_in_packet
                .checked_add(pn_len)
                .ok_or_else(|| QuicServerError::PacketParse("pn end overflow".into()))?;
            {
                let pn_bytes = &mut packet[pn_offset_in_packet..pn_end];
                let _ = apply_header_protection(hp_key, &sample, &mut first_byte, pn_bytes);
            }
            packet[0] = first_byte;
        } else {
            // fail-closed：HP 未应用的包不得发出（否则对端无法解密且违反 RFC 9001 §5.4）
            return Err(QuicServerError::PacketParse(
                "hp sample too short, refuse to send unprotected packet".into(),
            ));
        }

        Ok(packet)
    }

    /// 获取 TLS alert（rustls 握手失败时由 rustls 设置）
    /// 返回 (0x0100 + alert_code) 用于 CRYPTO_ERROR CONNECTION_CLOSE error code
    pub fn peer_alert_code(&self) -> u64 {
        self.crypto_session
            .alert()
            .map(|a| 0x0100 + u8::from(a) as u64)
            .unwrap_or(0x0100)
    }

    /// 获取版本
    pub fn version(&self) -> u32 {
        match self.crypto_session.version() {
            QuicVersion::V1 => QUIC_VERSION_V1,
            QuicVersion::V2 => QUIC_VERSION_V2,
        }
    }

    /// 发送 1-RTT 数据到指定 stream
    pub fn build_stream_packet(
        &mut self,
        stream_id: u64,
        offset: u64,
        fin: bool,
        data: &[u8],
    ) -> Result<Vec<u8>, QuicServerError> {
        let keys = self
            .one_rtt_keys
            .as_ref()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        let stream_frame = build_stream_frame(stream_id, offset, fin, data);
        // 记录服务端已打开的流（RFC 9000 §19.5/§19.10：STOP_SENDING/MAX_STREAM_DATA
        // 指向未打开的本地发起流 → STREAM_STATE_ERROR）
        self.server_opened_streams.insert(stream_id);
        let pn = self.next_1rtt_pn;
        let packet = QuicConnection::build_short_packet(
            &self.client_scid,
            keys,
            &mut self.next_1rtt_pn,
            &stream_frame,
            self.key_phase,
        )?;
        // 拥塞控制：记录已发包并计入在途字节（ACK 到达时移除并驱动 cwnd）
        let bytes = packet.len() as u64;
        self.congestion.on_send(bytes);
        self.track_sent(SentPacket {
            pn,
            bytes,
            sent_at: Instant::now(),
            ack_eliciting: true,
        });
        Ok(packet)
    }

    /// 构造一个承载任意帧字节的 1-RTT 包（用于 PATH_CHALLENGE 等控制帧）
    pub fn build_1rtt_packet(&mut self, frame_bytes: &[u8]) -> Result<Vec<u8>, QuicServerError> {
        let keys = self
            .one_rtt_keys
            .as_ref()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        let pkt = QuicConnection::build_short_packet(
            &self.client_scid,
            keys,
            &mut self.next_1rtt_pn,
            frame_bytes,
            self.key_phase,
        )?;
        Ok(pkt)
    }

    /// 用 Initial keys 构造一个承载 CONNECTION_CLOSE 的 Long Header 包
    ///
    /// 用于握手阶段协议错误（1-RTT keys 不可用时）。
    pub fn build_initial_cc_packet(
        &mut self,
        frame_bytes: &[u8],
    ) -> Result<Vec<u8>, QuicServerError> {
        let version = self.version();
        let pkt = QuicConnection::build_long_packet(
            version,
            &self.client_scid,
            &self.server_scid,
            0, // Initial
            &self.initial_keys,
            &mut self.next_initial_pn,
            frame_bytes,
        )?;
        Ok(pkt)
    }

    /// 用 Handshake keys 构造一个承载 CONNECTION_CLOSE 的 Long Header 包
    ///
    /// 用于握手阶段协议错误（h3spec 收到 ServerHello 后有 Handshake keys）。
    pub fn build_handshake_cc_packet(
        &mut self,
        frame_bytes: &[u8],
    ) -> Result<Vec<u8>, QuicServerError> {
        let version = self.version();
        let keys = self
            .handshake_keys
            .as_ref()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        let pkt = QuicConnection::build_long_packet(
            version,
            &self.client_scid,
            &self.server_scid,
            2, // Handshake
            keys,
            &mut self.next_handshake_pn,
            frame_bytes,
        )?;
        Ok(pkt)
    }

    /// 合并 ACK 帧 + CONNECTION_CLOSE 帧为单个 1-RTT 加密包
    ///
    /// h3spec 期望 ACK 和 CC 在同一个 QUIC 包中（coalesced frames），
    /// 分开发两个包会导致 PN 跳号解密失败。
    pub fn build_1rtt_cc_packet(
        &mut self,
        ack_frame: &[u8],
        cc_frame: &[u8],
    ) -> Result<Vec<u8>, QuicServerError> {
        let mut payload = Vec::with_capacity(ack_frame.len() + cc_frame.len());
        payload.extend_from_slice(ack_frame);
        payload.extend_from_slice(cc_frame);
        let keys = self
            .one_rtt_keys
            .as_ref()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        let pkt = QuicConnection::build_short_packet(
            &self.client_scid,
            keys,
            &mut self.next_1rtt_pn,
            &payload,
            self.key_phase,
        )?;
        Ok(pkt)
    }

    /// 主动发起密钥更新（RFC 9001 §6.1，MAY initiate）
    ///
    /// 翻转发送相位并派生下一代 keys；后续发送的包使用新相位，
    /// 对端检测到相位翻转后响应式更新其解密密钥。
    ///
    /// # 频率限制（RFC 9001 §6.5）
    /// 调用方负责控制更新频率；每次更新使 AEAD 密钥使用计数归零，
    /// 是突破单密钥 AEAD 加密上限（2^23 包）的唯一手段。
    pub fn initiate_key_update(&mut self) -> Result<(), QuicServerError> {
        let new_keys = self.crypto_session.next_packet_keys()?;
        let keys_mut = self
            .one_rtt_keys
            .as_mut()
            .ok_or(QuicServerError::HandshakeNotComplete)?;
        keys_mut.local.packet = new_keys.local;
        keys_mut.remote.packet = new_keys.remote;
        self.key_phase = !self.key_phase;
        self.key_update_count = self
            .key_update_count
            .checked_add(1)
            .ok_or_else(|| QuicServerError::PacketParse("key update count overflow".into()))?;
        tracing::debug!(
            count = self.key_update_count,
            phase = self.key_phase,
            "QUIC key update (locally initiated)"
        );
        Ok(())
    }

    /// 记录已发送包到待确认队列（容量受限，超出丢弃最旧以防内存膨胀）
    fn track_sent(&mut self, pkt: SentPacket) {
        if self.sent_1rtt.len() >= self.max_tracked_sent {
            self.sent_1rtt.pop_front();
        }
        self.sent_1rtt.push_back(pkt);
    }

    /// 处理 1-RTT ACK 帧：移除已确认包，驱动拥塞窗口增长与 RTT 估计（RFC 9002）
    ///
    /// `ack_ranges` 为 (low, high) 闭区间列表（解析器已把 largest_acked 并入首区间）。
    /// RTT 样本取最新被确认的 ack-eliciting 包，避免 ACK 延迟污染。
    fn process_1rtt_ack(&mut self, ack_ranges: &[(u64, u64)]) {
        let now = Instant::now();
        let mut newly_acked_bytes: u64 = 0;
        // (pn, rtt_us)：最新被确认包的 RTT 样本
        let mut best_sample: Option<(u64, u64)> = None;

        let mut i = 0;
        while i < self.sent_1rtt.len() {
            let pkt = self.sent_1rtt[i];
            let acked = ack_ranges
                .iter()
                .any(|(low, high)| pkt.pn >= *low && pkt.pn <= *high);
            if acked {
                // fail-closed：索引在循环条件内必然有效；若内部状态被破坏则停止扫描
                let Some(pkt) = self.sent_1rtt.remove(i) else {
                    break;
                };
                if pkt.ack_eliciting {
                    newly_acked_bytes = newly_acked_bytes.saturating_add(pkt.bytes);
                    let rtt = now
                        .saturating_duration_since(pkt.sent_at)
                        .as_micros()
                        .max(1) as u64;
                    if best_sample.is_none_or(|(p, _)| pkt.pn > p) {
                        best_sample = Some((pkt.pn, rtt));
                    }
                }
            } else {
                i += 1;
            }
        }

        if newly_acked_bytes > 0 {
            // 无有效样本时沿用当前 srtt（近似不变），初始默认 1ms
            let rtt = best_sample.map(|(_, r)| r).unwrap_or(if self.congestion.srtt > 0 {
                self.congestion.srtt
            } else {
                1000
            });
            self.congestion.on_ack(newly_acked_bytes, rtt);
            self.congestion.reset_pto();
        }
    }

    /// 当前拥塞窗口剩余可用字节数（供上层做发送 pacing）
    #[inline]
    pub fn congestion_available_bytes(&self) -> u64 {
        self.congestion.available_bytes()
    }

    /// 取出已收 stream 数据（连续交付：仅返回从已交付点开始的连续段，
    /// 有空洞时尾部保留在重组缓冲中等待填补）
    pub fn take_stream_data(&mut self, stream_id: u64) -> Option<Vec<u8>> {
        self.stream_rx
            .get_mut(&stream_id)
            .and_then(StreamRecv::take_contiguous)
    }

    /// 查询某个流是否已收到 FIN（对端已关闭发送方向）
    pub fn is_stream_fin(&self, stream_id: u64) -> bool {
        self.stream_rx
            .get(&stream_id)
            .is_some_and(|r| r.fin_offset.is_some())
    }

    /// 消费并返回某个流是否已 FIN（全部数据连续交付后返回 true 一次）
    pub fn take_stream_fin(&mut self, stream_id: u64) -> bool {
        self.stream_rx
            .get_mut(&stream_id)
            .is_some_and(StreamRecv::take_fin)
    }
}

/// 构造默认 QUIC 传输参数（编码后字节）
///
/// 严格按 RFC 9000 §18.2 编码：每个参数 = ID(varint) + length(varint) + value。
///
/// **关键**：整数型参数的 value 也是 varint 编码（不是固定 8 字节大端！）
/// length 字段 = value 的实际字节数。客户端解析时会读 varint 并校验
/// `consumed == param_len`，若用大端编码会导致 "Transport parameter length does not match"。
///
/// # 参数
/// - `client_dcid`: 客户端 Initial 包的 DCID（用于 `original_destination_connection_id`，
///   RFC 9000 §18.2 规定服务端 MUST 发送，值为客户端首个 Initial 的 DCID）
/// - `server_scid`: 服务端的 SCID（用于 `initial_source_connection_id`，
///   RFC 9000 §18.2 规定服务端 SHOULD 发送）
pub fn build_default_transport_params(client_dcid: &[u8], server_scid: &[u8]) -> Vec<u8> {
    let mut params = Vec::new();
    // original_destination_connection_id (ID=0x00): 服务端 MUST 发送，= 客户端首个 Initial 的 DCID
    push_bytes_param(&mut params, 0x00, client_dcid);
    // initial_source_connection_id (ID=0x0f): 服务端 SHOULD 发送，= 服务端 SCID
    push_bytes_param(&mut params, 0x0f, server_scid);
    // max_idle_timeout (ID=0x01): 10 seconds (ms)
    push_int_param(&mut params, 0x01, 10_000);
    // max_udp_payload_size (ID=0x03): 1452
    push_int_param(&mut params, 0x03, 1452);
    // initial_max_data (ID=0x04): 1 MB
    push_int_param(&mut params, 0x04, 1_048_576);
    // initial_max_stream_data_bidi_local (ID=0x05): 256 KB
    push_int_param(&mut params, 0x05, 262_144);
    // initial_max_stream_data_bidi_remote (ID=0x06): 256 KB
    push_int_param(&mut params, 0x06, 262_144);
    // initial_max_stream_data_uni (ID=0x07): 256 KB
    push_int_param(&mut params, 0x07, 262_144);
    // initial_max_streams_bidi (ID=0x08): 100
    push_int_param(&mut params, 0x08, 100);
    // initial_max_streams_uni (ID=0x09): 100
    push_int_param(&mut params, 0x09, 100);
    // active_connection_id_limit (ID=0x0e): 2
    push_int_param(&mut params, 0x0e, 2);
    params
}

/// 编码整数型 transport parameter：ID(varint) + len(varint) + value(varint)
#[inline]
fn push_int_param(out: &mut Vec<u8>, id: u64, value: u64) {
    // TLV 三段（id / len / value-bytes）全程栈缓冲串联，零堆分配
    let mut vb = [0u8; zenith_foundation::varint::MAX_VARINT_SIZE];
    let vn = match zenith_foundation::varint::encode_varint_buf(value, &mut vb) {
        Ok(n) => n,
        Err(_) => return, // 值域契约：内部生成值必 < 2^62（assert 于调用前拦截）
    };
    push_varint(out, id);
    push_varint(out, vn as u64);
    out.extend_from_slice(&vb[..vn]);
}

/// 编码字节型 transport parameter：ID(varint) + len(varint) + value(bytes)
#[inline]
fn push_bytes_param(out: &mut Vec<u8>, id: u64, value: &[u8]) {
    push_varint(out, id);
    push_varint(out, value.len() as u64);
    out.extend_from_slice(value);
}

/// RFC 9000 §18.2：校验客户端传输参数
///
/// 检查对端发送的 transport parameters 是否合法：
/// - original_destination_connection_id 禁止由客户端发送（§18.2，仅服务端发送）
/// - preferred_address 禁止由客户端发送（§18.2）
/// - retry_source_connection_id 禁止由客户端发送（§18.2）
/// - stateless_reset_token 禁止由客户端发送（§18.2）
/// - max_udp_payload_size 必须 >= 1200（§7.4）
/// - ack_delay_exponent 必须 <= 20（§7.4.1）
/// - max_ack_delay 必须 < 2^14（§7.4.1）
fn validate_peer_transport_params(buf: &[u8]) -> Result<(), String> {
    let mut off = 0usize;
    let mut has_initial_scid = false;

    while off < buf.len() {
        let (id, n) = parse_varint(&buf[off..]).ok_or("tp id parse")?;
        off += n;
        let (len, n) = parse_varint(&buf[off..]).ok_or("tp len parse")?;
        off += n;
        let val_end = off.checked_add(len as usize).ok_or("tp length overflow")?;
        if val_end > buf.len() {
            return Err("tp value extends past buffer".into());
        }
        let value = &buf[off..val_end];
        off = val_end;

        match id {
            // RFC 9000 §7.3: initial_source_connection_id 必须存在（h3spec test #3）
            0x0f => {
                has_initial_scid = true;
            }
            // original_destination_connection_id (0x00, §18.2): 客户端禁止发送
            0x00 => {
                return Err("client must not send original_destination_connection_id".into());
            }
            // stateless_reset_token (0x02, §18.2): 仅服务端发送，客户端禁止发送
            0x02 => {
                return Err("client must not send stateless_reset_token".into());
            }
            // preferred_address (0x0d, §18.2): 仅服务端发送，客户端禁止发送
            0x0d => {
                return Err("client must not send preferred_address".into());
            }
            // retry_source_connection_id (0x10, §18.2): 仅服务端发送，客户端禁止发送
            0x10 => {
                return Err("client must not send retry_source_connection_id".into());
            }
            // max_udp_payload_size (§7.4): 必须 >= 1200
            0x03 => {
                let (v, _) = parse_varint(value).ok_or("max_udp_payload_size parse")?;
                if v < 1200 {
                    return Err(format!("max_udp_payload_size={v} < 1200"));
                }
            }
            // ack_delay_exponent (§7.4.1): 必须 <= 20
            0x0a => {
                let (v, _) = parse_varint(value).ok_or("ack_delay_exponent parse")?;
                if v > 20 {
                    return Err(format!("ack_delay_exponent={v} > 20"));
                }
            }
            // max_ack_delay (0x0b, §7.4.1): 必须 < 2^14
            0x0b => {
                let (v, _) = parse_varint(value).ok_or("max_ack_delay parse")?;
                if v >= (1 << 14) {
                    return Err(format!("max_ack_delay={v} >= 2^14"));
                }
            }
            _ => {}
        }
    }

    // RFC 9000 §7.3: initial_source_connection_id 缺失 → TRANSPORT_PARAMETER_ERROR
    if !has_initial_scid {
        return Err("missing initial_source_connection_id".into());
    }

    Ok(())
}

/// QUIC 服务器
pub struct QuicServer {
    /// UDP socket
    socket: UdpSocket,
    /// 配置
    config: QuicServerConfig,
}

impl std::fmt::Debug for QuicServer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("QuicServer")
            .field("bind_addr", &self.config.bind_addr)
            .field("version", &self.config.version)
            .finish()
    }
}

impl QuicServer {
    /// 创建新的 QUIC 服务器
    pub fn bind(config: QuicServerConfig) -> Result<Self, QuicServerError> {
        let socket = UdpSocket::bind(config.bind_addr)?;
        socket.set_nonblocking(false)?;
        Ok(Self { socket, config })
    }

    /// 接收一个 QUIC 连接（阻塞模式）
    ///
    /// 完成 TLS 1.3 握手并返回 QuicConnection
    pub fn accept(&self) -> Result<QuicConnection, QuicServerError> {
        let mut buf = vec![0u8; self.config.max_recv_bytes];
        let mut established = false;
        let mut conn: Option<QuicConnection> = None;

        let deadline = Instant::now() + Duration::from_millis(self.config.idle_timeout_ms);

        while !established && Instant::now() < deadline {
            self.socket.set_read_timeout(Some(Duration::from_millis(1000)))?;
            match self.socket.recv_from(&mut buf) {
                Ok((n, client_addr)) => {
                    let packet = &buf[..n];
                    if packet.is_empty() {
                        continue;
                    }

                    let first_byte = packet[0];
                    let is_long = (first_byte & 0x80) != 0;

                    if conn.is_none() {
                        // 第一个包必须是 Initial
                        if !is_long {
                            continue; // 不是 Initial，忽略
                        }
                        let parsed = match parse_long_header_full(packet) {
                            Ok(p) => p,
                            Err(_) => continue,
                        };
                        if parsed.long_frame != 0 {
                            continue; // 不是 Initial
                        }

                        // 创建连接
                        let server_scid = self.config.scid.clone();
                        let new_conn = match QuicConnection::new(
                            client_addr,
                            parsed.scid.clone(),       // client SCID
                            parsed.dcid.clone(),       // client DCID (= server SCID? no, this is the initial DCID)
                            server_scid,
                            self.config.rustls_config.clone(),
                            self.config.version,
                        ) {
                            Ok(c) => c,
                            Err(_) => continue,
                        };
                        conn = Some(new_conn);
                    }

                    // fail-closed：连接创建失败已 continue，此处理论必有值；仍优雅跳过而非 panic
                    let Some(conn) = conn.as_mut() else {
                        continue;
                    };

                    // 处理包
                    let output_packets = if is_long {
                        let parsed = match parse_long_header_full(packet) {
                            Ok(p) => p,
                            Err(_) => continue,
                        };
                        match parsed.long_frame {
                            0 => match conn.handle_initial_packet(packet) {
                                Ok(pkts) => pkts,
                                Err(e) => {
                                    tracing::warn!(error = %e, "QUIC handle_initial_packet failed");
                                    Vec::new()
                                }
                            },
                            2 => match conn.handle_handshake_packet(packet) {
                                Ok(pkts) => pkts,
                                Err(e) => {
                                    tracing::warn!(error = %e, "QUIC handle_handshake_packet failed");
                                    Vec::new()
                                }
                            },
                            _ => Vec::new(),
                        }
                    } else {
                        match conn.handle_short_packet(packet) {
                            Ok(pkts) => pkts,
                            Err(e) => {
                                tracing::warn!(error = %e, "QUIC handle_short_packet failed");
                                Vec::new()
                            }
                        }
                    };

                    // 发送响应包
                    for pkt in output_packets {
                        match self.socket.send_to(&pkt, conn.client_addr) {
                            Ok(n) => tracing::debug!(peer = %conn.client_addr, len = n, "QUIC send"),
                            Err(e) => tracing::warn!(peer = %conn.client_addr, error = %e, "QUIC send failed"),
                        }
                    }

                    if conn.is_handshake_done() && conn.state == QuicServerState::Established {
                        established = true;
                    }
                }
                Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
                {
                    continue;
                }
                Err(e) => return Err(QuicServerError::Io(e)),
            }
        }

        conn.ok_or(QuicServerError::Timeout)
    }

    /// 接收一个 1-RTT 包并返回连接（用于已建立的连接）
    pub fn recv_packet(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr), QuicServerError> {
        self.socket.set_read_timeout(Some(Duration::from_millis(self.config.idle_timeout_ms)))?;
        match self.socket.recv_from(buf) {
            Ok((n, addr)) => Ok((n, addr)),
            Err(e) => Err(QuicServerError::Io(e)),
        }
    }

    /// 发送数据包
    pub fn send_to(&self, buf: &[u8], addr: SocketAddr) -> Result<usize, QuicServerError> {
        Ok(self.socket.send_to(buf, addr)?)
    }

    /// 获取 socket 引用
    pub fn socket(&self) -> &UdpSocket {
        &self.socket
    }

    /// 获取配置引用
    pub fn config(&self) -> &QuicServerConfig {
        &self.config
    }
}

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

    /// 回归（fuzz 实证缺陷）：ACK 帧敌对值解析禁止减法下溢 panic，
    /// 越界必须 fail-closed 返回 None（远程 DoS 防护）
    #[test]
    fn test_parse_frame_ack_underflow_rejected() {
        // first_ack_range > largest_acked（范围成负数）
        let mut hostile = vec![FRAME_ACK as u8];
        push_varint(&mut hostile, 1); // largest_acked = 1
        push_varint(&mut hostile, 0); // ack_delay
        push_varint(&mut hostile, 0); // ack_range_count = 0
        push_varint(&mut hostile, 5); // first_ack_range = 5 > largest_acked
        assert!(parse_frame(&hostile).is_none(), "first_ack_range 下溢必须拒绝");

        // gap 消耗超出 lowest（high = lowest - gap - 2 负）
        let mut hostile2 = vec![FRAME_ACK as u8];
        push_varint(&mut hostile2, 3); // largest = 3
        push_varint(&mut hostile2, 0);
        push_varint(&mut hostile2, 1); // range_count = 1
        push_varint(&mut hostile2, 2); // first = 2 → lowest = 1
        push_varint(&mut hostile2, 10); // gap = 10 > lowest
        push_varint(&mut hostile2, 0); // range_len
        assert!(parse_frame(&hostile2).is_none(), "gap 下溢必须拒绝");

        // range_len 超出 high（low 负）
        let mut hostile3 = vec![FRAME_ACK as u8];
        push_varint(&mut hostile3, 10);
        push_varint(&mut hostile3, 0);
        push_varint(&mut hostile3, 1);
        push_varint(&mut hostile3, 2); // lowest = 8
        push_varint(&mut hostile3, 1); // gap=1 → high = 8-1-2 = 5
        push_varint(&mut hostile3, 6); // range_len = 6 > high
        assert!(parse_frame(&hostile3).is_none(), "range_len 下溢必须拒绝");

        // 合法帧不受影响
        let mut okf = vec![FRAME_ACK as u8];
        push_varint(&mut okf, 10);
        push_varint(&mut okf, 0);
        push_varint(&mut okf, 0);
        push_varint(&mut okf, 2);
        assert!(matches!(parse_frame(&okf), Some((QuicFrame::Ack { .. }, _))));
    }

    #[test]
    fn test_varint_encode_decode() {
        for v in [0u64, 1, 63, 64, 16383, 16384, 1_073_741_823, 1_073_741_824] {
            let encoded = encode_varint(v);
            let (decoded, _) = parse_varint(&encoded).expect("parse should succeed");
            assert_eq!(decoded, v, "varint round-trip failed for {}", v);
        }
    }

    #[test]
    fn test_encode_varint_rfc9000_appendix_a() {
        // RFC 9000 §A.1 已知值（最短编码）
        assert_eq!(encode_varint(37), vec![0x25]);
        assert_eq!(encode_varint(15_293), vec![0x7b, 0xbd]);
        assert_eq!(encode_varint(494_878_333), vec![0x9d, 0x7f, 0x3e, 0x7d]);
        assert_eq!(
            encode_varint(151_288_809_941_952_652),
            vec![0xc2, 0x19, 0x7c, 0x5e, 0xff, 0x14, 0xe8, 0x8c]
        );
        // 非最短编码解码等价：0x40 0x25 与 0x25 同为 37（§16 示例）
        let (v, n) = parse_varint(&[0x40, 0x25]).expect("parse should succeed");
        assert_eq!(v, 37);
        assert_eq!(n, 2);
        // 各长度段边界（段内最小/最大值）
        assert_eq!(encode_varint(63), vec![0x3f]);
        assert_eq!(encode_varint(64), vec![0x40, 0x40]);
        assert_eq!(encode_varint(16_383), vec![0x7f, 0xff]);
        assert_eq!(encode_varint(16_384), vec![0x80, 0x00, 0x40, 0x00]);
        assert_eq!(encode_varint(1_073_741_823), vec![0xbf, 0xff, 0xff, 0xff]);
        assert_eq!(
            encode_varint(1_073_741_824),
            vec![0xc0, 0x00, 0x00, 0x00, 0x40, 0x00, 0x00, 0x00]
        );
        // RFC 9000 §16 最大合法 varint = 2^62 - 1
        assert_eq!(encode_varint((1u64 << 62) - 1), vec![0xff; 8]);
    }

    /// 测试用 rustls ServerConfig（空 SNI resolver，永不解析证书）
    fn dummy_rustls_config() -> Arc<rustls::ServerConfig> {
        let cfg = rustls::ServerConfig::builder()
            .with_no_client_auth()
            .with_cert_resolver(Arc::new(
                rustls::server::ResolvesServerCertUsingSni::new(),
            ));
        Arc::new(cfg)
    }

    #[test]
    fn test_scid_random_not_all_zero() {
        let bind_addr: SocketAddr = "127.0.0.1:0".parse().expect("valid addr");
        let cfg = QuicServerConfig::new(bind_addr, dummy_rustls_config(), QuicVersion::V1)
            .expect("config should build (CSPRNG available)");
        assert_eq!(cfg.scid_len, 8);
        assert_eq!(cfg.scid.len(), 8);
        assert!(
            cfg.scid.iter().any(|&b| b != 0),
            "SCID 不得为全零（可枚举将导致连接 ID 猜测）"
        );
    }

    #[test]
    fn test_scid_random_unique_per_config() {
        let bind_addr: SocketAddr = "127.0.0.1:0".parse().expect("valid addr");
        let c1 = QuicServerConfig::new(bind_addr, dummy_rustls_config(), QuicVersion::V1)
            .expect("config should build");
        let c2 = QuicServerConfig::new(bind_addr, dummy_rustls_config(), QuicVersion::V1)
            .expect("config should build");
        assert_ne!(
            c1.scid, c2.scid,
            "两次构造的 SCID 必须不相等（CSPRNG 随机化，RFC 9000 §7.2）"
        );
        // Debug/Clone 语义保持
        let debug = format!("{:?}", c1);
        assert!(debug.contains("QuicServerConfig"));
        let c3 = c1.clone();
        assert_eq!(c1.scid, c3.scid);
    }

    #[test]
    fn test_packet_number_len() {
        assert_eq!(packet_number_len(0b00), 1);
        assert_eq!(packet_number_len(0b01), 2);
        assert_eq!(packet_number_len(0b10), 3);
        assert_eq!(packet_number_len(0b11), 4);
    }

    #[test]
    fn test_decode_packet_number_simple() {
        // 简单情况：truncated=0, expected=0, pn_len=4 → 还原为 0
        let pn = decode_packet_number(0, 4, 0);
        assert_eq!(pn, 0);

        // 第一次包号通常为 0
        let pn = decode_packet_number(0, 1, 0);
        assert_eq!(pn, 0);
    }

    #[test]
    fn test_build_crypto_frame() {
        let data = b"hello";
        let frame = build_crypto_frame(0, data);
        assert_eq!(frame[0], 0x06); // CRYPTO
        assert_eq!(frame[1], 0);    // offset varint = 0
        assert_eq!(frame[2], 5);    // length varint = 5
        assert_eq!(&frame[3..], data);
    }

    #[test]
    fn test_build_ack_frame() {
        let frame = build_ack_frame(0, 0, 0);
        assert_eq!(frame[0], 0x02); // ACK
        assert_eq!(frame[1], 0);    // largest_acked = 0
        assert_eq!(frame[2], 0);    // ack_delay = 0
        assert_eq!(frame[3], 0);    // ack_range_count = 0
        assert_eq!(frame[4], 0);    // first_ack_range = 0
    }

    #[test]
    fn test_build_stream_frame() {
        let data = b"hello";
        let frame = build_stream_frame(0, 0, true, data);
        // frame_type: 0x08 | FIN(0x01) | LEN(0x02) | OFF(0x04) = 0x0f
        assert_eq!(frame[0], 0x0f);
        assert_eq!(frame[1], 0); // stream_id = 0
        assert_eq!(frame[2], 0); // offset = 0
        assert_eq!(frame[3], 5); // length = 5
        assert_eq!(&frame[4..], data);
    }

    #[test]
    fn test_parse_initial_header() {
        // 构造一个简单的 Initial 包头用于测试 parse_long_header_full
        // 注意：这只是 header 部分，不是完整可解密包
        let mut buf = Vec::new();
        // first byte: Long + Quic + Initial(00) + Reserved(00) + PN_len=4(11)
        buf.push(0xC3);
        // version = 0x00000001 (QUIC v1)
        buf.extend_from_slice(&QUIC_VERSION_V1.to_be_bytes());
        // DCID len + DCID
        buf.push(8);
        buf.extend_from_slice(&[0u8; 8]);
        // SCID len + SCID
        buf.push(8);
        buf.extend_from_slice(&[1u8; 8]);
        // Token len = 0
        buf.push(0);
        // Length (varint): pn_len(4) + payload(10) = 14
        buf.extend_from_slice(&encode_varint(14));
        // Packet number (4 bytes)
        buf.extend_from_slice(&[0u8, 0, 0, 0]);
        // payload (10 bytes)
        buf.extend_from_slice(&[0u8; 10]);

        let parsed = parse_long_header_full(&buf).expect("parse should succeed");
        assert_eq!(parsed.version, QUIC_VERSION_V1);
        assert_eq!(parsed.dcid, vec![0u8; 8]);
        assert_eq!(parsed.scid, vec![1u8; 8]);
        assert_eq!(parsed.long_frame, 0); // Initial
        assert_eq!(parsed.packet_number_len, 4);
        assert_eq!(parsed.payload_len, 10);
    }

    #[test]
    fn test_transport_params_encode() {
        let client_dcid = vec![0u8; 8];
        let server_scid = vec![1u8; 8];
        let params = build_default_transport_params(&client_dcid, &server_scid);
        // 至少应包含若干参数
        assert!(params.len() > 50, "transport params too short: {}", params.len());
        // 必须包含 original_destination_connection_id (ID=0x00)
        // 编码：0x00 (ID) + 0x08 (len) + 8 字节 client_dcid
        assert!(params.starts_with(&[0x00, 0x08]), "missing original_destination_connection_id");
    }
}