Skip to main content

kafka_client_engine/admin/
describe_outcome.rs

1//! Engine-owned terminal representation for one `DescribeCluster` call.
2
3use core::fmt;
4
5use kafka_client_core::{
6    ClusterBroker as CoreBroker, DeliveryStatus as CoreDeliveryStatus,
7    DescribeClusterFailureKind as CoreFailureKind, DescribeClusterTerminal,
8};
9
10/// Stable delivery certainty independent of deterministic core types.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum DescribeClusterDeliveryStatus {
13    /// The request definitely did not reach Kafka.
14    NotSent,
15    /// The request may have reached Kafka.
16    PossiblySent,
17}
18
19/// One broker endpoint in a cluster description.
20#[derive(Clone, Debug, Eq, PartialEq)]
21pub struct ClusterBroker {
22    id: i32,
23    host: String,
24    port: u16,
25    rack: Option<String>,
26    fenced: bool,
27}
28
29impl ClusterBroker {
30    /// Returns the broker identifier.
31    pub const fn id(&self) -> i32 {
32        self.id
33    }
34
35    /// Returns the broker host.
36    pub fn host(&self) -> &str {
37        &self.host
38    }
39
40    /// Returns the broker port.
41    pub const fn port(&self) -> u16 {
42        self.port
43    }
44
45    /// Returns the nullable rack.
46    pub fn rack(&self) -> Option<&str> {
47        self.rack.as_deref()
48    }
49
50    /// Returns whether Kafka reports this broker as fenced.
51    pub const fn is_fenced(&self) -> bool {
52        self.fenced
53    }
54
55    /// Consumes the broker into stable parts.
56    pub fn into_parts(self) -> (i32, String, u16, Option<String>, bool) {
57        (self.id, self.host, self.port, self.rack, self.fenced)
58    }
59}
60
61/// One bounded successful cluster description.
62#[derive(Clone, Debug, Eq, PartialEq)]
63pub struct ClusterDescription {
64    cluster_id: String,
65    controller_id: Option<i32>,
66    brokers: Vec<ClusterBroker>,
67    authorized_operations: Option<i32>,
68}
69
70impl ClusterDescription {
71    /// Returns Kafka's cluster identifier.
72    pub fn cluster_id(&self) -> &str {
73        &self.cluster_id
74    }
75
76    /// Returns the nullable broker-reported controller or fallback broker identifier.
77    pub const fn controller_id(&self) -> Option<i32> {
78        self.controller_id
79    }
80
81    /// Returns brokers in deterministic identifier order.
82    pub fn brokers(&self) -> &[ClusterBroker] {
83        &self.brokers
84    }
85
86    /// Returns the raw cluster authorization bitfield when Kafka supplied it.
87    pub const fn authorized_operations(&self) -> Option<i32> {
88        self.authorized_operations
89    }
90
91    /// Consumes the description into stable parts.
92    pub fn into_parts(self) -> (String, Option<i32>, Vec<ClusterBroker>) {
93        (self.cluster_id, self.controller_id, self.brokers)
94    }
95
96    /// Consumes the description into stable parts including authorization bits.
97    pub fn into_parts_with_authorized_operations(
98        self,
99    ) -> (String, Option<i32>, Vec<ClusterBroker>, Option<i32>) {
100        (
101            self.cluster_id,
102            self.controller_id,
103            self.brokers,
104            self.authorized_operations,
105        )
106    }
107}
108
109/// Exact top-level broker rejection.
110#[derive(Clone, Debug, Eq, PartialEq)]
111pub struct DescribeClusterBrokerError {
112    code: i16,
113    message: Option<String>,
114    message_truncated: bool,
115}
116
117impl DescribeClusterBrokerError {
118    /// Consumes the error into stable parts.
119    pub fn into_parts(self) -> (i16, Option<String>, bool) {
120        (self.code, self.message, self.message_truncated)
121    }
122}
123
124/// Stable whole-operation failure category.
125#[derive(Clone, Copy, Debug, Eq, PartialEq)]
126pub enum DescribeClusterFailureKind {
127    /// Original deadline elapsed before driver ownership.
128    DeadlineElapsed,
129    /// Driver rejected the call before transport ownership.
130    DriverRejected,
131    /// Driver-owned transport execution failed.
132    Transport,
133    /// SASL authentication rejected the connection before ordinary call admission.
134    Authentication,
135    /// The broker cannot represent the explicitly requested protocol semantics.
136    Compatibility,
137    /// Broker response was malformed or exceeded its retained-result budget.
138    InvalidResponse,
139}
140
141/// Whole-operation failure with authoritative delivery certainty.
142#[derive(Clone, Copy, Debug, Eq, PartialEq)]
143pub struct DescribeClusterFailure {
144    kind: DescribeClusterFailureKind,
145    delivery: DescribeClusterDeliveryStatus,
146}
147
148impl DescribeClusterFailure {
149    /// Returns the stable category.
150    pub const fn kind(self) -> DescribeClusterFailureKind {
151        self.kind
152    }
153
154    /// Returns authoritative delivery certainty.
155    pub const fn delivery(self) -> DescribeClusterDeliveryStatus {
156        self.delivery
157    }
158}
159
160/// Exactly one engine-owned terminal decision.
161#[derive(Clone, Debug, Eq, PartialEq)]
162pub enum DescribeClusterOutcome {
163    /// One successful cluster description.
164    Cluster(ClusterDescription),
165    /// One exact top-level broker rejection.
166    BrokerRejected(DescribeClusterBrokerError),
167    /// One local or transport failure.
168    Failed(DescribeClusterFailure),
169}
170
171/// Failure to observe a named completion.
172#[derive(Clone, Copy, Debug, Eq, PartialEq)]
173pub enum DescribeClusterObserverError {
174    /// This linear observer already consumed its terminal.
175    AlreadyObserved,
176    /// The observer generation is no longer live.
177    Stale,
178}
179
180impl fmt::Display for DescribeClusterObserverError {
181    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
182        formatter.write_str(match self {
183            Self::AlreadyObserved => "DescribeCluster result was already observed",
184            Self::Stale => "DescribeCluster observer is stale",
185        })
186    }
187}
188
189impl std::error::Error for DescribeClusterObserverError {}
190
191pub(crate) fn translate_terminal(terminal: DescribeClusterTerminal) -> DescribeClusterOutcome {
192    match terminal {
193        DescribeClusterTerminal::Cluster(description) => {
194            let (cluster_id, controller_id, brokers, authorized_operations) =
195                description.into_parts_with_authorized_operations();
196            DescribeClusterOutcome::Cluster(ClusterDescription {
197                cluster_id,
198                controller_id,
199                brokers: brokers.into_iter().map(translate_broker).collect(),
200                authorized_operations,
201            })
202        }
203        DescribeClusterTerminal::BrokerRejected(error) => {
204            let (code, message, message_truncated) = error.into_parts();
205            DescribeClusterOutcome::BrokerRejected(DescribeClusterBrokerError {
206                code,
207                message,
208                message_truncated,
209            })
210        }
211        DescribeClusterTerminal::Failed(failure) => {
212            DescribeClusterOutcome::Failed(DescribeClusterFailure {
213                kind: match failure.kind() {
214                    CoreFailureKind::DeadlineElapsed => DescribeClusterFailureKind::DeadlineElapsed,
215                    CoreFailureKind::DriverRejected => DescribeClusterFailureKind::DriverRejected,
216                    CoreFailureKind::Transport => DescribeClusterFailureKind::Transport,
217                    CoreFailureKind::Authentication => DescribeClusterFailureKind::Authentication,
218                    CoreFailureKind::Compatibility => DescribeClusterFailureKind::Compatibility,
219                    CoreFailureKind::InvalidResponse => DescribeClusterFailureKind::InvalidResponse,
220                },
221                delivery: translate_delivery(failure.delivery()),
222            })
223        }
224    }
225}
226
227fn translate_broker(broker: CoreBroker) -> ClusterBroker {
228    let (id, host, port, rack, fenced) = broker.into_parts();
229    ClusterBroker {
230        id,
231        host,
232        port,
233        rack,
234        fenced,
235    }
236}
237
238const fn translate_delivery(delivery: CoreDeliveryStatus) -> DescribeClusterDeliveryStatus {
239    match delivery {
240        CoreDeliveryStatus::NotSent => DescribeClusterDeliveryStatus::NotSent,
241        CoreDeliveryStatus::PossiblySent => DescribeClusterDeliveryStatus::PossiblySent,
242    }
243}