kobako 0.28.0 → 0.29.0

data/ext/kobako/src/runtime/filesystem.rs

@@ -0,0 +1,236 @@
+//! The Ruby face of the Filesystem: `Kobako::Filesystem::Memory`,
+//! `Temporary`, `Directory`, and `Overlay`, each standing for the
+//! `kobako_runtime` Filesystem of that kind.
+//!
+//! A kind kobako ships runs in Rust; Ruby only picks it and the access.
+//! Ruby is asked again while the guest runs through a mount's block, at
+//! most once per open or change, and through a Filesystem written in
+//! Ruby, once per call.
+
+mod grants;
+mod ruby;
+
+use std::sync::Arc;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{
+    function, gc, method, prelude::*, scan_args::get_kwargs, scan_args::scan_args,
+    DataTypeFunctions, Error as MagnusError, RHash, RModule, RString, Ruby, Symbol, TypedData,
+    Value,
+};
+
+use ruby::RubyFilesystem;
+
+use kobako_runtime::filesystem::{
+    Access, Blocking, Directory, Filesystem, Memory, Overlay, Temporary,
+};
+
+pub(super) use grants::{to_grants, validate_mount};
+
+macro_rules! filesystem_class {
+    ($name:ident, $class:literal) => {
+        #[magnus::wrap(class = $class, free_immediately, size)]
+        pub(super) struct $name(Arc<dyn Filesystem>);
+    };
+}
+
+filesystem_class!(MemoryFs, "Kobako::Filesystem::Memory");
+filesystem_class!(TemporaryFs, "Kobako::Filesystem::Temporary");
+filesystem_class!(DirectoryFs, "Kobako::Filesystem::Directory");
+
+/// The Overlay itself rather than a shared handle, so `layer` can answer a
+/// new one and leave this one as it was. It marks the Ruby object of
+/// every Layer, since a Filesystem written in Ruby has nothing else
+/// keeping it alive.
+#[derive(magnus::TypedData)]
+#[magnus(class = "Kobako::Filesystem::Overlay", free_immediately, size, mark)]
+pub(super) struct OverlayFs {
+    overlay: Overlay,
+    layers: Vec<Opaque<Value>>,
+}
+
+impl DataTypeFunctions for OverlayFs {
+    fn mark(&self, marker: &gc::Marker) {
+        marker.mark_slice(&self.layers);
+    }
+}
+
+pub(super) fn register(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
+    let module = kobako.define_module("Filesystem")?;
+    let memory = module.define_class("Memory", ruby.class_object())?;
+    memory.define_singleton_method("new", function!(memory_new, -1))?;
+    let temporary = module.define_class("Temporary", ruby.class_object())?;
+    temporary.define_singleton_method("new", function!(temporary_new, -1))?;
+    let directory = module.define_class("Directory", ruby.class_object())?;
+    directory.define_singleton_method("new", function!(directory_new, 1))?;
+    let overlay = module.define_class("Overlay", ruby.class_object())?;
+    overlay.define_singleton_method("new", function!(overlay_new, 0))?;
+    overlay.define_method("layer", method!(overlay_layer, -1))?;
+    MemoryFs::class(ruby);
+    TemporaryFs::class(ruby);
+    DirectoryFs::class(ruby);
+    OverlayFs::class(ruby);
+    Ok(())
+}
+
+/// `Memory.new(files = {}, limit: 64 MiB, inodes:)`: each
+/// `path => contents` pair becomes a file, its directories created along
+/// the way. Ruby hands a bare `"path" => contents` over as keywords, so
+/// every String keyword is a file too. Without `inodes:` the entries
+/// follow the limit.
+fn memory_new(args: &[Value]) -> Result<MemoryFs, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let args = scan_args::<(), (Option<RHash>,), (), (), RHash, ()>(args)?;
+    let mut files = Vec::new();
+    let mut limit = Some(Memory::DEFAULT_LIMIT);
+    let mut inodes = None;
+    let limit_key = ruby.to_symbol("limit");
+    let inodes_key = ruby.to_symbol("inodes");
+    for hash in args.optional.0.into_iter().chain([args.keywords]) {
+        hash.foreach(|key: Value, value: Value| {
+            match Symbol::from_value(key) {
+                Some(key) if key.equal(limit_key)? => limit = to_limit(value)?,
+                Some(key) if key.equal(inodes_key)? => inodes = Some(to_limit(value)?),
+                Some(key) => {
+                    return Err(MagnusError::new(
+                        ruby.exception_arg_error(),
+                        format!("unknown keyword: :{}", key.name()?),
+                    ))
+                }
+                None => files.push((
+                    String::try_convert(key)?,
+                    super::rstring_to_vec(RString::try_convert(value)?),
+                )),
+            }
+            Ok(magnus::r_hash::ForEach::Continue)
+        })?;
+    }
+    // A list no Memory holds is an `ArgumentError` the Host App can rescue.
+    let memory = Memory::try_from_iter(files)
+        .map_err(|error| MagnusError::new(ruby.exception_arg_error(), error.to_string()))?
+        .with_limit(limit);
+    Ok(MemoryFs(Arc::new(match inodes {
+        Some(inodes) => memory.with_inodes(inodes),
+        None => memory,
+    })))
+}
+
+/// `Temporary.new(limit: 64 MiB, inodes:)`.
+fn temporary_new(args: &[Value]) -> Result<TemporaryFs, MagnusError> {
+    let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+    let kwargs = get_kwargs::<_, (), (Option<Value>, Option<Value>), ()>(
+        args.keywords,
+        &[],
+        &["limit", "inodes"],
+    )?;
+    let (limit, inodes) = kwargs.optional;
+    let limit = match limit {
+        Some(limit) => to_limit(limit)?,
+        None => Some(Memory::DEFAULT_LIMIT),
+    };
+    let temporary = Temporary::new().with_limit(limit);
+    Ok(TemporaryFs(Arc::new(match inodes {
+        Some(inodes) => temporary.with_inodes(to_limit(inodes)?),
+        None => temporary,
+    })))
+}
+
+/// A `limit:` or `inodes:` count, or `nil` for none.
+fn to_limit(limit: Value) -> Result<Option<usize>, MagnusError> {
+    Option::<usize>::try_convert(limit)
+}
+
+fn directory_new(path: String) -> Result<DirectoryFs, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    Directory::new(&path)
+        .map(|directory| DirectoryFs(Arc::new(directory)))
+        .map_err(|err| {
+            MagnusError::new(
+                ruby.exception_arg_error(),
+                format!("cannot open host directory {path}: {err}"),
+            )
+        })
+}
+
+/// `Overlay.new`, with no Layer yet.
+fn overlay_new() -> OverlayFs {
+    OverlayFs {
+        overlay: Overlay::new().with_blocking(Arc::new(GvlFreeWait)),
+        layers: Vec::new(),
+    }
+}
+
+/// An Overlay's thread waits for its lock without the GVL, so a holder
+/// asking a Layer written in Ruby can take the GVL and finish.
+struct GvlFreeWait;
+
+impl Blocking for GvlFreeWait {
+    fn wait(&self, wait: &mut dyn FnMut()) {
+        super::gvl::region(super::gvl::holds(), wait);
+    }
+}
+
+/// `layer(filesystem, access: :read)`, a new Overlay with `filesystem`
+/// beneath this one's Layers.
+fn overlay_layer(overlay: &OverlayFs, args: &[Value]) -> Result<OverlayFs, MagnusError> {
+    let args = scan_args::<(Value,), (), (), (), RHash, ()>(args)?;
+    let kwargs = get_kwargs::<_, (), (Option<Value>,), ()>(args.keywords, &[], &["access"])?;
+    let (filesystem,) = args.required;
+    let access = match kwargs.optional.0 {
+        Some(access) => to_access(access)?,
+        None => Access::Read,
+    };
+    let mut layers = overlay.layers.clone();
+    layers.push(Opaque::from(filesystem));
+    Ok(OverlayFs {
+        overlay: overlay
+            .overlay
+            .clone()
+            .layer(to_filesystem(filesystem)?, access),
+        layers,
+    })
+}
+
+fn to_access(access: Value) -> Result<Access, MagnusError> {
+    let name = Symbol::from_value(access)
+        .map(|symbol| symbol.name())
+        .transpose()?;
+    match name.as_deref() {
+        Some("read") => Ok(Access::Read),
+        Some("read_write") => Ok(Access::ReadWrite),
+        _ => Err(MagnusError::new(
+            Ruby::get().expect("Ruby thread").exception_arg_error(),
+            format!(
+                "access must be :read or :read_write, got {}",
+                access.inspect()
+            ),
+        )),
+    }
+}
+
+/// The Filesystem a Ruby handle of any kobako kind stands for.
+fn to_filesystem(value: Value) -> Result<Arc<dyn Filesystem>, MagnusError> {
+    if let Ok(fs) = <&MemoryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&TemporaryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&DirectoryFs>::try_convert(value) {
+        return Ok(fs.0.clone());
+    }
+    if let Ok(fs) = <&OverlayFs>::try_convert(value) {
+        return Ok(Arc::new(fs.overlay.clone()));
+    }
+    if let Some(fs) = RubyFilesystem::from_value(value) {
+        return Ok(Arc::new(fs));
+    }
+    let ruby = Ruby::get().expect("Ruby thread");
+    Err(MagnusError::new(
+        ruby.exception_type_error(),
+        format!(
+            "expected a Kobako::Filesystem or an object answering open and stat, got {}",
+            value.class()
+        ),
+    ))
+}

