zenith-web 0.1.0

//! QUIC 传输服务器：zenith-net QUIC 传输层 ↔ zenith-http3 帧层桥接
//!
//! # 架构（分层协作，零重复实现）
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │               UDP socket (recv_from / send_to)              │
//! └─────────────┬───────────────────────────────────────────────┘
//!               │ 原始 QUIC 数据包
//!               ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │ zenith_net::transport::QuicConnection（RFC 9000/9001）       │
//! │   • Long/Short Header 解析                                  │
//! │   • Header Protection 移除 / AEAD 解密                      │
//! │   • TLS 1.3 握手驱动（rustls QuicCryptoSession）            │
//! │   • 1-RTT 流数据接收 / 发送                                  │
//! └─────────────┬───────────────────────────────────────────────┘
//!               │ 解密后的 stream_id → bytes
//!               ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │ zenith_http3::Http3Connection（RFC 9114）                   │
//! │   • 帧解析（DATA / HEADERS / SETTINGS / RST_STREAM / ...）   │
//! │   • QPACK 编解码（动态表）                                   │
//! │   • 流状态机（Request / Control / Push）                     │
//! │   • send_response() → HEADERS + DATA 帧编码                 │
//! └─────────────┬───────────────────────────────────────────────┘
//!               │ CanonicalRequest / CanonicalResponse
//!               ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │               App (Router / Middleware / Handler)           │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! # 安全保证（Fail-Closed 原则）
//! 1. QUIC 传输层由 zenith-net 处理（rustls 后端，RFC 9001 合规）
//! 2. HP / AEAD 由 zenith-tls 处理
//! 3. HTTP/3 帧解析由 zenith-http3 处理（RFC 9114 合规）
//! 4. 桥接层零自定义加密逻辑，仅做数据路由

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

/// 待重处理 1-RTT 包队列硬上限（防无匹配连接时攻击者无限填充）
const MAX_PENDING_1RTT: usize = 1024;

use rustc_hash::FxHashMap;
use std::net::{SocketAddr, UdpSocket};
use std::sync::Arc;

use zenith_api::{normalize, CanonicalRequest, CanonicalResponse, Transport};
use zenith_http3::connection::{
    FrameAction, Http3Connection, Http3ConnectionConfig,
};
use zenith_http3::frame::{Frame, Http3Error};
use zenith_http3::StreamPriority;
use zenith_net::transport::{
    QuicServerConnection as NetQuicConn, QuicServer as NetQuicServer,
    QuicServerConfig as NetQuicConfig, QuicServerError as NetQuicError,
    QuicServerState,
};
use zenith_net::{build_connection_close_app, build_connection_close_transport};
use zenith_tls::cert_manager::{CertGeneration, CertRotateError};
use zenith_tls::fingerprint::Ja3Fingerprint;
use zenith_tls::quic::QuicVersion;

// ---------------------------------------------------------------------------
// 错误类型
// ---------------------------------------------------------------------------

/// QUIC 传输错误（所有错误路径 fail-closed）
#[derive(Debug)]
pub enum QuicTransportError {
    /// UDP I/O 错误
    Io(std::io::Error),
    /// 证书错误（代际切换/加载失败）
    Cert(CertRotateError),
    /// QUIC 传输层错误
    Quic(String),
}

impl std::fmt::Display for QuicTransportError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(e) => write!(f, "quic io error: {e}"),
            Self::Cert(e) => write!(f, "quic cert error: {e}"),
            Self::Quic(m) => write!(f, "quic transport error: {m}"),
        }
    }
}

impl std::error::Error for QuicTransportError {}

impl From<std::io::Error> for QuicTransportError {
    fn from(e: std::io::Error) -> Self {
        Self::Io(e)
    }
}

impl From<CertRotateError> for QuicTransportError {
    fn from(e: CertRotateError) -> Self {
        Self::Cert(e)
    }
}

impl From<NetQuicError> for QuicTransportError {
    fn from(e: NetQuicError) -> Self {
        Self::Quic(e.to_string())
    }
}

// ---------------------------------------------------------------------------
// 类型别名
// ---------------------------------------------------------------------------

/// QUIC 响应包列表：每个元素为（加密后的包字节，目标地址）
type QuicResponsePackets = Vec<(Vec<u8>, SocketAddr)>;

// ---------------------------------------------------------------------------
// QUIC 传输配置
// ---------------------------------------------------------------------------

/// QUIC 传输服务器配置（用户可见，可 Clone）
#[derive(Debug, Clone)]
pub struct QuicServerConfig {
    /// 监听地址（UDP bind addr）
    pub bind_addr: SocketAddr,
    /// QUIC 版本（保留用于将来版本协商扩展）
    pub version: QuicVersion,
    /// 最大并发连接数
    pub max_connections: usize,
    /// 空闲超时（毫秒）
    pub idle_timeout_ms: u64,
}

impl Default for QuicServerConfig {
    fn default() -> Self {
        Self {
            // 硬编码常量直接构造，避免 parse().unwrap()（零 panic 铁则）
            bind_addr: SocketAddr::new(std::net::IpAddr::V4(std::net::Ipv4Addr::UNSPECIFIED), 443),
            version: QuicVersion::V1,
            max_connections: 65536,
            idle_timeout_ms: 30_000,
        }
    }
}

// ---------------------------------------------------------------------------
// HTTP/3 请求流累积
// ---------------------------------------------------------------------------

/// 待完成的 HTTP/3 流（累积 HEADERS + DATA，收齐后交给 App Handler）
#[derive(Debug, Default)]
struct PendingH3Stream {
    /// 累积的请求体（DATA 帧 payload 拼接）
    body: Vec<u8>,
    /// HEADERS 是否已收到并解码完成
    headers_complete: bool,
    /// 解码后的头部列表
    headers: Vec<(Vec<u8>, Vec<u8>)>,
    /// 对端是否已关闭流（QUIC FIN）
    fin_received: bool,
    /// 是否来自 0-RTT 早期数据（RFC 9001 §5.7）
    ///
    /// 防重放门控（RFC 8446 §8.1）：仅安全方法（GET/HEAD/OPTIONS/TRACE，
    /// RFC 9110 §9.2.1）允许经 0-RTT 处理；非安全方法拒绝并等待客户端
    /// 以 1-RTT 重发（重放只读请求无副作用，重放写请求必须禁止）。
    is_early: bool,
    /// RFC 9218 流优先级（Priority 头 / PRIORITY_UPDATE 帧；缺省 u=3）
    priority: StreamPriority,
}

// ---------------------------------------------------------------------------
// 桥接层辅助：流类型判定 + H3 帧解析
// ---------------------------------------------------------------------------

/// H3 响应发送辅助：编码 CanonicalResponse 为 H3 帧并构建 QUIC 流包，
/// 缓存响应包供 RFC 9002 被动重发，按 RFC 9218 优先级入队调度。
///
/// 供正常响应与错误响应（400 normalize 拒绝 / 421 SNI 不匹配）共用，
/// 禁止在各调用点重复实现发送通路。
fn send_h3_response(
    conn: &mut QuicConn,
    stream_id: u64,
    resp: &CanonicalResponse,
    pri_key: (u8, bool),
    scheduled: &mut Vec<((u8, bool), u64, Vec<u8>)>,
) {
    match conn.h3_conn.send_response(stream_id, resp) {
        Ok(h3_frames) => {
            match conn.net_conn.build_stream_packet(stream_id, 0, true, &h3_frames) {
                Ok(pkt) => {
                    conn.response_cache.insert(stream_id, pkt.clone());
                    scheduled.push((pri_key, stream_id, pkt));
                }
                Err(e) => {
                    tracing::debug!("[H3 RESP] stream_id={} build_stream_packet error: {}", stream_id, e);
                }
            }
        }
        Err(e) => {
            tracing::debug!("[H3 RESP] stream_id={} send_response error: {}", stream_id, e);
        }
    }
}

/// 构造 JSON 错误响应（400/421 等 fail-closed 拒绝共用）
///
/// 参数经 `escape_json_string` 转义，防止 `"`/`\`/控制字符破坏 JSON 结构
/// （JSON 注入防护，与 error.rs `WebError::into_response` 同一策略）。
fn error_response(status: u16, error: &str, reason: &str) -> CanonicalResponse {
    let mut resp = CanonicalResponse::new(status);
    let escaped_error = escape_json_string(error);
    let escaped_reason = escape_json_string(reason);
    resp.set_body(
        format!(r#"{{"error":"{escaped_error}","reason":"{escaped_reason}"}}"#).into_bytes(),
    );
    let _ = resp.add_header(b"content-type", b"application/json");
    resp
}

/// JSON 字符串转义（`"` / `\` / 控制字符），与 error.rs `escape_json_string` 同一实现。
///
/// 提取为 quic_server 模块私有函数，避免跨模块依赖 error.rs 的私有函数。
fn escape_json_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
            c => out.push(c),
        }
    }
    out
}

/// 提取并绑定已到达的 ClientHello JA3/JA4 指纹（若尚未绑定）
///
/// 供新连接路径与 coalesced/分片路径共用：QUIC CRYPTO 帧可能分片到达，
/// ClientHello 在哪个 UDP 包完整，指纹就在哪个 `handle_initial_packet`
/// 返回后绑定。已绑定时幂等跳过（连接级指纹只取首个 ClientHello）。
///
/// # 返回
/// 本次新绑定的指纹（此前未绑定过）；已绑定或未捕获返回 `None`。
fn bind_pending_fingerprint(conn: &mut QuicConn) -> Option<Ja3Fingerprint> {
    if conn.fingerprint.is_none()
        && let Some(fp) = conn.net_conn.take_client_fingerprint()
    {
        tracing::debug!(
            ja3 = %fp.ja3_hash, ja4 = %fp.ja4_hash,
            "QUIC H3 连接绑定 JA3/JA4 指纹"
        );
        conn.set_fingerprint(fp.clone());
        return Some(fp);
    }
    None
}

/// 判定 QUIC 流的 H3 类型
///
/// 根据 stream_id 的 bit 特征和流数据首字节：
/// - client bidi (stream_id % 4 == 0) → Request 流
/// - client uni (stream_id % 4 == 2) → 读取 type prefix：
///   0x00=Control, 0x01=Push（忽略）, 0x02=QpackEncoder, 0x03=QpackDecoder
/// - server bidi (stream_id % 4 == 1) → 响应流（桥接层写回）
/// - server uni (stream_id % 4 == 3) → 推送流或 QPACK 流
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum H3StreamKind {
    /// 请求流（client bidi）
    Request,
    /// 控制流（client uni, type prefix 0x00）
    Control,
    /// QPACK 编码器流（client uni, type prefix 0x02，RFC 9204 §4.2）
    QpackEncoder,
    /// QPACK 解码器流（client uni, type prefix 0x03，RFC 9204 §4.2）
    QpackDecoder,
    /// 未知/忽略（含 Push 流 type prefix 0x01）
    Unknown,
}

/// 从流数据首字节判定 H3 流类型
///
/// 单向流类型前缀（RFC 9114 §6.2 / RFC 9204 §4.2）：
/// - `0x00` = 控制流（Control）
/// - `0x01` = 推送流（Push，本服务器不使用推送 → Unknown 忽略）
/// - `0x02` = QPACK 编码器流（**对端的编码器**，其指令喂入本端解码器）
/// - `0x03` = QPACK 解码器流（**对端的解码器反馈**，其指令喂入本端编码器）
///
/// 与 `zenith_http3::stream::STREAM_TYPE_*` 常量力保持一致（单一事实源），
/// 并经回归测试锁定前缀映射（此前 0x01/0x02 错位曾导致对端编码器指令
/// 被误喂 decoder 路径、对端 decoder 反馈流被静默忽略）。
fn classify_stream(stream_id: u64, data: &[u8]) -> H3StreamKind {
    let low_bits = stream_id % 4;
    match low_bits {
        0 => H3StreamKind::Request,
        2 => {
            if data.is_empty() {
                return H3StreamKind::Unknown;
            }
            match data[0] {
                t if t == zenith_http3::stream::STREAM_TYPE_CONTROL as u8 => H3StreamKind::Control,
                t if t == zenith_http3::stream::STREAM_TYPE_QPACK_ENCODER as u8 => {
                    H3StreamKind::QpackEncoder
                }
                t if t == zenith_http3::stream::STREAM_TYPE_QPACK_DECODER as u8 => {
                    H3StreamKind::QpackDecoder
                }
                _ => H3StreamKind::Unknown,
            }
        }
        _ => H3StreamKind::Unknown,
    }
}

