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

小A与老Z围在一块展示完整微缩场景的黑板旁,老Z正把空白便签依次贴到板上,象征快照之后按序应用增量更新。

本章导读: 源码路线第 ⑨ 站(远程层),同时看 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) 发出去,编码失败也只记错误,不阻断关闭。”

text
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,直接失败。

ts
// 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,“处理顺序是这样的。”

text
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?登录即解锁完整章节。