跳转至

调度内核

本文引用的文件
- kernel.v - pipeline.v - adapter.v - context.v - exchange.v - http.v - relay.v - fixed_response_adapter.v - reject_adapter.v - relay_delivery_adapter.v - runtime_services.v - http_ingress_runtime.v - http_pipeline_runtime.v

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件系统性阐述 VHTTPD 的“调度内核”工作原理，覆盖从请求进入、匹配路由、构建交换上下文、执行管道与中间件、到最终通过适配器统一输出（HTTP、WebSocket、流式响应、中继投递等）的完整流程。重点说明： - 请求调度的端到端流程与控制流 - 管道处理机制与中间件注册、能力校验与执行顺序 - 上下文传递机制与数据交换模型（Exchange） - 适配器模式在调度中的应用与协议统一 - 关键数据结构与复杂度分析 - 流程图与类图帮助开发者理解内部机制

项目结构

调度内核位于 src/dispatch 模块，围绕“入站入口 → 管道编排 → 终端适配器”的统一抽象展开；HTTP 与中继等上层运行时负责将外部协议转换为统一的 Exchange 并驱动调度。

graph TB
subgraph "调度内核"
A["Ingress(入口)"] --> B["Pipeline(管道)"]
B --> C["Transforms(中间件)"]
B --> D["Egress(终端适配器)"]
E["Exchange(交换上下文)"] --- B
F["RuntimeServices(运行时服务)"] --- B
end
subgraph "HTTP 集成"
H1["HTTP 入站运行时"] --> H2["HTTP 管道运行时"]
H2 --> A
H2 --> D
end
subgraph "中继集成"
R1["Relay 入站"] --> A
R1 --> D
end

图表来源 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - http.v:20-46 - relay.v:24-59

章节来源 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - http.v:20-46 - relay.v:24-59

核心组件

  • 交换上下文 Exchange：承载一次处理的身份、元数据、负载与生命周期信息，是调度内核的数据总线。
  • 管道 PipelineDescriptor：声明 ingress、transforms、policies、egress 以及所需 Capabilities。
  • 中间件 Transformer：可插拔的处理单元，返回 TransformAction 控制继续、响应、转发、扇出、拒绝或丢弃。
  • 终端适配器 EgressAdapter：实现 deliver 将结果交付给具体协议（HTTP、WS、流、中继等）。
  • 运行时服务 RuntimeServices：提供 trace_id、事件发射等横切能力。
  • 上下文构造器：针对不同入站（HTTP、WebSocket、MCP、Stream、Relay）将外部请求映射为 DispatchContext 与 Exchange。

章节来源 - exchange.v:78-104 - exchange.v:147-159 - pipeline.v:3-12 - pipeline.v:114-118 - adapter.v:129-136 - runtime_services.v:1-17 - context.v:1-66

架构总览

调度内核以 Exchange 为中心，将不同协议的入站请求标准化为统一的数据模型，经由管道与中间件处理后，由终端适配器完成协议无关的输出。

sequenceDiagram
participant Client as "客户端"
participant HTTPIngress as "HTTP 入站运行时"
participant PipeRT as "HTTP 管道运行时"
participant Kernel as "调度内核(Exchange/Pipeline)"
participant Adapter as "终端适配器(Egress)"
Client->>HTTPIngress : "HTTP 请求"
HTTPIngress->>PipeRT : "选择引擎/管线"
PipeRT->>Kernel : "构建 Exchange(来自 HttpIngressRequest)"
Kernel->>Kernel : "按 transforms 顺序执行中间件"
Kernel-->>PipeRT : "TransformAction(继续/响应/拒绝...)"
PipeRT->>Adapter : "deliver(exchange)"
Adapter-->>Client : "HTTP 响应/文件/接受事件/流计划/会话计划/中继投递/失败"

图表来源 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - http.v:20-46 - adapter.v:129-136

详细组件分析

交换上下文与数据模型

  • ExchangeIdentity：包含 id、request_id、trace_id、parent_id，贯穿全链路追踪。
  • ExchangeKind：定义 request/response/event/stream_open/stream_chunk/stream_end/session_open/session_message/session_close/error 等语义。
  • Payload 联合类型：EmptyPayload/ErrorPayload/EventPayload/RequestPayload/ResponsePayload/SessionPayload/StreamPayload，承载各阶段数据。
  • Exchange：聚合 identity、kind、ingress、pipeline、时间戳、headers、metadata、payload，作为调度内核唯一数据载体。
classDiagram
class ExchangeIdentity {
+string id
+string request_id
+string trace_id
+string parent_id
}
class Exchange {
+ExchangeIdentity identity
+ExchangeKind kind
+string ingress
+string pipeline
+i64 created_at_ms
+i64 deadline_at_ms
+map~string,string~ headers
+map~string,string~ metadata
+ExchangePayload payload
}
class RequestPayload {
+string method
+string path
+map~string,string~ query
+string body
+string remote_addr
}
class ResponsePayload {
+int status
+string body
}
class EventPayload {
+string topic
+string name
+string data
+map~string,string~ metadata
}
class StreamPayload {
+string session_id
+string chunk
+string reason
}
class SessionPayload {
+string session_id
+string message
+[]string rooms
}
class ErrorPayload {
+string message
+string error_class
+int status
}
Exchange --> ExchangeIdentity : "包含"
Exchange --> RequestPayload : "payload"
Exchange --> ResponsePayload : "payload"
Exchange --> EventPayload : "payload"
Exchange --> StreamPayload : "payload"
Exchange --> SessionPayload : "payload"
Exchange --> ErrorPayload : "payload"

