microsandbox-rb 0.5.8 → 0.5.9

data/lib/microsandbox/ssh.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # The result of an {SshClient#exec} call. Like {ExecOutput}, `stdout`/`stderr`
+  # are the captured bytes decoded as UTF-8 (lenient); use `stdout_bytes`/
+  # `stderr_bytes` for the raw ASCII-8BIT bytes.
+  class SshOutput
+    # @return [Integer] the remote command's exit status
+    attr_reader :status
+    # @return [String] raw stdout bytes (ASCII-8BIT)
+    attr_reader :stdout_bytes
+    # @return [String] raw stderr bytes (ASCII-8BIT)
+    attr_reader :stderr_bytes
+
+    def initialize(data)
+      @status = data["status"]
+      @success = data["success"]
+      @stdout_bytes = data["stdout"]
+      @stderr_bytes = data["stderr"]
+    end
+
+    # @return [Boolean] whether the command exited with status 0
+    def success? = @success
+
+    # @return [Boolean] whether the command exited non-zero
+    def failure? = !@success
+
+    # @return [String] stdout decoded as UTF-8
+    def stdout
+      @stdout ||= @stdout_bytes.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # @return [String] stderr decoded as UTF-8
+    def stderr
+      @stderr ||= @stderr_bytes.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def to_s = stdout
+
+    def inspect
+      "#<Microsandbox::SshOutput status=#{@status} success=#{@success} " \
+        "stdout=#{stdout.bytesize}B stderr=#{stderr.bytesize}B>"
+    end
+  end
+
+  # A high-level SFTP session over an {SshClient}, from {SshClient#sftp}. All
+  # paths are guest paths. Mirrors the `SftpClient` of the official SDKs.
+  class SftpClient
+    def initialize(native)
+      @native = native
+    end
+
+    # Read a file's full contents.
+    # @return [String] raw bytes (ASCII-8BIT)
+    def read(path)
+      @native.read(path.to_s)
+    end
+
+    # Read a file and decode it as UTF-8 (lenient).
+    # @return [String]
+    def read_text(path)
+      read(path).force_encoding(Encoding::UTF_8)
+    end
+
+    # Write a file, creating or truncating it.
+    # @return [nil]
+    def write(path, data)
+      @native.write(path.to_s, data.to_s)
+      nil
+    end
+
+    # Create a directory.
+    # @return [nil]
+    def mkdir(path)
+      @native.mkdir(path.to_s)
+      nil
+    end
+
+    # Remove a file.
+    # @return [nil]
+    def remove_file(path)
+      @native.remove_file(path.to_s)
+      nil
+    end
+
+    # Remove an empty directory.
+    # @return [nil]
+    def remove_dir(path)
+      @native.remove_dir(path.to_s)
+      nil
+    end
+
+    # Rename (move) a file or directory.
+    # @return [nil]
+    def rename(old_path, new_path)
+      @native.rename(old_path.to_s, new_path.to_s)
+      nil
+    end
+
+    # Create a symlink at +link_path+ pointing to +target+.
+    # @return [nil]
+    def symlink(target, link_path)
+      @native.symlink(target.to_s, link_path.to_s)
+      nil
+    end
+
+    # Resolve a path to its canonical absolute form.
+    # @return [String]
+    def real_path(path)
+      @native.real_path(path.to_s)
+    end
+
+    # Read a symlink's target.
+    # @return [String]
+    def read_link(path)
+      @native.read_link(path.to_s)
+    end
+
+    # Close the SFTP session. Idempotent.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
+  end
+
+  # A native, in-process SSH client session to a sandbox, from
+  # {SshOps#open_client}. Mirrors the `SshClient` of the official SDKs.
+  #
+  # @example
+  #   sb.ssh.open_client do |client|
+  #     out = client.exec("uname -a")
+  #     puts out.stdout
+  #   end
+  class SshClient
+    def initialize(native)
+      @native = native
+    end
+
+    # Run a command over SSH and collect its output.
+    # @param command [String] the command line (interpreted by the remote shell)
+    # @param tty [Boolean] allocate a pseudo-terminal
+    # @return [SshOutput]
+    def exec(command, tty: false)
+      SshOutput.new(@native.exec(command.to_s, tty ? true : false))
+    end
+
+    # Attach the local terminal to an interactive SSH shell. Host-TTY coupled
+    # (puts the terminal in raw mode and forwards SIGWINCH); blocks until the
+    # remote shell exits or the detach sequence is typed.
+    # @param term [String, nil] TERM value to request (defaults to $TERM)
+    # @param detach_keys [String, nil] detach key sequence (e.g. "ctrl-p,ctrl-q")
+    # @return [Integer] the remote shell's exit status
+    def attach(term: nil, detach_keys: nil)
+      @native.attach(term&.to_s, detach_keys&.to_s)
+    end
+
+    # Open an SFTP session over this connection. With a block, the session is
+    # yielded and closed when the block returns.
+    # @yieldparam sftp [SftpClient]
+    # @return [SftpClient, Object]
+    def sftp
+      session = SftpClient.new(@native.sftp)
+      return session unless block_given?
+
+      begin
+        yield session
+      ensure
+        session.close
+      end
+    end
+
+    # Close the SSH client session. Idempotent.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
+  end
+
+  # A reusable SSH server endpoint for a sandbox, from {SshOps#prepare_server}.
+  # Each {#serve_connection} serves a single SSH transport over this process's
+  # stdin/stdout — typically wired up by a parent SSH daemon via `ForceCommand`
+  # or an inetd-style spawn. Mirrors the `SshServer` of the official SDKs.
+  class SshServer
+    def initialize(native)
+      @native = native
+    end
+
+    # Serve one SSH connection over this process's stdin/stdout. Blocks until
+    # the session ends.
+    # @return [nil]
+    def serve_connection
+      @native.serve_connection
+      nil
+    end
+
+    # Release the prepared server endpoint. Idempotent.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
+  end
+
+  # The SSH namespace for a sandbox, returned by {Sandbox#ssh}. Use it to open a
+  # native in-process SSH client or prepare a reusable server endpoint.
+  class SshOps
+    def initialize(native)
+      @native = native
+    end
+
+    # Open a native in-process SSH client to the sandbox. With a block, the
+    # client is yielded and closed when the block returns.
+    # @param user [String] guest user to authenticate as (default "root")
+    # @param term [String, nil] TERM value for the session
+    # @param sftp [Boolean] enable the SFTP subsystem (default true)
+    # @yieldparam client [SshClient]
+    # @return [SshClient, Object]
+    def open_client(user: "root", term: nil, sftp: true)
+      opts = { "user" => user.to_s, "sftp" => sftp ? true : false }
+      opts["term"] = term.to_s if term
+      client = SshClient.new(@native.ssh_open_client(opts))
+      return client unless block_given?
+
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    # Prepare a reusable SSH server endpoint for the sandbox.
+    # @param host_key_path [String, nil] PEM host key path (generated if omitted)
+    # @param authorized_keys_path [String, nil] authorized_keys file path
+    # @param user [String, nil] guest user connections run as
+    # @param sftp [Boolean] enable the SFTP subsystem (default true)
+    # @return [SshServer]
+    def prepare_server(host_key_path: nil, authorized_keys_path: nil, user: nil, sftp: true)
+      opts = { "sftp" => sftp ? true : false }
+      opts["host_key_path"] = host_key_path.to_s if host_key_path
+      opts["authorized_keys_path"] = authorized_keys_path.to_s if authorized_keys_path
+      opts["user"] = user.to_s if user
+      SshServer.new(@native.ssh_prepare_server(opts))
+    end
+  end
+end

