Skip to main content

kafka_client_engine/transaction/initialization/
owner_send.rs

1//! Linear public transactional-record send admission.
2
3use std::{fmt, sync::Arc, time::Duration};
4
5use crate::{
6    producer::{ProducerSendCapture, ProducerSendCaptureError, PublicProducerRecord},
7    transaction::send::TransactionSendInput,
8};
9
10use super::{
11    TransactionLifecycleControlAccepted, TransactionSendAdmissionError, TransactionSendObserver,
12    TransactionToken,
13    send_admission::{capture_error_kind, control_send_error_kind, record_error_kind},
14};
15
16impl<'owner> TransactionToken<'owner> {
17    /// Captures one transactional send boundary before record conversion.
18    pub fn capture_send(
19        &self,
20        timeout: Duration,
21    ) -> Result<ProducerSendCapture, ProducerSendCaptureError> {
22        self.owner.capture_send(timeout)
23    }
24
25    /// Admits one record into this exact transaction.
26    #[expect(
27        clippy::result_large_err,
28        reason = "rejection returns the exact caller-owned transactional record"
29    )]
30    pub fn send<'send>(
31        &'send mut self,
32        record: PublicProducerRecord,
33        timeout: Duration,
34    ) -> Result<TransactionSendAccepted<'send, 'owner>, TransactionSendAdmissionError> {
35        let capture = match self.capture_send(timeout) {
36            Ok(capture) => capture,
37            Err(error) => {
38                return Err(TransactionSendAdmissionError::new(
39                    capture_error_kind(error),
40                    record,
41                ));
42            }
43        };
44        self.send_captured(record, capture)
45    }
46
47    /// Admits one record under an already captured public send boundary.
48    #[expect(
49        clippy::result_large_err,
50        reason = "rejection returns the exact caller-owned transactional record"
51    )]
52    pub fn send_captured<'send>(
53        &'send mut self,
54        record: PublicProducerRecord,
55        capture: ProducerSendCapture,
56    ) -> Result<TransactionSendAccepted<'send, 'owner>, TransactionSendAdmissionError> {
57        let (deadline, default_timestamp_ms) = capture.into_parts();
58        let view = match record.transaction_view(default_timestamp_ms) {
59            Ok(view) => view,
60            Err(error) => {
61                return Err(TransactionSendAdmissionError::new(
62                    record_error_kind(error),
63                    record,
64                ));
65            }
66        };
67        let (topic, partition, materialization, retained_source_bytes) = view.into_parts();
68        let public_partition = match partition
69            .map(|partition| i32::try_from(partition.get()))
70            .transpose()
71        {
72            Ok(partition) => partition,
73            Err(_error) => {
74                return Err(TransactionSendAdmissionError::new(
75                    super::TransactionSendAdmissionErrorKind::InvalidPartition,
76                    record,
77                ));
78            }
79        };
80        let observer_topic = Arc::clone(&topic);
81        let input = TransactionSendInput::new(
82            self.epoch,
83            record,
84            topic,
85            partition,
86            materialization,
87            retained_source_bytes,
88            deadline.operation_deadline(),
89        );
90        let TransactionLifecycleControlAccepted { value, wake_failed } =
91            self.owner.send(input).map_err(|error| {
92                let kind = control_send_error_kind(&error);
93                TransactionSendAdmissionError::new(kind, error.into_input().into_original_record())
94            })?;
95        let epoch = self.epoch;
96        let send_id = value.send_id();
97        Ok(TransactionSendAccepted {
98            observer: TransactionSendObserver::new(
99                value.into_observer(),
100                self,
101                epoch,
102                send_id,
103                observer_topic,
104                public_partition,
105            ),
106            wake_failed,
107        })
108    }
109}
110
111/// Accepted send ownership plus advisory post-admission wake status.
112#[must_use = "accepted transactional send retains its sole terminal observer"]
113pub struct TransactionSendAccepted<'send, 'owner> {
114    observer: TransactionSendObserver<'send, 'owner>,
115    wake_failed: bool,
116}
117
118impl<'send, 'owner> TransactionSendAccepted<'send, 'owner> {
119    /// Reports that the advisory reactor wake failed after send acceptance.
120    pub const fn wake_failed(&self) -> bool {
121        self.wake_failed
122    }
123
124    /// Transfers the sole runtime-neutral send observer.
125    pub fn into_observer(self) -> TransactionSendObserver<'send, 'owner> {
126        self.observer
127    }
128}
129
130impl fmt::Debug for TransactionSendAccepted<'_, '_> {
131    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
132        formatter
133            .debug_struct("TransactionSendAccepted")
134            .field("observer", &self.observer)
135            .field("wake_failed", &self.wake_failed)
136            .finish()
137    }
138}