Skip to main content

kafka_client_engine/admin/topics/
outcome.rs

1//! Engine-owned terminal representation for one ordered `DescribeTopics` query.
2
3use core::fmt;
4
5mod translate;
6pub(crate) use translate::translate_terminal;
7#[cfg(test)]
8mod translate_test;
9
10/// Stable admin delivery certainty independent of core types.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum DescribeTopicsDeliveryStatus {
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 normalized topic.
20#[derive(Clone, Copy, Debug, Eq, PartialEq)]
21pub struct DescribeTopicError {
22    code: i16,
23}
24
25impl DescribeTopicError {
26    /// Returns Kafka's exact signed error code.
27    pub const fn code(self) -> i16 {
28        self.code
29    }
30}
31
32/// Stable description of one topic partition.
33#[derive(Clone, Debug, Eq, PartialEq)]
34pub struct TopicPartitionDescription {
35    partition_index: i32,
36    error_code: Option<i16>,
37    leader_id: Option<i32>,
38    leader_epoch: Option<i32>,
39    replicas: Vec<i32>,
40    in_sync_replicas: Vec<i32>,
41    offline_replicas: Vec<i32>,
42}
43
44impl TopicPartitionDescription {
45    /// Consumes the description into stable adapter-owned parts.
46    #[allow(clippy::type_complexity)]
47    pub fn into_parts(
48        self,
49    ) -> (
50        i32,
51        Option<i16>,
52        Option<i32>,
53        Option<i32>,
54        Vec<i32>,
55        Vec<i32>,
56        Vec<i32>,
57    ) {
58        (
59            self.partition_index,
60            self.error_code,
61            self.leader_id,
62            self.leader_epoch,
63            self.replicas,
64            self.in_sync_replicas,
65            self.offline_replicas,
66        )
67    }
68}
69
70/// Stable description of one normalized topic.
71#[derive(Clone, Debug, Eq, PartialEq)]
72pub struct TopicDescription {
73    name: String,
74    topic_id: Option<[u8; 16]>,
75    internal: bool,
76    partitions: Vec<TopicPartitionDescription>,
77    authorized_operations: Option<i32>,
78}
79
80impl TopicDescription {
81    /// Consumes the description into stable adapter-owned parts.
82    pub fn into_parts(
83        self,
84    ) -> (
85        String,
86        Option<[u8; 16]>,
87        bool,
88        Vec<TopicPartitionDescription>,
89        Option<i32>,
90    ) {
91        (
92            self.name,
93            self.topic_id,
94            self.internal,
95            self.partitions,
96            self.authorized_operations,
97        )
98    }
99}
100
101/// One per-topic terminal in policy-defined deterministic order.
102#[derive(Clone, Debug, Eq, PartialEq)]
103pub struct DescribeTopicResult {
104    topic: String,
105    internal: bool,
106    result: Result<TopicDescription, DescribeTopicError>,
107}
108
109/// One topic-ID-keyed terminal in caller order.
110#[derive(Clone, Debug, Eq, PartialEq)]
111pub struct DescribeTopicIdResult {
112    topic_id: [u8; 16],
113    result: Result<TopicDescription, DescribeTopicError>,
114}
115
116impl DescribeTopicIdResult {
117    /// Consumes the ordered result into stable adapter-owned parts.
118    pub fn into_parts(self) -> ([u8; 16], Result<TopicDescription, DescribeTopicError>) {
119        (self.topic_id, self.result)
120    }
121}
122
123impl DescribeTopicResult {
124    /// Consumes the ordered result into stable adapter-owned parts.
125    pub fn into_parts(self) -> (String, bool, Result<TopicDescription, DescribeTopicError>) {
126        (self.topic, self.internal, self.result)
127    }
128}
129
130/// Stable whole-operation failure category.
131#[derive(Clone, Copy, Debug, Eq, PartialEq)]
132pub enum DescribeTopicsFailureKind {
133    /// The original deadline elapsed before driver ownership.
134    DeadlineElapsed,
135    /// The generated request was rejected before driver ownership.
136    DriverRejected,
137    /// Driver-owned transport execution failed.
138    Transport,
139    /// Kafka rejected the whole Metadata request with this exact code.
140    Broker(i16),
141    /// A valid response exceeded the admitted retained-result budget.
142    ResponseTooLarge,
143    /// The broker cannot represent the operation's required read-only policy.
144    Compatibility,
145    /// The broker response could not be correlated.
146    InvalidResponse,
147}
148
149/// Whole-operation failure with authoritative delivery certainty.
150#[derive(Clone, Copy, Debug, Eq, PartialEq)]
151pub struct DescribeTopicsFailure {
152    kind: DescribeTopicsFailureKind,
153    delivery: DescribeTopicsDeliveryStatus,
154}
155
156impl DescribeTopicsFailure {
157    /// Returns the stable failure category.
158    pub const fn kind(self) -> DescribeTopicsFailureKind {
159        self.kind
160    }
161
162    /// Returns authoritative delivery certainty.
163    pub const fn delivery(self) -> DescribeTopicsDeliveryStatus {
164        self.delivery
165    }
166}
167
168/// Exactly one engine-owned terminal decision.
169#[derive(Clone, Debug, Eq, PartialEq)]
170pub enum DescribeTopicsOutcome {
171    /// Ordered broker outcomes.
172    Topics(Vec<DescribeTopicResult>),
173    /// Caller-ordered topic-ID-keyed broker outcomes.
174    TopicIds(Vec<DescribeTopicIdResult>),
175    /// Whole-operation failure outside per-topic results.
176    Failed(DescribeTopicsFailure),
177}
178
179/// Failure to observe a named completion.
180#[derive(Clone, Copy, Debug, Eq, PartialEq)]
181pub enum DescribeTopicsObserverError {
182    /// This linear observer already consumed its terminal.
183    AlreadyObserved,
184    /// The observer generation is no longer live.
185    Stale,
186}
187
188impl fmt::Display for DescribeTopicsObserverError {
189    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
190        formatter.write_str(match self {
191            Self::AlreadyObserved => "DescribeTopics result was already observed",
192            Self::Stale => "DescribeTopics observer is stale",
193        })
194    }
195}
196
197impl std::error::Error for DescribeTopicsObserverError {}