4. gRPC 插件

gRPC 插件（plugins/grpc/）是 Bridge 当前唯一可用的传输实现，基于 autonomy/common/async_grpc 将 §3 RPC 落地为异步服务端。

编号约定：本页 §4.1–§4.6 为插件总览；grpc/01_*–06_* 为 async_grpc 专题（子页 H2 为 {文件前缀}.x，如 02 → ## 2.1）。文档地图见 00_guide §0.1。

4.1 组件

路径	职责
`grpc_bridge.*`	`GrpcBridgeServer` 生命周期、Handler 注册
`handlers/navigation_handler.*`	`SendNavigationCommand`
`handlers/exploration_handler.*`	`SendExplorationCommand`
`clients/navigator_stub.*`	Navigator 客户端（待实现）
`grpc_bridge_context.*`	`ExecutionContext` 扩展（待接线）

4.2 服务器构建

Server::Builder b;
b.SetServerAddress("127.0.0.1");  // 待读 GrpcOptions，缺 port
b.SetNumGrpcThreads(4);
b.SetNumEventThreads(4);
b.RegisterHandler<SendNavigationHandler>();
b.RegisterHandler<SendExplorationHandler>();
grpc_server_ = b.Build();  // → Start() → Shutdown()

Builder 方法	Proto 字段	现状
`SetServerAddress`	`host` + `port`	硬编码，缺 port
`SetNumGrpcThreads`	`num_grpc_threads`	硬编码 4
`SetNumEventThreads`	`num_event_threads`	硬编码 4

接线缺口与目标形态：grpc/05 §5.7 · Handler 状态：grpc/07 §7.1。

4.3 Handler

RPC 字段见 rpcs/07 导航等专题。流程：OnRequest → 多次 Send() → Finish()；跨线程写 Stream 用 GetWriter()。

新增 RPC：proto → DEFINE_HANDLER_SIGNATURE → RpcHandler → RegisterHandler（详见 grpc/04 Handler API）。

4.4 状态码与调优

gRPC Status	场景
`OK` / `INVALID_ARGUMENT` / `FAILED_PRECONDITION`	正常 / 参数非法 / FSM 不允许
`UNAVAILABLE` / `DEADLINE_EXCEEDED`	Navigator 未就绪 / 超时

建议：num_event_threads ≥ num_grpc_threads；大载荷调高 max_send_message_size。详见 grpc/07 §7.4 · grpc/02 §2.7。

4.5 Navigator 对接

Bridge 命令	Navigator
`NAV_CMD_START` + `NAV_MODE_SINGLE_POSE`	`NavigateToPose`
`NAV_CMD_START` + `NAV_MODE_THROUGH_POSES`	`NavigateThroughPoses`
`NAV_CMD_REPLAN`	重规划（保持 goals）
`NAV_CMD_PAUSE` / `RESUME`	BT 暂停 / 恢复
`NAV_CMD_CANCEL` / `STOP`	`cancel_goal`

4.6 async_grpc 专题

文件	内容
grpc/01	框架定位、类图、Bridge 实例化
grpc/02	CQ / EQ 双队列、线程模型
grpc/03	Rpc 状态机、四种 RPC 类型
grpc/04	Handler API、ExecutionContext
grpc/05	源码接线、配置映射
grpc/06	cartographer async_grpc 上游

导航：← §3 RPC · grpc/ 专题 → · §5 MQTT →