data/lib/microsandbox/version.rb

@@ -5,5 +5,5 @@ module Microsandbox
   # the pinned core-crate tag); the patch segment advances for gem-only revisions
   # that add bindings atop the same core. Must equal the native ext's Cargo crate
   # version (`Native.version`), enforced by spec/unit/version_spec.rb.
-  VERSION = "0.5.8"
+  VERSION = "0.5.9"
 end

data/lib/microsandbox.rb

@@ -22,6 +22,10 @@ require_relative "microsandbox/streams"
 require_relative "microsandbox/image"
 require_relative "microsandbox/volume"
 require_relative "microsandbox/snapshot"
+require_relative "microsandbox/patch"
+require_relative "microsandbox/network"
+require_relative "microsandbox/agent"
+require_relative "microsandbox/ssh"
 require_relative "microsandbox/sandbox"
 
 # Microsandbox — lightweight microVM sandboxes for Ruby.

data/sig/microsandbox.rbs

@@ -140,7 +140,8 @@ module Microsandbox
                       ?user: String?, ?hostname: String?, ?labels: Hash[untyped, untyped]?,
                       ?scripts: Hash[untyped, untyped]?, ?entrypoint: Array[String]?,
                       ?ports: Hash[untyped, untyped]?, ?ports_udp: Hash[untyped, untyped]?,
