企业官网建设流程全解析

V 语言 net.quic 模块 HTTP/3 实现全景：从 RFC 9000 原语到 QPACK 的十二阶段工程实录

【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in <1s with zero library dependencies. Supports automatic C => V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v

本篇技术指南基于 V 语言官方仓库（GitHub_Trending/v/v）中vlib/net/quic/PROGRESS.md这一份详细的实施进度文档，系统梳理net.quic模块从零构建 QUIC v1 传输层并最终接入net.httpHTTP/3 客户端的完整技术路线：纯 V 实现的 QUIC 限定 TLS 1.3 握手、RFC 9000 包格式与传输参数、包/头部保护、流层与流控、丢包检测与 NewReno 拥塞控制，以及 RFC 9114 HTTP/3 帧层与 RFC 9204 QPACK 的全部落地细节。读完本文，你将掌握 QUIC/HTTP/3 在 V 语言生态中的实现骨架、各阶段模块划分与文件对应关系、关键 RFC 约束的工程化处理方式，以及如何用enable_http3在net.http中实际发起 HTTP/3 请求。

背景：为什么 V 需要一套自己的 QUIC 传输层

net.quic是net.http获得 HTTP/3 支持的地基。项目以分支http3-quic-foundation推进，其核心架构决策记录在 README.md 与 PROGRESS.md 中：

• TLS 1.3 用纯 V 从零实现，而不是修补 mbedTLS：已随仓库分发的 mbedTLS 在所有已发布版本中都没有 QUIC 支持，因此在 V 中实现一个 QUIC 限定的 TLS 1.3 握手（RFC 8446）是更干净的选择。
• X.509 证书解析与链校验仍委托 mbedTLS：复用已有的 C 绑定mbedtls_x509_crt_parse、mbedtls_x509_crt_verify、mbedtls_pk_parse_key、mbedtls_pk_verify_ext，与net.http的 HTTP/1.1、HTTP/2 后端做法一致，无需任何 mbedTLS 源码补丁。
• OpenSSL 是硬依赖而非可选开关：TLS 1.3 密钥交换需要 P-256 ECDH（secp256r1key_share组），此前 V 中不存在。新增 OpenSSL 绑定（vlib/crypto/ecdsa/ecdsa.c.v，derive_shared_secret、uncompressed_bytes/from_uncompressed_bytes），沿用crypto.ecdsa已有的-lcrypto链接方式。虽然曾考虑-d no_openssl_quic回退开关，但 Windows CI 已证明crypto.ecdsa在三大平台全量构建测试通过，故决策为硬依赖、无降级模式。

Phase 0 还验证了 mbedTLS 的 X.509 函数可以脱离mbedtls_ssl_context独立工作（见 x509_standalone_test.v），并新增了mbedtls_x509_crt_verify/mbedtls_pk_verify绑定到 mbedtls.c.v。

Phase 1 — 基础原语：varint、包号与包头

QUIC 的一切报文都以变量长整数（varint）为基础。varint.v 实现了 RFC 9000 §16 的 QUIC varint——注意它与vlib/encoding/leb128位级不兼容，绝不能互换：LEB128 每个字节用延续位，QUIC varint 则把 2 位长度类打包进首字节高位：

0b00xxxxxx -> 1 字节，6 位值 0b01xxxxxx xxxxxxxx -> 2 字节，14 位值 0b10xxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -> 4 字节，30 位值 0b11xxxxxx (+ 7 字节) -> 8 字节，62 位值

最大可表示值为 2^62-1（max_varint）。decode_varint接受全部四种合法长度类（RFC 允许非最短编码，曾有一个 Codex 发现把规范合法的非最短编码误判为解析错误，已修正），但拒绝截断输入。

packet_number.v 实现 RFC 9000 §17.1 的包号截断编码与 Appendix A 的重构算法：线上只传输 1–4 字节的最小表示，接收方依据同一包号空间中已确认的最大包号重构完整值。文档记录了一个真实的 u64 下溢 bug——重构算法的朴素移植在边界值测试中暴露并被修复；同时encode_packet_number拒绝超过 2^62-1（§12.3 上限）的包号而非静默截断。

header.v 负责长短包头解析与编码、零长度 CID、以及作为独立包形式的 Version Negotiation。两个刻意延迟的校验：

• Reserved 位校验推迟到 Phase 3（位于头部保护区内，未解除保护前无意义）；
• 合并包拆分推迟到 Phase 4（coalesce.v），解析器已返回“消耗字节数”作为该阶段的构建块。

Phase 2 — QUIC 限定的 TLS 1.3 握手与密钥调度

