Skip to main content

confluent_kafka/admin/
feature_metadata.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//! Details about finalized as well as supported features.
16
17use std::collections::HashMap;
18
19use super::{FinalizedVersionRange, SupportedVersionRange};
20
21/// Encapsulates details about finalized as well as supported features.
22///
23/// This is particularly useful to hold the result returned by the
24/// [`describe_features_with_options`](crate::admin::Admin::describe_features_with_options) API.
25#[derive(Clone, Debug, PartialEq, Eq)]
26#[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata")]
27pub struct FeatureMetadata {
28    finalized_features: HashMap<String, FinalizedVersionRange>,
29    finalized_features_epoch: Option<i64>,
30    supported_features: HashMap<String, SupportedVersionRange>,
31}
32
33impl FeatureMetadata {
34    /// Creates a new `FeatureMetadata`.
35    #[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata#FeatureMetadata")]
36    pub(crate) fn new(
37        finalized_features: HashMap<String, FinalizedVersionRange>,
38        finalized_features_epoch: Option<i64>,
39        supported_features: HashMap<String, SupportedVersionRange>,
40    ) -> Self {
41        Self { finalized_features, finalized_features_epoch, supported_features }
42    }
43
44    /// Returns a map of finalized feature versions. Each entry contains a
45    /// feature name and the range of version levels supported by every broker
46    /// in the cluster.
47    #[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata#finalizedFeatures")]
48    pub fn finalized_features(&self) -> &HashMap<String, FinalizedVersionRange> {
49        &self.finalized_features
50    }
51
52    /// Returns the epoch for the finalized features. If empty, the finalized features
53    /// are absent/unavailable.
54    #[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata#finalizedFeaturesEpoch")]
55    pub fn finalized_features_epoch(&self) -> Option<i64> {
56        self.finalized_features_epoch
57    }
58
59    /// Returns a map of supported feature versions. Each entry contains a
60    /// feature name and the range of versions supported by a particular broker
61    /// in the cluster.
62    #[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata#supportedFeatures")]
63    pub fn supported_features(&self) -> &HashMap<String, SupportedVersionRange> {
64        &self.supported_features
65    }
66}
67
68impl std::hash::Hash for FeatureMetadata {
69    // Java's `FeatureMetadata.hashCode()` is `Objects.hash` of the three
70    // fields; the two maps hash independently of their order.
71    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
72        crate::common::utils::Utils::hash_unordered(&self.finalized_features, state);
73        self.finalized_features_epoch.hash(state);
74        crate::common::utils::Utils::hash_unordered(&self.supported_features, state);
75    }
76}
77
78impl std::fmt::Display for FeatureMetadata {
79    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
80        let epoch = match self.finalized_features_epoch {
81            Some(e) => e.to_string(),
82            None => "<none>".to_string(),
83        };
84        write!(
85            f,
86            "FeatureMetadata{{finalizedFeatures:{}, finalizedFeaturesEpoch:{}, supportedFeatures:{}}}",
87            map_to_string(&self.finalized_features),
88            epoch,
89            map_to_string(&self.supported_features)
90        )
91    }
92}
93
94/// Formats a feature map as `{(name -> range), ...}`, mirroring Java's
95/// `FeatureMetadata.mapToString`.
96#[doc(alias = "org.apache.kafka.clients.admin.FeatureMetadata#mapToString")]
97fn map_to_string<V: std::fmt::Display>(map: &HashMap<String, V>) -> String {
98    let entries: Vec<String> = map.iter().map(|(k, v)| format!("({k} -> {v})")).collect();
99    format!("{{{}}}", entries.join(", "))
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn equality_is_order_insensitive() {
108        let mut finalized_a = HashMap::new();
109        finalized_a.insert("f1".to_string(), FinalizedVersionRange::new(1, 2).unwrap());
110        finalized_a.insert("f2".to_string(), FinalizedVersionRange::new(2, 3).unwrap());
111        let mut finalized_b = HashMap::new();
112        finalized_b.insert("f2".to_string(), FinalizedVersionRange::new(2, 3).unwrap());
113        finalized_b.insert("f1".to_string(), FinalizedVersionRange::new(1, 2).unwrap());
114
115        let a = FeatureMetadata::new(finalized_a, Some(1), HashMap::new());
116        let b = FeatureMetadata::new(finalized_b, Some(1), HashMap::new());
117        assert_eq!(a, b);
118    }
119
120    #[test]
121    fn accessors_return_inner_state() {
122        let mut supported = HashMap::new();
123        supported.insert("f1".to_string(), SupportedVersionRange::new(1, 5).unwrap());
124        let metadata = FeatureMetadata::new(HashMap::new(), None, supported);
125        assert!(metadata.finalized_features().is_empty());
126        assert_eq!(metadata.finalized_features_epoch(), None);
127        assert_eq!(
128            metadata.supported_features().get("f1"),
129            Some(&SupportedVersionRange::new(1, 5).unwrap())
130        );
131    }
132}