协议栈核心组件架构概览

本文档旨在为开发者提供一个关于本可靠UDP协议栈核心组件的全局视角。我们将自顶向下地剖析协议栈的每一层，阐明其设计理念、核心职责以及各层之间的交互关系。

分层架构模型

本协议栈采用了一个清晰、解耦的六层架构模型。每一层都专注于一个特定的领域，并通过明确定义的接口与相邻层进行通信。这种设计不仅降低了系统的复杂性，也极大地增强了代码的可维护性、可测试性和可扩展性。

graph TD
    A["用户应用"]
    
    subgraph "协议栈"
        direction TB
        L1["流API层<br>(stream.rs)"]
        L2["连接管理层<br>(socket/)"]
        L3["单连接状态机<br>(endpoint/)"]
        L4["可靠传输协议层<br>(reliability/)"]
        L5["UDP I/O层<br>(transport/)"]
        L6["数据序列化层<br>(packet/)"]
        L7["全局定时器系统<br>(timer/)"]
    end
    
    B["操作系统<br>UDP套接字"]

    A -- "read()/write()" --> L1
    L1 -- "StreamCommand" --> L3
    L2 -- "管理" --> L3
    L2 -- "路由帧至" --> L3
    L3 -- "使用" --> L4
    L3 -- "使用" --> L7
    L3 -- "提交FrameBatch至" --> L2
    L2 -- "发送FrameBatch" --> L5
    L4 -- "使用" --> L6
    L5 -- "收发UDP数据报" --> B
    L5 -- "调用L6解析帧" --> L6
    L6 -- "定义线路格式" --> B
    L7 -- "提供定时器服务" --> L3

    style A fill:#333,color:#fff
    style B fill:#333,color:#fff
    classDef layer fill:#333,color:#fff,stroke:#fff,stroke-width:1px;
    class L1,L2,L3,L4,L5,L6,L7 layer;

各层详细解析

1. 用户接口层 (`Stream`)

文档: 用户接口 (Stream)
核心职责: 提供面向用户的、符合人体工程学的API。
实现: Stream结构体实现了标准的tokio::io::AsyncRead和AsyncWrite trait，使得开发者可以像使用TcpStream一样轻松地进行字节流读写。它将所有I/O操作转换为StreamCommand消息，通过异步通道与底层的Endpoint任务解耦。

2. 连接管理层 (`Socket`)

文档: Socket层架构设计
核心职责: 协议栈的“大脑”和“事件中枢”，管理所有连接的生命周期。
实现: Socket层采用Actor模型，在SocketEventLoop中统一处理所有外部事件（新连接请求、网络数据包）。其核心是FrameRouter，它维护着ConnectionId -> Endpoint和SocketAddr -> ConnectionId的双重映射，能够智能地将网络帧分派给正确的Endpoint实例，并原生支持连接迁移（NAT穿透）。

3. 端点状态机层 (`Endpoint`)

文档: Endpoint层架构设计
核心职责: 单个连接的“微观世界”，是协议核心逻辑的执行单元。
实现: 每个Endpoint都在一个独立的Tokio任务中运行，拥有自己完整的状态机、缓冲区以及一个ReliabilityLayer实例。这种设计实现了连接间的完全隔离（无锁化），确保任何单个连接的故障或延迟都不会影响到其他连接。它负责驱动连接状态的转换，并协调ReliabilityLayer完成具体的数据收发。

4. 可靠传输协议层 (`Reliability`)

文档: 可靠性层 (reliability)
核心职责: 协议栈的“可靠性引擎”，负责将不可靠的UDP数据包转变为可靠的、有序的数据流。
实现: ReliabilityLayer是本协议ARQ（自动重传请求）和拥塞控制的核心。它聚合了多个关键组件：
- SackManager: 实现基于选择性确认（SACK）的高效重传逻辑和快速重传。
- CongestionControl Trait (Vegas实现): 实现基于延迟的拥塞控制算法，主动避免网络拥塞。
- SendBuffer / ReceiveBuffer: 管理数据的发送缓冲和接收时的乱序重组。
- Packetizer: 将发送字节流分割成符合MTU的PUSH帧。

5. 传输抽象层 (`Transport`)

文档: 传输层架构设计
核心职责: 抽象底层I/O操作，提供高性能的UDP数据包收发能力。
实现: Transport层通过trait定义了一套标准的UDP操作接口，并将发送和接收逻辑解耦到独立的异步任务中。它包含一个专用的批量发送任务 (transport_sender_task)，能自动聚合多个待发送的数据包，在一次系统调用中完成发送，显著提升高吞吐量场景下的性能。同时，它使用ArcSwap原子地管理底层UdpSocket，实现了无锁、安全、运行时的地址重绑定。

