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	#[error("usize {size} is too large to serialize (max is {max})", max = u32::MAX)]
52	UsizeTooLarge { size: usize },
53}
54
55// Copyright 2025 Irreducible Inc.
56
57use generic_array::{ArrayLength, GenericArray};
58
59impl<T: DeserializeBytes> DeserializeBytes for Box<T> {
60	fn deserialize(read_buf: impl Buf, mode: SerializationMode) -> Result<Self, SerializationError>
61	where
62		Self: Sized,
63	{
64		Ok(Self::new(T::deserialize(read_buf, mode)?))
65	}
66}
67
68impl SerializeBytes for usize {
69	fn serialize(
70		&self,
71		mut write_buf: impl BufMut,
72		mode: SerializationMode,
73	) -> Result<(), SerializationError> {
74		let value: u32 = (*self)
75			.try_into()
76			.map_err(|_| SerializationError::UsizeTooLarge { size: *self })?;
77		SerializeBytes::serialize(&value, &mut write_buf, mode)
78	}
79}
80
81impl DeserializeBytes for usize {
82	fn deserialize(
83		mut read_buf: impl Buf,
84		mode: SerializationMode,
85	) -> Result<Self, SerializationError>
86	where
87		Self: Sized,
88	{
89		let value: u32 = DeserializeBytes::deserialize(&mut read_buf, mode)?;
90		Ok(value as Self)
91	}
92}
93
94impl SerializeBytes for u128 {
95	fn serialize(
96		&self,
97		mut write_buf: impl BufMut,
98		_mode: SerializationMode,
99	) -> Result<(), SerializationError> {
100		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
101		write_buf.put_u128_le(*self);
102		Ok(())
103	}
104}
105
106impl DeserializeBytes for u128 {
107	fn deserialize(
108		mut read_buf: impl Buf,
109		_mode: SerializationMode,
110	) -> Result<Self, SerializationError>
111	where
112		Self: Sized,
113	{
114		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
115		Ok(read_buf.get_u128_le())
116	}
117}
118
119impl SerializeBytes for u64 {
120	fn serialize(
121		&self,
122		mut write_buf: impl BufMut,
123		_mode: SerializationMode,
124	) -> Result<(), SerializationError> {
125		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
126		write_buf.put_u64_le(*self);
127		Ok(())
128	}
129}
130
131impl DeserializeBytes for u64 {
132	fn deserialize(
133		mut read_buf: impl Buf,
134		_mode: SerializationMode,
135	) -> Result<Self, SerializationError>
136	where
137		Self: Sized,
138	{
139		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
140		Ok(read_buf.get_u64_le())
141	}
142}
143
144impl SerializeBytes for u32 {
145	fn serialize(
146		&self,
147		mut write_buf: impl BufMut,
148		_mode: SerializationMode,
149	) -> Result<(), SerializationError> {
150		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
151		write_buf.put_u32_le(*self);
152		Ok(())
153	}
154}
155
156impl DeserializeBytes for u32 {
157	fn deserialize(
158		mut read_buf: impl Buf,
159		_mode: SerializationMode,
160	) -> Result<Self, SerializationError>
161	where
162		Self: Sized,
163	{
164		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
165		Ok(read_buf.get_u32_le())
166	}
167}
168
169impl SerializeBytes for u16 {
170	fn serialize(
171		&self,
172		mut write_buf: impl BufMut,
173		_mode: SerializationMode,
174	) -> Result<(), SerializationError> {
175		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
176		write_buf.put_u16_le(*self);
177		Ok(())
178	}
179}
180
181impl DeserializeBytes for u16 {
182	fn deserialize(
183		mut read_buf: impl Buf,
184		_mode: SerializationMode,
185	) -> Result<Self, SerializationError>
186	where
187		Self: Sized,
188	{
189		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
190		Ok(read_buf.get_u16_le())
191	}
192}
193
194impl SerializeBytes for u8 {
195	fn serialize(
196		&self,
197		mut write_buf: impl BufMut,
198		_mode: SerializationMode,
199	) -> Result<(), SerializationError> {
200		assert_enough_space_for(&write_buf, std::mem::size_of::<Self>())?;
201		write_buf.put_u8(*self);
202		Ok(())
203	}
204}
205
206impl DeserializeBytes for u8 {
207	fn deserialize(
208		mut read_buf: impl Buf,
209		_mode: SerializationMode,
210	) -> Result<Self, SerializationError>
211	where
212		Self: Sized,
213	{
214		assert_enough_data_for(&read_buf, std::mem::size_of::<Self>())?;
215		Ok(read_buf.get_u8())
216	}
217}
218
219impl SerializeBytes for bool {
220	fn serialize(
221		&self,
222		write_buf: impl BufMut,
223		mode: SerializationMode,
224	) -> Result<(), SerializationError> {
225		u8::serialize(&(*self as u8), write_buf, mode)
226	}
227}
228
229impl DeserializeBytes for bool {
230	fn deserialize(read_buf: impl Buf, mode: SerializationMode) -> Result<Self, SerializationError>
231	where
232		Self: Sized,
233	{
234		Ok(u8::deserialize(read_buf, mode)? != 0)
235	}
236}
237
238impl<T> SerializeBytes for std::marker::PhantomData<T> {
239	fn serialize(
240		&self,
241		_write_buf: impl BufMut,
242		_mode: SerializationMode,
243	) -> Result<(), SerializationError> {
244		Ok(())
245	}
246}
247
248impl<T> DeserializeBytes for std::marker::PhantomData<T> {
249	fn deserialize(
250		_read_buf: impl Buf,
251		_mode: SerializationMode,
252	) -> Result<Self, SerializationError>
253	where
254		Self: Sized,
255	{
256		Ok(Self)
257	}
258}
259
260impl SerializeBytes for &str {
261	fn serialize(
262		&self,
263		mut write_buf: impl BufMut,
264		mode: SerializationMode,
265	) -> Result<(), SerializationError> {
266		let bytes = self.as_bytes();
267		SerializeBytes::serialize(&bytes.len(), &mut write_buf, mode)?;
268		assert_enough_space_for(&write_buf, bytes.len())?;
269		write_buf.put_slice(bytes);
270		Ok(())
271	}
272}
273
274impl SerializeBytes for String {
275	fn serialize(
276		&self,
277		mut write_buf: impl BufMut,
278		mode: SerializationMode,
279	) -> Result<(), SerializationError> {
280		SerializeBytes::serialize(&self.as_str(), &mut write_buf, mode)
281	}
282}
283
284impl DeserializeBytes for String {
285	fn deserialize(
286		mut read_buf: impl Buf,
287		mode: SerializationMode,
288	) -> Result<Self, SerializationError>
289	where
290		Self: Sized,
291	{
292		let len = DeserializeBytes::deserialize(&mut read_buf, mode)?;
293		assert_enough_data_for(&read_buf, len)?;
294		Ok(Self::from_utf8(read_buf.copy_to_bytes(len).to_vec())?)
295	}
296}
297
298impl<T: SerializeBytes> SerializeBytes for [T] {
299	fn serialize(
300		&self,
301		mut write_buf: impl BufMut,
302		mode: SerializationMode,
303	) -> Result<(), SerializationError> {
304		SerializeBytes::serialize(&self.len(), &mut write_buf, mode)?;
305		self.iter()
306			.try_for_each(|item| SerializeBytes::serialize(item, &mut write_buf, mode))
307	}
308}
309
310impl<T: SerializeBytes> SerializeBytes for Vec<T> {
311	fn serialize(
312		&self,
313		mut write_buf: impl BufMut,
314		mode: SerializationMode,
315	) -> Result<(), SerializationError> {
316		SerializeBytes::serialize(self.as_slice(), &mut write_buf, mode)
317	}
318}
319
320impl<T: DeserializeBytes> DeserializeBytes for Vec<T> {
321	fn deserialize(
322		mut read_buf: impl Buf,
323		mode: SerializationMode,
324	) -> Result<Self, SerializationError>
325	where
326		Self: Sized,
327	{
328		let len: usize = DeserializeBytes::deserialize(&mut read_buf, mode)?;
329		(0..len)
330			.map(|_| DeserializeBytes::deserialize(&mut read_buf, mode))
331			.collect()
332	}
333}
334
335impl<T: SerializeBytes> SerializeBytes for Option<T> {
336	fn serialize(
337		&self,
338		mut write_buf: impl BufMut,
339		mode: SerializationMode,
340	) -> Result<(), SerializationError> {
341		match self {
342			Some(value) => {
343				SerializeBytes::serialize(&true, &mut write_buf, mode)?;
344				SerializeBytes::serialize(value, &mut write_buf, mode)?;
345			}
346			None => {
347				SerializeBytes::serialize(&false, write_buf, mode)?;
348			}
349		}
350		Ok(())
351	}
352}
353
354impl<T: DeserializeBytes> DeserializeBytes for Option<T> {
355	fn deserialize(
356		mut read_buf: impl Buf,
357		mode: SerializationMode,
358	) -> Result<Self, SerializationError>
359	where
360		Self: Sized,
361	{
362		Ok(match bool::deserialize(&mut read_buf, mode)? {
363			true => Some(T::deserialize(&mut read_buf, mode)?),
364			false => None,
365		})
366	}
367}
368
369impl<U: SerializeBytes, V: SerializeBytes> SerializeBytes for (U, V) {
370	fn serialize(
371		&self,
372		mut write_buf: impl BufMut,
373		mode: SerializationMode,
374	) -> Result<(), SerializationError> {
375		U::serialize(&self.0, &mut write_buf, mode)?;
376		V::serialize(&self.1, write_buf, mode)
377	}
378}
379
380impl<U: DeserializeBytes, V: DeserializeBytes> DeserializeBytes for (U, V) {
381	fn deserialize(
382		mut read_buf: impl Buf,
383		mode: SerializationMode,
384	) -> Result<Self, SerializationError>
385	where
386		Self: Sized,
387	{
388		Ok((U::deserialize(&mut read_buf, mode)?, V::deserialize(read_buf, mode)?))
389	}
390}
391
392impl<N: ArrayLength<u8>> SerializeBytes for GenericArray<u8, N> {
393	fn serialize(
394		&self,
395		mut write_buf: impl BufMut,
396		_mode: SerializationMode,
397	) -> Result<(), SerializationError> {
398		assert_enough_space_for(&write_buf, N::USIZE)?;
399		write_buf.put_slice(self);
400		Ok(())
401	}
402}
403
404impl<N: ArrayLength<u8>> DeserializeBytes for GenericArray<u8, N> {
405	fn deserialize(
406		mut read_buf: impl Buf,
407		_mode: SerializationMode,
408	) -> Result<Self, SerializationError> {
409		assert_enough_data_for(&read_buf, N::USIZE)?;
410		let mut ret = Self::default();
411		read_buf.copy_to_slice(&mut ret);
412		Ok(ret)
413	}
414}
415
416#[inline]
417fn assert_enough_space_for(write_buf: &impl BufMut, size: usize) -> Result<(), SerializationError> {
418	if write_buf.remaining_mut() < size {
419		return Err(SerializationError::WriteBufferFull);
420	}
421	Ok(())
422}
423
424#[inline]
425fn assert_enough_data_for(read_buf: &impl Buf, size: usize) -> Result<(), SerializationError> {
426	if read_buf.remaining() < size {
427		return Err(SerializationError::NotEnoughBytes);
428	}
429	Ok(())
430}
431
432#[cfg(test)]
433mod tests {
434	use generic_array::typenum::U32;
435	use rand::{rngs::StdRng, RngCore, SeedableRng};
436
437	use super::*;
438
439	#[test]
440	fn test_generic_array_serialize_deserialize() {
441		let mut rng = StdRng::seed_from_u64(0);
442
443		let mut data = GenericArray::<u8, U32>::default();
444		rng.fill_bytes(&mut data);
445
446		let mut buf = Vec::new();
447		data.serialize(&mut buf, SerializationMode::Native).unwrap();
448
449		let data_deserialized =
450			GenericArray::<u8, U32>::deserialize(&mut buf.as_slice(), SerializationMode::Native)
451				.unwrap();
452		assert_eq!(data_deserialized, data);
453	}
454}
binius_utils/serialization.rs

binius_utils/
serialization.rs
