kafka_client_engine/transaction/initialization/
owner_offsets.rs1use 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 pub fn capture_offsets(&self, timeout: Duration) -> Option<TransactionOffsetsCapture> {
22 self.owner
23 .capture_offset_commit(timeout)
24 .map(TransactionOffsetsCapture::new)
25 }
26
27 #[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 #[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#[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#[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 pub const fn wake_failed(&self) -> bool {
144 self.wake_failed
145 }
146
147 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}