6. 数据序列化层 (`Packet`)

文档: 数据包层 (packet)
核心职责: 定义协议的“二进制语言”，负责数据在网络线路上的最终表示。
实现: packet模块定义了统一的Frame枚举，它是协议中所有数据单元（如PUSH, ACK, SYN）的抽象。该模块提供了：
- 长短头分离: LongHeader用于连接管理，ShortHeader用于数据传输，优化头部开销。
- 安全的编解码: 提供Frame::encode和Frame::decode作为唯一的序列化/反序列化入口，内部自动处理大小端、长度计算等细节，保证了协议实现的健壮性。

7. 全局定时器系统 (`Timer`)

文档: 全局定时器系统 (timer)
核心职责: 协议栈的"全局时钟"，提供高性能、可扩展的定时器管理服务。
实现: timer模块采用时间轮（Timing Wheel）算法实现O(1)时间复杂度的定时器操作，通过全局唯一的定时器任务为整个协议栈提供统一的超时管理。该模块包含：
- 时间轮算法: 高效的O(1)定时器添加、取消和到期检查操作。
- 全局任务管理: 单一的全局定时器任务管理所有连接的定时器需求。
- 连接隔离: 虽然使用全局任务，但每个连接的定时器在逻辑上完全隔离。
- 精确控制: 毫秒级精度的定时器，满足协议对精确超时控制的需求。

核心数据流（端到端）

理解数据如何在这些层次间流动，是掌握整个协议栈的关键。

数据发送路径 (用户 -> 网络)

Stream层: 用户调用 stream.write()。
Endpoint层: Stream将数据封装为StreamCommand发送给Endpoint任务。Endpoint将数据存入ReliabilityLayer的SendBuffer。
Reliability层: Packetizer根据拥塞和流量窗口的许可，从SendBuffer中拉取数据，创建PUSH帧。
Timer层: 发送的帧被添加到重传管理器，同时可能触发重传定时器的注册。
Endpoint层: Endpoint收集ReliabilityLayer生成的PUSH帧和ACK帧，聚合成一个FrameBatch。
Socket层: Endpoint将FrameBatch提交给Socket任务。
Transport层: Socket将FrameBatch转发给transport_sender_task进行批量发送。
Packet层: 在transport_sender_task内部，每个Frame通过Frame::encode被序列化成字节流。
网络: Transport层通过UdpSocket将最终的字节流作为UDP数据报发送出去。

数据接收路径 (网络 -> 用户)

Transport层: UdpSocket收到UDP数据报。
Packet层: Transport层的接收任务调用Frame::decode，将字节流反序列化成一个或多个Frame。
Socket层: Transport层将解码后的ReceivedDatagram发送给SocketEventLoop。FrameRouter根据帧头部的连接ID，将Frame路由到正确的Endpoint任务。
Endpoint层: Endpoint任务收到Frame，同时更新接收时间戳。
Timer层: 接收到数据包时，可能触发空闲超时定时器的重置。
Reliability层:
- 如果是PUSH帧，数据被送入ReceiveBuffer进行去重和排序。
- 如果是ACK帧，SackManager会更新在途包列表、计算RTT，并通知Vegas模块调整拥塞窗口。
Endpoint层: Endpoint调用ReliabilityLayer的reassemble方法，从ReceiveBuffer中提取出连续有序的字节流。
Stream层: Endpoint将重组好的字节流通过通道发送给Stream。
用户: 用户的stream.read()调用完成，获得数据。

定时器事件处理路径 (Timer -> Endpoint)

Timer层: 全局定时器任务检测到定时器到期，生成TimerEventData。
Endpoint层: TimingManager接收到定时器事件，通过check_timer_events()返回超时事件列表。
Endpoint层: Endpoint在事件循环中调用check_all_timeouts()，统一处理连接级和可靠性级的超时。
处理分支:
- 空闲超时: 强制关闭连接，返回ConnectionTimeout错误。
- 路径验证超时: 回到Established状态，通知调用者验证失败。
- 重传超时: 重传丢失的数据包，调整拥塞窗口。

总结

本协议栈通过这种高度模块化、职责明确的分层架构，成功地将一个复杂的可靠传输协议分解为一系列易于理解、开发和维护的组件。每一层都专注于解决特定的问题，同时通过现代化的异步编程范式（Actor模型、无锁化、批量处理、全局定时器）实现了高性能和高可靠性的统一。

特别是全局定时器系统的引入，不仅提供了高效的O(1)定时器操作，还通过统一的时间管理避免了每个连接维护独立定时器的开销，大大提升了系统的整体性能和可扩展性。这种设计为构建健壮的网络应用提供了坚实的基础。

Keyboard shortcuts

kestrel-protocol