Skip to main content

confluent_kafka/common/
topic_id_partition.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//! A topic-partition pair carrying the topic's universally unique identifier.
16//!
17//! Translated from `org.apache.kafka.common.TopicIdPartition`. Distinguishes
18//! topics recreated under the same name — two topics with the same name and
19//! partition layout have different [`TopicIdPartition`]s if their [`Uuid`]s
20//! differ.
21
22use std::fmt;
23
24use crate::common::TopicPartition;
25use crate::common::Uuid;
26
27/// This represents universally unique identifier with topic id for a topic
28/// partition. This makes sure that topics recreated with the same name will
29/// always have unique topic identifiers.
30#[derive(Clone, Debug)]
31#[doc(alias = "org.apache.kafka.common.TopicIdPartition")]
32pub struct TopicIdPartition {
33    topic_id: Uuid,
34    topic_partition: TopicPartition,
35}
36
37impl TopicIdPartition {
38    /// Creates an instance with the provided topic ID and topic partition.
39    ///
40    /// # Arguments
41    ///
42    /// - `topic_id` - the topic id
43    /// - `topic_partition` - the topic partition
44    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#TopicIdPartition")]
45    pub fn new(topic_id: Uuid, topic_partition: TopicPartition) -> Self {
46        Self { topic_id, topic_partition }
47    }
48
49    /// Creates an instance from a topic ID, partition number, and topic name.
50    ///
51    /// # Arguments
52    ///
53    /// - `topic_id` - the topic id
54    /// - `partition` - the partition id
55    /// - `topic` - the topic name, empty if unknown
56    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#TopicIdPartition")]
57    pub fn with_partition_topic(topic_id: Uuid, partition: i32, topic: impl Into<String>) -> Self {
58        Self { topic_id, topic_partition: TopicPartition::new(topic.into(), partition) }
59    }
60
61    /// Returns the universally unique id representing this topic partition.
62    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#topicId")]
63    pub fn topic_id(&self) -> Uuid {
64        self.topic_id
65    }
66
67    /// Returns the topic name (may be empty if unknown).
68    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#topic")]
69    pub fn topic(&self) -> &str {
70        self.topic_partition.topic()
71    }
72
73    /// Returns the partition number.
74    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#partition")]
75    pub fn partition(&self) -> i32 {
76        self.topic_partition.partition()
77    }
78
79    /// Returns the underlying topic partition.
80    #[doc(alias = "org.apache.kafka.common.TopicIdPartition#topicPartition")]
81    pub fn topic_partition(&self) -> &TopicPartition {
82        &self.topic_partition
83    }
84}
85
86impl PartialEq for TopicIdPartition {
87    fn eq(&self, other: &Self) -> bool {
88        self.topic_id == other.topic_id && self.topic_partition == other.topic_partition
89    }
90}
91
92impl Eq for TopicIdPartition {}
93
94impl std::hash::Hash for TopicIdPartition {
95    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
96        self.topic_id.hash(state);
97        self.topic_partition.hash(state);
98    }
99}
100
101impl fmt::Display for TopicIdPartition {
102    /// Matches Java's `toString()`: `<topicId>:<topic>-<partition>`.
103    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
104        write!(
105            f,
106            "{}:{}-{}",
107            self.topic_id,
108            self.topic_partition.topic(),
109            self.topic_partition.partition()
110        )
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117
118    #[test]
119    fn test_construction_via_parts() {
120        let id = Uuid::new(1, 2);
121        let tip = TopicIdPartition::with_partition_topic(id, 7, "mytopic");
122        assert_eq!(id, tip.topic_id());
123        assert_eq!("mytopic", tip.topic());
124        assert_eq!(7, tip.partition());
125    }
126
127    #[test]
128    fn test_construction_via_topic_partition() {
129        let id = Uuid::new(1, 2);
130        let tp = TopicPartition::new("mytopic".to_string(), 3);
131        let tip = TopicIdPartition::new(id, tp.clone());
132        assert_eq!(&tp, tip.topic_partition());
133    }
134
135    #[test]
136    fn test_equality() {
137        let id_a = Uuid::new(1, 2);
138        let id_b = Uuid::new(3, 4);
139        let tp_0 = TopicPartition::new("t".to_string(), 0);
140        let tp_1 = TopicPartition::new("t".to_string(), 1);
141
142        let tip_a0 = TopicIdPartition::new(id_a, tp_0.clone());
143        let tip_a0_again = TopicIdPartition::new(id_a, tp_0.clone());
144        let tip_a1 = TopicIdPartition::new(id_a, tp_1);
145        let tip_b0 = TopicIdPartition::new(id_b, tp_0);
146
147        assert_eq!(tip_a0, tip_a0_again);
148        assert_ne!(tip_a0, tip_a1);
149        assert_ne!(tip_a0, tip_b0);
150    }
151
152    #[test]
153    fn test_hash_consistency() {
154        use std::collections::HashSet;
155        let id = Uuid::new(1, 2);
156        let mut set = HashSet::new();
157        set.insert(TopicIdPartition::with_partition_topic(id, 0, "t"));
158        set.insert(TopicIdPartition::with_partition_topic(id, 0, "t"));
159        assert_eq!(set.len(), 1);
160        set.insert(TopicIdPartition::with_partition_topic(id, 1, "t"));
161        assert_eq!(set.len(), 2);
162    }
163
164    #[test]
165    fn test_display() {
166        let id = Uuid::new(0x1111_2222_3333_4444, 0x5555_6666_7777_8888);
167        let tip = TopicIdPartition::with_partition_topic(id, 5, "mytopic");
168        // Display delegates to Uuid::Display + ":<topic>-<partition>".
169        let s = format!("{tip}");
170        assert!(s.ends_with(":mytopic-5"), "got {s}");
171        assert!(s.starts_with(&id.to_string()), "got {s}");
172    }
173}