Skip to main content

kafka_client_engine/admin/list_offsets/
outcome.rs

1//! Stable engine terminal values for Admin `ListOffsets`.
2
3use core::fmt;
4
5use kafka_client_core::{
6    AdminListOffsetResult as CoreResult, AdminListOffsetsFailureKind as CoreFailureKind,
7    AdminListOffsetsTerminal 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 AdminListOffsetsDeliveryStatus {
13    /// No call in the operation reached Kafka.
14    NotSent,
15    /// At least one call may have reached Kafka.
16    PossiblySent,
17}
18
19/// Exact broker rejection for one topic-partition.
20#[derive(Clone, Copy, Debug, Eq, PartialEq)]
21pub struct AdminListOffsetEngineBrokerError {
22    code: i16,
23}
24
25impl AdminListOffsetEngineBrokerError {
26    /// Returns Kafka's exact signed error code.
27    pub const fn code(self) -> i16 {
28        self.code
29    }
30}
31
32/// One normalized successful result.
33#[derive(Clone, Copy, Debug, Eq, PartialEq)]
34pub struct AdminListOffsetDescription {
35    offset: Option<i64>,
36    timestamp_ms: Option<i64>,
37    leader_epoch: Option<i32>,
38}
39
40impl AdminListOffsetDescription {
41    /// Consumes the value into stable scalar parts.
42    pub const fn into_parts(self) -> (Option<i64>, Option<i64>, Option<i32>) {
43        (self.offset, self.timestamp_ms, self.leader_epoch)
44    }
45}
46
47/// One ordered topic-partition result.
48#[derive(Clone, Debug, Eq, PartialEq)]
49pub struct AdminListOffsetEngineResult {
50    topic: String,
51    partition: i32,
52    result: Result<AdminListOffsetDescription, AdminListOffsetEngineBrokerError>,
53}
54
55impl AdminListOffsetEngineResult {
56    /// Consumes this result into identity and exact broker outcome.
57    pub fn into_parts(
58        self,
59    ) -> (
60        String,
61        i32,
62        Result<AdminListOffsetDescription, AdminListOffsetEngineBrokerError>,
63    ) {
64        (self.topic, self.partition, self.result)
65    }
66}
67
68/// Ordered successful result plus maximum observed broker throttle.
69#[derive(Clone, Debug, Eq, PartialEq)]
70pub struct AdminListOffsetsEngineBatch {
71    throttle_time_ms: u32,
72    offsets: Vec<AdminListOffsetEngineResult>,
73}
74
75impl AdminListOffsetsEngineBatch {
76    /// Consumes the batch into throttle and caller-ordered partition results.
77    pub fn into_parts(self) -> (u32, Vec<AdminListOffsetEngineResult>) {
78        (self.throttle_time_ms, self.offsets)
79    }
80}
81
82/// Stable whole-operation failure category.
83#[derive(Clone, Copy, Debug, Eq, PartialEq)]
84pub enum AdminListOffsetsFailureKind {
85    /// The original absolute deadline elapsed.
86    DeadlineElapsed,
87    /// The driver rejected the current call before transport ownership.
88    DriverRejected,
89    /// Driver-owned transport execution failed.
90    Transport,
91    /// A valid response exceeded the admitted retained envelope.
92    ResponseTooLarge,
93    /// The selected broker API cannot represent the request.
94    Compatibility,
95    /// A broker response could not be normalized or correlated.
96    InvalidResponse,
97}
98
99/// Whole-operation failure with authoritative delivery certainty.
100#[derive(Clone, Copy, Debug, Eq, PartialEq)]
101pub struct AdminListOffsetsFailure {
102    kind: AdminListOffsetsFailureKind,
103    delivery: AdminListOffsetsDeliveryStatus,
104}
105
106impl AdminListOffsetsFailure {
107    /// Returns the stable failure category.
108    pub const fn kind(self) -> AdminListOffsetsFailureKind {
109        self.kind
110    }
111
112    /// Returns authoritative delivery certainty.
113    pub const fn delivery(self) -> AdminListOffsetsDeliveryStatus {
114        self.delivery
115    }
116}
117
118/// Exactly one engine-owned terminal decision.
119#[derive(Clone, Debug, Eq, PartialEq)]
120pub enum AdminListOffsetsOutcome {
121    /// Caller-ordered per-partition outcomes and maximum observed throttle.
122    Offsets(AdminListOffsetsEngineBatch),
123    /// Whole-operation failure outside exact partition broker results.
124    Failed(AdminListOffsetsFailure),
125}
126
127/// Failure to observe a named completion.
128#[derive(Clone, Copy, Debug, Eq, PartialEq)]
129pub enum AdminListOffsetsObserverError {
130    /// This linear observer already consumed its terminal.
131    AlreadyObserved,
132    /// The observer generation is no longer live.
133    Stale,
134}
135
136impl fmt::Display for AdminListOffsetsObserverError {
137    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
138        formatter.write_str(match self {
139            Self::AlreadyObserved => "Admin ListOffsets result was already observed",
140            Self::Stale => "Admin ListOffsets observer is stale",
141        })
142    }
143}
144
145impl std::error::Error for AdminListOffsetsObserverError {}
146
147pub(crate) fn translate_terminal(terminal: CoreTerminal) -> AdminListOffsetsOutcome {
148    match terminal {
149        CoreTerminal::Listed(batch) => {
150            let (throttle_time_ms, outcomes) = batch.into_parts();
151            AdminListOffsetsOutcome::Offsets(AdminListOffsetsEngineBatch {
152                throttle_time_ms,
153                offsets: outcomes
154                    .into_iter()
155                    .map(|outcome| {
156                        let (topic, partition, result) = outcome.into_parts();
157                        let result = match result {
158                            CoreResult::Listed(value) => Ok(AdminListOffsetDescription {
159                                offset: value.offset(),
160                                timestamp_ms: value.timestamp_ms(),
161                                leader_epoch: value.leader_epoch(),
162                            }),
163                            CoreResult::Failed(error) => {
164                                Err(AdminListOffsetEngineBrokerError { code: error.code() })
165                            }
166                        };
167                        AdminListOffsetEngineResult {
168                            topic,
169                            partition,
170                            result,
171                        }
172                    })
173                    .collect(),
174            })
175        }
176        CoreTerminal::Failed(failure) => AdminListOffsetsOutcome::Failed(AdminListOffsetsFailure {
177            kind: failure_kind(failure.kind()),
178            delivery: delivery(failure.delivery()),
179        }),
180    }
181}
182
183const fn failure_kind(kind: CoreFailureKind) -> AdminListOffsetsFailureKind {
184    match kind {
185        CoreFailureKind::DeadlineElapsed => AdminListOffsetsFailureKind::DeadlineElapsed,
186        CoreFailureKind::DriverRejected => AdminListOffsetsFailureKind::DriverRejected,
187        CoreFailureKind::Transport => AdminListOffsetsFailureKind::Transport,
188        CoreFailureKind::ResponseTooLarge => AdminListOffsetsFailureKind::ResponseTooLarge,
189        CoreFailureKind::Compatibility => AdminListOffsetsFailureKind::Compatibility,
190        CoreFailureKind::InvalidResponse => AdminListOffsetsFailureKind::InvalidResponse,
191    }
192}
193
194const fn delivery(status: CoreDeliveryStatus) -> AdminListOffsetsDeliveryStatus {
195    match status {
196        CoreDeliveryStatus::NotSent => AdminListOffsetsDeliveryStatus::NotSent,
197        CoreDeliveryStatus::PossiblySent => AdminListOffsetsDeliveryStatus::PossiblySent,
198    }
199}