这是最大、风险最高的阶段，按构建顺序分为 2a/2b/2c 三个子阶段。

2a — Initial 密钥（initial_secrets.v）：实现 RFC 9001 §5.2，固定公开盐（initial_salt，21 字节常量）+ HKDF（复用现有crypto.hkdf），并实现hkdf_expand_label（RFC 8446 §7.1）——这是 2b/2c 与 Phase 3 共享的派生原语，文档明确要求不要在其他地方重复实现。测试直接对 RFC 9001 Appendix A.1 的官方测试向量（initial_secret、client_initial_secret、server_initial_secret及链式quic key/quic iv/quic hp）做精确匹配，而非仅内部自洽。关键边界：derive_initial_secrets与 DCID 强相关，Retry 之后必须用 Retry 包的 Source Connection ID 重新派生（RFC 9001 §5.2 明确要求），文档还记录了一处曾经写反、后经 Codex 发现并纠正的说明。

2b — 密钥调度（tls13_keyschedule.v）：完整 RFC 8446 §7.1 链（Early → Handshake → Master），v1 仅固定TLS_AES_128_GCM_SHA256。derive_secret/derive_early_secret/derive_handshake_secrets/derive_application_secrets覆盖到两个 application traffic secrets_0；exporter_master_secret/resumption_master_secret刻意省略（v1 不用 TLS exporter 与 0-RTT）。HelloRetryRequest 的合成转录规则（§4.4.1）以synthetic_client_hello1_hash实现。验证独立于 2a 的向量：对照 RFC 8448 §3 的官方中间密钥，并程序化验证 Transcript-Hash 只覆盖裸握手消息字节、不含记录层帧（RFC 8446 §4.4.1 / RFC 9001 §4）。

2c — 消息与状态机（tls13_messages.v、tls13_handshake.v），子项包括：

• 通用握手消息框架：HandshakeType枚举只含 RFC 8446 §B.3 v1.3 真实集合，TLS 1.2 时代的 RESERVED 值正确拒绝而非静默接受；1 字节类型 + 3 字节长度；parse_handshake_message每次只剥离一条消息并报告消耗字节数——因为 QUIC 的 CRYPTO 流允许消息跨包拆分（Phase 4 的组装职责）。
• Finished 消息 MAC（§4.4.4）：compute_finished_verify_data/verify_finished侧无关，调用方自选 client/server traffic secret；对等方 verify_data 比较使用crypto.hmac.equal（恒定时间），而非==。
• quic_transport_parameters扩展内部载荷（RFC 9000 §18，transport_parameters.v）：全部 17 个 §18.2 参数（含嵌套preferred_address结构），未知 ID 忽略而非拒绝，ack_delay_exponent/max_udp_payload_size/max_ack_delay/active_connection_id_limit均按规范自带边界做接受/拒绝配对测试，重复参数 ID 拒绝。
• ClientHello 构造（tls13_client_hello.v）：legacy_version 0x0303、空 legacy_session_id（RFC 9001 §8.4 禁止 QUIC 上的中间盒兼容模式）、单一密码套件，六个扩展：server_name、supported_versions、supported_groups（仅 secp256r1）、signature_algorithms（ECDSA P-256 + RSA-PSS）、key_share（Phase 1 的 P-256 ECDH 公钥）、quic_transport_parameters。与 RFC 8448 §3 的真实 ClientHello 做了两处字节级交叉校验。
• ServerHello / EncryptedExtensions 解析（tls13_server_hello.v）：parse_server_hello返回ParsedHelloRetryRequest | ParsedServerHello和类型，通过 §4.1.3 的魔法 Random 值区分（该值由实时 SHA-256 计算独立验证）；校验所有可静态检查的 MUST。
• Certificate / CertificateVerify 解析（tls13_certificate.v）：certificate_verify_signed_content实现 §4.4.3 的 64 字节填充 + 上下文串 + 分隔符 + 转录哈希构造，与 RFC 自带算例逐字节核对。
• mbedTLS X.509 链校验（独立于mbedtls_ssl_context）：新增net.mbedtls公共 API（x509_standalone.c.v 的build_certificate_chain/verify_certificate_chain/free_certificate_chain），net.quic侧由 tls13_certificate_chain.c.v 包装。
• 客户端状态机（tls13_handshake.v）：Tls13ClientHandshake.start（临时 ECDHE 密钥 + ClientHello）→process_server_hello/process_encrypted_extensions/process_certificate_or_request/process_certificate_verify/process_finished；TlsAlert+tls_alert_to_quic_error实现 RFC 9001 §4.8 的 0x100 + alert description 映射。首次 HelloRetryRequest 与 CertificateRequest 明确“未实现”而非静默误处理。端到端测试用真正的假 TLS 1.3 服务器（真实 ECDHE、真实 RSA-PSS CertificateVerify 签名、真实 Finished HMAC）验证双方达成一致。

