Skip to main content

kafka_client_engine/consumer/group_commit/
observer.rs

1//! Runtime-neutral observation of one accepted group checkpoint commit.
2
3use std::{
4    fmt,
5    future::Future,
6    pin::Pin,
7    sync::Arc,
8    task::{Context, Poll},
9};
10
11use kafka_client_core::GroupOffsetCommitTerminal;
12
13use super::{GroupConsumerCommitOutcome, outcome::translate_terminal};
14use crate::{
15    completion::{CompletionObserver, CompletionObserverError},
16    consumer::group_batch::GroupConsumerCheckpointObservation,
17};
18
19/// Sole named observer for one accepted classic-group offset commit.
20#[must_use = "dropping abandons observation without cancelling the accepted commit"]
21pub struct GroupConsumerCommitObserver {
22    inner: CompletionObserver<GroupOffsetCommitTerminal>,
23    observation: Option<GroupConsumerCheckpointObservation>,
24    _lifetime: Arc<dyn Send + Sync>,
25}
26
27impl GroupConsumerCommitObserver {
28    pub(in crate::consumer) fn new(
29        inner: CompletionObserver<GroupOffsetCommitTerminal>,
30        observation: GroupConsumerCheckpointObservation,
31        lifetime: Arc<dyn Send + Sync>,
32    ) -> Self {
33        Self {
34            inner,
35            observation: Some(observation),
36            _lifetime: lifetime,
37        }
38    }
39
40    /// Blocks on the same bounded terminal cell used by [`Future::poll`].
41    pub fn wait(mut self) -> Result<GroupConsumerCommitOutcome, GroupConsumerCommitObserverError> {
42        let terminal = self.inner.wait().map_err(observer_error)?;
43        let observation = self
44            .observation
45            .take()
46            .ok_or(GroupConsumerCommitObserverError::AlreadyObserved)?;
47        translate_terminal(terminal, observation)
48    }
49}
50
51impl Future for GroupConsumerCommitObserver {
52    type Output = Result<GroupConsumerCommitOutcome, GroupConsumerCommitObserverError>;
53
54    fn poll(self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
55        let this = self.get_mut();
56        match Pin::new(&mut this.inner).poll(context) {
57            Poll::Ready(Ok(terminal)) => {
58                let Some(observation) = this.observation.take() else {
59                    return Poll::Ready(Err(GroupConsumerCommitObserverError::AlreadyObserved));
60                };
61                Poll::Ready(translate_terminal(terminal, observation))
62            }
63            Poll::Ready(Err(error)) => Poll::Ready(Err(observer_error(error))),
64            Poll::Pending => Poll::Pending,
65        }
66    }
67}
68
69impl fmt::Debug for GroupConsumerCommitObserver {
70    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
71        formatter
72            .debug_struct("GroupConsumerCommitObserver")
73            .finish_non_exhaustive()
74    }
75}
76
77/// Failure to observe or translate one accepted commit terminal.
78#[derive(Clone, Copy, Debug, Eq, PartialEq)]
79pub enum GroupConsumerCommitObserverError {
80    /// This linear observer already consumed its terminal.
81    AlreadyObserved,
82    /// The bounded completion generation is no longer live.
83    Stale,
84    /// A terminal violated the exact admitted checkpoint correlation.
85    InternalInvariant,
86}
87
88impl fmt::Display for GroupConsumerCommitObserverError {
89    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
90        formatter.write_str(match self {
91            Self::AlreadyObserved => "group checkpoint commit was already observed",
92            Self::Stale => "group checkpoint commit observer is stale",
93            Self::InternalInvariant => {
94                "group checkpoint commit terminal violated its admitted correlation"
95            }
96        })
97    }
98}
99
100impl std::error::Error for GroupConsumerCommitObserverError {}
101
102const fn observer_error(error: CompletionObserverError) -> GroupConsumerCommitObserverError {
103    match error {
104        CompletionObserverError::AlreadyObserved => {
105            GroupConsumerCommitObserverError::AlreadyObserved
106        }
107        CompletionObserverError::Stale => GroupConsumerCommitObserverError::Stale,
108    }
109}