Skip to main content

kafka_client_engine/admin/delete_records/
outcome.rs

1//! Stable engine terminal values for Admin `DeleteRecords`.
2
3use core::fmt;
4
5use kafka_client_core::{
6    DeleteRecordsFailureKind as CoreFailureKind, DeleteRecordsResult as CoreResult,
7    DeleteRecordsTerminal 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 DeleteRecordsDeliveryStatus {
13    /// The failed target's call did not reach Kafka.
14    NotSent,
15    /// The failed target's 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 DeleteRecordsEngineBrokerError {
22    code: i16,
23}
24
25impl DeleteRecordsEngineBrokerError {
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 DeleteRecordsDescription {
35    low_watermark: i64,
36}
37
38impl DeleteRecordsDescription {
39    /// Consumes the value into stable scalar parts.
40    pub const fn low_watermark(self) -> i64 {
41        self.low_watermark
42    }
43}
44
45/// One ordered topic-partition result.
46#[derive(Clone, Debug, Eq, PartialEq)]
47pub struct DeleteRecordsEngineResult {
48    topic: String,
49    partition: i32,
50    result: Result<DeleteRecordsDescription, DeleteRecordsEngineBrokerError>,
51}
52
53impl DeleteRecordsEngineResult {
54    /// Consumes this result into identity and exact broker outcome.
55    pub fn into_parts(
56        self,
57    ) -> (
58        String,
59        i32,
60        Result<DeleteRecordsDescription, DeleteRecordsEngineBrokerError>,
61    ) {
62        (self.topic, self.partition, self.result)
63    }
64}
65
66/// Ordered successful result plus maximum observed broker throttle.
67#[derive(Clone, Debug, Eq, PartialEq)]
68pub struct DeleteRecordsEngineBatch {
69    throttle_time_ms: u32,
70    records: Vec<DeleteRecordsEngineResult>,
71}
72
73impl DeleteRecordsEngineBatch {
74    /// Consumes the batch into throttle and caller-ordered partition results.
75    pub fn into_parts(self) -> (u32, Vec<DeleteRecordsEngineResult>) {
76        (self.throttle_time_ms, self.records)
77    }
78}
79
80/// Stable whole-operation failure category.
81#[derive(Clone, Copy, Debug, Eq, PartialEq)]
82pub enum DeleteRecordsFailureKind {
83    /// The original absolute deadline elapsed.
84    DeadlineElapsed,
85    /// The driver rejected the current call before transport ownership.
86    DriverRejected,
87    /// Driver-owned transport execution failed.
88    Transport,
89    /// A valid response exceeded the admitted retained envelope.
90    ResponseTooLarge,
91    /// The selected broker API cannot represent the request.
92    Compatibility,
93    /// A broker response could not be normalized or correlated.
94    InvalidResponse,
95}
96
97/// Partial operation failure with authoritative failed-target delivery certainty.
98#[derive(Clone, Debug, Eq, PartialEq)]
99pub struct DeleteRecordsFailure {
100    kind: DeleteRecordsFailureKind,
101    delivery: DeleteRecordsDeliveryStatus,
102    throttle_time_ms: u32,
103    completed: Vec<DeleteRecordsEngineResult>,
104    failed_target: super::DeleteRecordsRequestTarget,
105    unattempted: Vec<super::DeleteRecordsRequestTarget>,
106}
107
108impl DeleteRecordsFailure {
109    /// Returns the stable failure category.
110    pub const fn kind(&self) -> DeleteRecordsFailureKind {
111        self.kind
112    }
113
114    /// Returns authoritative delivery certainty for the failed target.
115    pub const fn delivery(&self) -> DeleteRecordsDeliveryStatus {
116        self.delivery
117    }
118
119    /// Consumes the partial terminal into stable adapter-owned parts.
120    pub fn into_parts(
121        self,
122    ) -> (
123        DeleteRecordsFailureKind,
124        DeleteRecordsDeliveryStatus,
125        u32,
126        Vec<DeleteRecordsEngineResult>,
127        super::DeleteRecordsRequestTarget,
128        Vec<super::DeleteRecordsRequestTarget>,
129    ) {
130        (
131            self.kind,
132            self.delivery,
133            self.throttle_time_ms,
134            self.completed,
135            self.failed_target,
136            self.unattempted,
137        )
138    }
139}
140
141/// Exactly one engine-owned terminal decision.
142#[derive(Clone, Debug, Eq, PartialEq)]
143pub enum DeleteRecordsOutcome {
144    /// Caller-ordered per-partition outcomes and maximum observed throttle.
145    Deleted(DeleteRecordsEngineBatch),
146    /// Whole-operation failure outside exact partition broker results.
147    Failed(DeleteRecordsFailure),
148}
149
150/// Failure to observe a named completion.
151#[derive(Clone, Copy, Debug, Eq, PartialEq)]
152pub enum DeleteRecordsObserverError {
153    /// This linear observer already consumed its terminal.
154    AlreadyObserved,
155    /// The observer generation is no longer live.
156    Stale,
157}
158
159impl fmt::Display for DeleteRecordsObserverError {
160    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
161        formatter.write_str(match self {
162            Self::AlreadyObserved => "Admin DeleteRecords result was already observed",
163            Self::Stale => "Admin DeleteRecords observer is stale",
164        })
165    }
166}
167
168impl std::error::Error for DeleteRecordsObserverError {}
169
170pub(crate) fn translate_terminal(terminal: CoreTerminal) -> DeleteRecordsOutcome {
171    match terminal {
172        CoreTerminal::Deleted(batch) => {
173            let (throttle_time_ms, outcomes) = batch.into_parts();
174            DeleteRecordsOutcome::Deleted(DeleteRecordsEngineBatch {
175                throttle_time_ms,
176                records: outcomes.into_iter().map(translate_result).collect(),
177            })
178        }
179        CoreTerminal::Failed(failure) => {
180            let (kind, delivery_status, throttle_time_ms, completed, failed, unattempted) =
181                failure.into_parts();
182            DeleteRecordsOutcome::Failed(DeleteRecordsFailure {
183                kind: failure_kind(kind),
184                delivery: delivery(delivery_status),
185                throttle_time_ms,
186                completed: completed.into_iter().map(translate_result).collect(),
187                failed_target: translate_target(&failed),
188                unattempted: unattempted.iter().map(translate_target).collect(),
189            })
190        }
191    }
192}
193
194fn translate_result(outcome: kafka_client_core::DeleteRecordsOutcome) -> DeleteRecordsEngineResult {
195    let (topic, partition, result) = outcome.into_parts();
196    let result = match result {
197        CoreResult::Deleted(value) => Ok(DeleteRecordsDescription {
198            low_watermark: value.low_watermark(),
199        }),
200        CoreResult::Failed(error) => Err(DeleteRecordsEngineBrokerError { code: error.code() }),
201    };
202    DeleteRecordsEngineResult {
203        topic,
204        partition,
205        result,
206    }
207}
208
209fn translate_target(
210    target: &kafka_client_core::DeleteRecordsTarget,
211) -> super::DeleteRecordsRequestTarget {
212    super::DeleteRecordsRequestTarget::new(
213        target.topic().to_owned(),
214        target.partition(),
215        target.before_offset(),
216    )
217}
218
219const fn failure_kind(kind: CoreFailureKind) -> DeleteRecordsFailureKind {
220    match kind {
221        CoreFailureKind::DeadlineElapsed => DeleteRecordsFailureKind::DeadlineElapsed,
222        CoreFailureKind::DriverRejected => DeleteRecordsFailureKind::DriverRejected,
223        CoreFailureKind::Transport => DeleteRecordsFailureKind::Transport,
224        CoreFailureKind::ResponseTooLarge => DeleteRecordsFailureKind::ResponseTooLarge,
225        CoreFailureKind::Compatibility => DeleteRecordsFailureKind::Compatibility,
226        CoreFailureKind::InvalidResponse => DeleteRecordsFailureKind::InvalidResponse,
227    }
228}
229
230const fn delivery(status: CoreDeliveryStatus) -> DeleteRecordsDeliveryStatus {
231    match status {
232        CoreDeliveryStatus::NotSent => DeleteRecordsDeliveryStatus::NotSent,
233        CoreDeliveryStatus::PossiblySent => DeleteRecordsDeliveryStatus::PossiblySent,
234    }
235}