Skip to main content

kafka_client_engine/transaction/initialization/
outcome.rs

1//! Stable terminal values for transaction initialization.
2
3use kafka_client_core::{
4    DeliveryStatus, TransactionInitializationBrokerCategory,
5    TransactionInitializationFailureKind as CoreFailureKind, TransactionInitializationTerminal,
6};
7
8use super::{
9    RetainedTransactionInitializationOutcome, TransactionInitializationHostError,
10    TransactionInitializationObserver, TransactionalOwnerHandle,
11};
12
13/// Advisory fault reported only after initialization was accepted.
14#[derive(Clone, Copy, Debug, Eq, PartialEq)]
15pub enum TransactionInitializationAcceptedFaultKind {
16    /// The operation was accepted but the advisory host wake failed.
17    Wake,
18    /// The operation was accepted but its owner reported an invariant fault.
19    HostInvariant,
20}
21
22/// Accepted initialization with one sole terminal observer.
23#[derive(Debug)]
24#[must_use = "accepted initialization retains its sole terminal observer"]
25pub struct TransactionInitializationAccepted {
26    pub(super) observer: TransactionInitializationObserver,
27    pub(super) fault: Option<TransactionInitializationAcceptedFaultKind>,
28}
29
30impl TransactionInitializationAccepted {
31    /// Returns an advisory post-acceptance host diagnostic.
32    pub const fn fault(&self) -> Option<TransactionInitializationAcceptedFaultKind> {
33        self.fault
34    }
35
36    /// Transfers the sole terminal observer.
37    pub fn into_observer(self) -> TransactionInitializationObserver {
38        self.observer
39    }
40}
41
42/// Delivery certainty for a failed initialization attempt.
43#[derive(Clone, Copy, Debug, Eq, PartialEq)]
44pub enum TransactionInitializationDeliveryStatus {
45    /// The request definitely did not enter transport ownership.
46    NotSent,
47    /// Kafka may have observed the request.
48    PossiblySent,
49}
50
51/// Stable semantic category for a terminal initialization failure.
52#[derive(Clone, Copy, Debug, Eq, PartialEq)]
53pub enum TransactionInitializationFailureKind {
54    /// The original absolute operation deadline elapsed.
55    DeadlineElapsed,
56    /// Bounded driver admission rejected before transport ownership.
57    DriverRejected,
58    /// Transport failed after accepting the request.
59    Transport,
60    /// Kafka returned an exact signed broker code and optional fencing fact.
61    Broker {
62        /// Kafka's exact signed protocol error code.
63        code: i16,
64        /// Whether core classified the broker response as fencing.
65        fenced: bool,
66    },
67    /// The broker response violated the transaction initialization contract.
68    InvalidResponse,
69    /// The initialized identity could not be installed into bounded execution ownership.
70    ExecutionUnavailable,
71}
72
73/// One terminal initialization failure with authoritative delivery certainty.
74#[derive(Clone, Copy, Debug, Eq, PartialEq)]
75pub struct TransactionInitializationFailure {
76    pub(crate) kind: TransactionInitializationFailureKind,
77    pub(crate) delivery: TransactionInitializationDeliveryStatus,
78}
79
80impl TransactionInitializationFailure {
81    /// Returns the stable failure category.
82    pub const fn kind(self) -> TransactionInitializationFailureKind {
83        self.kind
84    }
85
86    /// Returns authoritative delivery certainty.
87    pub const fn delivery(self) -> TransactionInitializationDeliveryStatus {
88        self.delivery
89    }
90}
91
92/// Exactly one engine-owned terminal initialization decision.
93#[derive(Debug)]
94pub enum TransactionInitializationOutcome {
95    /// Kafka initialized one unique idle owner.
96    Initialized(TransactionalOwnerHandle),
97    /// Initialization failed without producing an owner.
98    Failed(TransactionInitializationFailure),
99}
100
101/// Failure to observe a named initialization completion.
102#[derive(Clone, Copy, Debug, Eq, PartialEq)]
103pub enum TransactionInitializationObserverError {
104    /// This linear observer already consumed its terminal.
105    AlreadyObserved,
106    /// The observer generation is no longer live.
107    Stale,
108}
109
110impl std::fmt::Display for TransactionInitializationObserverError {
111    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
112        formatter.write_str(match self {
113            Self::AlreadyObserved => "transaction initialization was already observed",
114            Self::Stale => "transaction initialization observer is stale",
115        })
116    }
117}
118
119impl std::error::Error for TransactionInitializationObserverError {}
120
121pub(super) fn failed_retained_outcome(
122    terminal: TransactionInitializationTerminal,
123) -> Option<RetainedTransactionInitializationOutcome> {
124    let TransactionInitializationTerminal::Failed(failure) = terminal else {
125        return None;
126    };
127    let kind = match failure.kind() {
128        CoreFailureKind::DeadlineElapsed => {
129            self::TransactionInitializationFailureKind::DeadlineElapsed
130        }
131        CoreFailureKind::DriverRejected => {
132            self::TransactionInitializationFailureKind::DriverRejected
133        }
134        CoreFailureKind::Transport => self::TransactionInitializationFailureKind::Transport,
135        CoreFailureKind::Broker(broker) => self::TransactionInitializationFailureKind::Broker {
136            code: broker.code(),
137            fenced: broker.category() == TransactionInitializationBrokerCategory::Fenced,
138        },
139        CoreFailureKind::InvalidResponse => {
140            self::TransactionInitializationFailureKind::InvalidResponse
141        }
142    };
143    Some(RetainedTransactionInitializationOutcome::Failed(
144        TransactionInitializationFailure {
145            kind,
146            delivery: delivery(failure.delivery()),
147        },
148    ))
149}
150
151pub(super) const fn accepted_fault(
152    error: TransactionInitializationHostError,
153) -> TransactionInitializationAcceptedFaultKind {
154    match error {
155        TransactionInitializationHostError::Wake => {
156            TransactionInitializationAcceptedFaultKind::Wake
157        }
158        _ => TransactionInitializationAcceptedFaultKind::HostInvariant,
159    }
160}
161
162pub(super) const fn execution_unavailable_retained_outcome()
163-> RetainedTransactionInitializationOutcome {
164    RetainedTransactionInitializationOutcome::Failed(TransactionInitializationFailure {
165        kind: TransactionInitializationFailureKind::ExecutionUnavailable,
166        delivery: TransactionInitializationDeliveryStatus::PossiblySent,
167    })
168}
169
170const fn delivery(status: DeliveryStatus) -> TransactionInitializationDeliveryStatus {
171    match status {
172        DeliveryStatus::NotSent => TransactionInitializationDeliveryStatus::NotSent,
173        DeliveryStatus::PossiblySent => TransactionInitializationDeliveryStatus::PossiblySent,
174    }
175}