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}