microsandbox-rb 0.5.8 → 0.5.9

data/ext/microsandbox/src/ssh.rs

@@ -0,0 +1,317 @@
+//! SSH over a sandbox: `Microsandbox::Native::{SshClient, SftpClient, SshServer}`.
+//!
+//! Mirrors `sdk/python/src/ssh.rs`. The SSH ops are reached from the sandbox
+//! (`Sandbox::ssh_open_client` / `ssh_prepare_server` in `sandbox.rs`); this
+//! module holds the session wrappers. Each owns its core session behind an
+//! `Arc<tokio::Mutex<Option<…>>>` so it can be consumed exactly once on close.
+//!
+//! Discipline: the async work runs inside `block_on` (GVL released), so it must
+//! never touch the Ruby C API. Each method drives the future to a plain Rust
+//! `Result`, then maps it to a Ruby exception *after* `block_on` returns.
+
+use std::sync::Arc;
+
+use magnus::{method, prelude::*, Error, RHash, RModule, RString, Ruby};
+use microsandbox::sandbox::{
+    SftpClient as CoreSftp, SshClient as CoreSshClient, SshOutput, SshServer as CoreSshServer,
+    SshStdioStream,
+};
+use microsandbox::{MicrosandboxError, MicrosandboxResult};
+use tokio::io::AsyncWriteExt;
+use tokio::sync::Mutex;
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+/// A core error for a session whose value was already taken (closed). Built
+/// inside `block_on`, so it must be a plain Rust error, not a Ruby one.
+fn consumed() -> MicrosandboxError {
+    MicrosandboxError::Custom("SSH session is already closed".into())
+}
+
+//--------------------------------------------------------------------------------------------------
+// SshClient
+//--------------------------------------------------------------------------------------------------
+
+#[magnus::wrap(class = "Microsandbox::Native::SshClient", free_immediately, size)]
+pub struct SshClient {
+    inner: Arc<Mutex<Option<CoreSshClient>>>,
+}
+
+impl SshClient {
+    pub fn from_core(inner: CoreSshClient) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Some(inner))),
+        }
+    }
+
+    /// Run a command over SSH and collect {status, stdout, stderr}.
+    fn exec(&self, command: String, tty: bool) -> Result<RHash, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: MicrosandboxResult<SshOutput> = block_on(async move {
+            let guard = inner.lock().await;
+            let client = guard.as_ref().ok_or_else(consumed)?;
+            client.exec_with(command, |b| b.tty(tty)).await
+        });
+        Ok(ssh_output_to_hash(result.map_err(error::to_ruby)?))
+    }
+
+    /// Attach the local terminal to an interactive SSH shell; returns the exit
+    /// status. Host-TTY coupled (raw mode); not meaningful without a real tty.
+    fn attach(&self, term: Option<String>, detach_keys: Option<String>) -> Result<i32, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: MicrosandboxResult<i32> = block_on(async move {
+            let guard = inner.lock().await;
+            let client = guard.as_ref().ok_or_else(consumed)?;
+            client
+                .attach_with(|mut b| {
+                    if let Some(t) = term {
+                        b = b.term(t);
+                    }
+                    if let Some(k) = detach_keys {
+                        b = b.detach_keys(k);
+                    }
+                    b
+                })
+                .await
+        });
+        result.map_err(error::to_ruby)
+    }
+
+    /// Open an SFTP session over this SSH connection.
+    fn sftp(&self) -> Result<SftpClient, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: MicrosandboxResult<CoreSftp> = block_on(async move {
+            let guard = inner.lock().await;
+            let client = guard.as_ref().ok_or_else(consumed)?;
+            client.sftp().await
+        });
+        Ok(SftpClient::from_core(result.map_err(error::to_ruby)?))
+    }
+
+    /// Close the SSH client session. Idempotent.
+    fn close(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: MicrosandboxResult<()> = block_on(async move {
+            let client = {
+                let mut guard = inner.lock().await;
+                guard.take()
+            };
+            match client {
+                Some(c) => c.close().await,
+                None => Ok(()),
+            }
+        });
+        result.map_err(error::to_ruby)
+    }
+}
+
+fn ssh_output_to_hash(output: SshOutput) -> RHash {
+    let r = ruby();
+    let hash = r.hash_new();
+    let _ = hash.aset("status", output.status);
+    let _ = hash.aset("success", output.status == 0);
+    let _ = hash.aset("stdout", r.str_from_slice(output.stdout.as_ref()));
+    let _ = hash.aset("stderr", r.str_from_slice(output.stderr.as_ref()));
+    hash
+}
+
+//--------------------------------------------------------------------------------------------------
+// SftpClient
+//--------------------------------------------------------------------------------------------------
+
+#[magnus::wrap(class = "Microsandbox::Native::SftpClient", free_immediately, size)]
+pub struct SftpClient {
+    inner: Arc<Mutex<Option<CoreSftp>>>,
+}
+
+/// Format an SFTP-layer error as a plain string inside `block_on`; the Ruby
+/// exception is built from it afterward.
+fn sftp_str(e: impl std::fmt::Display) -> String {
+    format!("SFTP error: {e}")
+}
+
+impl SftpClient {
+    pub fn from_core(inner: CoreSftp) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Some(inner))),
+        }
+    }
+
+    fn read(&self, path: String) -> Result<RString, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<Vec<u8>, String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.read(path).await.map_err(sftp_str)
+        });
+        Ok(ruby().str_from_slice(&result.map_err(error::base_error)?))
+    }
+
+    fn write(&self, path: String, data: RString) -> Result<(), Error> {
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            let mut file = sftp.create(path).await.map_err(sftp_str)?;
+            file.write_all(&bytes).await.map_err(sftp_str)?;
+            file.shutdown().await.map_err(sftp_str)?;
+            Ok(())
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn mkdir(&self, path: String) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.create_dir(path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn remove_file(&self, path: String) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.remove_file(path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn remove_dir(&self, path: String) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.remove_dir(path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn rename(&self, old_path: String, new_path: String) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.rename(old_path, new_path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn symlink(&self, target: String, link_path: String) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.symlink(target, link_path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn real_path(&self, path: String) -> Result<String, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<String, String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.canonicalize(path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn read_link(&self, path: String) -> Result<String, Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<String, String> = block_on(async move {
+            let guard = inner.lock().await;
+            let sftp = guard.as_ref().ok_or_else(|| sftp_str("session closed"))?;
+            sftp.read_link(path).await.map_err(sftp_str)
+        });
+        result.map_err(error::base_error)
+    }
+
+    fn close(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: Result<(), String> = block_on(async move {
+            let sftp = {
+                let mut guard = inner.lock().await;
+                guard.take()
+            };
+            match sftp {
+                Some(s) => s.close().await.map_err(sftp_str),
+                None => Ok(()),
+            }
+        });
+        result.map_err(error::base_error)
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// SshServer
+//--------------------------------------------------------------------------------------------------
+
+#[magnus::wrap(class = "Microsandbox::Native::SshServer", free_immediately, size)]
+pub struct SshServer {
+    inner: Arc<Mutex<Option<CoreSshServer>>>,
+}
+
+impl SshServer {
+    pub fn from_core(inner: CoreSshServer) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Some(inner))),
+        }
+    }
+
+    /// Serve one SSH connection over this process's stdin/stdout.
+    fn serve_connection(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        let result: MicrosandboxResult<()> = block_on(async move {
+            let server = {
+                let guard = inner.lock().await;
+                guard.as_ref().cloned()
+            };
+            match server {
+                Some(s) => s.serve_connection(SshStdioStream::new()).await,
+                None => Err(consumed()),
+            }
+        });
+        result.map_err(error::to_ruby)
+    }
+
+    /// Release the prepared server endpoint. Idempotent.
+    fn close(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        block_on(async move {
+            inner.lock().await.take();
+        });
+        Ok(())
+    }
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let client = native.define_class("SshClient", ruby.class_object())?;
+    client.define_method("exec", method!(SshClient::exec, 2))?;
+    client.define_method("attach", method!(SshClient::attach, 2))?;
+    client.define_method("sftp", method!(SshClient::sftp, 0))?;
+    client.define_method("close", method!(SshClient::close, 0))?;
+
+    let sftp = native.define_class("SftpClient", ruby.class_object())?;
+    sftp.define_method("read", method!(SftpClient::read, 1))?;
+    sftp.define_method("write", method!(SftpClient::write, 2))?;
+    sftp.define_method("mkdir", method!(SftpClient::mkdir, 1))?;
+    sftp.define_method("remove_file", method!(SftpClient::remove_file, 1))?;
+    sftp.define_method("remove_dir", method!(SftpClient::remove_dir, 1))?;
+    sftp.define_method("rename", method!(SftpClient::rename, 2))?;
+    sftp.define_method("symlink", method!(SftpClient::symlink, 2))?;
+    sftp.define_method("real_path", method!(SftpClient::real_path, 1))?;
+    sftp.define_method("read_link", method!(SftpClient::read_link, 1))?;
+    sftp.define_method("close", method!(SftpClient::close, 0))?;
+
+    let server = native.define_class("SshServer", ruby.class_object())?;
+    server.define_method("serve_connection", method!(SshServer::serve_connection, 0))?;
+    server.define_method("close", method!(SshServer::close, 0))?;
+
+    Ok(())
+}

data/lib/microsandbox/agent.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A single raw agent-protocol frame: a correlation id, flag bits, and a
+  # CBOR-encoded body. Decode {#body} with a CBOR library of your choice.
+  class AgentFrame
+    # @return [Integer] correlation id from the frame header
+    attr_reader :id
+    # @return [Integer] flag bits (see {AgentClient::FLAG_TERMINAL} etc.)
+    attr_reader :flags
+    # @return [String] raw CBOR body bytes (ASCII-8BIT)
+    attr_reader :body
+
+    def initialize(data)
+      @id = data["id"]
+      @flags = data["flags"]
+      @body = data["body"]
+    end
+
+    # @return [Boolean] last frame of a stream
+    def terminal? = (@flags & AgentClient::FLAG_TERMINAL) != 0
+
+    # @return [Boolean] opens a new session
+    def session_start? = (@flags & AgentClient::FLAG_SESSION_START) != 0
+
+    # @return [Boolean] connection-shutdown signal
+    def shutdown? = (@flags & AgentClient::FLAG_SHUTDOWN) != 0
+
+    def inspect
+      "#<Microsandbox::AgentFrame id=#{@id} flags=0x#{@flags.to_s(16)} body=#{@body&.bytesize}B>"
+    end
+  end
+
+  # An open raw agent stream, from {AgentClient#stream}. {Enumerable}: iterate to
+  # consume {AgentFrame}s until the stream ends (the terminal frame is delivered,
+  # then iteration stops). Mirrors the official SDKs' `AgentStream`.
+  #
+  # @example
+  #   stream = client.stream(0, request_body)
+  #   stream.each { |frame| handle(frame) }
+  class AgentStream
+    include Enumerable
+
+    # @return [Integer] the protocol correlation id (pass to {AgentClient#send_frame})
+    attr_reader :id
+
+    def initialize(native, id, handle)
+      @native = native
+      @id = id
+      @handle = handle
+    end
+
+    # Pull the next frame, or nil at end-of-stream.
+    # @return [AgentFrame, nil]
+    def recv
+      frame = @native.stream_next(@handle)
+      frame && AgentFrame.new(frame)
+    end
+
+    # @yieldparam frame [AgentFrame]
+    # @return [self, Enumerator]
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (frame = recv)
+        yield frame
+      end
+      self
+    end
+
+    # Close the stream and release its handle. Idempotent.
+    # @return [nil]
+    def close
+      @native.stream_close(@handle)
+      nil
+    end
+  end
+
+  # A low-level **raw agent client** — the byte-level transport to a sandbox's
+  # `agentd` over its relay socket. This is the rawest tier of the SDK: it moves
+  # CBOR-encoded protocol frames in and out; encoding/decoding the bodies is up
+  # to you. Most users want {Sandbox#exec}/{Sandbox#fs} instead; reach for this
+  # to drive `agentd` protocol features the high-level API does not expose, or to
+  # bridge the relay socket to another transport (see {socket_path}).
+  #
+  # Mirrors the `AgentClient` in the official Python/Node/Go SDKs.
+  #
+  # @example one-shot request/response
+  #   Microsandbox::AgentClient.connect_sandbox("my-box") do |client|
+  #     frame = client.request(0, cbor_encoded_request)
+  #     handle(frame.body)
+  #   end
+  class AgentClient
+    # Frame flag bits (mirror the protocol constants in the other SDKs).
+    FLAG_TERMINAL = 0b0000_0001
+    FLAG_SESSION_START = 0b0000_0010
+    FLAG_SHUTDOWN = 0b0000_0100
+
+    class << self
+      # Connect to a running sandbox by name (max 128 UTF-8 bytes). With a block,
+      # the client is yielded and closed when the block returns.
+      # @param name [String]
+      # @param timeout [Numeric, nil] handshake timeout in seconds (default ~10s)
+      # @yieldparam client [AgentClient]
+      # @return [AgentClient, Object]
+      def connect_sandbox(name, timeout: nil, &block)
+        wrap(Native::AgentClient.connect_sandbox(name.to_s, timeout && Float(timeout)), &block)
+      end
+
+      # Connect to an agentd relay socket by path. See {connect_sandbox}.
+      # @return [AgentClient, Object]
+      def connect_path(path, timeout: nil, &block)
+        wrap(Native::AgentClient.connect_path(path.to_s, timeout && Float(timeout)), &block)
+      end
+
+      # Resolve a sandbox's agent relay socket path **without** connecting — the
+      # same path {connect_sandbox} would dial. Useful for bridging the socket to
+      # another byte transport. The sandbox need not be running.
+      # @return [String]
+      def socket_path(name)
+        Native::AgentClient.socket_path(name.to_s)
+      end
+
+      private
+
+      def wrap(native, &block)
+        client = new(native)
+        return client unless block
+
+        begin
+          block.call(client)
+        ensure
+          client.close
+        end
+      end
+    end
+
+    def initialize(native)
+      @native = native
+    end
+
+    # Send one frame and await a single response frame.
+    # @param flags [Integer] frame flag bits
+    # @param body [String] CBOR-encoded body bytes
+    # @return [AgentFrame]
+    def request(flags, body)
+      AgentFrame.new(@native.request(Integer(flags), body.to_s))
+    end
+
+    # Open a streaming session.
+    # @param flags [Integer]
+    # @param body [String]
+    # @return [AgentStream]
+    def stream(flags, body)
+      opened = @native.stream_open(Integer(flags), body.to_s)
+      AgentStream.new(@native, opened["id"], opened["handle"])
+    end
+
+    # Send a follow-up frame on an existing correlation id (e.g. a stream's
+    # {AgentStream#id}). Named +send_frame+ rather than +send+ so it does not
+    # shadow Ruby's `Object#send`. Maps to the protocol "send" in the other SDKs.
+    # @return [nil]
+    def send_frame(id, flags, body)
+      @native.send(Integer(id), Integer(flags), body.to_s)
+      nil
+    end
+
+    # The cached handshake `core.ready` frame body (CBOR bytes).
+    # @return [String]
+    def ready_bytes
+      @native.ready_bytes
+    end
+
+    # Close the connection. Idempotent.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
+  end
+end