1use alloc::collections::VecDeque;
67use alloc::string::String;
68use alloc::vec;
69use alloc::vec::Vec;
70use core::marker::PhantomData;
71
72#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74#[repr(transparent)]
75pub struct RelPtr(i32);
76
77impl RelPtr {
78 pub(crate) fn resolve(&self, field: *const u8) -> Option<*const u8> {
80 if self.0 < 0 {
81 return None;
82 }
83 Some(field.wrapping_add(self.0 as usize))
84 }
85
86 pub(crate) fn from_bytes(bytes: &[u8]) -> Option<Self> {
88 let value = i32::from_le_bytes(bytes.try_into().ok()?);
89 if value < 0 {
90 return None;
91 }
92 Some(Self(value))
93 }
94
95 pub(crate) fn raw(&self) -> i32 {
97 self.0
98 }
99}
100
101#[repr(transparent)]
111pub struct ArchivedString {
112 ptr: RelPtr,
113}
114
115impl ArchivedString {
116 pub unsafe fn as_str_unchecked(&self) -> &str {
123 let field = self as *const ArchivedString as *const u8;
124 let data = unsafe { self.ptr.resolve(field).unwrap_unchecked() };
125 let len = u32::from_le(unsafe { (data as *const u32).read_unaligned() }) as usize;
126 unsafe { core::str::from_utf8_unchecked(core::slice::from_raw_parts(data.add(4), len)) }
127 }
128
129 pub fn as_str(&self) -> &str {
131 unsafe { self.as_str_unchecked() }
132 }
133
134 pub fn as_bytes(&self) -> &[u8] {
136 self.as_str().as_bytes()
137 }
138
139 pub fn len(&self) -> usize {
141 self.as_str().len()
142 }
143
144 pub fn is_empty(&self) -> bool {
146 self.len() == 0
147 }
148}
149
150#[repr(transparent)]
159pub struct ArchivedVec<T> {
160 ptr: RelPtr,
161 marker: PhantomData<T>,
162}
163
164impl<T: ArchivedValue> ArchivedVec<T> {
165 pub unsafe fn as_slice_unchecked(&self) -> &[T] {
172 let field = self as *const ArchivedVec<T> as *const u8;
173 let data = unsafe { self.ptr.resolve(field).unwrap_unchecked() };
174 let count = u32::from_le(unsafe { (data as *const u32).read_unaligned() }) as usize;
175 let padding = (core::mem::align_of::<T>()
176 - (data.wrapping_add(4) as usize % core::mem::align_of::<T>()))
177 % core::mem::align_of::<T>();
178 let elements = unsafe { data.add(4 + padding).cast::<T>() };
179 unsafe { core::slice::from_raw_parts(elements, count) }
180 }
181
182 pub fn as_slice(&self) -> &[T] {
184 unsafe { self.as_slice_unchecked() }
186 }
187
188 pub fn as_ptr(&self) -> *const T {
190 self.as_slice().as_ptr()
191 }
192
193 pub fn iter(&self) -> core::slice::Iter<'_, T> {
195 self.as_slice().iter()
196 }
197
198 pub fn len(&self) -> usize {
200 self.as_slice().len()
201 }
202
203 pub fn is_empty(&self) -> bool {
205 self.len() == 0
206 }
207}
208
209impl<T: ArchivedValue> core::ops::Index<usize> for ArchivedVec<T> {
210 type Output = T;
211
212 fn index(&self, index: usize) -> &T {
213 &self.as_slice()[index]
214 }
215}
216
217pub unsafe trait ArchivedValue: 'static {}
232
233macro_rules! archived_primitive {
234 ($($t:ty),* $(,)?) => {$(
235 unsafe impl ArchivedValue for $t {}
236 )*};
237}
238
239archived_primitive!(u8, u16, u32, u64, i8, i16, i32, i64, f32, f64);
240
241unsafe impl ArchivedValue for ArchivedString {}
244unsafe impl<T: ArchivedValue> ArchivedValue for ArchivedVec<T> {}
248
249pub trait Archive {
251 type Archived;
253}
254
255pub trait ArchiveWrite {
262 fn write_skeleton(&self, serializer: &mut ArchiveSerializer, positions: &mut VecDeque<usize>);
264
265 fn write_bodies(
267 &self,
268 serializer: &mut ArchiveSerializer,
269 positions: &mut VecDeque<usize>,
270 ) -> Result<(), String>;
271}
272
273pub struct ArchiveSerializer {
275 bytes: Vec<u8>,
276}
277
278impl Default for ArchiveSerializer {
279 fn default() -> Self {
280 Self::new()
281 }
282}
283
284impl ArchiveSerializer {
285 pub fn new() -> Self {
287 Self { bytes: Vec::new() }
288 }
289
290 pub fn len(&self) -> usize {
292 self.bytes.len()
293 }
294
295 pub fn is_empty(&self) -> bool {
297 self.bytes.is_empty()
298 }
299
300 pub fn begin(&mut self) -> usize {
302 self.bytes.clear();
303 0
304 }
305
306 pub fn write_u8(&mut self, value: u8) {
308 self.bytes.push(value);
309 }
310
311 pub fn write_u16(&mut self, value: u16) {
313 self.bytes.extend_from_slice(&value.to_le_bytes());
314 }
315
316 pub fn write_u32(&mut self, value: u32) {
318 self.bytes.extend_from_slice(&value.to_le_bytes());
319 }
320
321 pub fn write_u64(&mut self, value: u64) {
323 self.bytes.extend_from_slice(&value.to_le_bytes());
324 }
325
326 pub fn write_i8(&mut self, value: i8) {
328 self.bytes.push(value as u8);
329 }
330
331 pub fn write_i16(&mut self, value: i16) {
333 self.bytes.extend_from_slice(&value.to_le_bytes());
334 }
335
336 pub fn write_i32(&mut self, value: i32) {
338 self.bytes.extend_from_slice(&value.to_le_bytes());
339 }
340
341 pub fn write_i64(&mut self, value: i64) {
343 self.bytes.extend_from_slice(&value.to_le_bytes());
344 }
345
346 pub fn write_f32(&mut self, value: f32) {
348 self.bytes.extend_from_slice(&value.to_le_bytes());
349 }
350
351 pub fn write_f64(&mut self, value: f64) {
353 self.bytes.extend_from_slice(&value.to_le_bytes());
354 }
355
356 pub fn write_bool(&mut self, value: bool) {
358 self.bytes.push(value as u8);
359 }
360
361 pub fn reserve_ptr(&mut self) -> usize {
364 let pos = self.bytes.len();
365 self.bytes.extend_from_slice(&0i32.to_le_bytes());
366 pos
367 }
368
369 pub fn align_to(&mut self, align: usize) {
377 debug_assert!(align != 0 && align.is_power_of_two());
378 let remainder = self.bytes.len() % align;
379 if remainder != 0 {
380 let pad = align - remainder;
381 self.bytes.resize(self.bytes.len() + pad, 0);
382 }
383 }
384
385 pub fn write_string_at(&mut self, field_pos: usize, value: &str) -> Result<(), String> {
387 let data_pos = self.bytes.len();
388 let len = u32::try_from(value.len()).map_err(|_| "archive string exceeds u32 length")?;
389 self.patch_ptr(field_pos, data_pos)?;
390 self.bytes.extend_from_slice(&len.to_le_bytes());
391 self.bytes.extend_from_slice(value.as_bytes());
392 Ok(())
393 }
394
395 pub fn write_vec_at<T: Pod>(&mut self, field_pos: usize, values: &[T]) -> Result<(), String> {
398 let data_pos = self.bytes.len();
399 let count = u32::try_from(values.len()).map_err(|_| "archive vec exceeds u32 count")?;
400 let elements_pos = checked_vec_elements_offset(data_pos, core::mem::align_of::<T>())?;
401 self.patch_ptr(field_pos, data_pos)?;
402 self.bytes.extend_from_slice(&count.to_le_bytes());
403 while self.bytes.len() < elements_pos {
404 self.bytes.push(0);
405 }
406 for value in values {
407 self.bytes.extend_from_slice(&value.to_le_bytes());
408 }
409 Ok(())
410 }
411
412 pub fn patch_ptr(&mut self, field_pos: usize, data_pos: usize) -> Result<(), String> {
415 let delta = data_pos
416 .checked_sub(field_pos)
417 .and_then(|delta| i32::try_from(delta).ok())
418 .ok_or("archive relative offset is outside the positive i32 range")?;
419 if data_pos > self.bytes.len() {
420 return Err("archive pointer target out of bounds".into());
421 }
422 let end = field_pos
423 .checked_add(4)
424 .ok_or("archive pointer position overflow")?;
425 self.bytes
426 .get_mut(field_pos..end)
427 .ok_or("archive pointer placeholder out of bounds")?
428 .copy_from_slice(&delta.to_le_bytes());
429 Ok(())
430 }
431
432 pub fn finish(self) -> Vec<u8> {
434 self.bytes
435 }
436}
437
438pub trait Pod: Sized {
440 fn to_le_bytes(&self) -> Vec<u8>;
442}
443
444macro_rules! pod_impl {
445 ($($t:ty),* $(,)?) => {$(
446 impl Pod for $t {
447 fn to_le_bytes(&self) -> Vec<u8> {
448 <$t>::to_le_bytes(*self).to_vec()
449 }
450 }
451 )*};
452}
453
454pod_impl!(u8, u16, u32, u64, i8, i16, i32, i64, f32, f64);
455
456impl Pod for bool {
457 fn to_le_bytes(&self) -> Vec<u8> {
458 vec![*self as u8]
459 }
460}
461
462pub unsafe trait CheckBytes {
485 fn check_at(bytes: &[u8], base: usize) -> Result<(), String>;
487}
488
489std::thread_local! {
490 static VALIDATION_STATE: core::cell::Cell<(usize, u64)> = const {
493 core::cell::Cell::new((0, 0))
494 };
495}
496
497#[doc(hidden)]
499pub struct ValidationGuard(PhantomData<*mut ()>);
500
501impl ValidationGuard {
502 pub fn enter() -> Result<Self, String> {
505 VALIDATION_STATE.with(|state| {
506 let (depth, visits) = state.get();
507 if depth >= crate::tags::MAX_DEPTH {
508 return Err("archive validation depth limit exceeded".into());
509 }
510 if visits >= crate::config::DEFAULT_COLLECTION_LIMIT {
511 return Err("archive validation visit limit exceeded".into());
512 }
513 state.set((depth + 1, visits + 1));
514 Ok(Self(PhantomData))
515 })
516 }
517}
518
519impl Drop for ValidationGuard {
520 fn drop(&mut self) {
521 VALIDATION_STATE.with(|state| {
522 let (depth, visits) = state.get();
523 state.set(if depth == 1 {
524 (0, 0)
525 } else {
526 (depth - 1, visits)
527 });
528 });
529 }
530}
531
532unsafe impl CheckBytes for ArchivedString {
533 fn check_at(bytes: &[u8], base: usize) -> Result<(), String> {
534 check_skeleton::<Self>(bytes, base)?;
535 check_string_field(bytes, base)
536 }
537}
538
539pub(crate) fn checked_field(bytes: &[u8], field_pos: usize) -> Option<usize> {
542 let ptr = RelPtr::from_bytes(bytes.get(field_pos..field_pos.checked_add(4)?)?)?;
543 let target = field_pos.checked_add(ptr.raw() as usize)?;
544 let end = target.checked_add(4)?;
545 if end > bytes.len() {
546 return None;
547 }
548 Some(target)
549}
550
551pub fn check_skeleton<T>(bytes: &[u8], base: usize) -> Result<(), String> {
554 if cfg!(target_endian = "big") {
555 return Err("zero-copy archive access requires a little-endian target".into());
556 }
557 let end = base
558 .checked_add(core::mem::size_of::<T>())
559 .ok_or("archive skeleton size overflow")?;
560 if end > bytes.len() {
561 return Err("archive skeleton out of bounds".into());
562 }
563 let alignment = core::mem::align_of::<T>();
564 if base % alignment != 0 || bytes.as_ptr() as usize % alignment != 0 {
565 return Err("archive skeleton is misaligned".into());
566 }
567 Ok(())
568}
569
570fn checked_vec_elements_offset(body_base: usize, align: usize) -> Result<usize, String> {
571 if !align.is_power_of_two() {
572 return Err("invalid vec element alignment".into());
573 }
574 let after_count = body_base.checked_add(4).ok_or("vec header overflow")?;
575 after_count
576 .checked_add((align - after_count % align) % align)
577 .ok_or_else(|| "vec alignment overflow".into())
578}
579
580pub(crate) fn vec_elements_offset(body_base: usize, align: usize) -> usize {
584 let after_count = body_base + 4;
585 let pad = (align - (after_count % align)) % align;
586 after_count + pad
587}
588
589pub fn vec_elements_offset_of<T>(body_base: usize) -> usize {
593 vec_elements_offset(body_base, core::mem::align_of::<T>())
594}
595
596pub fn check_string_field(bytes: &[u8], field_pos: usize) -> Result<(), String> {
599 let target = checked_field(bytes, field_pos).ok_or("string offset out of bounds")?;
600 let len = u32::from_le_bytes(
601 bytes
602 .get(target..target + 4)
603 .ok_or("string length out of bounds")?
604 .try_into()
605 .map_err(|_| "string length read failed")?,
606 ) as usize;
607 let body = target + 4;
608 let end = body.checked_add(len).ok_or("string body length overflow")?;
609 if end > bytes.len() {
610 return Err("string body out of bounds".into());
611 }
612 core::str::from_utf8(&bytes[body..end])
613 .map(|_| ())
614 .map_err(|_| "invalid UTF-8 in archived string".into())
615}
616
617pub fn check_vec_field(
620 bytes: &[u8],
621 field_pos: usize,
622 element_size: usize,
623 element_align: usize,
624) -> Result<(), String> {
625 if cfg!(target_endian = "big")
626 || !element_align.is_power_of_two()
627 || bytes.as_ptr() as usize % element_align != 0
628 || element_size % element_align != 0
629 {
630 return Err("invalid or misaligned vec element layout".into());
631 }
632 let target = checked_field(bytes, field_pos).ok_or("vec offset out of bounds")?;
633 let count = u32::from_le_bytes(
634 bytes
635 .get(target..target + 4)
636 .ok_or("vec count out of bounds")?
637 .try_into()
638 .map_err(|_| "vec count read failed")?,
639 ) as usize;
640 let size = count
641 .checked_mul(element_size)
642 .ok_or("vec body size overflow")?;
643 let body = checked_vec_elements_offset(target, element_align)?;
644 let end = body.checked_add(size).ok_or("vec body overflow")?;
645 if end > bytes.len() {
646 return Err("vec body out of bounds".into());
647 }
648 Ok(())
649}
650
651pub fn check_vec_nested<T: CheckBytes>(
655 bytes: &[u8],
656 field_pos: usize,
657 element_size: usize,
658 element_align: usize,
659) -> Result<(), String> {
660 let _validation = ValidationGuard::enter()?;
661 if element_size != core::mem::size_of::<T>() || element_align != core::mem::align_of::<T>() {
662 return Err("nested vec element layout does not match its type".into());
663 }
664 check_vec_field(bytes, field_pos, element_size, element_align)?;
665 let target = checked_field(bytes, field_pos).ok_or("vec offset out of bounds")?;
666 let count = u32::from_le_bytes(
667 bytes
668 .get(target..target + 4)
669 .ok_or("vec count out of bounds")?
670 .try_into()
671 .map_err(|_| "vec count read failed")?,
672 ) as usize;
673 let size = count
674 .checked_mul(element_size)
675 .ok_or("vec body size overflow")?;
676 let body = checked_vec_elements_offset(target, element_align)?;
677 let end = body.checked_add(size).ok_or("vec body overflow")?;
678 if end > bytes.len() {
679 return Err("vec body out of bounds".into());
680 }
681 for i in 0..count {
682 let element_base = body
683 .checked_add(
684 i.checked_mul(element_size)
685 .ok_or("vec element offset overflow")?,
686 )
687 .ok_or("vec element offset overflow")?;
688 T::check_at(bytes, element_base)?;
689 }
690 Ok(())
691}
692
693pub fn to_archive<T: ArchiveWrite>(value: &T) -> Result<Vec<u8>, String> {
695 let mut serializer = ArchiveSerializer::new();
696 serializer.begin();
697 let mut positions = VecDeque::new();
698 value.write_skeleton(&mut serializer, &mut positions);
699 value.write_bodies(&mut serializer, &mut positions)?;
700 Ok(serializer.finish())
701}
702
703#[cfg(test)]
704mod tests {
705 use super::*;
706
707 fn read_u32(bytes: &[u8], pos: usize) -> u32 {
713 u32::from_le_bytes(bytes[pos..pos + 4].try_into().expect("validated u32 range"))
714 }
715
716 #[test]
717 fn string_roundtrip() {
718 let mut serializer = ArchiveSerializer::new();
719 serializer.begin();
720 let field = serializer.reserve_ptr();
721 serializer.write_string_at(field, "hello archive").unwrap();
722 let payload = serializer.finish();
723 check_string_field(&payload, field).unwrap();
724
725 let target = checked_field(&payload, field).expect("validated string offset");
726 let len = read_u32(&payload, target) as usize;
727 let body = &payload[target + 4..target + 4 + len];
728 assert_eq!(
729 core::str::from_utf8(body).expect("validated UTF-8"),
730 "hello archive"
731 );
732 }
733
734 #[test]
735 fn vec_roundtrip() {
736 let mut serializer = ArchiveSerializer::new();
737 serializer.begin();
738 let field = serializer.reserve_ptr();
739 serializer
740 .write_vec_at(field, &[1i32, 2, 3, 65_536])
741 .unwrap();
742 let payload = serializer.finish();
743 check_vec_field(&payload, field, 4, 4).unwrap();
744 let target = checked_field(&payload, field).expect("validated vec offset");
745 assert_eq!(read_u32(&payload, target), 4);
746 let elements = vec_elements_offset(target, 4);
747 let expected = [1i32, 2, 3, 65_536];
748 for (i, &value) in expected.iter().enumerate() {
749 let start = elements + i * 4;
750 let word: [u8; 4] = payload[start..start + 4]
751 .try_into()
752 .expect("validated element");
753 assert_eq!(i32::from_le_bytes(word), value);
754 }
755 }
756
757 #[test]
758 fn vec_elements_are_aligned() {
759 let mut serializer = ArchiveSerializer::new();
760 serializer.begin();
761 let string_field = serializer.reserve_ptr();
762 serializer.write_string_at(string_field, "abc").unwrap();
763 serializer.align_to(4);
764 let vec_field = serializer.reserve_ptr();
765 serializer.write_vec_at(vec_field, &[7i32, 8, 9]).unwrap();
766 let payload = serializer.finish();
767 check_vec_field(&payload, vec_field, 4, 4).unwrap();
768
769 let target = checked_field(&payload, vec_field).expect("validated vec offset");
770 assert_eq!(read_u32(&payload, target), 3);
771 let elements = vec_elements_offset(target, 4);
772 assert_eq!(elements % 4, 0, "element array must be 4-aligned");
773 let expected = [7i32, 8, 9];
774 for (i, &value) in expected.iter().enumerate() {
775 let start = elements + i * 4;
776 let word: [u8; 4] = payload[start..start + 4]
777 .try_into()
778 .expect("validated element");
779 assert_eq!(i32::from_le_bytes(word), value);
780 }
781 }
782
783 #[test]
784 fn negative_offsets_are_rejected() {
785 let mut serializer = ArchiveSerializer::new();
786 serializer.begin();
787 let field = serializer.reserve_ptr();
788 serializer.bytes[field..field + 4].copy_from_slice(&(-8i32).to_le_bytes());
789 let payload = serializer.finish();
790 assert!(check_string_field(&payload, field).is_err());
791 }
792
793 #[test]
794 fn corrupted_length_is_rejected() {
795 let mut serializer = ArchiveSerializer::new();
796 serializer.begin();
797 let field = serializer.reserve_ptr();
798 serializer.write_string_at(field, "x").unwrap();
799 let mut payload = serializer.finish();
800
801 let target = RelPtr::from_bytes(&payload[field..field + 4])
802 .unwrap()
803 .raw() as usize;
804 payload[target..target + 4].copy_from_slice(&1_000_000u32.to_le_bytes());
805 assert!(check_string_field(&payload, field).is_err());
806 }
807
808 #[test]
809 fn nested_vec_elements_are_checked() {
810 let mut serializer = ArchiveSerializer::new();
811 serializer.begin();
812 let field = serializer.reserve_ptr();
813 serializer.write_u32(2); serializer.write_u64(10);
815 serializer.write_u32(100);
816 serializer.write_u64(20);
817 serializer.write_u32(200);
818 serializer.patch_ptr(field, 0).unwrap();
819 let payload = serializer.finish();
820
821 check_vec_field(&payload, field, 12, 1).unwrap();
822 }
823}