confluent_kafka/common/serialization/bytes_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//! Zero-copy byte-buffer deserializer.
16//!
17//! Returns each record's key/value as a refcounted [`bytes::Bytes`] slice of
18//! the buffer that owns the record's bytes rather than an owned `Vec<u8>`
19//! copy.
20
21use bytes::Bytes;
22
23use crate::common::Error;
24use crate::common::header::RecordHeaders;
25use crate::common::serialization::Deserializer;
26
27/// Deserializes byte arrays into refcounted [`bytes::Bytes`].
28///
29/// This is the zero-copy counterpart to
30/// [`ByteArrayDeserializer`](crate::common::serialization::ByteArrayDeserializer):
31/// where the latter must copy the borrowed `&[u8]` into an owned `Vec<u8>`,
32/// `BytesDeserializer` returns the record's key/value as the consumer hands it
33/// to [`deserialize_with_headers_bytes`](Deserializer::deserialize_with_headers_bytes):
34/// a refcounted slice of the buffer that owns the record's bytes
35/// (consumer-threading.md §27) — the fetched records buffer for an uncompressed
36/// batch, the buffer the record was decompressed into for a compressed one. No
37/// per-record key/value copy occurs on the receive path.
38///
39/// The plain [`deserialize`](Deserializer::deserialize) entry point (used when
40/// no shared buffer is available, e.g. unit tests) still copies via
41/// [`Bytes::copy_from_slice`], matching the §27 "safe copy fallback" contract.
42#[derive(Clone, Debug, Default)]
43#[non_exhaustive]
44#[doc(alias = "org.apache.kafka.common.serialization.BytesDeserializer")]
45pub struct BytesDeserializer;
46
47impl BytesDeserializer {
48 /// Create a new `BytesDeserializer`.
49 #[doc(alias = "org.apache.kafka.common.serialization.BytesDeserializer#BytesDeserializer")]
50 pub fn new() -> Self {
51 Self
52 }
53}
54
55impl Deserializer<Bytes> for BytesDeserializer {
56 async fn deserialize(&self, _topic: &str, data: &[u8]) -> Result<Bytes, Error> {
57 // Fallback path: no shared owning buffer available, so copy.
58 Ok(Bytes::copy_from_slice(data))
59 }
60
61 async fn deserialize_with_headers_bytes(
62 &self,
63 _topic: &str,
64 _headers: &mut RecordHeaders,
65 data: &Bytes,
66 ) -> Result<Bytes, Error> {
67 // Zero-copy: `data` is already a refcounted slice of the buffer that
68 // owns the record's bytes, so handing out a clone bumps a refcount and
69 // copies nothing. Bytes semantics ignore headers.
70 Ok(data.clone())
71 }
72}
73
74#[cfg(test)]
75mod tests {
76 use super::*;
77
78 #[tokio::test]
79 async fn test_deserialize_copy_fallback() {
80 let de = BytesDeserializer::new();
81 let data = b"my bytes";
82 let result = de.deserialize("topic", data.as_slice()).await.unwrap();
83 assert_eq!(&result[..], b"my bytes");
84 assert_ne!(
85 result.as_ptr(),
86 data.as_ptr(),
87 "the plain form has no shared buffer to slice, so it copies"
88 );
89 }
90
91 #[tokio::test]
92 async fn test_deserialize_empty() {
93 let de = BytesDeserializer::new();
94 let result = de.deserialize("topic", &[]).await.unwrap();
95 assert!(result.is_empty());
96 }
97
98 #[tokio::test]
99 async fn test_deserialize_with_headers_bytes_is_zero_copy() {
100 let de = BytesDeserializer::new();
101 let source = Bytes::from(vec![0u8, 1, 2, 3, 4, 5, 6, 7]);
102 // A subslice of the source allocation, as the receive path passes it.
103 let data = source.slice(2..5);
104 let mut headers = RecordHeaders::new();
105 let result = de.deserialize_with_headers_bytes("topic", &mut headers, &data).await.unwrap();
106 assert_eq!(&result[..], &[2, 3, 4]);
107 // The returned Bytes shares the source allocation (same data ptr).
108 assert_eq!(result.as_ptr(), source[2..].as_ptr());
109 }
110}