Skip to main content

rhue_bytecode/
serial.rs

1//! A compact binary form of a compiled chunk, so a host can compile once
2//! and load it a bunch of times without parsing, resolving or type-checking.
3//!
4//! ```text
5//! chunk   := MAGIC version:u8 name:str text:str types proto
6//! types   := 0 | 1 returns:str [name:str type:str] [alias:str]
7//!            (version 2 on; the aliases from version 3)
8//! proto   := flags:u8 [name:str] code:[u32] constants:[constant]
9//!            spans:[span] max_stack:u8 num_params:u8 protos:[proto]
10//!            upvalues:[in_stack:u8 index:u8 name:str]
11//!            locals:[name:str reg:u8 start:uv end:uv]
12//!            [templates:[array:uv hash:uv keys:[uv]]] span
13//!            (templates when flag 4 is set, from version 4)
14//! constant:= 0 f64 | 1 str
15//! span    := start:uv len:uv
16//! str     := len:uv bytes          [x] := count:uv x*
17//! ```
18//!
19//! `uv` is an unsigned LEB128 integer. The source text stays in so runtime
20//! errors and debuggers can still point at lines. The optional types are
21//! Luau type syntax (what the chunk returns and the globals it defines) so
22//! a loaded chunk or module keeps its types for the checker. This crate
23//! just carries them around.
24//!
25//! Loading only checks the *shape* of the bytes (lengths fit, strings are
26//! UTF-8, nesting is bounded, spans are inside the text). Whether the code
27//! is safe to run is the [verifier](crate::verify)'s job, and hosts have
28//! to run it on every loaded chunk (`Engine::load` does).
29
30use std::fmt;
31use std::rc::Rc;
32
33use rhue_common::{SourceFile, Span};
34
35use crate::{Constant, Instr, LocalVar, Proto, TableTemplate, UpvalDesc};
36
37/// The first bytes of every serialized chunk.
38pub const MAGIC: &[u8; 5] = b"\x1bRhue";
39
40/// Bumped whenever the encoding or instruction set changes. Chunks from a newer
41/// version get refused instead of misread (older versions are subsets of this
42/// one and still load).
43pub const FORMAT_VERSION: u8 = 4;
44
45/// The types saved with a chunk, as Luau type syntax.
46#[derive(Clone, Debug, Default, PartialEq)]
47pub struct ChunkTypes {
48    /// `type Name = ...` definitions the types below can refer to (so recursive
49    /// types and classes save exactly).
50    pub aliases: Vec<String>,
51    /// What the chunk returns (its type as a module).
52    pub returns: String,
53    /// The globals it defines, and their types.
54    pub globals: Vec<(String, String)>,
55}
56
57/// How deep functions can nest in a loaded chunk (same as the parser's limit).
58const MAX_NESTING: u32 = 1000;
59
60/// Why some bytes couldn't load as a chunk.
61#[derive(Clone, Debug, PartialEq)]
62pub struct LoadError {
63    pub offset: usize,
64    pub message: String,
65}
66
67impl fmt::Display for LoadError {
68    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69        write!(f, "{} (at byte {})", self.message, self.offset)
70    }
71}
72
73impl std::error::Error for LoadError {}
74
75/// Whether `bytes` start like a saved chunk.
76pub fn is_chunk(bytes: &[u8]) -> bool {
77    bytes.starts_with(MAGIC)
78}
79
80impl Proto {
81    /// Saves this main chunk (and everything nested in it), without types (see
82    /// [`write_chunk`]).
83    pub fn to_bytes(&self) -> Vec<u8> {
84        write_chunk(self, None)
85    }
86
87    /// Reads a chunk written by [`to_bytes`](Self::to_bytes) or
88    /// [`write_chunk`], ignoring any types. It's *not* verified, run
89    /// [`verify`](crate::verify) before executing it.
90    pub fn from_bytes(bytes: &[u8]) -> Result<Rc<Proto>, LoadError> {
91        read_chunk(bytes).map(|(p, _)| p)
92    }
93}
94
95/// Saves a main chunk, plus the types it exports if you give them.
96pub fn write_chunk(proto: &Proto, types: Option<&ChunkTypes>) -> Vec<u8> {
97    let mut w = Writer(Vec::with_capacity(64 + proto.source.text.len()));
98    w.0.extend_from_slice(MAGIC);
99    w.0.push(FORMAT_VERSION);
100    w.str(&proto.source.name);
101    w.str(&proto.source.text);
102    match types {
103        None => w.0.push(0),
104        Some(t) => {
105            w.0.push(1);
106            w.str(&t.returns);
107            w.uv(t.globals.len() as u64);
108            for (n, ty) in &t.globals {
109                w.str(n);
110                w.str(ty);
111            }
112            w.uv(t.aliases.len() as u64);
113            for a in &t.aliases {
114                w.str(a);
115            }
116        }
117    }
118    w.proto(proto);
119    w.0
120}
121
122/// Reads a chunk and the types saved with it (none for chunks saved without, or
123/// in format 1). Not verified.
124pub fn read_chunk(bytes: &[u8]) -> Result<(Rc<Proto>, Option<ChunkTypes>), LoadError> {
125    let mut r = Reader { bytes, pos: 0 };
126    if !is_chunk(bytes) {
127        return Err(r.fail("not a compiled Rhue chunk"));
128    }
129    r.pos = MAGIC.len();
130    let version = r.u8()?;
131    if !(1..=FORMAT_VERSION).contains(&version) {
132        return Err(LoadError {
133            offset: MAGIC.len(),
134            message: format!(
135                "compiled for bytecode format {version}, but this Rhue reads formats 1 to {FORMAT_VERSION}"
136            ),
137        });
138    }
139    let name = r.str()?;
140    let text = r.str()?;
141    let types = if version >= 2 {
142        match r.u8()? {
143            0 => None,
144            1 => {
145                let returns = r.str()?.to_string();
146                let n = r.count(2)?;
147                let mut globals = Vec::with_capacity(n);
148                for _ in 0..n {
149                    globals.push((r.str()?.to_string(), r.str()?.to_string()));
150                }
151                let mut aliases = Vec::new();
152                if version >= 3 {
153                    let n = r.count(1)?;
154                    for _ in 0..n {
155                        aliases.push(r.str()?.to_string());
156                    }
157                }
158                Some(ChunkTypes {
159                    aliases,
160                    returns,
161                    globals,
162                })
163            }
164            _ => return Err(r.fail("bad types flag")),
165        }
166    } else {
167        None
168    };
169    let source = SourceFile::new(name, text);
170    let proto = r.proto(&source, 0)?;
171    if r.pos != bytes.len() {
172        return Err(r.fail("trailing bytes after the chunk"));
173    }
174    Ok((Rc::new(proto), types))
175}
176
177struct Writer(Vec<u8>);
178
179impl Writer {
180    fn uv(&mut self, mut n: u64) {
181        loop {
182            let byte = (n & 0x7f) as u8;
183            n >>= 7;
184            if n == 0 {
185                self.0.push(byte);
186                return;
187            }
188            self.0.push(byte | 0x80);
189        }
190    }
191
192    fn str(&mut self, s: &str) {
193        self.uv(s.len() as u64);
194        self.0.extend_from_slice(s.as_bytes());
195    }
196
197    fn span(&mut self, s: Span) {
198        self.uv(s.start as u64);
199        self.uv(s.end.saturating_sub(s.start) as u64);
200    }
201
202    fn proto(&mut self, p: &Proto) {
203        let flags = p.is_vararg as u8
204            | (p.name.is_some() as u8) << 1
205            | (!p.templates.is_empty() as u8) << 2;
206        self.0.push(flags);
207        if let Some(name) = &p.name {
208            self.str(name);
209        }
210        self.uv(p.code.len() as u64);
211        for ins in &p.code {
212            self.0.extend_from_slice(&ins.0.to_le_bytes());
213        }
214        self.uv(p.constants.len() as u64);
215        for k in &p.constants {
216            match k {
217                Constant::Number(n) => {
218                    self.0.push(0);
219                    self.0.extend_from_slice(&n.to_le_bytes());
220                }
221                Constant::String(s) => {
222                    self.0.push(1);
223                    self.str(s);
224                }
225            }
226        }
227        self.uv(p.spans.len() as u64);
228        for s in &p.spans {
229            self.span(*s);
230        }
231        self.0.push(p.max_stack);
232        self.0.push(p.num_params);
233        self.uv(p.protos.len() as u64);
234        for child in &p.protos {
235            self.proto(child);
236        }
237        self.uv(p.upvalues.len() as u64);
238        for up in &p.upvalues {
239            self.0.push(up.in_stack as u8);
240            self.0.push(up.index);
241            self.str(&up.name);
242        }
243        self.uv(p.locals.len() as u64);
244        for l in &p.locals {
245            self.str(&l.name);
246            self.0.push(l.reg);
247            self.uv(l.start_pc as u64);
248            self.uv(l.end_pc as u64);
249        }
250        if !p.templates.is_empty() {
251            self.uv(p.templates.len() as u64);
252            for t in &p.templates {
253                self.uv(t.array as u64);
254                self.uv(t.hash as u64);
255                self.uv(t.keys.len() as u64);
256                for &k in &t.keys {
257                    self.uv(k as u64);
258                }
259            }
260        }
261        self.span(p.span);
262    }
263}
264
265struct Reader<'a> {
266    bytes: &'a [u8],
267    pos: usize,
268}
269
270impl Reader<'_> {
271    fn fail(&self, message: &str) -> LoadError {
272        LoadError {
273            offset: self.pos,
274            message: message.to_string(),
275        }
276    }
277
278    fn take(&mut self, n: usize) -> Result<&[u8], LoadError> {
279        if self.bytes.len() - self.pos < n {
280            return Err(self.fail("unexpected end of the chunk"));
281        }
282        let s = &self.bytes[self.pos..self.pos + n];
283        self.pos += n;
284        Ok(s)
285    }
286
287    fn u8(&mut self) -> Result<u8, LoadError> {
288        Ok(self.take(1)?[0])
289    }
290
291    fn uv(&mut self) -> Result<u64, LoadError> {
292        let mut n: u64 = 0;
293        for shift in (0..64).step_by(7) {
294            let b = self.u8()?;
295            n |= ((b & 0x7f) as u64) << shift;
296            if b & 0x80 == 0 {
297                return Ok(n);
298            }
299        }
300        Err(self.fail("integer too long"))
301    }
302
303    fn u32(&mut self) -> Result<u32, LoadError> {
304        let n = self.uv()?;
305        u32::try_from(n).map_err(|_| self.fail("number out of range"))
306    }
307
308    /// A count of items that are each at least `min_size` bytes, checked
309    /// against what's left so a damaged length can't allocate like crazy.
310    fn count(&mut self, min_size: usize) -> Result<usize, LoadError> {
311        let n = self.uv()?;
312        let left = (self.bytes.len() - self.pos) as u64;
313        if n.saturating_mul(min_size as u64) > left {
314            return Err(self.fail("length runs past the end of the chunk"));
315        }
316        Ok(n as usize)
317    }
318
319    fn str(&mut self) -> Result<Rc<str>, LoadError> {
320        let n = self.count(1)?;
321        let start = self.pos;
322        let bytes = self.take(n)?;
323        std::str::from_utf8(bytes)
324            .map(Rc::from)
325            .map_err(|_| LoadError {
326                offset: start,
327                message: "string isn't UTF-8".into(),
328            })
329    }
330
331    fn span(&mut self, text_len: u32) -> Result<Span, LoadError> {
332        let start = self.u32()?;
333        let len = self.u32()?;
334        match start.checked_add(len) {
335            Some(end) if end <= text_len => Ok(Span::new(start, end)),
336            _ => Err(self.fail("span outside the source text")),
337        }
338    }
339
340    fn proto(&mut self, source: &Rc<SourceFile>, depth: u32) -> Result<Proto, LoadError> {
341        if depth > MAX_NESTING {
342            return Err(self.fail("functions nested too deeply"));
343        }
344        let text_len = source.text.len() as u32;
345        let flags = self.u8()?;
346        if flags & !0b111 != 0 {
347            return Err(self.fail("unknown prototype flags"));
348        }
349        let name = if flags & 2 != 0 {
350            Some(self.str()?)
351        } else {
352            None
353        };
354        let n = self.count(4)?;
355        let mut code = Vec::with_capacity(n);
356        for _ in 0..n {
357            let b = self.take(4)?;
358            code.push(Instr(u32::from_le_bytes([b[0], b[1], b[2], b[3]])));
359        }
360        let n = self.count(2)?;
361        let mut constants = Vec::with_capacity(n);
362        for _ in 0..n {
363            constants.push(match self.u8()? {
364                0 => {
365                    let b = self.take(8)?;
366                    Constant::Number(f64::from_le_bytes(b.try_into().unwrap()))
367                }
368                1 => Constant::String(self.str()?),
369                _ => return Err(self.fail("unknown constant kind")),
370            });
371        }
372        let n = self.count(2)?;
373        let mut spans = Vec::with_capacity(n);
374        for _ in 0..n {
375            spans.push(self.span(text_len)?);
376        }
377        let max_stack = self.u8()?;
378        let num_params = self.u8()?;
379        let n = self.count(1)?;
380        let mut protos = Vec::with_capacity(n);
381        for _ in 0..n {
382            protos.push(Rc::new(self.proto(source, depth + 1)?));
383        }
384        let n = self.count(3)?;
385        let mut upvalues = Vec::with_capacity(n);
386        for _ in 0..n {
387            let in_stack = match self.u8()? {
388                0 => false,
389                1 => true,
390                _ => return Err(self.fail("bad upvalue kind")),
391            };
392            let index = self.u8()?;
393            let name = self.str()?;
394            upvalues.push(UpvalDesc {
395                in_stack,
396                index,
397                name,
398            });
399        }
400        let n = self.count(4)?;
401        let mut locals = Vec::with_capacity(n);
402        for _ in 0..n {
403            let name = self.str()?;
404            let reg = self.u8()?;
405            let start_pc = self.u32()?;
406            let end_pc = self.u32()?;
407            locals.push(LocalVar {
408                name,
409                reg,
410                start_pc,
411                end_pc,
412            });
413        }
414        let mut templates = Vec::new();
415        if flags & 4 != 0 {
416            let n = self.count(3)?;
417            templates.reserve(n);
418            for _ in 0..n {
419                let array = self.u32()?;
420                let hash = self.u32()?;
421                let n = self.count(1)?;
422                let mut keys = Vec::with_capacity(n);
423                for _ in 0..n {
424                    keys.push(self.u32()?);
425                }
426                templates.push(TableTemplate { array, hash, keys });
427            }
428        }
429        let span = self.span(text_len)?;
430        Ok(Proto {
431            templates,
432            name,
433            code,
434            constants,
435            spans,
436            max_stack,
437            num_params,
438            is_vararg: flags & 1 != 0,
439            protos,
440            upvalues,
441            locals,
442            span,
443            source: source.clone(),
444            ..Proto::default()
445        })
446    }
447}