Skip to main content

kafka_client_engine/admin/
outcome.rs

1//! Engine-owned terminal representation for one ordered `CreateTopics` batch.
2
3use core::fmt;
4
5use kafka_client_core::{
6    CreateTopicResult as CoreTopicResult, CreateTopicsFailureKind as CoreFailureKind,
7    CreateTopicsTerminal, DeliveryStatus as CoreDeliveryStatus,
8};
9
10/// Stable admin delivery certainty independent of deterministic core types.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum CreateTopicsDeliveryStatus {
13    /// The request definitely did not reach Kafka.
14    NotSent,
15    /// The request may have reached Kafka.
16    PossiblySent,
17}
18
19/// Exact broker rejection for one requested topic.
20#[derive(Clone, Debug, Eq, PartialEq)]
21pub struct CreateTopicError {
22    code: i16,
23    message: Option<String>,
24    message_truncated: bool,
25}
26
27impl CreateTopicError {
28    /// Returns Kafka's exact signed error code.
29    pub const fn code(&self) -> i16 {
30        self.code
31    }
32
33    /// Returns the optional broker diagnostic.
34    pub fn message(&self) -> Option<&str> {
35        self.message.as_deref()
36    }
37
38    /// Returns whether a present broker diagnostic was shortened or omitted.
39    pub const fn message_truncated(&self) -> bool {
40        self.message_truncated
41    }
42
43    /// Consumes the broker error into stable adapter-owned parts.
44    pub fn into_parts(self) -> (i16, Option<String>, bool) {
45        (self.code, self.message, self.message_truncated)
46    }
47}
48
49/// One per-topic terminal in original request order.
50#[derive(Clone, Debug, Eq, PartialEq)]
51pub struct CreateTopicResult {
52    topic: String,
53    result: Result<(), CreateTopicError>,
54}
55
56impl CreateTopicResult {
57    /// Returns the requested topic name.
58    pub fn topic(&self) -> &str {
59        &self.topic
60    }
61
62    /// Returns this topic's broker outcome.
63    pub const fn result(&self) -> &Result<(), CreateTopicError> {
64        &self.result
65    }
66
67    /// Consumes the ordered result into stable adapter-owned parts.
68    pub fn into_parts(self) -> (String, Result<(), CreateTopicError>) {
69        (self.topic, self.result)
70    }
71}
72
73/// Stable whole-operation failure category.
74#[derive(Clone, Copy, Debug, Eq, PartialEq)]
75pub enum CreateTopicsFailureKind {
76    /// The original deadline elapsed before driver ownership.
77    DeadlineElapsed,
78    /// The generated request was rejected before driver ownership.
79    DriverRejected,
80    /// Driver-owned transport execution failed.
81    Transport,
82    /// The broker response could not be correlated to the requested topics.
83    InvalidResponse,
84}
85
86/// Whole-operation failure with authoritative delivery certainty.
87#[derive(Clone, Copy, Debug, Eq, PartialEq)]
88pub struct CreateTopicsFailure {
89    kind: CreateTopicsFailureKind,
90    delivery: CreateTopicsDeliveryStatus,
91}
92
93impl CreateTopicsFailure {
94    /// Returns the stable failure category.
95    pub const fn kind(self) -> CreateTopicsFailureKind {
96        self.kind
97    }
98
99    /// Returns authoritative delivery certainty.
100    pub const fn delivery(self) -> CreateTopicsDeliveryStatus {
101        self.delivery
102    }
103}
104
105/// Exactly one engine-owned terminal decision.
106#[derive(Clone, Debug, Eq, PartialEq)]
107pub enum CreateTopicsOutcome {
108    /// Ordered broker outcomes.
109    Topics(Vec<CreateTopicResult>),
110    /// Whole-operation failure outside per-topic broker results.
111    Failed(CreateTopicsFailure),
112}
113
114/// Failure to observe a named completion.
115#[derive(Clone, Copy, Debug, Eq, PartialEq)]
116pub enum CreateTopicsObserverError {
117    /// This linear observer already consumed its terminal.
118    AlreadyObserved,
119    /// The observer generation is no longer live.
120    Stale,
121}
122
123impl fmt::Display for CreateTopicsObserverError {
124    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
125        formatter.write_str(match self {
126            Self::AlreadyObserved => "CreateTopics result was already observed",
127            Self::Stale => "CreateTopics observer is stale",
128        })
129    }
130}
131
132impl std::error::Error for CreateTopicsObserverError {}
133
134pub(crate) fn translate_terminal(terminal: CreateTopicsTerminal) -> CreateTopicsOutcome {
135    match terminal {
136        CreateTopicsTerminal::Topics(outcomes) => CreateTopicsOutcome::Topics(
137            outcomes
138                .into_iter()
139                .map(|outcome| {
140                    let (topic, result) = outcome.into_parts();
141                    let result = match result {
142                        CoreTopicResult::Created => Ok(()),
143                        CoreTopicResult::Failed(error) => {
144                            let (code, message, message_truncated) = error.into_parts();
145                            Err(CreateTopicError {
146                                code,
147                                message,
148                                message_truncated,
149                            })
150                        }
151                    };
152                    CreateTopicResult { topic, result }
153                })
154                .collect(),
155        ),
156        CreateTopicsTerminal::Failed(failure) => {
157            let kind = match failure.kind() {
158                CoreFailureKind::DeadlineElapsed => CreateTopicsFailureKind::DeadlineElapsed,
159                CoreFailureKind::DriverRejected => CreateTopicsFailureKind::DriverRejected,
160                CoreFailureKind::Transport => CreateTopicsFailureKind::Transport,
161                CoreFailureKind::InvalidResponse => CreateTopicsFailureKind::InvalidResponse,
162            };
163            CreateTopicsOutcome::Failed(CreateTopicsFailure {
164                kind,
165                delivery: match failure.delivery() {
166                    CoreDeliveryStatus::NotSent => CreateTopicsDeliveryStatus::NotSent,
167                    CoreDeliveryStatus::PossiblySent => CreateTopicsDeliveryStatus::PossiblySent,
168                },
169            })
170        }
171    }
172}