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