Hive Router 0.0.84：部署配置、traffic_shaping 排障与 coprocessor 扩展
项目信息
- 仓库：graphql-hive/router（The Guild，Rust 编写，MIT）
- 文档：the-guild.dev/graphql/hive/docs/router
- crates.io：hive-router 0.0.84
- Docker 镜像：
ghcr.io/graphql-hive/router:latest，版本列表见 GitHub Releases /ghcr.io/graphql-hive/router - 安装脚本：
curl -o- https://raw.githubusercontent.com/graphql-hive/router/main/install.sh | sh
预编译产物只有 Linux / macOS，Windows 走 Docker。
Hive Router 可作为 Apollo Router 的 drop-in 替代，二进制或 Docker 镜像分发。
基本配置与运行
router.config.yaml：
supergraph:
source: file
path: ./supergraph.graphql
./hive_router
默认读取 router.config.yaml，可用 ROUTER_CONFIG_FILE_PATH 覆盖路径。
Docker 运行：
docker run -p 4000:4000 -v ./router.config.yaml:/app/router.config.yaml ghcr.io/graphql-hive/router:latest
也可以直接用环境变量挂载 schema：
docker run -p 4000:4000 -e SUPERGRAPH_FILE_PATH="/app/supergraph.graphql" -v ./my-supergraph.graphql:/app/supergraph.graphql ghcr.io/graphql-hive/router:latest
默认在 4000 端口提供 GraphQL IDE。supergraph 来源除本地文件外还支持 Hive Console 与 Apollo GraphOS，变更时可热重载（Hive Console 为可选）。
生产环境建议固定镜像版本号，不要用 latest。
官方基准与实现
官方基准（blog welcome-hive-router 与产品页）：
- 199/199 Federation audit 测试用例通过
- 50 并发下 p95 约 48ms
- 峰值内存约 49MB
- 约 1830 RPS，约为 Apollo Router 的 6 倍吞吐
实现层面：Arena 分配 + 零拷贝 JSON + 无 GC；查询计划按 wave 并行执行（对齐 Apollo 的 Parallel/Sequence）；基于 Tokio + Hyper 的异步 I/O，热路径无全局锁。
traffic_shaping
配置参考文档 configuration/traffic_shaping。可全局配置，也可按子图覆盖。字段包括：allow_only_http2、circuit_breaker、dedupe_enabled、forward_operation_name、pool_idle_timeout、request_timeout、tls、websocket。
并发连接限制
单子图可限制最大并发 HTTP 连接数，防止压垮下游。
dedupe_enabled
router 侧的 dedupe_enabled 会把相同并发 query 合并成一次执行，结果共享给所有等待的客户端。订阅同样去重：N 个相同操作只建立一条上游连接，事件广播给这些客户端。
长连接上限与 503
长连接（WebSocket、SSE、Incremental Delivery、Multipart HTTP）有并发上限，超过后返回：
503
Retry-After: 5
普通 query / mutation 不受该上限影响。
request_timeout
router 级 request_timeout 覆盖从接收请求到返回响应的整条流水线：收 body、解析、校验、查询计划、执行。值是 duration 字符串，如 60s、1m。
子图的默认 request_timeout 是 30s。
circuit_breaker
circuit_breaker.enabled 设为 true 后累计子图失败次数，超过阈值则打开熔断。打开期间请求立即返回 SUBGRAPH_CIRCUIT_BREAKER_REJECTED。经过 reset_timeout 后进入 half-open，放行探测请求：探测结果低于错误阈值则关闭熔断，否则回到 open。
扩展
有两种方式：Rust plugin 和 coprocessor。
Rust plugin
编译进路由内部。用 crates.io 上的 hive-router 自定义 build：
configure_global_allocator!();
impl RouterPlugin for MyPlugin { /* ... */ }
#[hive_router::main]
fn main() -> Result> {
router_entrypoint(PluginRegistry::new().register::())
}
Coprocessor
外部 HTTP 服务，语言无关，在请求生命周期的各个 stage 被调用。各 stage 的触发位置：
router.request：HTTP 进入时，可做早期鉴权 / 快速拒绝graphql.request：payload 可用时，做请求整形 / 变量归一化graphql.analysis：解析校验之后、查询计划执行之前，可注入 progressive override labelgraphql.response：执行返回后，做响应规范化 / 错误整形 / 脱敏router.response：最末发送前
返回体只需包含 version + control 即表示继续。用 break + status code 可以短路请求（建议同时带上 body / headers）。要修改 headers / context 就一并返回；headers 会覆盖原 header，建议把原 header 一起带上。
部署建议：coprocessor 在关键路径上，尽量靠近路由实例。同节点 / 同 pod 用 unix:// + h2c + sidecar 延迟最低；跨机用 http://，但每个 stage 多一次网络跳。
观测方面，metrics 提供 per-stage 的吞吐、延迟、失败计数；trace 有 coprocessor span（coprocessor.stage / coprocessor.id）与 http.client 子 span。
订阅
文档位置 router/subscriptions。开箱支持联邦订阅，drop-in 可用。
客户端侧支持 SSE / WebSocket / Multipart HTTP / Incremental Delivery，路由按 Accept 头自动协商。路由到子图的协议独立于客户端协议：客户端可以用 WebSocket，而路由对子图走 SSE / multipart；连子图时优先 multipart，回退 SSE。
HTTP Callback 协议是子图侧专有的：路由向子图注册 callback URL，子图推事件，避免每个订阅占一条长连接，适合高订阅量场景。有 heartbeat 保活，可把 callback 端点绑到独立端口以隔离流量。
联邦实体字段在订阅事件到达时按普通 query 的方式解析，跨子图同样成立。
观测与安全
观测：OpenTelemetry trace、Prometheus metrics、结构化日志、健康 / 就绪探针，可送到 Hive Console / Grafana / Datadog 或任意兼容后端。
安全：JWT 鉴权、授权指令、demand control、persisted documents、CSRF / CORS，均可在同一个 YAML 里配置。