bsdkrun 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14072fa1b965040c136001ee65a8ef384205cbc119ef91658c387e2ed84100fb
-  data.tar.gz: c3981e13c6a964c084b3a1b54a051801ab373eda107f74dd869e789242c744df
+  metadata.gz: e78b89f68872f94abe500dba9bc0d69bd2b8ff0488745bb1f7e07ef2658f8a28
+  data.tar.gz: 1effefa03711b90030219d9456edbb6df361591184aa9bb7f01c06e87ad582e2
 SHA512:
-  metadata.gz: 5dcbfd7f46c6e412acc0eccc6ccbe639fdffaf875a8ac56e8af0bbac4ec4654804a149f8eff78316ad0ca06cf2338414de320cf6ba05ca8a8ea11d579167c92e
-  data.tar.gz: 165af797cc3af4b111c9fad1c02f8f1b788d1e900e1d49715e8547b02e8849b768b21ed3cc81d4f922accb073b46f33f7400d7ff854f5868de92869802d3699a
+  metadata.gz: ce3f123068f4c08775e7308513b727182ece1ce14737de2cc874ed050be8e19979e82c902703202f72a162222d0b12363a6aefc5b9441eeab34038976ed28a1c
+  data.tar.gz: 8eb660e5db46bf1fc617b250f76c55f41f75943f2bc71026994790e812c000ae90aa63384956938e7a5bda406d8f59912ab36ac7f5a5029a615738a1ccb4dca3

data/README.md

@@ -9,14 +9,14 @@ dependencies** — just the Ruby standard library (`open3`, `json`, `pathname`).
 ```ruby
 require "bsdkrun"
 
-box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
 
 # exec argv directly, with env / stdin / a PTY / a working dir:
-puts box.exec(["uname", "-a"]).text
-box.exec(["apk", "add", "curl"], throw_on_error: true)
-box.run_command("curl", ["-fsSL", "https://example.com"])
+puts sbx.exec(["uname", "-a"]).text
+sbx.exec(["apk", "add", "curl"], throw_on_error: true)
+sbx.run_command("curl", ["-fsSL", "https://example.com"])
 
-box.stop
+sbx.stop
 ```
 
 ## Install
