kobako 0.28.0 → 0.30.0

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

@@ -66,7 +66,7 @@ impl Preamble {
     /// appear at most once; an absent one reads as empty.
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        let count = reader.u32()? as usize;
+        let count = reader.read_u32()? as usize;
         // Each record costs at least six bytes, its two leading bytes and a
         // body length, so a count past the bytes left can never be
         // satisfied; refusing it bounds the work.
@@ -79,13 +79,13 @@ impl Preamble {
         let mut snippets = None;
         let mut flags = Vec::new();
         for _ in 0..count {
-            let critical = match reader.u8()? {
+            let critical = match reader.read_u8()? {
                 ADVISORY => false,
                 CRITICAL => true,
                 _ => return Err(DecodeError::new("Preamble criticality must be 0 or 1")),
             };
-            let kind = reader.u8()?;
-            let body = reader.bytes()?;
+            let kind = reader.read_u8()?;
+            let body = reader.read_bytes()?;
             match kind {
                 tag::BINDINGS => once(&mut bindings, decode_bindings(body)?)?,
                 tag::SNIPPETS => once(&mut snippets, decode_snippets(body)?)?,
@@ -147,7 +147,7 @@ fn once<T>(slot: &mut Option<T>, value: T) -> Result<(), DecodeError> {
 
 fn decode_bindings(bytes: &[u8]) -> Result<Bindings, DecodeError> {
     let mut reader = Reader::new(bytes);
-    let paths = reader.text_list()?;
+    let paths = reader.read_text_list()?;
     reader.finish()?;
     Ok(Bindings { paths })
 }
@@ -160,7 +160,7 @@ fn encode_bindings(bindings: &Bindings) -> Vec<u8> {
 
 fn decode_snippets(bytes: &[u8]) -> Result<Snippets, DecodeError> {
     let mut reader = Reader::new(bytes);
-    let count = reader.u32()? as usize;
+    let count = reader.read_u32()? as usize;
     // Each entry costs at least a kind byte and a `u32` length, so a count
     // past what the bytes left can hold is refused before it sizes the
     // allocation.
@@ -171,13 +171,13 @@ fn decode_snippets(bytes: &[u8]) -> Result<Snippets, DecodeError> {
     }
     let mut entries = Vec::with_capacity(count);
     for _ in 0..count {
-        entries.push(match reader.u8()? {
+        entries.push(match reader.read_u8()? {
             SNIPPET_SOURCE => Snippet::Source {
-                name: reader.text()?.to_owned(),
-                body: reader.text()?.to_owned(),
+                name: reader.read_text()?.to_owned(),
+                body: reader.read_text()?.to_owned(),
             },
             SNIPPET_BYTECODE => Snippet::Bytecode {
-                body: reader.bytes()?.to_vec(),
+                body: reader.read_bytes()?.to_vec(),
             },
             _ => return Err(DecodeError::new("Preamble snippet kind must be 0 or 1")),
         });
@@ -207,8 +207,8 @@ fn encode_snippets(snippets: &Snippets) -> Vec<u8> {
 
 fn decode_flag(bytes: &[u8], critical: bool) -> Result<Flag, DecodeError> {
     let mut reader = Reader::new(bytes);
-    let name = reader.text()?.to_owned();
-    let value = reader.text()?.to_owned();
+    let name = reader.read_text()?.to_owned();
+    let value = reader.read_text()?.to_owned();
     reader.finish()?;
     Ok(Flag {
         name,
@@ -243,7 +243,7 @@ mod tests {
         writer.into_bytes()
     }
 
-    fn preamble_of(records: &[Vec<u8>]) -> Vec<u8> {
+    fn preamble_with(records: &[Vec<u8>]) -> Vec<u8> {
         let mut bytes = (records.len() as u32).to_be_bytes().to_vec();
         for record in records {
             bytes.extend_from_slice(record);
@@ -307,7 +307,7 @@ mod tests {
     // @behavior WE-053
     #[test]
     fn an_absent_record_reads_as_empty() {
-        let bytes = preamble_of(&[record(0, 0x07, &encode_flag(&flag("f", "", false)))]);
+        let bytes = preamble_with(&[record(0, 0x07, &encode_flag(&flag("f", "", false)))]);
         let preamble = Preamble::decode(&bytes).expect("a flag-only Preamble must decode");
         assert_eq!(
             (preamble.bindings, preamble.snippets),
@@ -375,7 +375,7 @@ mod tests {
     // @behavior WE-056
     #[test]
     fn an_unknown_snippet_kind_is_refused() {
-        let bytes = preamble_of(&[record(1, 0x06, &[0, 0, 0, 1, 9])]);
+        let bytes = preamble_with(&[record(1, 0x06, &[0, 0, 0, 1, 9])]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a snippet kind that is neither source nor bytecode through Preamble::decode must \
@@ -387,7 +387,7 @@ mod tests {
     #[test]
     fn a_count_the_preamble_cannot_satisfy_is_refused() {
         let records = [0xff, 0xff, 0xff, 0xff];
-        let snippets = preamble_of(&[record(1, 0x06, &[0xff, 0xff, 0xff, 0xff])]);
+        let snippets = preamble_with(&[record(1, 0x06, &[0xff, 0xff, 0xff, 0xff])]);
         assert!(
             Preamble::decode(&records).is_err() && Preamble::decode(&snippets).is_err(),
             "a record or snippet count larger than what follows through Preamble::decode must \
@@ -400,7 +400,7 @@ mod tests {
     fn trailing_bytes_are_refused() {
         let mut past_the_list = Preamble::default().encode();
         past_the_list.push(0);
-        let past_a_body = preamble_of(&[record(1, 0x05, &[0, 0, 0, 0, 0])]);
+        let past_a_body = preamble_with(&[record(1, 0x05, &[0, 0, 0, 0, 0])]);
         assert!(
             Preamble::decode(&past_the_list).is_err() && Preamble::decode(&past_a_body).is_err(),
             "bytes past the last record or past a record body's last field through \
@@ -411,7 +411,7 @@ mod tests {
     // @behavior WE-077
     #[test]
     fn an_advisory_record_of_an_unknown_kind_is_skipped() {
-        let bytes = preamble_of(&[
+        let bytes = preamble_with(&[
             record(0, 0x7e, b"anything"),
             record(
                 1,
@@ -432,7 +432,7 @@ mod tests {
     // @behavior WE-078
     #[test]
     fn a_critical_record_of_an_unknown_kind_is_refused() {
-        let bytes = preamble_of(&[record(1, 0x7e, b"anything")]);
+        let bytes = preamble_with(&[record(1, 0x7e, b"anything")]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a critical record of a kind the registry has not assigned through \
@@ -444,7 +444,7 @@ mod tests {
     #[test]
     fn a_record_kind_assigned_to_another_message_is_refused() {
         for kind in [0x00, 0x01, 0x10] {
-            let bytes = preamble_of(&[record(0, kind, b"")]);
+            let bytes = preamble_with(&[record(0, kind, b"")]);
             assert!(
                 Preamble::decode(&bytes).is_err(),
                 "an advisory record of kind {kind:#04x}, which the registry assigns elsewhere, \
@@ -459,7 +459,7 @@ mod tests {
         let bindings = encode_bindings(&Bindings::default());
         let snippets = encode_snippets(&Snippets::default());
         for (kind, body) in [(0x05, bindings), (0x06, snippets)] {
-            let bytes = preamble_of(&[record(1, kind, &body), record(1, kind, &body)]);
+            let bytes = preamble_with(&[record(1, kind, &body), record(1, kind, &body)]);
             assert!(
                 Preamble::decode(&bytes).is_err(),
                 "a second record of kind {kind:#04x} through Preamble::decode must be refused"
@@ -485,7 +485,7 @@ mod tests {
     // @behavior WE-082
     #[test]
     fn a_criticality_that_is_neither_value_is_refused() {
-        let bytes = preamble_of(&[record(2, 0x07, &encode_flag(&flag("f", "", false)))]);
+        let bytes = preamble_with(&[record(2, 0x07, &encode_flag(&flag("f", "", false)))]);
         assert!(
             Preamble::decode(&bytes).is_err(),
             "a criticality byte other than 0 or 1 through Preamble::decode must be refused"
@@ -504,8 +504,8 @@ mod tests {
         );
         let flag = record(0, 0x07, &encode_flag(&flag("f", "", false)));
         assert_eq!(
-            Preamble::decode(&preamble_of(&[flag.clone(), bindings.clone()])),
-            Preamble::decode(&preamble_of(&[bindings, flag])),
+            Preamble::decode(&preamble_with(&[flag.clone(), bindings.clone()])),
+            Preamble::decode(&preamble_with(&[bindings, flag])),
             "the same records in another order through Preamble::decode must read as the same \
              Preamble"
         );

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

@@ -17,6 +17,9 @@ pub enum Reply {
     /// every field of a Fault is kobako's, so a guest reads a refusal
     /// whatever schema it speaks.
     Fault(Fault),
+    /// A block exit unwound the method; the guest continues that exit,
+    /// which it kept, so nothing of it crosses.
+    Break,
     /// The receiver does not serve the request it was sent.
     Unsupported(Unsupported),
 }
@@ -24,14 +27,18 @@ pub enum Reply {
 impl Reply {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        match reader.u8()? {
+        match reader.read_u8()? {
             tag::OK => Ok(Reply::Ok(reader.remaining().to_vec())),
             // No `finish` here: a Fault owns everything after the tag,
             // including the fields a later contract version appends.
             tag::FAULT => Ok(Reply::Fault(Fault::read(&mut reader)?)),
+            tag::BREAK => {
+                reader.finish()?;
+                Ok(Reply::Break)
+            }
             tag::UNSUPPORTED => Ok(Reply::Unsupported(Unsupported::read(&mut reader)?)),
             _ => Err(DecodeError::new(
-                "Reply tag must be 0x10 (ok), 0x11 (fault), or 0x15 (unsupported)",
+                "Reply tag must be 0x10 (ok), 0x11 (fault), 0x12 (break), or 0x15 (unsupported)",
             )),
         }
     }
@@ -46,21 +53,23 @@ impl Reply {
                 writer.u8(tag::FAULT);
                 fault.write(&mut writer);
             }
+            Reply::Break => {
+                writer.u8(tag::BREAK);
+            }
             Reply::Unsupported(refusal) => return refusal.encode(),
         }
         writer.into_bytes()
     }
 }
 
-/// The answer to one Yield Call. Carries a `Break` outcome the dispatch
-/// Reply has no counterpart for, because a block can end its caller.
+/// The answer to one Yield Call.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum YieldReply {
     /// The block completed; the bytes are its value, codec-encoded.
     Ok(Vec<u8>),
-    /// The block ran `break`; the bytes are the break value,
-    /// codec-encoded. It returns to the guest rather than to host code.
-    Break(Vec<u8>),
+    /// The block ran `break` or `return` to a frame past the Service.
+    /// The guest keeps the exit, so the Service is only unwound.
+    Break,
     /// The block raised, or failed in a way the host re-raises at the
     /// yield site.
     Error(ErrorRecord),
@@ -71,9 +80,12 @@ pub enum YieldReply {
 impl YieldReply {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        match reader.u8()? {
+        match reader.read_u8()? {
             tag::OK => Ok(YieldReply::Ok(reader.remaining().to_vec())),
-            tag::BREAK => Ok(YieldReply::Break(reader.remaining().to_vec())),
+            tag::BREAK => {
+                reader.finish()?;
+                Ok(YieldReply::Break)
+            }
             tag::ERROR => {
                 let record = ErrorRecord::read(&mut reader)?;
                 reader.finish()?;
@@ -90,8 +102,8 @@ impl YieldReply {
             YieldReply::Ok(body) => {
                 writer.u8(tag::OK).remainder(body);
             }
-            YieldReply::Break(body) => {
-                writer.u8(tag::BREAK).remainder(body);
+            YieldReply::Break => {
+                writer.u8(tag::BREAK);
             }
             YieldReply::Error(record) => {
                 writer.u8(tag::ERROR);
@@ -116,6 +128,7 @@ mod tests {
                 super::super::FaultKind::Undefined,
                 "no such method",
             )),
+            Reply::Break,
             Reply::Unsupported(Unsupported::new("no such operation")),
         ] {
             let encoded = reply.encode();
@@ -142,7 +155,7 @@ mod tests {
     #[test]
     fn an_unknown_reply_tag_is_refused() {
         assert!(
-            Reply::decode(&[0x12, 0]).is_err(),
+            Reply::decode(&[0x13, 0]).is_err(),
             "a Reply tag outside its arms must be rejected as a wire violation"
         );
     }
@@ -161,7 +174,7 @@ mod tests {
     fn every_live_yield_arm_round_trips() {
         let arms = [
             YieldReply::Ok(vec![0xa4]),
-            YieldReply::Break(vec![0xa4]),
+            YieldReply::Break,
             YieldReply::Error(ErrorRecord {
                 name: "LocalJumpError".into(),
                 message: "no block".into(),
@@ -214,6 +227,11 @@ mod tests {
             "an unsupported Reply must encode as tag byte 0x15 followed by kind 0 and the \
              message"
         );
+        assert_eq!(
+            Reply::Break.encode(),
+            vec![0x12],
+            "a break Reply must encode as tag byte 0x12 alone, since the guest keeps the exit"
+        );
     }
 
     // @behavior WE-068
@@ -242,9 +260,9 @@ mod tests {
             "a Yield Reply carrying the block's value must encode as tag byte 0x10"
         );
         assert_eq!(
-            YieldReply::Break(vec![0xc0]).encode(),
-            vec![0x12, 0xc0],
-            "a Yield Reply carrying a break value must encode as tag byte 0x12"
+            YieldReply::Break.encode(),
+            vec![0x12],
+            "a Yield Reply for a block exit must encode as tag byte 0x12 alone"
         );
         assert_eq!(
             YieldReply::Unsupported(Unsupported::new("x")).encode(),

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

@@ -18,9 +18,9 @@ pub enum Downcall {
     Eval(Vec<u8>),
     /// Call the entrypoint the Run names.
     Run(Run),
-    /// Re-enter the block bound to the active dispatch; the bytes are
-    /// its arguments, codec-encoded.
-    Yield(Vec<u8>),
+    /// Re-enter the block of the open Call `frame` counts to, from `0`
+    /// at the outermost; `args` are its arguments, codec-encoded.
+    Yield { frame: u32, args: Vec<u8> },
     /// Compile the Preamble's source Snippets without running them. It
     /// carries no body: what it compiles is the Preamble an invocation
     /// would read.
@@ -37,7 +37,10 @@ impl Downcall {
         Ok(match tag {
             tag::EVAL => Downcall::Eval(body.to_vec()),
             tag::RUN => Downcall::Run(Run::decode(body)?),
-            tag::YIELD => Downcall::Yield(body.to_vec()),
+            tag::YIELD => Downcall::Yield {
+                frame: reader.read_u32()?,
+                args: reader.remaining().to_vec(),
+            },
             tag::COMPILE if body.is_empty() => Downcall::Compile,
             tag::COMPILE => return Err(DecodeError::new("a compile request carries no body")),
             tag => Downcall::Unknown {
@@ -52,7 +55,7 @@ impl Downcall {
         match self {
             Downcall::Eval(source) => writer.u8(tag::EVAL).remainder(source),
             Downcall::Run(run) => writer.u8(tag::RUN).remainder(&run.encode()),
-            Downcall::Yield(args) => writer.u8(tag::YIELD).remainder(args),
+            Downcall::Yield { frame, args } => writer.u8(tag::YIELD).u32(*frame).remainder(args),
             Downcall::Compile => writer.u8(tag::COMPILE),
             Downcall::Unknown { tag, body } => writer.u8(tag.get()).remainder(body),
         };
@@ -112,7 +115,7 @@ impl UnknownTag {
 }
 
 fn read_tag(reader: &mut Reader<'_>) -> Result<u8, DecodeError> {
-    match reader.u8()? {
+    match reader.read_u8()? {
         tag::INVALID => Err(DecodeError::new("request tag 0x00 is invalid")),
         tag => Ok(tag),
     }
@@ -146,14 +149,18 @@ mod tests {
             (
                 Downcall::Eval(b"1".to_vec()).encode(),
                 Downcall::Run(run).encode(),
-                Downcall::Yield(vec![0x90]).encode(),
+                Downcall::Yield {
+                    frame: 2,
+                    args: vec![0x90],
+                }
+                .encode(),
                 Downcall::Compile.encode(),
                 Upcall::Call(call).encode(),
             ),
             (
                 vec![0x01, b'1'],
                 vec![0x02, 0, 0, 0, 1, b'M', 0x90],
-                vec![0x03, 0x90],
+                vec![0x03, 0, 0, 0, 2, 0x90],
                 vec![0x08],
                 vec![
                     0x04, // tag: call
@@ -177,7 +184,10 @@ mod tests {
                 entrypoint: "Main".into(),
                 payload: vec![0x90],
             }),
-            Downcall::Yield(vec![0x91, 0x01]),
+            Downcall::Yield {
+                frame: 0,
+                args: vec![0x91, 0x01],
+            },
             Downcall::Compile,
             Downcall::Unknown {
                 tag: UnknownTag::new(0xf0).unwrap(),

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

@@ -18,7 +18,7 @@ pub struct Run {
 impl Run {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        let entrypoint = reader.text()?.to_owned();
+        let entrypoint = reader.read_text()?.to_owned();
         Ok(Run {
             entrypoint,
             payload: reader.remaining().to_vec(),

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

@@ -38,8 +38,8 @@ impl Unsupported {
     }
 
     pub(crate) fn read(reader: &mut Reader<'_>) -> Result<Self, DecodeError> {
-        reader.u8()?;
-        let message = reader.text()?.to_owned();
+        reader.read_u8()?;
+        let message = reader.read_text()?.to_owned();
         // The last thing its answer carries, so whatever follows belongs
         // to a later version of these fields, as for a Fault.
         reader.skip_unknown_fields();

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

@@ -1,4 +1,4 @@
-//! The core envelope — the fixed-layout outer frame of every host↔guest
+//! The Envelope — the fixed-layout outer frame of every host↔guest
 //! message.
 //!
 //! Routing and outcome attribution live here; everything a resolved method
@@ -50,7 +50,7 @@ pub use unsupported::Unsupported;
 
 use std::fmt;
 
-/// A message that does not conform to the core envelope layout. Only
+/// A message that does not conform to the Envelope layout. Only
 /// decoding produces one — every `encode` is infallible — so the name says
 /// which direction it comes from.
 ///