server@earendil-works/pi-server

要点Key points

• 监听器负责传输层的认证；实验性的 Unix 监听器不做认证，只依靠文件权限。Listeners own transport-level authentication; the experimental Unix listener does none and relies on file permissions.
• coding-agent 的 radius-relay.ts 只用到 Pick<Server, "accept">：中继来的连接与本地 socket 进入同一个 Server。coding-agent's radius-relay.ts only needs Pick<Server, "accept">: relayed connections enter the same Server as local sockets.
• Server.closed 在关闭后 resolve，监听器或 Session 清理失败时 reject。Server.closed resolves after shutdown and rejects when listener or Session cleanup fails.

工作原理How it works

1. const server = new Server(host, { listeners, serverId })，然后 await server.start()。const server = new Server(host, { listeners, serverId }), then await server.start().
2. 本机：createUnixServer(host, { serverId, path: getUnixSocketPath(serverId, dir) })。Locally: createUnixServer(host, { serverId, path: getUnixSocketPath(serverId, dir) }).
3. onConnectionCountChanged(count) 观察连接数，onError(error) 收集诊断。Observe connections with onConnectionCountChanged(count), collect diagnostics with onError(error).

要点Key points

• 服务器级端点拿到一个 RoutedServerPresentation：attachSession、detachSession、prepareSessionRemoval——应用的管理服务就是用它们 attach 的。The server-wide endpoint receives a RoutedServerPresentation: attachSession, detachSession, prepareSessionRemoval; the app's management service attaches through these.
• terminated 是可选的 Promise：意外退出时以错误 resolve，Server 随即让该 Session 的附着全部失效。terminated is an optional promise: it resolves with an error on unexpected exit, and the Server then invalidates every attachment to that Session.
• SessionMetadata 只要求 id；应用可以扩展它（coding-agent 带上了 path）。SessionMetadata only requires an id; apps may extend it (coding-agent adds a path).

工作原理How it works

1. const host: ServerHost<StoredSession> = { serverServices, resolveSession, openSession }。const host: ServerHost<StoredSession> = { serverServices, resolveSession, openSession }.
2. 找不到时 throw new SessionNotFoundError(Unknown session: ${id})。When missing, throw new SessionNotFoundError(Unknown session: ${id}).
3. invokeService(call, publish, ctx)：订阅的更新经 publish(subscriptionId, update) 回到 Server。invokeService(call, publish, ctx): subscription updates return through publish(subscriptionId, update).

要点Key points

• 握手期间到达的请求挂在 state.handshake 之后，ready 时才处理，不会丢。Requests that arrive during the handshake wait on state.handshake and run once ready; none are lost.
• disconnect() 只执行一次：abort 所有进行中的请求、清空订阅编码器，并行释放 Session 附着与服务器级端点。disconnect() runs once: it aborts every active request, clears subscription encoders, and releases the Session attachment and server-wide endpoint in parallel.
• 关闭中的 Server 对新连接直接 close，不建任何状态。A closing Server closes new connections at once without creating any state.

工作原理How it works

1. handshakeTimeoutMs 与 maxFrameLength 都是 1 … 上限之间的整数，构造时检查。handshakeTimeoutMs and maxFrameLength are integers within bounds, checked by the constructor.
2. await server.close()：先关监听器，再关连接，最后关所有托管的 Session。await server.close(): listeners first, then connections, then every hosted Session.
3. 自定义监听器：start(accept) 里对每个连接调用 accept(connection)，把返回的 handler 接到传输事件上。A custom listener: in start(accept), call accept(connection) per connection and wire the returned handler to transport events.

要点Key points

• 错误回应用 toProtocolError() 映射：ServerError / RemoteServiceError 原样，ProtocolValidationError → invalid_request，其它 → internal_error。Error responses are mapped by toProtocolError(): ServerError / RemoteServiceError as is, ProtocolValidationError → invalid_request, anything else → internal_error.
• 已 abort 的请求一律回应 cancelled；cancel 本身从不单独回应。An aborted request always answers cancelled; a cancel never gets its own response.
• 回应已发出后才出错（例如冲刷更新时），Server 关闭这条连接：订阅流不能半途断掉。If something fails after the response was sent (flushing updates, say), the Server closes the connection: a stream must not break halfway.

工作原理How it works

1. 同一连接上的请求并发处理；需要顺序时由应用在服务里自己排队。Requests on one connection run concurrently; apps that need ordering queue inside their services.
2. 在服务里尊重 context 的 abort 信号，取消才会尽快生效。Honour the context abort signal in services so cancellation takes effect quickly.
3. 退订成功后编码器被删掉，之后对该订阅的 publish 静默丢弃。After a successful unsubscribe the encoder is deleted, and later publish calls for it are silently dropped.

要点Key points