图表来源 - exchange.v:3-22 - exchange.v:24-68 - exchange.v:78-90

章节来源 - exchange.v:3-22 - exchange.v:24-68 - exchange.v:78-90

管道与中间件

  • PipelineDescriptor：声明 id、group、ingress、transforms、policies、egress、required Capabilities。
  • TransformDescriptor：声明 id、kind、handler、capabilities。
  • TerminalDescriptor：声明 id、capabilities。
  • 能力校验：capabilities_satisfy/missing_capabilities/pipeline_capability_errors/issues 确保 ingress 能力满足 pipeline 需求。
  • PipelineDispatcher：定义 dispatch(services, exchange) -> DeliveryOutcome 的接口。
flowchart TD
Start(["开始"]) --> Build["构建 PipelineDescriptor"]
Build --> Validate["校验 Ingress 能力是否满足 Required"]
Validate --> |不满足| Report["生成能力缺失错误列表"]
Validate --> |满足| Execute["按 transforms 顺序执行中间件"]
Execute --> Action{"TransformAction 类型?"}
Action --> |continue_pipeline| Next["继续下一个中间件"]
Action --> |respond| Respond["直接响应(状态码)"]
Action --> |forward| Forward["转发到目标"]
Action --> |fanout| Fanout["扇出到多个目标"]
Action --> |reject| Reject["拒绝(状态+错误)"]
Action --> |drop| Drop["丢弃请求"]
Next --> Action
Respond --> End(["结束"])
Forward --> End
Fanout --> End
Reject --> End
Drop --> End

图表来源 - pipeline.v:3-12 - pipeline.v:14-26 - pipeline.v:44-55 - pipeline.v:57-90 - pipeline.v:92-112 - exchange.v:106-123

章节来源 - pipeline.v:3-12 - pipeline.v:14-26 - pipeline.v:44-55 - pipeline.v:57-90 - pipeline.v:92-112 - exchange.v:106-123

上下文传递机制

  • 针对 WebSocket Upstream、Stream、MCP、WebSocket Frame 等不同入站，提供专用函数将 transport 层请求转换为 DispatchContext，并携带 session、payload、metadata、event 等信息。
  • 这些上下文随后用于构建 Exchange，保证跨协议一致的数据访问。
sequenceDiagram
participant WSU as "WebSocket Upstream"
participant ST as "Stream"
participant MCP as "MCP"
participant WSF as "WebSocket Frame"
participant Ctx as "DispatchContext 构造器"
participant Ex as "Exchange"
WSU->>Ctx : "WorkerWebSocketUpstreamDispatchRequest"
ST->>Ctx : "StreamDispatchRequest"
MCP->>Ctx : "WorkerMcpDispatchRequest"
WSF->>Ctx : "WorkerWebSocketFrame"
Ctx-->>Ex : "session/payload/metadata/event"

图表来源 - context.v:8-15 - context.v:17-32 - context.v:34-49 - context.v:51-65

章节来源 - context.v:8-15 - context.v:17-32 - context.v:34-49 - context.v:51-65

适配器模式与协议统一

  • EgressAdapter 接口定义了 deliver(services, exchange) -> DeliveryOutcome，屏蔽协议差异。
  • 内置适配器：
  • FixedResponseAdapter：固定响应。
  • RejectAdapter：拒绝响应（带状态码与错误分类）。
  • RelayDeliveryAdapter：将请求投递至中继系统，支持 completion_mode、timeout、route 等元数据注入。
  • DeliveryOutcome 统一描述 response/file/accepted_event/stream_plan/session_plan/relay_delivery/failure 等结果形态。
classDiagram
class EgressAdapter {
+id() string
+capabilities() Capabilities
+warmup(services) !void
+deliver(services, exchange) !DeliveryOutcome
+close() void
}
class FixedResponseAdapter {
+name string
+status int
+headers map~string,string~
+body string
}
class RejectAdapter {
+name string
+status int
+error string
+error_class string
}
class RelayDeliveryAdapter {
+name string
+target string
+completion_mode string
+timeout_ms int
+metadata map~string,string~
}
class DeliveryOutcome {
+DeliveryOutcomeKind kind
+int status
+map~string,string~ headers
+string body
+string path
+string target
+string error
+string error_class
+map~string,string~ metadata
}
EgressAdapter <|.. FixedResponseAdapter
EgressAdapter <|.. RejectAdapter
EgressAdapter <|.. RelayDeliveryAdapter
EgressAdapter --> DeliveryOutcome : "返回"

图表来源 - adapter.v:129-136 - adapter.v:27-38 - fixed_response_adapter.v:1-45 - reject_adapter.v:1-45 - relay_delivery_adapter.v:1-110

