客户端服务连接：WebSocket 与 MessagePort

本文介绍 ZCode 中客户端与服务端之间的两类连接边界：面向 Web 服务的 WebSocket，以及 packages/rpc 中用于进程内／进程间通信示例的 MessagePort。当前源代码取样确认了服务端 WebSocket 入口、认证配置和 RPC MessagePort 示例的位置；由于本页的源代码读取预算已用尽，未读取底层连接实现，因此对具体帧格式、重连策略和方法签名不作推断。

Purpose and Scope

本页聚焦“客户端如何连接到 ZCode 服务”的传输层边界：

• packages/server 提供 HTTP／WebSocket 服务与远程连接能力。
• packages/web 是 Web 客户端包，属于客户端侧入口。
• packages/rpc 提供 RPC 通信相关代码，并在 package.json 中暴露 MessagePort IPC 演示脚本。
• WebSocket 认证通过 ZCODE_SERVER_AUTH_TOKEN（直接启动通用 Web 服务时）或程序化创建服务时的 authToken 选项配置。

本页不展开远程后端部署、Docker 后端、CLI 进程管理或 Web UI 业务功能；这些能力应由相应的兄弟目录／目录页负责。底层 RPC 协议、channel 生命周期、具体握手消息和异常类型在本次读取范围内未能验证，implementation details not found in source excerpt。

Overview

ZCode 的客户端连接可从两个层面理解：

1. Web 客户端到服务端的网络连接：仓库文档明确将 packages/web 定义为 Web 客户端，将 packages/server 定义为 HTTP／WebSocket 服务与远程连接；通用 Web 服务的 WebSocket 访问受服务认证配置控制。
2. RPC／IPC 通道：packages/rpc/package.json 声明了 demo:messageport 脚本，实际运行 examples/03-ipc-server-client.ts。这表明 MessagePort 是 RPC 包提供的一个客户端／服务端通信演示入口，但本页未读取该示例或通道实现，不能进一步断言其消息协议、传输序列化方式或关闭语义。

因此，WebSocket 更适合跨网络的 Web 服务连接；MessagePort 则出现在 RPC 包的 IPC 示例中。这里的“适合”只表示代码组织和脚本命名所呈现的边界，不代表源代码已证明某一种传输在所有部署模式下的强制选择。

Architecture

下图只展示已从仓库文档和包元数据确认的组件边界，不虚构未读取的内部类名或调用链：

Source: README.md Source: package.json

packages/web 与 packages/server 的职责来自根 README 的包说明；WebSocket 认证和 RPC MessagePort 演示分别由 README 的认证说明和 RPC 包脚本声明确认。图中 MessagePort 节点保持在 RPC 包内部，是因为已知证据只证明存在 IPC server-client 示例，并未读取足够源码确认它与 WebSocket 服务端之间的直接依赖关系。

WebSocket 连接边界

根 README 将 packages/server 描述为“HTTP / WebSocket 服务与远程连接”，并明确指出直接启动通用 Web 服务的 HTTP 入口时，API／WebSocket 认证使用 ZCODE_SERVER_AUTH_TOKEN。这说明 WebSocket 不是孤立的客户端 API，而是通用 Web 服务入口的一部分；运维配置认证令牌时必须同时考虑 HTTP API 与 WebSocket 访问。

已确认的认证配置入口如下：

• 环境变量：ZCODE_SERVER_AUTH_TOKEN，适用于直接启动通用 Web 服务的 HTTP 入口。
• 程序化配置：authToken 选项，适用于程序化创建服务。

本次源代码预算未读取 packages/server/src/entry-http.ts、packages/server/src/http.ts 或 WebSocket handler 的实现，因此以下细节不能从当前证据得出：连接 URL 的精确路径、握手头、令牌传递位置、未授权状态码、心跳、重连、广播、关闭码和并发模型。不要将这些行为从包名称或 README 描述中推断出来。

MessagePort RPC 边界

packages/rpc/package.json 中的脚本声明：

• demo:messageport 执行 node --loader ts-node/esm examples/03-ipc-server-client.ts。
• 同一脚本组还包含 proxy channel 和 remote connection 演示，表明 RPC 包按示例区分了不同的通信／封装场景。

因此，排查 MessagePort 连接时，建议从 examples/03-ipc-server-client.ts 开始，再沿着 packages/rpc/src 下的 channel、protocol 和 IPC 实现追踪。但这些文件在本次任务中未读取，具体 API、参数、返回类型和错误处理均应以源文件为准；当前无法提供经过验证的 API reference。

Core Flow

基于已确认的包职责和脚本入口，可以建立如下边界级流程。它不是对内部握手的模拟，而是帮助定位代码的最小路径：

Sources:

• README.md
• package.json

其中只有“Web 客户端／服务端包职责”“WebSocket 认证配置”和“MessagePort 示例脚本”是已验证事实；连接结果内容、消息方向和 IPC 内部步骤需要继续读取实现后才能扩展。

Usage Examples

WebSocket 认证配置

当前已读取的仓库材料只提供配置键名称和适用场景，没有读取可直接复制的启动代码。因此，No code example available。使用时应以服务启动实现和 CLI 文档为准，不应根据本页自行推断命令行参数。

MessagePort 示例入口

仓库已确认可用的脚本入口是 demo:messageport，但本次未读取示例源码，故不能安全摘录 MessagePort 的创建、监听或发送代码。No code example available。

Configuration Options

API Reference

本次读取的材料只确认了配置键与 npm script，没有读取 WebSocket handler、RPC channel 或 MessagePort 示例的实现。因此无法提供可信的类名、函数签名、参数、返回值或异常列表。请在补充读取 packages/server/src 与 packages/rpc/src 后再生成 API 级文档。

Failure Modes, Edge Cases and Concurrency

已验证的失败边界只有认证配置层面：如果服务要求 WebSocket 认证而客户端没有按部署方式提供令牌，连接行为需要由服务实现决定；当前摘录没有证明具体响应码或关闭原因。

以下事项在已读材料中没有足够证据：

• WebSocket 断线后的自动重连与退避；
• MessagePort 的端口关闭、重复连接和消息乱序处理；
• 多客户端并发、广播或背压；
• WebSocket 心跳、超时和连接清理；
• RPC 请求超时、取消和错误传播。

这些均应视为待核实项，而不是当前系统行为的结论。

Performance and Operational Notes

对于网络侧运维，必须保护 ZCODE_SERVER_AUTH_TOKEN，因为同一认证配置同时覆盖 API／WebSocket 访问。仓库 README 还将 packages/server 归类为 HTTP／WebSocket 服务与远程连接，因此服务端部署、远程后端和进程管理应留在对应专题中。

性能方面，当前证据不足以确认消息大小限制、压缩、连接池、事件循环调度或 RPC 序列化开销。implementation details not found in source excerpt。

Extension Points

源码目录清单显示 packages/rpc/src 包含 channelClient.ts、channelServer.ts、channels.ts、protocol.ts、persistent-protocol.ts、proxy-channel.ts 等实现文件，但本次未读取其内容，不能可靠描述扩展契约或替换方式。扩展 RPC 传输前，应先确认这些模块的接口关系和实现者。

Related Links

• 根 README：Web 服务认证说明
• 根 README：包职责说明
• RPC package scripts
• HTTP 服务入口目录
• RPC 实现目录