Endpoint层架构设计 - 单个连接的微观宇宙

概述

Endpoint层是协议栈中负责处理单个、独立、可靠连接的核心引擎。如果说Socket层是管理所有连接的“机场塔台”，那么每个Endpoint实例就是一个正在执行飞行任务的“独立飞机”。它在一个专属的异步任务(tokio::task)中运行，拥有自己完整的状态机、可靠性机制和拥塞控制算法，从而实现了连接之间的完全隔离。

核心使命:

连接隔离: 在独立的异步任务中管理单个连接，确保任何一个连接的失败或延迟都不会影响其他连接。
协议逻辑实现: 完整实现协议的状态机（连接建立、关闭、迁移）、可靠性传输（ARQ、SACK）和拥塞控制。
数据流管理: 负责将用户Stream的字节流分割成数据包（PUSH帧）发送，并将接收到的数据包重组为有序的字节流，供用户读取。
与Socket层协作: 作为Socket层的“工作单元”，接收Socket层分派的网络帧，并将待发送的数据包提交给Socket层。

架构实现:

主结构体: src/core/endpoint.rs - Endpoint的顶层结构体，整合了所有子模块。
核心逻辑: src/core/endpoint/core/ - 实现了事件驱动的主循环和数据发送逻辑。
生命周期: src/core/endpoint/lifecycle/ - 管理连接状态机的创建、转换和验证。
事件处理: src/core/endpoint/processing/ - 高性能的模块化事件处理引擎，将网络帧分派给专门的处理器。
时间管理: src/core/endpoint/timing.rs - 统一管理所有超时和定时事件。
类型定义: src/core/endpoint/types/ - 定义了Endpoint内部使用的所有核心数据结构。

设计原则

Endpoint的设计围绕着**“单一所有权下的Actor模型”**构建，确保了其在高并发场景下的健壮性和高性能。

1. 单一所有权的Actor模型

无锁化: Endpoint的所有状态，包括ReliabilityLayer、CongestionControl、连接状态、缓冲区等，都由一个独立的Tokio任务拥有和管理。
消息驱动: Endpoint通过异步通道(mpsc)接收来自Socket层（网络帧）和用户Stream（StreamCommand）的消息。所有外部交互都是通过消息传递完成的，避免了直接方法调用和状态共享。
状态隔离: 每个Endpoint实例都是一个自包含的、隔离的“微服务”。这种设计从根本上消除了连接之间的状态竞争，简化了并发管理。

2. 精细化的模块职责划分

高内聚: Endpoint的内部逻辑被清晰地划分为core, lifecycle, processing, timing, types等模块。每个模块都聚焦于一个特定的领域（如lifecycle只关心状态机，processing只关心事件处理）。
低耦合: 模块间通过明确的API或trait进行交互，降低了耦合度。例如，processing模块通过ProcessorOperations trait与Endpoint的主体逻辑解耦，使其可以独立测试和演进。

3. 分层协议栈的实现

Endpoint内部实现了一个小型的、分层的协议栈，清晰地分离了不同层次的职责。

graph TD
    subgraph "端点"
        A["面向用户的逻辑<br>(流API适配)"]
        B["连接生命周期管理<br>(`lifecycle`模块)"]
        C["事件处理与分发<br>(`processing`模块)"]
        D["可靠性与拥塞控制<br>(`ReliabilityLayer`)"]
    end

    A --> B
    B --> C
    C --> D

    style A fill:#333,color:#fff
    style B fill:#333,color:#fff
    style C fill:#333,color:#fff
    style D fill:#333,color:#fff

应用层逻辑: 负责将Stream的字节流接口与ReliabilityLayer的面向数据包的接口进行适配。
生命周期层: 管理连接的宏观状态（建立、关闭等）。
事件处理层: 负责根据当前状态处理具体的网络事件。
可靠传输层: 负责数据的可靠性（ARQ）、排序、流量控制和拥塞控制。

整体架构与数据流