@@ -77,15 +77,34 @@ Bsdkrun::Sandbox.create(os: "kernel", kernel: "netbsd", format: "elf", disk: "ro
 
 Every `create` runs the machine **detached** and returns a `Sandbox` handle.
 
+### Environment variables
+
+`env:` sets the guest environment for the machine's entrypoint. It is merged
+over the image's own config, so a key the image already defines is replaced
+rather than duplicated.
+
+```ruby
+sbx = Bsdkrun::Sandbox.create(
+  os: "linux",
+  image: "node:22",
+  env: { "NODE_ENV" => "production", "PORT" => "3000" },
+  command: ["node", "server.js"]
+)
+```
+
+Linux guests only — BSD guests boot their own init, so there is no generated
+init to export into; set those from `exec` after boot. For a single command
+rather than the whole machine, `exec` takes its own `env:`.
+
 ## Running commands
 
 `exec` is the primary programmatic entrypoint. No shell parsing — pass an argv
 array (or a program name plus `args:`).
 
 ```ruby
-box.exec(["ls", "-la", "/etc"])
+sbx.exec(["ls", "-la", "/etc"])
 
-box.exec("ruby",
+sbx.exec("ruby",
   args: ["-e", "puts ENV['X']"],
   env: { "X" => "hi" },
   cwd: "/app",
@@ -96,7 +115,7 @@ box.exec("ruby",
   throw_on_error: true)      # raise on non-zero exit (default: false)
 
 # Vercel-Sandbox-style alias:
-result = box.run_command("uname", ["-a"])
+result = sbx.run_command("uname", ["-a"])
 result.stdout       # raw stdout
 result.text         # stdout, trailing newlines trimmed
 result.exit_code
@@ -111,21 +130,74 @@ The callbacks run as chunks arrive, and the same bytes remain buffered in the
 returned result. They do not require `tty`; a PTY changes command semantics and
 may merge stderr into stdout.
 
+## Caching
+
+`sbx.cache` saves a guest directory under a key and restores it later, so a
+rebuild can pick up where the last one left off. **A miss is not an error** —
+check `restored` rather than rescuing.
+
+```ruby
+key = "deps-#{lock_hash}"
+hit = sbx.cache.restore(key: key, restore_keys: ["deps-"])
+unless hit.restored
+  sbx.exec(["npm", "ci"])
+  sbx.cache.save("/app/node_modules", key: key, compression: "zstd")
+end
+
+Bsdkrun::Caches.ls          # every stored entry, newest first
+Bsdkrun::Caches.rm([key])   # or Bsdkrun::Caches.rm(all: true)
+```
+
+`restore_keys` are prefixes tried in order when the exact key misses; within a
+prefix the newest matching entry wins, and `hit.key` says which one was used.
+Formats are `gzip` (default), `zstd`, `estargz` and `none`.
+
+Where entries live is host configuration, not an SDK concern: the default is
+this host's disk, and `BSDKRUN_CACHE_BACKEND=s3` + `BSDKRUN_CACHE_S3_*` (or
+`~/.config/bsdkrun/cache.toml`) points them at a bucket instead.
+
+## Files
+
+`sbx.fs` reads and writes files in the guest. Parent directories are created
+for you, and everything is byte-exact — `read_file` returns a binary string.
+
+```ruby
+sbx.fs.write_file("/app/main.py", "print('hi')")
+sbx.fs.write_file("/app/logo.png", png_bytes)
+
+text  = sbx.fs.read_text("/app/out.json")
+bytes = sbx.fs.read_file("/app/logo.png")
+
+sbx.fs.upload("./src", "/app/src")                       # file or directory
+sbx.fs.download("/app/dist", "./dist", recursive: true)
+```
+
+`upload` looks at the local path to decide whether to recurse; `download` cannot
+(the path is in the guest), so say so for a directory. A directory's *contents*
+land in the destination: uploading `./src` to `/app/src` leaves the guest's
+`/app/src` holding what `./src` holds.
+
+Failures raise `Bsdkrun::FileTransferFailed`, which carries the offending `path`.
+
+> Transfers ride the same in-guest agent as `exec`, so the sandbox must be
+> running. A directory copy also needs `tar` in the guest; single files need
+> only the shell every bootable image already has.
+
 ## Lifecycle & inventory
 
 ```ruby
-box  = Bsdkrun::Sandbox.create(os: "linux", image: "alpine", command: ["sleep", "300"])
-same = Bsdkrun::Sandbox.get(box.id)          # reconnect (prefix ok)
+sbx  = Bsdkrun::Sandbox.create(os: "linux", image: "alpine", command: ["sleep", "300"])
+same = Bsdkrun::Sandbox.get(sbx.id)          # reconnect (prefix ok)
 all  = Bsdkrun::Sandbox.list(all: true)      # Array<SandboxInfo>
 
-box.status        # SandboxInfo | nil
-box.running?      # true / false
-box.logs          # console log (String)
-box.shell         # interactive shell (inherits the terminal)
-box.stop          # BSD guests clean-poweroff; Linux SIGTERM
-box.start         # restart in place — resumes its own disk/rootfs (data persists)
-box.update(cpus: 4, mem: 2048)               # applies on next start
-box.remove(force: true)
+sbx.status        # SandboxInfo | nil
+sbx.running?      # true / false
+sbx.logs          # console log (String)
+sbx.shell         # interactive shell (inherits the terminal)
+sbx.stop          # BSD guests clean-poweroff; Linux SIGTERM
+sbx.start         # restart in place — resumes its own disk/rootfs (data persists)
+sbx.update(cpus: 4, mem: 2048)               # applies on next start
+sbx.remove(force: true)
 ```
 
 Host-level namespaces:
@@ -147,11 +219,11 @@ Bsdkrun::System.versions("netbsd")             # Array<String>
 Bsdkrun::Sandbox.create(os: "linux", image: "alpine", net: { ports: ["2222:22"] })
 
 # agent-managed key-based SSH
-box.ssh_setup                                  # install local ~/.ssh/*.pub keys
-box.ssh_setup(user: "tsiry", key: "~/.ssh/work.pub")
+sbx.ssh_setup                                  # install local ~/.ssh/*.pub keys
+sbx.ssh_setup(user: "tsiry", key: "~/.ssh/work.pub")
 
 # put a guest on your tailnet
-box.tailscale_up(authkey: "tskey-auth-...", hostname: "web")
+sbx.tailscale_up(authkey: "tskey-auth-...", hostname: "web")
 ```
 
 ### Global networks — reach machines by name

data/lib/bsdkrun/args.rb

@@ -28,6 +28,17 @@ module Bsdkrun
     # +--name+ flag if a name is set.
     # @param o [Hash]
     # @return [Array<String>]
+    # +-e K=V+ per entry, sorted by key.
+    #
+    # A hash has no argv order of its own, so sorting is what makes the command
+    # line — and the tests that assert on it — deterministic. The guest sees the
+    # same environment either way.
+    def env_args(env)
+      return [] if env.nil? || env.empty?
+
+      env.to_h.sort_by { |k, _| k.to_s }.flat_map { |k, v| ["-e", "#{k}=#{v}"] }
+    end
+
     def name_args(o)
       o[:name] ? ["--name", o[:name].to_s] : []
     end
@@ -81,7 +92,9 @@ module Bsdkrun
       a.push("--initramfs") if opts[:initramfs]
       a.push("-v", opts[:volume]) if opts[:volume]
       Array(opts[:mounts]).each { |m| a.push("--mount", m) }
+      Array(opts[:attach_disk]).each { |d| a.push("--attach-disk", d) }
       a.push("--entrypoint", opts[:entrypoint]) if opts[:entrypoint]
+      a.concat(env_args(opts[:env]))
       a.push("--console", opts[:console]) if opts[:console]
       a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
       cmd = opts[:command]

data/lib/bsdkrun/cache.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # A stored cache entry, as +cache ls+ reports it.
+  CacheEntry = Struct.new(:key, :path, :compression, :size, :created, :digest, keyword_init: true) do
+    def self.from(row)
+      new(
+        key: row["key"].to_s,
+        path: row["path"].to_s,
+        compression: row["compression"].to_s,
+        size: row["size"].to_i,
+        created: row["created"].to_i,
+        digest: row["digest"].to_s
+      )
+    end
+  end
+
+  # What a restore did. A miss is not an error — check +restored+.
+  RestoreResult = Struct.new(
+    :restored, :requested_key, :key, :path, :size, :compression, :created,
+    keyword_init: true
+  )
+
+  # Save and restore guest directories under a key, reached as {Sandbox#cache}.
+  #
+  # Entries are keyed, so a rebuild can pick up where the last one left off:
+  #
+  #   hit = sbx.cache.restore(key: key, restore_keys: ["deps-"])
+  #   unless hit.restored
+  #     sbx.exec(["npm", "ci"])
+  #     sbx.cache.save("/app/node_modules", key: key)
+  #   end
+  #
+  # Where entries live — host disk or S3 — is host configuration, not an SDK
+  # concern: set +BSDKRUN_CACHE_BACKEND+ / +BSDKRUN_CACHE_S3_*+, or write
+  # +~/.config/bsdkrun/cache.toml+.
+  class Cache
+    # @param id [String] the machine's id.
+    def initialize(id)
+      @id = id
+    end
+
+    # Archive the guest directory at +path+ under +key+.
+    #
+    # @param path [String] absolute path in the guest.
+    # @param key [String] key to store under.
+    # @param compression [String] gzip (default), zstd, estargz or none.
+    # @param force [Boolean] replace an entry that already has this key.
+    # @return [CacheEntry]
+    def save(path, key:, compression: "gzip", force: false)
+      args = ["cache", "save", "#{@id}:#{path}", "--key", key, "--json"]
+      args += ["--compression", compression] unless compression == "gzip"
+      args << "--force" if force
+      CacheEntry.from(json(args, "bsdkrun cache save"))
+    end
+
+    # Restore a stored tree.
+    #
+    # @param key [String]
+    # @param path [String, nil] defaults to where the entry was saved from.
+    # @param restore_keys [Array<String>] prefixes tried in order on a miss.
+    # @return [RestoreResult]
+    def restore(key:, path: nil, restore_keys: [])
+      target = path ? "#{@id}:#{path}" : @id
+      args = ["cache", "restore", target, "--key", key, "--json"]
+      args += ["--restore-keys", *restore_keys] unless restore_keys.empty?
+      row = json(args, "bsdkrun cache restore")
+      RestoreResult.new(
+        restored: !!row["restored"],
+        requested_key: row["requested_key"].to_s,
+        key: row["key"],
+        path: row["path"],
+        size: row["size"],
+        compression: row["compression"],
+        created: row["created"]
+      )
+    end
+
+    private
+
+    def json(args, label)
+      out = Process.run!(args, label: label).stdout
+      JSON.parse(out.strip.empty? ? "{}" : out)
+    end
+  end
+
+  # Host-level cache operations, mirroring {Bsdkrun.volumes}.
+  module Caches
+    module_function
+
+    # @return [Array<CacheEntry>] every stored entry, newest first.
+    def ls
+      out = Process.run!(["cache", "ls", "--json"], label: "bsdkrun cache ls").stdout
+      JSON.parse(out.strip.empty? ? "[]" : out).map { |row| CacheEntry.from(row) }
+    end
+
+    # Remove entries by key, or every one with <tt>all: true</tt>.
+    # @return [void]
+    def rm(keys = [], all: false)
+      args = ["cache", "rm"]
+      if all
+        args << "--all"
+      else
+        args += Array(keys)
+      end
+      Process.run!(args, label: "bsdkrun cache rm")
+      nil
+    end
+  end
+end

data/lib/bsdkrun/client.rb

@@ -293,6 +293,7 @@ module Bsdkrun
         net: net_input(o[:net]),
         volume: o[:volume],
         mounts: o[:mounts] || [],
+        attachDisk: o[:attach_disk] || [],
         env: o[:env] || [],
         entrypoint: o[:entrypoint],
         initramfs: o[:initramfs] || false,

data/lib/bsdkrun/errors.rb

@@ -50,6 +50,19 @@ module Bsdkrun
     end
   end
 
+  # A guest filesystem operation was refused (see {FileSystem}).
+  class FileTransferFailed < Error
+    # @return [String] the path that could not be transferred.
+    attr_reader :path
+
+    # @param message [String]
+    # @param path [String]
+    def initialize(message, path)
+      @path = path
+      super(message)
+    end
+  end
+
   # A GraphQL request to a remote +bsdkrund+ daemon failed — a transport
   # failure, a non-JSON response, or a +body["errors"]+ entry that was not an
   # auth failure. Mirrors +web/src/lib/graphql.ts+'s +GraphQLError+.

data/lib/bsdkrun/filesystem.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # Files in a running sandbox, reached as {Sandbox#fs}.
+  #
+  # Every call goes through the guest's exec agent, so the sandbox has to be
+  # running — there is no offline write.
+  #
+  # @example
+  #   sbx.fs.write_file("/app/main.py", "print('hi')")
+  #   sbx.fs.read_text("/app/out.json")
+  #   sbx.fs.upload("./src", "/app/src")
+  #   sbx.fs.download("/app/dist", "./dist", recursive: true)
+  class FileSystem
+    # @param id [String] the machine's id.
+    def initialize(id)
+      @id = id
+    end
+
+    # Write +data+ to +path+ in the guest, creating parent directories.
+    #
+    # @param path [String] absolute path in the guest.
+    # @param data [String] text or binary content.
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def write_file(path, data)
+      res = Process.run(["cp", "-", "#{@id}:#{path}"], stdin: data, binary: true)
+      check!(res, path)
+      nil
+    end
+
+    # Read +path+ from the guest as bytes (ASCII-8BIT).
+    #
+    # @param path [String]
+    # @return [String] binary string.
+    # @raise [FileTransferFailed]
+    def read_file(path)
+      res = Process.run(["cp", "#{@id}:#{path}", "-"], binary: true)
+      check!(res, path)
+      res.stdout
+    end
+
+    # Read +path+ from the guest and tag it with +encoding+.
+    #
+    # @param path [String]
+    # @param encoding [String]
+    # @return [String]
+    def read_text(path, encoding: "UTF-8")
+      read_file(path).force_encoding(encoding)
+    end
+
+    # Copy a host file or directory into the guest.
+    #
+    # A directory's *contents* land in +remote_path+, so
+    # <tt>upload("./src", "/app/src")</tt> leaves the guest's +/app/src+ holding
+    # what +./src+ holds. Whether it recurses is decided by looking at the local
+    # path, so callers do not have to say which kind of thing it is.
+    #
+    # @param local_path [String]
+    # @param remote_path [String]
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def upload(local_path, remote_path)
+      unless File.exist?(local_path)
+        raise FileTransferFailed.new("cannot upload #{local_path}: no such file or directory",
+                                     local_path)
+      end
+      args = ["cp"]
+      args << "-r" if File.directory?(local_path)
+      args += [local_path.to_s, "#{@id}:#{remote_path}"]
+      check!(Process.run(args), local_path)
+      nil
+    end
+
+    # Copy a file or directory out of the guest onto the host.
+    #
+    # Pass <tt>recursive: true</tt> for a directory; unlike {#upload} it cannot
+    # be detected here, because the path lives in the guest and answering would
+    # cost an extra round trip.
+    #
+    # @param remote_path [String]
+    # @param local_path [String]
+    # @param recursive [Boolean]
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def download(remote_path, local_path, recursive: false)
+      args = ["cp"]
+      args << "-r" if recursive
+      args += ["#{@id}:#{remote_path}", local_path.to_s]
+      check!(Process.run(args), remote_path)
+      nil
+    end
+
+    private
+
+    def check!(res, path)
+      return if res.exit_code.zero?
+
+      # The CLI already explains these well; strip its "Error: " prefix.
+      text = res.stderr.to_s.strip.sub(/\AError:\s*/, "")
+      text = "file transfer failed for #{path}" if text.empty?
+      raise FileTransferFailed.new(text, path)
+    end
+  end
+end

data/lib/bsdkrun/process.rb

@@ -26,15 +26,23 @@ module Bsdkrun
     # @param env [Hash] extra environment merged onto the process env.
     # @param stdin [String, nil] data piped to the child's stdin.
     # @param log_level [Integer] bsdkrun global log level (0=off .. 5=trace).
+    # @param binary [Boolean] keep stdout as bytes (ASCII-8BIT) instead of text.
+    #   Needed by {FileSystem#read_file}: appending a chunk of arbitrary bytes to
+    #   a UTF-8 buffer raises Encoding::CompatibilityError, so a PNG read back
+    #   out of a guest would blow up mid-transfer rather than return.
     # @return [RawResult]
-    def run(args, env: {}, stdin: nil, log_level: 0, on_stdout: nil, on_stderr: nil)
+    def run(args, env: {}, stdin: nil, log_level: 0, on_stdout: nil, on_stderr: nil, binary: false)
       bin = Binary.resolve
       full = ["--log-level", log_level.to_s, *args]
       merged_env = env.to_h.transform_keys(&:to_s).transform_values(&:to_s)
-      out = +""
+      out = binary ? (+"").b : +""
       err = +""
       status = nil
       Open3.popen3(merged_env, bin, *full) do |child_in, child_out, child_err, wait|
+        if binary
+          child_in.binmode
+          child_out.binmode
+        end
         writer = Thread.new { child_in.write(stdin) if stdin; child_in.close }
         stdout_reader = Thread.new do
           while (chunk = child_out.readpartial(8192) rescue nil)

data/lib/bsdkrun/sandbox.rb

@@ -9,9 +9,9 @@ module Bsdkrun
   # with {Sandbox.list}.
   #
   # @example
-  #   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
-  #   box.exec(["uname", "-a"]).text
-  #   box.stop
+  #   sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+  #   sbx.exec(["uname", "-a"]).text
+  #   sbx.stop
   class Sandbox
     ID_RE = /\A[0-9a-f]{6,}\z/
     SSH_PORT_RE = /ssh -p (\d+)/
@@ -32,6 +32,18 @@ module Bsdkrun
       @ssh_port = ssh_port
     end
 
+    # Read and write files in the guest.
+    # @return [FileSystem]
+    def fs
+      @fs ||= FileSystem.new(@id)
+    end
+
+    # Save and restore guest directories under a key.
+    # @return [Cache]
+    def cache
+      @cache ||= Cache.new(@id)
+    end
+
     class << self
       # Boot a new microVM and return a handle to it.
       #

data/lib/bsdkrun/version.rb

@@ -2,5 +2,5 @@
 
 module Bsdkrun
   # The bsdkrun Ruby SDK version.
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/bsdkrun.rb

@@ -5,6 +5,8 @@ require_relative "bsdkrun/errors"
 require_relative "bsdkrun/binary"
 require_relative "bsdkrun/process"
 require_relative "bsdkrun/args"
+require_relative "bsdkrun/cache"
+require_relative "bsdkrun/filesystem"
 require_relative "bsdkrun/types"
 require_relative "bsdkrun/sandbox"
 require_relative "bsdkrun/images"
@@ -23,9 +25,9 @@ require_relative "bsdkrun/client"
 # @example
 #   require "bsdkrun"
 #
-#   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
-#   puts box.exec(["uname", "-a"]).text
-#   box.stop
+#   sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+#   puts sbx.exec(["uname", "-a"]).text
+#   sbx.stop
 module Bsdkrun
   class << self
     # Force the SDK to use a specific +bsdkrun+ binary, bypassing discovery.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsdkrun
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Tsiry Sandratraina
@@ -51,8 +51,10 @@ files:
 - lib/bsdkrun.rb
 - lib/bsdkrun/args.rb
 - lib/bsdkrun/binary.rb
+- lib/bsdkrun/cache.rb
 - lib/bsdkrun/client.rb
 - lib/bsdkrun/errors.rb
+- lib/bsdkrun/filesystem.rb
 - lib/bsdkrun/images.rb
 - lib/bsdkrun/networks.rb
 - lib/bsdkrun/process.rb