Skip to main content

kafka_client_engine/admin/update_features/
outcome.rs

1//! Stable generated-free terminals for Admin `UpdateFeatures`.
2
3use core::fmt;
4
5mod translate;
6
7pub(crate) use translate::translate_terminal;
8
9/// Stable delivery certainty independent of core and driver types.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11pub enum UpdateFeaturesDeliveryStatus {
12    /// The failed call did not reach Kafka.
13    NotSent,
14    /// The failed call may have reached Kafka.
15    PossiblySent,
16}
17
18/// Exact Kafka rejection and bounded nullable diagnostic.
19#[derive(Clone, Debug, Eq, PartialEq)]
20pub struct UpdateFeaturesBrokerError {
21    pub(super) code: i16,
22    pub(super) message: Option<String>,
23    pub(super) message_truncated: bool,
24}
25
26impl UpdateFeaturesBrokerError {
27    /// Returns Kafka's exact signed error code.
28    pub const fn code(&self) -> i16 {
29        self.code
30    }
31
32    /// Returns Kafka's nullable UTF-8-safe diagnostic prefix.
33    pub fn message(&self) -> Option<&str> {
34        self.message.as_deref()
35    }
36
37    /// Reports whether a present diagnostic was truncated.
38    pub const fn message_truncated(&self) -> bool {
39        self.message_truncated
40    }
41
42    /// Consumes this rejection into exact diagnostic parts.
43    pub fn into_parts(self) -> (i16, Option<String>, bool) {
44        (self.code, self.message, self.message_truncated)
45    }
46}
47
48/// Stable result for one requested finalized feature.
49#[derive(Clone, Debug, Eq, PartialEq)]
50pub enum UpdateFeatureResult {
51    /// Kafka accepted or atomically validated this feature update.
52    Updated,
53    /// An older broker rejected this feature independently.
54    Failed(UpdateFeaturesBrokerError),
55}
56
57/// One finalized-feature result in original request order.
58#[derive(Clone, Debug, Eq, PartialEq)]
59pub struct UpdateFeatureOutcome {
60    pub(super) feature: String,
61    pub(super) result: UpdateFeatureResult,
62}
63
64impl UpdateFeatureOutcome {
65    /// Returns the correlated finalized-feature name.
66    pub fn feature(&self) -> &str {
67        &self.feature
68    }
69
70    /// Returns the exact per-feature result.
71    pub const fn result(&self) -> &UpdateFeatureResult {
72        &self.result
73    }
74
75    /// Consumes this row into its feature and result.
76    pub fn into_parts(self) -> (String, UpdateFeatureResult) {
77        (self.feature, self.result)
78    }
79}
80
81/// Caller-ordered finalized-feature results plus Kafka's throttle observation.
82#[derive(Clone, Debug, Eq, PartialEq)]
83pub struct UpdateFeaturesBatch {
84    pub(super) throttle_time_ms: u32,
85    pub(super) outcomes: Vec<UpdateFeatureOutcome>,
86}
87
88impl UpdateFeaturesBatch {
89    /// Returns Kafka's nonnegative throttle observation.
90    pub const fn throttle_time_ms(&self) -> u32 {
91        self.throttle_time_ms
92    }
93
94    /// Returns exactly one result per requested finalized feature.
95    pub fn outcomes(&self) -> &[UpdateFeatureOutcome] {
96        &self.outcomes
97    }
98
99    /// Consumes throttle and caller-ordered feature results.
100    pub fn into_parts(self) -> (u32, Vec<UpdateFeatureOutcome>) {
101        (self.throttle_time_ms, self.outcomes)
102    }
103}
104
105/// Stable whole-operation failure category.
106#[derive(Clone, Debug, Eq, PartialEq)]
107pub enum UpdateFeaturesFailureKind {
108    /// The original absolute deadline elapsed.
109    DeadlineElapsed,
110    /// Driver admission rejected the sole prepared request.
111    DriverRejected,
112    /// Driver-owned transport execution failed.
113    Transport,
114    /// Kafka rejected the complete atomic operation.
115    Broker(UpdateFeaturesBrokerError),
116    /// A valid response exceeded the admitted retained envelope.
117    ResponseTooLarge,
118    /// The selected API version cannot represent required semantics.
119    Compatibility,
120    /// A response was malformed or could not be correlated.
121    InvalidResponse,
122}
123
124/// Whole-operation failure with authoritative delivery certainty.
125#[derive(Clone, Debug, Eq, PartialEq)]
126pub struct UpdateFeaturesFailure {
127    pub(super) kind: UpdateFeaturesFailureKind,
128    pub(super) delivery: UpdateFeaturesDeliveryStatus,
129}
130
131impl UpdateFeaturesFailure {
132    /// Returns the stable failure category.
133    pub const fn kind(&self) -> &UpdateFeaturesFailureKind {
134        &self.kind
135    }
136
137    /// Returns authoritative delivery certainty.
138    pub const fn delivery(&self) -> UpdateFeaturesDeliveryStatus {
139        self.delivery
140    }
141}
142
143/// Exactly one engine-owned terminal decision.
144#[derive(Clone, Debug, Eq, PartialEq)]
145pub enum UpdateFeaturesOutcome {
146    /// Kafka returned one result per requested finalized feature.
147    Updated(UpdateFeaturesBatch),
148    /// The operation failed outside a valid feature-result batch.
149    Failed(UpdateFeaturesFailure),
150}
151
152/// Failure to observe one named completion.
153#[derive(Clone, Copy, Debug, Eq, PartialEq)]
154pub enum UpdateFeaturesObserverError {
155    /// This linear observer already consumed its terminal.
156    AlreadyObserved,
157    /// The observer generation is no longer live.
158    Stale,
159}
160
161impl fmt::Display for UpdateFeaturesObserverError {
162    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
163        formatter.write_str(match self {
164            Self::AlreadyObserved => "Admin UpdateFeatures result was already observed",
165            Self::Stale => "Admin UpdateFeatures observer is stale",
166        })
167    }
168}
169
170impl std::error::Error for UpdateFeaturesObserverError {}