Endpoint作为Socket层和ReliabilityLayer之间的关键桥梁，其内部数据流清晰而高效。

graph TD
    subgraph "套接字层"
        A[套接字事件循环] -- "帧入" --> B(通道管理器)
        B -- "帧批次出" --> A
    end

    subgraph "用户应用"
        C[流API] -- "流命令入" --> E(通道管理器)
        E -- "重组字节流出" --> C
    end

    subgraph "端点任务"
        B -- "帧" --> D{端点事件循环}
        E -- "流命令" --> D

        D -- "处理事件" --> F[处理模块]
        F -- "使用" --> G[生命周期模块]
        F -- "使用" --> H[可靠性层]
        
        D -- "打包并发送" --> H
        H -- "重组" --> D
        D -- "发送给用户" --> E

        D -- "检查超时" --> I[计时模块]
        I -- "唤醒时间" --> D
    end
    
    style A fill:#333,color:#fff
    style B fill:#333,color:#fff
    style C fill:#333,color:#fff
    style D fill:#333,color:#fff
    style E fill:#333,color:#fff
    style F fill:#333,color:#fff
    style G fill:#333,color:#fff
    style I fill:#333,color:#fff
    style H fill:#8B008B,color:#fff,stroke:#fff,stroke-width:2px

数据流解读:

入站数据流 (网络 -> 用户):
1. Socket层将收到的UDP包解析成Frame，通过ChannelManager发送给对应的Endpoint任务。
2. Endpoint的EventLoop收到Frame，交由Processing模块处理。
3. PushProcessor将数据载荷交给ReliabilityLayer的ReceiveBuffer进行排序、去重和缓存。
4. EventLoop在事件处理后，调用ReliabilityLayer的reassemble方法，从ReceiveBuffer中提取出有序的字节流。
5. 这些有序的字节流通过ChannelManager发送给用户Stream，完成read()操作。
出站数据流 (用户 -> 网络):
1. 用户调用Stream的write()方法，Stream将其封装成一个StreamCommand::SendData消息，通过ChannelManager发送给Endpoint任务。
2. EventLoop收到该命令，将数据块写入ReliabilityLayer的SendBuffer。
3. 在事件处理后，EventLoop调用packetize_and_send方法。
4. 该方法从SendBuffer中取出数据，将其分割成PUSH帧，并与可能存在的ACK等控制帧一起，通过core模块的PacketBuilder聚合成符合MTU的数据包。
5. 最终的数据包(FrameBatch)通过ChannelManager发送给Socket层，由其统一发送到网络。

与其他层的交互

与Socket层的关系:
- 父子关系: Socket层是Endpoint的创建者和管理者。它负责监听网络端口、解析入站数据包，并将Frame路由到正确的Endpoint实例。
- 通信: 两者之间完全通过mpsc通道进行异步通信。Endpoint对Socket层是“盲”的，它只知道通过通道发送和接收消息，实现了完全的解耦。
与ReliabilityLayer的关系:
- 引擎与策略: Endpoint是执行引擎，而ReliabilityLayer是核心的可靠性策略实现。
- 调用关系: Endpoint的Processing模块在处理网络帧时，会调用ReliabilityLayer的方法来更新其内部状态（例如，收到ACK时更新RTT和拥塞窗口）。同时，Endpoint的EventLoop也会调用ReliabilityLayer来获取待发送的数据和检查RTO。
- 所有权: 每个Endpoint实例拥有一个独立的ReliabilityLayer实例，确保了不同连接的可靠性计算（RTT、拥塞窗口等）互不干扰。

总结

Endpoint是本协议栈实现并发连接的核心所在。通过将每个连接封装为一个独立的、自包含的、由消息驱动的Actor，项目成功地构建了一个无需显式锁、易于推理且高度可扩展的并发模型。其内部精细的模块划分，将复杂的状态机、事件处理和时间管理逻辑分解为简单、内聚的组件，共同构成了一个健壮而高效的单连接处理引擎。

Keyboard shortcuts

kestrel-protocol