/// 将 QuicServerError 映射为 RFC 9000 §20.1 传输层错误码 + frame_type
///
/// 用于 QUIC 传输层 CONNECTION_CLOSE(0x1c) 帧的 error_code 与 frame_type 字段。
/// crypto 类错误用 (0x0100 + TLS alert code)，h3spec 按 alert code 精确匹配。
fn quic_error_code(e: &NetQuicError) -> (u64, u64) {
    let msg = e.to_string();
    if msg.contains("STREAM_LIMIT_ERROR") {
        return (0x04, 0x08); // STREAM_LIMIT_ERROR, STREAM frame
    }
    if msg.contains("STREAM_STATE_ERROR") {
        return (0x05, 0x08); // STREAM_STATE_ERROR, STREAM frame
    }
    if msg.contains("FRAME_SIZE_ERROR") {
        return (0x06, 0);
    }
    if msg.contains("TRANSPORT_PARAMETER_ERROR") {
        return (0x08, 0); // TRANSPORT_PARAMETER_ERROR
    }
    if msg.contains("PROTOCOL_VIOLATION") {
        return (0x0A, 0); // PROTOCOL_VIOLATION
    }
    if msg.contains("FRAME_ENCODING_ERROR") {
        return (0x07, 0); // FRAME_ENCODING_ERROR
    }
    match e {
        NetQuicError::FlowControl(_) => (0x03, 0x08),      // FLOW_CONTROL_ERROR, STREAM frame
        NetQuicError::PacketParse(_) => (0x07, 0),         // FRAME_ENCODING_ERROR
        NetQuicError::HandshakeNotComplete => (0x07, 0),   // FRAME_ENCODING_ERROR
        NetQuicError::Crypto(_) => (0x0100, 0x06),         // CRYPTO_ERROR base, CRYPTO frame
        _ => (0x07, 0),                                     // FRAME_ENCODING_ERROR (default)
    }
}

/// 将 Http3Error 映射为 RFC 9114 §8.1 定义的 H3 应用错误码
///
/// 用于 QUIC APPLICATION_CLOSE 帧（CONNECTION_CLOSE type=0x1d）的 error_code 字段。
fn h3_error_code(e: &Http3Error) -> u64 {
    match e {
        Http3Error::FrameFormatError(msg) => {
            // QPACK 编码器流错误
            if msg.contains("encoder stream") {
                return 0x0201; // QPACK_ENCODER_STREAM_ERROR
            }
            // QPACK 解码器流错误
            if msg.contains("decoder stream") {
                return 0x0202; // QPACK_DECODER_STREAM_ERROR
            }
            // QPACK 解压失败（静态表索引越界等）
            if msg.contains("QPACK") || msg.contains("qpack") || msg.contains("static index") {
                return 0x0200; // QPACK_DECOMPRESSION_FAILED
            }
            // SETTINGS 相关
            if msg.contains("SETTINGS reserved") || msg.contains("HTTP/2 settings") {
                return 0x0109; // H3_SETTINGS_ERROR
            }
            // MissingSettings 必须在 "control stream" 之前匹配
            if msg.contains("MissingSettings") || msg.contains("missing_settings") {
                return 0x010A; // H3_MISSING_SETTINGS
            }
            // 帧意外（DATA 在 HEADERS 前 / 控制流上的 DATA/HEADERS / 第二个 SETTINGS / CANCEL_PUSH 等）
            if msg.contains("H3_FRAME_UNEXPECTED") || msg.contains("frame unexpected") {
                return 0x0105; // H3_FRAME_UNEXPECTED
            }
            // 伪首部相关
            if msg.contains("pseudo") || msg.contains("pseudo-header") || msg.contains("mandatory") {
                return 0x010E; // H3_MESSAGE_ERROR
            }
            // 控制流关闭
            if msg.contains("control stream") || msg.contains("closed") {
                return 0x0104; // H3_CLOSED_CRITICAL_STREAM
            }
            // 默认帧格式错误
            return 0x0105; // H3_FRAME_UNEXPECTED
        }
        Http3Error::StreamError(_, code) => {
            // Http3ErrorCode 已是 RFC 9114 §8.1 正确值（0x0100-0x0202）
            *code as u64
        }
        Http3Error::ProtocolError(msg) if msg.contains("connection closed") => {
            // h3spec 可能复用同一 QUIC 连接：首次错误已关闭 H3 连接，
            // 后续测试的 on_frame 返回 "connection closed"。
            // 重发首次错误码的 CC（确保 h3spec 收到正确的 QUICException）。
            if msg.contains("connection closed") {
                return 0x0105; // H3_FRAME_UNEXPECTED 默认
            }
            0x0105
        }
        Http3Error::ProtocolError(msg) => {
            // 检查消息内容以区分 RFC 9114 §8.1 的具体错误码
            if msg.contains("H3_MISSING_SETTINGS") || msg.contains("missing_settings") {
                return 0x010A; // H3_MISSING_SETTINGS
            }
            if msg.contains("H3_FRAME_UNEXPECTED") || msg.contains("frame unexpected") {
                return 0x0105; // H3_FRAME_UNEXPECTED
            }
            if msg.contains("H3_SETTINGS_ERROR") || msg.contains("settings error") {
                return 0x0109; // H3_SETTINGS_ERROR
            }
            0x0105 // H3_FRAME_UNEXPECTED 默认
        }
        _ => 0x0102,                             // H3_INTERNAL_ERROR
    }
}

/// 解析 H3 帧并喂入 Http3Connection，返回所有 FrameAction
fn parse_and_feed_h3_frames(
    h3_conn: &mut Http3Connection,
    stream_id: u64,
    data: &[u8],
    partial_buf: &mut Vec<u8>,
) -> Result<Vec<FrameAction>, Http3Error> {
    // RFC 9114 §7.1: H3 帧可跨多个 QUIC STREAM 帧，需按流重组。
    // 将新数据追加到分帧缓冲，从缓冲头部解析完整帧，未解析的尾部留在缓冲中。
    partial_buf.extend_from_slice(data);
    let mut actions = Vec::new();
    let mut consumed_total = 0usize;
    while consumed_total < partial_buf.len() {
        match Frame::parse(&partial_buf[consumed_total..]) {
            // RFC 9114 §9：未知帧已按 length 跳过，计入消费字节继续
            Ok((consumed, None)) => {
                consumed_total += consumed;
                continue;
            }
            Ok((consumed, Some(frame))) => {
                consumed_total += consumed;
                match h3_conn.on_frame(stream_id, frame) {
                    Ok(action) => actions.push(action),
                    Err(Http3Error::FrameTooShort) => break,
                    Err(e) => return Err(e),
                }
            }
            Err(Http3Error::FrameTooShort) => break,
            Err(e) => return Err(e),
        }
    }
    // 移除已消费的字节，保留未解析的尾部
    if consumed_total > 0 {
        partial_buf.drain(..consumed_total);
    }
    Ok(actions)
}

// ---------------------------------------------------------------------------
// QUIC 连接封装（桥接层：NetQuicConn + Http3Connection + 流累积）
// ---------------------------------------------------------------------------

/// 连接迁移路径验证状态（RFC 9000 §9）
///
/// 当检测到客户端从新地址发来 1-RTT 包时，服务器发起 PATH_CHALLENGE 验证新路径，
/// 并在验证通过前施加防放大限制（发送 ≤ 3 × 接收，RFC 9000 §8.1）。
#[derive(Debug)]
struct MigrationState {
    /// 待验证的新地址
    new_addr: SocketAddr,
    /// 已发送的 PATH_CHALLENGE 8 字节探测数据
    challenge: [u8; 8],
    /// 从新地址累计接收的字节数（防放大分母）
    bytes_received: u64,
    /// 验证通过前向新地址累计发送的字节数
    bytes_sent: u64,
    /// 路径是否已通过 PATH_RESPONSE 验证
    validated: bool,
}

/// 桥接层的单连接状态
struct QuicConn {
    /// 客户端地址
    client_addr: SocketAddr,
    /// zenith-net QUIC 连接
    net_conn: NetQuicConn,
    /// HTTP/3 连接
    h3_conn: Http3Connection,
    /// 活动流映射：stream_id → 累积的请求状态
    active_streams: FxHashMap<u64, PendingH3Stream>,
    /// 服务端待发送的 SETTINGS ACK 控制帧
    pending_control_out: Vec<u8>,
    /// TLS 指纹（JA3/JA4，由 set_fingerprint 在 ClientHello 解析后填充）
    fingerprint: Option<Ja3Fingerprint>,
    /// H3 帧跨 STREAM 重组缓冲：stream_id → 未解析完的尾部字节
    /// RFC 9114 §7.1: H3 帧可跨多个 QUIC STREAM 帧，必须按流重组
    partial_frame_buf: FxHashMap<u64, Vec<u8>>,
    /// 单向流类型缓存：stream_id → H3 流类型（首个切片确定，续传切片复用）
    ///
    /// 关键修复：HTTP/3 单向流类型前缀（0x00/0x02/0x03）只出现在流的
    /// offset=0 首个切片。续传切片（offset>0）必须以缓存类型识别，不能
    /// 用切片首字节重新分类——否则 QPACK 编码器流续传数据（首字节是可执行
    /// 指令而非前缀）被误判为 `Unknown` 丢弃，导致依赖动态表条目的 HEADERS
    /// 永久阻塞（`HeadersBlocked` 永不解除），HTTP/3 POST 挂起无响应。
    stream_kinds: FxHashMap<u64, H3StreamKind>,
    /// 连接迁移路径验证状态（None = 无迁移/已验证）
    migration: Option<MigrationState>,
    /// RFC 9218 §7.1：PRIORITY_UPDATE 先于 HEADERS 到达时的优先级暂存
    /// （stream_id → priority；HeadersReceived 时取出合并，hint 优先于头部值）
    priority_hints: FxHashMap<u64, StreamPriority>,
    /// 已发送响应缓存（stream_id → 响应 QUIC 包），RFC 9002 被动重发：
    /// 对端重传请求（STREAM 纯重传）= 对端未收到响应 → 重发缓存响应包。
    /// 连接关闭时随 QuicConn 释放（无跨连接泄漏）。
    response_cache: FxHashMap<u64, Vec<u8>>,
    /// 服务端单向流 ID 分配器（控制流/QPACK 编码器流/QPACK 解码器流）
    uni_ids: ServerUniStreamIds,
}

/// 服务端单向流 ID 分配器（RFC 9000 §2.1：server uni stream 3, 7, 11, …）
///
/// 控制流/QPACK 编码器流/QPACK 解码器流按 RFC 9114 §6.2.1 / RFC 9204 §4.2
/// 的协议惯例**固定分配**：控制流 = 3（第一个 server uni stream）、QPACK 编码器
/// 流 = 7、QPACK 解码器流 = 11。流类型由前缀（0x00/0x02/0x03）标识，但流 ID 必须
/// 符合惯例，否则对端（nghttp3/ngtcp2）在建立 QPACK 上下文时无法识别。
///
/// ❗ 不得改为"按首次调用顺序惰性分配"：若 QPACK 指令在握手完成前被处理，
/// 惰性分配会让 QPACK 编码器流占用 stream 3、把控制流挤到 stream 11，
/// 导致对端误判控制流缺失 → INTERNAL_ERROR（GET 因响应即时返回而侥幸成功，
/// POST 需解码响应字段区时必然失败）。
#[derive(Debug)]
struct ServerUniStreamIds {
    /// 本端控制流 ID（固定 3）
    control: Option<u64>,
    /// 本端 QPACK 编码器指令流 ID（前缀 0x02 由载荷携带；固定 7）
    qpack_encoder: Option<u64>,
    /// 本端 QPACK 解码器反馈流 ID（前缀 0x03 由载荷携带；固定 11）
    qpack_decoder: Option<u64>,
}

impl ServerUniStreamIds {
    /// 初始分配器：三项均未使用
    #[inline]
    fn new() -> Self {
        Self { control: None, qpack_encoder: None, qpack_decoder: None }
    }

    /// 本端控制流 ID（固定 3，RFC 9114 §6.2.1 首 server uni stream）
    #[inline]
    fn control(&mut self) -> Option<u64> {
        Some(*self.control.get_or_insert(3))
    }

    /// 本端 QPACK 编码器指令流 ID（固定 7，RFC 9204 §4.2）
    #[inline]
    fn qpack_encoder(&mut self) -> Option<u64> {
        Some(*self.qpack_encoder.get_or_insert(7))
    }

    /// 本端 QPACK 解码器反馈流 ID（固定 11，RFC 9204 §4.2）
    #[inline]
    fn qpack_decoder(&mut self) -> Option<u64> {
        Some(*self.qpack_decoder.get_or_insert(11))
    }
}

impl std::fmt::Debug for QuicConn {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("QuicConn")
            .field("client_addr", &self.client_addr)
            .field("net_state", &self.net_conn.state)
            .field("h3_state", &self.h3_conn.state())
            .field("active_streams", &self.active_streams.len())
            .field("handshake_done", &self.net_conn.is_handshake_done())
            .finish()
    }
}

