Skip to main content

confluent_kafka/admin/
feature_update.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 an update to a finalized feature.
16
17use crate::common::Error;
18
19/// Indicates what kind of upgrade should be performed for a
20/// [`FeatureUpdate`].
21#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
22#[non_exhaustive]
23#[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate$UpgradeType")]
24pub enum UpgradeType {
25    /// Unknown upgrade type.
26    Unknown,
27    /// Upgrading the feature level.
28    Upgrade,
29    /// Only downgrades which do not result in metadata loss are permitted.
30    SafeDowngrade,
31    /// Any downgrade, including those which may result in metadata loss, are
32    /// permitted.
33    UnsafeDowngrade,
34}
35
36/// Java's inherited `Enum.toString()`: the constant's name.
37impl std::fmt::Display for UpgradeType {
38    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
39        f.write_str(match self {
40            Self::Unknown => "UNKNOWN",
41            Self::Upgrade => "UPGRADE",
42            Self::SafeDowngrade => "SAFE_DOWNGRADE",
43            Self::UnsafeDowngrade => "UNSAFE_DOWNGRADE",
44        })
45    }
46}
47
48impl UpgradeType {
49    /// Returns the wire-protocol code for this upgrade type.
50    #[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate$UpgradeType#code")]
51    pub fn code(&self) -> i8 {
52        match self {
53            UpgradeType::Unknown => 0,
54            UpgradeType::Upgrade => 1,
55            UpgradeType::SafeDowngrade => 2,
56            UpgradeType::UnsafeDowngrade => 3,
57        }
58    }
59
60    /// Returns the upgrade type for the given wire-protocol code, falling back
61    /// to [`UpgradeType::Unknown`] for unrecognized codes.
62    ///
63    /// # Arguments
64    ///
65    /// - `code` - the wire-protocol code.
66    #[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate$UpgradeType#fromCode")]
67    pub fn from_code(code: i32) -> UpgradeType {
68        match code {
69            1 => UpgradeType::Upgrade,
70            2 => UpgradeType::SafeDowngrade,
71            3 => UpgradeType::UnsafeDowngrade,
72            _ => UpgradeType::Unknown,
73        }
74    }
75}
76
77/// Encapsulates details about an update to a finalized feature.
78#[derive(Clone, Debug, PartialEq, Eq, Hash)]
79#[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate")]
80pub struct FeatureUpdate {
81    max_version_level: i16,
82    upgrade_type: UpgradeType,
83}
84
85impl FeatureUpdate {
86    /// Creates a new `FeatureUpdate`.
87    ///
88    /// # Arguments
89    ///
90    /// - `max_version_level` - The new maximum version level for the finalized feature. a value of
91    ///   zero is special and indicates that the update is intended to delete the finalized feature,
92    ///   and should be accompanied by setting the `upgrade_type` to safe or unsafe.
93    /// - `upgrade_type` - Indicate what kind of upgrade should be performed in this operation. -
94    ///   UPGRADE: upgrading the feature level - SAFE_DOWNGRADE: only downgrades which do not result
95    ///   in metadata loss are permitted - UNSAFE_DOWNGRADE: any downgrade, including those which
96    ///   may result in metadata loss, are permitted
97    ///
98    /// # Errors
99    ///
100    /// Returns an error answering `Error::is_local_illegal_argument_error` if
101    /// `max_version_level` is zero while
102    /// `upgrade_type` is [`UpgradeType::Upgrade`], or if `max_version_level` is
103    /// negative.
104    #[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate#FeatureUpdate")]
105    pub fn new(max_version_level: i16, upgrade_type: UpgradeType) -> Result<Self, Error> {
106        if max_version_level == 0 && upgrade_type == UpgradeType::Upgrade {
107            return Err(Error::local_illegal_argument(format!(
108                "The upgradeType flag should be set to SAFE_DOWNGRADE or UNSAFE_DOWNGRADE when the provided \
109                 maxVersionLevel:{max_version_level} is < 1."
110            )));
111        }
112        if max_version_level < 0 {
113            return Err(Error::local_illegal_argument("Cannot specify a negative version level."));
114        }
115        Ok(Self { max_version_level, upgrade_type })
116    }
117
118    /// Returns the new maximum version level for the finalized feature.
119    #[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate#maxVersionLevel")]
120    pub fn max_version_level(&self) -> i16 {
121        self.max_version_level
122    }
123
124    /// Returns the upgrade type for this update.
125    #[doc(alias = "org.apache.kafka.clients.admin.FeatureUpdate#upgradeType")]
126    pub fn upgrade_type(&self) -> UpgradeType {
127        self.upgrade_type
128    }
129}
130
131impl std::fmt::Display for FeatureUpdate {
132    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
133        write!(
134            f,
135            "FeatureUpdate{{maxVersionLevel:{}, upgradeType:{}}}",
136            self.max_version_level, self.upgrade_type
137        )
138    }
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144
145    #[test]
146    fn upgrade_type_codes_round_trip() {
147        assert_eq!(UpgradeType::Unknown.code(), 0);
148        assert_eq!(UpgradeType::Upgrade.code(), 1);
149        assert_eq!(UpgradeType::SafeDowngrade.code(), 2);
150        assert_eq!(UpgradeType::UnsafeDowngrade.code(), 3);
151        assert_eq!(UpgradeType::from_code(0), UpgradeType::Unknown);
152        assert_eq!(UpgradeType::from_code(1), UpgradeType::Upgrade);
153        assert_eq!(UpgradeType::from_code(2), UpgradeType::SafeDowngrade);
154        assert_eq!(UpgradeType::from_code(3), UpgradeType::UnsafeDowngrade);
155        // Unrecognized codes fall back to Unknown.
156        assert_eq!(UpgradeType::from_code(42), UpgradeType::Unknown);
157    }
158
159    #[test]
160    fn new_valid_update() {
161        let update = FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap();
162        assert_eq!(update.max_version_level(), 2);
163        assert_eq!(update.upgrade_type(), UpgradeType::Upgrade);
164    }
165
166    #[test]
167    fn new_deletion_with_downgrade_is_allowed() {
168        let update = FeatureUpdate::new(0, UpgradeType::SafeDowngrade).unwrap();
169        assert_eq!(update.max_version_level(), 0);
170        assert_eq!(update.upgrade_type(), UpgradeType::SafeDowngrade);
171    }
172
173    /// Mirrors `KafkaAdminClientTest.testUpdateFeaturesShouldFailRequestInClientWhenDowngradeFlagIsNotSetDuringDeletion`.
174    #[test]
175    fn new_rejects_deletion_with_upgrade_flag() {
176        let err = FeatureUpdate::new(0, UpgradeType::Upgrade).unwrap_err();
177        assert_eq!(
178            err.message(),
179            "The upgradeType flag should be set to SAFE_DOWNGRADE or UNSAFE_DOWNGRADE when the provided \
180             maxVersionLevel:0 is < 1."
181        );
182    }
183
184    #[test]
185    fn new_rejects_negative_version_level() {
186        let err = FeatureUpdate::new(-1, UpgradeType::SafeDowngrade).unwrap_err();
187        assert_eq!(err.message(), "Cannot specify a negative version level.");
188    }
189
190    /// Java's `toString()` prints the upgrade type's constant name.
191    #[test]
192    fn to_string_follows_java() {
193        let update = FeatureUpdate::new(0, UpgradeType::SafeDowngrade).unwrap();
194        assert_eq!(
195            update.to_string(),
196            "FeatureUpdate{maxVersionLevel:0, upgradeType:SAFE_DOWNGRADE}"
197        );
198    }
199}