Phase 2 还从 Cloudflare quiche（cloudflare/quiche-qns:latest，按 digest 固定）抓取真实握手（SSLKEYLOGFILE+tcpdump+tshark4.6.6 解密解剖），构建了 RFC 8448 风格的测试向量套件（testdata/tls13_vectors/），tls13_quiche_vector_test.v用模块自身的生产函数解析每一条真实捕获消息，并用真实 ECDSA P-256 签名验证成功——填补了仓库无 EC 私钥导致的覆盖缺口。

Phase 3 — 包保护与头部保护

packet_protection.v 与 header_protection.v 是两个核心文件：

• QuicPacketProtectionKeys（quic_key/quic_iv/quic_hp，RFC 9001 §5.1）经hkdf_expand_label从任一层级的单向 traffic secret 派生，用 RFC 9001 Appendix A.1 向量验证。
• encrypt_packet_payload/decrypt_packet_payload包装crypto.aes.AesGcm；AEAD nonce 将包的完整重构包号（绝非截断的线上字节）XOR 进 12 字节 IV 的低 8 字节。
• protect_packet/unprotect_packet把包+头部保护合并为单一正确顺序（发送侧：加密载荷 → 采样密文 → 派生掩码 → 应用到头；接收侧：先解头部保护——因为包号长度本身被保护——再 AEAD 解密），从结构上杜绝调用方把两步顺序搞反——这是该领域最常见的 bug 类别。
• 头部保护仅需 AES-ECB 掩码派生（RFC 9001 §5.4.3，因为全链固定TLS_AES_128_GCM_SHA256）；采样始终在包号字段之后固定 4 字节偏移处（§5.4.2）。
• unprotect_header一旦解除掩码即校验 Reserved 位为零（RFC 9000 §17.2/§17.3.1 MUST，Phase 1 就标注推迟至此），并返回普通错误供接收方映射为 PROTOCOL_VIOLATION，与 AEAD 认证失败（须静默丢弃、绝不升级为连接关闭，见decrypt_packet_payload文档）相区分。

测试亮点：用与 Phase 2 同一 quiche 抓包（quiche_p256_handshake.pcap）的第 1 帧（单个 1200 字节 Client Initial）做已知答案测试——用最小独立 pcap/UDP 解析器提取原始字节（无需 Wireshark），仅凭包自身 DCID 派生 Initial 密钥，去保护后校验明文包含与tls13_quiche_vector_test.v独立验证过的完全相同的 ClientHello 字节（两条完全不同的提取路径互为交叉验证）；配套负向测试翻转一位密文，确认 AEAD 干净失败。

Phase 4 — Initial 包交换

• frame.v：PADDING/PING/ACK/CRYPTO/CONNECTION_CLOSE 的解析与编码（RFC 9000 §19），范围严格限定为 Initial/Handshake 包号空间合法的帧类型（§12.4 Table 3）；其他帧类型（STREAM、MAX_DATA 等）报“not yet implemented”而非线格式错误。
• crypto_stream.v：按加密层级做 CRYPTO 帧重组，容忍乱序到达与重叠重传（§19.6）；任何重叠内容不一致在重叠点即被拒绝（单一校验后追加路径），而不是事后以难解的转录哈希/Finished MAC 失败浮现。
• coalesce.v：按长包头Length字段拆分数据报；在短包头、Version Negotiation、Retry 或尾部非包填充处干净停止；pad_initial_payload通过AEAD 保护载荷内部的 PADDING 帧把发送方 Initial 包补齐到 RFC 9000 §14.1 的 1200 字节下限（而非保护后追加裸字节）。
• retry.v：客户端 Retry 完整性标签（RFC 9001 §5.8），AEAD_AES_128_GCM 空明文 + 固定公开密钥/nonce；固定密钥/nonce 经 RFC 文本与 quiche Rust 源码（RETRY_INTEGRITY_KEY_V1/RETRY_INTEGRITY_NONCE_V1）双源确认。无效标签返回false（静默丢弃）而非错误——防伪造者借此中断合法握手。
• version_negotiation.v：列有 v1 自身的 VN 包必须静默丢弃（§6.2）；不含 v1 的 VN 包干净失败（客户端只实现 v1、无低版本回退）；VN 包 DCID 必须回显客户端原始 SCID，否则按未认证/伪造丢弃。