impl QuicConn {
    /// 创建新的桥接连接
    fn new(client_addr: SocketAddr, net_conn: NetQuicConn) -> Self {
        let mut h3_conn = Http3Connection::new(Http3ConnectionConfig::default());
        h3_conn.init();
        Self {
            client_addr,
            net_conn,
            h3_conn,
            active_streams: FxHashMap::default(),
            pending_control_out: Vec::new(),
            fingerprint: None,
            partial_frame_buf: FxHashMap::default(),
            stream_kinds: FxHashMap::default(),
            migration: None,
            priority_hints: FxHashMap::default(),
            response_cache: FxHashMap::default(),
            uni_ids: ServerUniStreamIds::new(),
        }
    }

    /// 设置连接指纹（在 QUIC Initial 的 CRYPTO 帧含 ClientHello 解析后调用）
    pub fn set_fingerprint(&mut self, fp: Ja3Fingerprint) {
        self.fingerprint = Some(fp);
    }

    /// 本端控制流 ID（惰性分配并缓存，生命周期内唯一，RFC 9114 §6.2.1）
    #[inline]
    fn control_stream_id(&mut self) -> Option<u64> {
        self.uni_ids.control()
    }

    /// 本端 QPACK 编码器指令流 ID（惰性分配并缓存，RFC 9204 §4.2）
    #[inline]
    fn qpack_encoder_stream_id(&mut self) -> Option<u64> {
        self.uni_ids.qpack_encoder()
    }

    /// 本端 QPACK 解码器反馈流 ID（惰性分配并缓存，RFC 9204 §4.2）
    #[inline]
    fn qpack_decoder_stream_id(&mut self) -> Option<u64> {
        self.uni_ids.qpack_decoder()
    }

    /// 请求完成检查与处理（HEADERS + (DATA 或 FIN) 收齐后交给 App Handler）
    ///
    /// 供请求流（`H3StreamKind::Request`）与 QPACK 编码器流解除阻塞后复用同一
    /// 处理通路，避免重复实现 normalize/SNI 一致性/0-RTT 防重放/回调/响应发送。
    /// 返回 true 表示该流已完成处理（已被移除），外层应 `continue` 跳过该流。
    fn try_complete_request<F>(
        &mut self,
        stream_id: u64,
        app_handler: &F,
        scheduled: &mut Vec<((u8, bool), u64, Vec<u8>)>,
    ) -> bool
    where
        F: Fn(CanonicalRequest, Option<&Ja3Fingerprint>) -> CanonicalResponse,
    {
        let Some(pending) = self.active_streams.get(&stream_id) else {
            return false;
        };
        tracing::debug!(
            "[H3 PROC] stream_id={} headers_complete={} body_len={} fin_received={}",
            stream_id, pending.headers_complete, pending.body.len(), pending.fin_received
        );
        if !(pending.headers_complete && (!pending.body.is_empty() || pending.fin_received)) {
            return false;
        }
        let is_early_req = pending.is_early;
        let pri_key = pending.priority.schedule_key();

        // 严格 normalize（RFC 9114 §4.3），与 H1/H2 生产路径同一严格等级
        let mut canonical_req = match crate::normalize::normalize_http3_request(
            &pending.headers,
            Transport::Tls13,
        ) {
            Ok(r) => r,
            Err(e) => {
                tracing::warn!(
                    "[H3 NORM] stream_id={} normalize rejected: {}",
                    stream_id, e
                );
                let resp = error_response(400, "bad request", "normalize_failed");
                send_h3_response(self, stream_id, &resp, pri_key, scheduled);
                self.active_streams.remove(&stream_id);
                return true;
            }
        };
        canonical_req.set_body(pending.body.clone());

        // §4.5 四元一致性：SNI 与 :authority 必须一致（都存在时）→ 421。
        // IPv6 感知：authority 可能形如 `[::1]:8443`，委托 split_host_port +
        // unbracket_ipv6 统一同形化（与 server.rs H1/H2 路径同一实现源）。
        let sni_mismatch = match self.net_conn.sni() {
            Some(sni_host) => {
                let auth = canonical_req.authority_str();
                if auth.is_empty() {
                    false
                } else {
                    let (auth_no_port_raw, _) = normalize::split_host_port(auth);
                    let auth_no_port = normalize::unbracket_ipv6(auth_no_port_raw);
                    if sni_host != auth && sni_host != auth_no_port {
                        tracing::warn!(
                            "[H3 SNI] stream_id={} sni={} authority={} mismatch → 421",
                            stream_id, sni_host, auth
                        );
                        true
                    } else {
                        false
                    }
                }
            }
            None => false,
        };
        if sni_mismatch {
            let resp = error_response(421, "misdirected request", "sni_host_mismatch");
            send_h3_response(self, stream_id, &resp, pri_key, scheduled);
            self.active_streams.remove(&stream_id);
            return true;
        }

        // RFC 8446 §8.1 防重放：0-RTT 仅允许安全方法
        if is_early_req
            && !matches!(
                canonical_req.method.as_str(),
                "GET" | "HEAD" | "OPTIONS" | "TRACE"
            )
        {
            tracing::warn!(
                "[H3 EARLY] stream_id={} non-safe method {:?} rejected (0-RTT anti-replay)",
                stream_id, canonical_req.method
            );
            self.active_streams.remove(&stream_id);
            return true;
        }

        tracing::debug!(
            "[H3 RESP] stream_id={} method={} path={} → building response",
            stream_id, canonical_req.method.as_str(), canonical_req.path_str()
        );
        let resp = app_handler(canonical_req, self.fingerprint.as_ref());
        tracing::debug!(
            "[H3 RESP] stream_id={} status={} body_len={}",
            stream_id, resp.status_code, resp.body().len()
        );
        send_h3_response(self, stream_id, &resp, pri_key, scheduled);
        self.active_streams.remove(&stream_id);
        true
    }
}

// ---------------------------------------------------------------------------
// DCID 路由键：HMAC keyed map（防 HashDoS + 恒定时间查找）
// ---------------------------------------------------------------------------

/// DCID 路由 HMAC 密钥（进程级随机，每次启动重新生成）
///
/// DCID 完全由对端控制：攻击者可构造大量哈希碰撞的 DCID 打满 HashMap 桶
/// （经典 HashDoS）。因此路由表不以原始 DCID 作键，而以
/// `HMAC-SHA256(process_key, dcid)` 的 32 字节 tag 作键：
/// tag 分布由密钥决定，与对端输入无关，哈希质量不可被外部操纵；
/// 且 tag 定长 32 字节，键比较不再依赖可变长输入的逐字节对比。
struct DcidKey {
    key: ring::hmac::Key,
}

impl DcidKey {
    /// 生成路由密钥（32 字节 OS 随机）；熵源失败返回 None（fail-closed）
    fn try_new() -> Option<Self> {
        let mut key_bytes = [0u8; 32];
        if !zenith_foundation::random::try_fill_random(&mut key_bytes) {
            return None;
        }
        Some(Self {
            key: ring::hmac::Key::new(ring::hmac::HMAC_SHA256, &key_bytes),
        })
    }

    /// 计算 DCID 的路由 tag
    #[inline]
    fn tag(&self, dcid: &[u8]) -> [u8; 32] {
        let t = ring::hmac::sign(&self.key, dcid);
        let mut out = [0u8; 32];
        // HMAC-SHA256 输出恒定 32 字节（ring 类型级保证），
        // copy_from_slice 长度必然匹配，无需 unwrap/expect（禁 panic）
        out.copy_from_slice(t.as_ref());
        out
    }
}

// ---------------------------------------------------------------------------
// 桥接层核心：QuicTransportServer
// ---------------------------------------------------------------------------

/// QUIC 传输服务器（zenith-net QUIC ↔ zenith-http3 桥接层）
///
/// 负责：
/// 1. UDP socket 管理
/// 2. QUIC 连接路由（基于 DCID 匹配，路由键为 DCID 的 HMAC tag，防 HashDoS）
/// 3. QUIC → H3：`net_conn.take_stream_data()` → H3 帧解析 → FrameAction
/// 4. H3 → QUIC：FrameAction → App Handler → `send_response()` → `net_conn.build_stream_packet()`
pub struct QuicTransportServer {
    /// 配置
    config: QuicServerConfig,
    /// rustls ServerConfig（QUIC/TLS 握手使用）
    rustls_config: Option<Arc<zenith_tls::ServerConfig>>,
    /// zenith-net QUIC 服务器（UDP socket 持有者）
    net_server: Option<NetQuicServer>,
    /// 活动连接：路由 tag(client DCID) → 桥接连接（tag = HMAC-SHA256，见 DcidKey）
    connections: FxHashMap<[u8; 32], QuicConn>,
    /// 路由 tag(server DCID) → 路由 tag(client DCID) 反向映射（短包头反查原连接）
    server_dcid_index: FxHashMap<[u8; 32], [u8; 32]>,
    /// DCID 路由密钥；构造期熵源失败为 None（全路由流程 fail-closed 丢包）
    dcid_key: Option<DcidKey>,
    /// 待重处理的握手期间缓存的 1-RTT 包
    pub pending_1rtt: Vec<(Vec<u8>, SocketAddr)>,
    /// 最近提取的 TLS 指纹
    last_fingerprint: Option<Ja3Fingerprint>,
}

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

impl QuicTransportServer {
    /// 创建新的 QUIC 传输服务器
    pub fn new(config: QuicServerConfig) -> Self {
        let dcid_key = match DcidKey::try_new() {
            Some(k) => Some(k),
            None => {
                tracing::error!(
                    "DCID 路由密钥生成失败（OS 熵源不可用）：连接路由 fail-closed，所有包将被丢弃"
                );
                None
            }
        };
        Self {
            config,
            rustls_config: None,
            net_server: None,
            connections: FxHashMap::default(),
            server_dcid_index: FxHashMap::default(),
            dcid_key,
            pending_1rtt: Vec::new(),
            last_fingerprint: None,
        }
    }

    /// 绑定证书（将 CertGeneration 转换为 rustls ServerConfig）
    pub fn bind_cert(&mut self, cert_gen: &CertGeneration) -> Result<(), QuicTransportError> {
        let rustls_config = cert_gen
            .to_server_config(vec![b"h3".to_vec()])
            .map_err(QuicTransportError::Cert)?;
        self.rustls_config = Some(rustls_config);
        Ok(())
    }

    /// 开始监听（创建 UDP socket）
    pub fn bind(&mut self) -> Result<(), QuicTransportError> {
        let rustls_config = self
            .rustls_config
            .clone()
            .ok_or_else(|| QuicTransportError::Quic("no rustls config — call bind_cert first".into()))?;

        let net_config = NetQuicConfig::new(
            self.config.bind_addr,
            rustls_config,
            self.config.version,
        )?;
        let net_server = NetQuicServer::bind(net_config)?;
        self.net_server = Some(net_server);
        Ok(())
    }

    /// 获取本地监听地址
    pub fn local_addr(&self) -> Option<SocketAddr> {
        self.net_server.as_ref().and_then(|s| {
            s.socket().local_addr().ok()
        })
    }

    /// 是否为无内核 socket 模式（socketless：AF_XDP 数据面专用）
    ///
    /// `bind_quic_socketless` 初始化的实例 `net_server` 为 `None`，
    /// 数据报经 AF_XDP 桥直接喂入，不触碰内核 UDP socket（铁则 1 合规）。
    #[inline]
    pub fn is_socketless(&self) -> bool {
        self.net_server.is_none()
    }

    /// 获取活动连接数
    pub fn active_connections(&self) -> usize {
        self.connections.len()
    }

    /// 获取最近的 TLS 指纹（消费）
    pub fn take_last_fingerprint(&mut self) -> Option<Ja3Fingerprint> {
        self.last_fingerprint.take()
    }

    /// 获取 UDP socket 引用
    pub fn socket(&self) -> Option<&UdpSocket> {
        self.net_server.as_ref().map(|s| s.socket())
    }

    // -------------------------------------------------------------------
    // 内部：连接路由与创建
    // -------------------------------------------------------------------

    /// 从 Long Header 提取 DCID 用于路由（借用切片，热路径零堆分配）
    fn extract_long_dcid(packet: &[u8]) -> Option<&[u8]> {
        if packet.len() < 6 {
            return None;
        }
        // first byte (0) | version (1..4) | dcid_len (5) | dcid (6..6+len)
        let dcid_len = packet[5] as usize;
        if dcid_len > 20 || 6 + dcid_len > packet.len() {
            return None;
        }
        Some(&packet[6..6 + dcid_len])
    }

    /// 从 Short Header 提取 DCID 用于路由（借用切片，热路径零堆分配）
    fn extract_short_dcid(packet: &[u8], dcid_len: usize) -> Option<&[u8]> {
        if packet.len() < 1 + dcid_len {
            return None;
        }
        Some(&packet[1..1 + dcid_len])
    }

