nibblecode 0.1.0

#![feature(
	allocator_api,
	maybe_uninit_slice,
	offset_of_enum,
	ptr_alignment_type,
	ptr_metadata
)]

use core::fmt::{self, Debug, Formatter};
use core::mem::MaybeUninit;
use core::ops::Range;
use core::ptr::{Alignment, read};
use core::str::Utf8Error;

use aligned_alloc::{AlignedAlloc, new_uninit_boxed_slice};

#[macro_use]
mod _macros;
pub mod aligned_alloc;
pub mod boxed;
mod impls;
pub mod list;
pub mod option;
pub mod primitive;
pub mod result;
pub mod string;
pub mod tuple;
pub mod util;

#[cfg(test)]
pub mod test;

pub use nibblecode_derive::Serialize;
use util::check_alignment;

pub enum SerializeError {
	SizedOutOfRange,
	OverflowedPointer,
	ListTooLong,
	StringTooLong,
	BufferTooSmall { serialized_size: usize, len: usize },
}

impl Debug for SerializeError {
	fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
		match self {
			SerializeError::SizedOutOfRange => f.write_str("pointer sized magnitude too big"),
			SerializeError::OverflowedPointer => f.write_str("overflowed pointer size"),
			SerializeError::ListTooLong => f.write_str("list was too long for the pointer size"),
			SerializeError::StringTooLong => {
				f.write_str("string was too long for the archived representation")
			}
			SerializeError::BufferTooSmall {
				serialized_size,
				len,
			} => write!(
				f,
				"buffer too small: trying to write {serialized_size} bytes into buffer of length \
				 {len}",
			),
		}
	}
}

pub enum VerifyError {
	InvalidPointer {
		address: *const u8,
		size: usize,
		range: Range<*const u8>,
	},
	ListTooLong,
	StringTooLong,
	Utf8Error(Utf8Error),
	NonZeroCheckError,
	InvalidEnumDiscriminantError {
		enum_name: &'static str,
		invalid_discriminant: u8,
	},
	UnalignedPointer {
		address: usize,
		align: Alignment,
	},
	InvalidChar,
	InvalidBool {
		byte: u8,
	},
}

impl Debug for VerifyError {
	fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
		match self {
			VerifyError::InvalidPointer {
				address,
				size,
				range,
			} => write!(
				f,
				"pointer overran buffer: ptr {address:p} size {size} in range {range:p}",
			),
			VerifyError::ListTooLong => f.write_str("list size was > `isize::MAX`"),
			VerifyError::StringTooLong => f.write_str("string size was > `isize::MAX`"),
			VerifyError::Utf8Error(utf8_error) => utf8_error.fmt(f),
			VerifyError::NonZeroCheckError => f.write_str("nonzero integer is zero"),
			VerifyError::InvalidEnumDiscriminantError {
				enum_name,
				invalid_discriminant,
			} => write!(
				f,
				"invalid discriminant '{invalid_discriminant}' for enum '{enum_name}'"
			),
			VerifyError::UnalignedPointer { address, align } => write!(
				f,
				"unaligned pointer: ptr {address:p} unaligned for alignment {align:?}"
			),
			VerifyError::InvalidChar => f.write_str("char out of range"),
			VerifyError::InvalidBool { byte } => {
				write!(f, "bool set to invalid byte {byte}, expected either 0 or 1")
			}
		}
	}
}

/// A type that can be serialized and accessed in it's serialized form (as `Self::Archived`)
pub trait Serialize {
	/// The serialized type
	type Archived;

	/// The minimum alignment required by this type
	const ALIGN: Alignment;

	/// An optimization flag that allows the bytes of this type to be copied
	/// directly to a buffer instead of calling `serialize`
	const COPY_OPTIMIZATION: bool = false;

	/// Serialize this type.
	///
	/// Implementations must fully initialize `out` and initialize into the start of `heap`.
	///
	/// # Safety
	/// `out` and `heap` must be valid pointers (unless `T` is a ZST), and `heap` must have
	/// at least the number of bytes returned by `Serialized::serialized_size`
	unsafe fn serialize(
		&self,
		out: *mut MaybeUninit<Self::Archived>,
		heap: *mut MaybeUninit<u8>,
	) -> usize;

	/// How many bytes will type type take up in the 'heap', including padding, if it was
	/// serialized starting at this offset in the buffer. Assume the entire buffer is properly
	/// aligned.
	///
	/// Types that are entirely self-contained should always return 0.
	fn serialized_size(&self, offset: usize) -> Result<usize, SerializeError>;

