binius_utils/
serialization.rs

1// Copyright 2024-2025 Irreducible Inc.
2
3use auto_impl::auto_impl;
4use bytes::{Buf, BufMut};
5use thiserror::Error;
6
7/// Serialize data according to Mode param
8#[auto_impl(Box, &)]
9pub trait SerializeBytes {
10	fn serialize(
11		&self,
12		write_buf: impl BufMut,
13		mode: SerializationMode,
14	) -> Result<(), SerializationError>;
15}
16
17/// Deserialize data according to Mode param
18pub trait DeserializeBytes {
19	fn deserialize(read_buf: impl Buf, mode: SerializationMode) -> Result<Self, SerializationError>
20	where
21		Self: Sized;
22}
23
24/// Specifies serialization/deserialization behavior
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum SerializationMode {
27	/// This mode is faster, and serializes to the underlying bytes
28	Native,
29	/// Will first convert any tower fields into the Fan-Paar field equivalent
30	CanonicalTower,
31}
32
33#[derive(Error, Debug, Clone)]
34pub enum SerializationError {
35	#[error("Write buffer is full")]
36	WriteBufferFull,
37	#[error("Not enough data in read buffer to deserialize")]
38	NotEnoughBytes,
39	#[error("Unknown enum variant index {name}::{index}")]
40	UnknownEnumVariant { name: &'static str, index: u8 },
41	#[error("Serialization has not been implemented")]
42	SerializationNotImplemented,
43	#[error("Deserializer has not been implemented")]
44	DeserializerNotImplented,
45	#[error("Multiple deserializers with the same name {name} has been registered")]
46	DeserializerNameConflict { name: String },
47	#[error("FromUtf8Error: {0}")]
48	FromUtf8Error(#[from] std::string::FromUtf8Error),
49	#[error("Invalid construction of {name}")]
50	InvalidConstruction { name: &'static str },
51}
52
53// Copyright 2025 Irreducible Inc.
54
55use generic_array::{ArrayLength, GenericArray};
56
57impl<T: DeserializeBytes> DeserializeBytes for Box<T> {
58	fn deserialize(read_buf: impl Buf, mode: SerializationMode) -> Result<Self, SerializationError>
59	where
60		Self: Sized,
61	{
62		Ok(Self::new(T::deserialize(read_buf, mode)?))
63	}
64}
65
66impl SerializeBytes for usize {
67	fn serialize(
68		&self,
69		mut write_buf: impl BufMut,
70		mode: SerializationMode,
71	) -> Result<(), SerializationError> {
72		SerializeBytes::serialize(&(*self as u64), &mut write_buf, mode)
73	}
74}
75
76impl DeserializeBytes for usize {
77	fn deserialize(
78		mut read_buf: impl Buf,
79		mode: SerializationMode,
80	) -> Result<Self, SerializationError>
81	where
82		Self: Sized,
83	{
84		let value: u64 = DeserializeBytes::deserialize(&mut read_buf, mode)?;
85		Ok(value as Self)
86	}
87}
88
89impl SerializeBytes for u128 {
90	fn serialize(
91		&self,
92		mut write_buf: impl BufMut,
93		_mode: SerializationMode,
94	) -> Result<(), SerializationError> {
95		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
96		write_buf.put_u128_le(*self);
97		Ok(())
98	}
99}
100
101impl DeserializeBytes for u128 {
102	fn deserialize(
103		mut read_buf: impl Buf,
104		_mode: SerializationMode,
105	) -> Result<Self, SerializationError>
106	where
107		Self: Sized,
108	{
109		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
110		Ok(read_buf.get_u128_le())
111	}
112}
113
114impl SerializeBytes for u64 {
115	fn serialize(
116		&self,
117		mut write_buf: impl BufMut,
118		_mode: SerializationMode,
119	) -> Result<(), SerializationError> {
120		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
121		write_buf.put_u64_le(*self);
122		Ok(())
123	}
124}
125
126impl DeserializeBytes for u64 {
127	fn deserialize(
128		mut read_buf: impl Buf,
129		_mode: SerializationMode,
130	) -> Result<Self, SerializationError>
131	where
132		Self: Sized,
133	{
134		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
135		Ok(read_buf.get_u64_le())
136	}
137}
138
139impl SerializeBytes for u32 {
140	fn serialize(
141		&self,
142		mut write_buf: impl BufMut,
143		_mode: SerializationMode,
144	) -> Result<(), SerializationError> {
145		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
146		write_buf.put_u32_le(*self);
147		Ok(())
148	}
149}
150
151impl DeserializeBytes for u32 {
152	fn deserialize(
153		mut read_buf: impl Buf,
154		_mode: SerializationMode,
155	) -> Result<Self, SerializationError>
156	where
157		Self: Sized,
158	{
159		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
160		Ok(read_buf.get_u32_le())
161	}
162}
163
164impl SerializeBytes for u16 {
165	fn serialize(
166		&self,
167		mut write_buf: impl BufMut,
168		_mode: SerializationMode,
169	) -> Result<(), SerializationError> {
170		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
171		write_buf.put_u16_le(*self);
172		Ok(())
173	}
174}
175
176impl DeserializeBytes for u16 {
177	fn deserialize(
178		mut read_buf: impl Buf,
179		_mode: SerializationMode,
180	) -> Result<Self, SerializationError>
181	where
182		Self: Sized,
183	{
184		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
185		Ok(read_buf.get_u16_le())
186	}
187}
188
189impl SerializeBytes for u8 {
190	fn serialize(
191		&self,
192		mut write_buf: impl BufMut,
193		_mode: SerializationMode,
194	) -> Result<(), SerializationError> {
195		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
196		write_buf.put_u8(*self);
197		Ok(())
198	}
199}
200
201impl DeserializeBytes for u8 {
202	fn deserialize(
203		mut read_buf: impl Buf,
204		_mode: SerializationMode,
205	) -> Result<Self, SerializationError>
206	where
207		Self: Sized,
208	{
209		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
210		Ok(read_buf.get_u8())
211	}
212}
213
214impl SerializeBytes for bool {
215	fn serialize(
216		&self,
217		write_buf: impl BufMut,
218		mode: SerializationMode,
219	) -> Result<(), SerializationError> {
220		u8::serialize(&(*self as u8), write_buf, mode)
221	}
222}
223
224impl DeserializeBytes for bool {
225	fn deserialize(read_buf: impl Buf, mode: SerializationMode) -> Result<Self, SerializationError>
226	where
227		Self: Sized,
228	{
229		Ok(u8::deserialize(read_buf, mode)? != 0)
230	}
231}
232
233impl<T> SerializeBytes for std::marker::PhantomData<T> {
234	fn serialize(
235		&self,
236		_write_buf: impl BufMut,
237		_mode: SerializationMode,
238	) -> Result<(), SerializationError> {
239		Ok(())
240	}
241}
242
243impl<T> DeserializeBytes for std::marker::PhantomData<T> {
244	fn deserialize(
245		_read_buf: impl Buf,
246		_mode: SerializationMode,
247	) -> Result<Self, SerializationError>
248	where
249		Self: Sized,
250	{
251		Ok(Self)
252	}
253}
254
255impl SerializeBytes for &str {
256	fn serialize(
257		&self,
258		mut write_buf: impl BufMut,
259		mode: SerializationMode,
260	) -> Result<(), SerializationError> {
261		let bytes = self.as_bytes();
262		SerializeBytes::serialize(&bytes.len(), &mut write_buf, mode)?;
263		assert_enough_space_for(&write_buf, bytes.len())?;
264		write_buf.put_slice(bytes);
265		Ok(())
266	}
267}
268
269impl SerializeBytes for String {
270	fn serialize(
271		&self,
272		mut write_buf: impl BufMut,
273		mode: SerializationMode,
274	) -> Result<(), SerializationError> {
275		SerializeBytes::serialize(&self.as_str(), &mut write_buf, mode)
276	}
277}
278
279impl DeserializeBytes for String {
280	fn deserialize(
281		mut read_buf: impl Buf,
282		mode: SerializationMode,
283	) -> Result<Self, SerializationError>
284	where
285		Self: Sized,
286	{
287		let len = DeserializeBytes::deserialize(&mut read_buf, mode)?;
288		assert_enough_data_for(&read_buf, len)?;
289		Ok(Self::from_utf8(read_buf.copy_to_bytes(len).to_vec())?)
290	}
291}
292
293impl<T: SerializeBytes> SerializeBytes for Vec<T> {
294	fn serialize(
295		&self,
296		mut write_buf: impl BufMut,
297		mode: SerializationMode,
298	) -> Result<(), SerializationError> {
299		SerializeBytes::serialize(&self.len(), &mut write_buf, mode)?;
300		self.iter()
301			.try_for_each(|item| SerializeBytes::serialize(item, &mut write_buf, mode))
302	}
303}
304
305impl<T: DeserializeBytes> DeserializeBytes for Vec<T> {
306	fn deserialize(
307		mut read_buf: impl Buf,
308		mode: SerializationMode,
309	) -> Result<Self, SerializationError>
310	where
311		Self: Sized,
312	{
313		let len: usize = DeserializeBytes::deserialize(&mut read_buf, mode)?;
314		(0..len)
315			.map(|_| DeserializeBytes::deserialize(&mut read_buf, mode))
316			.collect()
317	}
318}
319
320impl<T: SerializeBytes> SerializeBytes for Option<T> {
321	fn serialize(
322		&self,
323		mut write_buf: impl BufMut,
324		mode: SerializationMode,
325	) -> Result<(), SerializationError> {
326		match self {
327			Some(value) => {
328				SerializeBytes::serialize(&true, &mut write_buf, mode)?;
329				SerializeBytes::serialize(value, &mut write_buf, mode)?;
330			}
331			None => {
332				SerializeBytes::serialize(&false, write_buf, mode)?;
333			}
334		}
335		Ok(())
336	}
337}
338
339impl<T: DeserializeBytes> DeserializeBytes for Option<T> {
340	fn deserialize(
341		mut read_buf: impl Buf,
342		mode: SerializationMode,
343	) -> Result<Self, SerializationError>
344	where
345		Self: Sized,
346	{
347		Ok(match bool::deserialize(&mut read_buf, mode)? {
348			true => Some(T::deserialize(&mut read_buf, mode)?),
349			false => None,
350		})
351	}
352}
353
354impl<U: SerializeBytes, V: SerializeBytes> SerializeBytes for (U, V) {
355	fn serialize(
356		&self,
357		mut write_buf: impl BufMut,
358		mode: SerializationMode,
359	) -> Result<(), SerializationError> {
360		U::serialize(&self.0, &mut write_buf, mode)?;
361		V::serialize(&self.1, write_buf, mode)
362	}
363}
364
365impl<U: DeserializeBytes, V: DeserializeBytes> DeserializeBytes for (U, V) {
366	fn deserialize(
367		mut read_buf: impl Buf,
368		mode: SerializationMode,
369	) -> Result<Self, SerializationError>
370	where
371		Self: Sized,
372	{
373		Ok((U::deserialize(&mut read_buf, mode)?, V::deserialize(read_buf, mode)?))
374	}
375}
376
377impl<N: ArrayLength<u8>> SerializeBytes for GenericArray<u8, N> {
378	fn serialize(
379		&self,
380		mut write_buf: impl BufMut,
381		_mode: SerializationMode,
382	) -> Result<(), SerializationError> {
383		assert_enough_space_for(&write_buf, N::USIZE)?;
384		write_buf.put_slice(self);
385		Ok(())
386	}
387}
388
389impl<N: ArrayLength<u8>> DeserializeBytes for GenericArray<u8, N> {
390	fn deserialize(
391		mut read_buf: impl Buf,
392		_mode: SerializationMode,
393	) -> Result<Self, SerializationError> {
394		assert_enough_data_for(&read_buf, N::USIZE)?;
395		let mut ret = Self::default();
396		read_buf.copy_to_slice(&mut ret);
397		Ok(ret)
398	}
399}
400
401#[inline]
402fn assert_enough_space_for(write_buf: &impl BufMut, size: usize) -> Result<(), SerializationError> {
403	if write_buf.remaining_mut() < size {
404		return Err(SerializationError::WriteBufferFull);
405	}
406	Ok(())
407}
408
409#[inline]
410fn assert_enough_data_for(read_buf: &impl Buf, size: usize) -> Result<(), SerializationError> {
411	if read_buf.remaining() < size {
412		return Err(SerializationError::NotEnoughBytes);
413	}
414	Ok(())
415}
416
417#[cfg(test)]
418mod tests {
419	use generic_array::typenum::U32;
420	use rand::{rngs::StdRng, RngCore, SeedableRng};
421
422	use super::*;
423
424	#[test]
425	fn test_generic_array_serialize_deserialize() {
426		let mut rng = StdRng::seed_from_u64(0);
427
428		let mut data = GenericArray::<u8, U32>::default();
429		rng.fill_bytes(&mut data);
430
431		let mut buf = Vec::new();
432		data.serialize(&mut buf, SerializationMode::Native).unwrap();
433
434		let data_deserialized =
435			GenericArray::<u8, U32>::deserialize(&mut buf.as_slice(), SerializationMode::Native)
436				.unwrap();
437		assert_eq!(data_deserialized, data);
438	}
439}
binius_utils/serialization.rs

binius_utils/
serialization.rs
