Crate crabka_raft 

Metadata Raft quorum for Crabka.

crabka-raft runs a hand-rolled KIP-595 KRaft consensus engine (the kraft::KraftController) over Crabka’s storage (crabka_log) and transport (crabka_client_core). The public entry point is Controller::start, which spawns the engine, opens a TCP listener serving the real KIP-595 RPCs (Fetch=1, Vote=52, BeginQuorumEpoch=53, EndQuorumEpoch=54) plus the Crabka-private observer/forward RPCs, and returns a ControllerHandle for submitting metadata changes and reading the current crabka_metadata::MetadataImage.

Quick start

use crabka_metadata::{MetadataRecord, TopicRecord};
use crabka_raft::{Controller, ControllerConfig};
use std::time::Duration;
use uuid::Uuid;

let dir = tempfile::tempdir()?;
let cfg = ControllerConfig::for_tests(1, dir.path().to_path_buf());
let controller = Controller::start(cfg).await?;

controller
    .submit_change(vec![MetadataRecord::V1Topic(TopicRecord {
        name: "my-topic".into(),
        topic_id: Uuid::new_v4(),
        partitions: 3,
        replication_factor: 1,
    })])
    .await?;

assert!(controller.current_image().topic("my-topic").is_some());
controller.shutdown().await;

Capabilities and boundaries

The controller persists and recovers KRaft metadata records, serves and installs KIP-630 snapshots through FetchSnapshot, publishes the current metadata image to broker tasks, and exposes Crabka-private submit/fetch RPCs for broker and observer integration. KIP-853-style observer bootstrap and auto-join are wired through the broker/controller configuration; the older handle-level add_learner / change_membership compatibility methods still return RaftError::Unsupported. Mixed JVM+Crabka controller quorums are outside this crate’s compatibility target.

Re-exports

pub use handshake::DuplexStream;

pub use handshake::RaftHandshakeError;

pub use handshake::RaftListenerHandshake;

pub use kraft::MetadataFetchSlice;

pub use reconfig::AddVoter;

pub use reconfig::ReconfigOutcome;

pub use reconfig::RemoveVoter;

pub use reconfig::UpdateVoter;

Modules

handshake

Pluggable inbound handshake for the controller listener.

kraft

Hand-rolled KRaft consensus engine (KIP-595 + KIP-996): a pure, deterministic, sans-IO on_event state machine (core) over the QuorumState/Role model, driven by the async controller::KraftController over the log::KraftLog and the real KIP-595 transport wire. This is Crabka’s live metadata consensus engine.

reconfig

KIP-853 reconfiguration coordinator: single-voter add/remove/update with safety guards.

Structs

AppData

What we ask Raft to replicate. A batch of MetadataRecords so submit_change can group related records (Topic + N Partitions) in a single committed entry.

AppDataResponse

Controller

Zero-sized factory for ControllerHandles.

ControllerConfig

ControllerHandle

Handle returned by Controller::start. Owns the live KraftController engine and the listener task. Drop is NOT a clean shutdown — call Self::shutdown (or Self::cancel) to drain the listener + stop the engine before the runtime is torn down.

CrabkaMetadataFetchRequest

CrabkaMetadataFetchResponse

CrabkaSubmitChangeRequest

Forward-to-leader payload. Body is opaque wincode bytes representing the Vec<MetadataRecord> to apply; the controller layer owns the serde details so the wire module stays metadata-agnostic.

CrabkaSubmitChangeResponse

Node

KIP-853 voter node identity used by controller membership.

PlaintextDialer

Default no-op dialer: opens a raw TcpStream via Connection::connect. Used when the broker hasn’t injected an InterBrokerClient-backed dialer (legacy PLAINTEXT path).

QuorumState

Crabka-native view of the controller’s current quorum state. Surfaced by ControllerHandle::quorum_state for the broker’s DescribeQuorum admin handler so callers don’t depend on engine internals directly.

SnapshotSlice

A contiguous byte window of the latest metadata .checkpoint, returned by ControllerHandle::read_snapshot_range to back the broker’s FetchSnapshot handler.

Enums

BootstrapMode

Bootstrap orchestration for a freshly-formatted controller node.

RaftError

SnapshotRange

Outcome of ControllerHandle::read_snapshot_range. The broker’s FetchSnapshot handler maps each variant to its Kafka error code: NoSnapshot → SNAPSHOT_NOT_FOUND, OutOfRange → POSITION_OUT_OF_RANGE.

Constants

API_KEY_METADATA_FETCH

Observer metadata fetch. The body carries a fetch_offset (KraftLog offset) + max_bytes; the response carries committed __cluster_metadata entries encoded as Kafka record batches, plus log_start_offset / high_watermark and a leader_hint.

API_KEY_SUBMIT_CHANGE

Forward a Controller::submit_change from a follower to the leader. The body is the wincode-encoded Vec<MetadataRecord>; the response carries a single error_code (0 = applied, non-zero = not-leader / metadata-validation).

Traits

OutboundDialer

Outbound dialer the controller hands to the peer sender.

Type Aliases

NodeId