Skip to main content
Tonbo Stream is a stateful, multi-node stream service built for low-latency append-only workloads. It combines a web-native HTTP interface with Raft replication so writes are serialized once, replicated durably, and then served back from local state on every node.

​
Why the system looks this way

The core design goal is to avoid the trade-off between durability and latency that appears when append-heavy workloads are built directly on object storage. Instead of coordinating through optimistic compare-and-swap on a shared object, Tonbo Stream uses a leader-based replication model:
  • The leader serializes writes, so clients do not spin on conflicts.
  • Followers apply the same committed command stream, so reads can stay local.
  • Hot data stays on node-local disks for fast access, while colder data can move to object storage asynchronously.
This architecture is described in more detail in the underlying design notes in stream/docs/raft-durable-stream-rfd.md and stream/docs/raft-state-machine.md.

​
System components

Tonbo Stream has four core layers:
  • HTTP API handles create, append, read, tail, bootstrap, snapshot, and inspection requests.
  • Raft cluster replicates every state-changing command across nodes and commits on majority acknowledgement.
  • Replicated state machine tracks buckets, streams, offsets, visibility of hot or cold payloads, producer dedup state, and snapshot metadata.
  • Storage tiers keep recent payloads hot on node-local storage and allow older data to move into cold object storage without changing stream semantics.

​
Request flow

The write path and read path are intentionally different.

​
Write path

  1. A client sends a write to the current leader.
  2. The leader turns that request into a stream command.
  3. The command is appended to the Raft log and replicated to a majority.
  4. Once committed, the state machine advances the stream tail and publishes the payload as visible.
  5. The leader returns the committed offset to the client.
This is what gives Tonbo Stream stable ordering, exactly-once style producer coordination, and low-latency durability without external locking.

​
Read path

  1. A client reads from any node.
  2. The node looks up stream metadata in its local state machine.
  3. The node serves bytes from local hot state, a published snapshot, or cold references depending on the requested offset.
  4. For live subscriptions, the node can continue streaming new committed entries as they become visible.
For background on how offsets, snapshots, bootstrap, and SSE fit together, see the related concepts pages:

​
Interfaces and route families

The service currently exposes the same stream semantics through multiple route families:
  • Durable Streams routes under /ds/{bucket}/{stream}
  • Legacy routes under /streams/{id}
  • Compatibility routes under /v1/stream/{path}
The /ds routes are the primary surface used throughout this documentation because they map cleanly to buckets and stream identifiers.

​
Current implementation choices

The architecture notes describe a few areas where the current implementation favors delivery speed over theoretical optimality:
  • The Raft log store currently uses RocksDB rather than a custom pure-append segment log.
  • The first production shape is a single Raft group rather than multi-Raft sharding.
  • Cold tiering is optional and asynchronous so the hot path stays small.
Those choices keep the initial system simpler while preserving the core contract: ordered durable appends, replayable reads, and resumable live consumption.