kobako 0.28.0 → 0.30.0

data/crates/kobako-runtime/src/endpoint/buffer.rs

@@ -0,0 +1,192 @@
+//! Guest linear-memory I/O for the ABI's buffer handoffs, whether the
+//! invocation body or an upcall drives one.
+//!
+//! The two shared steps answer an error kind, and each caller words it,
+//! because depth decides what the same problem means: before the export
+//! call it is a `Trap` or an intact runtime, inside a callback it is a
+//! wire failure the guest receives.
+
+use kobako_transport::abi::{unpack_ptr_len, MAX_DISPATCH_PAYLOAD};
+
+use super::{GuestInstance, RUNTIME_INCOMPATIBLE, SANDBOX_RUNTIME_NOT_KOBAKO};
+
+// The size-limit messages here and in the endpoint name the cap as 16 MiB, so
+// moving the cap fails the build until they are reworded with it.
+const _: () = assert!(MAX_DISPATCH_PAYLOAD == 16 << 20);
+
+/// Why a host write into guest memory failed.
+pub(super) enum WriteError<F> {
+    TooLarge,
+    /// The allocator or the memory is missing or mistyped; carries the
+    /// message for it.
+    Incompatible(&'static str),
+    Trapped(F),
+    /// The allocator ran and answered 0.
+    OutOfMemory,
+    OutOfBounds,
+}
+
+/// Why a host read of a guest-named buffer failed.
+pub(super) enum ReadError {
+    TooLarge,
+    OutOfBounds,
+}
+
+/// Allocate a guest buffer and copy `bytes` into it, answering the buffer's
+/// address.
+pub(super) fn alloc_and_write<G: GuestInstance>(
+    guest: &mut G,
+    bytes: &[u8],
+) -> Result<u32, WriteError<G::Fault>> {
+    let len = checked_payload_len(bytes.len()).map_err(|_| WriteError::TooLarge)?;
+    if guest.memory().is_none() {
+        return Err(WriteError::Incompatible(SANDBOX_RUNTIME_NOT_KOBAKO));
+    }
+    let ptr = guest
+        .alloc(len as u32)
+        .ok_or(WriteError::Incompatible(RUNTIME_INCOMPATIBLE))?
+        .map_err(WriteError::Trapped)?;
+    if ptr == 0 {
+        return Err(WriteError::OutOfMemory);
+    }
+    let memory = guest
+        .memory()
+        .ok_or(WriteError::Incompatible(SANDBOX_RUNTIME_NOT_KOBAKO))?;
+    let range = guest_buffer_range(ptr as usize, bytes.len(), memory.len())
+        .map_err(|_| WriteError::OutOfBounds)?;
+    memory[range].copy_from_slice(bytes);
+    Ok(ptr)
+}
+
+/// Copy out the buffer the guest names; a length past the 16 MiB cap is
+/// refused before memory is touched.
+pub(super) fn read_buffer(data: &[u8], ptr: usize, len: usize) -> Result<Vec<u8>, ReadError> {
+    if len > MAX_DISPATCH_PAYLOAD {
+        return Err(ReadError::TooLarge);
+    }
+    let range = guest_buffer_range(ptr, len, data.len()).map_err(|_| ReadError::OutOfBounds)?;
+    Ok(data[range].to_vec())
+}
+
+/// Every host write boundary routes its length through here, so the
+/// wire-violation reason is uniform.
+pub(super) fn checked_payload_len(len: usize) -> Result<i32, &'static str> {
+    if len > MAX_DISPATCH_PAYLOAD {
+        return Err("payload exceeds the 16 MiB limit");
+    }
+    // The cap above sits below `i32::MAX`, so this conversion cannot wrap.
+    i32::try_from(len).map_err(|_| "payload exceeds the 16 MiB limit")
+}
+
+/// The bytes of guest memory a `(ptr, len)` names.
+fn guest_buffer_range(
+    ptr: usize,
+    len: usize,
+    mem_size: usize,
+) -> Result<core::ops::Range<usize>, &'static str> {
+    let end = ptr.checked_add(len).ok_or("ptr + len overflow")?;
+    if end > mem_size {
+        return Err("range exceeds Sandbox memory size");
+    }
+    Ok(ptr..end)
+}
+
+/// The `(ptr, len)` the guest packs for any answer it hands back, the
+/// outcome and a block's result alike.
+pub(super) fn unpack_guest_buffer(packed: u64) -> (usize, usize) {
+    let (ptr, len) = unpack_ptr_len(packed);
+    (ptr as usize, len as usize)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        checked_payload_len, guest_buffer_range, unpack_guest_buffer, MAX_DISPATCH_PAYLOAD,
+    };
+
+    // @behavior WE-059
+    #[test]
+    fn a_transfer_of_nothing_or_at_the_cap_is_admitted() {
+        assert_eq!(
+            (
+                checked_payload_len(0),
+                checked_payload_len(MAX_DISPATCH_PAYLOAD)
+            ),
+            (Ok(0), Ok(MAX_DISPATCH_PAYLOAD as i32)),
+            "0 bytes and MAX_DISPATCH_PAYLOAD bytes through checked_payload_len must be admitted"
+        );
+    }
+
+    // @behavior WE-060
+    #[test]
+    fn a_transfer_past_the_cap_is_refused() {
+        assert!(
+            checked_payload_len(MAX_DISPATCH_PAYLOAD + 1).is_err()
+                && checked_payload_len(usize::MAX).is_err(),
+            "one byte past MAX_DISPATCH_PAYLOAD and usize::MAX through checked_payload_len must be \
+             refused"
+        );
+    }
+
+    // @behavior WE-061
+    #[test]
+    fn a_guest_buffer_is_read_half_open() {
+        assert_eq!(
+            guest_buffer_range(10, 5, 100),
+            Ok(10..15),
+            "5 bytes at 10 in 100 bytes of memory through guest_buffer_range must answer 10..15"
+        );
+    }
+
+    // @behavior WE-062
+    #[test]
+    fn a_buffer_of_no_length_is_read_at_any_pointer_inside_memory() {
+        assert_eq!(
+            (guest_buffer_range(0, 0, 0), guest_buffer_range(42, 0, 100)),
+            (Ok(0..0), Ok(42..42)),
+            "no bytes at 0 in no memory and at 42 in 100 bytes through guest_buffer_range must \
+             answer an empty range there"
+        );
+    }
+
+    // @behavior WE-063
+    #[test]
+    fn a_pointer_and_length_that_overflow_are_refused() {
+        assert!(
+            guest_buffer_range(usize::MAX, 1, usize::MAX).is_err(),
+            "1 byte at usize::MAX through guest_buffer_range must be refused"
+        );
+    }
+
+    // @behavior WE-064
+    #[test]
+    fn a_buffer_ending_past_memory_is_refused() {
+        assert_eq!(
+            (guest_buffer_range(10, 100, 50).is_err(), guest_buffer_range(0, 50, 50)),
+            (true, Ok(0..50)),
+            "100 bytes at 10 in 50 bytes of memory through guest_buffer_range must be refused, and \
+             50 bytes at 0 admitted"
+        );
+    }
+
+    // @behavior WE-001
+    #[test]
+    fn a_packed_answer_carries_the_pointer_high_and_the_length_low() {
+        assert_eq!(
+            unpack_guest_buffer(0xAABB_CCDD_1122_3344),
+            (0xAABB_CCDD, 0x1122_3344),
+            "0xAABB_CCDD_1122_3344 through unpack_guest_buffer must answer pointer 0xAABB_CCDD and \
+             length 0x1122_3344"
+        );
+    }
+
+    // @behavior WE-065
+    #[test]
+    fn a_packed_answer_of_nothing_is_a_zero_pair() {
+        assert_eq!(
+            unpack_guest_buffer(0),
+            (0, 0),
+            "0 through unpack_guest_buffer must answer pointer 0 and length 0"
+        );
+    }
+}