集成测试 initial_exchange_test.v 把 Phase 2+3+4 串起来：真实 ClientHello → 真实 CRYPTO 帧 → 真实包+头部保护 → 经[]u8假传输“发送”→ 接收侧完全逆转，最终重组的 CRYPTO 流精确还原原始 ClientHello 字节并可重新解析为合法握手消息。

Phase 5 — 握手完成：包号空间、握手确认与密钥更新

• packet_number_space.v：形式化三个相互独立的包号空间（Initial/Handshake/Application Data）——文档明确标注这是最容易实现错的点（把包号当作连接全局会使 ACK 帧与任何合规对端互操作失败）。QuicPacketNumberSpaces以三个真正独立的结构体字段分组，无共享可变状态。
• handshake_confirm.v：把 “complete”（已发送自己的 Finished 且已校验对端 Finished）与 “confirmed”（收到 HANDSHAKE_DONE）建模为两个独立检查点，各有独立密钥丢弃触发（RFC 9001 §4.9.1/§4.9.2），外加第三个独立检查点（发送首个 Handshake 空间包时丢弃 Initial 密钥）。v1 总是等待 HANDSHAKE_DONE，不实现 ack 替代确认路径。
• key_update.v：仅接收侧的 1-RTT 密钥相位位旋转（RFC 9001 §6）。resolve_read_keys仅凭包相位位与包号决定用哪套密钥尝试解密（当前相位 / 保留的上一相位 / 新派生的下一相位），从不自行变更状态或认证；note_successful_decrypt只在调用方 AEAD 真正成功后提交结果，并在提交时重新从包的真实相位位推导分类而非信任解析时标志——修复了一个跨包提交的陈旧标志导致永久去同步的解密 bug。

Phase 6 — 流层与流控

• frame.v 扩展：STREAM（0x08-0x0f，OFF/LEN/FIN 位）、RESET_STREAM、STOP_SENDING、MAX_DATA、MAX_STREAM_DATA、MAX_STREAMS（双向/单向）、DATA_BLOCKED、STREAM_DATA_BLOCKED、STREAMS_BLOCKED（双向/单向）。无长度 STREAM 帧（LEN 位清零）正确消耗parse_frames缓冲区剩余部分（§19.8 要求它必须是包内最后一帧）。
• stream.v：StreamId类别推导（§2.1）、QuicRole感知的is_locally_initiated、SendStreamState/RecvStreamState（§3.1/§3.2）。QuicStream.send/recv是可空指针（&StreamSendHalf/&StreamRecvHalf，沿用Tls13ClientHandshake.verified_chain的既有约定），确保每个调用方直接修改同一个共享半流。QuicStreamSet.get_or_create自动创建对端发起的流（含同类别所有更小编号流，§2.1），同时执行max_streams限制（STREAM_LIMIT_ERROR），拒绝仅因帧引用而伪造本地发起流（STREAM_STATE_ERROR）。
• stream_reassembly.v：按流偏移排序的重组（镜像 Phase 4 的 CRYPTO 流设计），扩展note_final_size把流的最终大小（FIN STREAM 帧或 RESET_STREAM）与已收/已缓冲内容对账（不匹配即 FINAL_SIZE_ERROR，§4.5）——与无最终大小概念的 CRYPTO 流的唯一实质差异。
• flow_control.v：FlowControlWindow（发送侧记账）+ReceiveWindow（接收侧记账，含自动增长启发式：应用消费至少一半当前窗口后提升上限，避免吞吐停滞）。initial_send_limit_for_stream/initial_receive_limit_for_stream一次性解析 §4.1 容易搞反的对端相对传输参数命名（initial_max_stream_data_bidi_local/_remote语义随参数归属与流方向反转），并对 4 种流类别从客户端视角用手工算例验证。

集成测试 stream_layer_test.v：三条流（客户端发起的双向流、服务端发起的单向流、第二条客户端双向流）的 STREAM 帧真正交错到达（非按流分组），各自独立重组，同时由单个连接级ReceiveWindow追踪三者累计总量。

Phase 7 — 丢包检测与 NewReno 拥塞控制

