chongming-utils-request/README.md

# chongming-request

Zenoh Worker 直连客户端，用于从服务端或其他 Worker 直接调用 Zenoh RPC，无需经过 HTTP 路由。

---

## 安装

```bash
uv pip install -e utils/request
```

---

## 功能

- **自动服务发现**：基于 Zenoh liveliness 自动发现存活的 Worker
- **随机负载均衡**：在可用 Worker 间随机选择
- **超时重试**：请求超时后自动重试
- **同步/异步支持**：提供 `call`（异步）和 `call_sync`（同步）接口

---

## API

### `Client` 类

```python
from chongming_request import Client

async with Client(session=zenoh_session) as client:
    result = await client.call(
        worker_type="example",
        subject="example.add",
        payload={"a": 1, "b": 2},
        method="GET"
    )
```

| 参数          | 类型            | 说明                             |
| ------------- | --------------- | -------------------------------- |
| `session`     | `zenoh.Session` | Zenoh 会话对象                   |
| `worker_type` | `str`           | Worker 类型名（如 `"example"`）  |
| `subject`     | `str`           | Zenoh 主题（如 `"example.add"`） |
| `payload`     | `dict`          | 业务参数（自动封装为信封）       |
| `method`      | `str`           | HTTP 方法（`"GET"` / `"POST"`）  |
| `timeout`     | `float`         | 超时时间（秒）                   |

> **信封协议**：`call()` 会把 `payload` 自动封装为
> `{"meta": {"method": ...}, "data": payload}` 发送，**不再修改调用方传入的 dict**；
> 若传入的 `payload` 已含 `meta`/`data` 结构则原样复用（仅补 `meta.method`）。

### 同步调用

```python
result = client.call_sync(
    worker_type="example",
    subject="example.add",
    payload={"a": 1, "b": 2},
    timeout=5.0
)
```

---

## 使用场景

1. **Worker 间互相调用**：一个 Worker 调用另一个 Worker 的 RPC 方法
2. **服务端内部调用**：在 FastAPI 路由处理器中直接调用 Worker
3. **内部接口调用**：调用 `internal = true` 的端点（不暴露 HTTP 路由）
4. **测试与调试**：直接测试 Worker 的 RPC 行为

---

## 与 HTTP 调用的对比

| 特性                 | HTTP 调用          | `chongming-request`  |
| -------------------- | ------------------ | -------------------- |
| 需要注册 HTTP 路由   | ✅                 | ❌（直接 Zenoh RPC） |
| 支持 `internal` 端点 | ❌                 | ✅                   |
| 序列化开销           | JSON → HTTP → JSON | JSON → Zenoh → JSON  |
| 适用场景             | 外部客户端         | 内部微服务通信       |

---

## 依赖

- `zenoh` — Zenoh Python 绑定（`eclipse-zenoh`）