pole-sidecar

基于 Pingora 的多协议治理 Sidecar。HTTP、gRPC、Dubbo 和 Thrift 请求会先归一化为统一 TrafficContext，执行同一条治理 Pipeline，再转发到选定上游。

Thin SDK 通过 gRPC over UDS 建立本地会话，Sidecar 在首帧主动下发各协议 listener 端口。业务请求仍按原协议进入独立 loopback listener，不经过内部 gRPC。

当前能力

• HTTP/1.1、HTTP/2 与 gRPC h2c 流式代理；
• Dubbo 3 Triple 复用 HTTP/gRPC 数据面；
• Dubbo TCP 16 字节帧、request ID、oneway/event 和 serializer 识别；
• Thin SDK 的 Thrift-over-HTTP（Binary/Compact payload），以及底层 Framed Transport adapter；
• 四协议统一提取服务、方法、路径、group、version、deadline 和协议元信息；
• 普通 header/metadata/attachment 匹配；
• 对 JSON 格式 header 值执行惰性 JSONPath 查询；
• Dubbo/Thrift 按请求独立选路、上游连接池、关联 ID 重写、乱序响应恢复；
• 有界队列、in-flight 上限、帧长限制、超时清理和读写背压。

TargetService 使用 latticehub-target-namespace 与 latticehub-target-service； HTTP/Thrift-over-HTTP 放在 Header、gRPC 放在 Metadata、Dubbo 放在 Attachment。 Sidecar 消费后删除这些字段。Thrift 不使用私有帧或 Java 缺失的 THeader。

数据路径

协议 Adapter
    ↓
TrafficContext
    ↓
GovernancePipeline
    ↓
ForwardPlan / LocalReply / Drop
    ↓
HTTP/gRPC/Thrift-over-HTTP Forwarder 或 Dubbo TCP DataPlane

HTTP、gRPC 与 Thin SDK 的 Thrift-over-HTTP 由 Pingora 完成 framing 和流式转发。 Dubbo TCP 使用 BytesMut 增量成帧，业务 payload 保持原始 Bytes，只在需要时 改写协议关联 ID；底层 Thrift Framed adapter 仅保留给非 Thin SDK 场景。

配置

业务 listener 只绑定 loopback，默认尝试 HTTP 15001、gRPC 15002、Dubbo 15003、Thrift 15004，冲突时动态分配。Thin SDK 只固定 UDS：

/var/run/pole/sidecar/bootstrap.sock

可通过 POLE_SIDECAR_SOCKET 覆盖 UDS。路由与上游参考 sidecar.toml：

[egress_http]
addr = "127.0.0.1:15001"

[egress_grpc]
addr = "127.0.0.1:15002"

[egress_triple]
addr = "127.0.0.1:50052"

[egress_dubbo]
addr = "127.0.0.1:15003"
max_frame_size = 16777216
read_timeout_ms = 60000

[egress_thrift]
addr = "127.0.0.1:15004"
max_frame_size = 16777216
read_timeout_ms = 60000

[[routes]]
name = "grpc_catalog"
protocol = "grpc"
service = "catalog.v1.Catalog"
cluster = "catalog"

[[clusters]]
name = "catalog"
endpoints = ["127.0.0.1:50051"]
force_h2 = true
max_h2_streams = 128

JSON header 条件：

[[routes]]
name = "gold_tenant"
protocol = "http"
prefix = "/api/"
cluster = "gold_backend"

[[routes.headers]]
kind = "json_path_equals"
name = "x-governance"
path = "$.tenant.tier"
value = "gold"

普通 header 查询不会解析 JSON；只有包含 JSONPath 条件的规则才会惰性解析对应 header，并在同一请求内缓存结果。

Triple extended 与标准 gRPC 可以使用相同的 application/grpc+proto wire format，无法仅靠报文无歧义区分。egress_triple 监听器会显式把这类请求归类为 Dubbo；egress_grpc 则显式归类为 gRPC。旧配置键 inbound_* 仅作为兼容别名保留。

运行

cargo build --release
RUST_LOG=info cargo run --release

可通过 SIDECAR_CONFIG 指定配置文件：

SIDECAR_CONFIG=./my-sidecar.toml cargo run --release

验证

cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo bench --bench governance_hot_path

测试覆盖协议 golden frame、拆包粘包、畸形长度、ID 改写、乱序响应、超时、上游断连、JSONPath 惰性解析和治理选路。详细设计见 四协议统一治理数据面规格 和 多协议数据面模块架构。