章节来源 - adapter.v:129-136 - adapter.v:27-38 - fixed_response_adapter.v:1-45 - reject_adapter.v:1-45 - relay_delivery_adapter.v:1-110

HTTP 入站到管道执行流程

  • HTTP 入站运行时根据配置选择引擎与管线，必要时进行缓存命中判断与后端切换。
  • 管道运行时将 HttpIngressRequest 转换为 Exchange，调用调度内核执行 transforms，并根据 TransformAction 决定后续动作（如直接响应、调用 provider action、或渲染终端适配器）。
sequenceDiagram
participant HTTP as "HTTP 入站"
participant PR as "管道运行时"
participant K as "调度内核"
participant A as "终端适配器"
HTTP->>PR : "HttpIngressRequest"
PR->>K : "构建 Exchange"
K->>K : "执行 transforms"
K-->>PR : "TransformAction"
alt "直接响应"
PR-->>HTTP : "response_outcome(...)"
else "调用 Provider Action"
PR->>A : "deliver(exchange)"
A-->>PR : "DeliveryOutcome"
PR-->>HTTP : "delivery_outcome(...)"
end

图表来源 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - http.v:20-46 - adapter.v:40-47

章节来源 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - http.v:20-46 - adapter.v:40-47

流式与中继投递

  • 流式调度：通过 build_stream_open_request/build_stream_next_request/build_stream_close_request 构造 StreamDispatchRequest，并在 kernel 中封装为统一格式。
  • 中继投递：RelayDeliveryAdapter 将 Exchange 中的请求体、查询参数、路由信息等注入到 metadata，并返回 relay_delivery_outcome_with_completion，支持 completion_mode 与 timeout。
flowchart TD
SOpen["open 事件"] --> BuildReq["构建 StreamDispatchRequest"]
BuildReq --> Dispatch["调度内核分发"]
Dispatch --> Next["next 事件(携带 state)"]
Next --> Dispatch
Dispatch --> Close["close 事件(携带 reason)"]
Close --> End(["结束"])

图表来源 - kernel.v:30-46 - kernel.v:48-64 - kernel.v:66-77 - relay_delivery_adapter.v:38-74

章节来源 - kernel.v:30-46 - kernel.v:48-64 - kernel.v:66-77 - relay_delivery_adapter.v:38-74

依赖关系分析

  • 调度内核对上游 transport 与 executor 存在依赖，用于构造上下文与错误分类。
  • HTTP 与中继运行时依赖调度内核提供的 Exchange 与适配器接口，形成松耦合的协议适配层。
graph LR
T["transport(上游)"] --> K["调度内核(kernel.v)"]
X["executor(执行器)"] --> K
H["HTTP 入站/管道运行时"] --> K
R["Relay 入站"] --> K
K --> A["EgressAdapter(终端适配器)"]

图表来源 - kernel.v:1-10 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - relay.v:24-59

章节来源 - kernel.v:1-10 - http_ingress_runtime.v:111-122 - http_pipeline_runtime.v:128-161 - relay.v:24-59

性能考量

  • 中间件链长度与复杂度直接影响延迟，建议将轻量校验前置、重计算后置。
  • Exchange 的 headers/metadata 使用 map[string]string，频繁拷贝可能带来开销，建议在必要处复用或最小化字段。
  • 管道能力校验在启动时完成，避免运行时分支判断。
  • 流式场景下，state 传递应避免过大对象，保持增量更新。

[本节为通用指导，无需源码引用]

故障排查指南

  • 传输错误分类：kernel 提供 transport_failure/classify_transport_error 将底层错误映射为统一的状态码与错误分类，便于定位问题。
  • 管道能力不匹配：pipeline_capability_errors/issues 会列出缺失的能力项，检查 ingress 与 pipeline.required 的配置一致性。
  • 终端适配器失败：DeliveryOutcome.kind=failure 时，关注 status、error、error_class 字段，结合 trace_id/request_id 进行链路追踪。

章节来源 - kernel.v:22-28 - kernel.v:148-150 - pipeline.v:97-112 - adapter.v:120-127

结论

VHTTPD 调度内核以 Exchange 为核心，通过 Pipeline 与 Transformer 实现可插拔的中间件编排，并以 EgressAdapter 统一输出多种协议。该设计使 HTTP、WebSocket、流式响应与中继投递在同一套调度框架内得到一致处理，具备良好的扩展性与可观测性。

[本节为总结，无需源码引用]

附录

  • 关键数据结构速查
  • Exchange：统一上下文载体，含 identity、kind、ingress、pipeline、时间戳、headers、metadata、payload。
  • TransformAction：控制中间件行为（继续、响应、转发、扇出、拒绝、丢弃）。
  • DeliveryOutcome：统一输出结果（响应、文件、接受事件、流计划、会话计划、中继投递、失败）。
  • Capabilities：描述入站与管道的能力集合，用于启动期校验。

章节来源 - exchange.v:78-104 - exchange.v:106-123 - adapter.v:27-38 - pipeline.v:3-12