data/ext/kobako/src/runtime/gvl.rs

@@ -1,4 +1,4 @@
-//! Releasing Ruby's GVL for the guest-execution span so distinct Sandboxes on
+//! Releasing Ruby's GVL for an invocation's guest span so distinct Sandboxes on
 //! distinct Threads run their guest code in parallel.
 //!
 //! `region` brackets one invocation's guest span, releasing the GVL when the
@@ -35,6 +35,12 @@ where
     })
 }
 
+/// Whether this thread holds the GVL: outside any released region, or
+/// inside a dispatch that re-acquired it.
+pub(crate) fn holds() -> bool {
+    !GVL_RELEASED.with(|g| g.get())
+}
+
 /// Runs inline when the GVL is already held — hold mode, or a nested
 /// dispatch whose outer frame re-acquired it.
 pub(crate) fn reenter<F, R>(f: F) -> R

data/ext/kobako/src/runtime/pinned_value.rs

@@ -0,0 +1,31 @@
+//! A Ruby object Rust holds across calls into the guest, registered with
+//! Ruby's collector so it is neither freed nor moved by compaction while
+//! the holder lives.
+
+use magnus::value::Opaque;
+use magnus::{Ruby, Value};
+
+use super::gvl;
+
+pub(crate) struct PinnedValue(Box<Opaque<Value>>);
+
+impl PinnedValue {
+    pub(crate) fn new(ruby: &Ruby, value: Value) -> Self {
+        let value = Box::new(Opaque::from(value));
+        ruby.gc_register_address(&*value);
+        Self(value)
+    }
+
+    pub(crate) fn get(&self) -> Opaque<Value> {
+        *self.0
+    }
+}
+
+impl Drop for PinnedValue {
+    fn drop(&mut self) {
+        gvl::reenter(|| {
+            let ruby = Ruby::get().expect("Ruby handle unavailable releasing a pinned object");
+            ruby.gc_unregister_address(&*self.0);
+        });
+    }
+}

