kobako 0.26.0 → 0.28.0

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

@@ -2,18 +2,11 @@
 //!
 //! Success-versus-fault is decided by a tag byte rather than a reserved
 //! payload value, so a side learns the outcome of a Call whatever schema
-//! the payload carries.
+//! the payload carries. Each tag is the answer's arm in the shared
+//! registry, so the same byte means the same arm in every answer.
 
 use super::bytes::{Reader, Writer};
-use super::{DecodeError, ErrorRecord, Fault};
-
-const TAG_OK: u8 = 0;
-const TAG_FAULT: u8 = 1;
-
-const YIELD_OK: u8 = 0x01;
-const YIELD_BREAK: u8 = 0x02;
-const YIELD_RESERVED: u8 = 0x03;
-const YIELD_ERROR: u8 = 0x04;
+use super::{tag, DecodeError, ErrorRecord, Fault, Unsupported};
 
 /// The answer to one dispatch Call.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -24,18 +17,22 @@ pub enum Reply {
     /// every field of a Fault is kobako's, so a guest reads a refusal
     /// whatever schema it speaks.
     Fault(Fault),
+    /// The receiver does not serve the request it was sent.
+    Unsupported(Unsupported),
 }
 
 impl Reply {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        let tag = reader.u8()?;
-        match tag {
-            TAG_OK => Ok(Reply::Ok(reader.remaining().to_vec())),
+        match reader.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)?)),
-            _ => Err(DecodeError::new("Reply tag must be 0 (ok) or 1 (fault)")),
+            tag::FAULT => Ok(Reply::Fault(Fault::read(&mut reader)?)),
+            tag::UNSUPPORTED => Ok(Reply::Unsupported(Unsupported::read(&mut reader)?)),
+            _ => Err(DecodeError::new(
+                "Reply tag must be 0x10 (ok), 0x11 (fault), or 0x15 (unsupported)",
+            )),
         }
     }
 
@@ -43,12 +40,13 @@ impl Reply {
         let mut writer = Writer::new();
         match self {
             Reply::Ok(body) => {
-                writer.u8(TAG_OK).remainder(body);
+                writer.u8(tag::OK).remainder(body);
             }
             Reply::Fault(fault) => {
-                writer.u8(TAG_FAULT);
+                writer.u8(tag::FAULT);
                 fault.write(&mut writer);
             }
+            Reply::Unsupported(refusal) => return refusal.encode(),
         }
         writer.into_bytes()
     }
