bsdkrun 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3cc7fd1dcbcb90243855217c4fe7852f6e98baf235fc6e0875ca3f7aeafeb7b
-  data.tar.gz: 92aaa16edb2d6970912f64840835dbd78611cf9f30bc4c5830c1c4f0f537fa71
+  metadata.gz: b23de4b48a88b521c5909ad2aa610d8557e9b06661e450db3d862292cc3bb296
+  data.tar.gz: be6175dd5884c7ec861a57f355c3dff05d01e759355117d8e21e27904b717063
 SHA512:
-  metadata.gz: 1505af9b58a1397e6de294f06d76b2a8ca81ae0a46ba80f61c12baa6e5de99d8e9fba3c973bee7157c663233e575468bbe175e435fe23a01258855a4278a00fa
-  data.tar.gz: 38b533ac4692529528ce0c5c5739b1f62f8012f7ec6a2ac2814f866c99d7ec47a13ab26f1639e102012ca4e8161483cfe0731c8d987c23432da42133dfc61167
+  metadata.gz: 9b2b575fc9be711c375a053537e8ba687d162c4180c1e7075aaa5e3d27d8992655615c10c28ca5894a066213a3d8382c9f6f7c31fdca7118b8dc72707bddf86f
+  data.tar.gz: 38d9ba56709b1b870df9873d70c658e68534fb2eb90fa6c6793a2e87aa80d9fe1f076a6324579f4834a9241554960b35c6501ebc05e3896a781da3166be2c565

data/README.md

@@ -1,9 +1,7 @@
 # bsdkrun (Ruby SDK)
 
