# 傳輸協定

本頁規範 ToriiDB daemon client 與 server 在 unix socket 上交換的 frame 格式、request op 與錯誤種類。

## 傳輸協定

兩個方向使用相同 frame：

```text
[4-byte big-endian payload length][JSON payload]
```

超過 8 MiB 的 frame 會被 `readFrame` 拒絕。不是合法 JSON 的 payload 會在同一連線收到 `bad_request` 回應。

| op | 請求欄位 | 成功回應 |
|---|---|---|
| `get` | `db` `key` | `{"record":{db,key,type,content,created_at,updated_at?,expire_at?}}` |
| `entries` | `db` `pattern` `contains?` `after?` `limit?` | `{"entries":[<record>,...]}` |
| `set` | `db` `key` `content` `expire_at?` `vector?` | `{}` |
| `del` | `db` `keys` | `{"count":<removed>}` |
| `ttl` | `db` `key` | `{"ttl":<seconds>}` |
| `expire` | `db` `keys` `ttl` | `{"count":<applied>}` |
| `keys` | `db` `pattern` `limit?` `page?` | `{"list":{db,page,limit,total,keys}}` |
| `vsearch` | `db` `text` `pattern` `limit?` | `{"keys":[...]}` |
| `embedder` | 無 | `{"embedder":<bool>}` |

失敗時回傳 `{"error":"...","kind":"..."}`：

| kind | Client 錯誤 | 常見原因 |
|---|---|---|
| `not_found` | `ErrNotFound` | 對不存在的鍵 `get`/`ttl` |
| `bad_request` | `ErrBadRequest` | 無效 db 索引、缺少 `pattern`/`keys`/`text`、`ttl <= 0`、內容無效、未知 op |
| `no_embedder` | `ErrNoEmbedder` | 無 API key 時 `set` 帶 `vector` 或 `vsearch` |
| `internal` | 一般 error | store 或 embedding 失敗 |

## 相關頁面

- [Server 端篩選](/zh/socket-daemon-filtering)
- [連線處理](/zh/socket-daemon-connections)
- [錯誤](/zh/core-concepts-errors)