-                      ?volumes: Hash[untyped, untyped]?, ?network: untyped?, ?from_snapshot: String?,
+                      ?volumes: Hash[untyped, untyped]?, ?network: untyped?,
+                      ?patches: Array[Hash[untyped, untyped]]?, ?from_snapshot: String?,
                       ?log_level: (String | Symbol)?, ?quiet_logs: bool, ?security: (String | Symbol)?,
                       ?oci_upper_size: Integer?, ?max_duration: Integer?, ?idle_timeout: Integer?,
                       ?rlimits: Hash[untyped, untyped]?, ?pull_policy: (String | Symbol)?,
@@ -166,7 +167,12 @@ module Microsandbox
                       ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
     def shell_stream: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
                        ?timeout: Numeric?, ?tty: bool, ?stdin: String?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
+    def attach: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
+                 ?env: Hash[untyped, untyped]?, ?detach_keys: String?,
+                 ?rlimits: Hash[untyped, untyped]?) -> Integer
+    def attach_shell: () -> Integer
     def fs: () -> FS
+    def ssh: () -> SshOps
     def metrics: () -> Metrics
     def logs: (?tail: Integer?, ?since_ms: Numeric?, ?until_ms: Numeric?,
                ?sources: Array[String | Symbol]?) -> Array[LogEntry]
@@ -321,4 +327,130 @@ module Microsandbox
                       ?with_image: bool, ?plain_tar: bool) -> nil
     def self.import: (String archive_path, ?dest: String?) -> SnapshotInfo
   end