@@ -66,21 +64,22 @@ pub enum YieldReply {
     /// The block raised, or failed in a way the host re-raises at the
     /// yield site.
     Error(ErrorRecord),
+    /// The guest serves no block.
+    Unsupported(Unsupported),
 }
 
 impl YieldReply {
     pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
         let mut reader = Reader::new(bytes);
-        let tag = reader.u8()?;
-        match tag {
-            YIELD_OK => Ok(YieldReply::Ok(reader.remaining().to_vec())),
-            YIELD_BREAK => Ok(YieldReply::Break(reader.remaining().to_vec())),
-            YIELD_ERROR => {
+        match reader.u8()? {
+            tag::OK => Ok(YieldReply::Ok(reader.remaining().to_vec())),
+            tag::BREAK => Ok(YieldReply::Break(reader.remaining().to_vec())),
+            tag::ERROR => {
                 let record = ErrorRecord::read(&mut reader)?;
                 reader.finish()?;
                 Ok(YieldReply::Error(record))
             }
-            YIELD_RESERVED => Err(DecodeError::new("Yield Reply tag 0x03 is reserved")),
+            tag::UNSUPPORTED => Ok(YieldReply::Unsupported(Unsupported::read(&mut reader)?)),
             _ => Err(DecodeError::new("Yield Reply tag is not recognised")),
         }
     }
@@ -89,15 +88,16 @@ impl YieldReply {
         let mut writer = Writer::new();
         match self {
             YieldReply::Ok(body) => {
-                writer.u8(YIELD_OK).remainder(body);
+                writer.u8(tag::OK).remainder(body);
             }
             YieldReply::Break(body) => {
-                writer.u8(YIELD_BREAK).remainder(body);
+                writer.u8(tag::BREAK).remainder(body);
             }
             YieldReply::Error(record) => {
-                writer.u8(YIELD_ERROR);
+                writer.u8(tag::ERROR);
                 record.write(&mut writer);
             }
+            YieldReply::Unsupported(refusal) => return refusal.encode(),
         }
         writer.into_bytes()
     }
@@ -109,19 +109,20 @@ mod tests {
 
     // @behavior WE-018
     #[test]
-    fn both_reply_arms_round_trip() {
+    fn every_reply_arm_round_trips() {
         for reply in [
             Reply::Ok(vec![0x2a]),
             Reply::Fault(Fault::new(
                 super::super::FaultKind::Undefined,
                 "no such method",
             )),
+            Reply::Unsupported(Unsupported::new("no such operation")),
         ] {
             let encoded = reply.encode();
             assert_eq!(
                 Reply::decode(&encoded),
                 Ok(reply),
-                "a Reply must survive a host encode and decode on both arms"
+                "a Reply must survive a host encode and decode on every arm"
             );
         }
     }
@@ -141,8 +142,8 @@ mod tests {
     #[test]
     fn an_unknown_reply_tag_is_refused() {
         assert!(
-            Reply::decode(&[9, 0]).is_err(),
-            "a Reply tag that is neither ok nor fault must be rejected as a wire violation"
+            Reply::decode(&[0x12, 0]).is_err(),
+            "a Reply tag outside its arms must be rejected as a wire violation"
         );
     }
 
@@ -166,6 +167,7 @@ mod tests {
                 message: "no block".into(),
                 backtrace: vec!["(eval):1".into()],
             }),
+            YieldReply::Unsupported(Unsupported::new("no block support")),
         ];
         for arm in arms {
             let encoded = arm.encode();
@@ -177,22 +179,16 @@ mod tests {
         }
     }
 
-    // @behavior WE-023
-    #[test]
-    fn the_reserved_yield_tag_is_refused() {
-        assert!(
-            YieldReply::decode(&[0x03]).is_err(),
-            "Yield Reply tag 0x03 must be rejected by both peers so it stays reserved"
-        );
-    }
-
     // @behavior WE-024
     #[test]
     fn an_unknown_yield_tag_is_refused() {
-        assert!(
-            YieldReply::decode(&[0x7f]).is_err(),
-            "a Yield Reply tag outside the live set must be rejected as a wire violation"
-        );
+        for tag in [0x03, 0x11, 0x7f] {
+            assert!(
+                YieldReply::decode(&[tag]).is_err(),
+                "a Yield Reply tag {tag:#04x} outside the live set must be rejected as a \
+                 wire violation"
+            );
+        }
     }
 
     // @behavior WE-025
@@ -203,15 +199,38 @@ mod tests {
         // is what lets a side read the outcome without a payload codec.
         assert_eq!(
             Reply::Ok(vec![0x2a]).encode(),
-            vec![0, 0x2a],
-            "a successful Reply must encode as tag byte 0 followed by the body alone"
+            vec![0x10, 0x2a],
+            "a successful Reply must encode as tag byte 0x10 followed by the body alone"
         );
         assert_eq!(
             Reply::Fault(Fault::new(super::super::FaultKind::Runtime, "x")).encode(),
-            vec![1, 0, 0, 0, 0, 1, b'x'],
-            "a fault Reply must encode as tag byte 1 followed by the Fault's own fixed \
+            vec![0x11, 0, 0, 0, 0, 1, b'x'],
+            "a fault Reply must encode as tag byte 0x11 followed by the Fault's own fixed \
              layout, so a guest reads a refusal without reaching a payload codec"
         );
+        assert_eq!(
+            Reply::Unsupported(Unsupported::new("x")).encode(),
+            vec![0x15, 0, 0, 0, 0, 1, b'x'],
+            "an unsupported Reply must encode as tag byte 0x15 followed by kind 0 and the \
+             message"
+        );
+    }
+
+    // @behavior WE-068
+    #[test]
+    fn every_answer_takes_its_ok_tag_from_one_registry() {
+        let body = vec![0x2a];
+        assert_eq!(
+            [
+                Reply::Ok(body.clone()).encode()[0],
+                YieldReply::Ok(body.clone()).encode()[0],
+                super::super::CompileReply::Ok(vec![body.clone()]).encode()[0],
+                super::super::Outcome::Ok(body).encode()[0],
+            ],
+            [0x10, 0x10, 0x10, 0x10],
+            "a Reply, a Yield Reply, a Compile Reply and an Outcome on their ok arm must all \
+             open with tag byte 0x10"
+        );
     }
 
     // @behavior WE-026
@@ -219,13 +238,18 @@ mod tests {
     fn golden_layout_pins_the_yield_tags() {
         assert_eq!(
             YieldReply::Ok(vec![0xc0]).encode(),
-            vec![0x01, 0xc0],
-            "a Yield Reply carrying the block's value must encode as tag byte 0x01"
+            vec![0x10, 0xc0],
+            "a Yield Reply carrying the block's value must encode as tag byte 0x10"
         );
         assert_eq!(
             YieldReply::Break(vec![0xc0]).encode(),
-            vec![0x02, 0xc0],
-            "a Yield Reply carrying a break value must encode as tag byte 0x02"
+            vec![0x12, 0xc0],
+            "a Yield Reply carrying a break value must encode as tag byte 0x12"
+        );
+        assert_eq!(
+            YieldReply::Unsupported(Unsupported::new("x")).encode(),
+            vec![0x15, 0, 0, 0, 0, 1, b'x'],
+            "a Yield Reply from a guest serving no block must encode as tag byte 0x15"
         );
         assert_eq!(
             YieldReply::Error(ErrorRecord {
@@ -235,12 +259,12 @@ mod tests {
             })
             .encode(),
             vec![
-                0x04, // tag: error
+                0x13, // tag: error
                 0, 0, 0, 1, b'E', // name
                 0, 0, 0, 1, b'm', // message
                 0, 0, 0, 0, // backtrace count
             ],
-            "a Yield Reply carrying a guest failure must encode as tag byte 0x04 followed \
+            "a Yield Reply carrying a guest failure must encode as tag byte 0x13 followed \
              by an Error Record rather than a codec-encoded body"
         );
     }

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

@@ -0,0 +1,295 @@
+//! The requests a downcall and an upcall carry: a tag naming the
+//! operation, then that operation's body.
+//!
+//! A tag the registry has not assigned reads as `Unknown` with its body
+//! intact, so a receiver can serve it or answer it as unsupported. An
+//! assigned tag already means one thing, so one this direction does not
+//! carry as a request is a wire violation, as are an empty request and
+//! the invalid tag; each body's own layout refuses what it cannot frame.
+
+use super::bytes::{Reader, Writer};
+use super::{tag, Call, DecodeError, Run};
+
+/// A request the host sends the guest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Downcall {
+    /// Run the user source, UTF-8, as one invocation.
+    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>),
+    /// Compile the Preamble's source Snippets without running them. It
+    /// carries no body: what it compiles is the Preamble an invocation
+    /// would read.
+    Compile,
+    /// A tag the registry has not assigned, with the body it carried.
+    Unknown { tag: UnknownTag, body: Vec<u8> },
+}
+
+impl Downcall {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let tag = read_tag(&mut reader)?;
+        let body = reader.remaining();
+        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::COMPILE if body.is_empty() => Downcall::Compile,
+            tag::COMPILE => return Err(DecodeError::new("a compile request carries no body")),
+            tag => Downcall::Unknown {
+                tag: unknown(tag)?,
+                body: body.to_vec(),
+            },
+        })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        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::Compile => writer.u8(tag::COMPILE),
+            Downcall::Unknown { tag, body } => writer.u8(tag.get()).remainder(body),
+        };
+        writer.into_bytes()
+    }
+}
+
+/// A request the guest sends the host.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Upcall<'a> {
+    /// Dispatch the Call to a Receiver.
+    Call(Call<'a>),
+    /// A tag the registry has not assigned, with the body it carried.
+    Unknown { tag: UnknownTag, body: &'a [u8] },
+}
+
+impl<'a> Upcall<'a> {
+    pub fn decode(bytes: &'a [u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let tag = read_tag(&mut reader)?;
+        let body = reader.remaining();
+        Ok(match tag {
+            tag::CALL => Upcall::Call(Call::decode(body)?),
+            tag => Upcall::Unknown {
+                tag: unknown(tag)?,
+                body,
+            },
+        })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self {
+            Upcall::Call(call) => writer.u8(tag::CALL).remainder(&call.encode()),
+            Upcall::Unknown { tag, body } => writer.u8(tag.get()).remainder(body),
+        };
+        writer.into_bytes()
+    }
+}
+
+/// A request tag the registry has not assigned. Only such a tag can name
+/// an unknown request, so an unknown request never encodes as an
+/// operation the registry already has.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UnknownTag(u8);
+
+impl UnknownTag {
+    /// `None` when the registry assigns `tag`, the invalid tag included.
+    pub fn new(tag: u8) -> Option<Self> {
+        (!tag::is_assigned(tag)).then_some(UnknownTag(tag))
+    }
+
+    pub fn get(self) -> u8 {
+        self.0
+    }
+}
+
+fn read_tag(reader: &mut Reader<'_>) -> Result<u8, DecodeError> {
+    match reader.u8()? {
+        tag::INVALID => Err(DecodeError::new("request tag 0x00 is invalid")),
+        tag => Ok(tag),
+    }
+}
+
+fn unknown(tag: u8) -> Result<UnknownTag, DecodeError> {
+    UnknownTag::new(tag).ok_or(DecodeError::new(
+        "request tag is assigned to the other direction or to an answer",
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::envelope::Target;
+
+    // @behavior WE-071
+    #[test]
+    fn golden_layout_pins_each_request_tag() {
+        let run = Run {
+            entrypoint: "M".into(),
+            payload: vec![0x90],
+        };
+        let call = Call {
+            target: Target::Path("K"),
+            method: "m",
+            block_given: false,
+            payload: &[0x90],
+        };
+        assert_eq!(
+            (
+                Downcall::Eval(b"1".to_vec()).encode(),
+                Downcall::Run(run).encode(),
+                Downcall::Yield(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![0x08],
+                vec![
+                    0x04, // tag: call
+                    0,    // kind: path
+                    0, 0, 0, 1, b'K', // target
+                    0, 0, 0, 1, b'm', // method
+                    0,    // block_given
+                    0x90, // payload
+                ],
+            ),
+            "each request through Downcall and Upcall must open with its operation's tag \
+             followed by its body alone"
+        );
+    }
+
+    #[test]
+    fn every_downcall_round_trips() {
+        for request in [
+            Downcall::Eval(b"1 + 1".to_vec()),
+            Downcall::Run(Run {
+                entrypoint: "Main".into(),
+                payload: vec![0x90],
+            }),
+            Downcall::Yield(vec![0x91, 0x01]),
+            Downcall::Compile,
+            Downcall::Unknown {
+                tag: UnknownTag::new(0xf0).unwrap(),
+                body: vec![0xaa, 0xbb],
+            },
+        ] {
+            assert_eq!(
+                Downcall::decode(&request.encode()),
+                Ok(request),
+                "a downcall request must survive an encode and decode unchanged"
+            );
+        }
+    }
+
+    // @behavior WE-072
+    #[test]
+    fn an_unassigned_tag_reads_as_unknown_with_its_body() {
+        assert_eq!(
+            (
+                Downcall::decode(&[0x09, 0xff]),
+                Upcall::decode(&[0xf0, 0x01, 0x02])
+            ),
+            (
+                Ok(Downcall::Unknown {
+                    tag: UnknownTag::new(0x09).unwrap(),
+                    body: vec![0xff]
+                }),
+                Ok(Upcall::Unknown {
+                    tag: UnknownTag::new(0xf0).unwrap(),
+                    body: &[0x01, 0x02]
+                })
+            ),
+            "a request under a tag the registry has not assigned through Downcall and Upcall \
+             must read as unknown with its body intact"
+        );
+    }
+
+    // @behavior WE-073
+    #[test]
+    fn an_empty_request_is_refused() {
+        assert!(
+            Downcall::decode(&[]).is_err() && Upcall::decode(&[]).is_err(),
+            "a request of no length through Downcall and Upcall must be refused"
+        );
+    }
+
+    // @behavior WE-074
+    #[test]
+    fn a_request_under_the_invalid_tag_is_refused() {
+        assert!(
+            Downcall::decode(&[0x00, 0x01]).is_err() && Upcall::decode(&[0x00]).is_err(),
+            "a request under tag 0x00 through Downcall and Upcall must be refused"
+        );
+    }
+
+    // @behavior WE-075
+    #[test]
+    fn a_request_under_a_tag_assigned_elsewhere_is_refused() {
+        assert_eq!(
+            (
+                Downcall::decode(&[0x04, 0x90]).is_err(),
+                Downcall::decode(&[0x10, 0x90]).is_err(),
+                Upcall::decode(&[0x01, b'1']).is_err(),
+                Upcall::decode(&[0x15, 0x00]).is_err(),
+            ),
+            (true, true, true, true),
+            "a request under the other direction's tag or an answer's arm through Downcall and \
+             Upcall must be refused rather than read as unknown"
+        );
+    }
+
+    // @behavior WE-084
+    #[test]
+    fn a_compile_request_carrying_a_body_is_refused() {
+        assert!(
+            Downcall::decode(&[0x08, 0x90]).is_err(),
+            "a compile request with bytes after its tag through Downcall::decode must be \
+             refused, since the operation reads its input from the Preamble"
+        );
+    }
+
+    // @behavior WE-076
+    #[test]
+    fn an_unknown_tag_cannot_be_made_from_an_assigned_one() {
+        assert_eq!(
+            [0x00, 0x01, 0x04, 0x08, 0x10, 0x15].map(UnknownTag::new),
+            [None; 6],
+            "an assigned tag or tag 0x00 through UnknownTag::new must be refused, so an \
+             unknown request never encodes as a known operation"
+        );
+    }
+
+    #[test]
+    fn every_upcall_round_trips() {
+        let call = Call {
+            target: Target::Handle(7),
+            method: "m",
+            block_given: true,
+            payload: &[0x90],
+        };
+        for request in [
+            Upcall::Call(call),
+            Upcall::Unknown {
+                tag: UnknownTag::new(0xf1).unwrap(),
+                body: &[0xaa],
+            },
+        ] {
+            assert_eq!(
+                Upcall::decode(&request.encode()),
+                Ok(request),
+                "an upcall request must survive an encode and decode unchanged"
+            );
+        }
+    }
+}

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

@@ -3,8 +3,7 @@
 //! Run is Call's reverse-direction sibling — `entrypoint` routes it, the
 //! payload feeds it. It carries no `method` because the entrypoint is
 //! invoked through its own `#call`, and no `block_given` because `#run`
-//! supplies no block. It rides the command buffer rather than a stdin
-//! frame, so its length reaches the guest as an export argument.
+//! supplies no block. It is the body of a `run` downcall.
 
 use super::bytes::{Reader, Writer};
 use super::DecodeError;

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

@@ -0,0 +1,49 @@
+//! The tag registry: the first byte of every downcall and upcall message,
+//! and the kind of every Preamble record.
+//!
+//! One number space covers requests, answers, and records alike, so a byte
+//! means one thing in every message and an answer's arm never collides
+//! across operations. The registry grows append-only; a receiver answers a
+//! request tag it does not serve as unsupported.
+
+/// Never assigned, so a zeroed message cannot pass for one that was written.
+pub(crate) const INVALID: u8 = 0x00;
+pub(crate) const EVAL: u8 = 0x01;
+pub(crate) const RUN: u8 = 0x02;
+pub(crate) const YIELD: u8 = 0x03;
+pub(crate) const CALL: u8 = 0x04;
+pub(crate) const BINDINGS: u8 = 0x05;
+pub(crate) const SNIPPETS: u8 = 0x06;
+pub(crate) const FLAG: u8 = 0x07;
+pub(crate) const COMPILE: u8 = 0x08;
+
+pub(crate) const OK: u8 = 0x10;
+pub(crate) const FAULT: u8 = 0x11;
+pub(crate) const BREAK: u8 = 0x12;
+pub(crate) const ERROR: u8 = 0x13;
+pub(crate) const PANIC: u8 = 0x14;
+pub(crate) const UNSUPPORTED: u8 = 0x15;
+
+/// Whether the registry gives `tag` a meaning, the invalid tag included.
+/// An assigned tag means one thing in every message, so it can never
+/// stand for an operation this registry does not know.
+pub(crate) fn is_assigned(tag: u8) -> bool {
+    matches!(
+        tag,
+        INVALID
+            | EVAL
+            | RUN
+            | YIELD
+            | CALL
+            | BINDINGS
+            | SNIPPETS
+            | FLAG
+            | COMPILE
+            | OK
+            | FAULT
+            | BREAK
+            | ERROR
+            | PANIC
+            | UNSUPPORTED
+    )
+}