Skip to main content

confluent_kafka/consumer/
offset_and_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//! Offset and metadata committed by a consumer.
16//!
17//! Translated from `org.apache.kafka.clients.consumer.OffsetAndMetadata`.
18
19use std::fmt;
20use std::hash::{Hash, Hasher};
21
22use crate::common::Error;
23
24/// The Kafka offset commit API allows users to provide additional metadata
25/// (in the form of a string) when an offset is committed. This can be useful
26/// (for example) to store information about which node made the commit, what
27/// time the commit was made, etc.
28#[derive(Clone, Debug)]
29#[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata")]
30pub struct OffsetAndMetadata {
31    offset: i64,
32    // Internal leader epoch (raw); the public getter normalizes negative
33    // values to `None` to match Java's `leaderEpoch()`.
34    leader_epoch: Option<i32>,
35    metadata: String,
36}
37
38impl OffsetAndMetadata {
39    /// Construct a new OffsetAndMetadata object for committing through
40    /// [`KafkaConsumer`](crate::consumer::KafkaConsumer). The metadata
41    /// associated with the commit will be empty.
42    ///
43    /// # Arguments
44    ///
45    /// - `offset` - The offset to be committed
46    ///
47    /// # Returns
48    ///
49    /// The new `OffsetAndMetadata`.
50    ///
51    /// # Errors
52    ///
53    /// - `Error::is_local_illegal_argument_error` if `offset` is negative.
54    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#OffsetAndMetadata")]
55    pub fn new(offset: i64) -> Result<Self, Error> {
56        Self::with_leader_epoch_metadata(offset, None, String::new())
57    }
58
59    /// Construct a new OffsetAndMetadata object for committing through
60    /// [`KafkaConsumer`](crate::consumer::KafkaConsumer).
61    ///
62    /// # Arguments
63    ///
64    /// - `offset` - The offset to be committed
65    /// - `metadata` - Non-null metadata
66    ///
67    /// # Returns
68    ///
69    /// The new `OffsetAndMetadata`.
70    ///
71    /// # Errors
72    ///
73    /// - `Error::is_local_illegal_argument_error` if `offset` is negative.
74    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#OffsetAndMetadata")]
75    pub fn with_metadata(offset: i64, metadata: impl Into<String>) -> Result<Self, Error> {
76        Self::with_leader_epoch_metadata(offset, None, metadata)
77    }
78
79    /// Construct a new OffsetAndMetadata object for committing through
80    /// [`KafkaConsumer`](crate::consumer::KafkaConsumer).
81    ///
82    /// # Arguments
83    ///
84    /// - `offset` - The offset to be committed
85    /// - `leader_epoch` - Optional leader epoch of the last consumed record
86    /// - `metadata` - Non-null metadata
87    ///
88    /// # Returns
89    ///
90    /// The new `OffsetAndMetadata`.
91    ///
92    /// # Errors
93    ///
94    /// - `Error::is_local_illegal_argument_error` if `offset` is negative.
95    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#OffsetAndMetadata")]
96    pub fn with_leader_epoch_metadata(
97        offset: i64,
98        leader_epoch: Option<i32>,
99        metadata: impl Into<String>,
100    ) -> Result<Self, Error> {
101        if offset < 0 {
102            return Err(Error::local_illegal_argument("Invalid negative offset"));
103        }
104        // Java's constructor normalizes a null metadata string to the empty
105        // string ("NO_METADATA"). In Rust, callers can pass `""` directly;
106        // `impl Into<String>` accepts both `&str` and `String`.
107        Ok(Self { offset, leader_epoch, metadata: metadata.into() })
108    }
109
110    /// Returns the committed offset.
111    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#offset")]
112    pub fn offset(&self) -> i64 {
113        self.offset
114    }
115
116    /// Get the metadata of the previously consumed record.
117    ///
118    /// # Returns
119    ///
120    /// The metadata or empty string if no metadata
121    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#metadata")]
122    pub fn metadata(&self) -> &str {
123        &self.metadata
124    }
125
126    /// Get the leader epoch of the previously consumed record (if one is
127    /// known). Log truncation is detected if there exists a leader epoch which
128    /// is larger than this epoch and begins at an offset earlier than the
129    /// committed offset.
130    ///
131    /// # Returns
132    ///
133    /// The leader epoch or empty if not known
134    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadata#leaderEpoch")]
135    pub fn leader_epoch(&self) -> Option<i32> {
136        match self.leader_epoch {
137            Some(e) if e >= 0 => Some(e),
138            _ => None,
139        }
140    }
141}
142
143impl PartialEq for OffsetAndMetadata {
144    fn eq(&self, other: &Self) -> bool {
145        // Java equality uses the filtered leaderEpoch() value, not the raw
146        // field — see OffsetAndMetadata.equals in the Java source.
147        self.offset == other.offset && self.metadata == other.metadata && self.leader_epoch() == other.leader_epoch()
148    }
149}
150
151impl Eq for OffsetAndMetadata {}
152
153impl Hash for OffsetAndMetadata {
154    fn hash<H: Hasher>(&self, state: &mut H) {
155        self.offset.hash(state);
156        self.metadata.hash(state);
157        self.leader_epoch().hash(state);
158    }
159}
160
161impl fmt::Display for OffsetAndMetadata {
162    // Matches Java's `toString()`:
163    // `OffsetAndMetadata{offset=N, leaderEpoch=X, metadata='Y'}`
164    // where `X` is `null` if no leader epoch is present.
165    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
166        let leader_epoch_str = match self.leader_epoch() {
167            Some(e) => e.to_string(),
168            None => "null".to_string(),
169        };
170        write!(
171            f,
172            "OffsetAndMetadata{{offset={}, leaderEpoch={}, metadata='{}'}}",
173            self.offset, leader_epoch_str, self.metadata
174        )
175    }
176}
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181    use std::collections::hash_map::DefaultHasher;
182
183    fn hash_of(o: &OffsetAndMetadata) -> u64 {
184        let mut h = DefaultHasher::new();
185        o.hash(&mut h);
186        h.finish()
187    }
188
189    #[test]
190    fn test_simple_constructor() {
191        let o = OffsetAndMetadata::new(10).unwrap();
192        assert_eq!(o.offset(), 10);
193        assert_eq!(o.metadata(), "");
194        assert_eq!(o.leader_epoch(), None);
195    }
196
197    #[test]
198    fn test_new_metadata() {
199        let o = OffsetAndMetadata::with_metadata(10, "m").unwrap();
200        assert_eq!(o.metadata(), "m");
201        assert_eq!(o.leader_epoch(), None);
202    }
203
204    #[test]
205    fn test_new_leader_epoch_metadata() {
206        let o = OffsetAndMetadata::with_leader_epoch_metadata(10, Some(2), "m").unwrap();
207        assert_eq!(o.leader_epoch(), Some(2));
208    }
209
210    #[test]
211    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadataTest#testInvalidNegativeOffset")]
212    fn test_invalid_negative_offset() {
213        let err = OffsetAndMetadata::new(-1).unwrap_err();
214        assert!(err.message().contains("Invalid negative offset"));
215    }
216
217    #[test]
218    fn test_negative_leader_epoch_treated_as_none() {
219        let o = OffsetAndMetadata::with_leader_epoch_metadata(10, Some(-1), "m").unwrap();
220        assert_eq!(o.leader_epoch(), None);
221    }
222
223    #[test]
224    fn test_display() {
225        let o = OffsetAndMetadata::with_leader_epoch_metadata(10, Some(2), "m").unwrap();
226        assert_eq!(o.to_string(), "OffsetAndMetadata{offset=10, leaderEpoch=2, metadata='m'}");
227
228        let o = OffsetAndMetadata::new(10).unwrap();
229        assert_eq!(o.to_string(), "OffsetAndMetadata{offset=10, leaderEpoch=null, metadata=''}");
230    }
231
232    #[test]
233    #[doc(alias = "org.apache.kafka.clients.consumer.OffsetAndMetadataTest#testEqualsWithNullAndNegativeLeaderEpoch")]
234    fn test_equals_with_null_and_negative_leader_epoch() {
235        let with_none = OffsetAndMetadata::with_leader_epoch_metadata(100, None, "metadata").unwrap();
236        let with_neg = OffsetAndMetadata::with_leader_epoch_metadata(100, Some(-1), "metadata").unwrap();
237        assert_eq!(with_none, with_neg);
238        assert_eq!(hash_of(&with_none), hash_of(&with_neg));
239    }
240}