Skip to main content

confluent_kafka/admin/
describe_transactions_result.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 result of `Admin::describe_transactions`.
16
17use std::collections::HashMap;
18
19use crate::admin::TransactionDescription;
20use crate::common::{Error, KafkaFuture};
21
22/// The result of `Admin::describe_transactions`.
23// Java keys the per-transaction futures by `CoordinatorKey`; since
24// `CoordinatorKey` is an internal (`pub(crate)`) type, the Rust result keys
25// them by the transactional id string (the `idValue`), following the
26// `DescribeConsumerGroupsResult` precedent.
27#[derive(Clone, Debug)]
28#[doc(alias = "org.apache.kafka.clients.admin.DescribeTransactionsResult")]
29pub struct DescribeTransactionsResult {
30    futures: HashMap<String, KafkaFuture<TransactionDescription>>,
31}
32
33impl DescribeTransactionsResult {
34    /// Creates a result from the per-transactional-id futures.
35    #[doc(alias = "org.apache.kafka.clients.admin.DescribeTransactionsResult#DescribeTransactionsResult")]
36    pub(crate) fn new(futures: HashMap<String, KafkaFuture<TransactionDescription>>) -> Self {
37        Self { futures }
38    }
39
40    /// Get the description of a specific transactional id.
41    ///
42    /// # Arguments
43    ///
44    /// - `transactional_id` - the transactional ID to describe
45    ///
46    /// # Returns
47    ///
48    /// a future which completes when the transaction description of a particular transactional ID
49    /// is available.
50    ///
51    /// # Errors
52    ///
53    /// - `Error::is_local_illegal_argument_error` if `transactional_id` was not included in the
54    ///   respective call to `Admin::describe_transactions`.
55    #[doc(alias = "org.apache.kafka.clients.admin.DescribeTransactionsResult#description")]
56    pub fn description(&self, transactional_id: &str) -> Result<KafkaFuture<TransactionDescription>, Error> {
57        self.futures.get(transactional_id).cloned().ok_or_else(|| {
58            Error::local_illegal_argument(format!(
59                "TransactionalId `{transactional_id}` was not included in the request"
60            ))
61        })
62    }
63
64    /// Get a future yielding a map of every requested transactional id's
65    /// description. Fails if any transactional id's request fails.
66    ///
67    /// # Returns
68    ///
69    /// a future which either completes when all transaction descriptions complete or fails if any
70    /// of the descriptions cannot be obtained
71    #[doc(alias = "org.apache.kafka.clients.admin.DescribeTransactionsResult#all")]
72    pub fn all(&self) -> KafkaFuture<HashMap<String, TransactionDescription>> {
73        KafkaFuture::join_map(self.futures.iter().map(|(id, f)| (id.clone(), f.clone())).collect())
74    }
75}
76
77#[cfg(test)]
78mod tests {
79    use super::*;
80    use crate::admin::TransactionState;
81    use crate::common::internals::KafkaFutureImpl;
82    use std::collections::HashSet;
83
84    fn description() -> TransactionDescription {
85        TransactionDescription::new(1, TransactionState::Ongoing, 1, 2, 3, None, HashSet::new())
86    }
87
88    #[tokio::test]
89    async fn description_returns_future_for_known_id() {
90        let h: KafkaFutureImpl<TransactionDescription> = KafkaFutureImpl::new();
91        let result = DescribeTransactionsResult::new(HashMap::from([("t".to_string(), h.future())]));
92        h.complete(description());
93        assert_eq!(result.description("t").unwrap().get().await.unwrap(), description());
94    }
95
96    #[test]
97    fn description_errors_for_unknown_id() {
98        let result = DescribeTransactionsResult::new(HashMap::new());
99        let err = result.description("t").unwrap_err();
100        assert!(err.message().contains("was not included in the request"));
101    }
102
103    #[tokio::test]
104    async fn all_collects_every_id() {
105        let h: KafkaFutureImpl<TransactionDescription> = KafkaFutureImpl::new();
106        let result = DescribeTransactionsResult::new(HashMap::from([("t".to_string(), h.future())]));
107        h.complete(description());
108        let all = result.all().get().await.unwrap();
109        assert_eq!(all["t"], description());
110    }
111}