client@earendil-works/pi-client

要点Key points

• 根入口不碰 Node API：浏览器或 worker 也可以用，只要提供自己的传输（例如 WebSocket）。The root entry touches no Node APIs: a browser or worker can use it with its own transport (a WebSocket, say).
• Client 只认 @earendil-works/chord 的服务控制调用（目录、订阅、退订）和状态解码器，不解释任何应用契约。Client knows only @earendil-works/chord's service-control calls (catalogue, subscribe, unsubscribe) and state decoder; it interprets no application contract.
• coding-agent 里有两种传输：createUnixTransportFactory() 和 radius-relay.ts 的 WebSocket 中继传输。coding-agent uses two transports: createUnixTransportFactory() and the WebSocket relay transport in radius-relay.ts.

工作原理How it works

1. const client = await Client.connect({ serverId, transportFactory })：失败时它会自己 dispose()。const client = await Client.connect({ serverId, transportFactory }): on failure it disposes itself.
2. 低层调用：client.request({ serverId: client.serverId }, { serviceId, member, args })。A low-level call: client.request({ serverId: client.serverId }, { serviceId, member, args }).
3. 类型化调用：把 createClientServiceTransport(client, getTarget) 交给 Chord 绑定。Typed calls: hand createClientServiceTransport(client, getTarget) to a Chord binding.

要点Key points

• 旧尝试的回调带着旧 id，被 #isCurrent(id) 过滤掉；工厂迟到返回的传输会被直接 close()。Callbacks from an old attempt carry its id and are filtered by #isCurrent(id); a transport the factory returns late is simply closed.
• 握手前的数据、第一条不是 hello、握手后再来 hello / hello_error，都是协议错误。Data before the client hello, a first message other than hello, or another hello / hello_error after connecting are all protocol errors.
• 进入 disconnected 时 Client 清空 hello 与附着、拒绝全部挂起请求、丢弃全部订阅，再通知 onConnectionStateChange。Entering disconnected, the Client clears hello and the attachment, rejects every pending request, drops every subscription, then notifies onConnectionStateChange.

工作原理How it works

1. client.onConnectionStateChange(({ state, error }) => …) 观察状态；client.connectionState 读取当前值。Observe with client.onConnectionStateChange(({ state, error }) => …); read client.connectionState for the current value.
2. maxFrameLength 必须是 1 到 0xffffffff 的安全整数，否则构造时抛 TypeError。maxFrameLength must be a safe integer from 1 to 0xffffffff, or the constructor throws a TypeError.
3. 关闭时解码器 end()：残留半帧会变成截断错误，作为断开原因上报。On close the decoder end()s: a leftover partial frame becomes a truncation error, reported as the disconnect reason.

要点Key points

• 回应可以乱序到达；没有对应条目的回应是协议错误，会断开连接。Responses may arrive out of order; a response with no matching entry is a protocol error and drops the connection.
• abort 之后条目留在表里，直到服务端的 cancelled 回应到来，所以那条回应不算“无主”。After an abort the entry stays until the server's cancelled response arrives, so that response is not an orphan.
• 调用在发送前用 Chord 的 parseServiceCall() 校验；编码失败会取回条目并拒绝，什么也不发送。The call is validated with Chord's parseServiceCall() before sending; an encoding failure takes back the entry and rejects without sending anything.

工作原理How it works

1. await client.request(target, call, signal)：signal 是普通的 AbortSignal。await client.request(target, call, signal): signal is an ordinary AbortSignal.
2. client.serviceCatalogue(target) 是同一路径上的一个预置调用，结果用 parseServiceCatalogue() 校验。client.serviceCatalogue(target) is a preset call on the same path, checked with parseServiceCatalogue().
3. 错误处理：catch (e) { if (e instanceof ServerError && e.code === "cancelled") … }。Error handling: catch (e) { if (e instanceof ServerError && e.code === "cancelled") … }.

要点Key points

• 每个订阅有自己的 Chord 状态解码器（createServiceStateDecoder()）：快照和更新都经过它。Every subscription has its own Chord state decoder (createServiceStateDecoder()); snapshots and updates both go through it.
• dispose() 只在仍连接且路由仍是当前路由时发退订；随后等待 deliveryTail 并清空缓冲。dispose() sends the unsubscribe only while connected and while the route is current; then it awaits deliveryTail and clears the buffers.
• 断开时 #serviceListeners 整体清空；订阅不会自动恢复。On disconnect #serviceListeners is cleared wholesale; subscriptions are not restored.

工作原理How it works

1. const sub = await client.subscribeService(target, serviceId, mode, listener)；装好 sub.snapshot 后调用 sub.start()。const sub = await client.subscribeService(target, serviceId, mode, listener); install sub.snapshot, then call sub.start().
2. 监听器抛出的错误只交给 ClientOptions.onListenerError。Listener errors only reach ClientOptions.onListenerError.
3. 通过 Chord 绑定使用时，activate 对应 start()、close 对应 dispose()。Through a Chord binding, activate maps to start() and close to dispose().

