调度内核设计

本文引用的文件 - src/dispatch/kernel.v - src/dispatch/pipeline.v - src/dispatch/context.v - src/dispatch/adapter.v - src/dispatch/http_match.v - src/dispatch/exchange.v - src/dispatch/runtime_services.v - src/dispatch/plan_projection.v - src/dispatch/adapter_projection.v - src/kernel_dispatch.v - src/executor/types.v - src/upstream/transport/transport_handle.v - src/http_routing_runtime.v - src/pipeline_runtime.v

目录

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

引言

本文件系统性解析 VHTTPD 调度内核（Kernel）的设计与实现，重点覆盖： - 统一分发决策机制：请求路由匹配、执行器模式选择、策略应用流程 - 管道处理架构的分层设计：中间件链、转换器、适配器的协作机制 - 上下文管理系统的状态传递与生命周期控制 - 具体代码示例路径展示请求处理流程、错误分类与异常处理机制 - 性能优化建议与最佳实践指导

项目结构

调度内核围绕“交换模型 + 管道描述 + 适配器/转换器 + 运行时服务”展开。关键模块职责如下： - 交换与上下文：定义统一的 Exchange、Payload、TransformAction、Capabilities 等抽象，以及从不同协议构造 DispatchContext 的工厂方法 - 管道与能力校验：PipelineDescriptor、TransformDescriptor、TerminalDescriptor 及其能力匹配与诊断 - 适配器与出口：EgressAdapter 接口与多种 DeliveryOutcome 类型，用于将处理结果投递到 HTTP、文件、事件、流、会话或中继 - 路由匹配：基于 HTTP 方法的简单匹配与路径/查询/头匹配，支持通配符与前缀/后缀匹配 - 计划投影：将运行时计划（RuntimePlan）映射为管道/适配器/转换器的描述集合，并生成能力校验问题 - 内核入口：将上游传输请求转换为内核信封，委派引擎进行分发；同时提供构建各类请求帧的工具函数 - 运行时管道：HTTP 路由规则编译与匹配、静态资源根、响应缓存、重写目标、策略注入等

graph TB
subgraph "内核与入口"
K["kernel_dispatch.v<br/>内核分发入口"]
KT["executor/types.v<br/>内核信封/上下文"]
end
subgraph "调度抽象"
EX["dispatch/exchange.v<br/>Exchange/Payload/Action/Capabilities"]
CTX["dispatch/context.v<br/>DispatchContext 构造"]
PIPE["dispatch/pipeline.v<br/>Pipeline/Transform/Terminal 描述"]
ADP["dispatch/adapter.v<br/>EgressAdapter/DeliveryOutcome"]
SVC["dispatch/runtime_services.v<br/>RuntimeServices 接口"]
end
subgraph "计划与投影"
PLAN["dispatch/plan_projection.v<br/>计划->描述映射/能力校验"]
ADPP["dispatch/adapter_projection.v<br/>适配器描述/终端适配器"]
end
subgraph "路由与匹配"
HM["dispatch/http_match.v<br/>HTTP 匹配器"]
HR["http_routing_runtime.v<br/>HTTP 路由规则/重写/缓存"]
PR["pipeline_runtime.v<br/>HTTP/Relay 管道运行时"]
end
K --> KT
K --> EX
K --> CTX
K --> PIPE
K --> ADP
K --> SVC
PLAN --> PIPE
PLAN --> ADP
HR --> HM
PR --> HR
PR --> PLAN

图表来源 - src/kernel_dispatch.v:1-154 - src/executor/types.v:266-449 - src/dispatch/exchange.v:78-160 - src/dispatch/context.v:1-66 - src/dispatch/pipeline.v:1-119 - src/dispatch/adapter.v:1-137 - src/dispatch/runtime_services.v:1-17 - src/dispatch/plan_projection.v:1-314 - src/dispatch/adapter_projection.v:1-124 - src/dispatch/http_match.v:1-113 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224

章节来源 - src/kernel_dispatch.v:1-154 - src/dispatch/exchange.v:78-160 - src/dispatch/pipeline.v:1-119 - src/dispatch/adapter.v:1-137 - src/dispatch/http_match.v:1-113 - src/dispatch/plan_projection.v:1-314 - src/dispatch/adapter_projection.v:1-124 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224

核心组件

