Struct CanonicalRequest 

pub struct CanonicalRequest {
    pub method: Method,
    pub protocol: Protocol,
    pub transport: Transport,
    pub generation: u64,
    pub deadline_ms: u64,
    pub cancelled: bool,
    pub resource_lease: u64,
    /* private fields */
}

统一规范化请求

所有HTTP协议（HTTP/1.1、HTTP/2、HTTP/3）解析后都生成此结构， 全链路统一使用，避免协议差分攻击。

设计特点

• 零堆分配（小 Body）：Body <= MAX_BODY_LEN 使用栈上固定数组，避免堆分配
• 大 Body 溢出：超过 MAX_BODY_LEN 时使用堆分配（Option<Vec>），保证正确性
• 治理字段：generation、deadline、cancelled、resource_lease

Copy 语义

由于大 Body 场景下引入了 Option<Vec<u8>>，CanonicalRequest 不再是 Copy， 仅保留 Clone。绝大多数小请求 (<= 4KiB body) 的 clone 开销仅为栈数组拷贝。

Fields

method: Method

请求方法

protocol: Protocol

协议类型

transport: Transport

传输层类型

generation: u64

代际号（用于 ChangeSet 版本控制）

deadline_ms: u64

截止时间（毫秒，0 表示无限制）

cancelled: bool

是否已取消

resource_lease: u64

资源租约（令牌数，用于限流/配额）

Implementations

impl CanonicalRequest

pub const fn empty() -> CanonicalRequest

创建空请求

pub fn reset(&mut self)

重置请求（清空所有字段） 用于对象池复用，避免重新创建对象的开销

pub fn set_body(&mut self, body: impl Into<Vec<u8>>)

设置请求 Body

性能设计：

• Body 长度 <= MAX_BODY_LEN：使用栈上缓冲区，零堆分配
• Body 长度 > MAX_BODY_LEN：使用堆分配，保证正确性不截断

pub fn body(&self) -> &[u8]

获取请求 Body 的字节切片（零分配）

pub fn scheme_str(&self) -> &str

获取方案字符串

pub fn set_scheme(&mut self, scheme: &str) -> bool

设置方案（fail-closed）

Returns

• true - 设置成功
• false - 方案超长（拒绝静默截断，不修改原值直接返回 false； 截断会篡改语义，下游必须检查返回值）

pub fn authority_str(&self) -> &str

获取授权主机字符串

pub fn set_authority(&mut self, authority: &str) -> bool

设置授权主机（fail-closed）

Returns

• true - 设置成功
• false - authority 超长（拒绝静默截断，不修改原值直接返回 false）

pub fn path_str(&self) -> &str

获取规范化路径

pub fn path_bytes(&self) -> &[u8]

获取规范化路径的字节切片（零分配）

pub fn set_path(&mut self, path: &str) -> bool

设置规范化路径（fail-closed）

输入为 request target 时，其中的 ? 之后的部分会被拆分到 query 字段 （路由只匹配路径部分；若不拆分，/api?x=1 会作为整体参与路由匹配而被击穿）。 输入不含 ? 时 query 字段保持不变。

Returns

• true - 设置成功
• false - 路径部分超过 MAX_PATH_LEN 或拆分出的 query 超过 MAX_QUERY_LEN（拒绝静默截断，path 与 query 均不修改，原子拒绝）

pub fn query_str(&self) -> &str

获取规范化查询字符串

pub fn set_query(&mut self, query: &str) -> bool

设置规范化查询字符串（fail-closed）

Returns

• true - 设置成功
• false - query 超长（拒绝静默截断，不修改原值直接返回 false）

pub fn header_count(&self) -> u8

获取头部数量

pub fn get_header(&self, idx: usize) -> Option<&CanonicalHeader>

按索引获取头部

pub fn find_header(&self, name: &str) -> Option<&CanonicalHeader>

按名称查找头部（返回第一个匹配，ASCII 大小写不敏感）

HTTP 头部名称按 RFC 7230 §3.2 为大小写不敏感； 大小写敏感查找会被 Host/host 差分击穿，故统一不敏感比较。

pub fn add_header( &mut self, name: &[u8], value: &[u8], ) -> Result<(), &'static str>

添加头部（超过最大数量或字段超长时返回错误）

安全

• 拒绝包含 \r 或 \n 的头部名称和值，防止 HTTP 响应拆分攻击。
• 名称/值超长时 fail-closed 拒绝，禁止静默截断（截断会篡改头部语义）。

pub fn headers_iter(&self) -> &[CanonicalHeader]

迭代所有头部

pub fn cancel(&mut self)

设置已取消

pub fn is_cancelled(&self) -> bool

检查是否已取消

Trait Implementations

impl Clone for CanonicalRequest

fn clone(&self) -> CanonicalRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CanonicalRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for CanonicalRequest

fn default() -> CanonicalRequest

Returns the “default value” for a type.