rustorb-cdr 0.2.0

CDR (Common Data Representation) encoder and decoder for rustorb
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
use std::sync::Arc;

use crate::{ByteOrder, Encoding, Error, LongDouble, Octets, Result, SHARE_MIN};

/// Reads CDR from a byte slice.
///
/// Alignment is relative to the stream offset of the first byte, which is
/// `0` unless the decoder was created with [`Decoder::with_offset`].
/// [`Decoder::set_segments`] restarts the stream offset at given bytes,
/// for data joined from several messages.
#[derive(Debug, Clone)]
pub struct Decoder<'a> {
    pub(crate) buf: &'a [u8],
    /// The buffer `buf` lies in, when it is shared.
    shared: Option<&'a Arc<Vec<u8>>>,
    pub(crate) pos: usize,
    pub(crate) order: ByteOrder,
    encoding: Encoding,
    base: usize,
    /// The stream offset alignment counts from (`XCDR.origin`).
    pub(crate) origin: usize,
    segments: &'a [Segment],
    wstring_default_order: ByteOrder,
    /// What the valuetypes read so far need (indirections, chunks);
    /// made with the first value.
    pub(crate) values: Option<Box<crate::value::ReadState>>,
}

/// A point in a decoder's buffer from which the stream offset restarts.
///
/// The byte at index `start` of the buffer is at stream offset `offset`,
/// and the bytes after it follow on, until the next segment. This
/// describes a message joined from fragments whose contents are aligned
/// relative to each fragment rather than to the joined message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Segment {
    /// Index of the first byte of the segment in the buffer.
    pub start: usize,
    /// Stream offset of that byte.
    pub offset: usize,
}

