Skip to main content

confluent_kafka/consumer/
consumer_record.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 key/value pair received from Kafka.
16//!
17//! Translated from `org.apache.kafka.clients.consumer.ConsumerRecord`.
18
19use crate::common::Error;
20use std::fmt;
21use std::sync::Arc;
22
23use crate::common::header::RecordHeaders;
24use crate::common::record::TimestampType;
25
26/// A key/value pair to be received from Kafka. This also consists of a topic
27/// name and a partition number from which the record is being received, an
28/// offset that points to the record in a Kafka partition, and a timestamp as
29/// marked by the corresponding `ProducerRecord`.
30///
31/// # Translation notes
32///
33/// Java's record is not thread-safe because `headers()` hands out a mutable
34/// collection; here it hands out a shared reference, so the borrow rules make
35/// concurrent reads safe.
36// The `topic` is an `Arc<str>` shared cheaply across all records from the same
37// topic-partition (consumer-threading.md §27), and the headers are owned,
38// matching Java's allocation behavior.
39#[derive(Clone)]
40#[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord")]
41pub struct ConsumerRecord<K, V> {
42    topic: Arc<str>,
43    partition: i32,
44    offset: i64,
45    timestamp: i64,
46    timestamp_type: TimestampType,
47    serialized_key_size: i32,
48    serialized_value_size: i32,
49    headers: RecordHeaders,
50    key: Option<K>,
51    value: Option<V>,
52    leader_epoch: Option<i32>,
53    delivery_count: Option<i16>,
54}
55
56/// The parameters of [`ConsumerRecord::with_options`], built with
57/// [`ConsumerRecordOptionsBuilder`]: `topic`, `partition`, `offset`, `key` and
58/// `value` are mandatory.
59// Every parameter of Java's widest `ConsumerRecord` constructor. It differs from
60// the overload group's intersection `{topic, partition, offset, key, value}` by
61// seven parameters, so the naming rule makes this struct the method's only
62// parameter, carrying the intersection's own too (DoD #7). It deliberately has
63// no `Default`: the mandatory five are what even Java's narrowest constructor
64// `ConsumerRecord(String, int, long, K, V)` takes from its caller.
65#[non_exhaustive]
66#[derive(Clone, Debug)]
67// the options of ConsumerRecord's constructor overloads (CLAUDE.md §2)
68#[doc(alias = "rust-only")]
69pub struct ConsumerRecordOptions<K, V> {
70    // The topic this record is received from. Java's `topic`.
71    pub(crate) topic: Arc<str>,
72    // The partition of the topic this record is received from. Java's
73    // `partition`.
74    pub(crate) partition: i32,
75    // The offset of this record in the corresponding Kafka partition.
76    // Java's `offset`.
77    pub(crate) offset: i64,
78    // The timestamp of the record. Java's `timestamp`; starts as
79    // [`ConsumerRecord::NO_TIMESTAMP`], as in `ConsumerRecord(String, int, long, K, V)`.
80    pub(crate) timestamp: i64,
81    // The timestamp type of the record. Java's `timestampType`; starts as
82    // [`TimestampType::NoTimestampType`], as in `ConsumerRecord(String, int, long, K, V)`.
83    pub(crate) timestamp_type: TimestampType,
84    // The length of the serialized key. Java's `serializedKeySize`; starts
85    // as [`ConsumerRecord::NULL_SIZE`], as in `ConsumerRecord(String, int, long, K, V)`.
86    pub(crate) serialized_key_size: i32,
87    // The length of the serialized value. Java's `serializedValueSize`;
88    // starts as [`ConsumerRecord::NULL_SIZE`], as in `ConsumerRecord(String, int, long, K, V)`.
89    pub(crate) serialized_value_size: i32,
90    // The key of the record, if one exists. Java's `key`.
91    pub(crate) key: Option<K>,
92    // The record contents. Java's `value`.
93    pub(crate) value: Option<V>,
94    // The headers of the record. Java's `headers`; starts empty, as in the narrowest
95    // constructor (`new RecordHeaders()`).
96    pub(crate) headers: RecordHeaders,
97    // The leader epoch, if available. Java's `leaderEpoch`; starts as
98    // `None`, as in `ConsumerRecord(String, int, long, K, V)` (`Optional.empty()`).
99    pub(crate) leader_epoch: Option<i32>,
100    // The delivery count, if available. Java's `deliveryCount`; starts as
101    // `None`, as in the narrower constructors (`Optional.empty()`).
102    pub(crate) delivery_count: Option<i16>,
103}
104
105/// Fluent builder for [`ConsumerRecordOptions`]: every parameter has a setter,
106/// and [`Self::build`] checks that the mandatory ones were set.
107#[derive(Debug)]
108// builds ConsumerRecordOptions (CLAUDE.md §2)
109#[doc(alias = "rust-only")]
110pub struct ConsumerRecordOptionsBuilder<K, V> {
111    topic: Option<Arc<str>>,
112    partition: Option<i32>,
113    offset: Option<i64>,
114    timestamp: i64,
115    timestamp_type: TimestampType,
116    serialized_key_size: i32,
117    serialized_value_size: i32,
118    key: Option<Option<K>>,
119    value: Option<Option<V>>,
120    headers: RecordHeaders,
121    leader_epoch: Option<i32>,
122    delivery_count: Option<i16>,
123}
124
125impl<K, V> Default for ConsumerRecordOptionsBuilder<K, V> {
126    fn default() -> Self {
127        Self::new()
128    }
129}
130
131impl<K, V> ConsumerRecordOptionsBuilder<K, V> {
132    /// Creates a builder with every mandatory parameter unset and every other
133    /// parameter at the value Java passes on the caller's behalf.
134    ///
135    /// # Returns
136    ///
137    /// The new builder.
138    pub fn new() -> Self {
139        Self {
140            topic: None,
141            partition: None,
142            offset: None,
143            timestamp: ConsumerRecord::<K, V>::NO_TIMESTAMP,
144            timestamp_type: TimestampType::NoTimestampType,
145            serialized_key_size: ConsumerRecord::<K, V>::NULL_SIZE,
146            serialized_value_size: ConsumerRecord::<K, V>::NULL_SIZE,
147            key: None,
148            value: None,
149            headers: RecordHeaders::new(),
150            leader_epoch: None,
151            delivery_count: None,
152        }
153    }
154
155    /// Sets `ConsumerRecordOptions::topic`, a mandatory parameter: [`Self::build`]
156    /// returns an error if it was not set.
157    ///
158    /// # Arguments
159    ///
160    /// - `topic` - The topic this record is received from
161    ///
162    /// # Returns
163    ///
164    /// This builder.
165    pub fn set_topic(mut self, topic: impl Into<Arc<str>>) -> Self {
166        self.topic = Some(topic.into());
167        self
168    }
169    /// Sets `ConsumerRecordOptions::partition`, a mandatory parameter: [`Self::build`]
170    /// returns an error if it was not set.
171    ///
172    /// # Arguments
173    ///
174    /// - `partition` - The partition of the topic this record is received from
175    ///
176    /// # Returns
177    ///
178    /// This builder.
179    pub fn set_partition(mut self, partition: i32) -> Self {
180        self.partition = Some(partition);
181        self
182    }
183    /// Sets `ConsumerRecordOptions::offset`, a mandatory parameter: [`Self::build`]
184    /// returns an error if it was not set.
185    ///
186    /// # Arguments
187    ///
188    /// - `offset` - The offset of this record in the corresponding Kafka partition
189    ///
190    /// # Returns
191    ///
192    /// This builder.
193    pub fn set_offset(mut self, offset: i64) -> Self {
194        self.offset = Some(offset);
195        self
196    }
197    /// Sets `ConsumerRecordOptions::timestamp`.
198    ///
199    /// # Arguments
200    ///
201    /// - `timestamp` - The timestamp of the record.
202    ///
203    /// # Returns
204    ///
205    /// This builder.
206    pub fn set_timestamp(mut self, timestamp: i64) -> Self {
207        self.timestamp = timestamp;
208        self
209    }
210    /// Sets `ConsumerRecordOptions::timestamp_type`.
211    ///
212    /// # Arguments
213    ///
214    /// - `timestamp_type` - The timestamp type
215    ///
216    /// # Returns
217    ///
218    /// This builder.
219    pub fn set_timestamp_type(mut self, timestamp_type: TimestampType) -> Self {
220        self.timestamp_type = timestamp_type;
221        self
222    }
223    /// Sets `ConsumerRecordOptions::serialized_key_size`.
224    ///
225    /// # Arguments
226    ///
227    /// - `serialized_key_size` - The length of the serialized key
228    ///
229    /// # Returns
230    ///
231    /// This builder.
232    pub fn set_serialized_key_size(mut self, serialized_key_size: i32) -> Self {
233        self.serialized_key_size = serialized_key_size;
234        self
235    }
236    /// Sets `ConsumerRecordOptions::serialized_value_size`.
237    ///
238    /// # Arguments
239    ///
240    /// - `serialized_value_size` - The length of the serialized value
241    ///
242    /// # Returns
243    ///
244    /// This builder.
245    pub fn set_serialized_value_size(mut self, serialized_value_size: i32) -> Self {
246        self.serialized_value_size = serialized_value_size;
247        self
248    }
249    /// Sets `ConsumerRecordOptions::key`, a mandatory parameter: [`Self::build`]
250    /// returns an error if it was not set.
251    ///
252    /// # Arguments
253    ///
254    /// - `key` - The key of the record, if one exists (`None` is allowed)
255    ///
256    /// # Returns
257    ///
258    /// This builder.
259    pub fn set_key(mut self, key: Option<K>) -> Self {
260        self.key = Some(key);
261        self
262    }
263    /// Sets `ConsumerRecordOptions::value`, a mandatory parameter: [`Self::build`]
264    /// returns an error if it was not set.
265    ///
266    /// # Arguments
267    ///
268    /// - `value` - The record contents
269    ///
270    /// # Returns
271    ///
272    /// This builder.
273    pub fn set_value(mut self, value: Option<V>) -> Self {
274        self.value = Some(value);
275        self
276    }
277    /// Sets `ConsumerRecordOptions::headers`.
278    ///
279    /// # Arguments
280    ///
281    /// - `headers` - The headers of the record
282    ///
283    /// # Returns
284    ///
285    /// This builder.
286    pub fn set_headers(mut self, headers: RecordHeaders) -> Self {
287        self.headers = headers;
288        self
289    }
290    /// Sets `ConsumerRecordOptions::leader_epoch`.
291    ///
292    /// # Arguments
293    ///
294    /// - `leader_epoch` - Optional leader epoch of the record (may be empty for legacy record formats)
295    ///
296    /// # Returns
297    ///
298    /// This builder.
299    pub fn set_leader_epoch(mut self, leader_epoch: Option<i32>) -> Self {
300        self.leader_epoch = leader_epoch;
301        self
302    }
303    /// Sets `ConsumerRecordOptions::delivery_count`.
304    ///
305    /// # Arguments
306    ///
307    /// - `delivery_count` - Optional delivery count of the record (may be empty when deliveries not counted)
308    ///
309    /// # Returns
310    ///
311    /// This builder.
312    pub fn set_delivery_count(mut self, delivery_count: Option<i16>) -> Self {
313        self.delivery_count = delivery_count;
314        self
315    }
316
317    /// Returns the built options.
318    ///
319    /// # Errors
320    ///
321    /// - `Error::is_local_illegal_argument_error` naming the first of `topic`,
322    ///   `partition`, `offset`, `key` and `value` that was not set.
323    // The mandatory parameters are validated here rather than being named in
324    // the constructor, so a later Java version that makes one of them optional
325    // changes the set this accepts instead of adding a second constructor.
326    pub fn build(self) -> Result<ConsumerRecordOptions<K, V>, Error> {
327        Ok(ConsumerRecordOptions {
328            topic: self.topic.ok_or_else(|| Self::missing("topic"))?,
329            partition: self.partition.ok_or_else(|| Self::missing("partition"))?,
330            offset: self.offset.ok_or_else(|| Self::missing("offset"))?,
331            timestamp: self.timestamp,
332            timestamp_type: self.timestamp_type,
333            serialized_key_size: self.serialized_key_size,
334            serialized_value_size: self.serialized_value_size,
335            key: self.key.ok_or_else(|| Self::missing("key"))?,
336            value: self.value.ok_or_else(|| Self::missing("value"))?,
337            headers: self.headers,
338            leader_epoch: self.leader_epoch,
339            delivery_count: self.delivery_count,
340        })
341    }
342
343    /// Builds the error naming a mandatory parameter
344    /// [`Self::build`] found unset.
345    fn missing(parameter: &str) -> Error {
346        Error::local_illegal_argument(format!(
347            "ConsumerRecordOptionsBuilder::build: mandatory parameter `{parameter}` was not set"
348        ))
349    }
350}
351
352impl<K, V> ConsumerRecord<K, V> {
353    /// Sentinel value indicating no timestamp is associated with a record.
354    // Java's `RecordBatch.NO_TIMESTAMP`, referenced via `ConsumerRecord.NO_TIMESTAMP`.
355    pub const NO_TIMESTAMP: i64 = -1;
356
357    /// Sentinel value used for `serialized_key_size` / `serialized_value_size`
358    /// when the key/value is `None`.
359    pub const NULL_SIZE: i32 = -1;
360
361    /// Creates a record to be received from a specified topic and partition
362    /// (provided for compatibility with Kafka 0.9 before the message format
363    /// supported timestamps and before serialized metadata were exposed).
364    ///
365    /// # Arguments
366    ///
367    /// - `topic` - The topic this record is received from
368    /// - `partition` - The partition of the topic this record is received from
369    /// - `offset` - The offset of this record in the corresponding Kafka partition
370    /// - `key` - The key of the record, if one exists (`None` is allowed)
371    /// - `value` - The record contents
372    ///
373    /// # Returns
374    ///
375    /// The new `ConsumerRecord`.
376    // `{topic, partition, offset, key, value}` is the intersection across the
377    // three constructors, so this one owns the plain name (CLAUDE.md §2).
378    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#ConsumerRecord")]
379    pub fn new(topic: impl Into<Arc<str>>, partition: i32, offset: i64, key: Option<K>, value: Option<V>) -> Self {
380        Self::with_options(
381            ConsumerRecordOptionsBuilder::new()
382                .set_topic(topic)
383                .set_partition(partition)
384                .set_offset(offset)
385                .set_key(key)
386                .set_value(value)
387                .build()
388                .expect("ConsumerRecordOptionsBuilder::build: every mandatory parameter is set above"),
389        )
390    }
391
392    /// Creates a record to be received from a specified topic and partition.
393    ///
394    /// # Arguments
395    ///
396    /// - `options` - The topic, partition, offset, timestamp, timestamp type,
397    ///   serialized key and value sizes, key, value, headers, leader epoch and
398    ///   delivery count of the record
399    ///
400    /// # Returns
401    ///
402    /// The new `ConsumerRecord`.
403    // Java's 11-arg constructor (without `deliveryCount`) is not a separate Rust
404    // method: its body is this one with `deliveryCount = Optional.empty()`, and
405    // both derive the same name `with_options`. Callers get it by leaving
406    // `delivery_count` unset.
407    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#ConsumerRecord")]
408    pub fn with_options(options: ConsumerRecordOptions<K, V>) -> Self {
409        // Java validates `topic != null` and `headers != null`; both are
410        // type-system invariants in Rust (Arc<str> and RecordHeaders).
411        let ConsumerRecordOptions {
412            topic,
413            partition,
414            offset,
415            timestamp,
416            timestamp_type,
417            serialized_key_size,
418            serialized_value_size,
419            key,
420            value,
421            headers,
422            leader_epoch,
423            delivery_count,
424        } = options;
425        Self {
426            topic,
427            partition,
428            offset,
429            timestamp,
430            timestamp_type,
431            serialized_key_size,
432            serialized_value_size,
433            headers,
434            key,
435            value,
436            leader_epoch,
437            delivery_count,
438        }
439    }
440
441    /// Returns the topic this record is received from.
442    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#topic")]
443    pub fn topic(&self) -> &str {
444        &self.topic
445    }
446
447    /// Returns the partition from which this record is received.
448    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#partition")]
449    pub fn partition(&self) -> i32 {
450        self.partition
451    }
452
453    /// Returns the position of this record in the corresponding Kafka partition.
454    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#offset")]
455    pub fn offset(&self) -> i64 {
456        self.offset
457    }
458
459    /// Returns the timestamp of this record, in milliseconds elapsed since unix
460    /// epoch.
461    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#timestamp")]
462    pub fn timestamp(&self) -> i64 {
463        self.timestamp
464    }
465
466    /// Returns the timestamp type of this record.
467    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#timestampType")]
468    pub fn timestamp_type(&self) -> TimestampType {
469        self.timestamp_type
470    }
471
472    /// Returns the size of the serialized, uncompressed key in bytes. If key is
473    /// `None`, the returned size is -1.
474    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#serializedKeySize")]
475    pub fn serialized_key_size(&self) -> i32 {
476        self.serialized_key_size
477    }
478
479    /// Returns the size of the serialized, uncompressed value in bytes. If value
480    /// is `None`, the returned size is -1.
481    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#serializedValueSize")]
482    pub fn serialized_value_size(&self) -> i32 {
483        self.serialized_value_size
484    }
485
486    /// Returns the key (or `None` if no key is specified).
487    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#key")]
488    pub fn key(&self) -> Option<&K> {
489        self.key.as_ref()
490    }
491
492    /// Returns the value.
493    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#value")]
494    pub fn value(&self) -> Option<&V> {
495        self.value.as_ref()
496    }
497
498    /// Returns the headers.
499    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#headers")]
500    pub fn headers(&self) -> &RecordHeaders {
501        &self.headers
502    }
503
504    /// Get the leader epoch for the record if available.
505    ///
506    /// # Returns
507    ///
508    /// the leader epoch or empty for legacy record formats
509    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#leaderEpoch")]
510    pub fn leader_epoch(&self) -> Option<i32> {
511        self.leader_epoch
512    }
513
514    /// Get the delivery count for the record if available.
515    ///
516    /// Deliveries are counted for records delivered by share groups.
517    ///
518    /// # Returns
519    ///
520    /// the delivery count or empty when deliveries not counted
521    #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerRecord#deliveryCount")]
522    pub fn delivery_count(&self) -> Option<i16> {
523        self.delivery_count
524    }
525}
526
527impl<K, V> fmt::Debug for ConsumerRecord<K, V>
528where
529    K: fmt::Debug,
530    V: fmt::Debug,
531{
532    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
533        f.debug_struct("ConsumerRecord")
534            .field("topic", &&*self.topic)
535            .field("partition", &self.partition)
536            .field("offset", &self.offset)
537            .field("timestamp", &self.timestamp)
538            .field("timestamp_type", &self.timestamp_type)
539            .field("serialized_key_size", &self.serialized_key_size)
540            .field("serialized_value_size", &self.serialized_value_size)
541            .field("headers", &self.headers)
542            .field("key", &self.key)
543            .field("value", &self.value)
544            .field("leader_epoch", &self.leader_epoch)
545            .field("delivery_count", &self.delivery_count)
546            .finish()
547    }
548}
549
550impl<K, V> fmt::Display for ConsumerRecord<K, V>
551where
552    K: fmt::Debug,
553    V: fmt::Debug,
554{
555    // Matches Java's `toString()`:
556    //
557    // ```text
558    // ConsumerRecord(topic = T, partition = P, leaderEpoch = E, offset = O, TS_TYPE = TS,
559    //   deliveryCount = D, serialized key size = SKS, serialized value size = SVS,
560    //   headers = H, key = K, value = V)
561    // ```
562    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
563        let leader_epoch_str = match self.leader_epoch {
564            Some(e) => e.to_string(),
565            None => "null".to_string(),
566        };
567        let delivery_count_str = match self.delivery_count {
568            Some(d) => d.to_string(),
569            None => "null".to_string(),
570        };
571        let key_str = match &self.key {
572            Some(k) => format!("{:?}", k),
573            None => "null".to_string(),
574        };
575        let value_str = match &self.value {
576            Some(v) => format!("{:?}", v),
577            None => "null".to_string(),
578        };
579        write!(
580            f,
581            "ConsumerRecord(topic = {}, partition = {}, leaderEpoch = {}, offset = {}, {} = {}, deliveryCount = {}, serialized key size = {}, serialized value size = {}, headers = {}, key = {}, value = {})",
582            self.topic,
583            self.partition,
584            leader_epoch_str,
585            self.offset,
586            self.timestamp_type,
587            self.timestamp,
588            delivery_count_str,
589            self.serialized_key_size,
590            self.serialized_value_size,
591            self.headers,
592            key_str,
593            value_str
594        )
595    }
596}
597
598#[cfg(test)]
599mod tests {
600    use super::*;
601
602    /// CLAUDE.md §2: the mandatory parameters are validated in
603    /// [`ConsumerRecordOptionsBuilder::build`], not named in the constructor, so a
604    /// builder left untouched panics naming the first one it finds unset.
605    #[test]
606    fn consumer_record_options_builder_build_errors_when_no_mandatory_parameter_is_set() {
607        let Err(error) = ConsumerRecordOptionsBuilder::<i32, i32>::new().build() else {
608            panic!("build must reject the unset mandatory parameter");
609        };
610        assert!(matches!(error, Error::LocalIllegalArgument(_)), "{error:?}");
611        assert_eq!(
612            error.message(),
613            "ConsumerRecordOptionsBuilder::build: mandatory parameter `topic` was not set"
614        );
615    }
616}