要点Key points

• 附着信封先于 attach 的回应送达：回应 resolve 时 client.attachment 已经可用。The attachment envelope arrives before the attach response: when it resolves, client.attachment is already set.
• 路由不存在时，适配器抛 "Remote service target is unavailable"，不会发出请求。Without a route the adapter throws "Remote service target is unavailable" and sends nothing.
• #targetIsCurrent()：服务器级目标与 hello 的 serverId 比较，Session 目标与当前附着的三个字段比较。#targetIsCurrent(): a server target is compared with the hello's serverId, a Session target with all three fields of the current attachment.

工作原理How it works

1. 服务器级服务：createClientServiceTransport(client, () => ({ serverId: client.serverId }))。Server-wide services: createClientServiceTransport(client, () => ({ serverId: client.serverId })).
2. Session 服务：createClientServiceTransport(client, () => client.attachment)。Session services: createClientServiceTransport(client, () => client.attachment).
3. client.onAttachmentChange((a) => …)：undefined 表示没有附着。client.onAttachmentChange((a) => …): undefined means no attachment.

要点Key points

• maxPendingBytes 默认是帧上限的 4 倍（64 MiB）；超过就拒绝这次 send，Connection 随之断开。maxPendingBytes defaults to 4 × the frame limit (64 MiB); beyond it the send rejects and the Connection drops.
• 每个 chunk 都先 slice() 复制，调用方之后修改缓冲也不影响写出的字节。Every chunk is copied with slice() first, so later changes to the caller's buffer cannot affect what is written.
• 失败的写不会堵住队列：#writeTail 吞掉错误，只有该次调用的 Promise 被拒绝。A failed write never blocks the queue: #writeTail swallows it, and only that call's promise rejects.

工作原理How it works

1. createUnixTransportFactory({ path, maxPendingBytes })：path 不能为空，Windows 上不可用。createUnixTransportFactory({ path, maxPendingBytes }): the path must not be empty; unavailable on Windows.
2. 自定义传输：实现 send / close，并且恰好调用一次 onClose 或 onError。A custom transport: implement send / close and call exactly one of onClose or onError.
3. 两端配置相同的 maxFrameLength，并让 maxPendingBytes 至少容得下一帧。Configure the same maxFrameLength on both peers, with maxPendingBytes large enough for one frame.

要点Key points

• 只读：陈旧或无响应的 socket 只会被忽略，从不删除——清理归服务器端的监听器。Read-only: stale or unresponsive sockets are just ignored, never deleted; cleanup belongs to the server's listener.
• 超时、协议错误、版本不符、无 cause 的断开以及 ENOENT / ECONNREFUSED / ECONNRESET / EPIPE / ETIMEDOUT 都算“不是这台服务器”。Timeouts, protocol errors, version mismatches, cause-less disconnects and ENOENT / ECONNREFUSED / ECONNRESET / EPIPE / ETIMEDOUT all count as “not this server”.
• 其它错误让整个发现失败：第一个错误被记下，工作者停止领取新候选。Any other error fails discovery: the first one is remembered and workers stop taking candidates.

工作原理How it works

1. const routes = await discoverUnixServers({ directory })，directory 用绝对路径，例如展开后的 ~/.pi/server。const routes = await discoverUnixServers({ directory }) with an absolute directory such as the expanded ~/.pi/server.
2. timeoutMs 覆盖每次探测的超时（1 … 2,147,483,647）。timeoutMs overrides the per-probe timeout (1 … 2,147,483,647).
3. 然后 Client.connect({ serverId: route.serverId, transportFactory: createUnixTransportFactory({ path: route.path }) })。Then Client.connect({ serverId: route.serverId, transportFactory: createUnixTransportFactory({ path: route.path }) }).

要点Key points

• 断开时挂起的请求在本地拒绝，但已被服务器接受的工作仍可能在远端完成。On disconnect pending requests reject locally, but work the server accepted may still complete remotely.
• coding-agent 的 RadiusClientReconnect 就是这样一种应用策略：指数退避重连并重新附着原来的 Session。coding-agent's RadiusClientReconnect is one such application policy: reconnect with exponential backoff and reattach the same Session.
• 监听器的异常只交给 onListenerError，诊断不能影响协议或传输状态。Listener exceptions only reach onListenerError; diagnostics cannot affect protocol or transport state.

工作原理How it works

1. e instanceof ServerError → 看 e.code；e instanceof DisconnectedError → 看 e.cause。e instanceof ServerError → inspect e.code; e instanceof DisconnectedError → inspect e.cause.
2. await using client = … 或 await client.dispose()：两者等价（Symbol.asyncDispose）。await using client = … or await client.dispose(): equivalent (Symbol.asyncDispose).
3. client.reconnect() 只是再走一次 connect()：新传输、新握手。client.reconnect() is just another connect(): a new transport and a new handshake.