• rtt.v：RttEstimator（RFC 9002 §5.3），首样本直接播种 vs. 后续样本 EWMA 是两条真正不同的代码路径；Initial/Handshake 空间的 ACK Delay 无条件视为零（在update()内部由space参数决定，而非信任每个调用方）；对端max_ack_delay钳制仅在握手确认后应用；ack_delay 减法仅在其不会把样本压到min_rtt以下时应用。pto_period()抽取出smoothed_rtt + max(4*rttvar, kGranularity)项供各空间按 backoff 缩放。
• loss_detection.v：QuicLossDetectionTimer含三个独立每空间状态 + 单一连接级RttEstimator/pto_count/PTO 定时器（PTO 定时器刻意不按空间划分，经pto_time_and_space取自最早到期者）。detect_and_remove_lost_packets实现 §6.1 的包阈值（kPacketThreshold=3）或时间阈值（9/8·max(latest_rtt, smoothed_rtt)，下限 kGranularity）规则，任一满足即可。is_persistent_congestion按 §7.6.2 从单次检测批次实现。
• congestion_control.v：NewRenoCongestionControl（RFC 9002 Appendix B），慢启动/拥塞避免经is_in_slow_start()（每次调用重新推导congestion_window < ssthresh，不能简化为“发生过丢包”）；普通丢包 ssthresh 减半，持久拥塞直接塌缩到kMinimumWindow；in_congestion_recovery保证一次恢复事件无论带走多少包只反应一次。应用受限检测（§7.8）是 v1 明确的范围省略（Phase 9 之前没有真实发送队列），规范合法，只影响 cwnd 增长积极度。

Phase 8 — 连接生命周期

• idle_timeout.v：effective_idle_timeout解析 §10.1 的“取非零最小值”规则（覆盖全部 4 种零/非零组合，0 表示“无超时”）；IdleTimeoutState追踪刻意不对称的重置规则：收到 ack-eliciting 包重启、收到非 ack-eliciting 不重启，但任何发送都重启——并非“任一方向任意包”。
• connection_close.v：ConnectionCloseTracker：active→closing（本端已发 CONNECTION_CLOSE，可发限速重传——每收到一包至多一次，§10.2.1）→draining（收到对端 CONNECTION_CLOSE，或已在 closing 时收到；必须完全静默，§10.2.2 的单向吸收态）。
• stateless_reset.v：StatelessResetTracker按连接 ID 记录 stateless-reset token；is_stateless_reset文档明确限定只能在常规 AEAD 解密失败后调用（§10.3.1），且经crypto.subtle恒定时间比较尾随 16 字节（token 是秘密，变时比较会泄漏时序侧信道）。v1 不做完整 NEW_CONNECTION_ID/RETIRE_CONNECTION_ID 轮换。
• ecn.v：EcnState解析/记录对端上报的 ECN 计数（复用 frame.v 的EcnCounts）而不报错，但is_validated()恒为 false——V 目前没有 OS 级 ECN socket 选项可标记出站数据报，故无可验证（§13.4.2 的规范合法回退）。
• pmtu.v：固定 1200 字节安全下限（复用congestion_control.v的max_datagram_size，而非引入第三个常量），无主动 DPLPMTUD 探测；连接迁移明确不在范围内。

Phase 9 — QuicConn 顶层结构与事件循环

conn.v 是唯一把所有独立组件组合起来的文件，此前没有任何文件两两组合。单线程、调用方驱动的事件循环：调用方拥有实际 socket I/O，调用poll()/process_timeouts()推进状态机——与 quiche/ngtcp2 以库形式暴露自己的方式一致，无锁、无后台线程。

• 9a — 连接建立：dial()选择scid/original_dcid、派生 Initial 密钥、构建 ClientHello；poll()/process_timeouts()处理 Retry/VN 检测（含至多一次 Retry 与防伪造状态）、Initial/Handshake 包分流→去保护→帧解析、驱动Tls13ClientHandshake到process_finished、逐层密钥派生/晋升、CRYPTO 帧重组、接入丢包检测的 ACK 生成/处理、空闲超时、握手确认后密钥丢弃（RFC 9001 §4.9）。
• 9b — 稳态：1-RTT 包处理（STREAM/ACK/CONNECTION_CLOSE 分发进QuicStreamSet+ 双向流控）、open_stream/write_stream/read_stream、1-RTT 发送的丢包检测↔拥塞控制完整接线、MAX_STREAMS 执行、解密失败时的 stateless-reset 检测、ECN 计数记录、优雅/立即关闭、1-RTT 密钥更新轮换（app_read_keys/app_write_keys）。

测试（conn_test.v）用手工构建的 ServerHello→Finished 夹具（复用 Phase 2 的 RFC 8448/quiche 向量，无真实服务器）驱动dial()+poll()至handshake_confirmed；STREAM 数据往返、CONNECTION_CLOSE 处理、密钥更新均有覆盖。连接 ID 轮换/迁移明确排除在范围外（QuicConn只持有一个本地scid与对端当前dcid，无活动 CID 集合）。

Phase 10 — HTTP/3 帧层（RFC 9114）