    /// 计算 DCID 的路由 tag；dcid_key 缺失（构造期熵源失败）→ None（fail-closed）
    #[inline]
    fn dcid_tag(&self, dcid: &[u8]) -> Option<[u8; 32]> {
        self.dcid_key.as_ref().map(|k| k.tag(dcid))
    }

    /// 根据客户端地址匹配已有连接（fallback），返回其路由 tag
    fn find_conn_by_addr(&self, from: SocketAddr) -> Option<[u8; 32]> {
        self.connections
            .iter()
            .find(|(_, c)| c.client_addr == from)
            .map(|(k, _)| *k)
    }

    // -------------------------------------------------------------------
    // 内部：处理已建立连接的流数据（QUIC → H3 → App → H3 → QUIC）
    // -------------------------------------------------------------------

    /// 处理连接上的所有已接收流数据，完成 H3 帧解析 → App Handler → 响应编码
    fn process_streams<F>(
        &mut self,
        route_tag: &[u8; 32],
        app_handler: &F,
    ) -> QuicResponsePackets
    where
        F: Fn(CanonicalRequest, Option<&Ja3Fingerprint>) -> CanonicalResponse,
    {
        let mut response_packets = Vec::new();
        // RFC 9218 §10 优先级调度收集器：(schedule_key, stream_id, packet)
        // 本轮完成的响应不立即发出，按 urgency 排序后统一 flush
        let mut scheduled: Vec<((u8, bool), u64, Vec<u8>)> = Vec::new();

        // 获取目标连接（键为路由 tag）
        let conn = match self.connections.get_mut(route_tag) {
            Some(c) => c,
            None => return response_packets,
        };

        // 0. 握手确认后（HANDSHAKE_DONE 已发）才发送服务端控制流 + SETTINGS（RFC 9114 §6.5）
        //    RFC 9000 §10.3: 服务器必须在握手确认后才能发送应用数据（1-RTT）。
        //    is_handshake_done() 仅表示 1-RTT keys 可用（服务端 Finished 已生成），
        //    并不代表握手完成；必须用 handshake_done_sent（收到客户端 Finished 并已发 HANDSHAKE_DONE）。
        //    控制流 = 服务端第一个单向流 (stream_id = 3)
        //    数据 = [0x00 流类型前缀] + [SETTINGS 帧]
        let hs_done = conn.net_conn.handshake_done_sent;
        tracing::debug!("[H3 CTRL] check: handshake_done_sent={} h3_state={:?}", hs_done, conn.h3_conn.state());
        if hs_done {
            match conn.h3_conn.take_server_control_stream_init() {
                Ok(Some(ctrl_init)) => {
                    tracing::debug!("[H3 CTRL] ctrl_init len={} bytes={:02x?}", ctrl_init.len(), &ctrl_init[..ctrl_init.len().min(16)]);
                    // 控制流 ID 经分配器真实分配（首次调用 → 3，协议惯例首 server uni），
                    // 并缓存于连接生命周期内复用（与第 4 步 SETTINGS ACK 同一控制流）
                    let control_sid = conn.control_stream_id();
                    let build_result = match control_sid {
                        Some(sid) => conn.net_conn.build_stream_packet(sid, 0, false, &ctrl_init),
                        None => {
                            tracing::error!("[H3 CTRL] server uni stream id space exhausted (fail-closed)");
                            return response_packets;
                        }
                    };
                    match build_result {
                        Ok(pkt) => {
                            tracing::debug!(
                                "[H3 CTRL] sent control stream init (SETTINGS) on stream_id=3, {}B",
                                pkt.len()
                            );
                            response_packets.push((pkt, conn.client_addr));
                        }
                        Err(e) => {
                            tracing::debug!("[H3 CTRL] failed to send control stream init: {}", e);
                        }
                    }
                }
                Ok(None) => {
                    tracing::debug!("[H3 CTRL] Ok(None) - settings already sent");
                }
                Err(e) => {
                    tracing::debug!("[H3 CTRL] take_server_control_stream_init error: {}", e);
                }
            }
        }

        // 1. 从 NetQuicConn 取出所有已接收流数据（含 0-RTT 早期数据）
        // 0-RTT 早期流（RFC 9001 §5.7）与 1-RTT 流合并处理，
        // is_early 标记供后续安全方法门控（RFC 8446 §8.1 防重放）。
        let mut stream_ids: Vec<u64> = conn.net_conn.stream_rx.keys().copied().collect();
        let early_ids: Vec<u64> = conn.net_conn.early_stream_rx.keys().copied().collect();
        stream_ids.extend(early_ids.iter().copied());
        // RFC 9114 §6.2.1: 控制流（mod 4=2, client uni）优先于请求流（mod 4=0）
        stream_ids.sort_by_key(|sid| if sid % 4 == 2 { 0 } else { 1 });
        for stream_id in stream_ids {
            // 0-RTT 与 1-RTT 流严格分派（同一流 ID 不会同时存在于两个 map：
            // 0-RTT 在握手完成前到达，1-RTT 重发使用新流 ID）
            let is_early = conn.net_conn.early_stream_rx.contains_key(&stream_id);
            let (data_opt, fin_received) = if is_early {
                (
                    conn.net_conn.take_early_stream_data(stream_id),
                    conn.net_conn.take_early_stream_fin(stream_id),
                )
            } else {
                (
                    conn.net_conn.take_stream_data(stream_id),
                    conn.net_conn.take_stream_fin(stream_id),
                )
            };
            let stream_data = match data_opt {
                Some(d) if !d.is_empty() => d,
                _ => {
                    // RFC 9002 被动重发：本流收到纯重传数据（对端未收到响应）
                    // 且响应已缓存 → 重发响应包（相同包号，对端去重后处理）
                    if conn.net_conn.dup_stream_sids.contains(&stream_id)
                        && let Some(cached) = conn.response_cache.get(&stream_id)
                    {
                        tracing::debug!(
                            "[H3 RETRANS] stream_id={} retransmit cached response {}B",
                            stream_id, cached.len()
                        );
                        response_packets.push((cached.clone(), conn.client_addr));
                    }
                    // 即使没有数据，也可能有 FIN 需要处理
                    if fin_received {
                        // 对端 FIN 但无数据缓冲：可能是空流，触发请求完成检查
                        if let Some(pending) = conn.active_streams.get_mut(&stream_id) {
                            pending.fin_received = true;
                            pending.is_early = is_early;
                        }
                    }
                    continue;
                }
            };

            // 2. 判定 H3 流类型（首个切片分类并缓存，续传切片复用缓存）
            //    单向流类型前缀仅存在于 offset=0 首个切片；续传切片（offset>0）
            //    必须以缓存类型识别，不能以切片首字节重新分类（否则 QPACK 编码器
            //    流续传指令被误判 Unknown 丢弃 → 依赖动态表的 HEADERS 永久阻塞）。
            let is_first_slice = !conn.stream_kinds.contains_key(&stream_id);
            let kind = if is_first_slice {
                let k = classify_stream(stream_id, &stream_data);
                if k != H3StreamKind::Unknown {
                    conn.stream_kinds.insert(stream_id, k);
                }
                k
            } else {
                conn.stream_kinds
                    .get(&stream_id)
                    .copied()
                    .unwrap_or(H3StreamKind::Unknown)
            };
            tracing::debug!(
                "[H3 PROC] stream_id={} kind={:?} data_len={} fin={} first_bytes={:02x?}",
                stream_id, kind, stream_data.len(), fin_received,
                &stream_data[..8.min(stream_data.len())]
            );

            match kind {
                H3StreamKind::Request => {
                    // 请求流：解析 H3 帧
                    let partial = conn
                        .partial_frame_buf
                        .entry(stream_id)
                        .or_default();
                    let actions = match parse_and_feed_h3_frames(
                        &mut conn.h3_conn,
                        stream_id,
                        &stream_data,
                        partial,
                    ) {
                        Ok(a) => a,
                        Err(e) => {
                            let err_code = if e.to_string().contains("connection closed")
                                && conn.h3_conn.last_close_error_code != 0
                            {
                                conn.h3_conn.last_close_error_code
                            } else {
                                let code = h3_error_code(&e);
                                if conn.h3_conn.last_close_error_code == 0 {
                                    conn.h3_conn.last_close_error_code = code;
                                }
                                code
                            };
                            tracing::warn!(
                                "[H3 PROC] stream_id={} parse error -> CONNECTION_CLOSE: {} (code=0x{:04x})",
                                stream_id, e, err_code
                            );
                            let cc_frame = build_connection_close_app(
                                err_code,
                                "h3 frame parse error",
                            );
                            match conn.net_conn.build_1rtt_packet(&cc_frame) {
                                Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                                Err(be) => {
                                    tracing::warn!(
                                        "[H3 PROC] build_1rtt_packet FAILED: {}, trying Initial/Handshake fallback",
                                        be
                                    );
                                    // 1-RTT keys 不可用（握手未完成）时，
                                    // 回退用 Initial/Handshake keys 发 CONNECTION_CLOSE（RFC 9000 §10.2/§10.3）
                                    if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                    if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                }
                            }
                            // 不设 H3 state=Closed：h3spec 可能复用同一 QUIC 连接
                            // 后续测试的请求需被处理并返回各自正确的 H3 错误码
                            return response_packets;
                        }
                    };
                    tracing::debug!("[H3 PROC] stream_id={} actions_count={}", stream_id, actions.len());

                    for action in actions {
                        tracing::debug!("[H3 PROC] stream_id={} action={:?}", stream_id, action);
                        match action {
                            FrameAction::HeadersReceived { headers, .. } => {
                                // 存储头部，等待 DATA 完成
                                let pending = conn.active_streams.entry(stream_id).or_default();
                                pending.headers_complete = true;
                                // RFC 9218：Priority 头部字段解析；
                                // PRIORITY_UPDATE hint 优先于头部值（§7.1 更新语义）
                                let header_pri = headers
                                    .iter()
                                    .find(|(n, _)| n.eq_ignore_ascii_case(b"priority"))
                                    .map(|(_, v)| zenith_http3::parse_priority_field(v));
                                pending.priority = conn
                                    .priority_hints
                                    .remove(&stream_id)
                                    .or(header_pri)
                                    .unwrap_or_default();
                                pending.headers = headers;
                                pending.body = Vec::new();
                                pending.fin_received = fin_received;
                                pending.is_early = is_early;
                            }
                            FrameAction::DataReceived { stream_id: sid, data } => {
                                let pending = conn.active_streams.entry(sid).or_default();
                                pending.body.extend_from_slice(&data);
                                pending.fin_received = fin_received;
                                pending.is_early = is_early;
                            }
                            FrameAction::SettingsAck => {
                                // 对端 SETTINGS 已在本端确认（http3 层 settings_acked=true）。
                                // RFC 9114 §7.2.4：控制流只允许一个 SETTINGS 帧；本端无需也不得
                                // 回发 SETTINGS（不存在 SETTINGS ACK 帧）。此前误将此处编码为
                                // 空 SETTINGS 帧回发，导致控制流出现第二个 SETTINGS → 对端
                                // (ngtcp2/nghttp3) 判 H3_FRAME_UNEXPECTED 关闭连接（curl POST 000）。
                                tracing::debug!(
                                    "[H3 CTRL] peer SETTINGS acknowledged (no echo; RFC 9114 §7.2.4)"
                                );
                            }
                            _ => {}
                        }
                    }

                    // 3. 检查请求是否完整（HEADERS + (DATA 或 FIN)）并处理
                    // GET 请求只有 HEADERS + FIN，无 body；POST 才有 DATA。
                    if conn.try_complete_request(stream_id, app_handler, &mut scheduled) {
                        continue;
                    }
                }
                H3StreamKind::Control => {
                    // RFC 9114 §6.2.1: 控制流关闭 → H3_CLOSED_CRITICAL_STREAM
                    // 但如果 settings_acked=false 且 FIN 到达 → H3_MISSING_SETTINGS
                    if fin_received {
                        // 先处理已到达的控制流数据（可能含 SETTINGS 或非 SETTINGS 帧）
                        // 必须先 accept_control_stream，确保 on_frame 能检测到
                        // is_control_unacked && frame_type != Settings → H3_MISSING_SETTINGS
                        let _ = conn.h3_conn.stream_manager_mut().accept_control_stream(stream_id);
                        // 类型前缀仅存在于首个切片；续传切片（offset>0）不含前缀，不可再剥
                        let h3_data = if is_first_slice {
                            if stream_data.len() > 1 {
                                &stream_data[1..]
                            } else {
                                &[][..]
                            }
                        } else {
                            &stream_data[..]
                        };
                        if !h3_data.is_empty() {
                            let partial = conn.partial_frame_buf.entry(stream_id).or_default();
                            if let Err(e) = parse_and_feed_h3_frames(&mut conn.h3_conn, stream_id, h3_data, partial) {
                                tracing::warn!("[H3 CTRL] stream_id={} parse error -> CONNECTION_CLOSE: {}", stream_id, e);
                                let cc_frame = build_connection_close_app(h3_error_code(&e), "control stream parse error");
                                match conn.net_conn.build_1rtt_packet(&cc_frame) {
                                    Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                                    Err(_) => {
                                        if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                            response_packets.push((pkt, conn.client_addr));
                                        }
                                        if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                            response_packets.push((pkt, conn.client_addr));
                                        }
                                    }
                                }
                                // 不设 H3 state=Closed：h3spec 可能复用同一 QUIC 连接
                                return response_packets;
                            }
                        }
                        // 检查是否 settings_acked
                        let settings_acked = conn.h3_conn.stream_manager()
                            .get(stream_id)
                            .map(|s| s.settings_acked)
                            .unwrap_or(false);
                        if !settings_acked {
                            tracing::warn!(
                                "[H3 CTRL] stream_id={} closed (FIN) before SETTINGS -> H3_MISSING_SETTINGS",
                                stream_id
                            );
                            let cc_frame = build_connection_close_app(
                                0x010A, // H3_MISSING_SETTINGS
                                "control stream closed before SETTINGS",
                            );
                            match conn.net_conn.build_1rtt_packet(&cc_frame) {
                                Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                                Err(_) => {
                                    if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                    if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                }
                            }
                            // 保持连接开放（同上：h3spec 连接复用）
                            return response_packets;
                        }
                        tracing::warn!(
                            "[H3 CTRL] stream_id={} closed (FIN) -> H3_CLOSED_CRITICAL_STREAM",
                            stream_id
                        );
                        let cc_frame = build_connection_close_app(
                            0x0104, // H3_CLOSED_CRITICAL_STREAM
                            "control stream closed",
                        );
                        match conn.net_conn.build_1rtt_packet(&cc_frame) {
                            Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                            Err(_) => {
                                if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                                if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                            }
                        }
                        // 保持连接开放（同上：h3spec 连接复用）
                        return response_packets;
                    }
                    // 控制流：先消费 type prefix，然后解析 H3 帧
                    // 类型前缀仅存在于首个切片；续传切片不含前缀，直接喂全部
                    let h3_data = if is_first_slice {
                        if stream_data.len() > 1 {
                            &stream_data[1..]
                        } else {
                            continue;
                        }
                    } else {
                        &stream_data[..]
                    };

                    // 确保控制流已注册
                    let _ = conn.h3_conn.stream_manager_mut().accept_control_stream(stream_id);

                    let partial = conn
                        .partial_frame_buf
                        .entry(stream_id)
                        .or_default();
                    let actions = match parse_and_feed_h3_frames(
                        &mut conn.h3_conn,
                        stream_id,
                        h3_data,
                        partial,
                    ) {
                        Ok(a) => a,
                        Err(e) => {
                            tracing::warn!(
                                "[H3 CTRL] stream_id={} parse error -> CONNECTION_CLOSE: {}",
                                stream_id, e
                            );
                            let cc_frame = build_connection_close_app(
                                h3_error_code(&e),
                                "control stream parse error",
                            );
                            match conn.net_conn.build_1rtt_packet(&cc_frame) {
                                Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                                Err(be) => {
                                    tracing::warn!(
                                        "[H3 CTRL] build_1rtt_packet FAILED: {}, trying Initial/Handshake fallback",
                                        be
                                    );
                                    if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                    if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                }
                            }
                            // 不调 close()：h3spec 复用同一 QUIC 连接运行多个测试，
                            // close() 会设置 state=Closed，导致后续测试返回 "connection closed"
                            // 而非特定 H3 错误码。保持连接开放让后续测试正常处理。
                            return response_packets;
                        }
                    };

                    for action in actions {
                        match action {
                            FrameAction::SettingsAck => {
                                // RFC 9114 §7.2.4：不得回发 SETTINGS（无 SETTINGS ACK 帧），
                                // 否则控制流出现第二个 SETTINGS → 对端 H3_FRAME_UNEXPECTED 关闭。
                                // 对端 SETTINGS 已由 http3 层确认，此处仅记录、不回发。
                                tracing::debug!(
                                    "[H3 PROC] peer SETTINGS acknowledged (no echo; RFC 9114 §7.2.4)"
                                );
                            }
                            FrameAction::HeadersReceived { headers, .. } => {
                                let pending = conn.active_streams.entry(stream_id).or_default();
                                pending.headers_complete = true;
                                pending.headers = headers;
                            }
                            FrameAction::DataReceived { data, .. } => {
                                let pending = conn.active_streams.entry(stream_id).or_default();
                                pending.body.extend_from_slice(&data);
                            }
                            // RFC 9218 §7.1：请求流优先级更新——流存在直接更新，
                            // 否则暂存 hint（HEADERS 未到达时生效）；
                            // 推送流更新经 guard 落入 `_` 忽略（本服务器不使用推送，§7.1 允许）
                            FrameAction::PriorityUpdate {
                                element_id,
                                priority,
                                is_push: false,
                            } => {
                                match conn.active_streams.get_mut(&element_id) {
                                    Some(pending) => pending.priority = priority,
                                    None => {
                                        conn.priority_hints.insert(element_id, priority);
                                    }
                                }
                                tracing::debug!(
                                    "[H3 PRI] stream_id={} urgency={} incremental={}",
                                    element_id, priority.urgency, priority.incremental
                                );
                            }
                            _ => {}
                        }
                    }
                }
                H3StreamKind::QpackEncoder => {
                    // QPACK 编码器流：直接喂入解码器
                    // 类型前缀仅存在于首个切片；续传切片不含前缀，直接喂全部
                    let h3_data = if is_first_slice {
                        if stream_data.len() > 1 {
                            &stream_data[1..]
                        } else {
                            continue;
                        }
                    } else {
                        &stream_data[..]
                    };
                    // HTTP-028：对端 QPACK 编码器流建立（首切片）时跟踪，至多一条
                    if is_first_slice
                        && let Err(e) = conn.h3_conn.note_peer_qpack_stream(stream_id, true)
                    {
                        tracing::warn!("duplicate qpack encoder stream -> CONNECTION_CLOSE: {}", e);
                        let cc_frame = build_connection_close_app(
                            h3_error_code(&e),
                            "qpack encoder stream error",
                        );
                        match conn.net_conn.build_1rtt_packet(&cc_frame) {
                            Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                            Err(_) => {
                                if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                                if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                            }
                        }
                        return response_packets;
                    }
                    let actions = match conn.h3_conn.on_qpack_encoder_stream(h3_data) {
                        Ok(a) => a,
                        Err(e) => {
                            // RFC 9114 §7.2 / QPACK §4：QPACK 编码器流协议错误 →
                            // 发送 QUIC APPLICATION_CLOSE 帧 + 终止连接。
                            tracing::warn!("qpack encoder stream error -> CONNECTION_CLOSE: {}", e);
                            let cc_frame = build_connection_close_app(
                                h3_error_code(&e),
                                "qpack encoder stream error",
                            );
                            match conn.net_conn.build_1rtt_packet(&cc_frame) {
                                Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                                Err(_) => {
                                    if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                    if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                        response_packets.push((pkt, conn.client_addr));
                                    }
                                }
                            }
                            // 保持连接开放（h3spec 连接复用）
                            return response_packets;
                        }
                    };
                    // 处理编码器流解除阻塞的请求流 HEADERS（RFC 9204 §4.4）：
                    // 此前被 `HeadersBlocked` 暂存的请求流，一旦动态表条目就绪会在此
                    // 重新解码并返回 HeadersReceived。必须据此补齐 headers 并立即尝试
                    // 完成请求（否则仅收到 HEADERS 阻塞、DATA 已先到的 POST 永不处理）。
                    for action in actions {
                        if let FrameAction::HeadersReceived {
                            stream_id: unblocked_sid,
                            headers,
                        } = action
                        {
                            let pending = conn.active_streams.entry(unblocked_sid).or_default();
                            pending.headers_complete = true;
                            pending.headers = headers;
                            if conn.try_complete_request(unblocked_sid, app_handler, &mut scheduled) {
                                tracing::debug!(
                                    "[H3 QPACK] stream_id={} headers unblocked → request completed",
                                    unblocked_sid
                                );
                            }
                        }
                    }
                }
                H3StreamKind::QpackDecoder => {
                    // QPACK 解码器流
                    // 类型前缀仅存在于首个切片；续传切片不含前缀，直接喂全部
                    let h3_data = if is_first_slice {
                        if stream_data.len() > 1 {
                            &stream_data[1..]
                        } else {
                            continue;
                        }
                    } else {
                        &stream_data[..]
                    };
                    // HTTP-028：对端 QPACK 解码器流建立（首切片）时跟踪，至多一条
                    if is_first_slice
                        && let Err(e) = conn.h3_conn.note_peer_qpack_stream(stream_id, false)
                    {
                        tracing::warn!("duplicate qpack decoder stream -> CONNECTION_CLOSE: {}", e);
                        let cc_frame = build_connection_close_app(
                            h3_error_code(&e),
                            "qpack decoder stream error",
                        );
                        match conn.net_conn.build_1rtt_packet(&cc_frame) {
                            Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                            Err(_) => {
                                if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                                if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                            }
                        }
                        return response_packets;
                    }
                    if let Err(e) = conn.h3_conn.on_qpack_decoder_stream(h3_data) {
                        // RFC 9114 §7.2 / QPACK §4：QPACK 解码器流协议错误 →
                        // 发送 QUIC APPLICATION_CLOSE 帧 + 终止连接。
                        tracing::warn!("qpack decoder stream error -> CONNECTION_CLOSE: {}", e);
                        let cc_frame = build_connection_close_app(
                            h3_error_code(&e),
                            "qpack decoder stream error",
                        );
                        match conn.net_conn.build_1rtt_packet(&cc_frame) {
                            Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                            Err(_) => {
                                if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                                if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                    response_packets.push((pkt, conn.client_addr));
                                }
                            }
                        }
                        // 保持连接开放（h3spec 连接复用）
                        return response_packets;
                    }
                }
                H3StreamKind::Unknown => {
                    // 忽略未知流
                }
            }
        }

        // 3.5 RFC 9218 §10 优先级调度 flush：urgency 升序（0 最优先），
        // 同 urgency 非 incremental 先；稳定排序保持同键到达顺序
        if !scheduled.is_empty() {
            scheduled.sort_by_key(|(key, _, _)| *key);
            let addr = conn.client_addr;
            for (_, _, pkt) in scheduled.drain(..) {
                response_packets.push((pkt, addr));
            }
        }

        // 4. 发送控制帧（SETTINGS ACK 等）
        if !conn.pending_control_out.is_empty() {
            let data = conn.pending_control_out.clone();
            conn.pending_control_out.clear();
            // 与控制流 init 同一条已分配/缓存的控制流（RFC 9114 §6.1：控制流在
            // 连接生命周期内保持打开，绝不能发 FIN；ID 不再硬编码 3）
            match conn.control_stream_id() {
                Some(sid) => match conn.net_conn.build_stream_packet(sid, 0, false, &data) {
                    Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                    Err(e) => tracing::warn!("control stream build error: {}", e),
                },
                None => tracing::error!("control stream id exhausted (fail-closed, frame dropped)"),
            }
        }

        // 5. 发送 QPACK 指令（QPACK 流同样不能发 FIN，需保持打开；
        // 流 ID 经分配器惰性分配并缓存，替代硬编码 7/11）
        //
        // ❗ 必须受握手完成门控：RFC 9000 §10.3 要求 1-RTT 应用数据只能在握手
        // 确认后发送。若在 `handshake_done_sent=false` 时消费 QPACK 指令，
        // `build_stream_packet` 会因 1-RTT keys 未就绪而失败（"handshake not
        // complete"），但指令缓冲已被取走且 `qpack_encoder_stream_started` 已置位，
        // 导致 QPACK 编码器/解码器流从未真正建立 → 对端解码响应字段区失败
        // （POST 时 INTERNAL_ERROR）。握手未完成时不得消费指令，留待完成后再发。
        if hs_done {
            let (enc_instructions, dec_instructions) = conn.h3_conn.take_qpack_stream_instructions();
            if !enc_instructions.is_empty() {
                match conn.qpack_encoder_stream_id() {
                    Some(sid) => match conn.net_conn.build_stream_packet(sid, 0, false, &enc_instructions) {
                        Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                        Err(e) => tracing::warn!("qpack encoder instructions error: {}", e),
                    },
                    None => tracing::error!("qpack encoder stream id exhausted (fail-closed)"),
                }
            }
            if !dec_instructions.is_empty() {
                match conn.qpack_decoder_stream_id() {
                    Some(sid) => match conn.net_conn.build_stream_packet(sid, 0, false, &dec_instructions) {
                        Ok(pkt) => response_packets.push((pkt, conn.client_addr)),
                        Err(e) => tracing::warn!("qpack decoder instructions error: {}", e),
                    },
                    None => tracing::error!("qpack decoder stream id exhausted (fail-closed)"),
                }
            }
        }

        // 6. 清理已关闭的流
        conn.h3_conn.stream_manager_mut().purge_closed();

        // 7. 清空本轮重传信号（已消费）
        conn.net_conn.dup_stream_sids.clear();

        response_packets
    }

    // -------------------------------------------------------------------
    // 内部：创建新连接
    // -------------------------------------------------------------------

    fn create_connection(
        &mut self,
        client_addr: SocketAddr,
        client_scid: Vec<u8>,
        client_dcid: Vec<u8>,
        server_scid: Vec<u8>,
        rustls_config: &Arc<zenith_tls::ServerConfig>,
    ) -> Result<[u8; 32], QuicTransportError> {
        // 连接数上限检查（fail-closed：超限拒绝新连接，防连接表灌满 DoS）
        if self.connections.len() >= self.config.max_connections {
            tracing::warn!(
                "QUIC 连接数达上限 {max}，拒绝新连接 from {client_addr}",
                max = self.config.max_connections,
            );
            return Err(QuicTransportError::Quic(
                "max_connections reached, refusing new connection".into(),
            ));
        }
        let net_conn = NetQuicConn::new(
            client_addr,
            client_scid,
            client_dcid.clone(),
            server_scid,
            rustls_config.clone(),
            self.config.version,
        )?;
        let server_dcid = net_conn.server_dcid.clone();
        let bridge_conn = QuicConn::new(client_addr, net_conn);
        // 路由表键为 DCID 的 HMAC tag（防 HashDoS + 定长键恒定时间比较）
        // fail-closed：dcid_key 缺失（构造期熵源失败）直接拒绝新连接
        let client_tag = self.dcid_tag(&client_dcid).ok_or_else(|| {
            QuicTransportError::Quic("DCID 路由密钥不可用（熵源失败），拒绝新连接".into())
        })?;
        let server_tag = self.dcid_tag(&server_dcid).ok_or_else(|| {
            QuicTransportError::Quic("DCID 路由密钥不可用（熵源失败），拒绝新连接".into())
        })?;
        // 用 client_dcid 的 tag 做主键路由（客户端发来的 Initial 包 DCID = client_dcid）
        self.connections.insert(client_tag, bridge_conn);
        // 建立 server_dcid tag → client_dcid tag 反向映射（短包头用 server_dcid）
        self.server_dcid_index.insert(server_tag, client_tag);
        Ok(client_tag)
    }

    // -------------------------------------------------------------------
    // 公开 API：处理一个 UDP/QUIC 数据包
    // -------------------------------------------------------------------

    /// 处理一个 UDP/QUIC 数据包（HTTP/3 入口）
    ///
    /// # 流程
    /// 1. UDP 数据报 → 路由到已有连接或创建新连接
    /// 2. 调用 zenith-net 的 NetQuicConn 处理包（HP/AEAD/TLS 握手）
    /// 3. 取出解密后的流数据，喂入 zenith-http3 的 H3 帧解析
    /// 4. 构建 HTTP/3 请求 → App Handler → HTTP/3 响应编码
    /// 5. 通过 NetQuicConn 加密响应并返回待发送的数据报
    pub fn handle_packet<F>(
        &mut self,
        data: &[u8],
        from: SocketAddr,
        app_handler: &F,
    ) -> Result<QuicResponsePackets, QuicTransportError>
    where
        F: Fn(CanonicalRequest, Option<&Ja3Fingerprint>) -> CanonicalResponse,
    {
        if data.is_empty() {
            return Ok(Vec::new());
        }

        let is_long = (data[0] & 0x80) != 0;
        tracing::debug!("recv {}B from {} first_byte=0x{:02x} long={}", data.len(), from, data[0], is_long);

        // --- 握手路由 ---
        if is_long {
            // Long Header：尝试解析 DCID/SCID 并路由
            if let Some(dcid) = Self::extract_long_dcid(data) {
                tracing::debug!("long header dcid={:02x?} len={}", dcid, dcid.len());
                // fail-closed：路由密钥不可用（构造期熵源失败）→ 丢弃数据包
                let Some(dcid_tag) = self.dcid_tag(dcid) else {
                    tracing::error!("DCID 路由密钥不可用，丢弃 long header 数据包");
                    return Ok(Vec::new());
                };
                // 客户端在握手期间会切换 dcid（从随机 client_dcid 切到服务端 SCID），
                // 但 Initial/Handshake keys 始终基于第一个包的 dcid 派生。
                // 路由：先查 connections(主键=tag(client_dcid))；找不到再查 server_dcid_index
                // 反查 tag(client_dcid)（tag(server_scid) → tag(client_dcid)），再查 connections。
                let route_key = if self.connections.contains_key(&dcid_tag) {
                    dcid_tag
                } else if let Some(client_tag) = self.server_dcid_index.get(&dcid_tag) {
                    tracing::debug!(
                        "long header: dcid={:02x?} -> client_dcid tag matched (via server_dcid_index)",
                        dcid
                    );
                    *client_tag
                } else {
                    dcid_tag
                };
                if self.connections.contains_key(&route_key) {
                    tracing::debug!("existing connection found");
                    // 已有连接 — 处理可能 coalesced 的多个包（RFC 9000 §12.2）
                    // 客户端常将 Initial(ACK) + Handshake(Finished) + 1-RTT(data) 合并到一个 UDP 数据报
                    let first_end = zenith_net::transport::quic_server::parse_long_header_full(data)
                        .map(|p| p.pn_offset + p.length as usize)
                        .unwrap_or(data.len());

                    let Some(conn) = self.connections.get_mut(&route_key) else {
                        // 竞态防御：contains_key 守卫后连接被移除（理论不可达，fail-closed）
                        return Ok(Vec::new());
                    };
                    let client_addr = conn.client_addr;
                    let output = match data[0] & 0x30 {
                        0x00 => {
                            // Initial
                            match conn.net_conn.handle_initial_packet(data) {
                                Ok(pkts) => pkts,
                                Err(e) => {
                                    // RFC 9000 §19.19：Initial 阶段协议错误 →
                                    // 优先用 Initial keys 发 CONNECTION_CLOSE，
                                    // fallback 用 1-RTT keys（若已提取）
                                    tracing::warn!(
                                        "handle_initial_packet error -> CONNECTION_CLOSE: {}",
                                        e
                                    );
                                    let (error_code, frame_type) = quic_error_code(&e);
                                    let cc_frame = build_connection_close_transport(
                                        error_code,
                                        frame_type,
                                        "initial error",
                                    );
                                    let mut err_pkts: QuicResponsePackets = Vec::new();
                                    let i_r = conn.net_conn.build_initial_cc_packet(&cc_frame);
                                    if let Err(ref e) = i_r {
                                        tracing::warn!("[CC INITIAL] build err: {}", e);
                                    }
                                    if let Ok(pkt) = i_r {
                                        err_pkts.push((pkt, client_addr));
                                    }
                                    let h_r = conn.net_conn.build_handshake_cc_packet(&cc_frame);
                                    if let Err(ref e) = h_r {
                                        tracing::warn!("[CC HANDSHAKE] build err: {}", e);
                                    }
                                    if let Ok(pkt) = h_r {
                                        err_pkts.push((pkt, client_addr));
                                    }
                                    let r_r = conn.net_conn.build_1rtt_packet(&cc_frame);
                                    if let Err(ref e) = r_r {
                                        tracing::warn!("[CC 1RTT] build err: {}", e);
                                    }
                                    if let Ok(pkt) = r_r {
                                        err_pkts.push((pkt, client_addr));
                                    }
                                    tracing::info!("[CC TOTAL] sending {} packets to {}", err_pkts.len(), client_addr);
                                    return Ok(err_pkts);
                                }
                            }
                        }
                        0x10 => {
                            // 0-RTT（RFC 9001 §5.7）：解密失败/无 early secret 不致命，丢弃即可
                            match conn.net_conn.handle_0rtt_packet(data) {
                                Ok(pkts) => pkts,
                                Err(e) => {
                                    tracing::debug!("handle_0rtt_packet error: {}", e);
                                    Vec::new()
                                }
                            }
                        }
                        _ => {
                            // Handshake (0x20)；Retry(0x30) 不由客户端发出
                            match conn.net_conn.handle_handshake_packet(data) {
                                Ok(pkts) => pkts,
                                Err(e) => {
                                    tracing::warn!(
                                        "handle_handshake_packet error -> CONNECTION_CLOSE: {}",
                                        e
                                    );
                                    let (mut error_code, frame_type) = quic_error_code(&e);
                                    if matches!(e, NetQuicError::Crypto(_)) {
                                        let alert_code = conn.net_conn.peer_alert_code();
                                        let errmsg = e.to_string();
                                        tracing::warn!("[TLS DIAG HS] rustls error: {} (alert=0x{alert_code:x})", errmsg);
                                        let (adj, fix) = if errmsg.contains("unexpected message")
                                            || errmsg.contains("KeyUpdate")
                                            || errmsg.contains("EndOfEarlyData")
                                            || errmsg.contains("unexpected_message")
                                            || errmsg.contains("received unexpected")
                                        {
                                            (0x010A, true)
                                        } else if errmsg.contains("MissingQuicTransportParameters")
                                            || errmsg.contains("missing_extension")
                                            || errmsg.contains("MissingExtension")
                                        {
                                            (0x016D, true)
                                        } else {
                                            (alert_code, false)
                                        };
                                        error_code = if fix { adj } else { alert_code };
                                    }
                                    let cc_frame = build_connection_close_transport(
                                        error_code,
                                        frame_type,
                                        "handshake error",
                                    );
                                    let client_addr = conn.client_addr;
                                    let mut err_pkts: QuicResponsePackets = Vec::new();
                                    if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                        err_pkts.push((pkt, client_addr));
                                    }
                                    if let Ok(pkt) = conn.net_conn.build_1rtt_packet(&cc_frame) {
                                        err_pkts.push((pkt, client_addr));
                                    }
                                    return Ok(err_pkts);
                                }
                            }
                        }
                    };

                    // 绑定 QUIC ClientHello 提取的 JA3/JA4 指纹
                    //（ClientHello 的分片后续包可能在此 existing-conn 路径才完整到达）
                    if let Some(fp) = bind_pending_fingerprint(conn) {
                        self.last_fingerprint = Some(fp);
                    }

                    tracing::debug!("existing conn produced {} response packets", output.len());
                    let mut all_output: QuicResponsePackets =
                        output.into_iter().map(|p| (p, client_addr)).collect();

                    // 处理 coalesced 的后续包（Handshake Finished / 1-RTT data）
                    // RFC 9001 §4.9：服务器在处理完客户端 Finished 后必须立即发送 HANDSHAKE_DONE。
                    // 当 Handshake(完成) 与 1-RTT 请求合并在同一 UDP 数据报时，若在此继续内联
                    // 处理 1-RTT，HANDSHAKE_DONE 会被推迟到整包返回后才 flush；客户端(curl/ngtcp2)
                    // 在收到 HANDSHAKE_DONE 前写请求体(DATA) 会以 ERR_CLOSING 关闭连接
                    // （HTTP/3 POST 稳定失败）。故一旦握手完成，把数据报中剩余的 1-RTT 子包
                    // 推迟到 pending_1rtt（调用方先 flush HANDSHAKE_DONE 再重处理），
                    // 保证 HANDSHAKE_DONE 独立成包及时送达。
                    let mut hs_was_done = self
                        .connections
                        .get(&route_key)
                        .map(|c| c.net_conn.handshake_done_sent)
                        .unwrap_or(false);
                    let mut deferred_1rtt: Vec<(Vec<u8>, SocketAddr)> = Vec::new();
                    let mut off = first_end;
                    while off < data.len() {
                        let remaining = &data[off..];
                        let is_long = (remaining[0] & 0x80) != 0;
                        if is_long {
                            let pkt_end = zenith_net::transport::quic_server::parse_long_header_full(remaining)
                                .map(|p| p.pn_offset + p.length as usize)
                                .unwrap_or(remaining.len());
                            tracing::debug!("coalesced long header: {}B, pkt_end={}", remaining.len(), pkt_end);
                            let Some(conn) = self.connections.get_mut(&route_key) else {
                                break;
                            };
                            let addr = conn.client_addr;
                            let mut conn_new_fp: Option<Ja3Fingerprint> = None;
                            let out = match remaining[0] & 0x30 {
                                0x00 => {
                                    let out = conn.net_conn.handle_initial_packet(remaining)?;
                                    // 绑定 QUIC ClientHello 提取的 JA3/JA4 指纹
                                    //（coalesced/分片路径：ClientHello 可能在此包才完整到达）
                                    conn_new_fp = bind_pending_fingerprint(conn);
                                    out
                                }
                                0x10 => match conn.net_conn.handle_0rtt_packet(remaining) {
                                    Ok(pkts) => pkts,
                                    Err(e) => {
                                        tracing::debug!("coalesced 0-RTT error: {}", e);
                                        Vec::new()
                                    }
                                },
                                _ => conn.net_conn.handle_handshake_packet(remaining)?,
                            };
                            let hs_now = conn.net_conn.handshake_done_sent;
                            // conn 借用已结束，回填最近提取的指纹
                            if let Some(fp) = conn_new_fp {
                                self.last_fingerprint = Some(fp);
                            }
                            tracing::debug!("coalesced long produced {} packets", out.len());
                            all_output.extend(out.into_iter().map(|p| (p, addr)));
                            // 握手刚完成：无论剩余子包是否为 short header(1-RTT)、也不管其
                            // 是否恰为最后一个子包，一律推迟到 pending_1rtt。若 short header
                            // 正是数据报末尾（aioquic 将 1-RTT 直接合并在 Handshake 之后），
                            // 此处 `off + pkt_end < data.len()` 仍成立，必须推迟——
                            // 否则 1-RTT 密钥未就绪即进入 short 分支解密 → DecryptError。
                            if hs_now && !hs_was_done {
                                if off + pkt_end < data.len() {
                                    deferred_1rtt.push((data[off + pkt_end..].to_vec(), from));
                                }
                                break;
                            }
                            hs_was_done = hs_now;
                            off += pkt_end;
                        } else {
                            tracing::debug!("coalesced short header: {}B", remaining.len());
                            let Some(conn) = self.connections.get_mut(&route_key) else {
                                break;
                            };
                            let addr = conn.client_addr;
                            // 竞态防护（与 long 分支推迟语义一致）：aioquic 把 1-RTT 短包直接
                            // 合并在 Handshake 之后，本数据报的 Handshake 在循环外（主路径）
                            // 先处理，但短包可能在握手完成前进入本分支。若握手未完成，
                            // 1-RTT 密钥未就绪 → 解密失败/保留位误判。推迟到 pending_1rtt，
                            // 由 server.rs 先 flush HANDSHAKE_DONE 再重处理。
                            if !conn.net_conn.handshake_done_sent {
                                tracing::debug!(
                                    "coalesced short 在握手完成前到达，推迟到 pending_1rtt"
                                );
                                if self.pending_1rtt.len() >= MAX_PENDING_1RTT {
                                    self.pending_1rtt.remove(0);
                                }
                                self.pending_1rtt.push((remaining.to_vec(), from));
                                break;
                            }
                            match conn.net_conn.handle_short_packet(remaining) {
                                Ok(out) => {
                                    tracing::debug!("coalesced short produced {} packets", out.len());
                                    all_output.extend(out.into_iter().map(|p| (p, addr)));
                                }
                                Err(e) => tracing::debug!("coalesced short error: {}", e),
                            }
                            break; // Short header 始终是 coalesced 的最后一个
                        }
                    }

                    // 被推迟的 1-RTT 子包交给调用方：先 flush HANDSHAKE_DONE 再重处理
                    // （保证客户端在写请求体前收到 HANDSHAKE_DONE，消除 ERR_CLOSING）
                    let handshake_just_completed = !deferred_1rtt.is_empty();
                    if !deferred_1rtt.is_empty() {
                        let n = deferred_1rtt.len();
                        self.pending_1rtt.extend(deferred_1rtt);
                        tracing::debug!(
                            "handshake just completed; deferred {n} coalesced 1-RTT sub-packet(s) to pending_1rtt for immediate HANDSHAKE_DONE flush"
                        );
                    }

                    // 握手刚完成时，process_streams 会发送服务端控制流 SETTINGS 等 1-RTT
                    // 应用数据。为避免其与 HANDSHAKE_DONE 同批发出（推迟/干扰 HANDSHAKE_DONE
                    // 的独立送达），此处跳过——控制流 SETTINGS 与请求处理统一推迟到
                    // pending_1rtt 重处理阶段（该阶段 HANDSHAKE_DONE 已先行 flush）。
                    let h3_output = if handshake_just_completed {
                        Vec::new()
                    } else {
                        self.process_streams(&route_key, app_handler)
                    };
                    tracing::debug!("h3 produced {} response packets", h3_output.len());
                    all_output.extend(h3_output);
                    return Ok(all_output);
                } else {
                    tracing::debug!("new connection - creating");
                    // 新连接：解析 Initial 包信息，创建 NetQuicConn
                    if data.len() >= 6 {
                        let dcid_len = data[5] as usize;
                        let dcid_end = 6 + dcid_len;
                        if dcid_end < data.len() {
                            let scid_len = data[dcid_end] as usize;
                            let scid_start = dcid_end + 1;
                            let scid_end = scid_start + scid_len;
                            if scid_end <= data.len() {
                                let client_dcid = data[6..dcid_end].to_vec();
                                let client_scid = data[scid_start..scid_end].to_vec();

                                // 生成唯一 server SCID（密码学随机，防预测/碰撞）
                                let server_scid = {
                                    let mut scid = vec![0u8; 8];
                                    // fail-closed：OS 熵源失败直接返回错误，
                                    // 禁止静默降级为可预测 SCID（连接 ID 可被猜测即可被劫持）
                                    if !zenith_foundation::random::try_fill_random(&mut scid) {
                                        return Err(QuicTransportError::Quic(
                                            "SCID random generation failed".into(),
                                        ));
                                    }
                                    // 确保非零
                                    if scid.iter().all(|b| *b == 0) {
                                        scid[0] = 0x01;
                                    }
                                    scid
                                };

                                let rustls_config = self
                                    .rustls_config
                                    .clone()
                                    .ok_or_else(|| {
                                        tracing::error!("QUIC 新连接到达但 rustls config 未绑定（须先 bind_cert）");
                                        QuicTransportError::Quic("no rustls config".into())
                                    })?;

                                // create_connection 返回 client_dcid 的路由 tag（非 DCID 本身）
                                let route_tag = match self.create_connection(
                                    from,
                                    client_scid,
                                    client_dcid,
                                    server_scid,
                                    &rustls_config,
                                ) {
                                    Ok(tag) => {
                                        tracing::debug!("new connection created, route_tag={:02x?}", tag);
                                        tag
                                    }
                                    Err(e) => {
                                        tracing::debug!("create_connection error: {}", e);
                                        return Ok(Vec::new());
                                    }
                                };

                                // 现在用真实的 NetQuicConn 处理初始包
                                let Some(conn) = self.connections.get_mut(&route_tag) else {
                                    // create_connection 刚插入即消失（理论不可达，fail-closed）
                                    return Ok(Vec::new());
                                };
                                let output = match conn.net_conn.handle_initial_packet(data) {
                                    Ok(o) => {
                                        tracing::debug!("initial packet handled, {} response packets", o.len());
                                        // 绑定 QUIC ClientHello 提取的 JA3/JA4 指纹（若已完整到达）
                                        if let Some(fp) = bind_pending_fingerprint(conn) {
                                            self.last_fingerprint = Some(fp);
                                        }
                                        o
                                    }
                                    Err(e) => {
                                        // RFC 9000 §19.19：包解析失败（首包不可解密）→
                                        // RFC 9000 §8.1 防放大语义：静默丢弃，无响应。
                                        // 传输参数校验失败（TRANSPORT_PARAMETER_ERROR）需发 CC。
                                        // Crypto/TLS alert 错误也需发 CC（含 TLS alert code）。
                                        let msg = e.to_string();
                                        let is_tp_error = msg.contains("TRANSPORT_PARAMETER_ERROR");
                                        if matches!(e, NetQuicError::PacketParse(_)) && !is_tp_error {
                                            tracing::debug!(
                                                "new conn handle_initial_packet parse error (silent): {}",
                                                e
                                            );
                                            return Ok(Vec::new());
                                        }
                                        tracing::warn!(
                                            "new conn handle_initial_packet error -> CONNECTION_CLOSE: {}",
                                            e
                                        );
                                        // crypto 错误用 TLS alert code（rustls 已设置 alert）
                                        let (mut error_code, frame_type) = quic_error_code(&e);
                                        if matches!(e, NetQuicError::Crypto(_)) {
                                            let alert_code = conn.net_conn.peer_alert_code();
                                            let errmsg = e.to_string();
                                            tracing::warn!("[TLS DIAG] rustls error: {} (alert=0x{alert_code:x})", errmsg);
                                            // RFC 9001 §4.5: KeyUpdate / EndOfEarlyData / missing_extension / no_app_proto
                                            // → must use unexpected_message (10) / missing_extension (109)
                                            let (adj_alert, fix) = if errmsg.contains("unexpected message")
                                                || errmsg.contains("KeyUpdate")
                                                || errmsg.contains("EndOfEarlyData")
                                                || errmsg.contains("unexpected_message")
                                            {
                                                (0x010A, true) // unexpected_message
                                            } else if errmsg.contains("MissingQuicTransportParameters")
                                                || errmsg.contains("missing_extension")
                                                || errmsg.contains("MissingExtension")
                                            {
                                                (0x016D, true) // missing_extension (109)
                                            } else {
                                                (alert_code, false)
                                            };
                                            error_code = if fix { adj_alert } else { alert_code };
                                        }
                                        let cc_frame = build_connection_close_transport(
                                            error_code,
                                            frame_type,
                                            "initial error",
                                        );
                                        let client_addr = conn.client_addr;
                                        let mut err_pkts: QuicResponsePackets = Vec::new();
                                        if let Ok(pkt) = conn.net_conn.build_initial_cc_packet(&cc_frame) {
                                            err_pkts.push((pkt, client_addr));
                                        }
                                        if let Ok(pkt) = conn.net_conn.build_handshake_cc_packet(&cc_frame) {
                                            err_pkts.push((pkt, client_addr));
                                        }
                                        if let Ok(pkt) = conn.net_conn.build_1rtt_packet(&cc_frame) {
                                            err_pkts.push((pkt, client_addr));
                                        }
                                        return Ok(err_pkts);
                                    }
                                };

                                let client_addr = conn.client_addr;
                                let mut all_output: QuicResponsePackets =
                                    output.into_iter().map(|p| (p, client_addr)).collect();
                                let h3_output = self.process_streams(&route_tag, app_handler);
                                all_output.extend(h3_output);
                                tracing::debug!("handle_packet returning {} packets to send to {}", all_output.len(), client_addr);
                                return Ok(all_output);
                            }
                        }
                    }
                }
            }
        } else {
            // Short Header (1-RTT)：用 server DCID 路由（需通过 server_dcid_index 反查 client_dcid）
            let server_dcid_len = self
                .connections
                .values()
                .next()
                .map(|c| c.net_conn.server_dcid.len())
                .unwrap_or(8);

            // 尝试用 server DCID 精确匹配 → 反查 client 路由 tag → 查连接
            if let Some(srv_dcid) = Self::extract_short_dcid(data, server_dcid_len) {
                // fail-closed：路由密钥不可用（构造期熵源失败）→ 丢弃数据包
                let Some(srv_tag) = self.dcid_tag(srv_dcid) else {
                    tracing::error!("DCID 路由密钥不可用，丢弃 short header 数据包");
                    return Ok(Vec::new());
                };
                if let Some(client_tag) = self.server_dcid_index.get(&srv_tag) {
                    let client_tag = *client_tag;
                    tracing::debug!("short header: srv_dcid={:02x?} → client tag matched", srv_dcid);
                    if let Some(conn) = self.connections.get_mut(&client_tag) {
                        // ── 连接迁移检测（RFC 9000 §9）─────────────────────
                        // 1-RTT 包来自新地址 → 发起 PATH_CHALLENGE 路径验证，
                        // 乐观迁移到新地址，验证通过前施加防放大限制（§8.1）。
                        let mut path_challenge_pkt: Option<Vec<u8>> = None;
                        if from != conn.client_addr {
                            let need_new = match &conn.migration {
                                Some(m) => m.new_addr != from,
                                None => true,
                            };
                            if need_new {
                                // fail-closed：熵源失败直接返回错误，禁止可预测挑战值
                                // （可预测的 PATH_CHALLENGE 使路径验证形同虚设）
                                let mut challenge = [0u8; 8];
                                if !zenith_foundation::random::try_fill_random(&mut challenge) {
                                    return Err(QuicTransportError::Quic(
                                        "PATH_CHALLENGE 随机生成失败".into(),
                                    ));
                                }
                                let frame = zenith_net::transport::quic_server::build_path_challenge_frame(&challenge);
                                if let Ok(pkt) = conn.net_conn.build_1rtt_packet(&frame) {
                                    path_challenge_pkt = Some(pkt);
                                }
                                conn.migration = Some(MigrationState {
                                    new_addr: from,
                                    challenge,
                                    bytes_received: 0,
                                    bytes_sent: 0,
                                    validated: false,
                                });
                                tracing::debug!("[QUIC MIGRATION] new addr {} → PATH_CHALLENGE sent", from);
                            }
                            // 乐观迁移：立即切换（受防放大限制，见下）
                            conn.client_addr = from;
                        }
                        // 累计从新地址接收的字节（防放大分母）
                        if let Some(m) = &mut conn.migration
                            && m.new_addr == from
                            && !m.validated
                        {
                            m.bytes_received = m.bytes_received.saturating_add(data.len() as u64);
                        }

                        // ── 处理 1-RTT 包（可能含 PATH_RESPONSE）──────────────
                        // 竞态防护：aioquic 等客户端在 Finished 之后、握手完成前，
                        // 以独立 UDP 数据报发出 1-RTT 请求（不与 Finished coalesced）。
                        // 若此处 1-RTT 密钥未就绪即解密 → DecryptError 丢请求。
                        // 握手未完成时推迟到 pending_1rtt（server.rs 先 flush
                        // HANDSHAKE_DONE 再重处理），与 coalesced 推迟路径语义一致。
                        if !conn.net_conn.handshake_done_sent {
                            tracing::debug!(
                                "1-RTT short 包在握手完成前到达，推迟到 pending_1rtt"
                            );
                            if self.pending_1rtt.len() >= MAX_PENDING_1RTT {
                                self.pending_1rtt.remove(0);
                            }
                            self.pending_1rtt.push((data.to_vec(), from));
                            return Ok(Vec::new());
                        }
                        let output = match conn.net_conn.handle_short_packet(data) {
                            Ok(o) => o,
                            Err(e) => {
                                tracing::warn!(
                                    "handle_short_packet error -> CONNECTION_CLOSE: {}",
                                    e
                                );
                                let client_tag_copy = client_tag;
                                let cc_addr = conn.client_addr;
                                let ack_frame_opt = conn.net_conn.pending_err_ack.take();
                                let is_crypto = matches!(e, NetQuicError::Crypto(_));
                                let peer_alert = if is_crypto { conn.net_conn.peer_alert_code() } else { 0 };
                                let errmsg = e.to_string();
                                if is_crypto {
                                    tracing::warn!("[TLS DIAG 1RTT] rustls error: {} (alert=0x{peer_alert:x})", errmsg);
                                }
                                let _ = conn;
                                let h3_output = self.process_streams(&client_tag_copy, app_handler);
                                let (mut error_code, frame_type) = quic_error_code(&e);
                                if is_crypto {
                                    let (adj, fix) = if errmsg.contains("unexpected message")
                                        || errmsg.contains("KeyUpdate")
                                        || errmsg.contains("EndOfEarlyData")
                                        || errmsg.contains("unexpected_message")
                                        || errmsg.contains("received unexpected")
                                    {
                                        (0x010A, true)
                                    } else if errmsg.contains("MissingQuicTransportParameters")
                                        || errmsg.contains("missing_extension")
                                        || errmsg.contains("MissingExtension")
                                    {
                                        (0x016D, true)
                                    } else {
                                        (peer_alert, false)
                                    };
                                    error_code = if fix { adj } else { peer_alert };
                                }
                                let cc_frame = build_connection_close_transport(
                                    error_code,
                                    frame_type,
                                    "transport error",
                                );
                                let mut err_output: QuicResponsePackets = h3_output;
                                if let Some(conn) = self.connections.get_mut(&client_tag_copy) {
                                    if let Ok(pkt) = conn.net_conn.build_1rtt_cc_packet(
                                        ack_frame_opt.as_deref().unwrap_or(&[]),
                                        &cc_frame,
                                    ) {
                                        err_output.push((pkt, cc_addr));
                                    } else if let Ok(pkt) = conn.net_conn.build_1rtt_packet(&cc_frame) {
                                        err_output.push((pkt, cc_addr));
                                    }
                                }
                                return Ok(err_output);
                            }
                        };

                        // ── 迁移验证：PATH_RESPONSE 匹配 challenge 则通过 ──────
                        let validated_now = match &conn.migration {
                            Some(m) => !m.validated && conn.net_conn.pending_path_response.contains(&m.challenge),
                            None => false,
                        };
                        if validated_now {
                            if let Some(m) = &mut conn.migration {
                                m.validated = true;
                                let ch = m.challenge;
                                conn.net_conn.pending_path_response.retain(|d| *d != ch);
                            }
                            tracing::debug!("[QUIC MIGRATION] path validated → migrated to {}", conn.client_addr);
                        }

                        let mut all_output: QuicResponsePackets =
                            output.into_iter().map(|p| (p, conn.client_addr)).collect();
                        if let Some(pc) = path_challenge_pkt {
                            all_output.push((pc, conn.client_addr));
                        }

                        // ── 防放大：未验证路径发送 ≤ 3×接收（RFC 9000 §8.1）────
                        let amp_budget = match &conn.migration {
                            Some(m) if !m.validated => Some(
                                3u64.saturating_mul(m.bytes_received).saturating_sub(m.bytes_sent),
                            ),
                            _ => None,
                        };
                        if let Some(budget) = amp_budget {
                            let mut allowed = budget;
                            let mut sent_now = 0u64;
                            let mut kept: QuicResponsePackets = Vec::new();
                            for (pkt, addr) in all_output {
                                let plen = pkt.len() as u64;
                                if plen <= allowed {
                                    allowed -= plen;
                                    sent_now += plen;
                                    kept.push((pkt, addr));
                                }
                                // 超出预算的包丢弃（防放大），待路径验证后恢复正常
                            }
                            all_output = kept;
                            if let Some(m) = &mut conn.migration {
                                m.bytes_sent = m.bytes_sent.saturating_add(sent_now);
                            }
                        }

                        let h3_output = self.process_streams(&client_tag, app_handler);
                        all_output.extend(h3_output);

                        // RFC 9000 §10.3: 收到 CONNECTION_CLOSE 后清理连接状态
                        // （防内存泄漏：Closed 连接不从 map 移除将永久驻留）
                        let should_close = self.connections.get(&client_tag)
                            .is_some_and(|c| c.net_conn.state == QuicServerState::Closed);
                        if should_close {
                            self.server_dcid_index.retain(|_, v| *v != client_tag);
                            self.connections.remove(&client_tag);
                            tracing::debug!(
                                "[QUIC CLEANUP] removed closed connection, tag={:02x?}",
                                client_tag
                            );
                        }

                        return Ok(all_output);
                    }
                } else {
                    tracing::debug!("short header: no server_dcid_index entry for {:02x?}", srv_dcid);
                }
            }

            // Fallback: 用客户端地址匹配
            if let Some(dcid) = self.find_conn_by_addr(from) {
                tracing::debug!("short header: fallback by addr → route_tag={:02x?}", dcid);
                if let Some(conn) = self.connections.get_mut(&dcid) {
                    // 竞态防护（同主路径）：握手未完成的 1-RTT 短包推迟到 pending_1rtt
                    if !conn.net_conn.handshake_done_sent {
                        tracing::debug!(
                            "1-RTT short 包（fallback）在握手完成前到达，推迟到 pending_1rtt"
                        );
                        if self.pending_1rtt.len() >= MAX_PENDING_1RTT {
                            self.pending_1rtt.remove(0);
                        }
                        self.pending_1rtt.push((data.to_vec(), from));
                        return Ok(Vec::new());
                    }
                    let output = match conn.net_conn.handle_short_packet(data) {
                        Ok(o) => o,
                        Err(e) => {
                            tracing::debug!("handle_short_packet error: {}", e);
                            return Ok(Vec::new());
                        }
                    };

                    let mut all_output: QuicResponsePackets =
                        output.into_iter().map(|p| (p, conn.client_addr)).collect();
                    let h3_output = self.process_streams(&dcid, app_handler);
                    all_output.extend(h3_output);

                    // RFC 9000 §10.3: 收到 CONNECTION_CLOSE 后清理连接状态
                    let should_close = self.connections.get(&dcid)
                        .is_some_and(|c| c.net_conn.state == QuicServerState::Closed);
                    if should_close {
                        self.server_dcid_index.retain(|_, v| *v != dcid);
                        self.connections.remove(&dcid);
                        tracing::debug!(
                            "[QUIC CLEANUP] removed closed connection (fallback), tag={:02x?}",
                            dcid
                        );
                    }

                    return Ok(all_output);
                }
            }

            // 如果找不到连接，缓存 1-RTT 包（可能在握手完成前到达）
            // 有界队列防 DoS：超上限丢弃最旧包（FIFO 淘汰），不无限增长
            if self.pending_1rtt.len() >= MAX_PENDING_1RTT {
                self.pending_1rtt.remove(0);
                tracing::warn!(
                    "pending_1rtt 达到上限 {MAX_PENDING_1RTT}，丢弃最旧包（DoS 防护）"
                );
            }
            self.pending_1rtt.push((data.to_vec(), from));
            tracing::debug!("short header - no matching connection, cached as pending");
        }

        tracing::debug!("returning empty response (no matching path)");
        Ok(Vec::new())
    }
}