• 交换模型与动作
• Exchange 承载身份、种类、入站/管道标识、时间戳、头部、元数据与负载
• TransformAction 表达继续管道、直接响应、转发、扇出、拒绝、丢弃等动作
• Capabilities 描述系统对请求/事件/流/会话/多路复用/取消/背压/回放的支持
• 管道与能力约束
• PipelineDescriptor 指定入站、转换器序列、策略、出站及所需能力
• TransformDescriptor/TerminalDescriptor 描述转换器与终结节点的能力需求
• capabilities_satisfy/missing_capabilities 用于能力匹配与缺失诊断
• 适配器与交付结果
• EgressAdapter 负责将 DeliveryOutcome 投递到具体出口（HTTP 响应、文件、事件、流、会话、中继）
• DeliveryOutcome 统一封装状态码、头部、主体、目标、错误与元数据
• 上下文与运行时服务
• DispatchContext 封装会话句柄、负载、元数据与事件类型
• RuntimeServices 提供 trace_id 与 emit 事件能力，NoOpRuntimeServices 作为默认实现
• 计划投影与能力校验
• 将 Listener/Relay/Provider/Adapter/Transform 的计划项映射为描述集
• 校验管道与入站/转换器的能力一致性，输出诊断信息
• HTTP 路由匹配
• HttpMatch 支持方法、Host、路径、Query、Header 的多条件匹配
• http_exchange_matches 将 Exchange 中的 RequestPayload 与匹配器比对
• 运行时管道
• PipelineRuntime 组合 HTTP 路由与 Relay 管道
• HttpRoutingRuntime 提供规则匹配、路径重写、静态根、响应缓存、必要头检查、禁用查询参数检查等

章节来源 - src/dispatch/exchange.v:78-160 - src/dispatch/pipeline.v:1-119 - src/dispatch/adapter.v:1-137 - src/dispatch/context.v:1-66 - src/dispatch/runtime_services.v:1-17 - src/dispatch/plan_projection.v:1-314 - src/dispatch/http_match.v:1-113 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224

架构总览

调度内核以“请求进入 -> 路由匹配 -> 管道编排 -> 适配器投递”为主线，结合能力校验确保链路正确性。

sequenceDiagram
participant Client as "客户端"
participant Kernel as "内核(kernel_dispatch.v)"
participant Plan as "计划投影(plan_projection.v)"
participant Route as "HTTP路由(http_routing_runtime.v)"
participant Pipe as "管道运行时(pipeline_runtime.v)"
participant Adapter as "适配器(adapter.v)"
participant Out as "出口(响应/文件/事件/流/会话/中继)"
Client->>Kernel : "HTTP/WS/MCP/Stream 请求"
Kernel->>Kernel : "构造内核信封/上下文"
Kernel->>Pipe : "分发请求"
Pipe->>Route : "匹配路由规则"
Route-->>Pipe : "命中规则/未命中"
Pipe->>Plan : "获取管道/适配器/转换器描述"
Plan-->>Pipe : "描述集+能力校验"
Pipe->>Adapter : "执行管道并产出 DeliveryOutcome"
Adapter->>Out : "投递结果"
Out-->>Client : "返回响应/建立流/接受事件"

图表来源 - src/kernel_dispatch.v:1-154 - src/dispatch/plan_projection.v:1-314 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224 - src/dispatch/adapter.v:1-137

详细组件分析

统一分发决策机制

• 请求路由匹配
• 使用 HttpMatch 对 Exchange 的 RequestPayload 进行方法、Host、路径、Query、Header 匹配
• 支持通配符、前缀/后缀路径匹配与大小写不敏感的方法匹配
• 执行器模式选择
• 通过运行时规则决定 executor/engine_id，并在管道计划中绑定对应执行器
• 当存在协议级覆盖时，优先采用规则指定的执行器
• 策略应用流程
• 在管道描述中声明 policies，由运行时在执行前/后按序应用
• 能力校验确保入站、转换器、出站均满足所需能力

flowchart TD
Start(["开始"]) --> BuildEx["构造 Exchange 与 DispatchContext"]
BuildEx --> MatchRule["HTTP 路由匹配(HttpMatch)"]
MatchRule --> |命中| SelectExec["选择执行器(engine_id/executor)"]
MatchRule --> |未命中| Fallback["回退默认处理/拒绝"]
SelectExec --> LoadDesc["加载管道/适配器/转换器描述"]
LoadDesc --> ValidateCap["能力校验(caps_satisfy)"]
ValidateCap --> |通过| RunPipe["执行管道(转换器/策略)"]
ValidateCap --> |失败| ReportErr["输出能力不匹配诊断"]
RunPipe --> Deliver["适配器投递(DeliveryOutcome)"]
Deliver --> End(["结束"])
Fallback --> End
ReportErr --> End

