kafka_meta/lib.rs
1//! Metadata, routing, connection pooling and the error taxonomy.
2//!
3//! This is the layer that knows what a cluster looks like. Everything above it
4//! — admin RPCs, the read path — sends through [`Cluster`], which resolves the
5//! right broker, retries on the errors that mean "your view is stale", and
6//! keeps an immutable snapshot readers can take without blocking.
7//!
8//! # The two tables
9//!
10//! [`routing`] and the error taxonomy are first-class artifacts, each in one
11//! file, because both encode knowledge that is otherwise scattered into
12//! individual call sites and then quietly diverges.
13//!
14//! The error table lives in `kafka-conn` — [`ErrorCode`], [`Error`] — and is
15//! re-exported here so the two sit together at the layer that acts on them.
16//! It has to be defined down there because every crate in the workspace,
17//! including the connection layer itself, needs to classify a broker's answer,
18//! and a workspace with two error types would push a `From` conversion into
19//! every call site.
20//!
21//! ```no_run
22//! # async fn example() -> kafka_meta::Result<()> {
23//! use kafka_meta::{Cluster, ClusterConfig};
24//!
25//! let cluster = Cluster::connect(["localhost:9092"], ClusterConfig::default()).await?;
26//! let snapshot = cluster.snapshot();
27//! println!(
28//! "{} brokers, fetched {:?} ago",
29//! snapshot.brokers().len(),
30//! snapshot.age()
31//! );
32//!
33//! let leader = cluster.leader_for("orders", 0).await?;
34//! let coordinator = cluster.coordinator_for("my-group").await?;
35//! # Ok(())
36//! # }
37//! ```
38
39#![cfg_attr(
40 test,
41 allow(
42 clippy::unwrap_used,
43 clippy::expect_used,
44 clippy::panic,
45 clippy::indexing_slicing
46 )
47)]
48
49mod cluster;
50mod pool;
51mod retry;
52mod routing;
53mod snapshot;
54
55pub use cluster::{Cluster, ClusterConfig};
56pub use pool::{BrokerPool, Endpoint};
57pub use retry::RetryPolicy;
58pub use routing::{BrokerSelector, CoordinatorKind, Routing, routing};
59pub use snapshot::{BrokerInfo, MetadataSnapshot, PartitionInfo, TopicId, TopicInfo};
60
61/// The error taxonomy, re-exported.
62///
63/// One type across the workspace: see the crate docs for why it is defined a
64/// layer down.
65pub use kafka_conn::{ApiKey, Error, ErrorCode, KNOWN_ERROR_CODES, Result};