-A Ruby SDK for [**bsdkrun**](https://github.com/tsirysndr/bsdkrun) — a
-Firecracker-style microVM launcher for **BSD and Linux** guests on macOS and
-Linux, built on [libkrun](https://github.com/containers/libkrun). Boot and drive
-microVMs programmatically, inspired by the **Vercel** and **Deno** Sandbox SDKs.
+A Ruby SDK for [**bsdkrun**](https://github.com/tsirysndr/bsdkrun) — a Firecracker-style microVM launcher for **BSD, Linux, and unikernel** guests on macOS and
+Linux, built on [libkrun](https://github.com/containers/libkrun). Boot and drive microVMs programmatically, inspired by the **Vercel** and **Deno** Sandbox SDKs.
 
 The SDK shells out to the `bsdkrun` binary, so it has **zero runtime
 dependencies** — just the Ruby standard library (`open3`, `json`, `pathname`).
@@ -191,6 +189,71 @@ Names resolve on Linux and FreeBSD via the network's DNS; **NetBSD** resolves
 via a synced `/etc/hosts` block — joins auto-sync, and `Networks.sync` refreshes
 an existing network without restarting members.
 
+## Connecting to a remote daemon
+
+Everything above talks to a local `bsdkrun` binary. `Bsdkrun::Client` is the
+network sibling: it drives the same operations against a remote
+[`bsdkrund`](../../daemon/README.md) over its GraphQL API — no local binary
+needed, just a URL and a bearer token.
+
+```ruby
+require "bsdkrun"
+
+client = Bsdkrun::Client.new(url: "http://vps.example.com:50052", token: "9f2c...")
+# or, from BSDKRUN_URL / BSDKRUN_TOKEN:
+client = Bsdkrun::Client.from_env
+
+machines = client.list(all: true)  # Array<SandboxInfo> — same type Sandbox.list returns
+id = client.run_linux(image: "alpine", cpus: 2, mem: 1024, command: ["sleep", "300"])
+
+result = client.exec(id, ["uname", "-a"])
+puts result.output, result.exit_code
+
+client.stop(id)
+client.remove([id])
+```
+
+`client.run_linux`/`run_bsd`/`run_nanos`/`run_unikraft`/`run_solo5`/`run_osv`/
+`run_flavor` each take the same options as the corresponding GraphQL mutation
+(`daemon/src/graphql.rs`) — `run_bsd(os: "freebsd", ...)`, etc. — and return
+the new machine's id. `run_solo5` boots a MirageOS unikernel under the
+`solo5-hvt` tender rather than libkrun:
+`run_solo5(path: "dist/hello.hvt", args: ["--ipv4=10.0.0.2/24"])`.
+`stop`/`start`/`remove`/`update`/`commit` return a
+`CommandResult` (`exit_code`, `stdout`, `stderr`).
+
+For a live terminal instead of a one-shot `exec`, use `shell`:
+
+```ruby
+session = client.shell(id)  # or shell(id, command: [...]) for a non-login command
+session.on_output { |bytes| $stdout.write(bytes) }
+session.on_exit { |code| puts "\nexited #{code}" }
+session.write("ls -la\n")
+session.resize(50, 120)
+session.close
+```
+
+`follow_logs(id) { |bytes| ... }` streams a machine's console live instead of
+the one-shot `logs(id)`. Both `exec`/`shell` and `follow_logs` are built on
+the same `openShell`/`shellOutput` shell-session protocol the daemon uses for
+every interactive terminal — see [`daemon/README.md`](../../daemon/README.md#interactive-shells-over-graphql)
+for the wire-level story.
+
+Not every GraphQL operation has a typed method yet (flavor/network/volume
+management, for instance) — `client.request(query, variables)` runs any raw
+query or mutation, and `client.subscribe(query, variables, on_next: ...)` runs
+any raw subscription, for anything not wrapped above.
+
+Like the rest of this gem, `Client` uses **only the Ruby standard library** —
+the HTTP transport is `Net::HTTP`, and subscriptions (used by `exec`/`shell`/
+`follow_logs`) run over a hand-rolled `graphql-transport-ws` client on top of
+`Socket`/`OpenSSL`, since Ruby's standard library has no WebSocket client of
+its own.
+
+`Client.new(url:, token:)` and `.from_env` both reject a URL configured
+without a token rather than silently making an unauthenticated request — set
+both `BSDKRUN_URL` and `BSDKRUN_TOKEN`, or pass both explicitly.
+
 ## Errors
 
 All errors extend `Bsdkrun::Error`:
@@ -200,6 +263,9 @@ All errors extend `Bsdkrun::Error`:
   `stdout`, `stderr`, `command`). Raised by `exec` with `throw_on_error: true`,
   by the lifecycle/namespace helpers, and by the agent helpers.
 - `Bsdkrun::SandboxNotFound` — `Sandbox.get` matched no machine.
+- `Bsdkrun::GraphQLError` — a `Client` request failed (carries `code`, the
+  daemon's `extensions.code`, when there is one).
+- `Bsdkrun::AuthError` (a `GraphQLError`) — the daemon rejected the bearer token.
 
 ## Try it interactively
 

data/lib/bsdkrun/args.rb

@@ -65,6 +65,10 @@ module Bsdkrun
       when "netbsd"   then netbsd_args(opts)
       when "firmware" then firmware_args(opts)
       when "kernel"   then kernel_args(opts)
+      when "unikraft" then unikraft_args(opts)
+      when "solo5"    then solo5_args(opts)
+      when "nanos"    then nanos_args(opts)
+      when "osv"      then osv_args(opts)
       else raise ArgumentError, "unknown os: #{opts[:os].inspect}"
       end
     end
@@ -121,5 +125,67 @@ module Bsdkrun
       a.concat(disk_args(opts)).concat(net_args(opts[:net]))
        .concat(name_args(opts)).concat(vm_args(opts))
     end
+
+    # @!visibility private
+    #
+    # Nanos: no agent (like unikraft), but it has a root disk, so +persist+
+    # is honored. +:image+ is a path or a ~/.ops/images name.
+    def nanos_args(opts)
+      a = ["nanos", "-d"]
+      a.push("--kernel", opts[:kernel]) if opts[:kernel]
+      a.push("--cmdline", opts[:cmdline]) if opts[:cmdline]
+      a.push("--persist") if opts[:persist]
+      a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
+      a.push(opts.fetch(:image).to_s)
+    end
+
+    # @!visibility private
+    #
+    # OSv: like nanos, no agent (no exec/shell/snapshot), but it does have a
+    # root filesystem, so +persist+ is honored. +:image+ is a loader.img, or on
+    # x86_64 the loader ELF plus a +:disk+.
+    def osv_args(opts)
+      a = ["osv", "-d"]
+      a.push("--cmdline", opts[:cmdline]) if opts[:cmdline]
+      a.push("--disk", opts[:disk]) if opts[:disk]
+      a.push("--gic", opts[:gic].to_s) if opts[:gic]
+      a.push("--persist") if opts[:persist]
+      a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
+      a.push(opts.fetch(:image).to_s)
+    end
+
+    # @!visibility private
+    #
+    # No +disk_args+: a unikernel has no disk, so there is nothing to persist,
+    # attach or clone. +:path+ is a kraft project dir or an image; default +.+.
+    def unikraft_args(opts)
+      a = ["unikraft", "-d"]
+      a.push("--cmdline", opts[:cmdline]) if opts[:cmdline]
+      a.push("--initramfs", opts[:initramfs]) if opts[:initramfs]
+      # Volumes are the exception to "no disk options": virtio-fs shares,
+      # which need neither a disk nor an agent.
+      Array(opts[:mounts]).each { |m| a.push("--mount", m) }
+      a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
+      a.push((opts[:path] || ".").to_s)
+    end
+
+    # @!visibility private
+    #
+    # Solo5 (MirageOS): runs under the +solo5-hvt+ tender rather than libkrun.
+    # The unikernel declares its devices in its own MFT1 manifest, so only the
+    # +:block+ backing files (+NAME=FILE+) are passed. +:path+ is a +.hvt+
+    # binary or a project dir whose +dist/+ holds one; default +.+. Guest
+    # +:args+ go last, after a literal +--+ — MirageOS options look like
+    # bsdkrun's own (e.g. +--ipv4=...+), so the CLI takes them as trailing
+    # args.
+    def solo5_args(opts)
+      a = ["solo5", "-d"]
+      Array(opts[:block]).each { |b| a.push("--block", b) }
+      a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
+      a.push((opts[:path] || ".").to_s)
+      args = Array(opts[:args])
+      a.push("--", *args) unless args.empty?
+      a
+    end
   end
 end