kobako 0.19.0 → 0.21.0

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

@@ -0,0 +1,234 @@
+//! Byte primitives for the core envelope: unsigned big-endian integers,
+//! length-prefixed byte strings, counted lists, and the trailing remainder.
+//!
+//! `Reader` borrows rather than copies, so a decoded envelope's payload is
+//! a view into the caller's buffer and reaches a frontend without a second
+//! allocation.
+
+use super::DecodeError;
+
+const MALFORMED: DecodeError = DecodeError::new("core envelope ended before its declared length");
+
+/// Cursor over one message. Every read either advances past a complete
+/// field or fails, so a truncated message can never be mistaken for a
+/// short one.
+pub(crate) struct Reader<'a> {
+    bytes: &'a [u8],
+    pos: usize,
+}
+
+impl<'a> Reader<'a> {
+    pub(crate) fn new(bytes: &'a [u8]) -> Self {
+        Reader { bytes, pos: 0 }
+    }
+
+    pub(crate) fn u8(&mut self) -> Result<u8, DecodeError> {
+        let byte = *self.bytes.get(self.pos).ok_or(MALFORMED)?;
+        self.pos += 1;
+        Ok(byte)
+    }
+
+    pub(crate) fn u32(&mut self) -> Result<u32, DecodeError> {
+        let end = self.pos.checked_add(4).ok_or(MALFORMED)?;
+        let slice = self.bytes.get(self.pos..end).ok_or(MALFORMED)?;
+        self.pos = end;
+        // The slice is exactly 4 bytes, so the conversion cannot fail.
+        Ok(u32::from_be_bytes(slice.try_into().unwrap()))
+    }
+
+    /// A `u32` length followed by that many bytes.
+    pub(crate) fn bytes(&mut self) -> Result<&'a [u8], DecodeError> {
+        let len = self.u32()? as usize;
+        let end = self.pos.checked_add(len).ok_or(MALFORMED)?;
+        let slice = self.bytes.get(self.pos..end).ok_or(MALFORMED)?;
+        self.pos = end;
+        Ok(slice)
+    }
+
+    /// A byte string carrying UTF-8. Every text field in the envelope is
+    /// validated at decode so a frontend receives `&str` without repeating
+    /// the check.
+    pub(crate) fn text(&mut self) -> Result<&'a str, DecodeError> {
+        core::str::from_utf8(self.bytes()?)
+            .map_err(|_| DecodeError::new("core envelope text field is not valid UTF-8"))
+    }
+
+    /// A `u32` count followed by that many byte strings, each carrying
+    /// UTF-8. Every list the envelope defines is a list of names, so this
+    /// is the only list shape a reader needs.
+    ///
+    /// The elements are copied rather than borrowed: a binding's path and
+    /// a panic's `available` names outlive the frame buffer they arrive in.
+    pub(crate) fn text_list(&mut self) -> Result<Vec<String>, DecodeError> {
+        let count = self.u32()? as usize;
+        // A count larger than the bytes left cannot be satisfied; refusing
+        // it here bounds the allocation below by the message size.
+        if count > self.remaining().len() {
+            return Err(MALFORMED);
+        }
+        let mut out = Vec::with_capacity(count);
+        for _ in 0..count {
+            out.push(self.text()?.to_owned());
+        }
+        Ok(out)
+    }
+
+    /// Everything not yet consumed. The trailing field of an envelope that
+    /// carries one, so its extent comes from the transport rather than a
+    /// repeated length.
+    pub(crate) fn remaining(&self) -> &'a [u8] {
+        &self.bytes[self.pos..]
+    }
+
+    /// Refuse anything left over. Used by envelopes whose last field is
+    /// self-delimiting, where trailing bytes signal a framing desync.
+    pub(crate) fn finish(self) -> Result<(), DecodeError> {
+        if self.pos == self.bytes.len() {
+            Ok(())
+        } else {
+            Err(DecodeError::new(
+                "core envelope carries bytes past its last field",
+            ))
+        }
+    }
+}
+
+/// Accumulator for one message.
+#[derive(Default)]
+pub(crate) struct Writer {
+    out: Vec<u8>,
+}
+
+impl Writer {
+    pub(crate) fn new() -> Self {
+        Writer::default()
+    }
+
+    pub(crate) fn u8(&mut self, byte: u8) -> &mut Self {
+        self.out.push(byte);
+        self
+    }
+
+    pub(crate) fn u32(&mut self, value: u32) -> &mut Self {
+        self.out.extend_from_slice(&value.to_be_bytes());
+        self
+    }
+
+    pub(crate) fn bytes(&mut self, bytes: &[u8]) -> &mut Self {
+        self.u32(bytes.len() as u32);
+        self.out.extend_from_slice(bytes);
+        self
+    }
+
+    /// The trailing field: written without a length, since the transport
+    /// already carries the message's extent.
+    pub(crate) fn remainder(&mut self, bytes: &[u8]) -> &mut Self {
+        self.out.extend_from_slice(bytes);
+        self
+    }
+
+    pub(crate) fn list<S: AsRef<[u8]>>(&mut self, items: &[S]) -> &mut Self {
+        self.u32(items.len() as u32);
+        for item in items {
+            self.bytes(item.as_ref());
+        }
+        self
+    }
+
+    pub(crate) fn into_bytes(self) -> Vec<u8> {
+        self.out
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn round_trips_every_primitive() {
+        let mut w = Writer::new();
+        w.u8(7)
+            .u32(0xdead_beef)
+            .bytes(b"kv")
+            .list(&[&b"a"[..], &b"bc"[..]]);
+        w.remainder(b"tail");
+        let encoded = w.into_bytes();
+
+        let mut r = Reader::new(&encoded);
+        assert_eq!(r.u8(), Ok(7), "a u8 must round-trip through the writer");
+        assert_eq!(r.u32(), Ok(0xdead_beef), "a u32 must round-trip big-endian");
+        assert_eq!(
+            r.bytes(),
+            Ok(&b"kv"[..]),
+            "a length-prefixed byte string must round-trip"
+        );
+        assert_eq!(
+            r.text_list(),
+            Ok(vec!["a".to_owned(), "bc".to_owned()]),
+            "a counted list must round-trip element for element"
+        );
+        assert_eq!(
+            r.remaining(),
+            b"tail",
+            "the trailing field must be everything the prefixed fields left"
+        );
+    }
+
+    #[test]
+    fn u32_is_big_endian_on_the_wire() {
+        let mut w = Writer::new();
+        w.u32(1);
+        assert_eq!(
+            w.into_bytes(),
+            vec![0, 0, 0, 1],
+            "a u32 must encode big-endian so both peers read the same number"
+        );
+    }
+
+    #[test]
+    fn a_length_running_past_the_end_is_refused() {
+        // Declares 8 bytes but supplies 2.
+        let bytes = [0, 0, 0, 8, b'h', b'i'];
+        let mut r = Reader::new(&bytes);
+        assert!(
+            r.bytes().is_err(),
+            "a byte string whose length overruns the message must be rejected, not truncated"
+        );
+    }
+
+    #[test]
+    fn a_count_larger_than_the_message_is_refused() {
+        // Declares 0xffff_ffff elements in a 4-byte message.
+        let bytes = [0xff, 0xff, 0xff, 0xff];
+        let mut r = Reader::new(&bytes);
+        assert!(
+            r.text_list().is_err(),
+            "a list count the message cannot satisfy must be rejected before any allocation"
+        );
+    }
+
+    #[test]
+    fn non_utf8_in_a_text_field_is_refused() {
+        let mut w = Writer::new();
+        w.bytes(&[0xff, 0xfe]);
+        let encoded = w.into_bytes();
+        let mut r = Reader::new(&encoded);
+        assert!(
+            r.text().is_err(),
+            "a text field carrying non-UTF-8 bytes must be rejected at decode"
+        );
+    }
+
+    #[test]
+    fn trailing_bytes_after_a_self_delimiting_field_are_refused() {
+        let mut w = Writer::new();
+        w.bytes(b"ok").remainder(b"!");
+        let encoded = w.into_bytes();
+        let mut r = Reader::new(&encoded);
+        r.bytes().unwrap();
+        assert!(
+            r.finish().is_err(),
+            "bytes past an envelope's last field must fail loudly as a framing desync"
+        );
+    }
+}

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

@@ -0,0 +1,222 @@
+//! The Call envelope — a message inviting the other side to run one
+//! method and answer.
+//!
+//! Borrows from the buffer it decoded, so the payload reaches a frontend
+//! as a view rather than a copy.
+
+use super::bytes::{Reader, Writer};
+use super::DecodeError;
+
+/// Whether `target` names a bound constant or a capability Handle. The tag
+/// is explicit so a side reads the routing fields without interpreting any
+/// encoding but this one.
+const KIND_PATH: u8 = 0;
+const KIND_HANDLE: u8 = 1;
+
+/// The object a Call is addressed to.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Target<'a> {
+    /// A bound constant's path — `"MyService::KV"`, or a single segment
+    /// like `"File"`.
+    Path(&'a str),
+    /// A capability Handle, by the id this invocation's table issued.
+    Handle(u32),
+}
+
+/// One dispatch invitation: where it goes, what to run, whether a block
+/// came with it, and the arguments the resolved method consumes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Call<'a> {
+    pub target: Target<'a>,
+    pub method: &'a str,
+    pub block_given: bool,
+    pub payload: &'a [u8],
+}
+
+impl<'a> Call<'a> {
+    pub fn decode(bytes: &'a [u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let target = match reader.u8()? {
+            KIND_PATH => Target::Path(reader.text()?),
+            KIND_HANDLE => Target::Handle(reader.u32()?),
+            _ => return Err(DecodeError::new("Call kind must be 0 (path) or 1 (handle)")),
+        };
+        if let Target::Handle(0) = target {
+            return Err(DecodeError::new(
+                "Call target Handle id 0 is the invalid sentinel",
+            ));
+        }
+        let method = reader.text()?;
+        let block_given = match reader.u8()? {
+            0 => false,
+            1 => true,
+            _ => return Err(DecodeError::new("Call block_given must be 0 or 1")),
+        };
+        Ok(Call {
+            target,
+            method,
+            block_given,
+            payload: reader.remaining(),
+        })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self.target {
+            Target::Path(path) => {
+                writer.u8(KIND_PATH).bytes(path.as_bytes());
+            }
+            Target::Handle(id) => {
+                writer.u8(KIND_HANDLE).u32(id);
+            }
+        }
+        writer
+            .bytes(self.method.as_bytes())
+            .u8(u8::from(self.block_given))
+            .remainder(self.payload);
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_path_target_round_trips() {
+        let call = Call {
+            target: Target::Path("MyService::KV"),
+            method: "get",
+            block_given: false,
+            payload: b"\x92\x90\x80",
+        };
+        let encoded = call.encode();
+        assert_eq!(
+            Call::decode(&encoded),
+            Ok(call),
+            "a constant-path Call must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn a_handle_target_round_trips() {
+        let call = Call {
+            target: Target::Handle(7),
+            method: "commit",
+            block_given: true,
+            payload: b"",
+        };
+        let encoded = call.encode();
+        assert_eq!(
+            Call::decode(&encoded),
+            Ok(call),
+            "a Handle-targeted Call must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn the_payload_is_borrowed_not_interpreted() {
+        // Bytes that are not valid msgpack: the envelope layer must carry
+        // them through untouched, since the payload's encoding is not its
+        // concern.
+        let call = Call {
+            target: Target::Path("S"),
+            method: "m",
+            block_given: false,
+            payload: &[0xc1, 0xff, 0x00],
+        };
+        let encoded = call.encode();
+        assert_eq!(
+            Call::decode(&encoded).map(|c| c.payload.to_vec()),
+            Ok(vec![0xc1, 0xff, 0x00]),
+            "a payload the envelope cannot parse must still cross unchanged"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_path_kind_and_field_order() {
+        let call = Call {
+            target: Target::Path("S"),
+            method: "m",
+            block_given: true,
+            payload: b"\x01",
+        };
+        assert_eq!(
+            call.encode(),
+            vec![
+                0, // kind: path
+                0, 0, 0, 1, b'S', // target
+                0, 0, 0, 1, b'm', // method
+                1,    // block_given
+                0x01, // payload remainder
+            ],
+            "a constant-path Call must encode as kind byte 0 followed by target, method, \
+             block flag, and payload in that order"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_handle_kind_and_its_bare_id() {
+        let call = Call {
+            target: Target::Handle(0x0102_0304),
+            method: "m",
+            block_given: false,
+            payload: b"",
+        };
+        assert_eq!(
+            call.encode(),
+            vec![
+                1, // kind: handle
+                1, 2, 3, 4, // target: the id alone, with no length prefix
+                0, 0, 0, 1, b'm', // method
+                0,    // block_given
+            ],
+            "a Handle-targeted Call must encode as kind byte 1 followed by the bare \
+             big-endian id, not a length-prefixed byte string"
+        );
+    }
+
+    #[test]
+    fn an_unknown_kind_is_refused() {
+        let bytes = [9u8, 0, 0, 0, 0];
+        assert!(
+            Call::decode(&bytes).is_err(),
+            "a Call kind that is neither path nor handle must be rejected as a wire violation"
+        );
+    }
+
+    #[test]
+    fn handle_id_zero_is_refused() {
+        let call_bytes = {
+            let mut w = Writer::new();
+            w.u8(KIND_HANDLE).u32(0).bytes(b"m").u8(0);
+            w.into_bytes()
+        };
+        assert!(
+            Call::decode(&call_bytes).is_err(),
+            "the invalid-sentinel Handle id must be rejected in the target position"
+        );
+    }
+
+    #[test]
+    fn a_non_boolean_block_flag_is_refused() {
+        let bytes = {
+            let mut w = Writer::new();
+            w.u8(KIND_PATH).bytes(b"S").bytes(b"m").u8(2);
+            w.into_bytes()
+        };
+        assert!(
+            Call::decode(&bytes).is_err(),
+            "a block_given byte that is neither 0 nor 1 must be rejected rather than coerced"
+        );
+    }
+
+    #[test]
+    fn a_truncated_call_is_refused() {
+        let bytes = [KIND_PATH, 0, 0, 0, 4, b'a'];
+        assert!(
+            Call::decode(&bytes).is_err(),
+            "a Call whose target length overruns the message must be rejected, not truncated"
+        );
+    }
+}

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

@@ -0,0 +1,101 @@
+//! The guest's report that something it was running raised.
+//!
+//! A block failure and an invocation failure carry the same three fields,
+//! so the host re-raises from either without consulting a payload codec.
+//! Distinct from a Fault, which travels the other way and is categorized
+//! by one of three reserved type names the guest maps to a proxy-side
+//! error.
+
+use super::bytes::{Reader, Writer};
+use super::DecodeError;
+
+/// The error's name, message, and backtrace as the guest saw them. `name`
+/// rather than `class` because a guest need not be object-oriented to have
+/// named the error it is reporting.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ErrorRecord {
+    pub name: String,
+    pub message: String,
+    pub backtrace: Vec<String>,
+}
+
+impl ErrorRecord {
+    pub(crate) fn read(reader: &mut Reader<'_>) -> Result<Self, DecodeError> {
+        Ok(ErrorRecord {
+            name: reader.text()?.to_owned(),
+            message: reader.text()?.to_owned(),
+            backtrace: reader.text_list()?,
+        })
+    }
+
+    pub(crate) fn write(&self, writer: &mut Writer) {
+        writer
+            .bytes(self.name.as_bytes())
+            .bytes(self.message.as_bytes())
+            .list(&self.backtrace);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample() -> ErrorRecord {
+        ErrorRecord {
+            name: "RuntimeError".into(),
+            message: "boom".into(),
+            backtrace: vec!["(eval):1".into()],
+        }
+    }
+
+    #[test]
+    fn round_trips_through_the_wire() {
+        let mut w = Writer::new();
+        sample().write(&mut w);
+        let encoded = w.into_bytes();
+        let mut r = Reader::new(&encoded);
+        assert_eq!(
+            ErrorRecord::read(&mut r),
+            Ok(sample()),
+            "an Error Record must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn an_empty_backtrace_is_legal() {
+        let record = ErrorRecord {
+            backtrace: Vec::new(),
+            ..sample()
+        };
+        let mut w = Writer::new();
+        record.write(&mut w);
+        let encoded = w.into_bytes();
+        let mut r = Reader::new(&encoded);
+        assert_eq!(
+            ErrorRecord::read(&mut r),
+            Ok(record),
+            "a guest failure with no backtrace must round-trip as an empty list, not a decode error"
+        );
+    }
+
+    #[test]
+    fn golden_layout_is_name_then_message_then_backtrace() {
+        let record = ErrorRecord {
+            name: "E".into(),
+            message: "m".into(),
+            backtrace: vec!["b".into()],
+        };
+        let mut w = Writer::new();
+        record.write(&mut w);
+        assert_eq!(
+            w.into_bytes(),
+            vec![
+                0, 0, 0, 1, b'E', // name
+                0, 0, 0, 1, b'm', // message
+                0, 0, 0, 1, // backtrace count
+                0, 0, 0, 1, b'b',
+            ],
+            "the Error Record byte layout must stay fixed for both peers to agree"
+        );
+    }
+}