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}