Skip to main content

confluent_kafka/admin/
new_topic.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 new topic to be created via `Admin::create_topics`.
16
17use crate::common::requests::CreateTopicsRequest;
18use std::collections::BTreeMap;
19
20use crate::create_topics_request_data::{CreatableReplicaAssignment, CreatableTopic, CreatableTopicConfig};
21
22/// A new topic to be created via `Admin::create_topics`.
23// `replicas_assignments` and `configs` use `BTreeMap` (rather than `HashMap`)
24// so that conversion to the wire request is deterministically ordered — Java
25// iterates its `Map` in unspecified order, but a stable order simplifies
26// wire-byte comparison and testing.
27#[derive(Clone, Debug, PartialEq, Eq, Hash)]
28#[doc(alias = "org.apache.kafka.clients.admin.NewTopic")]
29pub struct NewTopic {
30    name: String,
31    num_partitions: Option<i32>,
32    replication_factor: Option<i16>,
33    replicas_assignments: Option<BTreeMap<i32, Vec<i32>>>,
34    configs: Option<BTreeMap<String, String>>,
35}
36
37impl NewTopic {
38    /// A new topic that optionally defaults `num_partitions` and `replication_factor` to the
39    /// broker configurations for `num.partitions` and `default.replication.factor` respectively.
40    ///
41    /// # Arguments
42    ///
43    /// - `name` - the topic name.
44    /// - `num_partitions` - the number of partitions, or `None` for the broker default.
45    /// - `replication_factor` - the replication factor, or `None` for the broker default.
46    ///
47    /// # Translation notes
48    ///
49    /// Translates both `NewTopic(String, int, short)` and
50    /// `NewTopic(String, Optional<Integer>, Optional<Short>)`: callers of the former pass `Some`.
51    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#NewTopic")]
52    pub fn with_num_partitions_replication_factor(
53        name: impl Into<String>,
54        num_partitions: Option<i32>,
55        replication_factor: Option<i16>,
56    ) -> Self {
57        Self {
58            name: name.into(),
59            num_partitions,
60            replication_factor,
61            replicas_assignments: None,
62            configs: None,
63        }
64    }
65
66    /// A new topic with the specified replica assignment configuration.
67    ///
68    /// # Arguments
69    ///
70    /// - `name` - the topic name.
71    /// - `replicas_assignments` - a map from partition id to replica ids (i.e. broker ids).
72    ///   Although not enforced, it is generally a good idea for all partitions to have the same
73    ///   number of replicas. The first replica will be treated as the preferred leader.
74    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#NewTopic")]
75    pub fn with_replicas_assignments(name: impl Into<String>, replicas_assignments: BTreeMap<i32, Vec<i32>>) -> Self {
76        Self {
77            name: name.into(),
78            num_partitions: None,
79            replication_factor: None,
80            replicas_assignments: Some(replicas_assignments),
81            configs: None,
82        }
83    }
84
85    /// Returns the name of the topic to be created.
86    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#name")]
87    pub fn name(&self) -> &str {
88        &self.name
89    }
90
91    /// Returns the number of partitions for the new topic or -1 if a replica assignment
92    /// has been specified.
93    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#numPartitions")]
94    pub fn num_partitions(&self) -> i32 {
95        self.num_partitions.unwrap_or(CreateTopicsRequest::NO_NUM_PARTITIONS)
96    }
97
98    /// Returns the replication factor for the new topic or -1 if a replica assignment
99    /// has been specified.
100    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#replicationFactor")]
101    pub fn replication_factor(&self) -> i16 {
102        self.replication_factor.unwrap_or(CreateTopicsRequest::NO_REPLICATION_FACTOR)
103    }
104
105    /// Returns a map from partition id to replica ids (i.e. broker ids) or `None` if the
106    /// number of partitions and replication factor have been specified instead.
107    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#replicasAssignments")]
108    pub fn replicas_assignments(&self) -> Option<&BTreeMap<i32, Vec<i32>>> {
109        self.replicas_assignments.as_ref()
110    }
111
112    /// Set the configuration to use on the new topic.
113    ///
114    /// # Arguments
115    ///
116    /// - `configs` - The configuration map, or `None` for none.
117    ///
118    /// # Returns
119    ///
120    /// This NewTopic object.
121    #[must_use]
122    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#configs")]
123    pub fn set_configs(mut self, configs: Option<BTreeMap<String, String>>) -> Self {
124        self.configs = configs;
125        self
126    }
127
128    /// Returns the configuration for the new topic or `None` if no configs were ever
129    /// specified.
130    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#configs")]
131    pub fn configs(&self) -> Option<&BTreeMap<String, String>> {
132        self.configs.as_ref()
133    }
134
135    /// Converts this new topic to a wire `CreatableTopic`.
136    ///
137    /// Used by
138    /// `KafkaAdminClient::create_topics`.
139    #[doc(alias = "org.apache.kafka.clients.admin.NewTopic#convertToCreatableTopic")]
140    pub(crate) fn convert_to_creatable_topic(&self) -> CreatableTopic {
141        let mut creatable = CreatableTopic::new();
142        creatable.set_name(self.name.clone());
143        creatable.set_num_partitions(self.num_partitions.unwrap_or(CreateTopicsRequest::NO_NUM_PARTITIONS));
144        creatable.set_replication_factor(self.replication_factor.unwrap_or(CreateTopicsRequest::NO_REPLICATION_FACTOR));
145        if let Some(assignments) = &self.replicas_assignments {
146            for (partition_index, broker_ids) in assignments {
147                let mut assignment = CreatableReplicaAssignment::new();
148                assignment.set_partition_index(*partition_index);
149                assignment.set_broker_ids(broker_ids.clone());
150                creatable.assignments.push(assignment);
151            }
152        }
153        if let Some(configs) = &self.configs {
154            for (name, value) in configs {
155                let mut config = CreatableTopicConfig::new();
156                config.set_name(name.clone());
157                config.set_value(Some(value.clone()));
158                creatable.configs.push(config);
159            }
160        }
161        creatable
162    }
163}
164
165/// Java's `toString()`: an unset partition
166/// count or replication factor renders as `default`, and the two maps as Java's
167/// `AbstractMap.toString()` renders them (`{0=[1, 2]}`, `{k=v}`), with `null`
168/// for a missing map.
169impl std::fmt::Display for NewTopic {
170    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
171        write!(f, "(name={}, numPartitions=", self.name)?;
172        match self.num_partitions {
173            Some(num_partitions) => write!(f, "{num_partitions}")?,
174            None => f.write_str("default")?,
175        }
176        f.write_str(", replicationFactor=")?;
177        match self.replication_factor {
178            Some(replication_factor) => write!(f, "{replication_factor}")?,
179            None => f.write_str("default")?,
180        }
181        f.write_str(", replicasAssignments=")?;
182        match &self.replicas_assignments {
183            Some(assignments) => {
184                f.write_str("{")?;
185                for (i, (partition, broker_ids)) in assignments.iter().enumerate() {
186                    if i > 0 {
187                        f.write_str(", ")?;
188                    }
189                    write!(f, "{partition}=[")?;
190                    for (j, broker_id) in broker_ids.iter().enumerate() {
191                        if j > 0 {
192                            f.write_str(", ")?;
193                        }
194                        write!(f, "{broker_id}")?;
195                    }
196                    f.write_str("]")?;
197                }
198                f.write_str("}")?;
199            },
200            None => f.write_str("null")?,
201        }
202        f.write_str(", configs=")?;
203        match &self.configs {
204            Some(configs) => {
205                f.write_str("{")?;
206                for (i, (name, value)) in configs.iter().enumerate() {
207                    if i > 0 {
208                        f.write_str(", ")?;
209                    }
210                    write!(f, "{name}={value}")?;
211                }
212                f.write_str("}")?;
213            },
214            None => f.write_str("null")?,
215        }
216        f.write_str(")")
217    }
218}
219
220#[cfg(test)]
221mod tests {
222    use super::*;
223
224    #[test]
225    fn counts_constructor() {
226        let topic = NewTopic::with_num_partitions_replication_factor("t", Some(3), Some(2));
227        assert_eq!(topic.name(), "t");
228        assert_eq!(topic.num_partitions(), 3);
229        assert_eq!(topic.replication_factor(), 2);
230        assert_eq!(topic.replicas_assignments(), None);
231    }
232
233    #[test]
234    fn optional_defaults_report_minus_one() {
235        let topic = NewTopic::with_num_partitions_replication_factor("t", None, None);
236        assert_eq!(topic.num_partitions(), CreateTopicsRequest::NO_NUM_PARTITIONS);
237        assert_eq!(topic.replication_factor(), CreateTopicsRequest::NO_REPLICATION_FACTOR);
238    }
239
240    #[test]
241    fn replica_assignments_constructor() {
242        let mut assignments = BTreeMap::new();
243        assignments.insert(0, vec![1, 2]);
244        assignments.insert(1, vec![2, 3]);
245        let topic = NewTopic::with_replicas_assignments("t", assignments.clone());
246        assert_eq!(topic.num_partitions(), CreateTopicsRequest::NO_NUM_PARTITIONS);
247        assert_eq!(topic.replication_factor(), CreateTopicsRequest::NO_REPLICATION_FACTOR);
248        assert_eq!(topic.replicas_assignments(), Some(&assignments));
249    }
250
251    #[test]
252    fn configs_builder_is_fluent() {
253        let mut configs = BTreeMap::new();
254        configs.insert("retention.ms".to_string(), "1000".to_string());
255        let topic =
256            NewTopic::with_num_partitions_replication_factor("t", Some(1), Some(1)).set_configs(Some(configs.clone()));
257        assert_eq!(topic.configs(), Some(&configs));
258    }
259
260    #[test]
261    fn convert_to_creatable_topic_with_counts() {
262        let creatable =
263            NewTopic::with_num_partitions_replication_factor("t", Some(3), Some(2)).convert_to_creatable_topic();
264        assert_eq!(creatable.name, "t");
265        assert_eq!(creatable.num_partitions, 3);
266        assert_eq!(creatable.replication_factor, 2);
267        assert!(creatable.assignments.is_empty());
268        assert!(creatable.configs.is_empty());
269    }
270
271    #[test]
272    fn convert_to_creatable_topic_with_assignments_and_configs() {
273        let mut assignments = BTreeMap::new();
274        assignments.insert(0, vec![1, 2]);
275        let mut configs = BTreeMap::new();
276        configs.insert("cleanup.policy".to_string(), "compact".to_string());
277        let creatable = NewTopic::with_replicas_assignments("t", assignments)
278            .set_configs(Some(configs))
279            .convert_to_creatable_topic();
280        assert_eq!(creatable.num_partitions, CreateTopicsRequest::NO_NUM_PARTITIONS);
281        assert_eq!(creatable.assignments.len(), 1);
282        assert_eq!(creatable.assignments[0].partition_index, 0);
283        assert_eq!(creatable.assignments[0].broker_ids, vec![1, 2]);
284        assert_eq!(creatable.configs.len(), 1);
285        assert_eq!(creatable.configs[0].name, "cleanup.policy");
286        assert_eq!(creatable.configs[0].value.as_deref(), Some("compact"));
287    }
288
289    // Translations of Java's `NewTopicTest`. `testConstructorWithPartitionsAndReplicationFactor`,
290    // `testConstructorWithOptionalValues`, `testConstructorWithReplicasAssignments`,
291    // `testConfigsNotNull` and the two `testConvertToCreatableTopic*` tests are
292    // `counts_constructor`, `optional_defaults_report_minus_one`,
293    // `replica_assignments_constructor`, `configs_builder_is_fluent` and the two
294    // `convert_to_creatable_topic_*` tests above. `testUnmodifiableReplicasAssignments`
295    // has no Rust counterpart: Java checks that the returned map rejects `put`,
296    // while `replicas_assignments()` returns a shared borrow, which cannot be
297    // mutated at all.
298
299    const TEST_TOPIC: &str = "testtopic";
300    const NUM_PARTITIONS: i32 = 3;
301    const REPLICATION_FACTOR: i16 = 1;
302    const CLEANUP_POLICY_CONFIG_KEY: &str = "cleanup.policy";
303    const CLEANUP_POLICY_CONFIG_VALUE: &str = "compact";
304
305    /// Translated from `NewTopicTest.testConfigsNull`.
306    #[test]
307    #[doc(alias = "org.apache.kafka.clients.admin.NewTopicTest#testConfigsNull")]
308    fn test_configs_null() {
309        let new_topic = NewTopic::with_num_partitions_replication_factor(
310            TEST_TOPIC,
311            Some(NUM_PARTITIONS),
312            Some(REPLICATION_FACTOR),
313        );
314        assert_eq!(new_topic.configs(), None);
315    }
316
317    /// Translated from `NewTopicTest.testToString`.
318    #[test]
319    #[doc(alias = "org.apache.kafka.clients.admin.NewTopicTest#testToString")]
320    fn test_to_string() {
321        let topic1 = NewTopic::with_num_partitions_replication_factor(
322            TEST_TOPIC,
323            Some(NUM_PARTITIONS),
324            Some(REPLICATION_FACTOR),
325        );
326        let expected1 = format!(
327            "(name={TEST_TOPIC}, numPartitions={NUM_PARTITIONS}, replicationFactor={REPLICATION_FACTOR}, \
328             replicasAssignments=null, configs=null)"
329        );
330        assert_eq!(expected1, topic1.to_string());
331
332        let topic1 = topic1.set_configs(Some(BTreeMap::from([(
333            CLEANUP_POLICY_CONFIG_KEY.to_string(),
334            CLEANUP_POLICY_CONFIG_VALUE.to_string(),
335        )])));
336        let expected2 = format!(
337            "(name={TEST_TOPIC}, numPartitions={NUM_PARTITIONS}, replicationFactor={REPLICATION_FACTOR}, \
338             replicasAssignments=null, configs={{{CLEANUP_POLICY_CONFIG_KEY}={CLEANUP_POLICY_CONFIG_VALUE}}})"
339        );
340        assert_eq!(expected2, topic1.to_string());
341
342        let partition_index = 0;
343        let topic2 = NewTopic::with_replicas_assignments(TEST_TOPIC, BTreeMap::from([(partition_index, vec![1, 2])]));
344        let expected3 = format!(
345            "(name={TEST_TOPIC}, numPartitions=default, replicationFactor=default, \
346             replicasAssignments={{{partition_index}=[1, 2]}}, configs=null)"
347        );
348        assert_eq!(expected3, topic2.to_string());
349    }
350
351    /// Translated from `NewTopicTest.testEqualsAndHashCode`.
352    #[test]
353    #[doc(alias = "org.apache.kafka.clients.admin.NewTopicTest#testEqualsAndHashCode")]
354    fn test_equals_and_hash_code() {
355        use std::hash::BuildHasher;
356        // One hasher for every value, as Java's `hashCode` is one function.
357        let hasher = std::collections::hash_map::RandomState::new();
358        let hash_code = |topic: &NewTopic| hasher.hash_one(topic);
359        let topic1 = NewTopic::with_num_partitions_replication_factor(
360            TEST_TOPIC,
361            Some(NUM_PARTITIONS),
362            Some(REPLICATION_FACTOR),
363        );
364        let topic2 = NewTopic::with_num_partitions_replication_factor(
365            TEST_TOPIC,
366            Some(NUM_PARTITIONS),
367            Some(REPLICATION_FACTOR),
368        );
369        let topic3 = NewTopic::with_num_partitions_replication_factor(
370            "another-topic",
371            Some(NUM_PARTITIONS),
372            Some(REPLICATION_FACTOR),
373        );
374
375        assert_eq!(topic1, topic2);
376        assert_ne!(topic1, topic3);
377        assert_eq!(hash_code(&topic1), hash_code(&topic2));
378        assert_ne!(hash_code(&topic1), hash_code(&topic3));
379    }
380
381    /// New test, no Java original: Java's `configs(null)` clears configs set
382    /// earlier (`NewTopic#configs(Map)`), so none are sent.
383    #[test]
384    fn set_configs_none_clears_the_configs() {
385        let topic = NewTopic::with_num_partitions_replication_factor(
386            TEST_TOPIC,
387            Some(NUM_PARTITIONS),
388            Some(REPLICATION_FACTOR),
389        )
390        .set_configs(Some(BTreeMap::from([(
391            CLEANUP_POLICY_CONFIG_KEY.to_string(),
392            CLEANUP_POLICY_CONFIG_VALUE.to_string(),
393        )])))
394        .set_configs(None);
395        assert_eq!(topic.configs(), None);
396        assert!(topic.convert_to_creatable_topic().configs.is_empty());
397    }
398}