Skip to main content

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}