Skip to main content

kafka_client_engine/admin/group_offsets/
outcome.rs

1//! Stable engine terminal values for consumer-group offset listing.
2
3use core::fmt;
4
5mod translate;
6pub(crate) use translate::translate_terminal;
7
8/// Stable delivery certainty independent of core and driver types.
9#[derive(Clone, Copy, Debug, Eq, PartialEq)]
10pub enum ListConsumerGroupOffsetsDeliveryStatus {
11    /// The request definitely did not reach Kafka.
12    NotSent,
13    /// The request may have reached Kafka.
14    PossiblySent,
15}
16
17/// Exact broker rejection for one topic-partition.
18#[derive(Clone, Copy, Debug, Eq, PartialEq)]
19pub struct GroupOffsetBrokerError {
20    code: i16,
21}
22
23impl GroupOffsetBrokerError {
24    /// Returns Kafka's exact signed error code.
25    pub const fn code(self) -> i16 {
26        self.code
27    }
28}
29
30/// One normalized committed next-offset description.
31#[derive(Clone, Debug, Eq, PartialEq)]
32pub struct GroupOffsetDescription {
33    offset: Option<i64>,
34    leader_epoch: Option<i32>,
35    metadata: Option<String>,
36}
37
38impl GroupOffsetDescription {
39    /// Consumes this description into stable scalar parts.
40    pub fn into_parts(self) -> (Option<i64>, Option<i32>, Option<String>) {
41        (self.offset, self.leader_epoch, self.metadata)
42    }
43}
44
45/// One ordered topic-partition result.
46#[derive(Clone, Debug, Eq, PartialEq)]
47pub struct GroupOffsetResult {
48    topic: String,
49    partition: i32,
50    result: Result<GroupOffsetDescription, GroupOffsetBrokerError>,
51}
52
53impl GroupOffsetResult {
54    /// Consumes this result into identity and exact broker outcome.
55    pub fn into_parts(
56        self,
57    ) -> (
58        String,
59        i32,
60        Result<GroupOffsetDescription, GroupOffsetBrokerError>,
61    ) {
62        (self.topic, self.partition, self.result)
63    }
64}
65
66/// Ordered successful result plus Kafka's throttle observation.
67#[derive(Clone, Debug, Eq, PartialEq)]
68pub struct ListConsumerGroupOffsetsBatch {
69    throttle_time_ms: u32,
70    offsets: Vec<GroupOffsetResult>,
71}
72
73impl ListConsumerGroupOffsetsBatch {
74    /// Consumes the batch into throttle and ordered partition results.
75    pub fn into_parts(self) -> (u32, Vec<GroupOffsetResult>) {
76        (self.throttle_time_ms, self.offsets)
77    }
78}
79
80/// Exact result for one consumer group in a caller-ordered batch operation.
81#[derive(Clone, Debug, Eq, PartialEq)]
82pub enum ListConsumerGroupBatchOutcome {
83    /// Kafka returned this group's ordered committed offsets.
84    Offsets {
85        /// Exact requested consumer-group identity.
86        group_id: String,
87        /// Ordered partition outcomes and this group's throttle.
88        offsets: ListConsumerGroupOffsetsBatch,
89    },
90    /// Kafka rejected this specific consumer group.
91    BrokerRejected {
92        /// Exact requested consumer-group identity.
93        group_id: String,
94        /// Kafka's exact signed nonzero group error code.
95        code: i16,
96    },
97}
98
99impl ListConsumerGroupBatchOutcome {
100    /// Returns the exact requested consumer-group identity.
101    pub fn group_id(&self) -> &str {
102        match self {
103            Self::Offsets { group_id, .. } | Self::BrokerRejected { group_id, .. } => group_id,
104        }
105    }
106
107    /// Consumes this outcome into its group and exact broker result.
108    pub fn into_parts(self) -> (String, Result<ListConsumerGroupOffsetsBatch, i16>) {
109        match self {
110            Self::Offsets { group_id, offsets } => (group_id, Ok(offsets)),
111            Self::BrokerRejected { group_id, code } => (group_id, Err(code)),
112        }
113    }
114}
115
116/// Caller-ordered outcomes plus maximum throttle across coordinator calls.
117#[derive(Clone, Debug, Eq, PartialEq)]
118pub struct ListConsumerGroupsOffsetsBatch {
119    throttle_time_ms: u32,
120    outcomes: Vec<ListConsumerGroupBatchOutcome>,
121}
122
123impl ListConsumerGroupsOffsetsBatch {
124    /// Returns the maximum nonnegative throttle observed across calls.
125    pub const fn throttle_time_ms(&self) -> u32 {
126        self.throttle_time_ms
127    }
128
129    /// Returns exactly one outcome per requested group in caller order.
130    pub fn outcomes(&self) -> &[ListConsumerGroupBatchOutcome] {
131        &self.outcomes
132    }
133
134    /// Consumes the batch into maximum throttle and caller-ordered outcomes.
135    pub fn into_parts(self) -> (u32, Vec<ListConsumerGroupBatchOutcome>) {
136        (self.throttle_time_ms, self.outcomes)
137    }
138}
139
140/// Stable whole-operation failure category.
141#[derive(Clone, Copy, Debug, Eq, PartialEq)]
142pub enum ListConsumerGroupOffsetsFailureKind {
143    /// The original absolute deadline elapsed.
144    DeadlineElapsed,
145    /// The driver rejected the request before ownership.
146    DriverRejected,
147    /// Driver-owned transport execution failed.
148    Transport,
149    /// Kafka rejected the explicit group with this exact signed code.
150    Broker(i16),
151    /// A valid response exceeded admitted retained capacity.
152    ResponseTooLarge,
153    /// The selected API cannot represent the requested semantics.
154    Compatibility,
155    /// The broker response could not be normalized.
156    InvalidResponse,
157}
158
159/// Whole-operation failure with authoritative delivery certainty.
160#[derive(Clone, Copy, Debug, Eq, PartialEq)]
161pub struct ListConsumerGroupOffsetsFailure {
162    kind: ListConsumerGroupOffsetsFailureKind,
163    delivery: ListConsumerGroupOffsetsDeliveryStatus,
164}
165
166impl ListConsumerGroupOffsetsFailure {
167    /// Returns the stable failure category.
168    pub const fn kind(self) -> ListConsumerGroupOffsetsFailureKind {
169        self.kind
170    }
171
172    /// Returns authoritative delivery certainty.
173    pub const fn delivery(self) -> ListConsumerGroupOffsetsDeliveryStatus {
174        self.delivery
175    }
176}
177
178/// Exactly one engine-owned terminal decision.
179#[derive(Clone, Debug, Eq, PartialEq)]
180pub enum ListConsumerGroupOffsetsOutcome {
181    /// Ordered partition outcomes plus broker throttle.
182    Offsets(ListConsumerGroupOffsetsBatch),
183    /// Every requested consumer group settled in caller order.
184    Batch(ListConsumerGroupsOffsetsBatch),
185    /// Whole-operation failure.
186    Failed(ListConsumerGroupOffsetsFailure),
187}
188
189/// Failure to observe a named completion.
190#[derive(Clone, Copy, Debug, Eq, PartialEq)]
191pub enum ListConsumerGroupOffsetsObserverError {
192    /// This linear observer already consumed its terminal.
193    AlreadyObserved,
194    /// The observer generation is no longer live.
195    Stale,
196}
197
198impl fmt::Display for ListConsumerGroupOffsetsObserverError {
199    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
200        formatter.write_str(match self {
201            Self::AlreadyObserved => "ListConsumerGroupOffsets result was already observed",
202            Self::Stale => "ListConsumerGroupOffsets observer is stale",
203        })
204    }
205}
206
207impl std::error::Error for ListConsumerGroupOffsetsObserverError {}