• 只有准入排队；调用结果在队列外等待，所以同一 Session 上的调用可以并发。Only admission is queued; results are awaited outside the queue, so calls on one Session run concurrently.
• openingSessions 让并发的 attach 共享同一次打开；失败时一起失败，之后可以重试。openingSessions lets concurrent attaches share one open; on failure they fail together, and a later retry may succeed.
• 打开期间服务器开始关闭：立即 handle.close() 并以 server_draining 拒绝。If the server starts closing during an open, handle.close() runs at once and the attach rejects with server_draining.

工作原理How it works

1. 应用的管理服务调用 presentation.attachSession(sessionId, ctx)；结果里不带任何路由 id。The app's management service calls presentation.attachSession(sessionId, ctx); its result carries no route ids.
2. 一个 Session 可以有多个连接的附着；每个附着各自有租约。One Session may have attachments from several connections, each with its own lease.
3. 要彻底删除 Session，先调用 prepareSessionRemoval(sessionId)，再删应用自己的元数据。To delete a Session, call prepareSessionRemoval(sessionId) first, then delete the app's own metadata.

要点Key points

• 连接断开只释放附着，Session 仍被托管；什么时候让 worker 退役由应用决定。A dropped connection only releases the attachment; the Session stays hosted, and the app decides when its worker retires.
• 句柄终止后 Session 从 hostedSessions 删除；下次 attach 会重新打开它。After a handle terminates, the Session leaves hostedSessions; the next attach reopens it.
• 释放失败也一定清掉路由（finally），否则连接会永远占着它。The route is cleared even if release fails (finally); otherwise the connection would hold it forever.

工作原理How it works

1. 在租约的 release(ctx) 里放掉 Session 级资源；它可能在调用仍在完成时被等待。Free Session-level resources in the lease's release(ctx); it may be awaited while calls are still completing.
2. 用 terminated 报告 worker 意外退出，让客户端尽快看到 attachment: null。Report unexpected worker exits through terminated so clients see attachment: null quickly.
3. 关闭失败时 server.close() 与 server.closed 以 AggregateError 拒绝。On cleanup failure server.close() and server.closed reject with an AggregateError.

要点Key points

• 活性探测：连得上或 1000 ms 没反应都算“还活着”——宁可启动失败，也不删别人的 socket。Liveness probe: connecting, or no answer within 1000 ms, both count as alive; better to fail start-up than delete another server's socket.
• 删除前总是先改名（stale- / cleanup-）再核对 dev/ino：避免与并发的替换竞争。Removal always renames first (stale- / cleanup-) and then checks dev/ino, to avoid racing a concurrent replacement.
• UnixByteConnection 把排队字节限制在 maxPendingBytes（默认 4 × 帧上限，至少帧上限 + 4），超过就断开慢的对端。UnixByteConnection caps queued bytes at maxPendingBytes (4 × the frame limit by default, at least limit + 4) and drops a slow peer beyond it.

工作原理How it works

1. getUnixSocketPath(serverId, dir) 得到 <dir>/<serverId>.sock；README 建议用一个短的私有运行时目录。getUnixSocketPath(serverId, dir) gives <dir>/<serverId>.sock; the README recommends a short private runtime directory.
2. createUnixListener({ path, mode, maxPendingBytes, gracefulCloseTimeoutMs }) 可以和其它监听器一起交给 new Server()。createUnixListener({ path, mode, maxPendingBytes, gracefulCloseTimeoutMs }) can go to new Server() alongside other listeners.
3. coding-agent：目录默认 ~/.pi/server，可用 PI_SERVER_DIR 覆盖。coding-agent: the directory defaults to ~/.pi/server, overridable with PI_SERVER_DIR.

要点Key points

• wrong_server 在访问任何仓库之前检查：发错服务器的请求不会触发 resolveSession。wrong_server is checked before any repository access: a request for another server never triggers resolveSession.
• 只有 ServerError 与 RemoteServiceError 的消息会被转发；其它异常的消息和堆栈不会离开服务器。Only ServerError and RemoteServiceError messages are forwarded; other exceptions' messages and stacks never leave the server.
• conformance.test.ts 是最大的测试文件：多附着、过期路由、未知 / 有歧义的 Session、Harness 终止与关闭时的清理。conformance.test.ts is the largest test file: multiple attachments, stale routes, unknown / ambiguous Sessions, Harness termination and shutdown cleanup.

工作原理How it works

1. 在 resolveSession 里 throw new SessionNotFoundError() 或 new SessionAmbiguousError()。In resolveSession, throw new SessionNotFoundError() or new SessionAmbiguousError().
2. const { server, host } = createTestServer({ listeners }) 得到一个未启动的测试服务器。const { server, host } = createTestServer({ listeners }) gives an unstarted test server.
3. const c = await connectUnixTestClient(path)，用 ProtocolTestClient 按帧断言。const c = await connectUnixTestClient(path), then assert frame by frame with ProtocolTestClient.