Phase 10 在写任何代码前先构建了逐节需求矩阵（quic_conformance_matrix.md的 “HTTP/3 framing layer” 一节）——直接回应 Phase 9 自己的事后总结（“在实现之前/期间构建 RFC 检查清单，而非被动应对”）。新文件全部位于 vlib/net/quic/：

• h3_reserved.v：单一0x1f*N+0x21grease 码点公式，帧类型（§7.2.8）、流类型（§6.2.3）、SETTINGS 标识符（§7.2.4.1）、错误码（§8.1）四处共用——写代码前先确认四处 RFC 引用逐字一致。
• h3_error.v：H3ErrorCode枚举，全部 17 个值（§8.1/Table 4）。
• h3_stream_type.v：单向流 Stream Type 头（§6.2/6.2.1/6.2.2/6.2.3）：control（0x00）、push（0x01 + push ID）、reserved、unknown。增量式（缓冲区短时返回none而非错误——RFC 未规定头字节如何跨 QUIC STREAM 帧拆分）。
• h3_frame.v：帧 Type/Length 外壳（§7.1）+ 全部 7 种定义帧类型的载荷（DATA/HEADERS/CANCEL_PUSH/SETTINGS/PUSH_PROMISE/GOAWAY/MAX_PUSH_ID，§7.2.1-7.2.7）；4 种 H2 遗留保留帧类型（§7.2.8/Table 2）按 H3_FRAME_UNEXPECTED 拒绝，与 grease/真未知类型（§9，保留为H3RawFrame永不拒绝）相区分。H3FrameDecoder是本阶段核心的增量/可恢复读取器——跨push()调用缓冲部分字节，只有完整声明 Length 可用时才返回一帧。SETTINGS 拒绝重复标识符（§7.2.4 的 MAY，选择强制执行并文档化）与 5 个保留的 HTTP/2 遗留设置标识符，但不拒绝 QPACK 自己的 0x01/0x07（RFC 9204 的，非 9114 保留），留给 Phase 11。
• h3_message_state.v：仅需流角色（而非请求/响应上下文）的消息帧规则：Table 1 的按角色帧类型合法性（is_h3_frame_valid_on_stream）与 control 流 SETTINGS 必须最先且仅一次（H3ControlStreamState）。

显式推迟到 Phase 12 的项目（每条都是矩阵行标记⏳ Phase 12，而非静默缺口）：§4.1 的 HEADERS→DATA*→尾部 HEADERS 消息内容排序、单请求每流执行、CONNECT 的不同帧结构、PUSH_PROMISE/CANCEL_PUSH/MAX_PUSH_ID 跨帧状态、control 流唯一性/关闭执行、未知单向流类型的中止/丢弃动作、未识别错误码重映射到 H3_NO_ERROR。

Phase 11 — QPACK（RFC 9204）

在写任何代码前完整通读 RFC 9204 全部章节 + Appendix A（静态表）+ Appendix B（算例）+ Appendix C（样例编码算法），并据阅读构建quic_conformance_matrix.md的 “QPACK” 一节。范围边界与 Phase 10 先例完全一致：表、线上编解码器、编码/解码器状态机全部自包含（只需被最终拥有真实 QUIC 流的对象喂字节/事件），包括完整驱动状态机（含驱逐/引用计数的动态表、Known Received Count、阻塞流追踪）。

12 个新文件（各配_test.v，除极小的 qpack_error.v）：qpack_primitives.v（前缀整数 + 字符串字面量编解码，泛化为 QPACK 可变前缀宽度，算法写前已对照已发布且经测的h2_hpack.v验证）、qpack_huffman_table.v+qpack_huffman.v（RFC 9204 §4.1.2 强制逐字节复用 RFC 7541 Appendix B 的表，复制已验证实现比二次手抄更安全，拷贝经数值 diff 逐字节确认）、qpack_static_table.v（99 条全部从 RFC 文本转写，与 HPACK 61 条表从 1 索引不同，从 0 索引）、qpack_dynamic_table.v（插入/驱逐/复制/容量，absolute/relative-from-insert-count/relative-from-Base/post-Base 索引作为 4 个不同的解析函数——最易转写错误点；引用计数保护驱逐）、qpack_stream_type.v（0x02/0x03 识别 +QpackStreamRegistry各至多一个追踪器）、qpack_settings.v（从已解码[]H3Setting纯提取 2 个 QPACK SETTINGS）、qpack_encoder_instructions.v+qpack_decoder_instructions.v（4 种编码器流 + 3 种解码器流指令的线上编解码）、qpack_field_line.v（Required Insert Count 回绕数学 + Base 符号/差值数学，直接转写 RFC 伪代码，外加 6 种字段行表示类型）、qpack_encoder.v（QpackEncoder驱动，选择 RFC 提供的 “仅引用已确认条目” 策略，永无阻塞流风险）、qpack_decoder.v（QpackDecoder驱动——阻塞字段段检测、无效引用拒绝、每次插入后发出 Insert Count Increment 作为确认策略）。

