bsdkrun 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e78b89f68872f94abe500dba9bc0d69bd2b8ff0488745bb1f7e07ef2658f8a28
-  data.tar.gz: 1effefa03711b90030219d9456edbb6df361591184aa9bb7f01c06e87ad582e2
+  metadata.gz: d1b2ffdacfec58cee3714b8ca96ecc133604655d423e264444d8f41ea88393e5
+  data.tar.gz: 848ec7c03c5489a41daf404135c3bbfdcfb126449ecb712ddf920ea7377bc822
 SHA512:
-  metadata.gz: ce3f123068f4c08775e7308513b727182ece1ce14737de2cc874ed050be8e19979e82c902703202f72a162222d0b12363a6aefc5b9441eeab34038976ed28a1c
-  data.tar.gz: 8eb660e5db46bf1fc617b250f76c55f41f75943f2bc71026994790e812c000ae90aa63384956938e7a5bda406d8f59912ab36ac7f5a5029a615738a1ccb4dca3
+  metadata.gz: a86228909ae198caab0e630bac039179fc115317118f321a1aa193683ee6fb10ccfdc56ae1d05d42cad3ebad712897b5979c0b3b75cd0fe9b64bef0406d1d5ae
+  data.tar.gz: aef36636aef92124b1c78695648c929bfee4f60e134b9ef0a2d5588693827994e8023f62c91f39cd2d1a19c74e7e1a6a3d99a99c2aca9df51ba53bf03022368e

data/README.md

@@ -300,6 +300,37 @@ the new machine's id. `run_solo5` boots a MirageOS unikernel under the
 `stop`/`start`/`remove`/`update`/`commit` return a
 `CommandResult` (`exit_code`, `stdout`, `stderr`).
 