macro_rules! read_number {
    ($(#[$doc:meta] $name:ident: $ty:ty;)*) => {
        $(
            #[$doc]
            pub fn $name(&mut self) -> Result<$ty> {
                self.align(size_of::<$ty>())?;
                let bytes = self.read_array()?;
                Ok(match self.order {
                    ByteOrder::Big => <$ty>::from_be_bytes(bytes),
                    ByteOrder::Little => <$ty>::from_le_bytes(bytes),
                })
            }
        )*
    };
}

impl<'a> Decoder<'a> {
    /// Creates a decoder whose first byte is at stream offset 0.
    pub fn new(buf: &'a [u8], order: ByteOrder, encoding: Encoding) -> Decoder<'a> {
        Decoder::with_offset(buf, order, encoding, 0)
    }

    /// Creates a decoder whose first byte is at stream offset `base`.
    pub fn with_offset(
        buf: &'a [u8],
        order: ByteOrder,
        encoding: Encoding,
        base: usize,
    ) -> Decoder<'a> {
        Decoder {
            buf,
            shared: None,
            pos: 0,
            order,
            encoding,
            base,
            origin: 0,
            segments: &[],
            wstring_default_order: ByteOrder::Big,
            values: None,
        }
    }

    /// Restarts the stream offset at the given buffer indexes. `segments`
    /// must be sorted by `start`; bytes before the first segment keep the
    /// offset given when the decoder was created.
    pub fn set_segments(&mut self, segments: &'a [Segment]) {
        debug_assert!(segments.windows(2).all(|w| w[0].start < w[1].start));
        self.segments = segments;
    }

    /// Opens an encapsulation: reads the byte order octet and returns a
    /// decoder positioned after it, with alignment starting at that octet.
    pub fn encapsulation(buf: &'a [u8], encoding: Encoding) -> Result<Decoder<'a>> {
        let (&flag, _) = buf.split_first().ok_or(Error::EmptyEncapsulation)?;
        let order = ByteOrder::from_flag(flag)?;
        let mut dec = Decoder::new(buf, order, encoding);
        dec.pos = 1;
        Ok(dec)
    }

    /// Sets the byte order assumed for a GIOP 1.2 `wstring` or `wchar`
    /// without a BOM. The specification says big endian, which is the
    /// default; some ORBs use the stream byte order instead.
    pub fn set_wstring_default_order(&mut self, order: ByteOrder) {
        self.wstring_default_order = order;
    }

    /// The byte order of the stream.
    pub fn byte_order(&self) -> ByteOrder {
        self.order
    }

    /// The encoding whose rules apply.
    pub fn encoding(&self) -> Encoding {
        self.encoding
    }

    /// The stream offset of the next byte.
    pub fn position(&self) -> usize {
        let i = self.segments.partition_point(|s| s.start <= self.pos);
        match i.checked_sub(1) {
            Some(i) => {
                let segment = self.segments[i];
                segment.offset + (self.pos - segment.start)
            }
            None => self.base + self.pos,
        }
    }

    /// Bytes left to read.
    pub fn remaining(&self) -> usize {
        self.buf.len() - self.pos
    }

    /// Whether every byte has been read.
    pub fn is_empty(&self) -> bool {
        self.remaining() == 0
    }

    /// The bytes left to read, without consuming them.
    pub fn remaining_bytes(&self) -> &'a [u8] {
        &self.buf[self.pos..]
    }

    /// Skips padding until the stream offset is a multiple of `align`, or
    /// of the encoding's [`max_align`](Encoding::max_align) when that is
    /// smaller.
    ///
    /// Inside a chunked valuetype, a chunk that ends here is followed by
    /// the next one: its length is read and the data aligned in it. In an
    /// XCDR stream the offset counts from the alignment origin (see
    /// [`set_origin`](Decoder::set_origin)).
    pub fn align(&mut self, align: usize) -> Result<()> {
        let align = align.min(self.encoding.max_align());
        loop {
            self.chunk_boundary()?;
            let rem = self.position().wrapping_sub(self.origin) % align;
            if rem == 0 {
                return Ok(());
            }
            // Padding that runs past the end of a chunk continues in the
            // next one, after its length.
            let mut pad = align - rem;
            if let Some(end) = self.chunk_end() {
                pad = pad.min(end - self.pos);
            }
            self.read_octets_raw(pad)?;
        }
    }

    /// The stream offset alignment counts from: 0 unless changed with
    /// [`set_origin`](Decoder::set_origin).
    pub fn origin(&self) -> usize {
        self.origin
    }

    /// Makes alignment count from stream offset `origin`. This is the XCDR
    /// `PUSH(ORIGIN)`; [`read_parameter`](Decoder::read_parameter) does it
    /// itself.
    pub fn set_origin(&mut self, origin: usize) {
        self.origin = origin;
    }

    /// Skips `n` bytes.
    pub fn skip(&mut self, n: usize) -> Result<()> {
        self.read_octets(n).map(|_| ())
    }

    /// Reads `n` raw octets without alignment.
    pub fn read_octets(&mut self, n: usize) -> Result<&'a [u8]> {
        if n > 0 {
            self.chunk_boundary()?;
            self.check_in_chunk(n)?;
        }
        self.read_octets_raw(n)
    }

    /// Skips padding, ignoring chunks.
    pub(crate) fn align_raw(&mut self, align: usize) -> Result<()> {
        let rem = self.position() % align;
        if rem != 0 {
            self.read_octets_raw(align - rem)?;
        }
        Ok(())
    }

    /// Reads an aligned `unsigned long`, ignoring chunks.
    pub(crate) fn read_u32_raw(&mut self) -> Result<u32> {
        self.align_raw(4)?;
        let bytes: [u8; 4] = self
            .read_octets_raw(4)?
            .try_into()
            .expect("read_octets_raw returned 4 bytes");
        Ok(match self.order {
            ByteOrder::Big => u32::from_be_bytes(bytes),
            ByteOrder::Little => u32::from_le_bytes(bytes),
        })
    }

    /// Reads `n` octets, ignoring chunks.
    pub(crate) fn read_octets_raw(&mut self, n: usize) -> Result<&'a [u8]> {
        let remaining = self.remaining();
        if n > remaining {
            return Err(Error::UnexpectedEof {
                needed: n,
                remaining,
            });
        }
        let bytes = &self.buf[self.pos..self.pos + n];
        self.pos += n;
        Ok(bytes)
    }

    fn read_array<const N: usize>(&mut self) -> Result<[u8; N]> {
        let bytes = self.read_octets(N)?;
        Ok(bytes.try_into().expect("read_octets returned N bytes"))
    }

    /// Reads an `octet`.
    pub fn read_octet(&mut self) -> Result<u8> {
        Ok(self.read_array::<1>()?[0])
    }

    /// Reads a `boolean`. Octets other than `0` and `1` are rejected.
    pub fn read_bool(&mut self) -> Result<bool> {
        match self.read_octet()? {
            0 => Ok(false),
            1 => Ok(true),
            other => Err(Error::InvalidBoolean(other)),
        }
    }

    /// Reads a `char` as a single octet in the transmission code set.
    pub fn read_char(&mut self) -> Result<u8> {
        self.read_octet()
    }

    read_number! {
        /// Reads a `short`.
        read_i16: i16;
        /// Reads an `unsigned short`.
        read_u16: u16;
        /// Reads a `long`.
        read_i32: i32;
        /// Reads an `unsigned long`.
        read_u32: u32;
        /// Reads a `long long`.
        read_i64: i64;
        /// Reads an `unsigned long long`.
        read_u64: u64;
        /// Reads a `float`.
        read_f32: f32;
        /// Reads a `double`.
        read_f64: f64;
    }

    /// Reads a `long double`: 16 octets on an 8 octet boundary.
    pub fn read_long_double(&mut self) -> Result<LongDouble> {
        self.align(8)?;
        let bytes = self.read_array()?;
        Ok(LongDouble::from_bits(match self.order {
            ByteOrder::Big => u128::from_be_bytes(bytes),
            ByteOrder::Little => u128::from_le_bytes(bytes),
        }))
    }

    /// Reads a sequence length and checks that `len * min_element_size`
    /// bytes are left, so a corrupt length cannot cause a huge allocation.
    pub fn read_len(&mut self, min_element_size: usize) -> Result<usize> {
        let len = self.read_u32()?;
        let remaining = self.remaining();
        let needed = (len as usize).saturating_mul(min_element_size);
        if needed > remaining {
            return Err(Error::LengthTooLarge { len, remaining });
        }
        Ok(len as usize)
    }

    /// Reads a `sequence<octet>` without copying.
    pub fn read_octet_seq(&mut self) -> Result<&'a [u8]> {
        let len = self.read_len(1)?;
        self.read_octets(len)
    }

    /// Tells the decoder that its bytes lie in `buf`, so that
    /// [`read_octet_seq_shared`](Decoder::read_octet_seq_shared) can share
    /// them.
    pub fn set_shared(&mut self, buf: &'a Arc<Vec<u8>>) {
        self.shared = Some(buf);
    }

    /// Reads a `sequence<octet>` that keeps pointing into the decoder's
    /// buffer, when that is shared (see
    /// [`set_shared`](Decoder::set_shared)) and the sequence is not short;
    /// otherwise a copy.
    pub fn read_octet_seq_shared(&mut self) -> Result<Octets> {
        let len = self.read_len(1)?;
        self.read_octets_shared(len)
    }

    /// Reads `len` raw octets like
    /// [`read_octet_seq_shared`](Decoder::read_octet_seq_shared) reads a
    /// sequence's.
    pub fn read_octets_shared(&mut self, len: usize) -> Result<Octets> {
        let bytes = self.read_octets(len)?;
        if let Some(buf) = self.shared.filter(|_| bytes.len() >= SHARE_MIN) {
            let base = buf.as_ptr() as usize;
            let at = bytes.as_ptr() as usize;
            if at >= base && at + bytes.len() <= base + buf.len() {
                let start = at - base;
                return Ok(Octets::slice_of(
                    Arc::clone(buf),
                    start..start + bytes.len(),
                ));
            }
        }
        Ok(Octets::from(bytes))
    }

    /// Reads a `string` as bytes in the transmission code set, without the
    /// terminating NUL.
    ///
    /// A length of 0 is not allowed by the specification but is accepted as
    /// an empty string, since some ORBs send it.
    pub fn read_string_bytes(&mut self) -> Result<&'a [u8]> {
        let bytes = self.read_octet_seq()?;
        match bytes.split_last() {
            None => Ok(bytes),
            Some((0, rest)) => Ok(rest),
            Some(_) => Err(Error::StringNotTerminated),
        }
    }

    /// Reads a `string` as UTF-8.
    pub fn read_string(&mut self) -> Result<String> {
        let bytes = self.read_string_bytes()?;
        String::from_utf8(bytes.to_vec()).map_err(|_| Error::InvalidUtf8)
    }

    /// Reads a `wchar` holding one UTF-16 code unit.
    pub fn read_wchar(&mut self) -> Result<u16> {
        match self.encoding {
            Encoding::Giop1_0 => Err(Error::WcharNotSupported),
            Encoding::Giop1_1 | Encoding::Xcdr1 | Encoding::Xcdr2 => self.read_u16(),
            Encoding::Giop1_2 => {
                let len = self.read_octet()?;
                if len != 2 && len != 4 {
                    return Err(Error::InvalidWcharLength(len));
                }
                let bytes = self.read_octets(len as usize)?;
                let units = self.utf16_units(bytes);
                match units.as_slice() {
                    [unit] => Ok(*unit),
                    _ => Err(Error::InvalidWcharLength(len)),
                }
            }
        }
    }

    /// Reads a `wstring` encoded as UTF-16.
    ///
    /// For GIOP 1.2 a leading BOM selects the byte order; without one the
    /// order set by [`Decoder::set_wstring_default_order`] is used. XCDR
    /// has an octet length and code units in the stream byte order.
    pub fn read_wstring(&mut self) -> Result<String> {
        match self.encoding {
            Encoding::Giop1_0 => Err(Error::WcharNotSupported),
            Encoding::Xcdr1 | Encoding::Xcdr2 => {
                let len = self.read_len(1)?;
                if len % 2 != 0 {
                    return Err(Error::OddWstringLength(len as u32));
                }
                let mut units = Vec::with_capacity(len / 2);
                for _ in 0..len / 2 {
                    units.push(self.read_u16()?);
                }
                String::from_utf16(&units).map_err(|_| Error::InvalidUtf16)
            }
            Encoding::Giop1_1 => {
                let len = self.read_len(2)?;
                let mut units = Vec::with_capacity(len);
                for _ in 0..len {
                    units.push(self.read_u16()?);
                }
                // The length counts a terminating NUL; tolerate its absence.
                if units.last() == Some(&0) {
                    units.pop();
                }
                String::from_utf16(&units).map_err(|_| Error::InvalidUtf16)
            }
            Encoding::Giop1_2 => {
                let bytes = self.read_octet_seq()?;
                if bytes.len() % 2 != 0 {
                    return Err(Error::OddWstringLength(bytes.len() as u32));
                }
                String::from_utf16(&self.utf16_units(bytes)).map_err(|_| Error::InvalidUtf16)
            }
        }
    }

    /// Splits GIOP 1.2 wide character octets into code units, honouring and
    /// removing a leading BOM.
    fn utf16_units(&self, bytes: &[u8]) -> Vec<u16> {
        let (order, data) = match bytes {
            [0xFE, 0xFF, rest @ ..] => (ByteOrder::Big, rest),
            [0xFF, 0xFE, rest @ ..] => (ByteOrder::Little, rest),
            _ => (self.wstring_default_order, bytes),
        };
        data.chunks_exact(2)
            .map(|c| match order {
                ByteOrder::Big => u16::from_be_bytes([c[0], c[1]]),
                ByteOrder::Little => u16::from_le_bytes([c[0], c[1]]),
            })
            .collect()
    }

    /// Reads an encapsulation and returns a decoder over its contents.
    pub fn read_encapsulation(&mut self) -> Result<Decoder<'a>> {
        let bytes = self.read_octet_seq()?;
        let mut inner = Decoder::encapsulation(bytes, self.encoding)?;
        inner.wstring_default_order = self.wstring_default_order;
        Ok(inner)
    }
}