Skip to main content

kafka_client_engine/transaction/initialization/
offset_observer.rs

1//! Runtime-neutral observation of one accepted transactional offset transfer.
2
3use std::{
4    fmt,
5    future::Future,
6    pin::Pin,
7    task::{Context, Poll},
8};
9
10use kafka_client_core::TransactionOffsetCommitId;
11
12use crate::{
13    completion::{CompletionObserver, CompletionObserverError},
14    transaction::offset_commit::TransactionOffsetCommitResult,
15};
16
17use super::{
18    TransactionOffsetsOutcome, TransactionToken, offset_outcome::translate_offset_outcome,
19};
20
21/// Sole named observer for one accepted transactional offset transfer.
22#[must_use = "dropping abandons observation without cancelling the accepted transfer"]
23pub struct TransactionOffsetsObserver<'send, 'owner> {
24    inner: CompletionObserver<TransactionOffsetCommitResult>,
25    _transaction: &'send mut TransactionToken<'owner>,
26    operation_id: TransactionOffsetCommitId,
27}
28
29impl<'send, 'owner> TransactionOffsetsObserver<'send, 'owner> {
30    pub(super) const fn new(
31        inner: CompletionObserver<TransactionOffsetCommitResult>,
32        transaction: &'send mut TransactionToken<'owner>,
33        operation_id: TransactionOffsetCommitId,
34    ) -> Self {
35        Self {
36            inner,
37            _transaction: transaction,
38            operation_id,
39        }
40    }
41
42    /// Blocks on the same bounded terminal cell used by [`Future::poll`].
43    pub fn wait(self) -> Result<TransactionOffsetsOutcome, TransactionOffsetsObserverError> {
44        translate(
45            self.inner.wait().map_err(observer_error)?,
46            self.operation_id,
47        )
48    }
49}
50
51impl Future for TransactionOffsetsObserver<'_, '_> {
52    type Output = Result<TransactionOffsetsOutcome, TransactionOffsetsObserverError>;
53
54    fn poll(self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
55        let this = self.get_mut();
56        Pin::new(&mut this.inner)
57            .poll(context)
58            .map(|result| translate(result.map_err(observer_error)?, this.operation_id))
59    }
60}
61
62impl fmt::Debug for TransactionOffsetsObserver<'_, '_> {
63    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
64        formatter
65            .debug_struct("TransactionOffsetsObserver")
66            .finish_non_exhaustive()
67    }
68}
69
70/// Failure to observe or correlate an accepted offset transfer.
71#[derive(Clone, Copy, Debug, Eq, PartialEq)]
72pub enum TransactionOffsetsObserverError {
73    /// This linear observer already consumed its terminal.
74    AlreadyObserved,
75    /// The bounded completion generation is no longer live.
76    Stale,
77    /// The terminal did not match the exact accepted operation.
78    InternalInvariant,
79}
80
81impl fmt::Display for TransactionOffsetsObserverError {
82    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
83        formatter.write_str(match self {
84            Self::AlreadyObserved => "transactional offsets were already observed",
85            Self::Stale => "transactional offset observer is stale",
86            Self::InternalInvariant => "transactional offset terminal violated its correlation",
87        })
88    }
89}
90
91impl std::error::Error for TransactionOffsetsObserverError {}
92
93fn translate(
94    result: TransactionOffsetCommitResult,
95    operation_id: TransactionOffsetCommitId,
96) -> Result<TransactionOffsetsOutcome, TransactionOffsetsObserverError> {
97    if result.operation_id() != operation_id {
98        return Err(TransactionOffsetsObserverError::InternalInvariant);
99    }
100    let outcome = result.outcome();
101    drop(result.into_input());
102    Ok(translate_offset_outcome(outcome))
103}
104
105const fn observer_error(error: CompletionObserverError) -> TransactionOffsetsObserverError {
106    match error {
107        CompletionObserverError::AlreadyObserved => {
108            TransactionOffsetsObserverError::AlreadyObserved
109        }
110        CompletionObserverError::Stale => TransactionOffsetsObserverError::Stale,
111    }
112}