kobako 0.26.0 → 0.28.0

data/crates/kobako-transport/src/envelope/compile_reply.rs

@@ -0,0 +1,139 @@
+//! The answer to a compile downcall.
+//!
+//! Only the guest can compile its own source, so the host learns the
+//! bytecode, or why there is none, from this answer alone.
+
+use super::bytes::{Reader, Writer};
+use super::{tag, DecodeError, ErrorRecord, Unsupported};
+
+/// How compiling the Preamble's source Snippets ended.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CompileReply {
+    /// One bytecode per source Snippet, in the Preamble's order.
+    Ok(Vec<Vec<u8>>),
+    /// A Snippet did not compile, or a Flag could not be applied first.
+    Error(ErrorRecord),
+    /// The guest does not compile.
+    Unsupported(Unsupported),
+}
+
+impl CompileReply {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        match reader.u8()? {
+            tag::OK => {
+                let bytecodes = reader.bytes_list()?;
+                reader.finish()?;
+                Ok(CompileReply::Ok(bytecodes))
+            }
+            tag::ERROR => {
+                let record = ErrorRecord::read(&mut reader)?;
+                reader.finish()?;
+                Ok(CompileReply::Error(record))
+            }
+            tag::UNSUPPORTED => Ok(CompileReply::Unsupported(Unsupported::read(&mut reader)?)),
+            _ => Err(DecodeError::new(
+                "Compile Reply tag must be 0x10 (ok), 0x13 (error), or 0x15 (unsupported)",
+            )),
+        }
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self {
+            CompileReply::Ok(bytecodes) => {
+                writer.u8(tag::OK).list(bytecodes);
+            }
+            CompileReply::Error(record) => {
+                writer.u8(tag::ERROR);
+                record.write(&mut writer);
+            }
+            CompileReply::Unsupported(refusal) => return refusal.encode(),
+        }
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // @behavior WE-085
+    #[test]
+    fn every_compile_reply_arm_round_trips() {
+        for reply in [
+            CompileReply::Ok(vec![vec![0x52, 0x49], Vec::new()]),
+            CompileReply::Ok(Vec::new()),
+            CompileReply::Error(ErrorRecord {
+                name: "SyntaxError".into(),
+                message: "unexpected end".into(),
+                backtrace: vec!["(snippet:A):1".into()],
+            }),
+            CompileReply::Unsupported(Unsupported::new("not compiled here")),
+        ] {
+            assert_eq!(
+                CompileReply::decode(&reply.encode()),
+                Ok(reply),
+                "a Compile Reply through encode and decode must arrive as it was given on \
+                 every arm"
+            );
+        }
+    }
+
+    // @behavior WE-086
+    #[test]
+    fn golden_layout_pins_the_compile_reply_tags() {
+        assert_eq!(
+            CompileReply::Ok(vec![vec![0xaa], vec![0xbb, 0xcc]]).encode(),
+            vec![
+                0x10, // tag: ok
+                0, 0, 0, 2, // bytecode count
+                0, 0, 0, 1, 0xaa, // first bytecode
+                0, 0, 0, 2, 0xbb, 0xcc, // second bytecode
+            ],
+            "a compiled answer must encode as tag byte 0x10 followed by a counted list of \
+             length-prefixed bytecodes"
+        );
+        assert_eq!(
+            CompileReply::Error(ErrorRecord {
+                name: "E".into(),
+                message: "m".into(),
+                backtrace: Vec::new(),
+            })
+            .encode(),
+            vec![
+                0x13, // tag: error
+                0, 0, 0, 1, b'E', // name
+                0, 0, 0, 1, b'm', // message
+                0, 0, 0, 0, // backtrace count
+            ],
+            "a failed compile must encode as tag byte 0x13 followed by an Error Record"
+        );
+        assert_eq!(
+            CompileReply::Unsupported(Unsupported::new("x")).encode(),
+            vec![0x15, 0, 0, 0, 0, 1, b'x'],
+            "a guest that does not compile must answer on tag byte 0x15"
+        );
+    }
+
+    // @behavior WE-087
+    #[test]
+    fn a_compile_reply_tag_outside_its_arms_is_refused() {
+        for bytes in [&[0x11, 0, 0, 0, 0][..], &[0x14][..], &[][..]] {
+            assert!(
+                CompileReply::decode(bytes).is_err(),
+                "a Compile Reply {bytes:02x?} through CompileReply::decode must be refused"
+            );
+        }
+    }
+
+    // @behavior WE-088
+    #[test]
+    fn a_compiled_answer_with_trailing_bytes_is_refused() {
+        assert!(
+            CompileReply::decode(&[0x10, 0, 0, 0, 0, 0xff]).is_err(),
+            "a compiled answer with bytes after its list through CompileReply::decode must be \
+             refused as a framing desync"
+        );
+    }
+}

