kobako 0.19.0 → 0.21.0

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

@@ -0,0 +1,171 @@
+//! The host refusing or failing a Call.
+//!
+//! Every byte of a Fault is kobako's — a closed category and a message —
+//! so it rides the envelope and a guest reads a refusal with no payload
+//! codec at all.
+//!
+//! Distinct from an `ErrorRecord`, which travels the other way. The
+//! direction decides what each carries: a Fault crosses host to guest,
+//! where a backtrace would put host paths and object graphs in front of
+//! untrusted code, so it structurally has none.
+
+use super::bytes::{Reader, Writer};
+use super::DecodeError;
+
+const KIND_RUNTIME: u8 = 0;
+const KIND_ARGUMENT: u8 = 1;
+const KIND_UNDEFINED: u8 = 2;
+
+/// Which of the three failures a Fault reports.
+///
+/// A tag rather than a name because the set is closed: a category outside
+/// these three is unrepresentable, so no endpoint decides what an unknown
+/// one means. `Undefined` stays indistinguishable across its causes — an
+/// unbound path, an unknown method, a rejected name — so a guest probing
+/// the surface learns nothing from which refusal it got.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FaultKind {
+    /// A Ruby exception raised inside the Service method.
+    Runtime,
+    /// The call shape did not fit the method.
+    Argument,
+    /// No such member or method.
+    Undefined,
+}
+
+impl FaultKind {
+    fn tag(self) -> u8 {
+        match self {
+            FaultKind::Runtime => KIND_RUNTIME,
+            FaultKind::Argument => KIND_ARGUMENT,
+            FaultKind::Undefined => KIND_UNDEFINED,
+        }
+    }
+
+    fn from_tag(tag: u8) -> Result<Self, DecodeError> {
+        match tag {
+            KIND_RUNTIME => Ok(FaultKind::Runtime),
+            KIND_ARGUMENT => Ok(FaultKind::Argument),
+            KIND_UNDEFINED => Ok(FaultKind::Undefined),
+            _ => Err(DecodeError::new(
+                "Fault kind must be 0 (runtime), 1 (argument), or 2 (undefined)",
+            )),
+        }
+    }
+
+    /// The spelling the guest raises under and a frontend reports.
+    pub fn name(self) -> &'static str {
+        match self {
+            FaultKind::Runtime => "runtime",
+            FaultKind::Argument => "argument",
+            FaultKind::Undefined => "undefined",
+        }
+    }
+
+    /// Read a category from the name a frontend uses, or `None` when the
+    /// name is outside the closed set.
+    pub fn from_name(name: &str) -> Option<Self> {
+        match name {
+            "runtime" => Some(FaultKind::Runtime),
+            "argument" => Some(FaultKind::Argument),
+            "undefined" => Some(FaultKind::Undefined),
+            _ => None,
+        }
+    }
+}
+
+/// A Service-level refusal: the guest re-raises it as a rescuable
+/// exception, never a wasm trap.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fault {
+    pub kind: FaultKind,
+    pub message: String,
+}
+
+impl Fault {
+    pub fn new(kind: FaultKind, message: impl Into<String>) -> Self {
+        Fault {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    pub(crate) fn read(reader: &mut Reader<'_>) -> Result<Self, DecodeError> {
+        let kind = FaultKind::from_tag(reader.u8()?)?;
+        let message = reader.text()?.to_owned();
+        Ok(Fault { kind, message })
+    }
+
+    pub(crate) fn write(&self, writer: &mut Writer) {
+        writer.u8(self.kind.tag()).bytes(self.message.as_bytes());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_kind_round_trips_through_the_wire() {
+        for kind in [
+            FaultKind::Runtime,
+            FaultKind::Argument,
+            FaultKind::Undefined,
+        ] {
+            let fault = Fault::new(kind, "boom");
+            let mut w = Writer::new();
+            fault.write(&mut w);
+            let encoded = w.into_bytes();
+            let mut r = Reader::new(&encoded);
+            assert_eq!(
+                Fault::read(&mut r),
+                Ok(fault),
+                "every Fault kind must survive an encode and decode unchanged"
+            );
+        }
+    }
+
+    #[test]
+    fn a_kind_outside_the_closed_set_is_refused() {
+        let encoded = vec![3, 0, 0, 0, 0];
+        let mut r = Reader::new(&encoded);
+        assert!(
+            Fault::read(&mut r).is_err(),
+            "a Fault kind byte outside the three the contract fixes must be refused, not carried"
+        );
+    }
+
+    #[test]
+    fn golden_layout_is_kind_then_message() {
+        let mut w = Writer::new();
+        Fault::new(FaultKind::Argument, "m").write(&mut w);
+        assert_eq!(
+            w.into_bytes(),
+            vec![
+                1, // kind: argument
+                0, 0, 0, 1, b'm', // message
+            ],
+            "the Fault byte layout must stay fixed for both peers to agree"
+        );
+    }
+
+    #[test]
+    fn names_map_both_ways() {
+        for kind in [
+            FaultKind::Runtime,
+            FaultKind::Argument,
+            FaultKind::Undefined,
+        ] {
+            assert_eq!(
+                FaultKind::from_name(kind.name()),
+                Some(kind),
+                "a kind's name must read back as the same kind"
+            );
+        }
+        assert_eq!(
+            FaultKind::from_name("other"),
+            None,
+            "a name outside the closed set must not resolve to a kind"
+        );
+    }
+}

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

@@ -0,0 +1,232 @@
+//! The invocation frames — Frame 1's bound constant paths and Frame 3's
+//! preloaded snippets, the two both entry points read before running
+//! anything. The numbering skips Frame 2 because the `#eval` user source
+//! is raw UTF-8 with no envelope of its own.
+//!
+//! Both are mandatory-presence even when empty, so a reader never has to
+//! tell an absent frame from an empty one, and each frame's length reaches
+//! the guest from the channel's own prefix rather than from the envelope.
+
+use super::bytes::{Reader, Writer};
+use super::DecodeError;
+
+const SNIPPET_SOURCE: u8 = 0;
+const SNIPPET_BYTECODE: u8 = 1;
+
+/// Frame 1 — the bound constant paths the guest installs proxies from.
+/// Always present; an empty list means no Service is bound.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Bindings {
+    pub paths: Vec<String>,
+}
+
+impl Bindings {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let paths = reader.text_list()?;
+        reader.finish()?;
+        Ok(Bindings { paths })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        writer.list(&self.paths);
+        writer.into_bytes()
+    }
+}
+
+/// One preloaded snippet. Source carries the filename the guest compiles
+/// under; bytecode does not, because its filename — when it has one — lives
+/// in the bytecode's own debug section.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Snippet {
+    Source { name: String, body: String },
+    Bytecode { body: Vec<u8> },
+}
+
+/// Frame 3 — the preloaded snippets, in insertion order. Always present;
+/// a zero count means nothing was preloaded.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Snippets {
+    pub entries: Vec<Snippet>,
+}
+
+impl Snippets {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let count = reader.u32()? as usize;
+        // Each entry costs at least a kind byte, so a count past the bytes
+        // left cannot be satisfied; refusing it bounds the allocation.
+        if count > reader.remaining().len() {
+            return Err(DecodeError::new(
+                "Frame 3 declares more entries than the frame holds",
+            ));
+        }
+        let mut entries = Vec::with_capacity(count);
+        for _ in 0..count {
+            entries.push(match reader.u8()? {
+                SNIPPET_SOURCE => Snippet::Source {
+                    name: reader.text()?.to_owned(),
+                    body: reader.text()?.to_owned(),
+                },
+                SNIPPET_BYTECODE => Snippet::Bytecode {
+                    body: reader.bytes()?.to_vec(),
+                },
+                _ => return Err(DecodeError::new("Frame 3 snippet kind must be 0 or 1")),
+            });
+        }
+        reader.finish()?;
+        Ok(Snippets { entries })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        writer.u32(self.entries.len() as u32);
+        for entry in &self.entries {
+            match entry {
+                Snippet::Source { name, body } => {
+                    writer
+                        .u8(SNIPPET_SOURCE)
+                        .bytes(name.as_bytes())
+                        .bytes(body.as_bytes());
+                }
+                Snippet::Bytecode { body } => {
+                    writer.u8(SNIPPET_BYTECODE).bytes(body);
+                }
+            }
+        }
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_bindings_round_trip() {
+        let encoded = Bindings::default().encode();
+        assert_eq!(
+            Bindings::decode(&encoded),
+            Ok(Bindings::default()),
+            "a Sandbox with no bindings must send a present, empty Frame 1"
+        );
+    }
+
+    #[test]
+    fn bindings_round_trip_every_path() {
+        let bindings = Bindings {
+            paths: vec!["MyService::KV".into(), "File".into()],
+        };
+        let encoded = bindings.encode();
+        assert_eq!(
+            Bindings::decode(&encoded),
+            Ok(bindings),
+            "Frame 1 must carry every bound path in order"
+        );
+    }
+
+    #[test]
+    fn snippets_round_trip_both_kinds_in_order() {
+        let snippets = Snippets {
+            entries: vec![
+                Snippet::Source {
+                    name: "Helper".into(),
+                    body: "def helper; end".into(),
+                },
+                Snippet::Bytecode {
+                    body: vec![0x52, 0x49, 0x54, 0x45],
+                },
+            ],
+        };
+        let encoded = snippets.encode();
+        assert_eq!(
+            Snippets::decode(&encoded),
+            Ok(snippets),
+            "Frame 3 must carry source and bytecode entries in insertion order"
+        );
+    }
+
+    #[test]
+    fn an_empty_snippet_table_round_trips() {
+        let encoded = Snippets::default().encode();
+        assert_eq!(
+            Snippets::decode(&encoded),
+            Ok(Snippets::default()),
+            "a Sandbox with no preloads must send a present, zero-count Frame 3"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_bindings_as_a_counted_list() {
+        let bindings = Bindings {
+            paths: vec!["A".into()],
+        };
+        assert_eq!(
+            bindings.encode(),
+            vec![
+                0, 0, 0, 1, // path count
+                0, 0, 0, 1, b'A',
+            ],
+            "Frame 1 must be a counted list of paths, so the count precedes the first entry"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_snippet_entry_shape() {
+        let snippets = Snippets {
+            entries: vec![
+                Snippet::Source {
+                    name: "N".into(),
+                    body: "b".into(),
+                },
+                Snippet::Bytecode { body: vec![0x52] },
+            ],
+        };
+        assert_eq!(
+            snippets.encode(),
+            vec![
+                0, 0, 0, 2, // entry count
+                0, // kind: source
+                0, 0, 0, 1, b'N', // name, source only
+                0, 0, 0, 1, b'b', // body
+                1,    // kind: bytecode
+                0, 0, 0, 1, 0x52, // body, no name
+            ],
+            "a source entry must encode as kind byte 0 with a name and a bytecode entry as \
+             kind byte 1 with none, so the two stay distinguishable by their tag alone"
+        );
+    }
+
+    #[test]
+    fn an_unknown_snippet_kind_is_refused() {
+        let bytes = {
+            let mut w = Writer::new();
+            w.u32(1).u8(9);
+            w.into_bytes()
+        };
+        assert!(
+            Snippets::decode(&bytes).is_err(),
+            "a Frame 3 snippet kind that is neither source nor bytecode must be rejected"
+        );
+    }
+
+    #[test]
+    fn a_snippet_count_the_frame_cannot_satisfy_is_refused() {
+        let bytes = [0xff, 0xff, 0xff, 0xff];
+        assert!(
+            Snippets::decode(&bytes).is_err(),
+            "a Frame 3 count larger than the frame must be rejected before any allocation"
+        );
+    }
+
+    #[test]
+    fn trailing_bytes_after_a_frame_are_refused() {
+        let mut encoded = Bindings::default().encode();
+        encoded.push(0);
+        assert!(
+            Bindings::decode(&encoded).is_err(),
+            "bytes past Frame 1's last field must fail loudly as a framing desync"
+        );
+    }
+}

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

@@ -0,0 +1,261 @@
+//! The Outcome envelope — one invocation's final result.
+//!
+//! Every Panic field is typed here, so a host attributes a failed
+//! invocation and reports the correction for it without decoding a payload
+//! 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;
+
+/// Who a failed invocation attributes to.
+///
+/// The wire field is an open set of byte strings, but only two values
+/// carry meaning — so both sides read and write it through this type and
+/// cannot come to spell either one differently. The fallback rule lives in
+/// `from_name`: an unrecognised value attributes to the sandbox rather
+/// than widening what a Service can claim.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Origin {
+    /// The guest script raised, or a boot step faulted.
+    #[default]
+    Sandbox,
+    /// An unrescued Service call raised.
+    Service,
+}
+
+impl Origin {
+    /// This attribution's spelling on the wire.
+    pub fn name(self) -> &'static str {
+        match self {
+            Origin::Sandbox => "sandbox",
+            Origin::Service => "service",
+        }
+    }
+
+    /// Read a wire spelling back. Everything other than `"service"`,
+    /// recognised or not, attributes to the sandbox.
+    pub fn from_name(name: &str) -> Self {
+        match name {
+            "service" => Origin::Service,
+            _ => Origin::Sandbox,
+        }
+    }
+}
+
+/// How an invocation ended.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Outcome {
+    /// The invocation completed; the bytes are its value, codec-encoded.
+    Ok(Vec<u8>),
+    /// The invocation terminated with an uncaught exception.
+    Panic(Panic),
+}
+
+/// An uncaught top-level failure, plus what attribution and correction need.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Panic {
+    pub origin: Origin,
+    pub error: ErrorRecord,
+    /// The names the invocation could have used in place of the one it
+    /// named. Empty when the failure offers no correction.
+    pub available: Vec<String>,
+}
+
+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 => {
+                let origin = Origin::from_name(reader.text()?);
+                let error = ErrorRecord::read(&mut reader)?;
+                let available = reader.text_list()?;
+                reader.finish()?;
+                Ok(Outcome::Panic(Panic {
+                    origin,
+                    error,
+                    available,
+                }))
+            }
+            _ => Err(DecodeError::new(
+                "Outcome tag must be 0x01 (ok) or 0x02 (panic)",
+            )),
+        }
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self {
+            Outcome::Ok(value) => {
+                writer.u8(TAG_OK).remainder(value);
+            }
+            Outcome::Panic(panic) => {
+                writer.u8(TAG_PANIC).bytes(panic.origin.name().as_bytes());
+                panic.error.write(&mut writer);
+                writer.list(&panic.available);
+            }
+        }
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn panic_sample() -> Panic {
+        Panic {
+            origin: Origin::Sandbox,
+            error: ErrorRecord {
+                name: "RuntimeError".into(),
+                message: "boom".into(),
+                backtrace: vec!["(eval):1".into()],
+            },
+            available: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn an_ok_outcome_round_trips() {
+        let outcome = Outcome::Ok(vec![0x2a]);
+        let encoded = outcome.encode();
+        assert_eq!(
+            Outcome::decode(&encoded),
+            Ok(outcome),
+            "an ok Outcome must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn a_panic_round_trips() {
+        let outcome = Outcome::Panic(panic_sample());
+        let encoded = outcome.encode();
+        assert_eq!(
+            Outcome::decode(&encoded),
+            Ok(outcome),
+            "a Panic Outcome must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn a_panic_carrying_available_names_round_trips() {
+        let outcome = Outcome::Panic(Panic {
+            available: vec!["Worker".into(), "Helper".into()],
+            ..panic_sample()
+        });
+        let encoded = outcome.encode();
+        assert_eq!(
+            Outcome::decode(&encoded),
+            Ok(outcome),
+            "a Panic offering a correction must carry its names through in order"
+        );
+    }
+
+    #[test]
+    fn a_panic_offering_no_correction_decodes_as_an_empty_list() {
+        let encoded = Outcome::Panic(panic_sample()).encode();
+        match Outcome::decode(&encoded) {
+            Ok(Outcome::Panic(panic)) => assert!(
+                panic.available.is_empty(),
+                "a Panic with no correction to offer must decode as an empty list, not a decode error"
+            ),
+            other => panic!("expected a Panic, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn attribution_reads_origin_alone() {
+        let service = Panic {
+            origin: Origin::Service,
+            ..panic_sample()
+        };
+        assert_eq!(
+            Outcome::decode(&Outcome::Panic(service.clone()).encode()),
+            Ok(Outcome::Panic(service)),
+            "a Panic written with Service attribution must decode back to it, since the \
+             origin field is all a host reads to attribute"
+        );
+    }
+
+    #[test]
+    fn bytes_past_the_available_list_are_refused() {
+        let mut encoded = Outcome::Panic(panic_sample()).encode();
+        encoded.push(0x2a);
+        assert!(
+            Outcome::decode(&encoded).is_err(),
+            "a Panic is self-delimiting to its last field, so trailing bytes must fail as a framing desync"
+        );
+    }
+
+    #[test]
+    fn an_unrecognised_origin_attributes_to_the_sandbox() {
+        // Written by hand: the origin field is an open set on the wire, so
+        // 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");
+        panic_sample().error.write(&mut writer);
+        writer.list::<&[u8]>(&[]);
+        assert_eq!(
+            Outcome::decode(&writer.into_bytes()),
+            Ok(Outcome::Panic(panic_sample())),
+            "an origin outside the reserved set must decode as sandbox attribution rather \
+             than widening what a Service can claim"
+        );
+    }
+
+    #[test]
+    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"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_panic_field_order() {
+        let panic = Panic {
+            origin: Origin::Service,
+            error: ErrorRecord {
+                name: "E".into(),
+                message: "m".into(),
+                backtrace: vec!["l".into()],
+            },
+            available: vec!["W".into()],
+        };
+        assert_eq!(
+            Outcome::Panic(panic).encode(),
+            vec![
+                0x02, // 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
+                0, 0, 0, 1, // backtrace count
+                0, 0, 0, 1, b'l', // backtrace[0]
+                0, 0, 0, 1, // available count
+                0, 0, 0, 1, b'W', // available[0]
+            ],
+            "attribution reads origin before the Error Record, so the field order must stay fixed"
+        );
+    }
+
+    #[test]
+    fn a_zero_length_outcome_is_refused() {
+        assert!(
+            Outcome::decode(&[]).is_err(),
+            "a zero-length outcome buffer must be rejected as a wire violation"
+        );
+    }
+
+    #[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"
+        );
+    }
+}