验证按置信度排序：（1）转写期间即手工推导 RFC 9204 Appendix B 全部 5 个算例的每一字节，独立复现 RFC 中间值（Set Dynamic Table Capacity 的 220 三字节编码、动态表 Size 累计 106/160/217/215）；（2）把确切字节序列写成 qpack_appendix_b_test.v 端到端测试，B.1-B.4 直接通过，B.5 唯一失败正确诊断为测试设计问题（要求自研编码器复现 RFC 刻意非最优的裸字符串选择，而encode_prefixed_string正确选择了更短的 Huffman 编码）而非绕过；（3）手写逐文件边界测试并重新推导编码器索引数学，抓到三个真实 bug：字段段编码对新插入条目混用 relative-vs-post-Base 索引上下文、Insert-With-Name-Reference 指令的相对索引用了插入后而非插入前的insert_count()（差一错误）、字面量引用已有动态名处直传绝对索引而要求 Base 相对索引。全套net.quic52/52 文件全绿，Phases 0-10 零回归。

Phase 12 — HTTP/3 客户端接线（12a/12b/12c/12d）

• 12a：对已合并的 Phase 9 代码做外科手术式增补（conn.v/tls13_handshake.v）：协商 ALPN 访问器（握手期间已计算但此前被丢弃）、对端发起流发现的peer_stream_opened事件、stream_recv_status查询。无新文件。
• 12b：HTTP/3 + QPACK 连接接线，纯module quic：h3_conn.v 用 control 流/QPACK 流驱动包装QuicConn，请求流消息帧状态机（RFC 9114 §4.1），以及此前完全缺失的阻塞 HEADERS 重试/重排队机制。无需 socket 即可夹具测试。
• 12c：UDP 传输 +H3MuxConn线程接线，module http（h3_udp_dial.v、h3_mux_conn.v）：仓库首个 UDP socket 代码、首个后台线程驱动非线程安全poll()状态机的代码。net.quic自身的QuicConn/H3Conn保持单线程调用方驱动不变；H3MuxConn的驱动线程就是“调用方”，与H2MuxConn后台读线程对H2Conn的关系相同。只需一把锁（qmu），因为只有驱动线程触碰h3/传输——请求线程经do()/PendingH3Request排队并在自己的条件变量上阻塞。
• 12d：Transport/Request/Response集成：req.enable_http3显式选择（默认false，无自动 h2/h1 回退）、h3_client.v（H3ClientRequest/H3ClientResponse转换）、transport_h3.v（h3_round_trip、H3DialCallsingleflight 拨号）。Version增加v3_0用例，使resp.version()对 h3 响应返回有意义的值而非.unknown。

v1 已知限制（在/vreview期间发现并文档化）：net.quic的 TLS 1.3 栈完全没有 OS/默认信任库回退（不同于 h1/h2 的ssl.SSLConn路径），因此req.verify今天对 HTTP/3 实际上是必需的，不设置则每个 h3 请求都会对每个真实服务器证书验证失败；req.validate（跳过验证）与req.cert/req.cert_key（双向 TLS）在 h3 路径上同样不可用。这些都在enable_http3的 doc comment（request.v、http.v）中显著记录。

对抗性验证：7 个跨子阶段真实 bug

Phase A 用 5 个独立审视视角（rfc/concurrency/pool-lifecycle/error-edges/holistic）的多 Agent 工作流审阅 12a-12d 合并 diff，找到 7 个每个子阶段自己的/vreview都漏掉的真实 bug（全是跨子阶段交互缺口）：

