runtime: I/O API + simulator

Cargo.toml

@@ -29,6 +29,7 @@ members = [
   "crates/query",
   "crates/runtime",
   "crates/runtime-core",
+  "crates/runtime-io",
   "crates/sats",
   "crates/schema",
   "crates/smoketests",
@@ -176,6 +177,7 @@ spacetimedb-query = { path = "crates/query", version = "=2.10.1" }
 spacetimedb-query-builder = { path = "crates/query-builder", version = "=2.10.1" }
 spacetimedb-runtime = { path = "crates/runtime", version = "=2.10.1" }
 spacetimedb-runtime-core = { path = "crates/runtime-core", version = "=2.10.1" }
+spacetimedb-runtime-io = { path = "crates/runtime-io", version = "=2.10.1" }
 spacetimedb-sats = { path = "crates/sats", version = "=2.10.1" }
 spacetimedb-schema = { path = "crates/schema", version = "=2.10.1" }
 spacetimedb-snapshot = { path = "crates/snapshot", version = "=2.10.1" }

crates/runtime-io/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "spacetimedb-runtime-io"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[lints]
+workspace = true
+
+[features]
+sim = ["dep:slab", "dep:spin"]
+
+[dependencies]
+slab = { version = "0.4", default-features = false, optional = true }
+spin = { version = "0.9", default-features = false, features = ["mutex", "spin_mutex"], optional = true }
+thiserror = { version = "2.0", default-features = false }
+zerocopy = "0.8"
+
+[dev-dependencies]
+spacetimedb-runtime-core = { workspace = true, features = ["sim"] }
+spacetimedb-runtime-io = { path = ".", features = ["sim"] }
+tokio.workspace = true

crates/runtime-io/src/buf.rs

@@ -0,0 +1,163 @@
+use alloc::boxed::Box;
+use core::{alloc::Layout, any::TypeId, ptr::NonNull};
+use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
+
+use crate::SECTOR_SIZE;
+
+/// Types that can be safely converted to and from sector-aligned byte slices.
+pub trait AlignedBytes: Sized {
+    /// Assert that the type' size is a multiple of [SECTOR_SIZE] and has the
+    /// right alignment.
+    ///
+    /// The type must also not rely on drop glue, i.e. `!core::mem::needs_drop()`.
+    ///
+    /// NOTE: Associated constants are evaluated lazily -- add a free
+    ///
+    /// `const _: () = <T as AlignedBytes>::ASSERT_VALID_LAYOUT;`
+    ///
+    /// for each `T` that is supposed to be used as an `AlignedBytes`.
+    const ASSERT_VALID_LAYOUT: () = {
+        assert!(align_of::<Self>() == SECTOR_SIZE);
+        assert!(size_of::<Self>().is_multiple_of(SECTOR_SIZE));
+        assert!(!core::mem::needs_drop::<Self>());
+    };
+
+    /// Reinterpret `self` as a byte slice.
+    ///
+    /// The returned slice will be of length `size_of::<Self>()`.
+    fn as_bytes(&self) -> &[u8];
+
+    /// Reinterpret `self` as a mutable byte slice.
+    ///
+    /// The returned slice will be of length `size_of::<Self>()`.
+    fn as_bytes_mut(&mut self) -> &mut [u8];
+
+    /// Reinterpret a byte slice as `Self`.
+    ///
+    /// The slice must be of length `size_of::<Self>()`.
+    ///
+    /// NOTE: Any slice of the right size, but consisting of only `0` (zero)
+    /// bytes can be converted to `Self`. It is the caller's responsibility to
+    /// validate the returned type as per the application's invariants.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `b.len() != size_of::<Self>()`.
+    fn from_bytes(b: &[u8]) -> Self;
+}
+
+impl<T: FromBytes + IntoBytes + KnownLayout + Immutable> AlignedBytes for T {
+    fn as_bytes(&self) -> &[u8] {
+        <T as IntoBytes>::as_bytes(self)
+    }
+
+    fn as_bytes_mut(&mut self) -> &mut [u8] {
+        <T as IntoBytes>::as_mut_bytes(self)
+    }
+
+    fn from_bytes(b: &[u8]) -> Self {
+        Self::read_from_bytes(b).unwrap()
+    }
+}
+
+/// A type-erased [AlignedBytes] heap allocation.
+#[derive(Debug)]
+pub struct ErasedBox {
+    ptr: NonNull<u8>,
+    len: usize,
+    layout: Layout,
+    ty: TypeId,
+}
+
+impl ErasedBox {
+    /// Create an [ErasedBox] from boxed [AlignedBytes]..
+    pub fn from_aligned<B: AlignedBytes + Send + 'static>(b: Box<B>) -> Self {
+        let () = B::ASSERT_VALID_LAYOUT;
+
+        let ptr = Box::into_raw(b);
+        Self {
+            ptr: NonNull::new(ptr.cast()).unwrap(),
+            len: size_of::<B>(),
+            layout: Layout::from_size_align(size_of::<B>(), align_of::<B>()).unwrap(),
+            ty: TypeId::of::<B>(),
+        }
+    }
+
+    /// Reify `B` via casting.
+    pub fn into_aligned<B: AlignedBytes + Send + 'static>(self) -> Box<B> {
+        assert_eq!(self.len, size_of::<B>());
+        assert_eq!(self.ty, TypeId::of::<B>());
+
+        let boxed = unsafe { Box::from_raw(self.ptr.as_ptr().cast::<B>()) };
+        // Prevent drop, which would deallocate.
+        core::mem::forget(self);
+
+        boxed
+    }
+
+    pub fn as_mut_ptr(&self) -> *mut u8 {
+        self.ptr.as_ptr()
+    }
+
+    pub fn len(&self) -> usize {
+        self.len
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub fn as_bytes(&self) -> &[u8] {
+        unsafe { core::slice::from_raw_parts(self.ptr.as_ptr(), self.len) }
+    }
+
+    pub fn as_bytes_mut(&mut self) -> &mut [u8] {
+        unsafe { core::slice::from_raw_parts_mut(self.ptr.as_ptr(), self.len) }
+    }
+}
+
+impl Drop for ErasedBox {
+    fn drop(&mut self) {
+        unsafe { alloc::alloc::dealloc(self.ptr.as_ptr(), self.layout) }
+    }
+}
+
+// SAFETY: [ErasedBox] is `Send` because it can only be constructed from a
+// `Send` [AlignedBuffer].
+unsafe impl Send for ErasedBox {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[repr(C, align(4096))]
+    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+    struct Trivial([u8; 4096]);
+
+    impl AlignedBytes for Trivial {
+        fn as_bytes(&self) -> &[u8] {
+            &self.0
+        }
+
+        fn as_bytes_mut(&mut self) -> &mut [u8] {
+            &mut self.0
+        }
+
+        fn from_bytes(b: &[u8]) -> Self {
+            assert_eq!(b.len(), size_of::<Self>());
+            let mut a = [0; 4096];
+            a.copy_from_slice(b);
+            Self(a)
+        }
+    }
+
+    #[test]
+    fn roundtrip_preserves_value() {
+        let t = Trivial([32; 4096]);
+
+        let erased = ErasedBox::from_aligned(Box::new(t));
+        let reified = erased.into_aligned::<Trivial>();
+
+        assert_eq!(reified, Box::new(t));
+    }
+}

