rkyv 0.8.16

Zero-copy deserialization framework for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Basic archive buffer validation.

mod validator;

use core::{alloc::Layout, ops::Range};

use bytecheck::rancor::{Fallible, Source, Strategy};
use rancor::ResultExt as _;

pub use self::validator::*;
use crate::traits::LayoutRaw;

/// A context that can validate nonlocal archive memory.
///
/// # Safety
///
/// `check_subtree_ptr` must only return true if `ptr` is located entirely
/// within the subtree range and is safe to dereference.
pub unsafe trait ArchiveContext<E = <Self as Fallible>::Error> {
    /// Checks that the given data address and layout is located completely
    /// within the subtree range.
    fn check_subtree_ptr(
        &mut self,
        ptr: *const u8,
        layout: &Layout,
    ) -> Result<(), E>;

    /// Pushes a new subtree range onto the validator and starts validating it.
    ///
    /// After calling `push_subtree_range`, the validator will have a subtree
    /// range starting at the original start and ending at `root`. After popping
    /// the returned range, the validator will have a subtree range starting at
    /// `end` and ending at the original end.
    ///
    /// # Safety
    ///
    /// `root` and `end` must be located inside the archive.
    unsafe fn push_subtree_range(
        &mut self,
        root: *const u8,
        end: *const u8,
    ) -> Result<Range<usize>, E>;

    /// Pops the given range, restoring the original state with the pushed range
    /// removed.
    ///
    /// If the range was not popped in reverse order, an error is returned.
    ///
    /// # Safety
    ///
    /// `range` must be a range returned from this validator.
    unsafe fn pop_subtree_range(
        &mut self,
        range: Range<usize>,
    ) -> Result<(), E>;
}

unsafe impl<T, E> ArchiveContext<E> for Strategy<T, E>
where
    T: ArchiveContext<E> + ?Sized,
{
    fn check_subtree_ptr(
        &mut self,
        ptr: *const u8,
        layout: &Layout,
    ) -> Result<(), E> {
        T::check_subtree_ptr(self, ptr, layout)
    }

    unsafe fn push_subtree_range(
        &mut self,
        root: *const u8,
        end: *const u8,
    ) -> Result<Range<usize>, E> {
        // SAFETY: This just forwards the call to the underlying context, which
        // has the same safety requirements.
        unsafe { T::push_subtree_range(self, root, end) }
    }

    unsafe fn pop_subtree_range(
        &mut self,
        range: Range<usize>,
    ) -> Result<(), E> {
        // SAFETY: This just forwards the call to the underlying context, which
        // has the same safety requirements.
        unsafe { T::pop_subtree_range(self, range) }
    }
}

/// Helper methods for [`ArchiveContext`].
pub trait ArchiveContextExt<E>: ArchiveContext<E> {
    /// Checks that the given pointer and layout are within the current subtree
    /// range of the context, then pushes a new subtree range onto the validator
    /// for it and calls the given function.
    fn in_subtree_raw<R>(
        &mut self,
        ptr: *const u8,
        layout: Layout,
        f: impl FnOnce(&mut Self) -> Result<R, E>,
    ) -> Result<R, E>;

    /// Checks that the value the given pointer points to is within the current
    /// subtree range of the context, then pushes a new subtree range onto the
    /// validator for it and calls the given function.
    fn in_subtree<T: LayoutRaw + ?Sized, R>(
        &mut self,
        ptr: *const T,
        f: impl FnOnce(&mut Self) -> Result<R, E>,
    ) -> Result<R, E>;
}

impl<C: ArchiveContext<E> + ?Sized, E: Source> ArchiveContextExt<E> for C {
    #[allow(clippy::not_unsafe_ptr_arg_deref)]
    fn in_subtree_raw<R>(
        &mut self,
        ptr: *const u8,
        layout: Layout,
        f: impl FnOnce(&mut Self) -> Result<R, E>,
    ) -> Result<R, E> {
        self.check_subtree_ptr(ptr, &layout)?;

        // SAFETY: We checked that the entire range from `ptr` to
        // `ptr + layout.size()` is located within the buffer.
        let range =
            unsafe { self.push_subtree_range(ptr, ptr.add(layout.size()))? };

        let result = f(self)?;

        // SAFETY: `range` was returned from `push_subtree_range`.
        unsafe {
            self.pop_subtree_range(range)?;
        }

        Ok(result)
    }

    #[allow(clippy::not_unsafe_ptr_arg_deref)]
    fn in_subtree<T: LayoutRaw + ?Sized, R>(
        &mut self,
        ptr: *const T,
        f: impl FnOnce(&mut Self) -> Result<R, E>,
    ) -> Result<R, E> {
        let layout = T::layout_raw(ptr_meta::metadata(ptr)).into_error()?;
        let root = ptr as *const u8;

        self.in_subtree_raw(root, layout, f)
    }
}