	/// Check that the data in the buffer is valid. `buffer_end` is a pointer to just after the
	/// buffer, you should not attempt to read past it.
	///
	/// # Safety
	/// `this` must be a valid pointer, and `buffer_end` must be after it, and part of the
	/// same allocation.
	unsafe fn verify(this: *const Self::Archived, buffer_end: *const u8)
	-> Result<(), VerifyError>;
}

/// Serialize a value and write the bytes to the given buffer without checking the length or
/// validity.
///
/// # Safety
/// `buffer` must be large enough to store the given value
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::aligned_alloc::new_uninit_boxed_slice;
/// use nibblecode::{Serialize, access, to_bytes_in_unchecked};
///
/// #[derive(Serialize, Debug)]
/// #[nibblecode(compare(PartialEq), derive(Debug))]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let mut bytes = new_uninit_boxed_slice::<Example>(2);
/// let bytes = unsafe {
/// 	to_bytes_in_unchecked(&value, &mut bytes);
/// 	bytes.assume_init()
/// };
///
/// let archived = access::<Example>(&bytes).unwrap();
///
/// assert_eq!(*archived, value);
/// ```
#[inline]
pub unsafe fn to_bytes_in_unchecked<'a, T: Serialize + ?Sized>(
	value: &T,
	buffer: &'a mut [MaybeUninit<u8>],
) -> usize {
	unsafe {
		if T::COPY_OPTIMIZATION {
			*(buffer as *mut [MaybeUninit<u8>]).cast() =
				MaybeUninit::new(read((value as *const T).cast::<T::Archived>()));

			size_of::<T::Archived>()
		} else {
			// SAFETY: the caller is responsible for making sure the buffer is large enough
			size_of::<T::Archived>()
				+ value.serialize(
					(&raw mut *buffer).cast(),
					(&raw mut *buffer)
						.cast::<MaybeUninit<u8>>()
						.add(size_of::<T::Archived>()),
				)
		}
	}
}

/// Serialize a value and write the bytes to the given buffer, returning th number of bytes
/// written.
///
/// # Safety
/// `buffer` must be large enough to store the given value
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::aligned_alloc::new_uninit_boxed_slice;
/// use nibblecode::{Serialize, access, to_bytes_in};
///
/// #[derive(Serialize, Debug)]
/// #[nibblecode(compare(PartialEq), derive(Debug))]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let mut bytes = new_uninit_boxed_slice::<Example>(2);
/// to_bytes_in(&value, &mut bytes).unwrap();
/// let bytes = unsafe { bytes.assume_init() };
///
/// let archived = access::<Example>(&bytes).unwrap();
///
/// assert_eq!(*archived, value);
/// ```
#[inline]
pub fn to_bytes_in<'a, T: Serialize + ?Sized>(
	value: &T,
	buffer: &'a mut [MaybeUninit<u8>],
) -> Result<usize, SerializeError> {
	value
		.serialized_size(size_of::<T::Archived>())
		.and_then(|heap_size| {
			let serialized_size = size_of::<T::Archived>() + heap_size;
			if serialized_size <= buffer.len() {
				unsafe {
					to_bytes_in_unchecked(value, &mut *buffer);
				}
				// We choose to return the pre-calculated size, rather than the one calculated
				// while serializing, because it allows the compiler to remove some of the extra
				// size calculations
				Ok(serialized_size)
			} else {
				Err(SerializeError::BufferTooSmall {
					serialized_size,
					len: buffer.len(),
				})
			}
		})
}

/// Serialize a value to bytes.
///
/// Returns the serialized bytes in a [`Box<[u8]>`].
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::{Serialize, access, to_bytes};
///
/// #[derive(Serialize, Debug)]
/// #[nibblecode(compare(PartialEq), derive(Debug))]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let bytes = to_bytes(&value).unwrap();
/// let deserialized = access::<Example>(&bytes).unwrap();
///
/// assert_eq!(*deserialized, value);
/// ```
#[inline]
pub fn to_bytes<T: Serialize + ?Sized>(
	value: &T,
) -> Result<Box<[u8], AlignedAlloc<T>>, SerializeError> {
	value
		.serialized_size(size_of::<T::Archived>())
		.map(|heap_size| {
			let mut buffer = new_uninit_boxed_slice::<T>(heap_size);

			unsafe {
				to_bytes_in_unchecked(value, &mut *buffer);

				// SAFETY: `to_bytes_in_unchecked` should've initialized everything
				buffer.assume_init()
			}
		})
}

/// Return a pointer to the archived data without verifying it.
#[inline]
#[must_use]
pub unsafe fn access_ptr_unchecked<T: Serialize + ?Sized>(bytes: &[u8]) -> *const T::Archived {
	<*const [u8]>::cast(bytes)
}