data/crates/kobako-transport/src/envelope/outcome.rs

@@ -5,10 +5,7 @@
 //! byte. Only the ok arm carries codec-encoded bytes.
 
 use super::bytes::{Reader, Writer};
-use super::{DecodeError, ErrorRecord};
-
-const TAG_OK: u8 = 0x01;
-const TAG_PANIC: u8 = 0x02;
+use super::{tag, DecodeError, ErrorRecord, Unsupported};
 
 /// Who a failed invocation attributes to.
 ///
@@ -52,6 +49,8 @@ pub enum Outcome {
     Ok(Vec<u8>),
     /// The invocation terminated with an uncaught exception.
     Panic(Panic),
+    /// The guest does not serve the invocation it was sent.
+    Unsupported(Unsupported),
 }
 
 /// An uncaught top-level failure, plus what attribution and correction need.
@@ -68,8 +67,8 @@ impl Outcome {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
         match reader.u8()? {
-            TAG_OK => Ok(Outcome::Ok(reader.remaining().to_vec())),
-            TAG_PANIC => {
+            tag::OK => Ok(Outcome::Ok(reader.remaining().to_vec())),
+            tag::PANIC => {
                 let origin = Origin::from_name(reader.text()?);
                 let error = ErrorRecord::read(&mut reader)?;
                 let available = reader.text_list()?;
@@ -80,8 +79,9 @@ impl Outcome {
                     available,
                 }))
             }
+            tag::UNSUPPORTED => Ok(Outcome::Unsupported(Unsupported::read(&mut reader)?)),
             _ => Err(DecodeError::new(
-                "Outcome tag must be 0x01 (ok) or 0x02 (panic)",
+                "Outcome tag must be 0x10 (ok), 0x14 (panic), or 0x15 (unsupported)",
             )),
         }
     }
@@ -90,13 +90,14 @@ impl Outcome {
         let mut writer = Writer::new();
         match self {
             Outcome::Ok(value) => {
-                writer.u8(TAG_OK).remainder(value);
+                writer.u8(tag::OK).remainder(value);
             }
             Outcome::Panic(panic) => {
-                writer.u8(TAG_PANIC).bytes(panic.origin.name().as_bytes());
+                writer.u8(tag::PANIC).bytes(panic.origin.name().as_bytes());
                 panic.error.write(&mut writer);
                 writer.list(&panic.available);
             }
+            Outcome::Unsupported(refusal) => return refusal.encode(),
         }
         writer.into_bytes()
     }
@@ -203,7 +204,7 @@ mod tests {
         // this is the shape a third-party guest can legally produce and the
         // one the fallback rule exists for.
         let mut writer = Writer::new();
-        writer.u8(TAG_PANIC).bytes(b"something-else");
+        writer.u8(tag::PANIC).bytes(b"something-else");
         panic_sample().error.write(&mut writer);
         writer.list::<&[u8]>(&[]);
         assert_eq!(
@@ -219,8 +220,8 @@ mod tests {
     fn golden_layout_pins_the_ok_tag() {
         assert_eq!(
             Outcome::Ok(vec![0x2a]).encode(),
-            vec![0x01, 0x2a],
-            "an ok Outcome must encode as tag byte 0x01 followed by the value alone"
+            vec![0x10, 0x2a],
+            "an ok Outcome must encode as tag byte 0x10 followed by the value alone"
         );
     }
 
@@ -239,7 +240,7 @@ mod tests {
         assert_eq!(
             Outcome::Panic(panic).encode(),
             vec![
-                0x02, // tag: panic
+                0x14, // tag: panic
                 0, 0, 0, 7, b's', b'e', b'r', b'v', b'i', b'c', b'e', // origin
                 0, 0, 0, 1, b'E', // name
                 0, 0, 0, 1, b'm', // message
@@ -257,7 +258,7 @@ mod tests {
     fn a_zero_length_outcome_is_refused() {
         assert!(
             Outcome::decode(&[]).is_err(),
-            "a zero-length outcome buffer must be rejected as a wire violation"
+            "a zero-length Outcome must be rejected as a wire violation"
         );
     }
 
@@ -265,8 +266,8 @@ mod tests {
     #[test]
     fn an_unknown_outcome_tag_is_refused() {
         assert!(
-            Outcome::decode(&[0x03, 0x00]).is_err(),
-            "an Outcome tag that is neither ok nor panic must be rejected as a wire violation"
+            Outcome::decode(&[0x11, 0x00]).is_err(),
+            "an Outcome tag outside its arms must be rejected as a wire violation"
         );
     }
 }