+### Snapshots
+
+A snapshot is a **copy-on-write clone of a machine's disk state** — instant to
+take, free until the two sides diverge. `branch` boots a new machine from one
+(or from a machine, which is snapshotted first); `restore`/`rollback` put one
+back, leaving the machine stopped. A BSD guest is powered off to snapshot it:
+a mounted UFS cannot be cloned consistently.
+
+```ruby
+snap = client.snapshot(machine_id, name: "before-upgrade")
+client.snapshots(machine: machine_id)      # newest first
+branch_id = client.branch(snap.name, name: "web-test")
+client.restore(machine_id, snap.name)      # or client.rollback(machine_id)
+client.remove_snapshots(snap.name)
+```
+
+### Docker
+
+bsdkrun runs one `docker:dind` microVM and serves its API on a host unix
+socket, so the host's own `docker` CLI drives the same engine these calls do.
+Starting is idempotent — the VM has a fixed name, so it resumes rather than
+creating a second.
+
+```ruby
+status = client.docker_start(cpus: 4, mem: 4096)   # or just docker_status
+puts status.socket
+client.docker_containers.each { |c| puts "#{c.name} #{c.state} #{c.ports}" }
+client.docker_container("restart", "web")
+puts client.docker_logs("web", tail: 50)
+```
+
 For a live terminal instead of a one-shot `exec`, use `shell`:
 
 ```ruby

data/lib/bsdkrun/client.rb

@@ -35,10 +35,16 @@ module Bsdkrun
     # +web/src/lib/api.ts+'s +MACHINE_FIELDS+ fragment exactly.
     MACHINE_FIELDS = <<~GQL.freeze
       id name image kind command status running exitCode pid detached
-      cpus mem volume stateDir createdAt finishedAt network netIp
+      cpus mem volume stateDir createdAt finishedAt network netIp origin
       ports { bind host guest }
     GQL
 
+    # The +Snapshot+ selection, likewise shared by every snapshot document.
+    SNAPSHOT_FIELDS = <<~GQL.freeze
+      id name machineId machineName kind image path parent description
+      cpus mem size createdAt ports { bind host guest }
+    GQL
+
     # @return [String] the GraphQL endpoint URL (normalized).
     attr_reader :url
 
@@ -242,6 +248,269 @@ module Bsdkrun
       )
     end
 
+    # ---- ai agents -------------------------------------------------------------
+    #
+    # A sandbox is a machine, so its terminal is the ordinary {#shell} with the
+    # argv {#ai_shell_command} returns.
+
+    AI_AGENT_FIELDS = "id label flavor description installed running"
+    AI_SESSION_FIELDS = "id name agent running workspace createdAt"
+
+    # The coding agents, and whether each one's sandbox image is built.
+    # @return [Array<AiAgent>]
+    def ai_agents
+      data = request("{ aiAgents { #{AI_AGENT_FIELDS} } }")
+      (data["aiAgents"] || []).map { |a| AiAgent.from_graphql(a) }
+    end
+
+    # Agent sandboxes, newest first.
+    # @return [Array<AiSession>]
+    def ai_sessions
+      data = request("{ aiSessions { #{AI_SESSION_FIELDS} } }")
+      (data["aiSessions"] || []).map { |s| AiSession.from_graphql(s) }
+    end
+
+    # Start (or reuse) a sandbox; returns its machine id.
+    #
+    # @param agent [String] +claude+, +codex+, ...
+    # @param workspace [String, nil] a directory **on the engine's host**.
+    # @param new [Boolean] boot a second sandbox against the same saved login.
+    # @return [String]
+    def ai_start(agent, cpus: nil, mem: nil, workspace: nil, new: false)
+      data = request(
+        "mutation($input:AiStartInput!){ aiStart(input:$input) }",
+        { input: { agent: agent, cpus: cpus, mem: mem,
+                   workspace: workspace, new: new } }
+      )
+      data["aiStart"].to_s
+    end
+
+    # The argv that starts the agent's TUI — pass it to {#shell}.
+    # @return [Array<String>]
+    def ai_shell_command(agent, machine_id)
+      data = request(
+        "query($agent:String!,$machineId:String!){ " \
+        "aiShellCommand(agent:$agent, machineId:$machineId) }",
+        { agent: agent, machineId: machine_id }
+      )
+      Array(data["aiShellCommand"])
+    end
+
+    # Stop an agent's sandboxes. Its saved login survives.
+    # @return [CommandResult]
+    def ai_stop(agent)
+      run_command_mutation(
+        "aiStop",
+        "mutation($agent:String!){ aiStop(agent:$agent){ exitCode stdout stderr } }",
+        { agent: agent }
+      )
+    end
+
+    # Remove an agent's sandboxes, and unless +keep_home+ its saved login too.
+    # @return [CommandResult]
+    def ai_remove(agent, keep_home: false)
+      run_command_mutation(
+        "aiRemove",
+        "mutation($agent:String!,$keepHome:Boolean!){ " \
+        "aiRemove(agent:$agent, keepHome:$keepHome){ exitCode stdout stderr } }",
+        { agent: agent, keepHome: keep_home }
+      )
+    end
+
+    # ---- docker --------------------------------------------------------------
+    #
+    # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+    # socket, so these drive the same engine the host's +docker+ CLI does.
+
+    DOCKER_STATUS_FIELDS = <<~GQL.freeze
+      running machineId machineRunning socket socketReady apiPort version
+      containers images mounts disk diskSize
+    GQL
+
+    DOCKER_CONTAINER_FIELDS = "id name image command state status ports created"
+
+    # Is the Docker engine up, and where is its socket?
+    # @return [DockerStatus]
+    def docker_status
+      data = request("{ dockerStatus { #{DOCKER_STATUS_FIELDS} } }")
+      DockerStatus.from_graphql(data["dockerStatus"])
+    end
+
+    # Containers in the engine.
+    # @param all [Boolean] include stopped ones (default true).
+    # @return [Array<DockerContainer>]
+    def docker_containers(all: true)
+      data = request(
+        "query($all:Boolean!){ dockerContainers(all:$all){ #{DOCKER_CONTAINER_FIELDS} } }",
+        { all: all }
+      )
+      (data["dockerContainers"] || []).map { |c| DockerContainer.from_graphql(c) }
+    end
+
+    # Start (or resume) the engine, returning its status once it answers.
+    #
+    # Idempotent: the VM has a fixed name, so this resumes the existing one
+    # rather than creating a second.
+    #
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param mounts [Array<String>] host dirs to share, +PATH+ or +HOST:GUEST+.
+    # @param no_home [Boolean] do not share +$HOME+ (shared by default).
+    # @param publish_bind [String, nil] +mirror+ (default) or a fixed address.
+    # @param disk_size [String, nil] a dedicated image store, e.g. +60G+.
+    # @return [DockerStatus]
+    def docker_start(cpus: nil, mem: nil, mounts: [], no_home: false,
+                     publish_bind: nil, disk_size: nil)
+      data = request(
+        "mutation($input:DockerStartInput!){ dockerStart(input:$input){ " \
+        "#{DOCKER_STATUS_FIELDS} } }",
+        { input: { cpus: cpus, mem: mem, mounts: Array(mounts), noHome: no_home,
+                   publishBind: publish_bind, diskSize: disk_size } }
+      )
+      DockerStatus.from_graphql(data["dockerStart"])
+    end
+
+    # Stop the engine. Images and containers stay on its disk.
+    # @return [CommandResult]
+    def docker_stop
+      run_command_mutation(
+        "dockerStop",
+        "mutation{ dockerStop{ exitCode stdout stderr } }",
+        {}
+      )
+    end
+
+    # start | stop | restart | kill | pause | unpause | rm.
+    # @param action [String]
+    # @param ids [String, Array<String>]
+    # @return [CommandResult]
+    def docker_container(action, ids)
+      run_command_mutation(
+        "dockerContainer",
+        "mutation($action:String!,$ids:[String!]!){ " \
+        "dockerContainer(action:$action, ids:$ids){ exitCode stdout stderr } }",
+        { action: action, ids: Array(ids) }
+      )
+    end
+
+    # One container's logs (stdout+stderr, most recent +tail+ lines).
+    # @param id [String]
+    # @param tail [Integer]
+    # @return [String]
+    def docker_logs(id, tail: 200)
+      data = request(
+        "query($id:String!,$tail:Int!){ dockerContainerLogs(id:$id, tail:$tail) }",
+        { id: id, tail: tail }
+      )
+      data["dockerContainerLogs"].to_s
+    end
+
+    # ---- snapshots ---------------------------------------------------------
+    #
+    # A snapshot is a copy-on-write clone of a machine's disk state: instant to
+    # take, free until the two sides diverge. {#branch} boots a new machine
+    # from one; {#restore}/{#rollback} put one back.
+
+    # List snapshots, newest first.
+    # @param machine [String, nil] only this machine's, when given.
+    # @return [Array<SnapshotInfo>]
+    def snapshots(machine: nil)
+      data = request(
+        "query($machine:String){ snapshots(machine:$machine){ #{SNAPSHOT_FIELDS} } }",
+        { machine: machine }
+      )
+      (data["snapshots"] || []).map { |s| SnapshotInfo.from_graphql(s) }
+    end
+
+    # Capture a machine's disk state.
+    #
+    # A BSD guest is powered off first — a mounted UFS cannot be cloned
+    # consistently — so the machine is left stopped; {#start} brings it back.
+    #
+    # @param id [String]
+    # @param name [String, nil] defaults to +<machine>-<n>+.
+    # @param description [String]
+    # @return [SnapshotInfo]
+    def snapshot(id, name: nil, description: "")
+      data = request(
+        "mutation($id:String!,$name:String,$description:String!){ " \
+        "snapshotMachine(id:$id, name:$name, description:$description){ #{SNAPSHOT_FIELDS} } }",
+        { id: id, name: name, description: description }
+      )
+      SnapshotInfo.from_graphql(data["snapshotMachine"])
+    end
+
+    # Delete snapshots and their data. Machines branched from them are
+    # unaffected.
+    # @param names [String, Array<String>]
+    # @return [CommandResult]
+    def remove_snapshots(names)
+      run_command_mutation(
+        "removeSnapshots",
+        "mutation($names:[String!]!){ removeSnapshots(names:$names){ exitCode stdout stderr } }",
+        { names: Array(names) }
+      )
+    end
+
+    # Put a machine's disk state back to one of its snapshots.
+    #
+    # +force+ stops the machine first (it holds the very files being
+    # replaced); +backup+ snapshots the state being overwritten, which is a
+    # CoW clone and therefore free. The machine is left stopped.
+    #
+    # @param id [String]
+    # @param snapshot [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def restore(id, snapshot, force: true, backup: true)
+      run_command_mutation(
+        "restoreMachine",
+        "mutation($id:String!,$snapshot:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "restoreMachine(id:$id, snapshot:$snapshot, force:$force, backup:$backup){ " \
+        "exitCode stdout stderr } }",
+        { id: id, snapshot: snapshot, force: force, backup: backup }
+      )
+    end
+
+    # Restore a machine to its most recent snapshot.
+    # @param id [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def rollback(id, force: true, backup: true)
+      run_command_mutation(
+        "rollbackMachine",
+        "mutation($id:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "rollbackMachine(id:$id, force:$force, backup:$backup){ exitCode stdout stderr } }",
+        { id: id, force: force, backup: backup }
+      )
+    end
+
+    # Boot a NEW machine from a snapshot — or from a machine, which is
+    # snapshotted first — and return the new machine's id.
+    #
+    # The state is cloned, never booted in place, so the source is untouched
+    # and one snapshot can be branched any number of times. With no +ports+,
+    # the snapshot's own forwards are inherited, with any host port that is
+    # already taken swapped for a free one.
+    #
+    # @param snapshot [String] snapshot name/id, or a machine id.
+    # @param name [String, nil]
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param ports [Array<String>]
+    # @param no_ports [Boolean]
+    # @return [String] the new machine's id.
+    def branch(snapshot, name: nil, cpus: nil, mem: nil, ports: [], no_ports: false)
+      data = request(
+        "mutation($input:BranchInput!){ branchSnapshot(input:$input) }",
+        { input: { snapshot: snapshot, name: name, cpus: cpus, mem: mem,
+                   ports: Array(ports), noPorts: no_ports } }
+      )
+      data["branchSnapshot"].to_s
+    end
+
     # One-shot console log fetch. Use {#follow_logs} to stream instead.
     # @param id [String]
     # @param boot [Boolean] bsdkrun's own boot log instead of the guest console.

data/lib/bsdkrun/types.rb

@@ -34,7 +34,7 @@ module Bsdkrun
   SandboxInfo = Data.define(
     :id, :name, :image, :kind, :command, :status, :running, :exit_code,
     :pid, :detached, :cpus, :mem, :volume, :state_dir, :network, :net_ip,
-    :created_at, :finished_at, :ports
+    :created_at, :finished_at, :ports, :origin
   ) do
     # Map a +ps --json+ row (String keys) to a typed instance.
     # @param row [Hash]
@@ -60,7 +60,8 @@ module Bsdkrun
         net_ip: row["net_ip"],
         created_at: row["created_at"].to_i,
         finished_at: to_i_or_nil(row["finished_at"]),
-        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: row["origin"]
       )
     end
 
@@ -96,11 +97,190 @@ module Bsdkrun
         net_ip: m["netIp"],
         created_at: m["createdAt"].to_i,
         finished_at: to_i_or_nil(m["finishedAt"]),
-        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: m["origin"]
       )
     end
   end
 
+  # A machine snapshot: one machine's disk state, captured under a name.
+  #
+  # A copy-on-write clone rather than a memory image — the files the guest
+  # wrote, not what it was executing. {Bsdkrun::Client#branch} boots a new
+  # machine from one; {Bsdkrun::Client#restore} puts one back.
+  SnapshotInfo = Data.define(
+    :id, :name, :machine_id, :machine_name, :kind, :image, :path, :parent,
+    :description, :cpus, :mem, :ports, :size, :created_at
+  ) do
+    # Map a GraphQL +Snapshot+ (camelCase) to a typed instance.
+    # @param s [Hash]
+    # @return [SnapshotInfo]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        machine_id: s["machineId"].to_s,
+        machine_name: (s["machineName"] || "").to_s,
+        kind: s["kind"].to_s,
+        image: (s["image"] || "").to_s,
+        path: (s["path"] || "").to_s,
+        parent: s["parent"],
+        description: (s["description"] || "").to_s,
+        cpus: s["cpus"].to_i,
+        mem: s["mem"].to_i,
+        ports: (s["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: s["size"],
+        created_at: s["createdAt"].to_i
+      )
+    end
+
+    # Map a +bsdkrun snapshots --json+ row (snake_case).
+    # @param row [Hash]
+    # @return [SnapshotInfo]
+    def self.from_row(row)
+      new(
+        id: row["id"].to_s,
+        name: row["name"].to_s,
+        machine_id: row["machine_id"].to_s,
+        machine_name: (row["machine_name"] || "").to_s,
+        kind: row["kind"].to_s,
+        image: (row["image"] || "").to_s,
+        path: (row["path"] || "").to_s,
+        parent: row["parent"],
+        description: (row["description"] || "").to_s,
+        cpus: row["cpus"].to_i,
+        mem: row["mem"].to_i,
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: row["size"],
+        created_at: row["created_at"].to_i
+      )
+    end
+  end
+
+  # A coding agent bsdkrun can sandbox.
+  #
+  # Each runs in a disposable microVM with a persistent login, a shared skills
+  # store, and only the folder you choose to share.
+  AiAgent = Data.define(
+    :id, :label, :flavor, :description, :installed, :running
+  ) do
+    # @param a [Hash]
+    # @return [AiAgent]
+    def self.from_graphql(a)
+      new(
+        id: a["id"].to_s,
+        label: a["label"].to_s,
+        flavor: a["flavor"].to_s,
+        description: (a["description"] || "").to_s,
+        installed: !!a["installed"],
+        running: a["running"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # One agent sandbox. It is a machine, so +logs+/+stop+ work on +id+.
+  AiSession = Data.define(
+    :id, :name, :agent, :running, :workspace, :created_at
+  ) do
+    # @param s [Hash]
+    # @return [AiSession]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        agent: s["agent"].to_s,
+        running: !!s["running"],
+        workspace: s["workspace"],
+        created_at: (s["createdAt"] || s["created_at"]).to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # The Docker engine VM: whether it is up, and how to reach it.
+  #
+  # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+  # socket, so the host's own +docker+ CLI drives the same engine.
+  DockerStatus = Data.define(
+    :running, :machine_id, :machine_running, :socket, :socket_ready, :api_port,
+    :version, :containers, :images, :mounts, :disk, :disk_size
+  ) do
+    # @param s [Hash] a GraphQL +DockerStatus+ (camelCase).
+    # @return [DockerStatus]
+    def self.from_graphql(s)
+      new(
+        running: !!s["running"],
+        machine_id: s["machineId"],
+        machine_running: !!s["machineRunning"],
+        socket: s["socket"].to_s,
+        socket_ready: !!s["socketReady"],
+        api_port: to_i_or_nil(s["apiPort"]),
+        version: s["version"],
+        containers: to_i_or_nil(s["containers"]),
+        images: to_i_or_nil(s["images"]),
+        mounts: Array(s["mounts"]),
+        disk: s["disk"],
+        disk_size: to_i_or_nil(s["diskSize"])
+      )
+    end
+
+    # @param row [Hash] a +bsdkrun docker status --json+ row (snake_case).
+    # @return [DockerStatus]
+    def self.from_row(row)
+      new(
+        running: !!row["running"],
+        machine_id: row["machine_id"],
+        machine_running: !!row["machine_running"],
+        socket: row["socket"].to_s,
+        socket_ready: !!row["socket_ready"],
+        api_port: to_i_or_nil(row["api_port"]),
+        version: row["version"],
+        containers: to_i_or_nil(row["containers"]),
+        images: to_i_or_nil(row["images"]),
+        mounts: Array(row["mounts"]),
+        disk: row["disk"],
+        disk_size: to_i_or_nil(row["disk_size"])
+      )
+    end
+  end
+
+  # A container in the Docker engine VM — a trimmed +docker ps+ row.
+  DockerContainer = Data.define(
+    :id, :name, :image, :command, :state, :status, :ports, :created
+  ) do
+    # @return [Boolean] whether the container is up.
+    def running?
+      state == "running"
+    end
+
+    # Both the GraphQL object and +docker ps --json+ use these field names.
+    # @param c [Hash]
+    # @return [DockerContainer]
+    def self.from_graphql(c)
+      new(
+        id: c["id"].to_s,
+        name: c["name"].to_s,
+        image: c["image"].to_s,
+        command: (c["command"] || "").to_s,
+        state: c["state"].to_s,
+        status: c["status"].to_s,
+        ports: Array(c["ports"]),
+        created: c["created"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
   # An image as reported by +bsdkrun images --json+.
   ImageInfo = Data.define(:id, :reference, :digest, :size, :rootfs, :created_at) do
     # @param row [Hash]

data/lib/bsdkrun/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsdkrun
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Tsiry Sandratraina