图表来源 - src/dispatch/http_match.v:1-113 - src/dispatch/plan_projection.v:1-314 - src/pipeline_runtime.v:1-224 - src/http_routing_runtime.v:1-483

章节来源 - src/dispatch/http_match.v:1-113 - src/dispatch/plan_projection.v:1-314 - src/pipeline_runtime.v:1-224 - src/http_routing_runtime.v:1-483

管道处理架构的分层设计

• 中间件链（Transformers）
• 每个 Transformer 具备 id、capabilities、warmup/transform/close 生命周期
• transform 返回 TransformAction，驱动继续、响应、转发、扇出、拒绝、丢弃等行为
• 转换器与适配器协作
• 转换器关注请求/事件的变换与策略应用
• 适配器关注最终结果的投递（HTTP 响应、文件、事件、流、会话、中继）
• 能力契约
• 入站、转换器、出站均需满足 Capabilities，否则产生 pipeline_capability_mismatch 类问题

classDiagram
class Exchange {
+identity
+kind
+ingress
+pipeline
+headers
+metadata
+payload
}
class TransformAction {
+kind
+target
+targets
+status
+error
+error_class
}
class Transformer {
+id()
+capabilities()
+warmup(services)
+transform(services, exchange)
+close()
}
class EgressAdapter {
+id()
+capabilities()
+warmup(services)
+deliver(services, exchange)
+close()
}
class DeliveryOutcome {
+kind
+status
+headers
+body
+path
+target
+error
+error_class
+metadata
}
Transformer --> Exchange : "读取/修改"
Transformer --> TransformAction : "返回动作"
EgressAdapter --> DeliveryOutcome : "产出结果"

图表来源 - src/dispatch/exchange.v:78-160 - src/dispatch/pipeline.v:1-119 - src/dispatch/adapter.v:1-137

章节来源 - src/dispatch/exchange.v:78-160 - src/dispatch/pipeline.v:1-119 - src/dispatch/adapter.v:1-137

上下文管理系统

• 上下文构造
• 从 WebSocket Upstream、Stream、MCP、WebSocket Frame 等不同协议源构造 DispatchContext
• 包含 SessionHandle、payload、metadata、event 字段，贯穿整个管道
• 生命周期控制
• 通过 TransportHandle 记录协议、提供者、实例、连接状态与端点
• 在 close 阶段可清理资源与状态

sequenceDiagram
participant Ingress as "入站(协议)"
participant Ctx as "上下文(context.v)"
participant Pipe as "管道(pipeline.v)"
participant Adp as "适配器(adapter.v)"
participant Exit as "出口"
Ingress->>Ctx : "构造 DispatchContext"
Ctx->>Pipe : "携带会话/负载/元数据/事件"
Pipe->>Adp : "执行并产出 DeliveryOutcome"
Adp->>Exit : "根据 kind 投递"
Exit-->>Ingress : "完成/关闭/释放"

图表来源 - src/dispatch/context.v:1-66 - src/upstream/transport/transport_handle.v:1-21 - src/dispatch/adapter.v:1-137

章节来源 - src/dispatch/context.v:1-66 - src/upstream/transport/transport_handle.v:1-21

错误分类与异常处理

• 传输层错误分类
• transport_failure/classify_transport_error 将后端错误分类为状态码与错误类别
• 流式分发失败
• stream_failure 将 StreamDispatchResponse 的错误事件转换为内核失败对象
• 管道能力不匹配
• pipeline_capability_issues 输出结构化问题，便于诊断与告警

flowchart TD
A["收到响应/错误"] --> B{"是否为错误事件?"}
B --> |是| C["转换为 KernelStreamDispatchFailure"]
B --> |否| D["正常流程继续"]
C --> E["上报错误类别/状态码"]
E --> F["上层处理/重试/降级"]
D --> G["继续管道执行"]

图表来源 - src/dispatch/kernel.v:12-28 - src/dispatch/plan_projection.v:133-166

章节来源 - src/dispatch/kernel.v:12-28 - src/dispatch/plan_projection.v:133-166

