Skip to main content

confluent_kafka/common/serialization/
mod.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//! Serialization interfaces and implementations (org.apache.kafka.common.serialization).
16//!
17//! Provides the [`Serializer`] and [`Deserializer`] traits and common
18//! implementations for strings and byte arrays.
19
20mod byte_array_deserializer;
21mod byte_array_serializer;
22mod bytes_deserializer;
23mod deserializer;
24mod dyn_deserializer;
25mod dyn_serializer;
26mod inline_future;
27#[cfg(test)]
28mod serialization_test;
29mod string_deserializer;
30mod string_serializer;
31
32pub use byte_array_deserializer::ByteArrayDeserializer;
33pub use byte_array_serializer::ByteArraySerializer;
34pub use bytes_deserializer::BytesDeserializer;
35pub use deserializer::Deserializer;
36// The dyn-compatible companions and the future they return are the crate's own
37// dispatch mechanism: the clients take serdes as `impl Serializer<K>` /
38// `impl Deserializer<K>` and box them once, and never hand a serde out, so no
39// caller needs to name them (`check-dyn-compatible`).
40pub(crate) use dyn_deserializer::DynDeserializer;
41pub(crate) use dyn_serializer::DynSerializer;
42pub(crate) use inline_future::InlineFuture;
43pub use string_deserializer::StringDeserializer;
44pub use string_serializer::StringSerializer;
45
46use std::borrow::Cow;
47use std::collections::HashMap;
48
49use crate::common::Error;
50use crate::common::header::RecordHeaders;
51
52/// An interface for converting objects to bytes.
53///
54/// This interface can be combined with `ClusterResourceListener` to receive
55/// cluster metadata once it's available, as well as `Monitorable` to enable the
56/// serializer to register metrics. For the latter, the following tags are
57/// automatically added to all metrics registered: `config` set to either
58/// `key.serializer` or `value.serializer`, and `class` set to the serializer
59/// class name.
60///
61/// # Type Parameters
62///
63/// - `T` - Type to be serialized from. It may be unsized (`Serializer<str>`).
64///
65/// # Translation notes
66///
67/// WARNING: combining with `ClusterResourceListener` or `Monitorable` has no effect: no client registers either.
68///
69/// Methods return a `Send` future, which the producer stores inline: a serializer
70/// awaiting a large operation only on a cache miss should `Box::pin` it alone.
71#[doc(alias = "org.apache.kafka.common.serialization.Serializer")]
72pub trait Serializer<T: ?Sized>: Send + Sync {
73    /// Convert `data` into a byte array.
74    ///
75    /// It is recommended to serialize `None` data to `None` byte array.
76    ///
77    /// # Arguments
78    ///
79    /// * `topic` - topic associated with data
80    /// * `data` - typed data; may be `None`
81    ///
82    /// # Returns
83    ///
84    /// Serialized bytes, which may borrow from `data`; may be `None`.
85    ///
86    /// # Errors
87    ///
88    /// Whatever error the serializer reports; the producer returns it from
89    /// `send`, or fails the record's future.
90    #[doc(alias = "org.apache.kafka.common.serialization.Serializer#serialize")]
91    fn serialize<'a>(
92        &'a self,
93        topic: &'a str,
94        data: Option<&'a T>,
95    ) -> impl Future<Output = Result<Option<Cow<'a, [u8]>>, Error>> + Send + 'a;
96
97    /// Convert `data` into a byte array, with access to the record headers.
98    ///
99    /// It is recommended to serialize `None` data to `None` byte array.
100    ///
101    /// Note that the passed in headers may be empty. The implementation is allowed
102    /// to modify them, as a side effect of serialization. It is considered best
103    /// practice to not delete or modify existing headers, but rather only add new
104    /// ones.
105    ///
106    /// # Arguments
107    ///
108    /// - `topic` - topic associated with data
109    /// - `headers` - headers associated with the record
110    /// - `data` - typed data; may be `None`
111    ///
112    /// # Returns
113    ///
114    /// Serialized bytes, which may borrow from `data`; may be `None`.
115    ///
116    /// # Errors
117    ///
118    /// As [`serialize`](Serializer::serialize).
119    ///
120    /// # Translation notes
121    ///
122    /// The default implementation ignores the headers and delegates to `serialize`.
123    /// The producer makes the headers read-only once both serializers ran.
124    // The headers are borrowed for `'h`, a lifetime of their own, so the
125    // serialized bytes (which live for `'a`) do not keep them borrowed: the
126    // producer serializes the key, then lends the same headers to the value
127    // serializer while it still holds the key's bytes.
128    #[doc(alias = "org.apache.kafka.common.serialization.Serializer#serialize")]
129    fn serialize_with_headers<'a, 'h>(
130        &'a self,
131        topic: &'a str,
132        headers: &'h mut RecordHeaders,
133        data: Option<&'a T>,
134    ) -> impl Future<Output = Result<Option<Cow<'a, [u8]>>, Error>> + Send + use<'a, 'h, Self, T>
135    where
136        'a: 'h,
137    {
138        let _ = headers;
139        self.serialize(topic, data)
140    }
141
142    /// Configure this class. The default implementation is a no-op.
143    ///
144    /// # Arguments
145    ///
146    /// - `configs` - configs in key/value pairs
147    /// - `is_key` - whether the serializer is used for the key or the value
148    ///
149    /// # Errors
150    ///
151    /// Whatever error the serializer reports.
152    // Declared after the `serialize` methods, as on `Deserializer`, so the C
153    // constructor takes the methods in the same order for both.
154    #[doc(alias = "org.apache.kafka.common.serialization.Serializer#configure")]
155    fn configure<'a>(
156        &'a mut self,
157        configs: &'a HashMap<String, String>,
158        is_key: bool,
159    ) -> impl Future<Output = Result<(), Error>> + Send + 'a {
160        // intentionally left blank — Java default
161        let _ = (configs, is_key);
162        async { Ok(()) }
163    }
164
165    /// Close this serializer.
166    ///
167    /// This method must be idempotent as it may be called multiple times.
168    ///
169    /// # Errors
170    ///
171    /// Whatever error the serializer reports; the producer still closes the
172    /// other serializer, then returns it as the source of its own.
173    // The producer calls it once: from its `close`, after its I/O task has
174    // stopped, or from a constructor that fails, as Java's catch does. It closes
175    // its serializers as Java's `Utils.closeQuietly` does: it logs an error (or a
176    // caught panic), keeps the first one and closes the other serializer; then the
177    // producer's `close` returns `Failed to close kafka producer`, with the first
178    // error as its source, while a failed constructor only logs it. It takes `&self`, unlike
179    // `Deserializer::close`: the producer shares its serializers with every
180    // concurrent `send`, so an exclusive borrow would need a lock on every send.
181    #[doc(alias = "org.apache.kafka.common.serialization.Serializer#close")]
182    fn close(&self) -> impl Future<Output = Result<(), Error>> + Send + '_ {
183        // intentionally left blank — Java default
184        async { Ok(()) }
185    }
186}