crates/runtime-io/src/error.rs

@@ -0,0 +1,43 @@
+/// An error `E`, along with auxiliary data `T`.
+///
+/// `T` is usually a buffer of type [AlignedBytes], whose ownership is
+/// transferred back to the caller when an error occurs.
+///
+/// As this type signifies an error condition, the contents of `T` are
+/// unspecified.
+///
+/// [AlignedBytes]: crate::io::buf::AlignedBytes
+#[derive(Debug)]
+pub struct ErrorWith<E, T> {
+    pub error: E,
+    pub with: T,
+}
+
+impl<E, T> ErrorWith<E, T> {
+    /// Map a type-changing function over `self.error`.
+    pub fn map_err<F>(self, f: impl FnOnce(E) -> F) -> ErrorWith<F, T> {
+        ErrorWith {
+            error: f(self.error),
+            with: self.with,
+        }
+    }
+
+    /// Map a type-changing function over `self.with`.
+    pub fn map_with<U>(self, f: impl FnOnce(T) -> U) -> ErrorWith<E, U> {
+        ErrorWith {
+            error: self.error,
+            with: f(self.with),
+        }
+    }
+
+    /// Extract `self.error`, discarding `self.with`.
+    pub fn into_err(self) -> E {
+        self.error
+    }
+
+    /// Convert from `&ErrorWith<E, T>` to `ErrorWith<&E, &T>`.
+    pub fn as_ref(&self) -> ErrorWith<&E, &T> {
+        let Self { ref error, ref with } = *self;
+        ErrorWith { error, with }
+    }
+}