/// Verify this buffer and return a pointer to the archived data.
#[inline]
pub fn access_ptr<T: Serialize + ?Sized>(bytes: &[u8]) -> Result<*const T::Archived, VerifyError> {
	let bytes = bytes as *const [u8];

	let address = bytes.cast::<u8>();

	check_alignment(address, T::ALIGN)?;

	let archived = bytes.cast::<T::Archived>();

	unsafe {
		// SAFETY: this should never overflow, see the comment in `[T]::as_ptr_range`
		let buffer_end = address.add(bytes.len());

		if bytes.len() < size_of::<T::Archived>() {
			return Err(VerifyError::InvalidPointer {
				address,
				size: size_of::<T::Archived>(),
				range: address..buffer_end,
			});
		}

		// SAFETY: `archived` is valid, since we just made sure `bytes` had enough bytes for it.
		// `buffer_end` is also correct.
		T::verify(archived, buffer_end)?;

		Ok(archived)
	}
}

/// Access a byte slice.
///
/// This function does not check that the bytes are valid to access. Use
/// [`access`] to safely access the buffer using validation.
///
/// # Safety
///
/// The byte slice must represent a valid archived type when accessed at the
/// default root position.
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::{Serialize, access_unchecked, to_bytes};
///
/// #[derive(Serialize)]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let bytes = to_bytes(&value).unwrap();
///
/// let archived = unsafe { access_unchecked::<Example>(&*bytes) };
/// assert_eq!(archived.name, "pi");
/// assert_eq!(archived.value, 31415926);
/// ```
#[inline]
#[must_use]
pub unsafe fn access_unchecked<T: Serialize + ?Sized>(bytes: &[u8]) -> &T::Archived {
	unsafe { &*access_ptr_unchecked::<T>(bytes) }
}

/// Access a byte slice.
///
/// This is a safe alternative to [`access_unchecked`].
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::{Serialize, access, to_bytes};
///
/// #[derive(Serialize)]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let bytes = to_bytes(&value).unwrap();
/// let archived = access::<Example>(&bytes).unwrap();
///
/// assert_eq!(archived.name, "pi");
/// assert_eq!(archived.value, 31415926);
/// ```
#[inline]
pub fn access<T: Serialize + ?Sized>(bytes: &[u8]) -> Result<&T::Archived, VerifyError> {
	access_ptr::<T>(bytes).map(|archived| unsafe { &*archived })
}

/// Mutably access a byte slice.
///
/// This function does not check that the bytes are valid to access. Use
/// [`access_mut`] to safely access the buffer using
/// validation.
///
/// # Safety
///
/// The byte slice must represent a valid archived type when accessed at the
/// default root position.
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::{Serialize, access_unchecked_mut, to_bytes};
///
/// #[derive(Serialize)]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let mut bytes = to_bytes(&value).unwrap();
///
/// let mut archived = unsafe { access_unchecked_mut::<Example>(&mut *bytes) };
/// assert_eq!(archived.name, "pi");
/// assert_eq!(archived.value, 31415926);
///
/// // Because the access is mutable, we can mutate the archived data
/// let value = &mut archived.value;
/// assert_eq!(*value, 31415926);
/// *value = 12345.into();
/// assert_eq!(*value, 12345);
/// ```
#[inline]
#[must_use]
pub unsafe fn access_unchecked_mut<T: Serialize + ?Sized>(bytes: &mut [u8]) -> &mut T::Archived {
	unsafe { &mut *<*mut [u8]>::cast(bytes) }
}

/// Mutably access a byte slice.
///
/// This is a safe alternative to [`access_unchecked_mut`].
///
/// # Example
///
/// ```
/// #![feature(ptr_alignment_type)]
///
/// use core::fmt::Debug;
///
/// use nibblecode::{Serialize, access_mut, to_bytes};
///
/// #[derive(Serialize)]
/// struct Example {
/// 	name: String,
/// 	value: i32,
/// }
///
/// let value = Example {
/// 	name: "pi".to_string(),
/// 	value: 31415926,
/// };
///
/// let mut bytes = to_bytes(&value).unwrap();
///
/// let mut archived = access_mut::<Example>(&mut bytes).unwrap();
///
/// // Because the access is mutable, we can mutate the archived data
/// let value = &mut archived.value;
/// assert_eq!(*value, 31415926);
/// *value = 12345.into();
/// assert_eq!(*value, 12345);
/// ```
#[inline]
pub fn access_mut<T: Serialize + ?Sized>(
	bytes: &mut [u8],
) -> Result<&mut T::Archived, VerifyError> {
	access_ptr::<T>(bytes).map(|archived| unsafe { &mut *archived.cast_mut() })
}