Skip to main content

kafka_client_engine/transaction/initialization/
offset_outcome.rs

1//! Stable stage, delivery, consequence, and failure facts for transactional offsets.
2
3use kafka_client_core::{DeliveryStatus, TransactionOffsetCommitStage};
4
5use crate::transaction::offset_commit::{
6    TransactionOffsetCommitFailure as InternalFailure,
7    TransactionOffsetCommitFailureKind as InternalKind,
8    TransactionOffsetCommitOutcome as InternalOutcome,
9};
10
11/// Kafka request stage that terminally settled the offset transfer.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13pub enum TransactionOffsetsStage {
14    /// Adding the consumer group to the active transaction.
15    AddOffsets,
16    /// Writing the assignment-fenced offsets.
17    CommitOffsets,
18}
19
20/// Authoritative transport certainty for a failed stage.
21#[derive(Clone, Copy, Debug, Eq, PartialEq)]
22pub enum TransactionOffsetsDeliveryStatus {
23    /// The stage definitely did not enter transport ownership.
24    NotSent,
25    /// Kafka may have observed the stage.
26    PossiblySent,
27}
28
29/// Effect of the failure on the active transaction.
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub enum TransactionOffsetsConsequence {
32    /// The transaction remains eligible to continue or commit.
33    FailedHealthy,
34    /// The transaction may now only be aborted.
35    AbortRequired,
36    /// The initialized producer owner is permanently unusable.
37    Fatal,
38}
39
40/// Stable reason one accepted transactional offset transfer failed.
41#[derive(Clone, Copy, Debug, Eq, PartialEq)]
42pub enum TransactionOffsetsFailureKind {
43    /// The original public absolute deadline elapsed.
44    DeadlineElapsed,
45    /// Driver admission rejected before transport ownership.
46    DriverRejected,
47    /// Fixed local execution or terminal capacity was unavailable.
48    Backpressure,
49    /// The broker cannot execute the required protocol version.
50    Compatibility,
51    /// A response was malformed or did not match the exact request.
52    InvalidResponse,
53    /// Driver-owned transport execution failed.
54    Transport,
55    /// Kafka returned an exact signed broker rejection.
56    Broker,
57    /// Accepted operation identity or stage correlation failed.
58    Correlation,
59    /// The driver closed before stable settlement.
60    DriverClosed,
61}
62
63/// Exact failed stage, certainty, broker code, and transaction consequence.
64#[derive(Clone, Copy, Debug, Eq, PartialEq)]
65pub struct TransactionOffsetsFailure {
66    stage: TransactionOffsetsStage,
67    kind: TransactionOffsetsFailureKind,
68    delivery: TransactionOffsetsDeliveryStatus,
69    broker_code: Option<i16>,
70    consequence: TransactionOffsetsConsequence,
71}
72
73impl TransactionOffsetsFailure {
74    /// Returns the exact request stage that failed.
75    pub const fn stage(self) -> TransactionOffsetsStage {
76        self.stage
77    }
78    /// Returns the stable failure category.
79    pub const fn kind(self) -> TransactionOffsetsFailureKind {
80        self.kind
81    }
82    /// Returns authoritative transport certainty.
83    pub const fn delivery(self) -> TransactionOffsetsDeliveryStatus {
84        self.delivery
85    }
86    /// Returns Kafka's exact signed broker code when supplied.
87    pub const fn broker_code(self) -> Option<i16> {
88        self.broker_code
89    }
90    /// Returns the deterministic transaction-health consequence.
91    pub const fn consequence(self) -> TransactionOffsetsConsequence {
92        self.consequence
93    }
94}
95
96/// Exactly one public terminal for an accepted offset transfer.
97#[derive(Clone, Copy, Debug, Eq, PartialEq)]
98pub enum TransactionOffsetsOutcome {
99    /// Both Kafka request stages succeeded.
100    Succeeded,
101    /// One exact stage failed with explicit certainty and consequence.
102    Failed(TransactionOffsetsFailure),
103}
104
105pub(super) fn translate_offset_outcome(outcome: InternalOutcome) -> TransactionOffsetsOutcome {
106    match outcome {
107        InternalOutcome::Succeeded => TransactionOffsetsOutcome::Succeeded,
108        InternalOutcome::RejectedNotSent { stage, failure } => {
109            failed(stage, failure, TransactionOffsetsConsequence::FailedHealthy)
110        }
111        InternalOutcome::AbortRequired { stage, failure } => {
112            failed(stage, failure, TransactionOffsetsConsequence::AbortRequired)
113        }
114        InternalOutcome::Fatal { stage, failure } => {
115            failed(stage, failure, TransactionOffsetsConsequence::Fatal)
116        }
117    }
118}
119
120fn failed(
121    stage: TransactionOffsetCommitStage,
122    failure: InternalFailure,
123    consequence: TransactionOffsetsConsequence,
124) -> TransactionOffsetsOutcome {
125    let (kind, broker_code) = match failure.kind() {
126        InternalKind::DeadlineElapsed => (TransactionOffsetsFailureKind::DeadlineElapsed, None),
127        InternalKind::DriverRejected => (TransactionOffsetsFailureKind::DriverRejected, None),
128        InternalKind::Allocation => (TransactionOffsetsFailureKind::Backpressure, None),
129        InternalKind::Compatibility => (TransactionOffsetsFailureKind::Compatibility, None),
130        InternalKind::InvalidResponse => (TransactionOffsetsFailureKind::InvalidResponse, None),
131        InternalKind::Transport => (TransactionOffsetsFailureKind::Transport, None),
132        InternalKind::Broker { code, .. } => (TransactionOffsetsFailureKind::Broker, Some(code)),
133        InternalKind::Correlation => (TransactionOffsetsFailureKind::Correlation, None),
134        InternalKind::DriverShutdown => (TransactionOffsetsFailureKind::DriverClosed, None),
135    };
136    TransactionOffsetsOutcome::Failed(TransactionOffsetsFailure {
137        stage: match stage {
138            TransactionOffsetCommitStage::AddOffsets => TransactionOffsetsStage::AddOffsets,
139            TransactionOffsetCommitStage::TxnOffsetCommit => TransactionOffsetsStage::CommitOffsets,
140        },
141        kind,
142        delivery: match failure.delivery() {
143            DeliveryStatus::NotSent => TransactionOffsetsDeliveryStatus::NotSent,
144            DeliveryStatus::PossiblySent => TransactionOffsetsDeliveryStatus::PossiblySent,
145        },
146        broker_code,
147        consequence,
148    })
149}