confluent_kafka/producer/producer_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 to be sent to Kafka.
16//!
17//! Translated from `org.apache.kafka.clients.producer.ProducerRecord`.
18
19use crate::common::Error;
20use std::fmt;
21use std::hash::{Hash, Hasher};
22
23use crate::common::LocalIllegalArgumentError;
24use crate::common::header::RecordHeaders;
25
26/// A key/value pair to be sent to Kafka. This consists of a topic name to which the record
27/// is being sent, an optional partition number, and an optional key and value.
28///
29/// If a valid partition number is specified that partition will be used when sending the
30/// record. If no partition is specified but a key is present a partition will be chosen
31/// using a hash of the key. If neither key nor partition is present a partition will be
32/// assigned in a round-robin fashion. Note that partition numbers are 0-indexed.
33///
34/// The record also has an associated timestamp. If the user did not provide a timestamp,
35/// the producer will stamp the record with its current time. The timestamp eventually
36/// used by Kafka depends on the timestamp type configured for the topic.
37///
38/// - If the topic is configured to use `CreateTime`, the timestamp in the producer record
39/// will be used by the broker.
40/// - If the topic is configured to use `LogAppendTime`, the timestamp in the producer
41/// record will be overwritten by the broker with the broker local time when it appends
42/// the message to its log.
43///
44/// In either case, the timestamp that has actually been used will be returned to the user
45/// in [`RecordMetadata`](super::RecordMetadata).
46#[derive(Clone, Debug)]
47#[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord")]
48pub struct ProducerRecord<K, V> {
49 topic: String,
50 partition: Option<i32>,
51 headers: RecordHeaders,
52 key: Option<K>,
53 value: Option<V>,
54 timestamp: Option<i64>,
55}
56
57/// The parameters of Java's widest `ProducerRecord` constructor
58/// (`ProducerRecord(String, Integer, Long, K, V, Iterable<Header>)`,
59/// `ProducerRecord#ProducerRecord`).
60///
61/// This struct has **no Java counterpart**. It exists because a method taking
62/// more than three parameters beyond the overload group's intersection takes a
63/// single options struct instead: that constructor
64/// differs from the group's intersection `{topic, value}` by four parameters
65/// — `partition`, `timestamp`, `key`, `headers` — so this
66/// struct becomes the method's *only* parameter, carrying every Java
67/// parameter including the intersection's own.
68///
69/// It deliberately has **no** `Default`. `topic` and `value` are what even
70/// Java's narrowest constructor (`ProducerRecord#ProducerRecord(String,Object)`) takes from its caller, so neither has
71/// a Java-derived default — and a synthesised empty topic would silently send
72/// the record nowhere. Construct it with [`ProducerRecordOptionsBuilder::new`]
73/// and set them: [`ProducerRecordOptionsBuilder::build`] returns an error if any of `topic`, `value` was not set.
74#[non_exhaustive]
75#[derive(Debug, Clone)]
76// the options of ProducerRecord's constructor overloads (CLAUDE.md §2)
77#[doc(alias = "rust-only")]
78pub struct ProducerRecordOptions<K, V> {
79 /// The topic the record will be appended to. Java's `topic`.
80 pub(crate) topic: String,
81 /// The partition to which the record should be sent. Java's `partition`.
82 /// Starts as `None`, as in `ProducerRecord(topic, value)`.
83 pub(crate) partition: Option<i32>,
84 /// The timestamp of the record, in milliseconds since epoch. If `None`,
85 /// the producer will assign the timestamp using the system clock. Java's
86 /// `timestamp`; starts as `None`, as in `ProducerRecord(topic, value)`.
87 pub(crate) timestamp: Option<i64>,
88 /// The key that will be included in the record. Java's `key`. Starts as
89 /// `None`, as in `ProducerRecord(topic, value)`.
90 pub(crate) key: Option<K>,
91 /// The record contents. Java's `value`.
92 pub(crate) value: Option<V>,
93 /// The headers that will be included in the record. Java's `headers`.
94 /// Starts as `None`, as in `ProducerRecord(topic, value)`.
95 pub(crate) headers: Option<RecordHeaders>,
96}
97
98/// Fluent builder for [`ProducerRecordOptions`].
99///
100/// [`Self::new`] takes no parameters, every parameter has a fluent setter, and
101/// [`Self::build`] validates the mandatory ones — returning
102/// [`Error::LocalIllegalArgument`] if they were not set. Like
103/// [`ProducerRecordOptions`] it has no Java counterpart.
104#[derive(Debug)]
105// builds ProducerRecordOptions (CLAUDE.md §2)
106#[doc(alias = "rust-only")]
107pub struct ProducerRecordOptionsBuilder<K, V> {
108 topic: Option<String>,
109 partition: Option<i32>,
110 timestamp: Option<i64>,
111 key: Option<K>,
112 value: Option<Option<V>>,
113 headers: Option<RecordHeaders>,
114}
115
116impl<K, V> Default for ProducerRecordOptionsBuilder<K, V> {
117 fn default() -> Self {
118 Self::new()
119 }
120}
121
122impl<K, V> ProducerRecordOptionsBuilder<K, V> {
123 /// Creates a builder with every mandatory parameter unset and every other
124 /// parameter at the value Java passes on the caller's behalf.
125 pub fn new() -> Self {
126 Self {
127 topic: None,
128 partition: None,
129 timestamp: None,
130 key: None,
131 value: None,
132 headers: None,
133 }
134 }
135
136 /// Sets `ProducerRecordOptions::topic`, a mandatory parameter: [`Self::build`]
137 /// returns an error if it was not set.
138 ///
139 /// # Arguments
140 ///
141 /// - `topic` - the topic the record will be appended to
142 ///
143 /// # Returns
144 ///
145 /// This builder.
146 pub fn set_topic(mut self, topic: String) -> Self {
147 self.topic = Some(topic);
148 self
149 }
150 /// Sets `ProducerRecordOptions::partition`.
151 ///
152 /// # Arguments
153 ///
154 /// - `partition` - the partition to which the record should be sent
155 ///
156 /// # Returns
157 ///
158 /// This builder.
159 pub fn set_partition(mut self, partition: Option<i32>) -> Self {
160 self.partition = partition;
161 self
162 }
163 /// Sets `ProducerRecordOptions::timestamp`.
164 ///
165 /// # Arguments
166 ///
167 /// - `timestamp` - the timestamp of the record, in milliseconds since epoch
168 ///
169 /// # Returns
170 ///
171 /// This builder.
172 pub fn set_timestamp(mut self, timestamp: Option<i64>) -> Self {
173 self.timestamp = timestamp;
174 self
175 }
176 /// Sets `ProducerRecordOptions::key`.
177 ///
178 /// # Arguments
179 ///
180 /// - `key` - the key that will be included in the record
181 ///
182 /// # Returns
183 ///
184 /// This builder.
185 pub fn set_key(mut self, key: Option<K>) -> Self {
186 self.key = key;
187 self
188 }
189 /// Sets `ProducerRecordOptions::value`, a mandatory parameter: [`Self::build`]
190 /// returns an error if it was not set.
191 ///
192 /// # Arguments
193 ///
194 /// - `value` - the record contents
195 ///
196 /// # Returns
197 ///
198 /// This builder.
199 pub fn set_value(mut self, value: Option<V>) -> Self {
200 self.value = Some(value);
201 self
202 }
203 /// Sets `ProducerRecordOptions::headers`.
204 ///
205 /// # Arguments
206 ///
207 /// - `headers` - the headers that will be included in the record
208 ///
209 /// # Returns
210 ///
211 /// This builder.
212 pub fn set_headers(mut self, headers: Option<RecordHeaders>) -> Self {
213 self.headers = headers;
214 self
215 }
216
217 /// Returns the built options.
218 ///
219 /// The mandatory parameters are validated here rather than
220 /// being named in the constructor, so a later Java version that makes one of
221 /// them optional changes the set this accepts instead of adding a second
222 /// constructor. Today there is one mandatory set: `topic`, `value`.
223 ///
224 /// # Errors
225 ///
226 /// - `Error::is_local_illegal_argument_error`, naming the first parameter
227 /// of that set which was not given a setter call. Only presence is
228 /// checked here; semantic validation belongs to the method the options
229 /// are passed to.
230 pub fn build(self) -> Result<ProducerRecordOptions<K, V>, Error> {
231 Ok(ProducerRecordOptions {
232 topic: self.topic.ok_or_else(|| Self::missing("topic"))?,
233 partition: self.partition,
234 timestamp: self.timestamp,
235 key: self.key,
236 value: self.value.ok_or_else(|| Self::missing("value"))?,
237 headers: self.headers,
238 })
239 }
240
241 /// Builds the [`Error::LocalIllegalArgument`] naming a mandatory parameter
242 /// [`Self::build`] found unset.
243 fn missing(parameter: &str) -> Error {
244 Error::local_illegal_argument(format!(
245 "ProducerRecordOptionsBuilder::build: mandatory parameter `{parameter}` was not set"
246 ))
247 }
248}
249
250impl<K, V> ProducerRecord<K, V> {
251 /// Creates a record with a specified timestamp to be sent to a specified topic and
252 /// partition
253 ///
254 /// # Arguments
255 ///
256 /// - `options` - The topic the record will be appended to, the partition
257 /// to which the record should be sent, the timestamp of the record in
258 /// milliseconds since epoch (if `None`, the producer will assign the
259 /// timestamp using the system clock), the key and the headers that will
260 /// be included in the record, and the record contents
261 ///
262 /// # Errors
263 ///
264 /// - `LocalIllegalArgumentError` if the timestamp or the partition is
265 /// negative.
266 ///
267 /// # Translation notes
268 ///
269 /// Java's `ProducerRecord(String, Integer, Long, K, V, Iterable<Header>)`:
270 /// its six parameters are the fields of [`ProducerRecordOptions`].
271 // Six parameters exceed CLAUDE.md §2's three-parameter cap on derived
272 // overload names, so `ProducerRecordOptions` is this method's only
273 // parameter.
274 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
275 pub fn with_options(options: ProducerRecordOptions<K, V>) -> Result<Self, LocalIllegalArgumentError> {
276 let ProducerRecordOptions { topic, partition, timestamp, key, value, headers } = options;
277 if let Some(ts) = timestamp
278 && ts < 0
279 {
280 return Err(LocalIllegalArgumentError::new(format!(
281 "Invalid timestamp: {ts}. Timestamp should always be non-negative or null."
282 )));
283 }
284 if let Some(p) = partition
285 && p < 0
286 {
287 return Err(LocalIllegalArgumentError::new(format!(
288 "Invalid partition: {p}. Partition number should always be non-negative or null."
289 )));
290 }
291 Ok(Self { topic, partition, key, value, timestamp, headers: headers.unwrap_or_default() })
292 }
293
294 /// Creates a record with a specified timestamp to be sent to a specified topic and
295 /// partition
296 ///
297 /// # Arguments
298 ///
299 /// - `topic` - The topic the record will be appended to
300 /// - `partition` - The partition to which the record should be sent
301 /// - `timestamp` - The timestamp of the record, in milliseconds since epoch. If None, the
302 /// producer will assign the timestamp using System.currentTimeMillis().
303 /// - `key` - The key that will be included in the record
304 /// - `value` - The record contents
305 ///
306 /// # Errors
307 ///
308 /// - `LocalIllegalArgumentError` if the timestamp or the partition is
309 /// negative.
310 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
311 pub fn with_partition_timestamp_key(
312 topic: String,
313 partition: Option<i32>,
314 timestamp: Option<i64>,
315 key: Option<K>,
316 value: Option<V>,
317 ) -> Result<Self, LocalIllegalArgumentError> {
318 Self::with_options(
319 ProducerRecordOptionsBuilder::new()
320 .set_topic(topic)
321 .set_value(value)
322 .set_partition(partition)
323 .set_timestamp(timestamp)
324 .set_key(key)
325 .build()
326 .expect("ProducerRecordOptionsBuilder::build: every mandatory parameter is set above"),
327 )
328 }
329
330 /// Creates a record to be sent to a specified topic and partition
331 ///
332 /// # Arguments
333 ///
334 /// - `topic` - The topic the record will be appended to
335 /// - `partition` - The partition to which the record should be sent
336 /// - `key` - The key that will be included in the record
337 /// - `value` - The record contents
338 /// - `headers` - The headers that will be included in the record
339 ///
340 /// # Errors
341 ///
342 /// - `LocalIllegalArgumentError` if the partition is negative.
343 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
344 pub fn with_partition_key_headers(
345 topic: String,
346 partition: Option<i32>,
347 key: Option<K>,
348 value: Option<V>,
349 headers: RecordHeaders,
350 ) -> Result<Self, LocalIllegalArgumentError> {
351 Self::with_options(
352 ProducerRecordOptionsBuilder::new()
353 .set_topic(topic)
354 .set_value(value)
355 .set_partition(partition)
356 .set_key(key)
357 .set_headers(Some(headers))
358 .build()
359 .expect("ProducerRecordOptionsBuilder::build: every mandatory parameter is set above"),
360 )
361 }
362
363 /// Creates a record to be sent to a specified topic and partition
364 ///
365 /// # Arguments
366 ///
367 /// - `topic` - The topic the record will be appended to
368 /// - `partition` - The partition to which the record should be sent
369 /// - `key` - The key that will be included in the record
370 /// - `value` - The record contents
371 ///
372 /// # Errors
373 ///
374 /// - `LocalIllegalArgumentError` if the partition is negative.
375 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
376 pub fn with_partition_key(
377 topic: String,
378 partition: Option<i32>,
379 key: Option<K>,
380 value: Option<V>,
381 ) -> Result<Self, LocalIllegalArgumentError> {
382 Self::with_options(
383 ProducerRecordOptionsBuilder::new()
384 .set_topic(topic)
385 .set_value(value)
386 .set_partition(partition)
387 .set_key(key)
388 .build()
389 .expect("ProducerRecordOptionsBuilder::build: every mandatory parameter is set above"),
390 )
391 }
392
393 /// Create a record to be sent to Kafka
394 ///
395 /// # Arguments
396 ///
397 /// - `topic` - The topic the record will be appended to
398 /// - `key` - The key that will be included in the record
399 /// - `value` - The record contents
400 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
401 pub fn with_key(topic: String, key: Option<K>, value: Option<V>) -> Self {
402 // Cannot fail: no partition, no timestamp to validate
403 Self::with_options(
404 ProducerRecordOptionsBuilder::new()
405 .set_topic(topic)
406 .set_value(value)
407 .set_key(key)
408 .build()
409 .expect("ProducerRecordOptionsBuilder::build: every mandatory parameter is set above"),
410 )
411 .unwrap()
412 }
413
414 /// Create a record with no key
415 ///
416 /// # Arguments
417 ///
418 /// - `topic` - The topic this record should be sent to
419 /// - `value` - The record contents
420 // Java's `ProducerRecord(String, V)`, whose parameters `{topic, value}` are
421 // the intersection across the six constructors, so it owns the plain name
422 // (CLAUDE.md §2).
423 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#ProducerRecord")]
424 pub fn new(topic: String, value: Option<V>) -> Self {
425 // Cannot fail: no partition, no timestamp to validate
426 Self::with_options(
427 ProducerRecordOptionsBuilder::new()
428 .set_topic(topic)
429 .set_value(value)
430 .build()
431 .expect("ProducerRecordOptionsBuilder::build: every mandatory parameter is set above"),
432 )
433 .unwrap()
434 }
435
436 /// Returns the topic this record is being sent to.
437 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#topic")]
438 pub fn topic(&self) -> &str {
439 &self.topic
440 }
441
442 /// Returns the headers.
443 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#headers")]
444 pub fn headers(&self) -> &RecordHeaders {
445 &self.headers
446 }
447
448 /// Returns a mutable reference to the headers: Java's `headers()` is
449 /// mutable, and a serializer may add to it.
450 pub(crate) fn headers_mut(&mut self) -> &mut RecordHeaders {
451 &mut self.headers
452 }
453
454 /// Returns the key (or `None` if no key is specified).
455 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#key")]
456 pub fn key(&self) -> Option<&K> {
457 self.key.as_ref()
458 }
459
460 /// Returns the value.
461 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#value")]
462 pub fn value(&self) -> Option<&V> {
463 self.value.as_ref()
464 }
465
466 /// Returns the timestamp, which is in milliseconds since epoch.
467 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#timestamp")]
468 pub fn timestamp(&self) -> Option<i64> {
469 self.timestamp
470 }
471
472 /// Returns the partition to which the record will be sent (or `None` if no partition
473 /// was specified).
474 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecord#partition")]
475 pub fn partition(&self) -> Option<i32> {
476 self.partition
477 }
478
479 /// Consume this record and return its parts, moving the fields out
480 /// without copying them (CLAUDE.md §14). Crate-private: a fixed tuple would
481 /// have to change shape whenever Java adds a field to `ProducerRecord`.
482 pub(crate) fn into_parts(self) -> (String, Option<i32>, Option<i64>, RecordHeaders, Option<K>, Option<V>) {
483 (self.topic, self.partition, self.timestamp, self.headers, self.key, self.value)
484 }
485}
486
487impl<K: PartialEq, V: PartialEq> PartialEq for ProducerRecord<K, V> {
488 fn eq(&self, other: &Self) -> bool {
489 self.key == other.key
490 && self.partition == other.partition
491 && self.topic == other.topic
492 && self.headers == other.headers
493 && self.value == other.value
494 && self.timestamp == other.timestamp
495 }
496}
497
498impl<K: Eq, V: Eq> Eq for ProducerRecord<K, V> {}
499
500impl<K: Hash, V: Hash> Hash for ProducerRecord<K, V> {
501 fn hash<H: Hasher>(&self, state: &mut H) {
502 self.topic.hash(state);
503 self.partition.hash(state);
504 self.headers.hash(state);
505 self.key.hash(state);
506 self.value.hash(state);
507 self.timestamp.hash(state);
508 }
509}
510
511impl<K: fmt::Debug, V: fmt::Debug> fmt::Display for ProducerRecord<K, V> {
512 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
513 let headers = format!("{}", self.headers);
514 let key = match &self.key {
515 Some(k) => format!("{:?}", k),
516 None => "null".to_string(),
517 };
518 let value = match &self.value {
519 Some(v) => format!("{:?}", v),
520 None => "null".to_string(),
521 };
522 let timestamp = match self.timestamp {
523 Some(ts) => ts.to_string(),
524 None => "null".to_string(),
525 };
526 write!(
527 f,
528 "ProducerRecord(topic={}, partition={:?}, headers={}, key={}, value={}, timestamp={})",
529 self.topic, self.partition, headers, key, value, timestamp
530 )
531 }
532}
533
534#[cfg(test)]
535mod tests {
536 use super::*;
537
538 /// Translated from `ProducerRecordTest.testEqualsAndHashCode`.
539 #[test]
540 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecordTest#testEqualsAndHashCode")]
541 fn test_equals_and_hash_code() {
542 let producer_record =
543 ProducerRecord::with_partition_key("test".to_string(), Some(1), Some("key".to_string()), Some(1)).unwrap();
544 assert_eq!(producer_record, producer_record.clone());
545
546 let equal_record =
547 ProducerRecord::with_partition_key("test".to_string(), Some(1), Some("key".to_string()), Some(1)).unwrap();
548 assert_eq!(producer_record, equal_record);
549 assert_eq!(hash_of(&producer_record), hash_of(&equal_record));
550
551 let topic_mismatch =
552 ProducerRecord::with_partition_key("test-1".to_string(), Some(1), Some("key".to_string()), Some(1))
553 .unwrap();
554 assert_ne!(producer_record, topic_mismatch);
555
556 let partition_mismatch =
557 ProducerRecord::with_partition_key("test".to_string(), Some(2), Some("key".to_string()), Some(1)).unwrap();
558 assert_ne!(producer_record, partition_mismatch);
559
560 let key_mismatch =
561 ProducerRecord::with_partition_key("test".to_string(), Some(1), Some("key-1".to_string()), Some(1))
562 .unwrap();
563 assert_ne!(producer_record, key_mismatch);
564
565 let value_mismatch =
566 ProducerRecord::with_partition_key("test".to_string(), Some(1), Some("key".to_string()), Some(2)).unwrap();
567 assert_ne!(producer_record, value_mismatch);
568
569 let null_fields_record: ProducerRecord<String, String> = ProducerRecord::with_options(
570 ProducerRecordOptionsBuilder::new()
571 .set_topic("topic".to_string())
572 .set_value(None)
573 .build()
574 .unwrap(),
575 )
576 .unwrap();
577 assert_eq!(null_fields_record, null_fields_record.clone());
578 assert_eq!(hash_of(&null_fields_record), hash_of(&null_fields_record));
579 }
580
581 /// Translated from `ProducerRecordTest.testInvalidRecords`.
582 #[test]
583 #[doc(alias = "org.apache.kafka.clients.producer.ProducerRecordTest#testInvalidRecords")]
584 fn test_invalid_records() {
585 // Negative timestamp
586 let result = ProducerRecord::with_partition_timestamp_key(
587 "test".to_string(),
588 Some(0),
589 Some(-1),
590 Some("key".to_string()),
591 Some(1),
592 );
593 assert!(result.is_err(), "Expected error because of negative timestamp");
594
595 // Negative partition
596 let result = ProducerRecord::with_partition_key("test".to_string(), Some(-1), Some("key".to_string()), Some(1));
597 assert!(result.is_err(), "Expected error because of negative partition");
598 }
599
600 fn hash_of<T: Hash>(value: &T) -> u64 {
601 use std::hash::DefaultHasher;
602 let mut hasher = DefaultHasher::new();
603 value.hash(&mut hasher);
604 hasher.finish()
605 }
606
607 /// CLAUDE.md §2: the mandatory parameters are validated in
608 /// [`ProducerRecordOptionsBuilder::build`], not named in the constructor, so a
609 /// builder left untouched panics naming the first one it finds unset.
610 #[test]
611 fn producer_record_options_builder_build_errors_when_no_mandatory_parameter_is_set() {
612 let Err(error) = ProducerRecordOptionsBuilder::<String, String>::new().build() else {
613 panic!("build must reject the unset mandatory parameter");
614 };
615 assert!(matches!(error, Error::LocalIllegalArgument(_)), "{error:?}");
616 assert_eq!(
617 error.message(),
618 "ProducerRecordOptionsBuilder::build: mandatory parameter `topic` was not set"
619 );
620 }
621
622 /// Validation covers every mandatory parameter, not just the first: setting
623 /// all but one still panics, naming the one left unset.
624 #[test]
625 fn producer_record_options_builder_build_errors_when_only_value_is_unset() {
626 let Err(error) = ProducerRecordOptionsBuilder::<String, String>::new()
627 .set_topic("topic".to_string())
628 .build()
629 else {
630 panic!("build must reject the unset mandatory parameter");
631 };
632 assert!(matches!(error, Error::LocalIllegalArgument(_)), "{error:?}");
633 assert_eq!(
634 error.message(),
635 "ProducerRecordOptionsBuilder::build: mandatory parameter `value` was not set"
636 );
637 }
638}