请求处理流程示例（路径参考）

• 内核入口与信封构造
• src/kernel_dispatch.v:9-16
• src/kernel_dispatch.v:30-37
• src/kernel_dispatch.v:58-62
• src/kernel_dispatch.v:83-91
• 上下文构造
• src/dispatch/context.v:17-32
• src/dispatch/context.v:34-49
• src/dispatch/context.v:51-65
• 路由匹配与计划投影
• src/dispatch/http_match.v:12-39
• src/dispatch/plan_projection.v:270-278
• src/http_routing_runtime.v:112-122
• 管道运行时与适配器
• src/pipeline_runtime.v:91-106
• src/dispatch/adapter.v:129-137

章节来源 - src/kernel_dispatch.v:9-91 - src/dispatch/context.v:17-65 - src/dispatch/http_match.v:12-39 - src/dispatch/plan_projection.v:270-278 - src/http_routing_runtime.v:112-122 - src/pipeline_runtime.v:91-106 - src/dispatch/adapter.v:129-137

依赖关系分析

• 内核依赖 executor 与 upstream.transport 的类型与工具
• 调度抽象依赖 runtime_plan 进行计划投影与能力校验
• HTTP 路由依赖 regex 与 transport 工具进行规范化与匹配
• 管道运行时组合 HTTP 路由与 Relay 管道，协调适配器与转换器

graph LR
KD["kernel_dispatch.v"] --> ET["executor/types.v"]
KD --> DT["dispatch/*"]
DT --> RP["runtime_plan"]
HR["http_routing_runtime.v"] --> HM["dispatch/http_match.v"]
PR["pipeline_runtime.v"] --> HR
PR --> DT

图表来源 - src/kernel_dispatch.v:1-154 - src/executor/types.v:1-449 - src/dispatch/plan_projection.v:1-314 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224

章节来源 - src/kernel_dispatch.v:1-154 - src/executor/types.v:1-449 - src/dispatch/plan_projection.v:1-314 - src/http_routing_runtime.v:1-483 - src/pipeline_runtime.v:1-224

性能考量

• 路由匹配优化
• 预编译正则表达式，避免重复编译开销
• 优先使用精确匹配与通配符匹配，减少复杂正则的使用
• 响应缓存
• 启用边缘响应缓存，合理设置 TTL 与 bypass 规则（如 Cookie、Authorization、Cache-Control）
• 针对 GET/HEAD 且无敏感头的请求进行缓存存储
• 管道能力校验
• 启动时完成能力校验与诊断，避免运行期失败
• 适配器与转换器
• 尽量保持转换器幂等与轻量，避免阻塞操作
• 使用扇出与并行策略时需考虑背压与限流

[本节为通用指导，无需特定文件引用]

故障排查指南

• 能力不匹配
• 检查 pipeline_capability_errors/pipeline_transform_capability_errors 的输出，定位缺失能力字段
• 传输错误分类
• 查看 transport_failure/classify_transport_error 的分类结果，确认状态码与错误类别
• 流式分发失败
• 检查 stream_failure 的错误事件与 error_class，必要时进行重试或降级
• 路由未命中
• 核对 HttpMatch 的条件与方法/路径/查询/头是否一致，必要时调整规则或增加通配符

章节来源 - src/dispatch/plan_projection.v:133-166 - src/dispatch/kernel.v:12-28 - src/dispatch/http_match.v:12-39

结论

VHTTPD 调度内核通过统一的交换模型与能力契约，实现了跨协议（HTTP/WS/MCP/Stream）的统一分发与管道化编排。计划投影与能力校验保障了链路正确性，HTTP 路由与响应缓存提升了性能，适配器与转换器分层清晰，便于扩展与维护。建议在部署前完成能力校验与路由规则优化，并结合业务场景配置合适的缓存与策略。

[本节为总结，无需特定文件引用]

附录

• 关键数据结构与复杂度
• Exchange 与 Payload：O(1) 访问，适合高频分发
• TransformAction：常量级判断，驱动管道流转
• Capabilities 匹配：线性比较各布尔位，整体 O(n)
• 最佳实践
• 明确入站能力与转换器能力边界，避免过度耦合
• 使用策略进行横切关注点（鉴权、限流、审计）的解耦
• 对长连接与流式处理，重视背压与会话状态管理

[本节为补充说明，无需特定文件引用]