Skip to main content

kafka_client_engine/admin/list_consumer_groups/
outcome.rs

1//! Stable engine terminal values for cluster-wide consumer-group listing.
2
3use core::fmt;
4
5use kafka_client_core::{
6    AdminListConsumerGroupsFailureKind as CoreFailureKind,
7    AdminListConsumerGroupsTerminal as CoreTerminal, DeliveryStatus as CoreDeliveryStatus,
8};
9
10/// Stable delivery certainty independent of core and driver types.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum ListConsumerGroupsDeliveryStatus {
13    /// No request from this operation reached the driver.
14    NotSent,
15    /// One or more discovery or listing requests may have reached a broker.
16    PossiblySent,
17}
18
19/// One stable classic or modern consumer-group listing.
20#[derive(Clone, Debug, Eq, PartialEq)]
21pub struct ConsumerGroupListing {
22    group_id: String,
23    protocol_type: String,
24    group_state: Option<String>,
25    group_type: Option<String>,
26}
27
28impl ConsumerGroupListing {
29    /// Consumes this listing into stable scalar parts.
30    pub fn into_parts(self) -> (String, String, Option<String>, Option<String>) {
31        (
32            self.group_id,
33            self.protocol_type,
34            self.group_state,
35            self.group_type,
36        )
37    }
38}
39
40/// Exact top-level `ListGroups` error from one broker.
41#[derive(Clone, Copy, Debug, Eq, PartialEq)]
42pub struct ListConsumerGroupsBrokerError {
43    broker_id: i32,
44    code: i16,
45}
46
47impl ListConsumerGroupsBrokerError {
48    /// Consumes this error into exact broker and code parts.
49    pub const fn into_parts(self) -> (i32, i16) {
50        (self.broker_id, self.code)
51    }
52}
53
54/// Exact top-level discovery error with bounded diagnostic storage.
55#[derive(Clone, Debug, Eq, PartialEq)]
56pub struct ListConsumerGroupsDiscoveryError {
57    code: i16,
58    message: Option<String>,
59    message_truncated: bool,
60}
61
62impl ListConsumerGroupsDiscoveryError {
63    /// Consumes this error into stable diagnostic parts.
64    pub fn into_parts(self) -> (i16, Option<String>, bool) {
65        (self.code, self.message, self.message_truncated)
66    }
67}
68
69/// Successful cluster-wide terminal with deterministic group ordering.
70#[derive(Clone, Debug, Eq, PartialEq)]
71pub struct ListConsumerGroupsBatch {
72    throttle_time_ms: u32,
73    groups: Vec<ConsumerGroupListing>,
74    broker_errors: Vec<ListConsumerGroupsBrokerError>,
75}
76
77impl ListConsumerGroupsBatch {
78    /// Consumes throttle, globally merged groups, and exact broker errors.
79    pub fn into_parts(
80        self,
81    ) -> (
82        u32,
83        Vec<ConsumerGroupListing>,
84        Vec<ListConsumerGroupsBrokerError>,
85    ) {
86        (self.throttle_time_ms, self.groups, self.broker_errors)
87    }
88}
89
90/// Stable whole-operation failure category.
91#[derive(Clone, Copy, Debug, Eq, PartialEq)]
92pub enum ListConsumerGroupsFailureKind {
93    /// The public absolute deadline elapsed.
94    DeadlineElapsed,
95    /// The driver rejected a call before accepting it.
96    DriverRejected,
97    /// Transport failed after call submission.
98    Transport,
99    /// A response exceeded the operation's retained-byte envelope.
100    ResponseTooLarge,
101    /// No compatible protocol version was available.
102    Compatibility,
103    /// A response violated discovery or correlation invariants.
104    InvalidResponse,
105}
106
107/// Whole-operation failure with authoritative delivery certainty.
108#[derive(Clone, Copy, Debug, Eq, PartialEq)]
109pub struct ListConsumerGroupsFailure {
110    kind: ListConsumerGroupsFailureKind,
111    delivery: ListConsumerGroupsDeliveryStatus,
112}
113
114impl ListConsumerGroupsFailure {
115    /// Returns the stable failure category.
116    pub const fn kind(self) -> ListConsumerGroupsFailureKind {
117        self.kind
118    }
119
120    /// Returns authoritative delivery certainty.
121    pub const fn delivery(self) -> ListConsumerGroupsDeliveryStatus {
122        self.delivery
123    }
124}
125
126/// Exactly one engine-owned terminal decision.
127#[derive(Clone, Debug, Eq, PartialEq)]
128pub enum ListConsumerGroupsOutcome {
129    /// Discovery and every exact-broker call settled.
130    Groups(ListConsumerGroupsBatch),
131    /// Controller-routed discovery returned an exact broker error.
132    DiscoveryRejected(ListConsumerGroupsDiscoveryError),
133    /// A mechanism or structural failure stopped the operation.
134    Failed(ListConsumerGroupsFailure),
135}
136
137/// Failure to observe a named completion.
138#[derive(Clone, Copy, Debug, Eq, PartialEq)]
139pub enum ListConsumerGroupsObserverError {
140    /// The single terminal value was already observed.
141    AlreadyObserved,
142    /// The observer no longer identifies a live completion slot.
143    Stale,
144}
145
146impl fmt::Display for ListConsumerGroupsObserverError {
147    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
148        formatter.write_str(match self {
149            Self::AlreadyObserved => "ListConsumerGroups result was already observed",
150            Self::Stale => "ListConsumerGroups observer is stale",
151        })
152    }
153}
154
155impl std::error::Error for ListConsumerGroupsObserverError {}
156
157pub(crate) fn translate_terminal(terminal: CoreTerminal) -> ListConsumerGroupsOutcome {
158    match terminal {
159        CoreTerminal::Listed(batch) => {
160            let (throttle_time_ms, groups, broker_errors) = batch.into_parts();
161            ListConsumerGroupsOutcome::Groups(ListConsumerGroupsBatch {
162                throttle_time_ms,
163                groups: groups
164                    .into_iter()
165                    .map(|group| {
166                        let (group_id, protocol_type, group_state, group_type) = group.into_parts();
167                        ConsumerGroupListing {
168                            group_id,
169                            protocol_type,
170                            group_state,
171                            group_type,
172                        }
173                    })
174                    .collect(),
175                broker_errors: broker_errors
176                    .into_iter()
177                    .map(|error| {
178                        let (broker_id, code) = error.into_parts();
179                        ListConsumerGroupsBrokerError { broker_id, code }
180                    })
181                    .collect(),
182            })
183        }
184        CoreTerminal::DiscoveryRejected(error) => {
185            let (code, message, message_truncated) = error.into_parts();
186            ListConsumerGroupsOutcome::DiscoveryRejected(ListConsumerGroupsDiscoveryError {
187                code,
188                message,
189                message_truncated,
190            })
191        }
192        CoreTerminal::Failed(failure) => {
193            ListConsumerGroupsOutcome::Failed(ListConsumerGroupsFailure {
194                kind: failure_kind(failure.kind()),
195                delivery: delivery(failure.delivery()),
196            })
197        }
198    }
199}
200
201const fn failure_kind(kind: CoreFailureKind) -> ListConsumerGroupsFailureKind {
202    match kind {
203        CoreFailureKind::DeadlineElapsed => ListConsumerGroupsFailureKind::DeadlineElapsed,
204        CoreFailureKind::DriverRejected => ListConsumerGroupsFailureKind::DriverRejected,
205        CoreFailureKind::Transport => ListConsumerGroupsFailureKind::Transport,
206        CoreFailureKind::ResponseTooLarge => ListConsumerGroupsFailureKind::ResponseTooLarge,
207        CoreFailureKind::Compatibility => ListConsumerGroupsFailureKind::Compatibility,
208        CoreFailureKind::InvalidResponse => ListConsumerGroupsFailureKind::InvalidResponse,
209    }
210}
211
212const fn delivery(status: CoreDeliveryStatus) -> ListConsumerGroupsDeliveryStatus {
213    match status {
214        CoreDeliveryStatus::NotSent => ListConsumerGroupsDeliveryStatus::NotSent,
215        CoreDeliveryStatus::PossiblySent => ListConsumerGroupsDeliveryStatus::PossiblySent,
216    }
217}