Skip to main content

kafka_client_engine/consumer/group_event/
immediate.rs

1//! Immediate observation through the unique classic-group capability.
2
3use std::sync::Arc;
4
5use kafka_client_core::GroupId;
6
7use super::{
8    GroupConsumerEvent, GroupConsumerRevocationAcknowledgeError, GroupConsumerState,
9    GroupConsumerStateError, GroupConsumerStateErrorKind, GroupConsumerTryTakeEventError,
10};
11use crate::consumer::{
12    GroupConsumerEventPortError, GroupConsumerHandle, GroupConsumerPort,
13    GroupConsumerStatePortError,
14};
15
16/// Linear capability for completing one observed graceful-revocation lease.
17///
18/// Creating this value starts no protocol work and captures no new deadline.
19/// The exact assignment epoch is supplied by the event that owns this
20/// capability.
21pub struct GroupConsumerRevocationControl {
22    group_id: GroupId,
23    port: GroupConsumerPort,
24    _lifetime: Arc<dyn Send + Sync>,
25}
26
27impl GroupConsumerRevocationControl {
28    /// Completes the exact assignment lease named by an observed event.
29    pub fn complete(
30        &mut self,
31        assignment_epoch: u64,
32    ) -> Result<(), GroupConsumerRevocationAcknowledgeError> {
33        self.port
34            .try_acknowledge_revocation(self.group_id, assignment_epoch)
35            .map_err(GroupConsumerRevocationAcknowledgeError::from_port)
36    }
37}
38
39impl core::fmt::Debug for GroupConsumerRevocationControl {
40    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
41        formatter
42            .debug_struct("GroupConsumerRevocationControl")
43            .field("group_id", &self.group_id)
44            .finish_non_exhaustive()
45    }
46}
47
48impl GroupConsumerHandle {
49    /// Transfers one completion capability to the next observed revocation.
50    pub fn revocation_control(&self) -> GroupConsumerRevocationControl {
51        GroupConsumerRevocationControl {
52            group_id: self.group_id,
53            port: self.port.clone(),
54            _lifetime: Arc::clone(&self.lifetime),
55        }
56    }
57
58    /// Immediately copies the current driver-confirmed membership and assignment.
59    ///
60    /// `Ok(None)` means no Sync-confirmed membership is current. This starts no
61    /// group work, requests no reactor turn, and does not consume rebalance events.
62    pub fn state(&self) -> Result<Option<GroupConsumerState>, GroupConsumerStateError> {
63        match self.port.try_group_state(self.group_id) {
64            Ok(state) => Ok(state),
65            Err(error) if error.is_terminal() => Ok(None),
66            Err(error) => Err(GroupConsumerStateError::new(match error {
67                GroupConsumerStatePortError::Lock(error) if error.is_contended() => {
68                    GroupConsumerStateErrorKind::Contended
69                }
70                GroupConsumerStatePortError::Lock(error) if error.is_poisoned() => {
71                    GroupConsumerStateErrorKind::HostUnavailable
72                }
73                GroupConsumerStatePortError::Registry(error) if error.is_allocation() => {
74                    GroupConsumerStateErrorKind::Allocation
75                }
76                GroupConsumerStatePortError::Closed
77                | GroupConsumerStatePortError::Lock(_)
78                | GroupConsumerStatePortError::Registry(_) => {
79                    GroupConsumerStateErrorKind::InternalInvariant
80                }
81            })),
82        }
83    }
84
85    /// Immediately transfers one retained classic-group transition, if ready.
86    ///
87    /// This does not wait, start group work, request a reactor turn, or reopen
88    /// observation after the event stream terminates.
89    pub fn try_take_event(
90        &mut self,
91    ) -> Result<Option<GroupConsumerEvent>, GroupConsumerTryTakeEventError> {
92        translate_immediate_result(self.port.try_take_event(self.group_id))
93    }
94}
95
96pub(super) fn translate_immediate_result(
97    result: Result<Option<GroupConsumerEvent>, GroupConsumerEventPortError>,
98) -> Result<Option<GroupConsumerEvent>, GroupConsumerTryTakeEventError> {
99    match result {
100        Ok(event) => Ok(event),
101        Err(error) if error.is_terminal() => Ok(None),
102        Err(error) => Err(GroupConsumerTryTakeEventError::from_port(error)),
103    }
104}