Skip to main content

kafka_client_engine/consumer/group_event/
error.rs

1//! Stable failure categories for classic-group event observation.
2
3use crate::consumer::{
4    ClassicGroupRevocationAcknowledgeError, GroupConsumerEventPortError,
5    GroupConsumerRevocationPortError, GroupConsumerShardLockError,
6};
7
8/// Stable reason graceful assignment release could not be completed.
9#[derive(Clone, Copy, Debug, Eq, PartialEq)]
10pub enum GroupConsumerRevocationAcknowledgeErrorKind {
11    /// Group or engine admission has closed.
12    Closed,
13    /// Another owner currently holds the classic-group shard.
14    Contended,
15    /// The synchronized engine host can no longer expose the group owner.
16    HostUnavailable,
17    /// The registered group no longer accepts this operation.
18    GroupUnavailable,
19    /// No active graceful lease matches the supplied assignment epoch.
20    StaleAssignmentEpoch,
21    /// The one absolute graceful-release deadline already elapsed.
22    DeadlineElapsed,
23    /// Monotonic time could not be observed.
24    Clock,
25    /// Internal ownership was inconsistent.
26    InternalInvariant,
27}
28
29/// Failure to complete one exact graceful-release assignment epoch.
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub struct GroupConsumerRevocationAcknowledgeError {
32    kind: GroupConsumerRevocationAcknowledgeErrorKind,
33}
34
35impl GroupConsumerRevocationAcknowledgeError {
36    pub(in crate::consumer) const fn from_port(error: GroupConsumerRevocationPortError) -> Self {
37        use GroupConsumerRevocationAcknowledgeErrorKind as Kind;
38        let kind = match error {
39            GroupConsumerRevocationPortError::Closed => Kind::Closed,
40            GroupConsumerRevocationPortError::Clock(_) => Kind::Clock,
41            GroupConsumerRevocationPortError::Lock(GroupConsumerShardLockError::Contended) => {
42                Kind::Contended
43            }
44            GroupConsumerRevocationPortError::Lock(GroupConsumerShardLockError::Poisoned) => {
45                Kind::HostUnavailable
46            }
47            GroupConsumerRevocationPortError::UnknownGroup
48            | GroupConsumerRevocationPortError::GroupUnavailable => Kind::GroupUnavailable,
49            GroupConsumerRevocationPortError::Acknowledge(
50                ClassicGroupRevocationAcknowledgeError::NoActiveLease
51                | ClassicGroupRevocationAcknowledgeError::AssignmentEpochMismatch,
52            ) => Kind::StaleAssignmentEpoch,
53            GroupConsumerRevocationPortError::Acknowledge(
54                ClassicGroupRevocationAcknowledgeError::DeadlineElapsed,
55            ) => Kind::DeadlineElapsed,
56            GroupConsumerRevocationPortError::Acknowledge(
57                ClassicGroupRevocationAcknowledgeError::Core(_)
58                | ClassicGroupRevocationAcknowledgeError::UnexpectedEffect,
59            ) => Kind::InternalInvariant,
60        };
61        Self { kind }
62    }
63
64    /// Returns the stable completion failure category.
65    pub const fn kind(self) -> GroupConsumerRevocationAcknowledgeErrorKind {
66        self.kind
67    }
68}
69
70impl std::fmt::Display for GroupConsumerRevocationAcknowledgeError {
71    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
72        write!(
73            formatter,
74            "classic-group revocation completion failed: {:?}",
75            self.kind
76        )
77    }
78}
79
80impl std::error::Error for GroupConsumerRevocationAcknowledgeError {}
81
82/// Stable reason current confirmed membership could not be observed immediately.
83#[derive(Clone, Copy, Debug, Eq, PartialEq)]
84pub enum GroupConsumerStateErrorKind {
85    /// Another owner currently holds the classic-group shard.
86    Contended,
87    /// The synchronized engine host can no longer expose group state.
88    HostUnavailable,
89    /// Snapshot storage could not be reserved within the bounded assignment.
90    Allocation,
91    /// Internal group ownership was inconsistent.
92    InternalInvariant,
93}
94
95/// Failure to observe current confirmed membership without waiting.
96#[derive(Clone, Copy, Debug, Eq, PartialEq)]
97pub struct GroupConsumerStateError {
98    kind: GroupConsumerStateErrorKind,
99}
100
101impl GroupConsumerStateError {
102    pub(in crate::consumer) const fn new(kind: GroupConsumerStateErrorKind) -> Self {
103        Self { kind }
104    }
105
106    /// Returns the stable immediate-observation category.
107    pub const fn kind(self) -> GroupConsumerStateErrorKind {
108        self.kind
109    }
110}
111
112impl std::fmt::Display for GroupConsumerStateError {
113    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
114        write!(
115            formatter,
116            "classic-group state observation failed: {:?}",
117            self.kind
118        )
119    }
120}
121
122impl std::error::Error for GroupConsumerStateError {}
123
124/// Stable reason immediate event observation could not complete.
125#[derive(Clone, Copy, Debug, Eq, PartialEq)]
126pub enum GroupConsumerTryTakeEventErrorKind {
127    /// Another owner or caller currently holds the classic-group shard.
128    Contended,
129    /// The synchronized engine host can no longer expose retained events.
130    HostUnavailable,
131    /// A non-semantic engine mechanism violated its ownership contract.
132    InternalInvariant,
133}
134
135/// Immediate observation failure before a retained event transferred.
136#[derive(Clone, Copy, Debug, Eq, PartialEq)]
137pub struct GroupConsumerTryTakeEventError {
138    kind: GroupConsumerTryTakeEventErrorKind,
139}
140
141impl GroupConsumerTryTakeEventError {
142    pub(in crate::consumer) const fn from_port(error: GroupConsumerEventPortError) -> Self {
143        Self {
144            kind: match error {
145                GroupConsumerEventPortError::Lock(GroupConsumerShardLockError::Contended) => {
146                    GroupConsumerTryTakeEventErrorKind::Contended
147                }
148                GroupConsumerEventPortError::Lock(GroupConsumerShardLockError::Poisoned) => {
149                    GroupConsumerTryTakeEventErrorKind::HostUnavailable
150                }
151                GroupConsumerEventPortError::Closed | GroupConsumerEventPortError::Registry(_) => {
152                    GroupConsumerTryTakeEventErrorKind::InternalInvariant
153                }
154            },
155        }
156    }
157
158    /// Returns the stable immediate-observation category.
159    pub const fn kind(&self) -> GroupConsumerTryTakeEventErrorKind {
160        self.kind
161    }
162}
163
164impl std::fmt::Display for GroupConsumerTryTakeEventError {
165    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
166        write!(
167            formatter,
168            "classic-group immediate event observation failed: {:?}",
169            self.kind
170        )
171    }
172}
173
174impl std::error::Error for GroupConsumerTryTakeEventError {}
175
176/// Stable reason one event observation could not continue.
177#[derive(Clone, Copy, Debug, Eq, PartialEq)]
178pub enum GroupConsumerNextEventErrorKind {
179    /// The embedded host or registered group is unavailable.
180    HostUnavailable,
181    /// Event ownership or notification state was inconsistent.
182    InternalInvariant,
183}
184
185/// Event observation failure with a stable public category.
186#[derive(Clone, Copy, Debug, Eq, PartialEq)]
187pub struct GroupConsumerNextEventError {
188    kind: GroupConsumerNextEventErrorKind,
189}
190
191impl GroupConsumerNextEventError {
192    pub(in crate::consumer) const fn host_unavailable() -> Self {
193        Self {
194            kind: GroupConsumerNextEventErrorKind::HostUnavailable,
195        }
196    }
197
198    pub(in crate::consumer) const fn internal_invariant() -> Self {
199        Self {
200            kind: GroupConsumerNextEventErrorKind::InternalInvariant,
201        }
202    }
203
204    /// Returns the stable event-observation category.
205    pub const fn kind(self) -> GroupConsumerNextEventErrorKind {
206        self.kind
207    }
208}
209
210impl std::fmt::Display for GroupConsumerNextEventError {
211    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
212        write!(
213            formatter,
214            "classic-group event observation failed: {:?}",
215            self.kind
216        )
217    }
218}
219
220impl std::error::Error for GroupConsumerNextEventError {}