data/crates/kobako-runtime/src/endpoint/capture.rs

@@ -0,0 +1,115 @@
+//! Per-channel stdout / stderr capture sizing and clipping.
+//!
+//! Two pure helpers shared by the run path: one sizes the per-run pipe, the
+//! other clips a captured snapshot back to the configured limit and reports
+//! whether the limit was passed. Kept channel-agnostic (a function of `limit`,
+//! not of which channel) so a regression that only breaks one channel cannot
+//! sneak through the test that pins them.
+
+/// One byte past the limit, so "wrote exactly the limit" and "passed the
+/// limit" stay distinguishable.
+pub fn pipe_capacity(limit: Option<usize>) -> usize {
+    match limit {
+        Some(limit) => limit.saturating_add(1),
+        None => usize::MAX,
+    }
+}
+
+/// Takes the snapshot by value and truncates in place, so the readback
+/// costs one copy out of the pipe rather than two.
+pub fn clip_capture(mut raw: Vec<u8>, limit: Option<usize>) -> (Vec<u8>, bool) {
+    match limit {
+        Some(limit) if raw.len() > limit => {
+            raw.truncate(limit);
+            (raw, true)
+        }
+        _ => (raw, false),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{clip_capture, pipe_capacity};
+
+    // @behavior S-108
+    #[test]
+    fn a_pipe_holds_one_byte_past_its_limit() {
+        assert_eq!(
+            (pipe_capacity(Some(5)), pipe_capacity(Some(0))),
+            (6, 1),
+            "a limit of 5 and of 0 through pipe_capacity must size the pipe 6 and 1"
+        );
+    }
+
+    // @behavior S-109
+    #[test]
+    fn a_pipe_without_a_limit_holds_usize_max() {
+        assert_eq!(
+            pipe_capacity(None),
+            usize::MAX,
+            "no limit through pipe_capacity must size the pipe usize::MAX"
+        );
+    }
+
+    // @behavior S-110
+    #[test]
+    fn a_pipe_past_usize_max_saturates() {
+        assert_eq!(
+            pipe_capacity(Some(usize::MAX)),
+            usize::MAX,
+            "a limit of usize::MAX through pipe_capacity must saturate at usize::MAX"
+        );
+    }
+
+    // @behavior S-111
+    #[test]
+    fn a_capture_under_its_limit_stays_whole() {
+        assert_eq!(
+            clip_capture(b"abc".to_vec(), Some(5)),
+            (b"abc".to_vec(), false),
+            "3 bytes under a limit of 5 through clip_capture must stay whole and untruncated"
+        );
+    }
+
+    // @behavior S-112
+    #[test]
+    fn a_capture_at_its_limit_is_not_truncated() {
+        assert_eq!(
+            clip_capture(b"abcde".to_vec(), Some(5)),
+            (b"abcde".to_vec(), false),
+            "5 bytes at a limit of 5 through clip_capture must stay whole and untruncated"
+        );
+    }
+
+    // @behavior S-024
+    #[test]
+    fn a_capture_past_its_limit_is_clipped_and_truncated() {
+        // The pipe holds one byte past the limit, so 6 bytes is the most a
+        // limit of 5 can capture.
+        assert_eq!(
+            clip_capture(b"abcdef".to_vec(), Some(5)),
+            (b"abcde".to_vec(), true),
+            "6 bytes past a limit of 5 through clip_capture must clip to 5 and flag truncation"
+        );
+    }
+
+    // @behavior S-033
+    #[test]
+    fn a_capture_without_a_limit_stays_whole() {
+        assert_eq!(
+            clip_capture(b"abcdef".to_vec(), None),
+            (b"abcdef".to_vec(), false),
+            "6 bytes with no limit through clip_capture must stay whole and untruncated"
+        );
+    }
+
+    // @behavior S-100 S-101
+    #[test]
+    fn an_empty_capture_stays_empty() {
+        assert_eq!(
+            clip_capture(Vec::new(), Some(5)),
+            (Vec::new(), false),
+            "no bytes under a limit of 5 through clip_capture must stay empty and untruncated"
+        );
+    }
+}

data/crates/kobako-runtime/src/endpoint/dispatch.rs

@@ -0,0 +1,253 @@
+//! Host side of the `__kobako_upcall` import: hand the guest's Call to
+//! the bound `DispatchHandler` and write its Reply back into guest memory.
+//! A request under a tag the host does not serve is answered as
+//! unsupported, so a guest asking for a later operation can fall back.
+//!
+//! A failure lands on whoever is answerable for it, and always says why.
+//! A trap the guest raises during a callback into it ends the invocation
+//! as that trap. A Call the host could not answer is answered as an
+//! internal failure naming why, and an answer too large for a message as
+//! the Service's own failure. Only an answer that cannot be written into
+//! guest memory at all ends the invocation, as a trap naming why.
+
+use std::sync::Arc;
+
+use kobako_transport::abi::pack_ptr_len;
+use kobako_transport::envelope::{
+    Downcall, Fault, FaultKind, Reply, Unsupported, Upcall, YieldReply,
+};
+
+use super::buffer::{
+    alloc_and_write, checked_payload_len, read_buffer, unpack_guest_buffer, ReadError, WriteError,
+};
+use super::{GuestInstance, RUNTIME_INCOMPATIBLE, SANDBOX_RUNTIME_NOT_KOBAKO};
+use crate::dispatch::DispatchHandler;
+use crate::error::Trap;
+use crate::yielder::Yielder;
+
+/// The message of the trap ending an invocation its host gave up on.
+pub const ABANDONED: &str = "the host abandoned the invocation";
+
+/// The state of the Calls open on one instance: who answers them, how many
+/// stand open, and the first trap a callback into the guest raised, as the
+/// guest counts the Calls it has open.
+pub struct Calls<F> {
+    on_dispatch: Option<Arc<dyn DispatchHandler>>,
+    open: u32,
+    reentry_trap: Option<F>,
+}
+
+impl<F> Default for Calls<F> {
+    fn default() -> Self {
+        Self {
+            on_dispatch: None,
+            open: 0,
+            reentry_trap: None,
+        }
+    }
+}
+
+impl<F> Calls<F> {
+    /// Have `handler` answer the Calls on this instance.
+    pub fn bind(&mut self, handler: Arc<dyn DispatchHandler>) {
+        self.on_dispatch = Some(handler);
+    }
+
+    /// Whether its host gave up on the invocation, which ends at the next
+    /// host call it answers.
+    pub fn abandoned(&self) -> bool {
+        self.on_dispatch
+            .as_ref()
+            .is_some_and(|handler| handler.abandoned())
+    }
+}
+
+/// How an upcall ends an invocation instead of answering.
+pub enum UpcallEnd<F> {
+    /// The guest trapped during a callback into it.
+    Fault(F),
+    /// The host gave the invocation up.
+    Abandoned,
+    /// The answer could not be written into guest memory, naming why.
+    Unwritable(&'static str),
+}
+
+/// The Yielder of one upcall's frame, built over that frame's guest, so nested
+/// dispatch frames each carry their own and stack on the call stack with no
+/// shared slot.
+struct FrameYielder<'a, G> {
+    guest: &'a mut G,
+    frame: u32,
+}
+
+impl<G: GuestInstance> Yielder for FrameYielder<'_, G> {
+    fn frame(&self) -> u32 {
+        self.frame
+    }
+
+    fn yield_to_block(&mut self, frame: u32, args: &[u8]) -> Result<YieldReply, Trap> {
+        let bytes =
+            drive_yield(self.guest, frame, args).map_err(|msg| Trap::Other(msg.to_string()))?;
+        YieldReply::decode(&bytes).map_err(|err| Trap::Other(err.to_string()))
+    }
+}
+
+/// Answer one `__kobako_upcall` call with the packed `(ptr<<32)|len` of
+/// the Reply, or what ends the invocation instead.
+pub fn handle<G: GuestInstance>(
+    guest: &mut G,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<i64, UpcallEnd<G::Fault>> {
+    let reply = reply_to(guest, req_ptr, req_len)
+        .unwrap_or_else(|reason| Reply::Fault(Fault::new(FaultKind::Internal, reason)));
+    let written = write_reply(guest, &fit_in_message(reply).encode());
+    if let Some(trap) = guest.calls().reentry_trap.take() {
+        return Err(UpcallEnd::Fault(trap));
+    }
+    if guest.calls().abandoned() {
+        return Err(UpcallEnd::Abandoned);
+    }
+    written.map_err(UpcallEnd::Unwritable)
+}
+
+/// An answer past the message cap is the Service's to change, as any other
+/// answer the host cannot write is.
+fn fit_in_message(reply: Reply) -> Reply {
+    let bytes = reply.encode().len();
+    match checked_payload_len(bytes) {
+        Ok(_) => reply,
+        Err(limit) => Reply::Fault(Fault::new(
+            FaultKind::Runtime,
+            format!("Sandbox could not write the Service's answer: {limit}"),
+        )),
+    }
+}
+
+fn reply_to<G: GuestInstance>(
+    guest: &mut G,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<Reply, &'static str> {
+    let req_bytes = read_request(guest, req_ptr, req_len)?;
+    // The endpoint decodes the Envelope, here and in `FrameYielder`, so
+    // the frontend never sees a frame; the payload inside it stays bytes
+    // the whole way through.
+    let call = match Upcall::decode(&req_bytes) {
+        Ok(Upcall::Call(call)) => call,
+        Ok(_) => {
+            return Ok(Reply::Unsupported(Unsupported::new(
+                "the host does not serve this request",
+            )))
+        }
+        Err(_) => {
+            return Err(
+                "the guest sent a malformed Call envelope — please report this as a kobako bug",
+            )
+        }
+    };
+
+    // A frontend always installs the dispatch handler before invoking the
+    // runtime, so reaching this branch indicates a misuse rather than a
+    // normal control path.
+    let handler = guest
+        .calls()
+        .on_dispatch
+        .clone()
+        .ok_or("a Sandbox callback fired outside an active invocation — please report this as a kobako bug")?;
+
+    // A frame-scoped yielder lends the guest to the handler. The borrow ends
+    // with the block, freeing it for `write_reply`; nested dispatch frames
+    // each build their own, so the LIFO re-entry lives on the stack.
+    let frame = {
+        let calls = guest.calls();
+        calls.open += 1;
+        calls.open - 1
+    };
+    let reply = {
+        let mut yielder = FrameYielder { guest, frame };
+        handler.dispatch(call, &mut yielder)
+    };
+    guest.calls().open -= 1;
+    reply.ok_or(
+        "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug",
+    )
+}
+
+fn write_reply<G: GuestInstance>(guest: &mut G, bytes: &[u8]) -> Result<i64, &'static str> {
+    let ptr = write_from_callback(guest, bytes)?;
+    // The write has already held the length to the payload cap.
+    Ok(pack_ptr_len(ptr, bytes.len() as u32) as i64)
+}
+
+/// The request the guest hands the upcall import. Its `(ptr, len)` are
+/// guest addresses, so they are read unsigned.
+fn read_request<G: GuestInstance>(
+    guest: &mut G,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<Vec<u8>, &'static str> {
+    let memory = guest.memory().ok_or(SANDBOX_RUNTIME_NOT_KOBAKO)?;
+    read_buffer(memory, req_ptr as u32 as usize, req_len as u32 as usize).map_err(|err| match err {
+        ReadError::TooLarge => "request payload exceeds the 16 MiB limit",
+        ReadError::OutOfBounds => "the Sandbox produced an out-of-bounds request",
+    })
+}
+
+/// Keep a trap the guest raised during a callback into it for the upcall to
+/// end the invocation with, and answer the callback's own reason.
+fn keep_trap<G: GuestInstance>(
+    guest: &mut G,
+    trap: G::Fault,
+    reason: &'static str,
+) -> &'static str {
+    guest.calls().reentry_trap.get_or_insert(trap);
+    reason
+}
+
+/// Write `bytes` into the guest from inside a callback. A guest that has
+/// already trapped is not called again.
+fn write_from_callback<G: GuestInstance>(guest: &mut G, bytes: &[u8]) -> Result<u32, &'static str> {
+    if guest.calls().reentry_trap.is_some() {
+        return Err("the Sandbox already trapped during this invocation");
+    }
+    alloc_and_write(guest, bytes).map_err(|err| match err {
+        WriteError::TooLarge => "payload exceeds the 16 MiB limit",
+        WriteError::Incompatible(message) => message,
+        WriteError::Trapped(trap) => keep_trap(
+            guest,
+            trap,
+            "the Sandbox trapped while allocating memory for the request",
+        ),
+        WriteError::OutOfMemory => "the Sandbox ran out of memory while preparing the request",
+        WriteError::OutOfBounds => "could not write the request into the Sandbox's memory",
+    })
+}
+
+fn drive_yield<G: GuestInstance>(
+    guest: &mut G,
+    frame: u32,
+    args: &[u8],
+) -> Result<Vec<u8>, &'static str> {
+    let request = Downcall::Yield {
+        frame,
+        args: args.to_vec(),
+    }
+    .encode();
+    let len_i32 = checked_payload_len(request.len())?;
+    let req_ptr = write_from_callback(guest, &request)? as i32;
+
+    let packed = guest
+        .downcall(req_ptr, len_i32)
+        .ok_or(RUNTIME_INCOMPATIBLE)?
+        .map_err(|trap| keep_trap(guest, trap, "the Sandbox trapped while invoking a block"))?;
+    let (reply_ptr, reply_len) = unpack_guest_buffer(packed);
+    if reply_len == 0 {
+        return Err("the Sandbox returned an empty block result");
+    }
+    let memory = guest.memory().ok_or(SANDBOX_RUNTIME_NOT_KOBAKO)?;
+    read_buffer(memory, reply_ptr, reply_len).map_err(|err| match err {
+        ReadError::TooLarge => "block result payload exceeds the 16 MiB limit",
+        ReadError::OutOfBounds => "the Sandbox returned an out-of-bounds block result",
+    })
+}