+
+  module Patch
+    def self.text: (String path, String content, ?mode: Integer?, ?replace: bool) -> Hash[String, untyped]
+    def self.file: (String path, String content, ?mode: Integer?, ?replace: bool) -> Hash[String, untyped]
+    def self.append: (String path, String content) -> Hash[String, untyped]
+    def self.copy_file: (String src, String dst, ?mode: Integer?, ?replace: bool) -> Hash[String, untyped]
+    def self.copy_dir: (String src, String dst, ?replace: bool) -> Hash[String, untyped]
+    def self.symlink: (String target, String link, ?replace: bool) -> Hash[String, untyped]
+    def self.mkdir: (String path, ?mode: Integer?) -> Hash[String, untyped]
+    def self.remove: (String path) -> Hash[String, untyped]
+  end
+
+  module Destination
+    def self.any: () -> Hash[String, String]
+    def self.ip: (String value) -> Hash[String, String]
+    def self.cidr: (String value) -> Hash[String, String]
+    def self.domain: (String value) -> Hash[String, String]
+    def self.domain_suffix: (String value) -> Hash[String, String]
+    def self.group: ((String | Symbol) value) -> Hash[String, String]
+  end
+
+  module Rule
+    def self.allow: (?destination: untyped?, ?direction: (String | Symbol),
+                     ?protocol: (String | Symbol)?, ?protocols: Array[String | Symbol]?,
+                     ?port: (String | Integer)?, ?ports: Array[String | Integer]?) -> Hash[String, untyped]
+    def self.deny: (?destination: untyped?, ?direction: (String | Symbol),
+                    ?protocol: (String | Symbol)?, ?protocols: Array[String | Symbol]?,
+                    ?port: (String | Integer)?, ?ports: Array[String | Integer]?) -> Hash[String, untyped]
+  end
+
+  class NetworkPolicy
+    PRESET_ALIASES: Hash[String, String]
+    def self.public_only: () -> NetworkPolicy
+    def self.none: () -> NetworkPolicy
+    def self.allow_all: () -> NetworkPolicy
+    def self.non_local: () -> NetworkPolicy
+    def self.preset: ((String | Symbol) name) -> NetworkPolicy
+    def self.custom: (?default_egress: (String | Symbol)?, ?default_ingress: (String | Symbol)?,
+                      ?rules: Array[Hash[untyped, untyped]], ?deny_domains: Array[String],
+                      ?deny_domain_suffixes: Array[String]) -> NetworkPolicy
+    def self.coerce: (untyped network) -> Hash[String, untyped]
+    def initialize: (Hash[String, untyped] wire) -> void
+    def to_h: () -> Hash[String, untyped]
+  end
+
+  class AgentFrame
+    def initialize: (Hash[String, untyped] data) -> void
+    def id: () -> Integer
+    def flags: () -> Integer
+    def body: () -> String
+    def terminal?: () -> bool
+    def session_start?: () -> bool
+    def shutdown?: () -> bool
+  end
+
+  class AgentStream
+    include Enumerable[AgentFrame]
+    def id: () -> Integer
+    def recv: () -> AgentFrame?
+    def each: () { (AgentFrame) -> void } -> self
+            | () -> Enumerator[AgentFrame, self]
+    def close: () -> nil
+  end
+
+  class AgentClient
+    FLAG_TERMINAL: Integer
+    FLAG_SESSION_START: Integer
+    FLAG_SHUTDOWN: Integer
+    def self.connect_sandbox: (String name, ?timeout: Numeric?) ?{ (AgentClient) -> untyped } -> untyped
+    def self.connect_path: (String path, ?timeout: Numeric?) ?{ (AgentClient) -> untyped } -> untyped
+    def self.socket_path: (String name) -> String
+    def initialize: (untyped native) -> void
+    def request: (Integer flags, String body) -> AgentFrame
+    def stream: (Integer flags, String body) -> AgentStream
+    def send_frame: (Integer id, Integer flags, String body) -> nil
+    def ready_bytes: () -> String
+    def close: () -> nil
+  end
+
+  class SshOutput
+    def initialize: (Hash[String, untyped] data) -> void
+    def status: () -> Integer
+    def success?: () -> bool
+    def failure?: () -> bool
+    def stdout: () -> String
+    def stderr: () -> String
+    def stdout_bytes: () -> String
+    def stderr_bytes: () -> String
+    def to_s: () -> String
+  end
+
+  class SftpClient
+    def initialize: (untyped native) -> void
+    def read: (String path) -> String
+    def read_text: (String path) -> String
+    def write: (String path, String data) -> nil
+    def mkdir: (String path) -> nil
+    def remove_file: (String path) -> nil
+    def remove_dir: (String path) -> nil
+    def rename: (String old_path, String new_path) -> nil
+    def symlink: (String target, String link_path) -> nil
+    def real_path: (String path) -> String
+    def read_link: (String path) -> String
+    def close: () -> nil
+  end
+
+  class SshClient
+    def initialize: (untyped native) -> void
+    def exec: (String command, ?tty: bool) -> SshOutput
+    def attach: (?term: String?, ?detach_keys: String?) -> Integer
+    def sftp: () ?{ (SftpClient) -> untyped } -> untyped
+    def close: () -> nil
+  end
+
+  class SshServer
+    def initialize: (untyped native) -> void
+    def serve_connection: () -> nil
+    def close: () -> nil
+  end
+
+  class SshOps
+    def initialize: (untyped native) -> void
+    def open_client: (?user: String, ?term: String?, ?sftp: bool) ?{ (SshClient) -> untyped } -> untyped
+    def prepare_server: (?host_key_path: String?, ?authorized_keys_path: String?,
+                         ?user: String?, ?sftp: bool) -> SshServer
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.8
+  version: 0.5.9
 platform: ruby
 authors:
 - ya-luotao
@@ -45,6 +45,7 @@ files:
 - README.md
 - ext/microsandbox/Cargo.toml
 - ext/microsandbox/extconf.rb
+- ext/microsandbox/src/agent.rs
 - ext/microsandbox/src/conv.rs
 - ext/microsandbox/src/error.rs
 - ext/microsandbox/src/exec.rs
@@ -53,9 +54,11 @@ files:
 - ext/microsandbox/src/runtime.rs
 - ext/microsandbox/src/sandbox.rs
 - ext/microsandbox/src/snapshot.rs
+- ext/microsandbox/src/ssh.rs
 - ext/microsandbox/src/stream.rs
 - ext/microsandbox/src/volume.rs
 - lib/microsandbox.rb
+- lib/microsandbox/agent.rb
 - lib/microsandbox/errors.rb
 - lib/microsandbox/exec_handle.rb
 - lib/microsandbox/exec_output.rb
@@ -63,8 +66,11 @@ files:
 - lib/microsandbox/image.rb
 - lib/microsandbox/log_entry.rb
 - lib/microsandbox/metrics.rb
+- lib/microsandbox/network.rb
+- lib/microsandbox/patch.rb
 - lib/microsandbox/sandbox.rb
 - lib/microsandbox/snapshot.rb
+- lib/microsandbox/ssh.rb
 - lib/microsandbox/streams.rb
 - lib/microsandbox/version.rb
 - lib/microsandbox/volume.rb