Skip to main content

kafka_client_engine/consumer/group_control/
error.rs

1//! Stable control rejection and exhaustive private-port translation.
2
3use kafka_client_core::AssignedConsumerMachineError;
4
5use crate::consumer::{
6    group::{ClassicGroupFetchControlError as Fetch, GroupConsumerControlPortError},
7    group_control::partition::GroupConsumerPartition,
8    group_control::resume_capture::GroupConsumerResumeCaptureError,
9};
10
11/// Stable pre-core batch-control rejection category.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13pub enum GroupConsumerControlErrorKind {
14    /// Engine or group admission has closed.
15    Closed,
16    /// Another owner currently holds the classic-group shard.
17    Contended,
18    /// The synchronized engine host can no longer expose the group owner.
19    HostUnavailable,
20    /// The registered group no longer accepts this operation.
21    GroupUnavailable,
22    /// The group has no active assignment.
23    NoAssignment,
24    /// Earlier group Fetch control remains unsettled.
25    Pending,
26    /// The caller supplied the same topic-partition more than once.
27    DuplicatePartition,
28    /// A topic-partition is absent from the active assignment.
29    UnknownPartition,
30    /// A paused topic-partition has no retained position to resume.
31    PositionNotRetained,
32    /// Bounded event, effect, or allocation capacity is unavailable.
33    ResourceExhausted,
34    /// Internal ownership was inconsistent.
35    InternalInvariant,
36}
37
38/// Rejected control retaining the exact caller-owned target vector.
39#[derive(Debug)]
40#[must_use = "control rejection retains the exact target vector"]
41pub struct GroupConsumerControlError {
42    kind: GroupConsumerControlErrorKind,
43    partitions: Vec<GroupConsumerPartition>,
44}
45
46impl GroupConsumerControlError {
47    pub(super) fn from_resume_capture(
48        _error: GroupConsumerResumeCaptureError,
49        partitions: Vec<GroupConsumerPartition>,
50    ) -> Self {
51        Self {
52            kind: GroupConsumerControlErrorKind::HostUnavailable,
53            partitions,
54        }
55    }
56
57    pub(super) fn from_port(
58        error: GroupConsumerControlPortError,
59        partitions: Vec<GroupConsumerPartition>,
60    ) -> Self {
61        Self {
62            kind: control_error_kind(error),
63            partitions,
64        }
65    }
66
67    /// Returns the stable rejection category.
68    pub const fn kind(&self) -> GroupConsumerControlErrorKind {
69        self.kind
70    }
71
72    /// Borrows the exact rejected caller order.
73    pub fn partitions(&self) -> &[GroupConsumerPartition] {
74        &self.partitions
75    }
76
77    /// Recovers the exact rejected target vector for retry.
78    pub fn into_partitions(self) -> Vec<GroupConsumerPartition> {
79        self.partitions
80    }
81}
82
83impl core::fmt::Display for GroupConsumerControlError {
84    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
85        write!(formatter, "classic-group control rejected: {:?}", self.kind)
86    }
87}
88
89impl std::error::Error for GroupConsumerControlError {}
90
91const fn control_error_kind(error: GroupConsumerControlPortError) -> GroupConsumerControlErrorKind {
92    match error {
93        GroupConsumerControlPortError::Closed
94        | GroupConsumerControlPortError::Fetch(Fetch::Core(
95            AssignedConsumerMachineError::ConsumerClosed,
96        )) => GroupConsumerControlErrorKind::Closed,
97        GroupConsumerControlPortError::Lock(error) if error.is_contended() => {
98            GroupConsumerControlErrorKind::Contended
99        }
100        GroupConsumerControlPortError::Lock(_) => GroupConsumerControlErrorKind::HostUnavailable,
101        GroupConsumerControlPortError::UnknownGroup
102        | GroupConsumerControlPortError::GroupUnavailable
103        | GroupConsumerControlPortError::Fetch(
104            Fetch::Faulted
105            | Fetch::BindingMismatch
106            | Fetch::Core(AssignedConsumerMachineError::StaleAssignment { .. }),
107        ) => GroupConsumerControlErrorKind::GroupUnavailable,
108        GroupConsumerControlPortError::NoAssignment
109        | GroupConsumerControlPortError::Fetch(
110            Fetch::Inactive | Fetch::Core(AssignedConsumerMachineError::NoAssignment),
111        ) => GroupConsumerControlErrorKind::NoAssignment,
112        GroupConsumerControlPortError::DuplicatePartition
113        | GroupConsumerControlPortError::Fetch(Fetch::Core(
114            AssignedConsumerMachineError::DuplicatePartition { .. },
115        )) => GroupConsumerControlErrorKind::DuplicatePartition,
116        GroupConsumerControlPortError::UnknownPartition
117        | GroupConsumerControlPortError::Fetch(Fetch::Core(
118            AssignedConsumerMachineError::UnknownPartition { .. },
119        )) => GroupConsumerControlErrorKind::UnknownPartition,
120        GroupConsumerControlPortError::Fetch(Fetch::Core(
121            AssignedConsumerMachineError::PositionNotRetained { .. },
122        )) => GroupConsumerControlErrorKind::PositionNotRetained,
123        GroupConsumerControlPortError::Allocation
124        | GroupConsumerControlPortError::Fetch(
125            Fetch::EffectCapacity
126            | Fetch::Event(
127                crate::consumer::assigned_event::AssignedConsumerEventStoreError::Capacity,
128            )
129            | Fetch::Core(
130                AssignedConsumerMachineError::ControlAllocationFailed
131                | AssignedConsumerMachineError::AssignmentEpochExhausted
132                | AssignedConsumerMachineError::PositionEpochExhausted { .. }
133                | AssignedConsumerMachineError::FetchRevisionExhausted { .. },
134            ),
135        ) => GroupConsumerControlErrorKind::ResourceExhausted,
136        GroupConsumerControlPortError::Fetch(Fetch::Pending) => {
137            GroupConsumerControlErrorKind::Pending
138        }
139        GroupConsumerControlPortError::Fetch(Fetch::Core(_) | Fetch::Event(_)) => {
140            GroupConsumerControlErrorKind::InternalInvariant
141        }
142    }
143}