fidl/
persistence.rs

1// Copyright 2023 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Provides standalone FIDL encoding and decoding.
6
7use crate::encoding::{
8    AtRestFlags, Context, Decode, Decoder, Depth, Encode, Encoder, GenericMessage,
9    GenericMessageType, HandleFor, NoHandleResourceDialect, ProxyChannelFor, ResourceDialect,
10    ResourceTypeMarker, TypeMarker, ValueTypeMarker, WireFormatVersion, MAGIC_NUMBER_INITIAL,
11};
12use crate::{Error, Result};
13
14/// Marker trait implemented for FIDL non-resource structs, tables, and unions.
15/// These can be used with the persistence API and standalone encoding/decoding API.
16pub trait Persistable:
17    TypeMarker<Owned = Self>
18    + Decode<Self, NoHandleResourceDialect>
19    + for<'a> ValueTypeMarker<Borrowed<'a> = &'a Self>
20    + for<'a> ValueTypeMarker<Borrowed<'a>: Encode<Self, NoHandleResourceDialect>>
21{
22}
23
24/// Marker trait implemented for FIDL resource structs, tables, and unions.
25/// These can be used with the standalone encoding/decoding API, but not the persistence API.
26pub trait Standalone<D>:
27    TypeMarker<Owned = Self> + Decode<Self, D> + for<'a> ResourceTypeMarker<Borrowed<'a> = &'a mut Self>
28{
29}
30
31/// Header for RFC-0120 persistent FIDL messages.
32#[derive(Copy, Clone, Debug, Eq, PartialEq)]
33#[repr(C)]
34pub struct WireMetadata {
35    /// Must be zero.
36    disambiguator: u8,
37    /// Magic number indicating the message's wire format. Two sides with
38    /// different magic numbers are incompatible with each other.
39    magic_number: u8,
40    /// "At rest" flags set for this message. MUST NOT be validated by bindings.
41    at_rest_flags: [u8; 2],
42    /// Reserved bytes. Must be zero.
43    reserved: [u8; 4],
44}
45
46impl WireMetadata {
47    /// Creates a new `WireMetadata` with a specific context and magic number.
48    #[inline]
49    fn new_full(context: Context, magic_number: u8) -> Self {
50        WireMetadata {
51            disambiguator: 0,
52            magic_number,
53            at_rest_flags: context.at_rest_flags().into(),
54            reserved: [0; 4],
55        }
56    }
57
58    /// Returns the header's flags as an `AtRestFlags` value.
59    #[inline]
60    fn at_rest_flags(&self) -> AtRestFlags {
61        AtRestFlags::from_bits_truncate(u16::from_le_bytes(self.at_rest_flags))
62    }
63
64    /// Returns the context to use for decoding the message body associated with
65    /// this header. During migrations, this is dependent on `self.flags()` and
66    /// controls dynamic behavior in the read path.
67    #[inline]
68    fn decoding_context(&self) -> Context {
69        Context { wire_format_version: WireFormatVersion::V2 }
70    }
71
72    /// Returns an error if this header has an incompatible wire format.
73    #[inline]
74    pub fn validate_wire_format(&self) -> Result<()> {
75        if self.magic_number != MAGIC_NUMBER_INITIAL {
76            return Err(Error::IncompatibleMagicNumber(self.magic_number));
77        }
78        if !self.at_rest_flags().contains(AtRestFlags::USE_V2_WIRE_FORMAT) {
79            return Err(Error::UnsupportedWireFormatVersion);
80        }
81        Ok(())
82    }
83}
84
85/// The default context for persistent encoding.
86#[inline]
87fn default_persistent_encode_context() -> Context {
88    Context { wire_format_version: WireFormatVersion::V2 }
89}
90
91/// Encodes a FIDL object to bytes following RFC-0120. This only works on
92/// non-resource structs, tables, and unions. See `unpersist` for the reverse.
93pub fn persist<T: Persistable>(body: &T) -> Result<Vec<u8>> {
94    let context = default_persistent_encode_context();
95    let header = WireMetadata::new_full(context, MAGIC_NUMBER_INITIAL);
96    let msg = GenericMessage { header, body };
97    let mut bytes = Vec::<u8>::new();
98    let mut handles = Vec::new();
99    Encoder::encode_with_context::<GenericMessageType<WireMetadata, T>>(
100        context,
101        &mut bytes,
102        &mut handles,
103        msg,
104    )?;
105    debug_assert!(handles.is_empty(), "value type contains handles");
106    Ok(bytes)
107}
108
109/// Decodes a FIDL object from bytes following RFC-0120. Must be a non-resource
110/// struct, table, or union. See `persist` for the reverse.
111pub fn unpersist<T: Persistable>(bytes: &[u8]) -> Result<T> {
112    let (header, body_bytes) = decode_wire_metadata(bytes)?;
113    let mut output = T::new_empty();
114    Decoder::decode_with_context::<T>(header.decoding_context(), body_bytes, &mut [], &mut output)?;
115    Ok(output)
116}
117
118/// Encodes a FIDL object to bytes and wire metadata following RFC-0120. Must be
119/// a non-resource struct, table, or union.
120pub fn standalone_encode_value<T: Persistable>(body: &T) -> Result<(Vec<u8>, WireMetadata)>
121where
122    for<'a> T::Borrowed<'a>: Encode<T, NoHandleResourceDialect>,
123{
124    // This helper is needed to convince rustc that &T implements Encode<T>.
125    fn helper<T: ValueTypeMarker>(body: T::Borrowed<'_>) -> Result<(Vec<u8>, WireMetadata)>
126    where
127        for<'a> T::Borrowed<'a>: Encode<T, NoHandleResourceDialect>,
128    {
129        let context = default_persistent_encode_context();
130        let metadata = WireMetadata::new_full(context, MAGIC_NUMBER_INITIAL);
131        let mut bytes = Vec::<u8>::new();
132        let mut handles = Vec::new();
133        Encoder::<NoHandleResourceDialect>::encode_with_context::<T>(
134            context,
135            &mut bytes,
136            &mut handles,
137            body,
138        )?;
139        debug_assert!(handles.is_empty(), "value type contains handles");
140        Ok((bytes, metadata))
141    }
142    helper::<T>(body)
143}
144
145/// Encodes a FIDL object to bytes, handles, and wire metadata following
146/// RFC-0120. Must be a resource struct, table, or union.
147#[allow(clippy::type_complexity)]
148pub fn standalone_encode_resource<T: Standalone<D>, D: ResourceDialect>(
149    mut body: T,
150) -> Result<(Vec<u8>, Vec<<D::ProxyChannel as ProxyChannelFor<D>>::HandleDisposition>, WireMetadata)>
151where
152    for<'a> T::Borrowed<'a>: Encode<T, D>,
153{
154    let context = default_persistent_encode_context();
155    let metadata = WireMetadata::new_full(context, MAGIC_NUMBER_INITIAL);
156    let mut bytes = Vec::<u8>::new();
157    let mut handles = Vec::<_>::new();
158    Encoder::encode_with_context::<T>(context, &mut bytes, &mut handles, &mut body)?;
159    Ok((bytes, handles, metadata))
160}
161
162/// Decodes a FIDL object from bytes and wire metadata following RFC-0120. Must
163/// be a non-resource struct, table, or union.
164pub fn standalone_decode_value<T: Persistable>(bytes: &[u8], metadata: &WireMetadata) -> Result<T> {
165    let mut output = T::Owned::new_empty();
166    Decoder::decode_with_context::<T>(metadata.decoding_context(), bytes, &mut [], &mut output)?;
167    Ok(output)
168}
169
170/// Decodes a FIDL object from bytes, handles, and wire metadata following
171/// RFC-0120. Must be a resource struct, table, or union.
172pub fn standalone_decode_resource<T: Standalone<D>, D: ResourceDialect>(
173    bytes: &[u8],
174    handles: &mut [<D::Handle as HandleFor<D>>::HandleInfo],
175    metadata: &WireMetadata,
176) -> Result<T> {
177    let mut output = <T as TypeMarker>::Owned::new_empty();
178    Decoder::decode_with_context::<T>(metadata.decoding_context(), bytes, handles, &mut output)?;
179    Ok(output)
180}
181
182/// Decodes the persistently stored header from a message.
183/// Returns the header and a reference to the tail of the message.
184fn decode_wire_metadata(bytes: &[u8]) -> Result<(WireMetadata, &[u8])> {
185    let mut header = new_empty!(WireMetadata, NoHandleResourceDialect);
186    let context = Context { wire_format_version: WireFormatVersion::V2 };
187    let header_len = <WireMetadata as TypeMarker>::inline_size(context);
188    if bytes.len() < header_len {
189        return Err(Error::OutOfRange);
190    }
191    let (header_bytes, body_bytes) = bytes.split_at(header_len);
192    Decoder::<NoHandleResourceDialect>::decode_with_context::<WireMetadata>(
193        context,
194        header_bytes,
195        &mut [],
196        &mut header,
197    )
198    .map_err(|_| Error::InvalidHeader)?;
199    header.validate_wire_format()?;
200    Ok((header, body_bytes))
201}
202
203unsafe impl TypeMarker for WireMetadata {
204    type Owned = Self;
205
206    #[inline(always)]
207    fn inline_align(_context: Context) -> usize {
208        1
209    }
210
211    #[inline(always)]
212    fn inline_size(_context: Context) -> usize {
213        8
214    }
215}
216
217impl ValueTypeMarker for WireMetadata {
218    type Borrowed<'a> = &'a Self;
219    fn borrow(value: &<Self as TypeMarker>::Owned) -> Self::Borrowed<'_> {
220        value
221    }
222}
223
224unsafe impl<D: ResourceDialect> Encode<WireMetadata, D> for &WireMetadata {
225    #[inline]
226    unsafe fn encode(
227        self,
228        encoder: &mut Encoder<'_, D>,
229        offset: usize,
230        _depth: Depth,
231    ) -> Result<()> {
232        encoder.debug_check_bounds::<WireMetadata>(offset);
233        unsafe {
234            let buf_ptr = encoder.buf.as_mut_ptr().add(offset);
235            (buf_ptr as *mut WireMetadata).write_unaligned(*self);
236        }
237        Ok(())
238    }
239}
240
241impl<D: ResourceDialect> Decode<Self, D> for WireMetadata {
242    #[inline(always)]
243    fn new_empty() -> Self {
244        Self { disambiguator: 0, magic_number: 0, at_rest_flags: [0; 2], reserved: [0; 4] }
245    }
246
247    #[inline]
248    unsafe fn decode(
249        &mut self,
250        decoder: &mut Decoder<'_, D>,
251        offset: usize,
252        _depth: Depth,
253    ) -> Result<()> {
254        decoder.debug_check_bounds::<Self>(offset);
255        unsafe {
256            let buf_ptr = decoder.buf.as_ptr().add(offset);
257            let obj_ptr = self as *mut WireMetadata;
258            std::ptr::copy_nonoverlapping(buf_ptr, obj_ptr as *mut u8, 8);
259        }
260        Ok(())
261    }
262}
fidl/persistence.rs

fidl/
persistence.rs
