Skip to main content

confluent_kafka/consumer/
consumer_log_truncation_error.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//! Translated from `org.apache.kafka.clients.consumer.LogTruncationException`.
16
17use std::collections::HashMap;
18use std::fmt;
19
20use crate::common::Error;
21use crate::common::TopicPartition;
22use crate::common::error::{ErrorCode, ErrorHierarchy, ErrorMessage, ErrorSource};
23use crate::consumer::OffsetAndMetadata;
24
25/// In the event of an unclean leader election, the log will be truncated,
26/// previously committed data will be lost, and new data will be written over
27/// these offsets. When this happens, the consumer will detect the truncation
28/// and return this error (if no automatic reset policy has been defined) with
29/// the first offset known to diverge from what the consumer previously read.
30// Java `extends` chain: `LogTruncationException` -> `OffsetOutOfRangeException`
31// -> `InvalidOffsetException` -> `KafkaException`, the consumer package's
32// classes, so this is a `ConsumerOffsetOutOfRangeError` too and carries the same
33// `offset_out_of_range_partitions` map. It has no entry in `Errors`.
34#[derive(Clone, Debug)]
35#[doc(alias = "org.apache.kafka.clients.consumer.LogTruncationException")]
36pub struct ConsumerLogTruncationError {
37    message: String,
38    /// The out-of-range offset per partition, inherited from the parent class.
39    pub(crate) offset_out_of_range_partitions: HashMap<TopicPartition, i64>,
40    /// The divergent offset per partition.
41    pub(crate) divergent_offsets: HashMap<TopicPartition, OffsetAndMetadata>,
42}
43
44impl ConsumerLogTruncationError {
45    /// Constructs a new `ConsumerLogTruncationError` with the fetch offsets and
46    /// divergent offsets.
47    ///
48    /// # Arguments
49    ///
50    /// - `offset_out_of_range_partitions` - The fetch offsets that were out of range
51    /// - `divergent_offsets` - The offsets where the consumer's log diverged from the broker's log
52    #[doc(alias = "org.apache.kafka.clients.consumer.LogTruncationException#LogTruncationException")]
53    pub fn new(
54        offset_out_of_range_partitions: HashMap<TopicPartition, i64>,
55        divergent_offsets: HashMap<TopicPartition, OffsetAndMetadata>,
56    ) -> Self {
57        let mut items: Vec<String> = divergent_offsets.iter().map(|(k, v)| format!("{k}={v}")).collect();
58        items.sort();
59        let message = format!("Truncated partitions detected with divergent offsets {{{}}}", items.join(", "));
60        Self { message, offset_out_of_range_partitions, divergent_offsets }
61    }
62
63    /// Constructs a new `ConsumerLogTruncationError` with a custom message.
64    ///
65    /// # Arguments
66    ///
67    /// - `message` - The detail message
68    /// - `offset_out_of_range_partitions` - The fetch offsets that were out of range
69    /// - `divergent_offsets` - The offsets where the consumer's log diverged from the broker's log
70    #[doc(alias = "org.apache.kafka.clients.consumer.LogTruncationException#LogTruncationException")]
71    pub fn with_message(
72        message: impl Into<String>,
73        offset_out_of_range_partitions: HashMap<TopicPartition, i64>,
74        divergent_offsets: HashMap<TopicPartition, OffsetAndMetadata>,
75    ) -> Self {
76        Self { message: message.into(), offset_out_of_range_partitions, divergent_offsets }
77    }
78
79    /// Get a map of the topic partitions and the respective out-of-range fetch
80    /// offsets.
81    ///
82    /// # Returns
83    ///
84    /// The out-of-range fetch offset per partition
85    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetOutOfRangeException#offsetOutOfRangePartitions")]
86    pub fn offset_out_of_range_partitions(&self) -> &HashMap<TopicPartition, i64> {
87        &self.offset_out_of_range_partitions
88    }
89
90    /// Get the divergent offsets for the partitions which were truncated. For
91    /// each partition, this is the first offset which is known to diverge from
92    /// what the consumer read.
93    ///
94    /// Note that there is no guarantee that this offset will be known. It is
95    /// necessary to use [`Self::partitions`] to see the set of partitions that
96    /// were truncated and then check for the presence of a divergent offset in
97    /// this map.
98    ///
99    /// # Returns
100    ///
101    /// The divergent offset per partition
102    #[doc(alias = "org.apache.kafka.clients.consumer.LogTruncationException#divergentOffsets")]
103    pub fn divergent_offsets(&self) -> &HashMap<TopicPartition, OffsetAndMetadata> {
104        &self.divergent_offsets
105    }
106
107    /// Returns the set of partitions for which the offset was invalid.
108    ///
109    /// # Returns
110    ///
111    /// The set of partitions with invalid offsets
112    ///
113    /// # Translation notes
114    ///
115    /// Iterates the keys instead of copying them.
116    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetOutOfRangeException#partitions")]
117    pub fn partitions(&self) -> impl Iterator<Item = &TopicPartition> {
118        self.offset_out_of_range_partitions.keys()
119    }
120
121    /// Returns the error message.
122    // Java's Throwable.getMessage, a JDK method
123    #[doc(alias = "rust-only")]
124    pub fn message(&self) -> &str {
125        &self.message
126    }
127}
128
129impl fmt::Display for ConsumerLogTruncationError {
130    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
131        write!(f, "ConsumerLogTruncationError: {}", self.message)
132    }
133}
134
135impl ErrorMessage for ConsumerLogTruncationError {
136    fn message(&self) -> &str {
137        &self.message
138    }
139}
140
141impl ErrorCode for ConsumerLogTruncationError {}
142
143impl ErrorHierarchy for ConsumerLogTruncationError {
144    fn is_kafka_error(&self) -> bool {
145        true
146    }
147    fn is_consumer_invalid_offset_error(&self) -> bool {
148        true
149    }
150    fn is_consumer_offset_out_of_range_error(&self) -> bool {
151        true
152    }
153    fn is_consumer_log_truncation_error(&self) -> bool {
154        true
155    }
156}
157
158impl ErrorSource for ConsumerLogTruncationError {
159    // `LogTruncationException` exposes no `Throwable cause` constructor, so its cause is
160    // always null in Java; the trait default (`None`) is that answer.
161}
162
163impl ConsumerLogTruncationError {
164    /// Returns the cause of this error: always `None`, as no constructor takes
165    /// one.
166    // An inherent method, so it shadows both `ErrorSource::source` and
167    // `std::error::Error::source`, keeping `x.source()` unambiguous and typed.
168    // Java's Throwable.getCause, a JDK method
169    #[doc(alias = "rust-only")]
170    pub fn source(&self) -> Option<&Error> {
171        None
172    }
173}
174
175impl std::error::Error for ConsumerLogTruncationError {
176    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
177        Option::<&Error>::None.map(|e| e as &(dyn std::error::Error + 'static))
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184    use std::collections::HashSet;
185
186    /// Recovered from `master:src/consumer/errors.rs`
187    /// (`test_log_truncation_default_message_and_accessors`), which was dropped
188    /// when that file was split into one file per error class.
189    ///
190    /// Java: `LogTruncationException(Map, Map)` composes
191    /// `"Truncated partitions detected with divergent offsets " +
192    /// divergentOffsets` (`org.apache.kafka.clients.consumer.LogTruncationException#LogTruncationException(Map,Map)`); Java's
193    /// `Map.toString()` braces the entries.
194    #[test]
195    fn test_log_truncation_default_message_and_accessors() {
196        let tp = TopicPartition::new("t".to_string(), 0);
197        let e = ConsumerLogTruncationError::new(
198            HashMap::from([(tp.clone(), 100)]),
199            HashMap::from([(tp.clone(), OffsetAndMetadata::new(95).unwrap())]),
200        );
201        assert!(
202            e.message().starts_with("Truncated partitions detected with divergent offsets "),
203            "got: {}",
204            e.message()
205        );
206        assert!(e.divergent_offsets().contains_key(&tp));
207        assert!(e.offset_out_of_range_partitions().contains_key(&tp));
208    }
209
210    /// `LogTruncationException` does NOT override `partitions()`, so it inherits
211    /// `OffsetOutOfRangeException`'s `offsetOutOfRangePartitions.keySet()`
212    /// (`org.apache.kafka.clients.consumer.OffsetOutOfRangeException#partitions`). That is what makes the javadoc
213    /// of `org.apache.kafka.clients.consumer.LogTruncationException#divergentOffsets` meaningful: iterate
214    /// `partitions()`, then look each one up in `divergentOffsets()`, "because
215    /// there is no guarantee that this offset will be known". So the two sets
216    /// are deliberately allowed to differ, and `partitions()` must follow the
217    /// out-of-range map.
218    #[test]
219    fn test_log_truncation_partitions_is_out_of_range_set_not_divergent_set() {
220        let known = TopicPartition::new("t".to_string(), 0);
221        let unknown = TopicPartition::new("t".to_string(), 1);
222        let e = ConsumerLogTruncationError::new(
223            HashMap::from([(known.clone(), 100), (unknown.clone(), 200)]),
224            // Only one of the two truncated partitions has a known divergent
225            // offset — Java's documented case.
226            HashMap::from([(known.clone(), OffsetAndMetadata::new(95).unwrap())]),
227        );
228        let parts: HashSet<&TopicPartition> = e.partitions().collect();
229        assert_eq!(parts, HashSet::from([&known, &unknown]));
230        assert!(!e.divergent_offsets().contains_key(&unknown));
231    }
232
233    /// `LogTruncationException extends OffsetOutOfRangeException extends
234    /// InvalidOffsetException extends KafkaException`
235    /// (`org.apache.kafka.clients.consumer.LogTruncationException`), where the middle two are the
236    /// CONSUMER package's classes — so it answers to both consumer predicates
237    /// and to neither `ApiException` nor `RetriableException`.
238    #[test]
239    fn test_log_truncation_error_hierarchy() {
240        let tp = TopicPartition::new("t".to_string(), 0);
241        let e = Error::ConsumerLogTruncation(Box::new(ConsumerLogTruncationError::new(
242            HashMap::from([(tp.clone(), 100)]),
243            HashMap::from([(tp, OffsetAndMetadata::new(95).unwrap())]),
244        )));
245        assert!(e.is_kafka_error());
246        assert!(e.is_consumer_invalid_offset_error());
247        assert!(e.is_consumer_offset_out_of_range_error());
248        assert!(!e.is_api_error());
249        assert!(!e.is_retriable_error());
250    }
251}