Skip to main content

kafka_client_engine/admin/create_acls/
outcome.rs

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