crabka_rebalancer/lib.rs
1//! Crabka rebalancer — Cruise-Control-equivalent partition placement
2//! advisor and executor.
3//!
4//! The crate ingests broker/topic metrics, builds a cluster model, evaluates
5//! goal plugins, and emits executable partition-reassignment plans. The
6//! Connect-RPC API exposes the same analysis and execution path used by the
7//! Kubernetes operator.
8//!
9//! ## Optimization workflow
10//!
11//! ```no_run
12//! use crabka_rebalancer::capacity::BrokerCapacities;
13//! use crabka_rebalancer::goals::{GoalContext, leader_distribution::LeaderDistribution};
14//! use crabka_rebalancer::model::{BrokerView, ClusterState, PartitionView};
15//! use crabka_rebalancer::optimizer;
16//! use crabka_rebalancer::scraper::UsageStore;
17//! use std::sync::Arc;
18//!
19//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
20//! let state = ClusterState {
21//! cluster_id: Some("cluster-a".into()),
22//! snapshot_at_ms: 1_713_000_000_000,
23//! brokers: vec![
24//! BrokerView {
25//! id: 1,
26//! host: "b1".into(),
27//! port: 9092,
28//! rack: None,
29//! },
30//! BrokerView {
31//! id: 2,
32//! host: "b2".into(),
33//! port: 9092,
34//! rack: None,
35//! },
36//! ],
37//! partitions: vec![PartitionView {
38//! topic: "orders".into(),
39//! partition: 0,
40//! replicas: vec![1, 2],
41//! leader: 1,
42//! isr: vec![1, 2],
43//! }],
44//! in_flight_reassignments: Vec::new(),
45//! };
46//! let ctx = GoalContext {
47//! imbalance_threshold_pct: 10,
48//! max_movements_per_proposal: 100,
49//! min_topic_leaders_per_broker: 0,
50//! broker_capacities: Arc::new(BrokerCapacities::default()),
51//! broker_usages: Arc::new(UsageStore::default()),
52//! };
53//! let goal = LeaderDistribution;
54//! let out = optimizer::optimize(&state, &[&goal], &ctx)?;
55//! println!("{} partition movements", out.proposal.movements.len());
56//! # Ok(())
57//! # }
58//! ```
59
60/// Generated protobuf + Connect server stubs. The actual content lives
61/// in `OUT_DIR/crabka.rebalancer.v1.rs` and is produced by `build.rs`.
62///
63/// Pedantic lints are silenced here because the include is verbatim
64/// codegen output; we cannot retrofit `#[must_use]` annotations or
65/// shorter helper functions without forking the upstream codegen.
66#[allow(clippy::pedantic, clippy::style)]
67pub mod pb {
68 include!(concat!(env!("OUT_DIR"), "/crabka.rebalancer.v1.rs"));
69}
70
71pub mod api;
72pub mod capacity;
73pub mod detector;
74pub mod executor;
75pub mod goals;
76pub mod health;
77pub mod ingest;
78pub mod metrics;
79pub mod model;
80pub mod optimizer;
81pub mod scraper;
82pub mod state_topic;