Skip to main content

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}