Skip to main content

confluent_kafka/admin/
log_dir_description.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 description of a log directory on a particular broker.
16
17use crate::common::requests::DescribeLogDirsResponse;
18use std::collections::HashMap;
19
20use crate::common::Error;
21use crate::common::TopicPartition;
22
23use super::ReplicaInfo;
24
25/// A description of a log directory on a particular broker.
26#[derive(Clone, Debug)]
27#[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription")]
28pub struct LogDirDescription {
29    error: Option<Error>,
30    replica_infos: HashMap<TopicPartition, ReplicaInfo>,
31    total_bytes: Option<i64>,
32    usable_bytes: Option<i64>,
33    is_cordoned: bool,
34}
35
36impl LogDirDescription {
37    /// Creates a new `LogDirDescription` with unknown volume sizes.
38    ///
39    /// # Arguments
40    ///
41    /// - `error` - the error if the log directory is offline or an error occurred, otherwise
42    ///   `None`.
43    /// - `replica_infos` - the replicas of the log directory, by partition.
44    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#LogDirDescription")]
45    pub fn new(error: Option<Error>, replica_infos: HashMap<TopicPartition, ReplicaInfo>) -> Self {
46        Self::with_total_bytes_usable_bytes_is_cordoned(
47            error,
48            replica_infos,
49            DescribeLogDirsResponse::UNKNOWN_VOLUME_BYTES,
50            DescribeLogDirsResponse::UNKNOWN_VOLUME_BYTES,
51            false,
52        )
53    }
54
55    /// Creates a new `LogDirDescription` with the given raw volume sizes and no
56    /// cordoning. A raw value of `UNKNOWN_VOLUME_BYTES` (`-1`) maps to `None`.
57    ///
58    /// # Arguments
59    ///
60    /// - `error` - the error if the log directory is offline or an error occurred, otherwise
61    ///   `None`.
62    /// - `replica_infos` - the replicas of the log directory, by partition.
63    /// - `total_bytes` - the total size of the volume, or `UNKNOWN_VOLUME_BYTES` (`-1`).
64    /// - `usable_bytes` - the usable size of the volume, or `UNKNOWN_VOLUME_BYTES` (`-1`).
65    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#LogDirDescription")]
66    pub fn with_total_bytes_usable_bytes(
67        error: Option<Error>,
68        replica_infos: HashMap<TopicPartition, ReplicaInfo>,
69        total_bytes: i64,
70        usable_bytes: i64,
71    ) -> Self {
72        Self::with_total_bytes_usable_bytes_is_cordoned(error, replica_infos, total_bytes, usable_bytes, false)
73    }
74
75    /// Creates a new `LogDirDescription` with the given raw volume sizes and
76    /// cordoning flag. A raw value of `UNKNOWN_VOLUME_BYTES` (`-1`) maps to
77    /// `None`.
78    ///
79    /// # Arguments
80    ///
81    /// - `error` - the error if the log directory is offline or an error occurred, otherwise
82    ///   `None`.
83    /// - `replica_infos` - the replicas of the log directory, by partition.
84    /// - `total_bytes` - the total size of the volume, or `UNKNOWN_VOLUME_BYTES` (`-1`).
85    /// - `usable_bytes` - the usable size of the volume, or `UNKNOWN_VOLUME_BYTES` (`-1`).
86    /// - `is_cordoned` - whether the log directory is cordoned.
87    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#LogDirDescription")]
88    pub fn with_total_bytes_usable_bytes_is_cordoned(
89        error: Option<Error>,
90        replica_infos: HashMap<TopicPartition, ReplicaInfo>,
91        total_bytes: i64,
92        usable_bytes: i64,
93        is_cordoned: bool,
94    ) -> Self {
95        Self {
96            error,
97            replica_infos,
98            total_bytes: (total_bytes != DescribeLogDirsResponse::UNKNOWN_VOLUME_BYTES).then_some(total_bytes),
99            usable_bytes: (usable_bytes != DescribeLogDirsResponse::UNKNOWN_VOLUME_BYTES).then_some(usable_bytes),
100            is_cordoned,
101        }
102    }
103
104    /// Returns the error if the log directory is offline or an error occurred,
105    /// otherwise `None`.
106    ///
107    /// - `KafkaStorageError` — the log directory is offline.
108    /// - `UnknownServerError` — the server experienced an unexpected error.
109    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#error")]
110    pub fn error(&self) -> Option<&Error> {
111        self.error.as_ref()
112    }
113
114    /// Returns a map from topic partition to replica information for that partition in
115    /// this log directory.
116    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#replicaInfos")]
117    pub fn replica_infos(&self) -> &HashMap<TopicPartition, ReplicaInfo> {
118        &self.replica_infos
119    }
120
121    /// Returns the total size of the volume this log directory is on or `None` if the broker did
122    /// not return a value. For volumes larger than `i64::MAX`, `i64::MAX` is returned. This
123    /// value does not include the size of data stored in remote storage.
124    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#totalBytes")]
125    pub fn total_bytes(&self) -> Option<i64> {
126        self.total_bytes
127    }
128
129    /// Returns the usable size on the volume this log directory is on or `None` if the broker
130    /// did not return a value. For usable sizes larger than `i64::MAX`, `i64::MAX` is returned.
131    /// This value does not include the size of data stored in remote storage.
132    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#usableBytes")]
133    pub fn usable_bytes(&self) -> Option<i64> {
134        self.usable_bytes
135    }
136
137    /// Returns whether this log directory is cordoned or not.
138    #[doc(alias = "org.apache.kafka.clients.admin.LogDirDescription#isCordoned")]
139    pub fn is_cordoned(&self) -> bool {
140        self.is_cordoned
141    }
142}
143
144impl std::fmt::Display for LogDirDescription {
145    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
146        write!(
147            f,
148            "LogDirDescription(replicaInfos={:?}, error={:?}, totalBytes={:?}, usableBytes={:?}, isCordoned={})",
149            self.replica_infos, self.error, self.total_bytes, self.usable_bytes, self.is_cordoned
150        )
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157    use crate::common::protocol::Errors;
158
159    #[test]
160    fn unknown_volume_bytes_maps_to_none() {
161        let d = LogDirDescription::new(None, HashMap::new());
162        assert!(d.error().is_none());
163        assert_eq!(d.total_bytes(), None);
164        assert_eq!(d.usable_bytes(), None);
165        assert!(!d.is_cordoned());
166    }
167
168    #[test]
169    fn cordoned_flag_is_carried() {
170        let d = LogDirDescription::with_total_bytes_usable_bytes_is_cordoned(None, HashMap::new(), -1, -1, true);
171        assert!(d.is_cordoned());
172        assert_eq!(d.total_bytes(), None);
173        // The four-arg constructor defaults `is_cordoned` to false.
174        let d2 = LogDirDescription::with_total_bytes_usable_bytes(None, HashMap::new(), 1, 2);
175        assert!(!d2.is_cordoned());
176    }
177
178    #[test]
179    fn known_volume_bytes_are_present() {
180        let d = LogDirDescription::with_total_bytes_usable_bytes(
181            Some(Error::new(Errors::KafkaStorageError)),
182            HashMap::new(),
183            123,
184            456,
185        );
186        assert_eq!(d.error().unwrap().error(), Errors::KafkaStorageError);
187        assert_eq!(d.total_bytes(), Some(123));
188        assert_eq!(d.usable_bytes(), Some(456));
189    }
190}