Cursus separates client handling, partition data, coordinator metadata, storage, and cluster ownership while preserving one wire contract in standalone and distributed modes.
| Area | Primary packages | Authority |
|---|---|---|
| Server and protocol | pkg/server, pkg/controller, pkg/protocol |
Framing, authentication, command dispatch, structured responses, redirects. |
| Topics and partitions | pkg/topic |
Partition selection, producer fencing, HWM/LSO, transaction visibility, in-process fan-out. |
| Consumer groups | pkg/coordinator |
Membership, generation, assignment, ownership fencing, durable monotonic offsets. |
| Transactions | pkg/transaction, controller transaction handlers |
Transactional-id sessions, producer epochs, staging, prepared/final decisions, recovery. |
| Storage | pkg/disk |
Segment/index files, buffering, sync, mmap reads, retention, active-tail repair. |
| Cluster | pkg/cluster |
Raft metadata, broker registry, coordinator/leader routing, replication and internal transport. |
| Event sourcing | pkg/eventsource, controller/topic integration |
Aggregate version checks, stream indexes, snapshots, committed replay. |
| SDK | sdk |
Go producer/consumer, redirects, offsets, read isolation, transactions, auth, event store. |
Normal records are owned by a partition leader. Consumer membership/offsets are owned by the selected group coordinator. Transaction lifecycle state is owned by the selected transaction coordinator. Distributed metadata mutations are replicated through the Raft FSM; standalone transaction state is appended to the broker transaction journal before acknowledgement.
A transaction does not collapse those owners into one in-memory object. The transaction coordinator durably registers participants, partition leaders append unresolved idempotent output, the group coordinator applies one fenced multi-topic source-offset set, and commit markers plus the final decision gate read_committed visibility.
| Area | Default |
|---|---|
| Client TCP / health / metrics ports | 9000 / 9080 / 9100 |
| Disk flush batch / linger | 50 records / 50ms |
| Disk sync interval | 500ms |
| Disk write channel | buffered, capacity 1024 |
| Segment / sparse index size | 1GiB / 10MiB |
| Sparse index interval | 4096 bytes |
| Retention | 168h, unlimited bytes, delete policy |
| Partition / consumer / broadcast buffers | 10000 / 1000 / 10000 |
| Distribution | disabled unless configured |
Configuration validation normalizes invalid values. Cleanup policy accepts delete, compact, or delete,compact. Application topics support compaction in standalone and distributed mode; distributed passes run only while the protocol, replica, HWM, lifecycle, and policy safety gate is open. Event-sourcing topics reject compaction.
TopicManager and Topic use read/write locks for registries and partition metadata.DiskHandler.writeCh is buffered; flushLoop, syncLoop, and the retention loop are independent goroutines.committing transactions,Distributed recovery waits for partition materialization by tracking Raft snapshot, commit, log, applied, and target indexes. Its two-minute timeout is a no-progress timeout: forward movement resets the deadline, while a genuinely stalled replay fails startup with the last observed indexes.
The broker stops accepting work, closes client/stream activity, drains partition/storage channels, flushes and syncs active files, persists checkpoints, stops coordinator loops, and closes cluster resources. Shutdown is best-effort under process kill; restart recovery is the correctness path for abrupt failure.
nextOffset and generation/owner fencing,External side effects are never part of a broker transaction. Time/size retention can remove replay history, so applications must monitor offset gaps and choose reset/rebuild policy explicitly.