# hamb

**Repository Path**: deaglebear/hamb

## Basic Information

- **Project Name**: hamb
- **Description**: High-Availability Message Bus
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hamb

**High-Availability Message Bus**：面向低时延、高可用场景的 C++20 嵌入式消息总线 SDK；
SDK 嵌入每个节点进程，多个节点进程组成集群。

hamb 提供多节点强一致复制、选主与故障恢复、UDP 组播/单播、跨集群级联、持久 WAL、
长期归档与无洞回放。默认复制模式是 **All**，默认 ACK 策略是 `all_memory`：一条消息只有在
全部 ACTIVE 成员连续接纳后才提交。任一 ACTIVE 成员停滞都会阻塞提交，直到它追平或被安全移除；
系统不会隐式切换为 quorum。若要求全站断电 RPO=0，须显式使用 `all_disk` 或更严格策略。

> 当前状态（2026-09-17）：内核 UDP 与固定成员集合的进程内逻辑已经闭环，普通构建
> 403/403 用例通过，可进入内核 UDP 目标环境验收，但尚未完成生产签字。包含加速驱动的
> 生产矩阵仍有 F-Stack/RDMA P0；24h soak、跨机性能、目标机房网络与真实断电演练也尚待完成。完整边界见
> [代码完整度审计](docs/code-completeness-audit.md)和[集成测试计划](docs/integration-test-plan.md)。

[English](README.en.md) | [文档索引](docs/README.md) | [详细设计](docs/hamb-detailed-design.md)

## 核心特性

- **强一致复制**：默认全写提交，支持显式 ACK 持久级别、fencing、PreVote/check-quorum、
  新主共同前缀对账和 speculative 尾截断。
- **成员恢复**：固定 `1..cluster_size` 成员集合内支持剔除、追赶和安全再加入；当前不支持
  启动配置之外的新 ID 在线扩容。
- **运行时执行面**：`NodeAgent` 用 Receiver、Consensus、Sender、Callback 四线程和有界队列
  隔离控制面、数据面及业务回调。
- **可靠数据链路**：UDP 组播/单播、NAK/重传、严格在序交付、WAL 追赶、Archive credit 回放，
  Replay 使用独立 pacing 预算，不挤占 Live 流量。
- **跨集群级联**：支持 A→B、A↔B、A→B→C 和 A+B→C，以下游持久 `SourceCursor` 保证
  换主、桥重启和在途请求重播后的幂等。
- **显式传输策略**：部署只选择一个驱动；插件缺失、硬件不可用、join/open 失败或运行期永久
  错误均 fail-fast，不自动切换介质。
- **SDK 交付**：静态库 `hamb::hamb`、公共头和 CMake package；核心不耦合 Horus，公共头不暴露
  `nlohmann/json`。可选加速驱动以独立 `dlopen` 插件交付，默认关闭。

## 构建与测试

要求 CMake 3.20+、支持 C++20 的编译器和 Linux/POSIX 环境。gtest 已 vendor 在仓库中，
默认构建无需 Conan 或网络：

```bash
cmake -S . -B build
cmake --build build -j
./build/test/hamb_tests
```

运行确定性故障矩阵：

```bash
./build/test/hamb_tests --gtest_filter='FaultMatrix.*'
```

24 小时 soak 脚本为 `tools/soak_fault_matrix.sh`。普通、ASan/UBSan 和 TSan 门禁会复用 UDP
端口与组播组，必须串行运行；完整命令及 TSan 排除项见 [AGENTS.md](AGENTS.md)。

## 安装与消费

### CMake install / find_package

```bash
cmake -S . -B build-sdk \
  -DHAMB_BUILD_TESTS=OFF \
  -DCMAKE_INSTALL_PREFIX=/path/to/hamb-sdk
cmake --build build-sdk -j
cmake --install build-sdk
```

消费侧：

```cmake
find_package(hamb CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE hamb::hamb)
target_compile_features(your_app PRIVATE cxx_std_20)
```

配置消费工程时，把安装前缀加入 CMake 搜索路径：

```bash
cmake -S /path/to/consumer -B consumer-build \
  -DCMAKE_PREFIX_PATH=/path/to/hamb-sdk
cmake --build consumer-build -j
```

### Conan 2

Conan 只用于打包分发，构建包时关闭测试：

```bash
cd conan
conan create . --build=missing
```

recipe 自带 `test_package`，会真实链接 `hamb::hamb`，启动单节点选主并发布消息。

## 运行时组件

| 组件 | 职责 |
|---|---|
| `DriverRegistry` | 按显式名称创建内核 UDP 或懒加载可选插件 |
| `runtime::Node` | 选主、定序、复制、成员变更、追赶与 WAL |
| `runtime::NodeAgent` | Node 的四线程产品执行面 |
| `runtime::PublisherClient` | Mode A 租约发布、续租和缺帧重放 |
| `runtime::SubscriberClient` | 严格在序交付、断点重读及实时/回放拼接 |
| `runtime::CascadeNode` | 跨集群桥接、位点恢复和幂等重播 |
| `runtime::ClusterView` | leader、term、committed 快照及换主通知 |
| `runtime::ArchiveNode` / Replay 组件 | 长期录制、保留策略及定向 credit 回放 |

`DriverRegistry` 插件目前只接入 `NodeAgent` 节点间链路；其他 runtime 组件固定使用内核 UDP，
不会因配置了加速插件而暗中形成“部分链路换介质”。runtime wire 默认完整帧上限为 1472B，
默认 V3 业务 payload 上限为 1368B；jumbo frame 必须由所有通信端一致配置并在目标环境验收。

## 可选加速驱动

```bash
cmake -S . -B build-plugins \
  -DHAMB_BUILD_TESTS=OFF \
  -DCMAKE_INSTALL_PREFIX=/path/to/hamb-sdk \
  -DHAMB_WITH_EFVI=ON \
  -DHAMB_WITH_DPDK=ON \
  -DHAMB_WITH_RDMA=ON
cmake --build build-plugins -j
cmake --install build-plugins
```

插件默认均为 OFF，构建为 `libhamb_driver_<name>.so`，安装到 `lib/hamb/drivers/`。仓库内 vendor
SDK 可用于编译和 ABI/安装布局验证，但不能替代真实 NIC、驱动和交换机验收：

- ef_vi：执行模型已补齐，尚未完成 Solarflare/AMD NIC 真机签字。
- F-Stack/DPDK：进程级初始化及多实例 `ff_run` 生命周期未封版，不能用于 `NodeAgent` 生产拓扑。
- RDMA UD：固定端口带外握手与 `NodeAgent` 的发送端 `port=0` 模型不兼容，且 IB SA 原生组播
  join 未实现，不能用于 `NodeAgent` 生产拓扑。

详见[传输模块设计](docs/module-04-driver.md)。

## 文档

- [文档索引](docs/README.md)：11 个模块、运行时组件和文档维护规则
- [现行详细设计](docs/hamb-detailed-design.md)：当前 as-built 架构与一致性机制
- [代码完整度审计](docs/code-completeness-audit.md)：已完成边界、已知限制和生产放行条件
- [集成测试计划](docs/integration-test-plan.md)：L1/L2/L3 用例及 ✅/⏸ 状态账本
- [V2 可靠性计划](docs/hamb-v2-reliability-plan.md)：里程碑历史与剩余环境验收
- [项目交接说明](AGENTS.md)：构建门禁、关键 gotcha 和当前任务

## 许可证

[Apache License 2.0](LICENSE)