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}