CarrotPrint/yipe/grpc_summary.md

# gRPC 控制流协议摘要（ControlService）

## 接口
- 服务：`control.v1.Control`
- RPC：`ControlStream(stream ClientMessage) returns (stream ServerMessage)`
- 双向长连接，客户端与控制端可任意时序发消息。

## 消息结构（摘自 proto/control.proto）
- `ClientMessage` oneof：
  - `Hello`：client_id、version、hostname、printers[]
  - `PrintResult`：request_id、ok、printer、message、retries_used
  - `Pong`：nonce（对应 Ping）
  - `PrinterUpdate`：printers[]
- `ServerMessage` oneof：
  - `PrintInstruction`：request_id、pdf_data(bytes)、PrintParams
  - `Ping`：nonce
- `PrintParams`：copies、duplex(one_sided/long_edge/short_edge)、color(auto/color/monochrome)、media、quality(draft/normal/high)、orientation(portrait/landscape)、job_name、printer(optional 指定目标打印机)
- `PrinterInfo`：id、name、host、uri、state、accepting_jobs、color_supported、active_jobs、ppm、ppm_color、reasons[]

## 客户端行为（当前实现）
- 建立流后立即发送 `Hello`，携带当前打印机快照。
- 后台按配置刷新（默认 10s，最小 5s）检测变更，发送 `PrinterUpdate`。
- 收到 `Ping{nonce}` 立即回 `Pong{nonce}`。
- 收到 `PrintInstruction`：
  - 将 pdf_data 落盘临时文件。
  - 按调度策略（默认 least_queued，支持指定 printer；尊重彩色需求和可用性）分发到 CUPS。
  - 成功/失败后返回 `PrintResult{ok, printer, message, retries_used}`。
- 连接出错自动指数退避重连（1s 起，最大 10s），控制端无需主动重连。

## 字段语义补充
- `color_supported`：客户端基于 CUPS 选项判定，保守为 false 以避免误判。
- `state`：CUPS 状态字符串（Idle/Processing/Stopped 等）。
- `reasons`：CUPS 状态原因列表（offline/jam/paper-out 等）。
- `ppm`/`ppm_color`：若 CUPS 未提供则为缺省/0。

## 控制端最小交互建议
1) 等待首条 `Hello`，登记客户端与打印机列表。  
2) 定期/按需发送 `Ping` 保活。  
3) 下发打印用 `PrintInstruction`（带 request_id 以关联结果）。  
4) 接收 `PrintResult` 做业务回执；可订阅 `PrinterUpdate` 更新状态。  

## 开发/测试命令
- 生成/查看 proto：文件位于 `proto/control.proto`，由 `tonic-build` 在 `build.rs` 生成绑定。  
- 本地 smoke（无控制端）：`LIBCLANG_PATH=/usr/lib CONFIG_PATH=config/app.yaml cargo run --bin cups_smoke -- --list` / `--print <file> -p <printer>`。

## 原始 proto 文件
路径：`proto/control.proto`

```
syntax = "proto3";

package control.v1;

service Control {
  rpc ControlStream(stream ClientMessage) returns (stream ServerMessage);
}

message ClientMessage {
  oneof msg {
    Hello hello = 1;
    PrintResult result = 2;
    Pong pong = 3;
    PrinterUpdate printers = 4;
  }
}

message ServerMessage {
  oneof msg {
    PrintInstruction print = 1;
    Ping ping = 2;
  }
}

message Hello {
  string client_id = 1;
  string version = 2;
  string hostname = 3;
  repeated PrinterInfo printers = 4;
}

message Ping {
  string nonce = 1;
}

message Pong {
  string nonce = 1;
}

message PrintInstruction {
  string request_id = 1;
  bytes pdf_data = 2;
  PrintParams params = 3;
}

message PrintParams {
  uint32 copies = 1;
  string duplex = 2;        // one_sided, long_edge, short_edge
  string color = 3;         // auto, color, monochrome
  string media = 4;
  string quality = 5;       // draft, normal, high
  string orientation = 6;   // portrait, landscape
  string job_name = 7;
  string printer = 8;
}

message PrintResult {
  string request_id = 1;
  bool ok = 2;
  string printer = 3;
  string message = 4;
  uint32 retries_used = 5;
}

message PrinterUpdate {
  repeated PrinterInfo printers = 1;
}

message PrinterInfo {
  string id = 1;
  string name = 2;
  string host = 3;
  string uri = 4;
  string state = 5;
  bool accepting_jobs = 6;
  bool color_supported = 7;
  uint32 active_jobs = 8;
  uint32 ppm = 9;
  uint32 ppm_color = 10;
  repeated string reasons = 11;
}
```