Skip to main content

kafka_client_engine/transaction/initialization/
offset_admission.rs

1//! Stable public rejection and exact input recovery for transactional offsets.
2
3use core::fmt;
4
5use crate::consumer::{GroupConsumerCheckpoint, GroupConsumerMetadata};
6
7use super::TransactionOffsetCommitControlError;
8
9/// Stable reason transactional offsets did not cross admission.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11pub enum TransactionOffsetsAdmissionErrorKind {
12    /// The timeout could not form a positive absolute deadline.
13    InvalidDeadline,
14    /// Metadata and checkpoint do not name the same live assignment fence.
15    StaleCheckpoint,
16    /// Another caller currently owns the bounded transaction shard.
17    Contended,
18    /// Engine shutdown closed transactional offset admission.
19    Closed,
20    /// The initialized producer owner is no longer installed.
21    StaleOwner,
22    /// Another transactional offset transfer owns the fixed slot.
23    Busy,
24    /// Completion or retained-input capacity rejected the operation.
25    Backpressure,
26    /// The transaction lifecycle does not accept offset transfer.
27    InvalidLifecycle,
28    /// The metadata or checkpoint contains invalid broker input.
29    InvalidInput,
30    /// A nonreused operation identity was exhausted.
31    IdentityExhausted,
32}
33
34/// Definitely-unsent rejection retaining the exact metadata and checkpoint.
35#[must_use = "transactional offset rejection retains the original inputs"]
36pub struct TransactionOffsetsAdmissionError {
37    kind: TransactionOffsetsAdmissionErrorKind,
38    metadata: GroupConsumerMetadata,
39    checkpoint: GroupConsumerCheckpoint,
40}
41
42impl TransactionOffsetsAdmissionError {
43    pub(super) const fn new(
44        kind: TransactionOffsetsAdmissionErrorKind,
45        metadata: GroupConsumerMetadata,
46        checkpoint: GroupConsumerCheckpoint,
47    ) -> Self {
48        Self {
49            kind,
50            metadata,
51            checkpoint,
52        }
53    }
54
55    /// Returns the stable admission category.
56    pub const fn kind(&self) -> TransactionOffsetsAdmissionErrorKind {
57        self.kind
58    }
59
60    /// Recovers both exact caller inputs.
61    pub fn into_parts(self) -> (GroupConsumerMetadata, GroupConsumerCheckpoint) {
62        (self.metadata, self.checkpoint)
63    }
64}
65
66impl fmt::Debug for TransactionOffsetsAdmissionError {
67    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
68        formatter
69            .debug_struct("TransactionOffsetsAdmissionError")
70            .field("kind", &self.kind)
71            .field("metadata", &self.metadata)
72            .field("checkpoint", &self.checkpoint)
73            .finish()
74    }
75}
76
77impl fmt::Display for TransactionOffsetsAdmissionError {
78    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
79        write!(formatter, "transactional offsets rejected: {:?}", self.kind)
80    }
81}
82
83impl std::error::Error for TransactionOffsetsAdmissionError {}
84
85pub(super) const fn control_error_kind(
86    error: &TransactionOffsetCommitControlError,
87) -> TransactionOffsetsAdmissionErrorKind {
88    use crate::transaction::offset_commit::TransactionOffsetCommitAdmissionErrorKind as Internal;
89    match error.kind() {
90        super::TransactionOffsetCommitControlErrorKind::Contended => {
91            TransactionOffsetsAdmissionErrorKind::Contended
92        }
93        super::TransactionOffsetCommitControlErrorKind::Closed => {
94            TransactionOffsetsAdmissionErrorKind::Closed
95        }
96        super::TransactionOffsetCommitControlErrorKind::Admission(kind) => match kind {
97            Internal::Busy => TransactionOffsetsAdmissionErrorKind::Busy,
98            Internal::CompletionCapacity
99            | Internal::OffsetCount { .. }
100            | Internal::RetainedBytes { .. } => TransactionOffsetsAdmissionErrorKind::Backpressure,
101            Internal::StaleOwner => TransactionOffsetsAdmissionErrorKind::StaleOwner,
102            Internal::InvalidLifecycle => TransactionOffsetsAdmissionErrorKind::InvalidLifecycle,
103            Internal::InvalidInput => TransactionOffsetsAdmissionErrorKind::InvalidInput,
104            Internal::IdentityExhausted => TransactionOffsetsAdmissionErrorKind::IdentityExhausted,
105        },
106    }
107}