Skip to main content

rustorb_cdr/
value.rs

1//! Valuetype tags, sharing and chunking (CORBA 3.4 part 2, 9.3.4).
2//!
3//! A value is written as a value tag (`0x7fffff00` plus flags), an
4//! optional codebase URL, optional repository ids and its state. `null`
5//! is the tag `0`, and a value written before in the same stream is the
6//! tag `0xffffffff` followed by the offset back to its value tag.
7//!
8//! A chunked value splits its state into chunks, each a positive length
9//! followed by that many octets, and ends with an end tag: the negated
10//! nesting depth. A reader that does not know a truncatable value's type
11//! skips the chunks and nested values it cannot read, up to the end tag.
12//!
13//! Positions are buffer indexes, so a message joined from fragments keeps
14//! its indirections even when the stream offset restarts.
15
16use std::collections::HashMap;
17
18use crate::{Decoder, Encoder, Error, Result};
19
20const VALUE_TAG: u32 = 0x7fff_ff00;
21const CODEBASE: u32 = 0x01;
22const SINGLE_ID: u32 = 0x02;
23const ID_LIST: u32 = 0x06;
24const CHUNKED: u32 = 0x08;
25const INDIRECTION: u32 = 0xffff_ffff;
26
27/// What [`Decoder::read_value_header`] found where a value was expected.
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub enum ValueHeader {
30    /// A `null` value.
31    Null,
32    /// A value read earlier in the stream, by its slot.
33    Indirection(usize),
34    /// A new value, whose state follows. The caller reads the state and
35    /// then calls [`Decoder::end_value`].
36    Value {
37        /// The number of this value in the stream, counting from 0, which
38        /// later indirections refer to.
39        slot: usize,
40        /// The repository ids sent, most derived first; empty when the
41        /// sender left the type to the receiver.
42        ids: Vec<String>,
43        /// Whether the state is chunked.
44        chunked: bool,
45    },
46}
47
48/// Writing state kept in an [`Encoder`] once a value has been written.
49#[derive(Debug, Clone, Default)]
50pub(crate) struct WriteState {
51    /// Buffer index of the value tag of each value written, by key.
52    written: HashMap<u64, usize>,
53    /// Whether each value being written is chunked, outermost first.
54    frames: Vec<bool>,
55    /// Buffer index of the length of the open chunk.
56    chunk: Option<usize>,
57}
58
59/// Reading state kept in a [`Decoder`] once a value has been read.
60#[derive(Debug, Clone, Default)]
61pub(crate) struct ReadState {
62    /// Slot of each value tag read, by buffer index.
63    tags: HashMap<usize, usize>,
64    /// Repository ids and codebase URLs read, by buffer index of their
65    /// length, for indirections to them.
66    strings: HashMap<usize, String>,
67    /// Lists of repository ids read, by buffer index of their count.
68    lists: HashMap<usize, Vec<String>>,
69    /// Values read so far.
70    slots: usize,
71    /// The values being read, outermost first.
72    frames: Vec<Frame>,
73    /// Buffer index of the end of the chunk being read.
74    chunk_end: Option<usize>,
75    /// The depth of the values an end tag has already ended, or `0`.
76    ended: usize,
77}
78
79#[derive(Debug, Clone, Copy)]
80struct Frame {
81    chunked: bool,
82    /// The nesting depth, from 1.
83    depth: usize,
84}
85
86impl Encoder {
87    /// Writes a `null` value.
88    pub fn write_null_value(&mut self) {
89        self.write_u32(0);
90    }
91
92    /// Starts writing a value.
93    ///
94    /// `key` identifies the value: if a value with the same key was
95    /// written before in this stream, an indirection to it is written and
96    /// `false` is returned. Otherwise the value tag and `ids` (repository
97    /// ids, most derived first; none leaves the type to the receiver) are
98    /// written and `true` is returned: the caller writes the state and
99    /// then calls [`Encoder::end_value`].
100    ///
101    /// A value nested in a chunked value is chunked as well.
102    pub fn begin_value(&mut self, key: u64, ids: &[&str], chunked: bool) -> Result<bool> {
103        let state = self.values.get_or_insert_with(Default::default);
104        if let Some(&tag_at) = state.written.get(&key) {
105            self.write_u32(INDIRECTION);
106            let at = self.buf.len();
107            let offset = i32::try_from(tag_at as i64 - at as i64)
108                .map_err(|_| Error::LengthOverflow(at - tag_at))?;
109            self.write_i32(offset);
110            return Ok(false);
111        }
112        let chunked = chunked || state.frames.last() == Some(&true);
113        self.close_chunk();
114        let mut tag = VALUE_TAG;
115        match ids.len() {
116            0 => {}
117            1 => tag |= SINGLE_ID,
118            _ => tag |= ID_LIST,
119        }
120        if chunked {
121            tag |= CHUNKED;
122        }
123        self.align(4);
124        let tag_at = self.buf.len();
125        self.write_u32(tag);
126        if ids.len() > 1 {
127            self.write_len(ids.len())?;
128        }
129        for id in ids {
130            self.write_string(id)?;
131        }
132        let state = self.values.as_mut().expect("made above");
133        state.written.insert(key, tag_at);
134        state.frames.push(chunked);
135        if chunked {
136            self.open_chunk();
137        }
138        Ok(true)
139    }
140
141    /// Ends the value started by the last [`Encoder::begin_value`] that
142    /// returned `true`.
143    pub fn end_value(&mut self) -> Result<()> {
144        let state = self
145            .values
146            .as_mut()
147            .ok_or(Error::InvalidValue("end_value without begin_value"))?;
148        let depth = state.frames.len();
149        let chunked = state
150            .frames
151            .pop()
152            .ok_or(Error::InvalidValue("end_value without begin_value"))?;
153        let outer_chunked = state.frames.last() == Some(&true);
154        if chunked {
155            self.close_chunk();
156            let depth = i32::try_from(depth).map_err(|_| Error::LengthOverflow(depth))?;
157            self.write_i32(-depth);
158            if outer_chunked {
159                self.open_chunk();
160            }
161        }
162        Ok(())
163    }
164
165    /// Starts a chunk, whose length is filled in when it is closed.
166    fn open_chunk(&mut self) {
167        self.align(4);
168        let at = self.buf.len();
169        self.write_u32(0);
170        if let Some(state) = self.values.as_mut() {
171            state.chunk = Some(at);
172        }
173    }
174
175    /// Fills in the length of the open chunk, or drops it if it is empty.
176    fn close_chunk(&mut self) {
177        let Some(at) = self.values.as_mut().and_then(|s| s.chunk.take()) else {
178            return;
179        };
180        let len = self.buf.len() - (at + 4);
181        if len == 0 {
182            self.buf.truncate(at);
183        } else {
184            let len = len as u32;
185            let bytes = match self.order {
186                crate::ByteOrder::Big => len.to_be_bytes(),
187                crate::ByteOrder::Little => len.to_le_bytes(),
188            };
189            self.buf[at..at + 4].copy_from_slice(&bytes);
190        }
191    }
192}
193
194impl Decoder<'_> {
195    /// Reads what stands where a value is expected: `null`, an indirection
196    /// to a value read before, or the header of a new value.
197    ///
198    /// After [`ValueHeader::Value`], the caller reads the state and then
199    /// calls [`Decoder::end_value`].
200    pub fn read_value_header(&mut self) -> Result<ValueHeader> {
201        let state = self.values.get_or_insert_with(Default::default);
202        let outer_chunked = state.frames.last().is_some_and(|f| f.chunked);
203        let (at, tag, in_chunk) = self.read_value_tag(outer_chunked)?;
204        match tag {
205            0 => Ok(ValueHeader::Null),
206            INDIRECTION => {
207                let offset_at = self.pos;
208                let offset = if in_chunk {
209                    self.read_i32()?
210                } else {
211                    self.read_u32_raw()? as i32
212                };
213                let target = offset_at as i64 + i64::from(offset);
214                let slot = usize::try_from(target)
215                    .ok()
216                    .and_then(|target| self.state().tags.get(&target).copied())
217                    .ok_or(Error::InvalidValue("indirection to no value"))?;
218                Ok(ValueHeader::Indirection(slot))
219            }
220            tag if tag & 0xffff_fff0 == VALUE_TAG => {
221                if in_chunk {
222                    return Err(Error::InvalidValue("value tag inside a chunk"));
223                }
224                let chunked = tag & CHUNKED != 0;
225                if outer_chunked && !chunked {
226                    return Err(Error::InvalidValue("unchunked value in a chunked value"));
227                }
228                if tag & CODEBASE != 0 {
229                    self.read_shared_string()?;
230                }
231                let ids = match tag & ID_LIST {
232                    0 => Vec::new(),
233                    SINGLE_ID => vec![self.read_shared_string()?],
234                    ID_LIST => self.read_id_list()?,
235                    _ => return Err(Error::InvalidValue("invalid value tag")),
236                };
237                let state = self.state();
238                let slot = state.slots;
239                state.slots += 1;
240                state.tags.insert(at, slot);
241                let depth = state.frames.len() + 1;
242                state.frames.push(Frame { chunked, depth });
243                state.chunk_end = None;
244                Ok(ValueHeader::Value { slot, ids, chunked })
245            }
246            _ => Err(Error::InvalidValue("invalid value tag")),
247        }
248    }
249
250    /// Ends the value whose header was read last and is not yet ended.
251    ///
252    /// For a chunked value, the rest of its state (chunks and nested
253    /// values a truncating reader did not read) is skipped up to its end
254    /// tag.
255    pub fn end_value(&mut self) -> Result<()> {
256        let frame = *self
257            .values
258            .as_ref()
259            .and_then(|s| s.frames.last())
260            .ok_or(Error::InvalidValue("end_value without a value"))?;
261        if frame.chunked {
262            let ended = self.state().ended;
263            if ended == 0 || ended > frame.depth {
264                self.skip_to_end_tag(frame.depth)?;
265            }
266        }
267        let state = self.state();
268        state.frames.pop();
269        state.chunk_end = None;
270        if state.frames.last().is_none_or(|f| f.depth < state.ended) {
271            state.ended = 0;
272        }
273        Ok(())
274    }
275
276    /// Skips the rest of a chunked value at `depth` and reads its end tag.
277    fn skip_to_end_tag(&mut self, depth: usize) -> Result<()> {
278        loop {
279            if let Some(end) = self.state().chunk_end.take() {
280                if end > self.pos {
281                    self.pos = end;
282                }
283            }
284            self.align_raw(4)?;
285            let at = self.pos;
286            let tag = self.read_u32_raw()?;
287            match tag {
288                // A null value between chunks.
289                0 => {}
290                tag if tag >= 0x8000_0000 => {
291                    // An end tag ends this value and the values nested in
292                    // it; some writers count only chunked values, so a
293                    // deeper tag still ends this one.
294                    let ended = (tag as i32).unsigned_abs() as usize;
295                    self.state().ended = ended.min(depth);
296                    return Ok(());
297                }
298                tag if tag < VALUE_TAG => self.enter_chunk(tag)?,
299                _ => {
300                    self.pos = at;
301                    if let ValueHeader::Value { .. } = self.read_value_header()? {
302                        self.end_value()?;
303                    }
304                }
305            }
306        }
307    }
308
309    /// Reads a value tag, entering chunks before it. Returns the buffer
310    /// index of the tag, the tag, and whether it was inside a chunk.
311    fn read_value_tag(&mut self, outer_chunked: bool) -> Result<(usize, u32, bool)> {
312        loop {
313            if outer_chunked {
314                if let Some(end) = self.chunk_end() {
315                    let rem = self.position() % 4;
316                    if rem != 0 {
317                        let pad = (4 - rem).min(end - self.pos);
318                        self.read_octets_raw(pad)?;
319                    }
320                    if self.pos < end {
321                        self.check_in_chunk(4)?;
322                        let at = self.pos;
323                        return Ok((at, self.read_u32_raw()?, true));
324                    }
325                    self.state().chunk_end = None;
326                }
327            }
328            self.align_raw(4)?;
329            let at = self.pos;
330            let tag = self.read_u32_raw()?;
331            if outer_chunked && tag != 0 && tag < VALUE_TAG {
332                self.enter_chunk(tag)?;
333                continue;
334            }
335            return Ok((at, tag, false));
336        }
337    }
338
339    /// Starts a chunk of `len` octets at the current position.
340    fn enter_chunk(&mut self, len: u32) -> Result<()> {
341        let remaining = self.remaining();
342        if len as usize > remaining {
343            return Err(Error::LengthTooLarge { len, remaining });
344        }
345        let end = self.pos + len as usize;
346        self.state().chunk_end = Some(end);
347        Ok(())
348    }
349
350    /// Reads a repository id or codebase URL, which may be an indirection
351    /// to the same string read before.
352    fn read_shared_string(&mut self) -> Result<String> {
353        self.align_raw(4)?;
354        let at = self.pos;
355        let len = self.read_u32_raw()?;
356        if len == INDIRECTION {
357            let target = self.read_offset()?;
358            return self
359                .state()
360                .strings
361                .get(&target)
362                .cloned()
363                .ok_or(Error::InvalidValue("indirection to no repository id"));
364        }
365        let remaining = self.remaining();
366        if len as usize > remaining {
367            return Err(Error::LengthTooLarge { len, remaining });
368        }
369        let bytes = self.read_octets_raw(len as usize)?;
370        let bytes = match bytes.split_last() {
371            None => bytes,
372            Some((0, rest)) => rest,
373            Some(_) => return Err(Error::StringNotTerminated),
374        };
375        let s = String::from_utf8(bytes.to_vec()).map_err(|_| Error::InvalidUtf8)?;
376        self.state().strings.insert(at, s.clone());
377        Ok(s)
378    }
379
380    /// Reads a list of repository ids, which may be an indirection to the
381    /// same list read before.
382    fn read_id_list(&mut self) -> Result<Vec<String>> {
383        self.align_raw(4)?;
384        let at = self.pos;
385        let count = self.read_u32_raw()?;
386        if count == INDIRECTION {
387            let target = self.read_offset()?;
388            return self
389                .state()
390                .lists
391                .get(&target)
392                .cloned()
393                .ok_or(Error::InvalidValue("indirection to no repository id list"));
394        }
395        let remaining = self.remaining();
396        if (count as usize).saturating_mul(4) > remaining {
397            return Err(Error::LengthTooLarge {
398                len: count,
399                remaining,
400            });
401        }
402        let ids = (0..count)
403            .map(|_| self.read_shared_string())
404            .collect::<Result<Vec<_>>>()?;
405        self.state().lists.insert(at, ids.clone());
406        Ok(ids)
407    }
408
409    /// Reads an indirection offset outside chunks and returns the buffer
410    /// index it points to.
411    fn read_offset(&mut self) -> Result<usize> {
412        let at = self.pos;
413        let offset = self.read_u32_raw()? as i32;
414        usize::try_from(at as i64 + i64::from(offset))
415            .map_err(|_| Error::InvalidValue("indirection before the stream"))
416    }
417
418    /// Before data is read in a chunked value: if no chunk is open, or the
419    /// open one ended, reads the length of the next chunk.
420    pub(crate) fn chunk_boundary(&mut self) -> Result<()> {
421        if !self.in_chunked_value() {
422            return Ok(());
423        }
424        loop {
425            if self.chunk_end().is_some_and(|end| self.pos < end) {
426                return Ok(());
427            }
428            let len = self.read_u32_raw()?;
429            if len >= VALUE_TAG {
430                return Err(Error::InvalidValue("chunk expected"));
431            }
432            self.enter_chunk(len)?;
433        }
434    }
435
436    /// Fails if `n` octets do not fit in the open chunk.
437    pub(crate) fn check_in_chunk(&self, n: usize) -> Result<()> {
438        match self.chunk_end() {
439            Some(end) if self.pos + n > end => Err(Error::InvalidValue("data crosses a chunk end")),
440            _ => Ok(()),
441        }
442    }
443
444    /// The buffer index where the open chunk ends, inside a chunked value.
445    pub(crate) fn chunk_end(&self) -> Option<usize> {
446        if self.in_chunked_value() {
447            self.values.as_ref().and_then(|s| s.chunk_end)
448        } else {
449            None
450        }
451    }
452
453    fn in_chunked_value(&self) -> bool {
454        self.values
455            .as_ref()
456            .and_then(|s| s.frames.last())
457            .is_some_and(|f| f.chunked)
458    }
459
460    fn state(&mut self) -> &mut ReadState {
461        self.values.get_or_insert_with(Default::default)
462    }
463}
464
465#[cfg(test)]
466mod tests {
467    use super::*;
468    use crate::{ByteOrder, CdrVersion};
469
470    fn encoder(order: ByteOrder) -> Encoder {
471        Encoder::new(order, CdrVersion::Giop1_2)
472    }
473
474    fn decoder(bytes: &[u8], order: ByteOrder) -> Decoder<'_> {
475        Decoder::new(bytes, order, CdrVersion::Giop1_2)
476    }
477
478    #[test]
479    fn plain_value_and_sharing() {
480        for order in [ByteOrder::Big, ByteOrder::Little] {
481            let mut enc = encoder(order);
482            enc.write_octet(7);
483            assert!(enc.begin_value(1, &["IDL:V:1.0"], false).unwrap());
484            enc.write_i32(42);
485            enc.write_f64(1.5);
486            enc.end_value().unwrap();
487            assert!(!enc.begin_value(1, &["IDL:V:1.0"], false).unwrap());
488            enc.write_null_value();
489            enc.write_u16(9);
490            let bytes = enc.into_bytes();
491            assert_eq!(&bytes[4..8], &tag_bytes(0x7fffff02, order));
492
493            let mut dec = decoder(&bytes, order);
494            assert_eq!(dec.read_octet().unwrap(), 7);
495            assert_eq!(
496                dec.read_value_header().unwrap(),
497                ValueHeader::Value {
498                    slot: 0,
499                    ids: vec!["IDL:V:1.0".into()],
500                    chunked: false
501                }
502            );
503            assert_eq!(dec.read_i32().unwrap(), 42);
504            assert_eq!(dec.read_f64().unwrap(), 1.5);
505            dec.end_value().unwrap();
506            assert_eq!(
507                dec.read_value_header().unwrap(),
508                ValueHeader::Indirection(0)
509            );
510            assert_eq!(dec.read_value_header().unwrap(), ValueHeader::Null);
511            assert_eq!(dec.read_u16().unwrap(), 9);
512            assert!(dec.is_empty());
513        }
514    }
515
516    fn tag_bytes(tag: u32, order: ByteOrder) -> [u8; 4] {
517        match order {
518            ByteOrder::Big => tag.to_be_bytes(),
519            ByteOrder::Little => tag.to_le_bytes(),
520        }
521    }
522
523    #[test]
524    fn chunked_values_nest() {
525        let order = ByteOrder::Big;
526        let mut enc = encoder(order);
527        assert!(
528            enc.begin_value(1, &["IDL:D:1.0", "IDL:B:1.0"], true)
529                .unwrap()
530        );
531        enc.write_i32(1);
532        // An unchunked request inside a chunked value is chunked.
533        assert!(enc.begin_value(2, &["IDL:N:1.0"], false).unwrap());
534        enc.write_f64(2.0);
535        enc.write_null_value();
536        assert!(!enc.begin_value(1, &[], false).unwrap());
537        enc.end_value().unwrap();
538        enc.write_octet(3);
539        enc.end_value().unwrap();
540        enc.write_i32(4);
541        let bytes = enc.into_bytes();
542
543        let mut dec = decoder(&bytes, order);
544        assert_eq!(
545            dec.read_value_header().unwrap(),
546            ValueHeader::Value {
547                slot: 0,
548                ids: vec!["IDL:D:1.0".into(), "IDL:B:1.0".into()],
549                chunked: true
550            }
551        );
552        assert_eq!(dec.read_i32().unwrap(), 1);
553        assert_eq!(
554            dec.read_value_header().unwrap(),
555            ValueHeader::Value {
556                slot: 1,
557                ids: vec!["IDL:N:1.0".into()],
558                chunked: true
559            }
560        );
561        assert_eq!(dec.read_f64().unwrap(), 2.0);
562        assert_eq!(dec.read_value_header().unwrap(), ValueHeader::Null);
563        assert_eq!(
564            dec.read_value_header().unwrap(),
565            ValueHeader::Indirection(0)
566        );
567        dec.end_value().unwrap();
568        assert_eq!(dec.read_octet().unwrap(), 3);
569        dec.end_value().unwrap();
570        assert_eq!(dec.read_i32().unwrap(), 4);
571        assert!(dec.is_empty());
572    }
573
574    #[test]
575    fn truncation_skips_unread_state() {
576        let order = ByteOrder::Little;
577        let mut enc = encoder(order);
578        assert!(
579            enc.begin_value(1, &["IDL:D:1.0", "IDL:B:1.0"], true)
580                .unwrap()
581        );
582        enc.write_i32(1);
583        // State of the derived type, with a nested value, that a reader
584        // knowing only the base type skips.
585        enc.write_string("derived").unwrap();
586        assert!(enc.begin_value(2, &["IDL:N:1.0"], false).unwrap());
587        enc.write_f64(2.0);
588        enc.end_value().unwrap();
589        enc.write_octet(5);
590        enc.end_value().unwrap();
591        enc.write_i32(4);
592        let bytes = enc.into_bytes();
593
594        let mut dec = decoder(&bytes, order);
595        assert!(matches!(
596            dec.read_value_header().unwrap(),
597            ValueHeader::Value { chunked: true, .. }
598        ));
599        assert_eq!(dec.read_i32().unwrap(), 1);
600        dec.end_value().unwrap();
601        assert_eq!(dec.read_i32().unwrap(), 4);
602        assert!(dec.is_empty());
603    }
604
605    /// A stream written by hand: data split across chunks in the middle
606    /// of padding, a merged end tag, and repository ids by indirection.
607    #[test]
608    fn reads_other_writers_forms() {
609        let mut b: Vec<u8> = Vec::new();
610        let long = |b: &mut Vec<u8>, v: u32| b.extend_from_slice(&v.to_be_bytes());
611        // Outer chunked value with one id.
612        long(&mut b, 0x7fffff0a);
613        long(&mut b, 4);
614        b.extend_from_slice(b"IDL\0");
615        let id_at = 4;
616        // A chunk holding an octet only.
617        long(&mut b, 1);
618        b.push(1);
619        b.extend_from_slice(&[0; 3]);
620        // The next chunk holds the long that follows the octet.
621        long(&mut b, 4);
622        long(&mut b, 2);
623        // Nested chunked value whose id is an indirection.
624        long(&mut b, 0x7fffff0a);
625        long(&mut b, 0xffffffff);
626        let at = b.len();
627        long(&mut b, (id_at as i64 - at as i64) as i32 as u32);
628        long(&mut b, 2);
629        b.extend_from_slice(&[0x12, 0x34]);
630        // One end tag ends both values.
631        b.extend_from_slice(&[0; 2]);
632        long(&mut b, -1i32 as u32);
633        long(&mut b, 9);
634
635        let mut dec = decoder(&b, ByteOrder::Big);
636        assert!(matches!(
637            dec.read_value_header().unwrap(),
638            ValueHeader::Value { ref ids, .. } if ids == &["IDL"]
639        ));
640        assert_eq!(dec.read_octet().unwrap(), 1);
641        assert_eq!(dec.read_i32().unwrap(), 2);
642        assert!(matches!(
643            dec.read_value_header().unwrap(),
644            ValueHeader::Value { slot: 1, ref ids, .. } if ids == &["IDL"]
645        ));
646        assert_eq!(dec.read_u16().unwrap(), 0x1234);
647        dec.end_value().unwrap();
648        dec.end_value().unwrap();
649        assert_eq!(dec.read_u32().unwrap(), 9);
650        assert!(dec.is_empty());
651    }
652
653    #[test]
654    fn rejects_bad_streams() {
655        let mut dec = decoder(&[0x7f, 0xff, 0xff, 0x10], ByteOrder::Big);
656        assert!(dec.read_value_header().is_err());
657        let mut dec = decoder(&[0xff, 0xff, 0xff, 0xff, 0, 0, 0, 0], ByteOrder::Big);
658        assert!(dec.read_value_header().is_err());
659        // Data past the end of the last chunk.
660        let mut b = Vec::new();
661        b.extend_from_slice(&0x7fffff08u32.to_be_bytes());
662        b.extend_from_slice(&2u32.to_be_bytes());
663        b.extend_from_slice(&[0, 0]);
664        b.extend_from_slice(&[0, 0]);
665        b.extend_from_slice(&(-1i32).to_be_bytes());
666        let mut dec = decoder(&b, ByteOrder::Big);
667        dec.read_value_header().unwrap();
668        assert!(dec.read_i32().is_err());
669        let mut enc = encoder(ByteOrder::Big);
670        assert!(enc.end_value().is_err());
671    }
672}