raft-workers

选主 · 日志复制的可视化沙盒 —— 每个节点都是真正的 Web Worker 进程。

Raft leader election + log replication · Vite 6 · React 19 · TypeScript strict · Tailwind v4 · Vitest

---

一个纯前端的 Raft 协议教学/演示沙盒：每个节点卡片背后是一个独立的 Web Worker（节点进程），节点之间不直接通信，所有 Raft 消息都经由主线程的 NetworkBus 路由、分区与注入延迟/丢包。主线程的 ProcessManager 持有 kill / 恢复节点的权威。

特性

• 真实 Raft 核心（src/core/raft.ts，纯 TS）：随机选举超时、term 单调递增、最多一主、选举限制、日志冲突截断、多数派提交、逐条 apply 为决策。
• Web Worker 即节点：卡片 = 进程；kill / 恢复节点（主群、分区、恢复）。
• 网络总线：节点间只能通过 NetworkBus 互发 Raft 消息，可整网分区（少数/多数）、模拟延迟与丢包。
• 客户端命令：PROPOSE 一条 {client, seq, payload} 命令，交由当前 leader 复制并提交。
• 实时观测：每张卡片展示 term、投票、日志尾、commit/applied、收件时间线，配合全局事件日志。

快速开始

npm install
npm run dev        # 本地开发

脚本

命令	说明
npm run dev	启动本地开发服务器
npm run typecheck	TypeScript 严格类型检查
npm test	Vitest：raft 核心 + 网络 + SimHost 集成测试
npm run build	typecheck + Vite 产物构建（含 worker chunk）
npm run preview	预览构建产物

已验证的行为（确定性集群测试）

• N=3 首轮选举；多条决策在所有存活节点上提交
• kill leader 后重新选举；失去法定人数时孤立 follower 永不成为 leader
• 少数派/多数派分区后愈合；N=5 多数/少数场景
• kill/复活扰动下安全：每个 term 至多一个 leader，term 单调递增
• 选举限制与冲突截断的单元测试

目录结构

public/logo.svg
src/
  core/        Raft 核心纯 TS：消息联合类型、日志、法定人数、故事
  runtime/     ProcessManager、SimulationClock、WorkerPool、SimHost
  network/     NetworkBus：路由 / 分区 / down-gating、全知消息日志
  ui/          React：NodeCard、ControlBar、EventLog
  worker.ts    节点进程入口（只加载 raft-core）

技术栈

TypeScript (strict) · React 19 · Vite 6 · Tailwind CSS v4 · Vitest 3 —— 无后端。