data/ext/kobako/src/runtime/snapshot.rs

@@ -0,0 +1,127 @@
+//! `Kobako::Snapshot`: one invocation's result at the Ruby boundary.
+
+use magnus::{
+    method, prelude::*, typed_data::DataTypeFunctions, Error as MagnusError, Exception, RModule,
+    RString, Ruby, TypedData,
+};
+
+use kobako_runtime::snapshot::{Completion, Snapshot as RuntimeSnapshot};
+use kobako_transport::envelope::Outcome;
+
+use super::errors;
+
+/// A Panic's fields as they cross to Ruby: origin, class, message,
+/// backtrace, and the names the invocation could have used in place of the
+/// one it named. Named so the Ruby side reads them positionally against one
+/// shape, matching the `Kobako::Outcome::panic_fields` alias.
+type PanicFields = (String, String, String, Vec<String>, Vec<String>);
+
+pub(super) fn register(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
+    let snapshot = kobako.define_class("Snapshot", ruby.class_object())?;
+    snapshot.define_method("outcome", method!(Snapshot::outcome, 0))?;
+    snapshot.define_method("trap_error", method!(Snapshot::trap_error, 0))?;
+    snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
+    snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
+    snapshot.define_method("stdout", method!(Snapshot::stdout, 0))?;
+    snapshot.define_method("stdout_truncated?", method!(Snapshot::stdout_truncated, 0))?;
+    snapshot.define_method("stderr", method!(Snapshot::stderr, 0))?;
+    snapshot.define_method("stderr_truncated?", method!(Snapshot::stderr_truncated, 0))?;
+    Ok(())
+}
+
+/// One invocation's result at the Ruby boundary — the whole `Snapshot` the
+/// driver produced, exposed as `Kobako::Snapshot`. Usage and the
+/// two output captures are present on every outcome, so the trap path
+/// carries them just like the value path; the completion is read as either
+/// the Outcome (`#outcome`) or a trap (`#trap_error`). The verb names the
+/// invocation, so an unsupported one says which operation is lacking.
+#[derive(TypedData)]
+#[magnus(class = "Kobako::Snapshot", free_immediately, size)]
+pub(super) struct Snapshot(RuntimeSnapshot, &'static str);
+
+impl DataTypeFunctions for Snapshot {}
+
+impl Snapshot {
+    pub(super) fn new(snapshot: RuntimeSnapshot, verb: &'static str) -> Self {
+        Self(snapshot, verb)
+    }
+
+    /// Already split off the core envelope, so the Ruby side maps a failure
+    /// onto its error taxonomy without decoding a payload byte: the ok
+    /// arm's payload, or a Panic's fields beside an empty payload. A trap
+    /// has no Outcome; `#trap_error` is the discriminator there.
+    fn outcome(&self) -> Result<(RString, Option<PanicFields>), MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        match &self.0.completion {
+            Completion::Outcome(Outcome::Ok(value)) => Ok((ruby.str_from_slice(value), None)),
+            Completion::Outcome(Outcome::Panic(panic)) => Ok((
+                ruby.str_from_slice(&[]),
+                Some((
+                    panic.origin.name().to_owned(),
+                    panic.error.name.clone(),
+                    panic.error.message.clone(),
+                    panic.error.backtrace.clone(),
+                    panic.available.clone(),
+                )),
+            )),
+            // The Guest Binary answered rather than broke, so it reads as
+            // the Sandbox's failure, worded by the host.
+            Completion::Outcome(Outcome::Unsupported(_)) => Ok((
+                ruby.str_from_slice(&[]),
+                Some((
+                    "sandbox".to_owned(),
+                    "Kobako::SandboxError".to_owned(),
+                    format!(
+                        "the Sandbox runtime does not support #{}; \
+                         rebuild it against the kobako version in use",
+                        self.1
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                )),
+            )),
+            Completion::Trap(_) => Err(MagnusError::new(
+                ruby.exception_runtime_error(),
+                "a trapped run has no outcome",
+            )),
+        }
+    }
+
+    /// Unraised, so the Sandbox layer can attach the run's Execution before
+    /// raising it.
+    fn trap_error(&self) -> Result<Option<Exception>, MagnusError> {
+        let Completion::Trap(trap) = &self.0.completion else {
+            return Ok(None);
+        };
+        let ruby = Ruby::get().expect("Ruby thread");
+        errors::trap_class(&ruby, trap)
+            .new_instance((trap.to_string(),))
+            .map(Some)
+    }
+
+    fn wall_time(&self) -> f64 {
+        self.0.usage.wall_time
+    }
+
+    fn memory_peak(&self) -> usize {
+        self.0.usage.memory_peak
+    }
+
+    fn stdout(&self) -> RString {
+        let ruby = Ruby::get().expect("Ruby thread");
+        ruby.str_from_slice(&self.0.stdout.bytes)
+    }
+
+    fn stdout_truncated(&self) -> bool {
+        self.0.stdout.truncated
+    }
+
+    fn stderr(&self) -> RString {
+        let ruby = Ruby::get().expect("Ruby thread");
+        ruby.str_from_slice(&self.0.stderr.bytes)
+    }
+
+    fn stderr_truncated(&self) -> bool {
+        self.0.stderr.truncated
+    }
+}