Skip to main content

kafka_client_engine/transaction/initialization/
owner_offsets.rs

1//! Linear public transactional offset-transfer admission.
2
3use std::{fmt, time::Duration};
4
5use crate::{
6    clock::OperationDeadline,
7    consumer::{GroupConsumerCheckpoint, GroupConsumerMetadata},
8    transaction::offset_commit::{
9        TransactionOffsetCommitGroup, TransactionOffsetCommitOffset, TransactionOffsetCommitRequest,
10    },
11};
12
13use super::{
14    TransactionLifecycleControlAccepted, TransactionOffsetsAdmissionError,
15    TransactionOffsetsAdmissionErrorKind, TransactionOffsetsObserver, TransactionToken,
16    offset_admission::control_error_kind,
17};
18
19impl<'owner> TransactionToken<'owner> {
20    /// Captures one transactional offset-transfer boundary before input translation.
21    pub fn capture_offsets(&self, timeout: Duration) -> Option<TransactionOffsetsCapture> {
22        self.owner
23            .capture_offset_commit(timeout)
24            .map(TransactionOffsetsCapture::new)
25    }
26
27    /// Admits one exact assignment-fenced checkpoint into this transaction.
28    #[expect(
29        clippy::result_large_err,
30        reason = "rejection returns the exact linear metadata and checkpoint inputs"
31    )]
32    pub fn send_offsets<'send>(
33        &'send mut self,
34        metadata: GroupConsumerMetadata,
35        checkpoint: GroupConsumerCheckpoint,
36        timeout: Duration,
37    ) -> Result<TransactionOffsetsAccepted<'send, 'owner>, TransactionOffsetsAdmissionError> {
38        let Some(capture) = self.capture_offsets(timeout) else {
39            return Err(TransactionOffsetsAdmissionError::new(
40                TransactionOffsetsAdmissionErrorKind::InvalidDeadline,
41                metadata,
42                checkpoint,
43            ));
44        };
45        self.send_offsets_captured(metadata, checkpoint, capture)
46    }
47
48    /// Admits exact offset inputs under an already captured public boundary.
49    #[expect(
50        clippy::result_large_err,
51        reason = "rejection returns the exact linear metadata and checkpoint inputs"
52    )]
53    pub fn send_offsets_captured<'send>(
54        &'send mut self,
55        metadata: GroupConsumerMetadata,
56        checkpoint: GroupConsumerCheckpoint,
57        capture: TransactionOffsetsCapture,
58    ) -> Result<TransactionOffsetsAccepted<'send, 'owner>, TransactionOffsetsAdmissionError> {
59        let deadline = capture.into_deadline();
60        if metadata.position_fence() != checkpoint.position_fence() {
61            return Err(TransactionOffsetsAdmissionError::new(
62                TransactionOffsetsAdmissionErrorKind::StaleCheckpoint,
63                metadata,
64                checkpoint,
65            ));
66        }
67        let mut offsets = Vec::new();
68        if offsets.try_reserve_exact(1).is_err() {
69            return Err(TransactionOffsetsAdmissionError::new(
70                TransactionOffsetsAdmissionErrorKind::Backpressure,
71                metadata,
72                checkpoint,
73            ));
74        }
75        let (topic, partition, next_offset, leader_epoch) = checkpoint.transaction_offset();
76        offsets.push(TransactionOffsetCommitOffset::new(
77            Arc::clone(topic),
78            partition,
79            next_offset,
80            leader_epoch,
81            None,
82        ));
83        let request = TransactionOffsetCommitRequest::new(
84            self.owner.owner_id(),
85            self.epoch,
86            TransactionOffsetCommitGroup::new(
87                metadata.group_arc(),
88                metadata.generation_id_or_member_epoch(),
89                metadata.member_arc(),
90                metadata.group_instance_id_arc(),
91                metadata.position_fence(),
92            ),
93            offsets,
94            deadline,
95        );
96        let TransactionLifecycleControlAccepted { value, wake_failed } =
97            match self.owner.send_offsets(request) {
98                Ok(accepted) => accepted,
99                Err(error) => {
100                    let kind = control_error_kind(&error);
101                    drop(error.into_input());
102                    return Err(TransactionOffsetsAdmissionError::new(
103                        kind, metadata, checkpoint,
104                    ));
105                }
106            };
107        let operation_id = value.operation_id();
108        Ok(TransactionOffsetsAccepted {
109            observer: TransactionOffsetsObserver::new(value.into_observer(), self, operation_id),
110            wake_failed,
111        })
112    }
113}
114
115use std::sync::Arc;
116
117/// One non-cloneable transactional offset-transfer call boundary.
118#[must_use = "consume the captured boundary with one transactional offset transfer"]
119#[derive(Debug)]
120pub struct TransactionOffsetsCapture {
121    deadline: OperationDeadline,
122}
123
124impl TransactionOffsetsCapture {
125    const fn new(deadline: OperationDeadline) -> Self {
126        Self { deadline }
127    }
128
129    const fn into_deadline(self) -> OperationDeadline {
130        self.deadline
131    }
132}
133
134/// Accepted transfer ownership plus advisory post-admission wake status.
135#[must_use = "accepted transactional offsets retain their sole terminal observer"]
136pub struct TransactionOffsetsAccepted<'send, 'owner> {
137    observer: TransactionOffsetsObserver<'send, 'owner>,
138    wake_failed: bool,
139}
140
141impl<'send, 'owner> TransactionOffsetsAccepted<'send, 'owner> {
142    /// Reports that the advisory reactor wake failed after acceptance.
143    pub const fn wake_failed(&self) -> bool {
144        self.wake_failed
145    }
146
147    /// Transfers the sole runtime-neutral terminal observer.
148    pub fn into_observer(self) -> TransactionOffsetsObserver<'send, 'owner> {
149        self.observer
150    }
151}
152
153impl fmt::Debug for TransactionOffsetsAccepted<'_, '_> {
154    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
155        formatter
156            .debug_struct("TransactionOffsetsAccepted")
157            .field("observer", &self.observer)
158            .field("wake_failed", &self.wake_failed)
159            .finish()
160    }
161}