源码篇第10章 黑板与便签——pi-server+pi-client ​

本章导读: 源码路线第 ⑨ 站(远程层),同时看
pi-server和pi-client,读server/server.ts、server/session-router.ts和client/connection.ts、client/client.ts。这一站要直面断线后最难缠的问题:那条命令到底执行了没有?重连拿到的状态能信多少?
字节已经能变成协议消息了。但小A把 client 和 server 连起来的时候,又冒出第二个问题:“我断线重连之后,怎么知道那条命令到底执行了没有?重连后拿到的状态,我能信多少?”
“先别急着信。”老Z说,“连接建立后要回答三件事:客户端如何确认版本和服务器身份、何时相信快照、断线后又能保证什么。我们跟读 client/server 这一层;源码未实现的自动重连,这一章不承诺。”
本章源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a7,packages/server/src/、packages/client/src/,包版本 1.0.0)。上一章说过,v1.0.0 的协议只剩通用 RPC 信封;业务内容是 @earendil-works/chord 定义的服务调用(service call),server 只负责把调用路由到宿主提供的服务。服务本身怎样实现会话、模型和工具,不在本章范围。
握手先于请求 ​
小A:“那我连上就发请求?”
“不行。”老Z说,“packages/server/src/connection.ts 定义了 ConnectionStage = "awaitingHello" | "handshaking" | "ready" | "closing" | "closed"。连接刚建立是 awaitingHello,第一条消息如果不是 hello,dispatchMessage 直接 failProtocol(invalid_request, "The first client message must be hello")。”
“收到 hello 后切到 handshaking,finishHandshake 按顺序做三件事:先 isSupportedProtocolVersion(hello.version),不支持就以 version 失败;再调用宿主的 serverServices.attachClient(...),给这条连接挂上服务器级服务,同时交给它 attachSession、detachSession、prepareSessionRemoval 三个能力;最后发 server hello,内容只有 version 和 serverId。发送成功才把 stage 切到 ready、清掉握手超时。”
“server hello 里没有快照?”小A问。
“v1.0.0 没有。”老Z说,“状态全部通过服务订阅拿,后面讲。还有一个细节:handshaking 期间如果又来一条消息,dispatchMessage 不会丢弃它,而是挂到 handshake.then(...) 上,等握手成功且 stage 已是 ready 才处理。握手失败的话,那条排队的消息永远不会被处理,连接也会被关掉。”
小A:“握手总不能一直挂着吧?”
“accept 里就埋了超时。”老Z回到 server.ts,“连接建立的同时 setTimeout 一个握手超时,默认 5 秒(DEFAULT_HANDSHAKE_TIMEOUT_MS),触发时以 invalid_request 和 ‘Handshake timeout’ 失败。所以‘收到 hello 但版本错’和‘一直不发 hello’是两种不同的死法:前者立刻报 version,后者拖到超时才报 invalid_request。failProtocol 会把 stage 置成 closing,尝试把一条 hello_error 作为最后一段数据随 close(finalFrame) 发出去,编码失败也只记错误,不阻断关闭。”
accept ──> awaitingHello
│ 非 hello 首帧 ──failProtocol(invalid_request)
│ 超时未 hello ──failProtocol(invalid_request)
v
收到 hello ──> handshaking ──版本不支持──> failProtocol(version)
│ ──serverServices.attachClient──> 异常 ──toProtocolError ──failProtocol
v
发送 server hello(version, serverId)
│ 期间 connection 关闭 ──返回,不置 ready
v
ready(清超时)
│ request ──handleRequest
│ cancel ──handleCancel
│ 再来 hello ──failProtocol("hello may only be sent as the first message")“token 认证呢?”小A问,“旧资料说 hello 里带 token。”
“v1.0.0 的 ClientHello 只有 type 和 version。”老Z说,“listener.ts 的注释写的是:listener 在完成传输层需要的认证之后,才把连接交给 server。认证从协议里挪到了传输层;Unix socket listener 的具体做法本章不展开。”
客户端这边,packages/client/src/connection.ts 的 Connection 维护三态生命周期:disconnected/connecting/connected,外加一个自增的 id。connect() 时 ++#sequence 得到新 id,#handleData、onClose、onError 都先判断 id 是否还是当前这一次,旧连接的迟到事件不会污染新连接。transport 建好后由 client 先发 hello;收到服务端数据时还没发出 hello,直接失败。
// packages/client/src/connection.ts,#handleMessage 的握手分支(v1.0.0,节选)
if (message.type === "hello_error") {
this.#failAndClose(new ServerError(message.error));
return;
}
if (message.type !== "hello") {
this.#failAndClose(new ProtocolValidationError("Expected server hello as first message"));
return;
}
if (message.serverId !== this.#options.serverId) {
this.#failAndClose(new ProtocolValidationError(`Connected server ... does not match ...`));
return;
}“注意第三个检查。”老Z说,“client 构造时就要给出期望的 serverId,server hello 里的 serverId 对不上就断开。物理地址可能指向别的服务器,这一步确认的是逻辑身份。”
要点:版本不匹配不执行请求
版本不匹配、首帧不是 hello、握手超时,都以
hello_error结束连接,不会进入任何服务调用。
一次请求怎样被路由 ​
小A:“ready 之后,请求怎么找到会话?”
“看 RequestEnvelope:id、target、call。”老Z打开 handleRequest,“处理顺序是这样的。”
handleRequest(envelope)
→ id 已在 activeRequests 中 ──> response ok:false invalid_request
→ parseServiceCall(call) 失败 ──> response ok:false invalid_request
→ 登记 AbortController 到 activeRequests
→ target.serverId 不是本机 ──> WrongServerError(wrong_server)
→ target 带 sessionId ──> SessionRouter.executeServiceCall
target 不带 sessionId ──> 本连接的 serverServices.invokeService
→ 成功:response ok:true(可带 result)
→ 失败:response ok:false;已被 cancel 则 code 为 cancelled
→ finally:从 activeRequests 移除“cancel 信封按 id 和 target 找到在途请求,调用它的 controller.abort();目标不一致就忽略。错误码经 toProtocolError 统一:ServerError 和 chord 的 RemoteServiceError 原样带出 code;协议校验错误归为 invalid_request;其他异常只报 internal_error 和固定文本 ‘Internal server error’,细节只进本地 onError,不发给对端。”
客户端的 Client.#request 是镜像:请求 ID 是 request-${序号},未完成的请求存在 #pendingRequests 里;传入的 AbortSignal 触发时,本地 Promise 立即 reject,同时发一个 cancel 信封。收到 response 时按 ID 取出;取不到就 #connection.fail(...),未知 ID 的 response 被当成协议错误,把连接废掉,而不是静默忽略。
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。