confluent_kafka/common/serialization/deserializer.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//! Deserialization interface.
16//!
17//! Translated from `org.apache.kafka.common.serialization.Deserializer<T>`.
18
19use std::collections::HashMap;
20
21use bytes::Bytes;
22
23use crate::common::Error;
24use crate::common::header::RecordHeaders;
25
26/// An interface for converting bytes to objects.
27///
28/// This interface can be combined with `ClusterResourceListener` to receive
29/// cluster metadata once it's available, as well as `Monitorable` to enable the
30/// deserializer to register metrics. For the latter, the following tags are
31/// automatically added to all metrics registered: `config` set to either
32/// `key.deserializer` or `value.deserializer`, and `class` set to the
33/// deserializer class name.
34///
35/// # Type Parameters
36///
37/// - `T` - Type to be deserialized into.
38///
39/// # Translation notes
40///
41/// WARNING: combining with `ClusterResourceListener` or `Monitorable` has no effect: no client registers either.
42///
43/// Methods return a `Send` future, which the consumer stores inline: a deserializer
44/// awaiting a large operation only on a cache miss should `Box::pin` it alone.
45///
46/// A `poll()` cancelled mid-record deserializes that record again on the next
47/// `poll()`.
48#[doc(alias = "org.apache.kafka.common.serialization.Deserializer")]
49pub trait Deserializer<T>: Send + Sync + 'static {
50 /// Deserialize a record value from a byte array into a value or object.
51 ///
52 /// # Arguments
53 ///
54 /// - `topic` - topic associated with the data
55 /// - `data` - serialized bytes
56 ///
57 /// # Returns
58 ///
59 /// The deserialized typed object.
60 ///
61 /// # Errors
62 ///
63 /// Whatever error the deserializer reports; the consumer returns it from
64 /// `poll`.
65 ///
66 /// # Translation notes
67 ///
68 /// The consumer skips the call for a null key or value, so `data` and the
69 /// result are never `None`.
70 #[doc(alias = "org.apache.kafka.common.serialization.Deserializer#deserialize")]
71 fn deserialize<'a>(&'a self, topic: &'a str, data: &'a [u8]) -> impl Future<Output = Result<T, Error>> + Send + 'a;
72
73 /// Deserialize a record value from a byte array into a value or object.
74 ///
75 /// Note that the passed in headers may be empty. The implementation is allowed to
76 /// modify the passed in headers, as a side effect of deserialization. It is
77 /// considered best practice to not delete or modify existing headers, but rather
78 /// only add new ones.
79 ///
80 /// # Arguments
81 ///
82 /// - `topic` - topic associated with the data
83 /// - `headers` - headers associated with the record
84 /// - `data` - serialized bytes
85 ///
86 /// # Returns
87 ///
88 /// The deserialized typed object.
89 ///
90 /// # Errors
91 ///
92 /// As [`deserialize`](Deserializer::deserialize).
93 ///
94 /// # Translation notes
95 ///
96 /// The default implementation ignores the headers and delegates to
97 /// [`deserialize`](Deserializer::deserialize). The consumer skips the call for a
98 /// null key or value.
99 // Takes the concrete `RecordHeaders` rather than a `&dyn Headers` trait
100 // object, as `Serializer::serialize_with_headers` does: the client only ever
101 // passes its one implementation, which keeps the two serde traits symmetric
102 // and lets the C binding hand the headers over as a `RecordHeaders_t` handle.
103 #[doc(alias = "org.apache.kafka.common.serialization.Deserializer#deserialize")]
104 fn deserialize_with_headers<'a>(
105 &'a self,
106 topic: &'a str,
107 headers: &'a mut RecordHeaders,
108 data: &'a [u8],
109 ) -> impl Future<Output = Result<T, Error>> + Send + 'a {
110 let _ = headers;
111 self.deserialize(topic, data)
112 }
113
114 /// Deserialize a record value from a [`Bytes`] buffer into a value or object.
115 ///
116 /// If this method is overridden, the implementation cannot make any assumptions
117 /// about the passed in buffer.
118 ///
119 /// Note that the passed in headers may be empty. The implementation is allowed to
120 /// modify the passed in headers, as a side effect of deserialization. It is
121 /// considered best practice to not delete or modify existing headers, but rather
122 /// only add new ones.
123 ///
124 /// # Arguments
125 ///
126 /// - `topic` - topic associated with the data
127 /// - `headers` - headers associated with the record
128 /// - `data` - serialized bytes
129 ///
130 /// # Returns
131 ///
132 /// The deserialized typed object.
133 ///
134 /// # Errors
135 ///
136 /// As [`deserialize`](Deserializer::deserialize).
137 ///
138 /// # Translation notes
139 ///
140 /// The consumer calls this overload. `data` is a refcounted slice of the fetched
141 /// bytes, so a deserializer may keep it without copying. The default delegates to
142 /// [`deserialize_with_headers`](Deserializer::deserialize_with_headers) with
143 /// `&data[..]`, copying nothing. The consumer skips the call for a null key or
144 /// value.
145 #[doc(alias = "org.apache.kafka.common.serialization.Deserializer#deserialize")]
146 fn deserialize_with_headers_bytes<'a>(
147 &'a self,
148 topic: &'a str,
149 headers: &'a mut RecordHeaders,
150 data: &'a Bytes,
151 ) -> impl Future<Output = Result<T, Error>> + Send + 'a {
152 self.deserialize_with_headers(topic, headers, &data[..])
153 }
154
155 /// Configure this class. The default implementation is a no-op.
156 ///
157 /// # Arguments
158 ///
159 /// - `configs` - configs in key/value pairs
160 /// - `is_key` - whether the deserializer is used for the key or the value
161 ///
162 /// # Errors
163 ///
164 /// Whatever error the deserializer reports.
165 #[doc(alias = "org.apache.kafka.common.serialization.Deserializer#configure")]
166 fn configure<'a>(
167 &'a mut self,
168 configs: &'a HashMap<String, String>,
169 is_key: bool,
170 ) -> impl Future<Output = Result<(), Error>> + Send + 'a {
171 // intentionally left blank — Java default
172 let _ = (configs, is_key);
173 async { Ok(()) }
174 }
175
176 /// Close this deserializer.
177 ///
178 /// This method must be idempotent as it may be called multiple times.
179 ///
180 /// # Errors
181 ///
182 /// Whatever error the deserializer reports; the consumer still closes the
183 /// other deserializer, then returns it as the source of its own.
184 // The consumer closes its deserializers as Java's `Utils.closeQuietly` does:
185 // it logs an error (or a caught panic), keeps the first one and closes the
186 // other deserializer; then the consumer's `close` returns `Failed to close
187 // kafka consumer`, caused by `Failed to close deserializers` with the first
188 // error as its source, while a failed constructor only logs it.
189 #[doc(alias = "org.apache.kafka.common.serialization.Deserializer#close")]
190 fn close(&mut self) -> impl Future<Output = Result<(), Error>> + Send {
191 // intentionally left blank — Java default
192 async { Ok(()) }
193 }
194}
195
196#[cfg(test)]
197mod tests {
198 use super::*;
199 use crate::common::header::Headers;
200
201 /// Reports where the slice it was handed starts, and whether it went
202 /// through `deserialize_with_headers`.
203 struct Address;
204
205 impl Deserializer<(usize, bool)> for Address {
206 async fn deserialize(&self, _topic: &str, data: &[u8]) -> Result<(usize, bool), Error> {
207 Ok((data.as_ptr() as usize, false))
208 }
209
210 async fn deserialize_with_headers(
211 &self,
212 _topic: &str,
213 headers: &mut RecordHeaders,
214 data: &[u8],
215 ) -> Result<(usize, bool), Error> {
216 assert!(headers.last_header("k").is_some(), "the headers are forwarded");
217 Ok((data.as_ptr() as usize, true))
218 }
219 }
220
221 #[tokio::test]
222 async fn test_default_bytes_overload_forwards_the_slice_without_copying() {
223 let source = Bytes::from_static(b"hello world");
224 let data = source.slice(6..);
225 let mut headers = RecordHeaders::new();
226 headers.add_with_key_value("k", Some(b"v")).expect("add");
227 let (address, through_headers) =
228 Deserializer::deserialize_with_headers_bytes(&Address, "t", &mut headers, &data)
229 .await
230 .expect("deserialize");
231 assert!(through_headers, "the default forwards to deserialize_with_headers");
232 assert_eq!(
233 data.as_ptr() as usize,
234 address,
235 "the default hands over the buffer itself, not a copy"
236 );
237 }
238}