// ---------------------------------------------------------------------------
// 辅助：encode_varint_buf 直接复用 zenith-http3 单一实现
// （含 ≥2^62 fail-closed 拒绝；本地副本已删除，消除双实现分歧）
// ---------------------------------------------------------------------------

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

    /// 回归（曾 0x01/0x02 错位）：
    /// RFC 9204 §4.2 单向流类型前缀 0x02=QPACK encoder / 0x03=QPACK decoder；
    /// RFC 9114 §6.2.1 Push 流 = 0x01（本服务器不使用推送 → Unknown）。
    /// 与 zenith_http3::stream::STREAM_TYPE_* 常量同步锁定。
    #[test]
    fn classify_stream_qpack_prefixes_rfc_9204() {
        // client uni stream（stream_id % 4 == 2）
        assert_eq!(classify_stream(2, &[0x00]), H3StreamKind::Control);
        assert_eq!(classify_stream(2, &[0x02]), H3StreamKind::QpackEncoder);
        assert_eq!(classify_stream(2, &[0x03]), H3StreamKind::QpackDecoder);
        // 常量契约持续锁定
        assert_eq!(zenith_http3::stream::STREAM_TYPE_CONTROL, 0x00);
        assert_eq!(zenith_http3::stream::STREAM_TYPE_QPACK_ENCODER, 0x02);
        assert_eq!(zenith_http3::stream::STREAM_TYPE_QPACK_DECODER, 0x03);
        // Push 流（0x01）与未知前缀 → Unknown
        assert_eq!(classify_stream(2, &[0x01]), H3StreamKind::Unknown);
        assert_eq!(classify_stream(2, &[0xff]), H3StreamKind::Unknown);
        // 空载荷 → Unknown；server bidi（%4==1）→ Unknown；client bidi → Request
        assert_eq!(classify_stream(2, &[]), H3StreamKind::Unknown);
        assert_eq!(classify_stream(1, &[0x00]), H3StreamKind::Unknown);
        assert_eq!(classify_stream(0, &[0x02]), H3StreamKind::Request);
        assert_eq!(classify_stream(6, &[0x03]), H3StreamKind::QpackDecoder);
    }

    /// 服务端单向流 ID 分配器：固定协议惯例序 3/7/11（RFC 9114 §6.2.1 / RFC 9204 §4.2）。
    ///
    /// 控制流固定 = 3（首 server uni stream）、QPACK 编码器流固定 = 7、
    /// QPACK 解码器流固定 = 11。**必须固定**而不能按调用顺序惰性分配：
    /// 若 QPACK 指令在握手完成前被处理，惰性分配会让 QPACK 流抢占 stream 3，
    /// 把控制流挤到 11，导致对端误判控制流缺失（POST INTERNAL_ERROR）。
    #[test]
    fn server_uni_stream_ids_fixed_layout() {
        let mut ids = ServerUniStreamIds::new();
        // 固定协议惯例：4 + 于 3 的 server uni 流
        assert_eq!(ids.control(), Some(3));
        assert_eq!(ids.qpack_encoder(), Some(7));
        assert_eq!(ids.qpack_decoder(), Some(11));
        // 缓存不变性：再次获取稳定同值
        assert_eq!(ids.control(), Some(3));
        assert_eq!(ids.qpack_encoder(), Some(7));
        assert_eq!(ids.qpack_decoder(), Some(11));
        // 干净分配器上调用顺序互换仍返回固定值（不依赖调用顺序）
        let mut ids2 = ServerUniStreamIds::new();
        assert_eq!(ids2.qpack_decoder(), Some(11));
        assert_eq!(ids2.control(), Some(3));
        assert_eq!(ids2.qpack_encoder(), Some(7));
    }
}