1. 新连接首请求竞态：驱动循环在当次迭代读取/轮询线路前就清空c.pending，新连接首个请求会撞上STREAM_LIMIT（对端传输参数未学到）或 “QPACK encoder stream not open yet”——修复为h3_do_on_fresh_conn（有界同连接重试）。
2. RFC 9114 §5.2 GOAWAY draining 从未实现：.goaway分支只禁止新接入，从不读取goaway_id或按边界失败已打开流——修复为遍历c.streams失败所有id >= boundary的流（与 H2 完全对齐），start_request也增加goaway_received检查。
3. H3_REQUEST_REJECTED（§8.1）不可重试：.request_error分支对每个错误码硬编码retryable = false，与 H2 的REFUSED_STREAM对等检查不符——已修复。
4. 孤儿池化连接泄漏：被取代连接的清理只调orphan.release()从不调orphan.shutdown_when_idle()，而H3MuxConn.release()对拆除是文档化的 no-op——驱动线程 + UDP socket 泄漏到进程结束。
5. 自行终止的连接从不移出池：H3MuxConn无法告知Transport它自行死亡（空闲超时、致命 UDP 错误），死条目留在t.h3_conns中，空闲驱逐扫描可能把死连接误当空闲连接驱逐——用可选on_retired回调修复（镜像 H2 模式但 nil 容忍）。
6. 对端控制错误码可能与可重试哨兵冲突：QUIC RESET_STREAM 错误码是完整 62 位 varint，收窄为int可能恰好产生h3_err_retryable_code，导致被服务端显式拒绝的非幂等请求被静默重放——修复为只信任正的int()结果。
7. 无界每连接内存增长：H3Conn.request_streams/request_decoders在请求结束后从不修剪，随长寿命池化连接累计——两个 map 均在成功/失败路径中修剪。

另有两条经项目自身后续复审发现：RFC 9110 §15.2 缺口——请求流消息帧状态机完全没有 1xx 信息性响应概念，103-then-200序列会把 103 当作最终状态并把真正的 200 字段误投为尾部（修复于 h3_request_stream.v/h3_conn.v：.awaiting_response_headers→.in_body相位转换延迟到解码出的:status确认非 1xx 之后）；以及wait_response中:status伪头验证缺口（无长度/重复/顺序/未知伪头检查），已对齐h2_mux_conn.v。

两项无响应的范围决策按低风险默认推进：服务端推送在 v1 永久禁用（从不发送 MAX_PUSH_ID 意味着按 §7.2.7 推送永未授权，任何收到的 PUSH_PROMISE/CANCEL_PUSH 一律H3_ID_ERROR拒绝）；enable_http3无自动 h2/h1 回退（UDP 没有 TCP 关闭端口那样的快速失败信号，自动对所有https://请求竞速 h3 会拖累常规场景）。

生效中的范围决策

• 客户端优先，服务端是后续阶段（Phase 1-9 设计为无需返工即可支持，role字段已存在）。
• 拥塞控制选 NewReno，非 CUBIC。
• 0-RTT 推迟。
• 单线程、调用方驱动事件循环（poll()/process_timeouts()），非每连接后台线程——匹配 V 缺乏原生异步 I/O 以及 QUIC 一 socket 多连接按 CID 分流的模型。
• 服务器支持（Phase 13 条目）与 0-RTT（条目 14）明确排除在承诺范围之外。

在 net.http 中使用 HTTP/3

HTTP/3 是完全显式选择的能力，需要两个条件同时满足：

1. 编译期：以-d http3构建，否则 QUIC/TLS/QPACK 栈不会编入普通net.http构建（避免其编译期开销），enable_http3请求会快速失败并报 “not compiled in” 错误（见 transport_h3_notd_http3.v）。
2. 运行期：在Request上设置req.enable_http3 = true（仅对https://URL 生效；对http://忽略；默认false且永不自动探测/回退）。

import net.http fn main() { // 注意：v1 的 h3 路径要求显式验证证书（无默认信任库回退） resp := http.fetch( url: 'https://example.com/' enable_http3: true verify: true ) or { panic(err) } println(resp.version()) // http/3 println(resp.body) }

连接池集成把h3_conns/h3_dial_id作为第三个池折叠进既有共享空闲驱逐扫描（transport.v），且enable_http3折叠进连接池键，使同一源站点的 h3 与非 h3 请求永不冲突（transport_h3_test.v 有专门断言）。

验证工作流（每个新阶段适用）

文档最后给出了每次提交前必须执行的四步验证流程：

1. 用./vnew（而非./v）构建并跑全部测试；
2. 每个新文件配套一个_test.v；
3. 提交前对 diff 跑/vreview——目前每个阶段都抓到过真实 bug（新文件必须全文阅读，不能只看 diff）；
4. 提交前用./vnew fmt -w <file>格式化。

贯穿全文的审查纪律值得总结：边界值测试抓 u64 下溢与整数截断、双源验证抓测试向量转写错误（RFC 页面页脚文本 “20”/“19” 被解析成合法十六进制对）、对规范 MUST 的逐条落实而非依赖 diff 审查、以及 “先重述契约再写测试” 的高产出检查方式——这正是本模块 12 个阶段、数十个文件、每个文件独立单元测试仍能保持 52/52 全绿的方法论根基。

【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in <1s with zero library dependencies. Supports automatic C => V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v