对象与热重载 —— 改代码为什么不用重启
凌晨两点,线上有 400 个会话开着。
你刚修完一个分词器的 bug,一行改动,改完了。Ctrl-C。四个 worker 进程重启,十几秒里所有会话的 WebSocket 断开,前端显示"连接已丢失",用户明天早上会看到一堆中断的对话。于是"先发布吧,明天再修"成了常态。
真正难的不是改代码。是改代码时不把状态弄丢。
你的会话对象内存里有两样东西:一份对话历史(数据),一个分词器实例(代码)。前者属于用户,不能丢;后者属于你的这次提交,需要换。这两样东西现在死绑在同一个进程里,所以换一个必须重启另一个。
chord 做的就是把这根绑线剪断。剪断之后,换代码不需要换对象,换对象不需要停服务。它的 README 三句话就是这件事的全貌:
Chord builds applications out of objects that live in several processes (a server, workers, browser tabs) and can be hot reloaded while they run.
对象、多进程、热重载。三者不是并列关系——前两个是第三个的前提。
只有当"对象"和"调用它的代码"分开住,换代码才不需要换对象; 只有当"状态"和"状态的所有者"分开住,换代码才不需要停服务。
50,101 行,216 个文件。这是仓库里最大的包,也是 durable 唯一非可选的依赖。
接着 M11 往下说:那边用 generation 交接,让旧循环把控制权交给新循环;
chord 的 reload 是同一件事的另一种实现——换代码,不换状态。
先给结论,好在细节里找不到方向:整个包的努力都花在一件事上—— 让"引用"活得比"实现"长。 对象可以死,实现可以换,但调用方手里那个引用必须一直是有效的。 下面每一个设计,都是在为这句话补漏洞。
零、读这章之前,你需要先知道四件事
这四个词读源码时绕不开,但它们都不是和弦自己的发明,而是分布式系统里的通用概念:
租约(lease):不是"永久占有",而是先签一段时间的使用权,到期自动失效。 两阶段提交:先"准备"(谁都能反悔),再"提交"(不可反悔)。 幂等:同一个请求发两次,结果和发一次一样。 祖父亲条款:老的不动,新的按新规矩。
没有它们会怎样:把热重载当成"重启进程",于是看不懂为什么正在跑的请求没被杀掉—— 它们靠的是"新旧两个版本同时活一会儿",不是靠杀进程。
本书哪里用到:§一 五个词(本章自己的术语),§七 提交协议。
一、五个词
先把术语钉死,后面全部靠它们。这五个词里只有一个(reload)是 chord 自己发明的。
| 词 | 一句话 | 落在哪 |
|---|---|---|
| object | 一个地址上的状态 + 代码,按需创建 | object.ts(1,932) |
| reference | 调用方拿到的永远是引用,不是对象 | RefImpl(object.ts:759) |
| principal | 每个对象知道自己在为谁服务 | ctx.principal |
| state | 可观察的 JSON:先快照,后增量 | state.ts(424) + delta/ |
| reload | 换代码,不换状态,不停服务 | reload.ts(724) |
README 里还有一句容易被跳过的话,它其实是这五个词的总纲:
Everyone gets a reference, never the object. References work the same locally and across processes, and survive reloads.
"survive reloads"——引用能活过一次热重载。这句话是整章要解释的东西。
1.1 它和 Actor 差在哪
长得像 Actor:有地址、有状态、有消息。差别在两处,都很关键:
- Actor 的方法调用是消息,发出去就不保证回。
chord的方法调用是await,有返回值、 有异常、有取消。 - Actor 的代码是固定的。
chord的对象在自己的生命周期里可以换三次代码。
第一处让它能当普通 API 用;第二处让它能在生产环境里改自己。
把三个参照物摆在旁边,位置就清楚了:
| 普通 RPC 框架 | 插件宿主 | chord |
|
|---|---|---|---|
| 调用形状 | 函数调用 | 不提供 | 函数调用 |
| 状态归谁 | 服务端私有 | — | 对象自己,可订阅 |
| 换代码 | 重启 | 重启宿主 | 不重启 |
| 跨进程 | 是 | — | 是,同一套引用 |
第二行和第三行是它真正的差异:状态是公开可观察的,并且不跟着代码版本走。
1.2 durable 站在哪一层
M11 说过 durable 的 storage/store/ 是两个 SQL 后端共享的一层。那一层不是它自己写的:
// durable/src/storage/store/storage.ts:14-15} from "@earendil-works/chord/next";import type { SqliteExecutor } from "@earendil-works/chord/sqlite";commit.ts / documents.ts / queries.ts / tables.ts 四个文件都从 chord/next 拿东西。
所以层级是:
durable 的调度器与任务 | +-> durable 的 storage/store/(文档表、提交、查询) | +-> chord/next 的 store(文档寻址、历史、退休) | +-> chord/sqlite(可移植的 SqliteDatabase)chord 不是"又一个库",是 durable 的地基。 M11 讲的那套提交语义,
最后是这一层的 SQL 在保证。
二、包的地图
chord/src/ 216 个文件 / 50,101 行,按目录切:
| 目录 | 文件 | 行数 | 是什么 |
|---|---|---|---|
| 根层 | 25 | 10,438 | v1 API:对象、契约、主机、热重载、链路 |
next/ |
146 | 28,733 | v2(实验):契约、文档、存储、任务、状态 |
next-node/ |
29 | 5,743 | v2 的 Node 侧实现 |
delta/ |
7 | 3,976 | 事务性 JSON 跟踪器与线格式 |
telemetry-sqlite/ |
2 | 536 | 遥测的 SQLite 落盘 |
sqlite/ |
6 | 513 | 可移植的 SqliteDatabase |
context/ |
1 | 162 | 取消、遥测、调用值 |
注意最后两行的对比:sqlite/ 只有 513 行,telemetry-sqlite/ 536 行。
一个包里的"存储抽象"可以比"存储的实现"还小——因为真正的实现挂在 peer 依赖上。
2.1 v1 根层的七个大文件
| 文件 | 行 | 职责 |
|---|---|---|
object.ts |
1,932 | 对象、引用、生命周期、闸门 |
connection.ts |
1,328 | 一条链路上的引用、调用、状态单元 |
host.ts |
1,306 | 主机:服务表、代码版本、根、插件 |
reload.ts |
724 | 一次热重载的 prepare / gate / commit |
remote.ts |
659 | 远端引用的代理与转发 |
watch.ts |
493 | 可观察值的订阅与快照 |
manager.ts |
444 | 子主机进程的托管 |
object.ts 一个人占了根层的 18%。它不只是"对象",是引用的生命周期账本——
后面 §三 会看到,一个 ObjectImpl 上有六种引用持有者。
2.2 next/ 是什么
src/next/index.ts 第一行就写了:
// Chord v2 (`@earendil-works/chord/next`, experimental): every layer's API// for apps, and the store's surface for adapters (Durable's `StoreStorage`),// marked internal.v2 是"文档 + 存储"的重写,v1 是"对象 + 热重载"。两者并存,通过不同的导出路径区分:
// package.json 的 exports(节选)".": v1 顶层"./next": v2"./delta": 独立导出"./sqlite": 可移植 SQLite九个 v2 子目录,行数分布很不均匀:
| 子目录 | 文件 | 行数 |
|---|---|---|
host/ |
31 | 8,846 |
store/ |
34 | 6,117 |
jobs/ |
10 | 2,495 |
documents/ |
13 | 2,222 |
link/ |
12 | 2,052 |
contracts/ |
13 | 1,835 |
state/ |
7 | 991 |
registries/ |
7 | 853 |
data/ |
8 | 574 |
store/ 就是 M11 §5.7 那次提交的落点。它和 v1 的 object.ts 几乎一样重,
说明在 v2 里"文档与提交"取代了"对象与引用"成了中心。
本章讲 v1——因为"改代码不用重启"是 v1 的能力,v2 还没接上热重载。 v2 只在 §九 和 §13.2 出现。
三、object:地址 + 状态 + 代码
3.1 一个对象是怎么被定义的
契约先写,实现在后。contract.ts 的 remote 描述"这个类型长什么样、住在哪台主机":
// contract.ts:214-247(签名节选)export function remote<const D extends RemoteDef>( name: string, def: D,): RemoteContract<D>;RemoteDef 有四个必填部分(contract.ts:102-108):
| 字段 | 作用 |
|---|---|
version |
契约版本,用于兼容性判定 |
input |
创建对象时的输入 schema,也决定它住在哪台主机 |
host |
hostNamed("server") 或 hostFamily("session:", "session") |
variants |
变体表,每个变体有自己的 state 与 methods |
实现挂在主机上(host.ts 的 serve)。同一个契约,不同的主机可以给出完全不同的实现——
因为 host 字段决定了"这个类型的对象只在某台主机上创建"。
hostFamily 更细:它按输入里的某个字符串字段路由。
// contract.ts:72-76export function hostFamily<const K extends string>( prefix: string, key: K,): HostFamily<K>;hostFamily("session:", "session") 的意思是:输入里的 session 字段是 "abc",
这个对象就住在 session:abc 这台主机上。前缀 + 输入字段 = 主机名,纯数据推导,
所以每台主机都能独立算出"这个对象该不该归我"(resolveHost,contract.ts:84)。
3.2 self:工厂能声明的五样东西
工厂的第二个参数是 self,它是唯一能"声明"的入口。Self 接口(object.ts:155-197)
有五个方法,每个都用"重载时要怎么处理"来定义:
| 方法 | 声明什么 | 重载时 |
|---|---|---|
state(name, schema, init) |
一个可观察的 cell | 保留值(升版则迁移) |
derive(...) |
一个同步投影 | 每次重建 |
resource(...) |
一个依赖(文件、连接) | 保留,exclusive 则替换 |
on(...) |
一个订阅 | 重新订阅 |
task(...) |
长期工作 | 重启 |
三行"每次重建"、"重新订阅"、"重启",两行保留。这条分界线不是随意的:
- 状态是数据。数据没有代码版本,只有语义版本。所以它跳代。
- 派生是投影。用新代码重算一遍最准;保留旧值反而可能和新的输入对不上。
- 订阅是连接。旧监听器闭包着旧代码,必须换掉。
- 任务是动作。让旧代码的动作继续跑,等于没重载。
换成一句话:跨代的是数据与外部句柄,不跨代的是行为。
resource 那一行的例外很关键——exclusive: true 的资源(比如一个写锁)不能两代共用,
必须等闸门。这就是 §6.2 里第二种进闸门的理由。
3.3 引用不是对象
这是全章第一个反直觉的点。调用方手里的那个东西是个 Proxy:
// object.ts:758-759/** One reference on an object. Exposed through a Proxy so members * bind late to the current implementation. */export class RefImpl {注释里 "bind late to the current implementation" 是热重载能工作的第一个前提。 把这句话拆开:
- 引用上存的是地址,不是函数指针。
- 每次调
ref.increment(...),代理才去问"这个地址现在由哪份代码实现"。 - 所以换掉实现之后,同一个引用下一次调用的就是新代码。
如果引用在创建时就抓住了 increment 的函数对象,热重载就必须重新分发所有引用——
那就等于重启。
引用的解引用还有一层:bind(contract.ts:321)在"消费者契约"和"提供者实现"之间
插适配器。所以引用不是直接拿到实现,而是拿到"按我的契约版本翻译过的视图"(object.ts:880)。
3.4 principal:同一个地址,两个对象
README 说:
Every object knows its principal: an owner and a guest get different objects, with different methods.
这句话容易被当成权限校验。它比权限更强:owner 和 guest 拿到的是两个不同的对象实例,
只是共用一个地址。各自的工厂调用会收到不同的 principal,返回不同的变体。
// contract.ts:417-424(节选)export type ImplementationOf<C, P = unknown> = C extends RemoteContract<infer D> ? ... : never;infer D 是条件类型里"就地取一个类型变量"的写法:句子读作"如果 C 长得像
RemoteContract<D>,就把那个 D 记下来"。读源码时见到 infer,后面跟的一定是
一个待推导的名字。
与 as 的差别:infer 是从结构反推,推不出来就落到 never,编译器替你算;
as 是你向编译器断言,真错了也没人拦,运行时才炸。附录 B §2.5 有对比。
P 就是应用自己定义的 principal 类型。factory 的签名里它是个参数(object.ts:78),
于是"给谁创建"是一个构造期的输入,不是每次调用都重新判断的运行时检查。
好处很直接:owner 看到的方法集可以比 guest 多,而且多出来的方法在 guest 那侧根本不存在—— 不是调了被拒绝,是代理上就没有这个成员。
3.5 生命周期:谁还拿着引用
Lifetime 只有两个值(object.ts:75):
| 值 | 含义 |
|---|---|
"referenced" |
没有引用就回收,回收前还能再等 linger 毫秒 |
"host" |
和主机同生共死,永不回收 |
linger(object.ts:51)是给"引用刚放掉、马上又要"的场景留的缓冲。
默认值由服务选项决定,不是硬编码。
真正复杂的是谁在持有引用。RefOwner 有六种(object.ts:560):
| owner | 谁 | 会不会挡住热重载的闸门 |
|---|---|---|
"object" |
另一个对象 | 会 |
"call" |
一次正在进行的调用 | 会 |
"host" |
主机自己 | 会 |
"external" |
宿主代码直接持有 | 会 |
"connection" |
另一台主机 | 会(集群一起重载) |
"client" |
浏览器 | 不会 |
最后一行是 §六 的关键:浏览器的引用不阻塞热重载。它拿不到新代码,
提交之后会被标成 upgrade_required,让前端自己决定刷新。
这一条是整个设计里最尖锐的取舍,值得单独说清楚。
你可能会想: 既然如此,为什么浏览器不能像服务端引用一样, 重新绑定到新提供方就行?
因为服务端的"重新绑定"有一份同一代代码的主机做中介:新实现就在这台
主机的模块表里,重绑只是一次查表。而浏览器里跑的是你打包发过去的那份代码,
它在 commit 之前就已经下载完毕、已经实例化。主机换了代码,浏览器手里的
Proxy 也找不到对应物——重绑过去也只能绑到旧代码的拷贝。
那让它阻塞闸门呢? 那就是另一条路:浏览器不刷新,重载就不提交。 代价是热重载变成"必须所有标签页都关闭"——很多用户把标签页开着过夜。
reload.ts:424-427 的注释把结论说死了:
/** * Every reference that survives into the new code version must bind to * the new provider. Browser references don't block a reload: after the * commit they get `upgrade_required` instead. */"don't block" 和 "get upgrade_required instead" 是同一个决定的两半:
服务端的连续性,优先于客户端的连续性。 客户端被告知世界变了,
但服务端永远不用为了一个没关的标签页而停在旧代码上。
这也是一个值得抄走的模式:遇到"远端无法跟随"的情况,
不要让远端阻塞本地——给它一个可识别的错误码,让它自己决定何时追上。
错误码的名字里已经包含了这条设计意旨:upgrade_required,不是 upgrade_failed。
一个对象什么时候死?object.ts:1645 的注释写得很短:
"No references and no invocations: dispose (after linger for a live object)."
两个条件同时成立才回收——没有引用,而且没有正在跑的调用。
少一个都不行,因为"引用放掉了"和"活干完了"是两件事。
3.6 根:租约的来源
上面那张表里的 "call" / "host" / "external",在代码里全都统一成一个概念:租约。
object.ts:1045 有一行不起眼但承重的字段:
readonly leases = new Map<string, number>();key 是根 id,value 是代码版本号。 一行同时回答了"谁还拿着"和"他手里是第几代代码"。
登记发生在一次调用的入口(object.ts:1533-1542):
if (this.gate !== undefined && !this.gate.grandfathered.has(ctx.rootId)) { // 闸门开着且你不是祖父:排队}if (this.leases.has(ctx.rootId)) return;this.leases.set(ctx.rootId, ctx.codeVersion);this.host.touch(ctx.rootId, this);"根"就是 host.root(async (ctx) => { ... }) 那个作用域。它结束的时候,
沿途碰过的所有对象的租约一起释放(object.ts:1627-1630):
rootEnded(rootId: string): void { this.leases.delete(rootId); // ... if (gate?.grandfathered.delete(rootId) && gate.grandfathered.size === 0) gate.drained();}最后一行把 §6.3 的闸门闭环了:每个旧租约释放时,都在检查是不是最后一个。
跨进程的根要多一步。call 帧带着它(wire.ts:132-133):
/** Absent: the receiving host starts a root (browsers never carry roots). */root: opt(RootRefSchema),root_end 帧负责收工(wire.ts:163-164):
/** The root ended at its origin: its leases on objects end * (sent on every link the root's calls used). */Open({ t: lit("root_end"), rootId: Name }),"sent on every link the root's calls used"——根得在它走过的每一条链路上各通知一遍。 因为租约是分散在多台主机上的,没有任何一条链路知道全部。
还有一个例外(object.ts:1550):
if (ctx.rootId.startsWith("task:")) return;任务的根不登记租约。 因为它们会被 stopTasks() 直接停掉(§6.3),
用租约挡只会让闸门等一个不会自己结束的根。
于是"引用能活过重载"可以拆成三层,每层一个机制:
| 层 | 靠什么 |
|---|---|
| 引用不失效 | 引用存地址,成员晚期绑定(§3.3) |
| 对象不销毁 | 有租约在,就不算"无人引用" |
| 闸门知道等谁 | 租约的 key 就是根,value 是代码版本(§6.3) |
四、state:可观察的 JSON
状态不是"字段",是"订阅源"。区别在于:读字段不会告诉你它变了,订阅会。
4.1 一个 cell 是怎么声明的
// README 的 Quick start(节选)const count = self.state("count", num(), 0);三个参数:名字、schema、初值。self.state 返回的东西能读、能改、能订阅。
它的选项里有一个容易被忽略的字段(object.ts:133-137):
export interface StateOptions<T> { /** The meaning of the cell's value (default 1). * A reload that raises it runs `migrate`. */ version?: number; ...}version 是"这个值的语义版本",不是包版本、不是契约版本。默认 1。
§六 会看到它为什么存在:热重载时,只有 version 提高了的 cell 才需要迁移和闸门。
一个改了方法体、没改状态语义的 reload,根本不需要迁移。
4.2 快照 + 增量
远端看到的状态是两段式:先一个 snapshot,然后是一串 ops。
// wire.ts:148-158Open({ t: lit("state"), hold: Id, m: Name, /** `snap`/`reset` without `value`: the value is `undefined`. */ as: union([lit("snap"), lit("reset"), lit("ops"), lit("error")]), value: opt(unknown()), /** Encoded with the stream's delta encoder; the decoder * validates each op. */ ops: opt(List(List(unknown()))), error: opt(WireErrorSchema),}),四种子类型,各管一件事:
as |
什么时候用 |
|---|---|
snap |
第一次,或订阅被重置 |
ops |
之后每次变化 |
reset |
上游换了(转发链断了),必须整份重来 |
error |
读这个成员失败了 |
为什么要区分 snap 和 reset?因为两者都带完整值,但语义不同:
snap 是"这就是当前值",reset 是"之前的增量作废了"。收到 reset 的消费者必须
丢掉本地缓存,不能尝试合并。
4.3 replicatedState 有三种形态
state.ts 导出三样东西,名字很像,用途完全不同(state.ts:404-413 的三个重载):
| 形态 | 谁来写 | 典型场景 |
|---|---|---|
MutableReplicatedState |
本地 | 对象自己的状态,本机是权威 |
AttachedReplicatedState |
上游一个源 | 转发别人的状态,自己只读 |
ReplicatedState(只读) |
没人 | 交给消费者 |
AttachedReplicatedState 的注释说得很克制(state.ts:85-90):
"A synchronously hydrated publication-only state backed by one source attachment"。
同步水合——订阅的那一刻值已经在了,不需要等一次异步往返。
代价是它必须有一个"源"。源的帧是有序的(state.ts:45-51):
// state.ts:45-51(节选)export interface ReplicatedStateSourceFrame<T> { /** Monotonic source cursor. The first frame after a snapshot must * be `snapshot.cursor + 1`. */ cursor: number; readonly value: T; readonly ops: ...;}cursor 必须严格 +1。跳号就是源坏了,消费者不应该猜。
为什么要有三种形态,而不是一个可变对象?因为"谁有权写"是一个必须显式回答的问题:
| 形态 | 写权在谁 | 类型上有什么 |
|---|---|---|
MutableReplicatedState |
本机 | change() 等写方法 |
AttachedReplicatedState |
上游一个源 | 只有读与订阅 |
ReplicatedState(只读) |
没人 | 连"能改"都不暴露 |
这是类型上的减法:消费者拿到的类型里没有写方法,就写不出"顺手改一下"的代码。 和 §3.4 里"guest 的代理上就没有 owner 的方法"是同一个手法—— 把权限做在类型里,而不是做在运行时检查里。
五、contract:运行时值,不是类型
这是 chord 和绝大多数 RPC 框架最大的分歧点。
5.1 契约有 JSON 形态
contract.ts 里有一个 DescriptionSchema(:139-151),契约能被序列化成 Description:
export type Description = Static<typeof DescriptionSchema>;而且 hold 帧里就带着它(wire.ts:99-100):
/** The consumer's contract token; the provider checks that it covers it. * Remote tokens carry `host`. */token: DescriptionSchema,调用方把自己的契约发给提供方,提供方判断"我能不能覆盖你"。这就是 coverage
(contract.ts:284):
Returns why
providerdoes not coverconsumer, or undefined when it does.
注意返回值:不是布尔,是失败原因。这个选择让错误信息不用另写一遍。
remote 不是唯一的契约形状。contract.ts 里有三种,切的是"这些成员能不能跨链路":
| 构造 | 能跨链路吗 | 需要什么 |
|---|---|---|
remote(name, def) |
能 | version / input / host / variants |
local(name, def) |
不能 | methods 与 state,没有 host |
opaque("name@version") |
不能 | 一个已存在的原生对象 |
local 的 LocalDef(contract.ts:113-127)里没有 host 也没有 input,因为它不需要路由。
而 LOCAL_VARIANT = ""(contract.ts:132)——本地契约只有一个无名变体。
opaque 更有意思(contract.ts:37-41):
/** A native in-process object identified by `name@version` * (local contracts only). */export const opaque = <T = unknown>(id: string): OpaqueSpec<T> => {它把"一个已经存在的对象"包成契约成员,不经过工厂、不经过 serve,
而且只在 local 契约里能用。name@version 这个字符串形状本身就是答案:
它不参与 coverage 那套版本协商,因为它压根不跨链路。
三个构造对应三种边界的远近:跨机器、同进程跨对象、包一层已存在的东西。 写契约之前先回答"它会跨链路吗",选错构造后错的不是类型,是整个生命周期语义。
5.2 同一个版本号不能装两种东西
reload.ts:321 有一条校验,注释只有一句:
/** Same contract version must cover the old description (forgotten bump); * facets' `uses` must bind. */也就是说:如果你改了契约但忘了升 version,热重载会拒绝。
不是警告,是失败。这条规则的动机很实际——忘了升版本是这类框架最常见的 bug,
而它的后果(老消费者按旧 schema 解析新数据)极难排查。
同一个思路在状态里也有(reload.ts:396-397):
else if (!deepEqual(cell.schema, run.decls.cellSchemas.get(name))) throw invalid( "state", `${object.address}: schema of state ${name} ` + "changed without a version bump", );改了 schema 必须升 version,改了就报 invalid。
两条规则合起来是一个原则:版本号是声明,不是装饰。 声明变了就必须动它, 否则系统会替你拒绝。
5.3 accepts:按版本号索引的适配器
版本不兼容怎么办?不是"必须同时升级",而是提供方可以写适配器:
// contract.ts:316-318export type Adapter = ( current: Record<string, unknown>,) => Record<string, unknown>;export type Accepts = Readonly<Record<number, Adapter>>;Accepts 的键是版本号。bind(:321)拿着消费者报的版本去查表:
// contract.ts:321-323export function bind( provider: AnyContract, accepts: Accepts | undefined, consumer: AnyContract,): Adapter | undefined;于是"老前端连新后端"有了第三种解法:不改前端,后端加一个 accepts[3] = ...。
这和 HTTP API 的版本化是同一个思路,但落在方法返回值的形状上,粒度更细。
三条路一起看,才能理解 chord 的兼容性模型:
| 情况 | 手段 |
|---|---|
| 只加不改 | 升 version,什么都不用做 |
| 改了返回值形状 | 提供方写 accepts[v] 适配器 |
| 状态语义变了 | 升 cell 的 version + 写 migrate |
三张表,没有第四种。
六、hot reload:一次 reload 到底做了什么
这是全章的核心。先看总入口。
6.1 prepare() 的九步
// reload.ts:205-224async prepare(): Promise<void> { try { await this.waitForRetirement(); this.load(); this.checkProviders(); await this.prepareAll(); // From here new objects of changed types are rejected // (upgrade_conflict, retryable) until commit or abort, // so the candidate set is final once the activations // already in flight have been prepared. this.host.gating = this.changed; await this.withDeadline( this.prepareAll(), "activations in flight did not finish", ); this.checkRefs(); this.tables = this.host.buildTables(this.entries()); await this.gate(); this.#alive(); this.#stage(); } catch (error) { await this.rollback(); throw reloadError(error); }}九步,分三类:
| 步 | 做什么 | 失败了会怎样 |
|---|---|---|
waitForRetirement |
等上一代代码退休 | 超时就强制退休 |
load |
加载新模块 | 旧代码继续跑 |
checkProviders |
新服务表能不能覆盖旧契约 | 同上 |
prepareAll |
对每个活对象跑一遍新工厂 | 同上 |
host.gating = changed |
候选集冻结 | — |
prepareAll 第二遍 |
跑到不动点(在飞行的激活也要准备完) | 同上 |
checkRefs |
每个活着的引用都要能绑到新提供方 | 同上 |
gate |
闸门:等老根结束 | 超过 gateDeadline 则 abort |
#stage |
提前订阅新监听器(缓冲事件) | 同上 |
第五步值得单独说。host.gating 一设,变更类型的新对象就被拒了——
错误码是 upgrade_conflict,而且标着可重试。为什么必须拒?
因为候选集一旦还在长,prepareAll 就永远追不上它。
注释里那句 "so the candidate set is final" 是一个设计决定: 宁可变重载期间拒绝新建,也不要一个永远在变的集合。
6.2 只有两种变更需要闸门
这是整章最值得记住的一条。prepareObject 里,需要闸门的理由(reasons)只有一个来源:
状态语义版本提升 和 独占资源替换。
// reload.ts:388-398// Each cell carries its own version: a raised one gates and// migrates, a schema change without one is refused.for (const [name, cell] of run.decls.cells) { if (object.decls.cells.get(name) !== cell) continue; const from = object.decls.cellVersions.get(name) ?? 1; const to = run.decls.cellVersions.get(name) ?? 1; if (to < from) throw invalid( "state", `${object.address}: version of state ${name} ` + `lowered from ${from} to ${to}`, ); if (to > from) candidate.reasons.push(`state ${name} version ${from} -> ${to}`); else if (!deepEqual(cell.schema, run.decls.cellSchemas.get(name))) throw invalid( "state", `${object.address}: schema of state ${name} ` + "changed without a version bump", );}三行分支,三种结局:
| 版本比较 | 结局 |
|---|---|
to < from |
抛 invalid——版本号不许降 |
to > from |
进闸门,待会儿迁移 |
to === from 但 schema 变了 |
抛 invalid——改 schema 必须升版本 |
另一处是独占资源(reload.ts:399-409):新跑的工厂里有 exclusive 资源,
或者依赖了一个被推迟的资源,就推到 atGate;旧的那个如果还开着,落到 replaced。
然后:
if (deferred.size > 0) candidate.reasons.push("exclusive resource replaced");结论很硬:改方法体、改派生函数、加新方法、加新状态字段——这些都不进闸门。
于是"热重载看起来毫不费力"有了机制上的解释:不是它把难事藏起来了,是很难的变更本来就少。 大多数提交只是改了一个函数体,而那些对象仍然可以直接换代码, 一根引用都不用动。
那两条路径在代码里是分开跑的(reload.ts:410-421):
await object.open( run.created.resources.filter((resource) => !deferred.has(resource)), run.created.refs, this.abort.signal,);await object.waitHydrated(run);// Cells this reload adds read their first value once the new// resources are open (gated objects: at the gate); the// derivations over them are checked after.if (candidate.reasons.length === 0) { await object.initCells(run, this.abort.signal); dryRun(candidate);}三段各管一件事:
open(...)开的是不需要闸门的资源。deferred里那些(独占的、或依赖了被推迟的资源的) 得等闸门。waitHydrated(run)等的是引用水合:新工厂拿到的远端成员,得先有值。- 最后那个
if是分水岭:只有不进闸门的对象在这里初始化 cell 并跑dryRun。
进闸门的对象要等到 gate() 之后才做这两件事——因为迁移还没跑,新 cell 还读不出值。
所以"闸门"这个名字有两层含义:它既是一道队列,也是一个阶段边界。 闸门之前的对象只做到一半,闸门之后的才是完整的新版本。
6.3 闸门:祖父条款
进闸门的那一小拨对象,要等什么?
// reload.ts:457-468async gate(): Promise<void> { this.gated = [...this.candidates.values()].filter( (candidate) => candidate.reasons.length > 0 && candidate.object.status === "live", ); const drained = this.gated.map(({ object }) => { const grandfathered = new Set(object.leases.keys()); return new Promise<void>((resolve) => { object.gate = { grandfathered, queue: [], drained: resolve }; object.stopTasks(); if (grandfathered.size === 0) resolve(); }); });grandfathered 是"祖父条款"——已经在旧代码上持着租约的引用。
这些引用不会被赶走,它们手里的活儿跑完才算数。
object.gate 里同时放了三样东西:
| 字段 | 作用 |
|---|---|
grandfathered |
允许继续跑完的租约集合 |
queue |
新调用的缓冲区——不拒绝,排队 |
drained |
全部跑完时 resolve |
再加 stopTasks():旧的长任务直接停。于是"in flight 的活儿跑完旧代码"
就有了精确含义:方法调用能跑完,长期任务不能。
这个区别不是随意的。方法调用有调用方在等结果,砍掉就是错误; 长期任务是自由的,停掉之后可以在新代码里重新开始。
闸门等的时候,object.ts:1538 那个 #touch 在记账:
/** Records that the root of `ctx` touched this object (a reload gate * grandfathers it). */新来的根不算祖父。 只有已经碰过这个对象的根才被放行,新根得等闸门开。
6.4 commit():一次同步安装
// reload.ts:561-582/** * Publishes the new code version in one synchronous step. Everything * fallible ran in prepare (factories, opens, migration and derivation * checks against the prospective schemas, listener subscriptions), so * this only installs. * ... */commit(beforeStart?: () => void): ReloadReport { try { return holdPublications(() => { const report = this.#publish(); beforeStart?.(); for (const start of this.#starts.splice(0)) start(); return report; }); } catch (error) { this.host.fail(error); throw reloadError(error); }}注释第一句是全章最该背下来的一句: "Everything fallible ran in prepare, so this only installs."
所有会失败的事——跑工厂、开资源、迁移并校验、订阅监听器——都在 prepare 里做完了。 commit 只剩下把新版本挂上去,所以它可以是同步的。
为什么同步那么重要?因为"同步"等于"没人能插进来"。
一旦 commit 里有一个 await,就会有代码在"旧版本已卸、新版本未装"的中间态里跑。
#publish 只动三个字段(reload.ts:587-594):
const previous = host.current;const next: CodeVersionState = host.pending!;host.pending = undefined;host.codeVersions.set(next.id, next);host.previous = previous;host.current = next;换代码就是换一个指针。 对象、引用、状态全没动,只有一个 host.current 指向了新版本。
6.5 三件事的顺序,为什么不能乱
commit 里那三行看着像收尾,其实是一个顺序约束:
#publish() 挂上新版本(观察者通知被 holdPublications 攒住) |beforeStart?.() 协调者把 commit 帧发给子主机 |#starts 新版本的任务、注册、监听器才开始注释(reload.ts:571-573)说得很具体:
没有这一步,"this code version starts"的东西可能先到子主机。
换成大白话:先让所有人知道新版本存在,再让新版本开始干活。 否则子主机可能收到一条"新版本发起"的消息,而它那边还不知道有个新版本。
6.6 三种失败,三种结局
| 失败在 | 处理 | 后果 |
|---|---|---|
| prepare 里 | rollback() |
旧代码继续跑,抛 reloadError |
| 协调者中途喊停 | #alive() 抛 aborted |
同 rollback |
| commit 里 | host.fail(error) |
主机终态,不再接任何活 |
第三种是整套设计里最狠的一处取舍。注释(reload.ts:564-565)写着:
"the code version is half-published: the host fails terminally and admits no more work"。
为什么不回滚?因为 commit 的设计前提是"这里不会失败"。真失败了,说明有个假设破了, 此时磁盘上的状态处于一个谁也没设计过的形状。 宁可整台机器停掉让人来查,也不要带着半装版本继续对外服务。
这和 M11 里"预留阶段抛错就整个 Session 判死"是同一个态度(M11 §5.1 的 #failSession)。
#alive()(reload.ts:240-242)是第二种的实现细节:
#alive(): void { if (this.rolledBack) throw new ChordError("aborted", "reload aborted while preparing", { reason: "aborted", });}它在 prepare 里每一个 await 之后都调用一次。因为 abort 是异步到来的,
只能在每个可能让出執行权的位置检查。
6.7 旧代码什么时候退休
主机同时持有两个代码版本(reload.ts:259-263):
Retires the previous code version before loading the next one (a host keeps two). Waits until its roots ended and, on a child host, its parent retired it too (
retireframe), at mostretireDeadline. Past the deadline it is retired anyway: its remaining roots are aborted first and get a short grace to stop, so they see cancellation before the resources only that code version used are closed; their next call issuperseded.
三个细节:
- 只留两个。不是 n 个。还在跑上上代的根,说明它已经跨了两轮 reload,不正常。
- 先给取消信号,再关资源。顺序反了,那些根会在资源已关的情况下继续跑。
- 下一次调用是
superseded。不是gone——对象还在,只是你手里那个代码版本没了。
superseded 这个错误码本身就是给"热重载了,你的调用被跳过了,重试就好"准备的。
它和 upgrade_required(浏览器引用)是同一类:都是"你没坏,只是世界变了"。
七、集群:五个帧的两阶段提交
单机热重载靠闸门。多主机靠什么?靠投票。
wire.ts:166-182 里有五个专用帧,方向看前缀就清楚:
// wire.ts:166-182(节选)Open({ t: lit("prepare"), reload, codeVersion, plugins, options }),Open({ t: lit("vote"), reload, error: opt(...), report: opt(...) }),Open({ t: lit("commit"), reload }),Open({ t: lit("retire"), codeVersion }),Open({ t: lit("abort"), reload }),| 帧 | 方向 | 作用 |
|---|---|---|
prepare |
父 → 子 | "我要重载,你去准备" |
vote |
子 → 父 | "我准备好了(或拒绝了)",带 ReloadReport |
commit |
父 → 子 | "装" |
abort |
父 → 子 | "撤" |
retire |
父 → 子 | "我不再用这个版本了" |
这是教科书里的两阶段提交,但有一处不一样:协调者的 commit 在自己的准备完成之后、 子机的 commit 之前。
ReloadReport.children(reload.ts:47-51)就是这一步留下的车辙:
/** * Cluster reloads: what each participating child host prepared, by host name * (its vote; the child commits it after the server). Absent for local reloads. */readonly children?: Readonly<Record<string, ReloadReport>>;注释里那句 "the child commits it after the server" 是顺序声明: 服务器先,子主机后。
为什么不能反过来?因为"哪个代码版本算数"由服务器定。子主机先装,就会有一段 "子机已经是 v5、服务器还是 v4"的窗口;而 v5 的对象可能已经开始向 v4 的服务器发调用。
服务器先装,窗口就变成了"服务器 v5、子机 v4"——这个方向是安全的: 新版本声明自己能覆盖旧契约(§5),所以 v5 的服务器可以接受 v4 子机的调用。
八、link:二十三个帧,五个方向
wire.ts 开头有一段注释,是整个协议的目录:
// JSON frames between two hosts (or a host and a client). Ids are chosen by// the side that creates the hold, call or subscription; every frame type has// one direction, so ids never collide:// consumer -> provider: hold, release, call, cancel, sub, unsub, resync// provider -> consumer: shape, gone, result, state// both: hello, ping, pong, bye, root_end, ack// parent -> child: invalidate, prepare, commit, abort, retire// child -> parent: vote一句话概括:每个帧只有一个方向,所以 id 不会撞。( 7 + 4 + 6 + 5 + 1 = 23 个帧)
这是协议设计里最省事的一个决定。双向帧要让两侧各自维护 id 空间, 单向帧就不用——谁创建的谁发包。
| 方向 | 帧 | 数 |
|---|---|---|
| 消费方 → 提供方 | hold release call cancel sub unsub resync |
7 |
| 提供方 → 消费方 | shape gone result state |
4 |
| 双向 | hello ping pong bye root_end ack |
6 |
| 父 → 子 | invalidate prepare commit abort retire |
5 |
| 子 → 父 | vote |
1 |
8.1 hold 是"我要一个对象"
七个消费方帧里,hold 是最重的一个:
// wire.ts:91-114(节选)Open({ t: lit("hold"), id: Id, at: Name, /** The consumer's contract token; the provider checks that it covers it. */ token: DescriptionSchema, input: unknown(), /** A forwarded principal. Honored only on frames from the parent link. */ principal: opt(unknown()), /** The client connection the hold comes from ... */ origin: opt(Name), /** False: no state for this hold until `sub`. */ state: opt(lit(false)), /** The consumer already has values (a re-hold after a link loss). */ again: opt(lit(true)),}),五个字段,各管一个真实场景(token 和 input 必填,其余四个可选):
| 字段 | 场景 |
|---|---|
token |
让我核一下你的契约版本能不能被我覆盖 |
principal |
这是替另一个人建的(只在父链路生效,防止伪造) |
origin |
这是某个浏览器发起的,不算重载参与者 |
state: false |
我只调方法,不要状态 |
again: true |
链路断了又连上,我手里已有值,不急 |
principal 和 origin 那句 "Honored only on frames from the parent link" 是一道安全边界:
只有上级主机能替别人说话。 同级主机转发一个伪造的 principal 会被忽略。
8.2 shape:先给目录,再给内容
状态不是一次性发过来的,而是分成"单元":先一个 shape,然后每个状态成员一个 snap。
// wire.ts:116-124Open({ t: lit("shape"), id: Id, variant: opt(str()), members: List(str()), contract: str(), /** The state members whose snapshots follow this frame; * the consumer applies the shape once they are here. */ state: List(Name),}),四个字段各管一件事:
| 字段 | 作用 |
|---|---|
variant |
这个对象对你给出的是哪个变体(§3.4) |
members |
你这个变体看得见的成员列表 |
contract |
契约指纹,用来确认"我看到的是我以为的那个版本" |
state |
后面跟几个 snap,到齐了才应用 shape |
最后一行是最讲究的:shape 要等它的快照都到齐才生效。
否则客户端会有一瞬间知道"有个成员叫 count",但它的值还没来——
那一瞬间任何读 count 的代码都会拿到 undefined。
这条规则把"订阅"变成了一个原子动作:要么你什么都没有,要么你有一致的目录加快照。
8.3 三种链路,一种帧
link.ts 里三个实现,接口完全一样:
| 构造 | 跑在哪 | 文件行 |
|---|---|---|
memoryLinkPair() |
同进程 | link.ts:272 |
ipcLink(channel) |
Node 子进程 | link.ts:339 |
webSocketLink(socket) |
跨机器、浏览器 | link.ts:414 |
三个类都继承 BaseLink(link.ts:242 的 MemoryLink 是第一个)。帧的编码、校验、
重传逻辑全在基类里,子类只负责"怎么把一段字符串发出去"。
所以"同进程两个主机"和"跨机器两个主机"走的是同一套代码, 区别只在传输层。测试能跑全链路,原因就在这里。
8.4 64 KB 之后压缩
// link.ts:108-113// whose JSON exceeds `PACK_THRESHOLD` characters is sent deflated. A host// that only relays the frame forwards ...export const PACK_THRESHOLD = 64 * 1024;超过 64 KB 的 JSON 先 deflate 再发。注释里那句 "a host that only relays the frame forwards" 说明了设计意图:中转主机不重新压缩,直接把已经压好的字节转出去。
这是个容易被忽略的细节:状态快照很容易超过 64 KB,而每个中继节点重新压一遍 会是纯浪费。
九、delta:不可变是所有权约定
delta/ 3,976 行,是 chord 里最独立的一块(有自己独立的导出路径 ./delta)。
它的 README 第二段是全包最诚实的一句话:
Immutability is an ownership contract. Nothing is frozen or defensively copied, so an illegal mutation is not detected. It silently corrupts state.
翻译过来:不可变是约定,不是检查。 你毁了约,它不会报错,只会静默地坏掉。
这是一个明确取舍:要零拷贝的性能,就得把正确性交给调用方。
反过来,每一次修改都做深拷贝或者冻结,chord 就不可能在每秒钟几千次状态变更下工作。
9.1 谁有写权
README 里给了一张表(这里只摘五条最常用的):
| 值 | 能改吗 |
|---|---|
传给 track() 的初始值 |
不能。所有权已转移 |
change.state |
能,但只在那个 change 开着的时候 |
| 赋进 draft 的外部对象 | 能。draft 存的是校验过的拷贝 |
tracker.value / prepared.base |
不能 |
apply() 的批 |
被吞了。它把 payload 收进了副本 |
第二行是使用中最容易出错的:change.state 只在 change 期间可变,
prepare() 之后任何一次访问都会抛。这不是防御性检查,是句柄被作废了。
9.2 一次变更的四个动词
// delta/README.md 的示例(节选)const tracker = track(initial); // 所有权转移const change = tracker.beginChange();change.state.output += "done\n"; // 只有这里能改const prepared = change.prepare(); // 句柄作废,产生不可变修订assert(prepared.base); // base + ops = valuetracker.adopt(prepared); // tracker.value === prepared.value关键在 prepare() 的产物:base、value 和 ops。
ops 是一串精确的增量,把它应用到 base 上,必然得到 value。
于是有两件事同时成立:
- 本地直接换
tracker.value(零成本,因为已经是同一个对象) - 远端按
ops重放出同样的值(有成本,但不需要传全量)
applyImmutable(base, ops) 就是远端那一步。它是纯函数:同样的输入永远同样的输出,
不碰 base,不碰 ops,返回一个新值。
9.3 这套东西和热重载的关系
chord 的 cell 值就是这种不可变修订。三个环节因此变得廉价:
| 环节 | 为什么便宜 |
|---|---|
| 迁移(§6.2) | 迁移函数拿到旧值、返回新值,不需要冻结旧值 |
| 快照(§4.2) | 直接发当前修订,不用拷贝 |
| 订阅(§4.3) | 每次变化就是一个 ops 数组,订阅者按需重放 |
一个不可变修订,同时是三个功能的输入。 这是 delta 那 3,976 行真正的价值:
它不是"一个 diff 库",它是 chord 状态层的公共前提。
9.4 积压的批可以一次性重放
applyImmutable 一次一批。链路断开重连时可能积压了几十批,一批一批地应用会产生
几十个中间修订——每一个都不需要,也都不该被看到。
applyImmutableBatches 处理这个(delta/README.md:53-60):
replica = applyImmutableBatches( replica, queuedFrames.map((frame) => frame.ops),);注释里那句 "no intermediate revision is exposed or safe to retain" 是要点: 整个调用共享一个写时复制作用域,所以中间态从来没存在过。
这和 §6.4 的 holdPublications 是同一个手法:把一串变化攒进一个作用域,最后一次性公布。
一个用于重放,一个用于发布;都在利用"不可变"这个前提。
十、完整链路
把前面几节拼起来,一次本地热重载的时序:
reload() | +-> prepare() | | | +-> waitForRetirement 上一代还在吗(retireDeadline, 5s) | | | +-> load 加载新模块,得到新服务表 | +-> checkProviders 新实现能覆盖旧契约吗 | | | +-> prepareAll 每个活对象跑一遍新工厂(记录模式) | | | | | +-> cell.version 提升 -> reasons.push() -> 进闸门 | | +-> 独占资源换了 -> reasons.push() -> 进闸门 | | +-> 都没有 -> 可直接换,一根引用不动 | | | +-> host.gating = changed 候选集冻结(新对象 -> upgrade_conflict) | +-> prepareAll 第二遍 跑到不动点 | +-> checkRefs 每个引用都能绑到新提供方(浏览器除外) | | | +-> gate 只等进闸门的那几个 | | | | | +-> grandfathered = 已在旧代码上持租约的引用 | | +-> stopTasks() 长期任务直接停 | | +-> queue = [] 新调用排队 | | +-> 租约全释放 -> drained(超过 5s 就 abort) | | | +-> #stage 新监听器先订阅,事件先缓冲 | +-> commit() | +-> holdPublications 攒住观察者通知 +-> #publish host.current = 新版本(换一个指针) +-> beforeStart 协调者把 commit 帧发给子主机 +-> #starts 新版本的任务与监听器才开跑 +-> 解散通知 状态、形状、注册表一起公布注意最后四行的顺序。它回答了一个容易被忽略的问题:
为什么新版本不能一起去掉旧版本? 因为还有很多根在旧代码上跑。
两个版本同时活着,是靠 host.previous 和 host.current 两个字段做到的。
十一、工程暗坑
1. 改了状态 schema 不升 version,直接报错。
reload.ts:396-397 是 to === from 但 schema 变了就 invalid。不是警告,是拒绝。
理由很实在:老消费者会按旧 schema 解析新数据,而这类 bug 几乎无法复现。
2. cell.version 不能降。
to < from 直接 invalid(reload.ts:393-394)。降版本意味着"把新数据当旧语义读",
没有任何迁移函数能救。
3. gateDeadline 超时是 abort,retireDeadline 超时是强制执行。
两个都是 5 秒,结局完全不同(reload.ts:26-28)。
闸门里还有人在干活 → 已经太久,放弃这次重载;上一代还有根 → 已经跨了一代,不管了。
4. 浏览器引用不阻塞重载,但会变成 upgrade_required。
reload.ts:424-426 写得很直白:RefOwner 为 "client" 的不算重载参与者。
所以 commit 之后,浏览器手里那个引用下一次调用会拿到这个错误——前端得自己刷新。
5. superseded 不等于 gone。
对象还在,只是你那个代码版本没了。这两个错误码分开,前端才能区分"重试就行"和"没这个东西"。
6. commit 失败没有回滚,主机直接终态。
reload.ts:578-581 的 catch 里是 this.host.fail(error)。
"半装版本"不是一个可以恢复的状态,它只能停机。
7. state: false 的 hold 永远收不到状态。
wire.ts:110-111:这种 hold 只绑方法。想要状态就得再发一个 sub(wire.ts:143)。
而 again: true(:113)是"链路断了又连上"专用,首次 hold 加它只会让状态单元变慢。
8. hostFamily 的主机名是从输入里算的。
输入里的 key 字段一变,"这个对象住在哪里"就变了——但对你来说那是另一个对象:
新地址、新状态、新生命周期。把主机名当目录结构理解会出大错。
9. delta 的不可变没有任何运行时检查。
改了一个 prepared.value 里的嵌套对象,不报错,直接静默污染。
这类 bug 唯一的发现方式是"某个订阅者看到的值和源头不一致"。
10. prepareAll 是两遍,不是一遍。
reload.ts:205-224 里 prepareAll() 出现了两次,中间隔着 host.gating。
第一遍后,准备过程中可能有新对象激活了;第二遍把它们也追上,才能叫"候选集固定"。
11. 三个版本号,各管一件事。
契约的 version(remote 的 def.version)、cell 的 version(StateOptions)、
协议的 PROTOCOL_VERSION = 4(wire.ts:40),改错一个,报的错完全看不懂:
前者报 contract_mismatch,中者报 invalid/state,后者直接断链路。
11.1 十二个错误码,只有两个能重试
errors.ts 只有 77 行,但它是调用方面对失败时的全部词汇。12 个错误码里,
只有两个是可重试的(errors.ts:24):
const RETRYABLE: ReadonlySet<ChordErrorCode> = new Set([ "superseded", "upgrade_conflict",]);| 码 | 什么情况 | 能重试 |
|---|---|---|
superseded |
你的代码版本已被换掉 | 能 |
upgrade_conflict |
重载期间该类型暂停新建(§6.1) | 能 |
upgrade_required |
浏览器引用需要刷新 | 不能,解法是刷新 |
contract_mismatch |
契约不覆盖(§5.1) | 不能 |
invalid |
参数、状态或实现不合规 | 不能 |
not_ready |
对象还没水合 | 可以等 |
gone / released |
对象没了 / 引用放掉了 | 不能 |
not_in_variant |
这个变体没这个成员 | 不能 |
forbidden |
principal 被拒 | 不能 |
aborted |
取消了 | 不能 |
unavailable |
底层坏了 | 看情况 |
这张表真正的价值是那个 retryable 字段(errors.ts:42):
框架直接把"这次失败是不是该重试"算好了告诉你,不用字符串匹配。
还有一行值得记住(errors.ts:1):
"A refused or aborted reload keeps the code of its cause"。
重载失败不会被包成一个笼统的 reload_failed,你会直接看到 contract_mismatch
或 invalid/state——排查时省掉一层嵌套。
十二、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。
chord 的测试不需要额外环境,cd packages/chord 直接跑。六个实验,前五个都只是读。
实验 1:跑一遍热重载的核心用例
cd packages/chordnpx vitest --run test/reload.test.ts判据:全绿。这个文件里每条用例都是一个"变更类型 + 预期结局"的表格。
实验 2:看对象层面的重载
npx vitest --run test/host-objects-reload.test.ts判据:能看到"引用活过重载"的断言——同一个 ref,重载前后调用的实现不同。
这一条就是第一章 "survive reloads" 的可执行版本。
实验 3:看集群的两阶段提交
npx vitest --run test/cluster.test.ts判据:用例里会出现"子机 vote 失败 -> 整次重载 abort"。 把它和 §七 那五个帧对着看。
实验 4:自己触发一次闸门
找 test/reload.test.ts 里任意一个带 state 的实现,把 self.state(...) 的选项
从默认改成 { version: 2 },再跑。
判据:ReloadReport.gated 里多了那个对象的地址。
把 version 改成 1(比原来的小),则 reload() 直接抛 invalid。
实验 5:从教程跑一遍全链路
npx vitest --run test/tutorial.test.ts判据:共 55 个测试文件里,这一个对应 README 的 Quick start(共享待办清单)。 它跑通了,说明契约、主机、引用、状态、链路五个环节都对。
实验 6:把闸门卡死,看两种超时差在哪
在 test/reload.test.ts 里找一条带闸门的用例,把 gateDeadline 改成 1 再跑;
再用同样的方式把 retireDeadline 改成 1。
判据:两件事完全不一样——
gateDeadline太小 →reload()抛aborted,旧代码继续正常服务(走 rollback)。retireDeadline太小 → reload 成功,只是上一代被强制退休,它的根被 abort 掉。
这个对比把 §6.6 那张表的第二行和 §6.7 的最后一个细节同时验证了。
最后一个实验不为验证代码,为验证你自己的理解: 看完这章再读一遍 README 的 Quick start,应该能说出每一行背后发生了几次帧交换。
五句话
如果只记五句:
- 引用活得比实现长。 调用方拿的是
Proxy,成员在访问时才绑到当前实现。 - 跨代的是数据与外部句柄,不跨代的是行为。 state 和 resource 保留,derive / on / task 重建。
- 闸门只等两类人。 状态 schema 升版的对象,和持着独占资源的对象。
- 两阶段提交:先准备(能反悔),再提交(不能)。
prepare跑两遍到不动点。 - 远端不阻塞本地。 浏览器引用不挡重载,换成一个可重试的错误码。
本章小结
- chord 的对象 = 地址 + 状态 + 代码,三样分开存。
- 热重载靠引用存地址不存函数,换实现不用重新分发。
prepare与commit分开,安装就没有中间态。- 只有两种变更过闸门:状态语义版本提升、独占资源替换。
- 集群重载是两阶段提交:一个子机投反对,整次 abort。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| object | 地址 + 状态 + 代码,三样拆开 | §三 |
| state | 可观察的 JSON,版本号带语义 | §四 |
| contract | 运行时值,不是类型声明 | §五 |
| hot reload | 换代不换引用 | §六 |
| 两阶段提交 | prepare 之后才 commit |
§七 |
练习
练习 1(读):§十二 实验 6 里两种超时结果完全不同。 为什么一个回滚、一个继续成功?→ 回 §6.6 的表与 §6.7。
练习 2(改):照 §十二 实验 4 把 self.state(...) 的 version
改成 2 再跑。预期:ReloadReport.gated 里多出那个地址;
改成 1 则 reload() 抛 invalid;回滚:改回默认。
常见误区
- 你会以为 热重载要重新分发引用;实际是 引用存地址,不用重发; 证据 §三、§六。
- 你会以为 状态只是个 JSON 块;实际是 版本号带语义,提升就得过闸门; 证据 §6.2。
- 你会以为 集群重载是各子机各自换;实际是 两阶段提交,一个失败全 abort; 证据 §七。
读完自检
三条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 热重载靠什么成立? | 引用存地址不存函数,换实现不用重新分发引用 | §三、§六 |
prepare 和 commit 为什么必须分开? |
会失败的放一边、不可失败的放一边,安装就没有中间态 | §6.1、§6.4 |
| 哪些变更才需要过闸门? | 只有两种:状态语义版本提升、独占资源替换 | §6.2 |
十三、收束
13.1 三个可迁移的方法
一、要热重载,先让"引用"和"实现"解耦。 引用存地址不存函数,所以换实现不需要重新分发引用。 任何想支持热更新的系统都绕不开这一条:函数指针一旦被拷出去,就只能重启。
二、把"会失败的事"和"不可失败的事"分开。
prepare 装下所有会抛异常的东西(跑工厂、开资源、迁移、校验、订阅),
commit 只负责把指针换一下。于是"安装"变成了一个不会有中间态的动作。
这个分法比"先备份再安装"更强:备份只能事后恢复,而这里压根不需要恢复。
三、闸门要窄,不要宽。 只有"状态语义版本提升"和"独占资源替换"两种变更需要排队,其余全部无缝。 一个把所有变更都当不兼容的系统,每次发布都是一次停服。
13.2 这章的边界
没讲的部分:
next/(28,733 行):v2 的文档与存储层。本章只在 §1.2 讲了它和durable的接缝, 因为 v2 还没接上热重载,讲它会把主线撕成两半。connection.ts(1,328 行):一条链路上引用、调用、状态单元的完整状态机。本章只讲到帧。manager.ts(444 行)、next-node/(5,743 行):子进程托管。只在本章边界处出现。output.ts(410 行)、telemetry-sqlite/(536 行):与主线无关。
一个必须说清楚的数字修正:chord 是 216 文件 / 50,101 行,不是流传的 45,619。
后者只算了 src/ 的一部分。
13.3 下一站
M13 讲 mcp 与 codemode:模型自己写的代码,怎么在一个受控环境里跑。
那里会出现 chord 的第三种用法——不是宿主应用,也不是存储层,而是沙箱的边界。
下一章:M13 mcp + codemode——模型写的代码怎么在受控环境里跑。
本章源码索引
| 文件 | 行数 | 职责 |
|---|---|---|
chord/src/object.ts |
1,932 | 对象、引用、生命周期、闸门、RefOwner |
chord/src/connection.ts |
1,328 | 一条链路上的引用与状态单元 |
chord/src/host.ts |
1,306 | 主机:服务表、代码版本、根、插件 |
chord/src/reload.ts |
724 | 本章核心:prepare / gate / commit |
chord/src/remote.ts |
659 | 远端引用的代理与转发 |
chord/src/watch.ts |
493 | 可观察值的订阅与快照 |
chord/src/manager.ts |
444 | 子主机进程托管 |
chord/src/contract.ts |
436 | 契约、Description、coverage、accepts |
chord/src/state.ts |
424 | replicatedState 的三种形态 |
chord/src/link.ts |
416 | 三种链路与 64 KB 压缩阈值 |
chord/src/cell.ts |
403 | 单个 cell 的值与版本 |
chord/src/wire.ts |
200 | 23 个帧的 schema,协议版本 4 |
chord/src/delta/ |
3,976 | 不可变修订与操作批 |
chord/src/sqlite/ |
513 | 可移植的 SqliteDatabase |
chord/src/next/store/ |
6,117 | durable 的 StoreStorage 建在这一层 |
chord/docs/spec.md |
43 KB | 兼容性、生命周期、重载的规格说明 |
chord/README.md |
268 行 | 五个概念与七个导出路径 |