Skip to main content

kafka_client_engine/transaction/initialization/
send_outcome.rs

1//! Stable public outcomes for one accepted transactional record send.
2
3use std::sync::Arc;
4
5use kafka_client_core::{ProducerBatchSuccess, TransactionEpoch, TransactionSendId};
6
7use crate::transaction::send::TransactionSendTerminal as InternalTerminal;
8
9use super::send_failure_mapping::public_failure;
10
11/// Authoritative transport certainty for a failed transactional send.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13pub enum TransactionSendDeliveryStatus {
14    /// The record definitely did not enter transport ownership.
15    NotSent,
16    /// Kafka may have observed the record.
17    PossiblySent,
18}
19
20/// Deterministic effect of a failed send on the active transaction.
21#[derive(Clone, Copy, Debug, Eq, PartialEq)]
22pub enum TransactionSendConsequence {
23    /// This send failed, but the transaction remains eligible to commit.
24    FailedHealthy,
25    /// The transaction may now only be aborted.
26    AbortRequired,
27    /// The initialized producer owner is permanently unusable.
28    Fatal,
29}
30
31/// Stable reason one accepted transactional send failed.
32#[derive(Clone, Copy, Debug, Eq, PartialEq)]
33pub enum TransactionSendFailureKind {
34    /// Another bounded transactional send owns the sole slot.
35    Busy,
36    /// The active transaction no longer matches the send.
37    StaleTransaction,
38    /// The initialized transactional owner is unavailable.
39    OwnerUnavailable,
40    /// Topic or partition routing was invalid.
41    InvalidTarget,
42    /// A fixed record, topic, partition, or driver capacity was full.
43    Backpressure,
44    /// The original public absolute deadline elapsed.
45    DeadlineElapsed,
46    /// Driver admission rejected before transport ownership.
47    DriverRejected,
48    /// Driver-owned transport execution failed.
49    Transport,
50    /// The negotiated protocol or record format was incompatible.
51    Compatibility,
52    /// Broker response shape or correlation was invalid.
53    InvalidResponse,
54    /// The driver or its completion owner closed.
55    DriverClosed,
56    /// Kafka returned an exact signed broker rejection.
57    Broker,
58    /// Record-batch materialization failed before Produce ownership.
59    Materialization,
60    /// No usable broker route was available.
61    Routing,
62    /// A required broker name could not be resolved.
63    NameResolution,
64    /// A usable connection generation was unavailable.
65    ConnectionUnavailable,
66    /// A structural failure cannot be repaired by retry.
67    Permanent,
68    /// Internal epoch or send correlation failed.
69    Correlation,
70}
71
72/// Exact failure, delivery certainty, and transaction consequence.
73#[derive(Clone, Copy, Debug, Eq, PartialEq)]
74pub struct TransactionSendFailure {
75    pub(super) kind: TransactionSendFailureKind,
76    pub(super) delivery: TransactionSendDeliveryStatus,
77    pub(super) broker_code: Option<i16>,
78    pub(super) consequence: TransactionSendConsequence,
79}
80
81impl TransactionSendFailure {
82    /// Returns the stable failure category.
83    pub const fn kind(self) -> TransactionSendFailureKind {
84        self.kind
85    }
86
87    /// Returns authoritative transport certainty.
88    pub const fn delivery(self) -> TransactionSendDeliveryStatus {
89        self.delivery
90    }
91
92    /// Returns Kafka's exact signed broker code when present.
93    pub const fn broker_code(self) -> Option<i16> {
94        self.broker_code
95    }
96
97    /// Returns this send failure's deterministic transaction consequence.
98    pub const fn consequence(self) -> TransactionSendConsequence {
99        self.consequence
100    }
101}
102
103/// Kafka acknowledgment metadata for one transactional record.
104#[derive(Clone, Debug, Eq, PartialEq)]
105pub struct TransactionSendMetadata {
106    topic: Arc<str>,
107    partition: i32,
108    offset: i64,
109    timestamp: Option<i64>,
110    leader_epoch: Option<i32>,
111}
112
113impl TransactionSendMetadata {
114    /// Returns the exact canonical topic spelling admitted for this send.
115    pub fn topic(&self) -> &str {
116        &self.topic
117    }
118
119    /// Returns the acknowledged zero-based partition.
120    pub const fn partition(&self) -> i32 {
121        self.partition
122    }
123
124    /// Returns the record's absolute Kafka offset.
125    pub const fn offset(&self) -> i64 {
126        self.offset
127    }
128
129    /// Returns Kafka's append timestamp when supplied.
130    pub const fn timestamp(&self) -> Option<i64> {
131        self.timestamp
132    }
133
134    /// Returns Kafka's leader epoch when supplied.
135    pub const fn leader_epoch(&self) -> Option<i32> {
136        self.leader_epoch
137    }
138}
139
140/// Exactly one public terminal for an accepted transactional record send.
141#[derive(Clone, Debug, Eq, PartialEq)]
142pub enum TransactionSendOutcome {
143    /// Kafka acknowledged the record.
144    Succeeded(TransactionSendMetadata),
145    /// The record failed with an explicit transaction consequence.
146    Failed(TransactionSendFailure),
147}
148
149pub(super) fn translate_send_terminal(
150    terminal: InternalTerminal,
151    epoch: TransactionEpoch,
152    send_id: TransactionSendId,
153    topic: Arc<str>,
154    partition: Option<i32>,
155) -> Option<TransactionSendOutcome> {
156    match terminal {
157        InternalTerminal::Succeeded {
158            epoch: actual_epoch,
159            send_id: actual_send_id,
160            partition: actual_partition,
161            success,
162        } if actual_epoch == epoch
163            && actual_send_id == send_id
164            && partition.is_none_or(|partition| {
165                u32::try_from(partition).ok() == Some(actual_partition.get())
166            }) =>
167        {
168            let partition = i32::try_from(actual_partition.get()).ok()?;
169            Some(TransactionSendOutcome::Succeeded(success_metadata(
170                success, topic, partition,
171            )))
172        }
173        InternalTerminal::FailedHealthy {
174            epoch: actual_epoch,
175            send_id: actual_send_id,
176            failure,
177        } if actual_epoch == epoch && actual_send_id == send_id => Some(public_failure(
178            failure,
179            TransactionSendConsequence::FailedHealthy,
180        )),
181        InternalTerminal::AbortRequired {
182            epoch: actual_epoch,
183            send_id: actual_send_id,
184            failure,
185        } if actual_epoch == epoch && actual_send_id == send_id => Some(public_failure(
186            failure,
187            TransactionSendConsequence::AbortRequired,
188        )),
189        InternalTerminal::Fatal {
190            epoch: actual_epoch,
191            send_id: actual_send_id,
192            failure,
193        } if actual_epoch == epoch && actual_send_id == send_id => {
194            Some(public_failure(failure, TransactionSendConsequence::Fatal))
195        }
196        _ => None,
197    }
198}
199
200fn success_metadata(
201    success: ProducerBatchSuccess,
202    topic: Arc<str>,
203    partition: i32,
204) -> TransactionSendMetadata {
205    TransactionSendMetadata {
206        topic,
207        partition,
208        offset: success.base_offset(),
209        timestamp: success.append_timestamp(),
210        leader_epoch: success.leader_epoch(),
211    }
212}