Skip to main content

confluent_kafka/admin/
transaction_description.rs

1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! The description of a transaction, as reported by `DescribeTransactions`.
16
17use std::collections::HashSet;
18
19use crate::admin::TransactionState;
20use crate::common::TopicPartition;
21
22/// The description of a transaction.
23#[derive(Clone, Debug, PartialEq, Eq)]
24#[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription")]
25pub struct TransactionDescription {
26    coordinator_id: i32,
27    state: TransactionState,
28    producer_id: i64,
29    producer_epoch: i32,
30    transaction_timeout_ms: i64,
31    transaction_start_time_ms: Option<i64>,
32    topic_partitions: HashSet<TopicPartition>,
33}
34
35impl std::hash::Hash for TransactionDescription {
36    // Java's `TransactionDescription.hashCode()` is `Objects.hash` of every
37    // field; the `topicPartitions` set hashes independently of its order.
38    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
39        self.coordinator_id.hash(state);
40        self.state.hash(state);
41        self.producer_id.hash(state);
42        self.producer_epoch.hash(state);
43        self.transaction_timeout_ms.hash(state);
44        self.transaction_start_time_ms.hash(state);
45        crate::common::utils::Utils::hash_unordered(&self.topic_partitions, state);
46    }
47}
48
49impl TransactionDescription {
50    /// Creates a new `TransactionDescription`.
51    ///
52    /// # Arguments
53    ///
54    /// - `coordinator_id` - the id of the coordinator that owns this transaction.
55    /// - `state` - the current state of the transaction.
56    /// - `producer_id` - the producer id of the transaction.
57    /// - `producer_epoch` - the producer epoch of the transaction.
58    /// - `transaction_timeout_ms` - the transaction timeout in milliseconds.
59    /// - `transaction_start_time_ms` - the start time of the transaction in milliseconds, or
60    ///   `None` if no transaction is in progress.
61    /// - `topic_partitions` - the partitions included in the transaction.
62    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#TransactionDescription")]
63    pub fn new(
64        coordinator_id: i32,
65        state: TransactionState,
66        producer_id: i64,
67        producer_epoch: i32,
68        transaction_timeout_ms: i64,
69        transaction_start_time_ms: Option<i64>,
70        topic_partitions: HashSet<TopicPartition>,
71    ) -> Self {
72        Self {
73            coordinator_id,
74            state,
75            producer_id,
76            producer_epoch,
77            transaction_timeout_ms,
78            transaction_start_time_ms,
79            topic_partitions,
80        }
81    }
82
83    /// Returns the id of the coordinator that owns this transaction.
84    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#coordinatorId")]
85    pub fn coordinator_id(&self) -> i32 {
86        self.coordinator_id
87    }
88
89    /// Returns the current state of the transaction.
90    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#state")]
91    pub fn state(&self) -> TransactionState {
92        self.state
93    }
94
95    /// Returns the producer id of the transaction.
96    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#producerId")]
97    pub fn producer_id(&self) -> i64 {
98        self.producer_id
99    }
100
101    /// Returns the producer epoch of the transaction.
102    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#producerEpoch")]
103    pub fn producer_epoch(&self) -> i32 {
104        self.producer_epoch
105    }
106
107    /// Returns the transaction timeout in milliseconds.
108    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#transactionTimeoutMs")]
109    pub fn transaction_timeout_ms(&self) -> i64 {
110        self.transaction_timeout_ms
111    }
112
113    /// Returns the transaction start time in milliseconds, if a transaction is in
114    /// progress.
115    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#transactionStartTimeMs")]
116    pub fn transaction_start_time_ms(&self) -> Option<i64> {
117        self.transaction_start_time_ms
118    }
119
120    /// Returns the set of topic partitions that have been added to the transaction.
121    #[doc(alias = "org.apache.kafka.clients.admin.TransactionDescription#topicPartitions")]
122    pub fn topic_partitions(&self) -> &HashSet<TopicPartition> {
123        &self.topic_partitions
124    }
125}
126
127impl std::fmt::Display for TransactionDescription {
128    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
129        write!(
130            f,
131            "TransactionDescription(coordinatorId={}, state={}, producerId={}, producerEpoch={}, \
132             transactionTimeoutMs={}, transactionStartTimeMs={:?}, topicPartitions={:?})",
133            self.coordinator_id,
134            self.state,
135            self.producer_id,
136            self.producer_epoch,
137            self.transaction_timeout_ms,
138            self.transaction_start_time_ms,
139            self.topic_partitions,
140        )
141    }
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    #[test]
149    fn accessors_return_constructor_values() {
150        let partitions = HashSet::from([TopicPartition::new("foo", 1)]);
151        let d = TransactionDescription::new(
152            2,
153            TransactionState::Ongoing,
154            12345,
155            15,
156            10000,
157            Some(1_599_151_791),
158            partitions.clone(),
159        );
160        assert_eq!(d.coordinator_id(), 2);
161        assert_eq!(d.state(), TransactionState::Ongoing);
162        assert_eq!(d.producer_id(), 12345);
163        assert_eq!(d.producer_epoch(), 15);
164        assert_eq!(d.transaction_timeout_ms(), 10000);
165        assert_eq!(d.transaction_start_time_ms(), Some(1_599_151_791));
166        assert_eq!(d.topic_partitions(), &partitions);
167    }
168
169    #[test]
170    fn equality_compares_all_fields() {
171        let a = TransactionDescription::new(1, TransactionState::Empty, 1, 2, 3, None, HashSet::new());
172        let b = TransactionDescription::new(1, TransactionState::Empty, 1, 2, 3, None, HashSet::new());
173        assert_eq!(a, b);
174        assert_ne!(
175            a,
176            TransactionDescription::new(1, TransactionState::Ongoing, 1, 2, 3, None, HashSet::new())
177        );
178    }
179}