bsdkrun 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 86e468aea9e96825db542d4c5e9ddf2fbbc473ddfb4e4b7edfa8ecac48abd685
4
- data.tar.gz: 86f792adb80c6218763193a256b16c4f307e68063a494718277e4e4b94d3c0b1
3
+ metadata.gz: 9b75574627d21db63ed83e7f53f408040625b0d640e6f2746c99c14c3d8c64e4
4
+ data.tar.gz: 25f6eb79d3c448b286ddb310e07e25811d0ad2e0529075755c195c852e66a861
5
5
  SHA512:
6
- metadata.gz: e948aea05cab5bffabb28a50a0fb8df66500ab6b6ead6fe0e8a3ff9f07d981f84f19deac1f775e7c4a7665dd037a711d2c6aba19fb15ee4d1cdb7903f8293c40
7
- data.tar.gz: 56d75e614b8f78319079302e61cc257cd30a3229e27384d09e6412c9bcb58459a6519d6df4e17a608a0b0fc18e92569e4510fea063bc849b13e60af3a723cea8
6
+ metadata.gz: e4909e766e538e2e3b19149bfdcb8352a75660b36f3e3857dee1b3a58a147c8b6c84607c88ae2a8601770383cd09bd28cc37201ca6a8dc0a6555fed75a10465e
7
+ data.tar.gz: 1e907304edd3923d0288cd4db7e6518c5bb0c398b0d0ad0cf68eeaa3660062f25c48a8a461df354b5cb5a4bff6cb505a1ec15b0cdd9fdeaa8afeaadcafb0088b
data/README.md CHANGED
@@ -207,6 +207,16 @@ Bsdkrun::System.probe # toolchain sanity check -> Boole
207
207
  Bsdkrun::Images.list # Array<ImageInfo>
208
208
  Bsdkrun::Volumes.list # Array<VolumeInfo>
209
209
  Bsdkrun::Volumes.remove("web", force: true)
210
+
211
+ # ZFS volumes: one zpool per volume, branched copy-on-write in the guest
212
+ # (zfs clone), held by one machine at a time (Linux, FreeBSD, NetBSD).
213
+ Bsdkrun::Zfs.create("data", size: "10G") # sparse image; pool made on first import
214
+ Bsdkrun::Zfs.attach("data", vm_id) # data@main at /mnt/data on next start
215
+ Bsdkrun::Zfs.branch("data", "feature") # zfs snapshot + clone, no copy
216
+ Bsdkrun::Zfs.attach("data@feature", vm_id, mount: "/srv")
217
+ Bsdkrun::Zfs.list # Array<ZfsVolumeInfo>
218
+ Bsdkrun::Zfs.destroy("data@feature")
219
+ Bsdkrun::Zfs.destroy("data", force: true)
210
220
  Bsdkrun::Networks.list # Array<NetworkInfo>
211
221
  Bsdkrun::System.fetch_image("freebsd", version: "14.3")
212
222
  Bsdkrun::System.versions("netbsd") # Array<String>
data/lib/bsdkrun/types.rb CHANGED
@@ -315,6 +315,60 @@ module Bsdkrun
315
315
  end
316
316
  end
317
317
 
318
+ # One branch of a ZFS volume mounted in a guest.
319
+ ZfsMount = Data.define(:branch, :mountpoint) do
320
+ # @param row [Hash]
321
+ # @return [ZfsMount]
322
+ def self.from_row(row)
323
+ new(branch: row["branch"].to_s, mountpoint: row["mountpoint"].to_s)
324
+ end
325
+ end
326
+
327
+ # A branch of a ZFS volume: a dataset cloned copy-on-write inside its pool.
328
+ # +origin+ is the branch it was cloned from, nil for +main+.
329
+ ZfsBranch = Data.define(:name, :origin, :created_at) do
330
+ # @param row [Hash]
331
+ # @return [ZfsBranch]
332
+ def self.from_row(row)
333
+ created = row["created_at"]
334
+ new(name: row["name"].to_s, origin: row["origin"], created_at: created.nil? ? nil : created.to_i)
335
+ end
336
+ end
337
+
338
+ # The machine holding a ZFS volume and what it mounts.
339
+ ZfsAttachment = Data.define(:machine, :machine_name, :running, :mounts) do
340
+ # @param row [Hash]
341
+ # @return [ZfsAttachment]
342
+ def self.from_row(row)
343
+ new(
344
+ machine: row["machine"].to_s,
345
+ machine_name: row["machine_name"],
346
+ running: !!row["running"],
347
+ mounts: (row["mounts"] || []).map { |m| ZfsMount.from_row(m) }
348
+ )
349
+ end
350
+ end
351
+
352
+ # A ZFS volume as reported by +bsdkrun zfs ls --json+. +size_bytes+ is the
353
+ # image's nominal size (what the guest sees); +size+ the space actually
354
+ # allocated on the host. +attached_to+ holds the one machine holding it.
355
+ ZfsVolumeInfo = Data.define(:name, :path, :size_bytes, :size, :branches, :attached_to, :created_at) do
356
+ # @param row [Hash]
357
+ # @return [ZfsVolumeInfo]
358
+ def self.from_row(row)
359
+ created = row["created_at"]
360
+ new(
361
+ name: row["name"].to_s,
362
+ path: row["path"].to_s,
363
+ size_bytes: (row["size_bytes"] || 0).to_i,
364
+ size: row["size"],
365
+ branches: (row["branches"] || []).map { |b| ZfsBranch.from_row(b) },
366
+ attached_to: (row["attached_to"] || []).map { |a| ZfsAttachment.from_row(a) },
367
+ created_at: created.nil? ? nil : created.to_i
368
+ )
369
+ end
370
+ end
371
+
318
372
  # A global network as reported by +bsdkrun network ls --json+.
319
373
  NetworkInfo = Data.define(:name, :subnet, :gateway, :members, :running, :up, :created_at) do
320
374
  # @param row [Hash]
@@ -2,5 +2,5 @@
2
2
 
3
3
  module Bsdkrun
4
4
  # The bsdkrun Ruby SDK version.
5
- VERSION = "0.6.0"
5
+ VERSION = "0.7.0"
6
6
  end
@@ -0,0 +1,78 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ module Bsdkrun
6
+ # ZFS volumes: one zpool per volume on a disk image, held by one machine at
7
+ # a time (Linux, FreeBSD, NetBSD). Branches are datasets cloned
8
+ # copy-on-write inside the pool (+zfs snapshot+ + +zfs clone+), so a branch
9
+ # costs nothing until it diverges.
10
+ module Zfs
11
+ module_function
12
+
13
+ # List ZFS volumes, with their branches and holder.
14
+ # @return [Array<ZfsVolumeInfo>]
15
+ def list
16
+ res = Process.run!(["zfs", "ls", "--json"], label: "bsdkrun zfs ls")
17
+ JSON.parse(res.stdout.empty? ? "[]" : res.stdout).map { |row| ZfsVolumeInfo.from_row(row) }
18
+ end
19
+
20
+ # The branches of one volume.
21
+ # @param volume [String]
22
+ # @return [Array<ZfsBranch>]
23
+ def branches(volume)
24
+ res = Process.run!(["zfs", "ls", volume, "--json"], label: "bsdkrun zfs ls")
25
+ JSON.parse(res.stdout.empty? ? "[]" : res.stdout).map { |row| ZfsBranch.from_row(row) }
26
+ end
27
+
28
+ # Create a volume: a sparse image that becomes a zpool with a +main+
29
+ # branch the first time a guest imports it.
30
+ # @param name [String]
31
+ # @param size [String, nil] e.g. "10G" (the default)
32
+ # @return [String] the volume name
33
+ def create(name, size: nil)
34
+ args = ["zfs", "create", name]
35
+ args.push("--size", size) if size
36
+ Process.run!(args, label: "bsdkrun zfs create").stdout.strip
37
+ end
38
+
39
+ # Fork a branch copy-on-write from +from+ (+main+ by default). Runs in the
40
+ # machine holding the volume or in a short-lived FreeBSD helper, so it can
41
+ # take as long as a BSD boot.
42
+ # @return [String] the new +VOL@BRANCH+
43
+ def branch(volume, name, from: nil)
44
+ args = ["zfs", "branch", volume, name]
45
+ args.push("--from", from) if from
46
+ Process.run!(args, label: "bsdkrun zfs branch").stdout.strip
47
+ end
48
+
49
+ # Attach +VOL+ or +VOL@BRANCH+ to a machine at +mount+ (+/mnt/VOL+, or
50
+ # +/mnt/VOL-BRANCH+, by default). A pool is imported by one machine at a
51
+ # time; a stopped machine picks it up on start, a running holder mounts
52
+ # the branch live.
53
+ # @return [String] the CLI's one-line report
54
+ def attach(target, machine, mount: nil)
55
+ args = ["zfs", "attach", target, machine]
56
+ args.push("--mount", mount) if mount
57
+ Process.run!(args, label: "bsdkrun zfs attach").stdout.strip
58
+ end
59
+
60
+ # Detach one branch (+VOL@BRANCH+) or the whole volume (+VOL+).
61
+ # @return [String]
62
+ def detach(target, machine)
63
+ Process.run!(["zfs", "detach", target, machine], label: "bsdkrun zfs detach").stdout.strip
64
+ end
65
+
66
+ # Destroy branches (+VOL@BRANCH+) or whole volumes (+VOL+).
67
+ # @param targets [String, Array<String>]
68
+ # @param force [Boolean] destroy a volume a stopped machine still has attached
69
+ # @return [void]
70
+ def destroy(targets, force: false)
71
+ args = ["zfs", "destroy"]
72
+ args << "--force" if force
73
+ args.concat(Array(targets))
74
+ Process.run!(args, label: "bsdkrun zfs destroy")
75
+ nil
76
+ end
77
+ end
78
+ end
data/lib/bsdkrun.rb CHANGED
@@ -12,6 +12,7 @@ require_relative "bsdkrun/types"
12
12
  require_relative "bsdkrun/sandbox"
13
13
  require_relative "bsdkrun/images"
14
14
  require_relative "bsdkrun/volumes"
15
+ require_relative "bsdkrun/zfs"
15
16
  require_relative "bsdkrun/networks"
16
17
  require_relative "bsdkrun/system"
17
18
  require_relative "bsdkrun/websocket_frame"
@@ -80,6 +81,12 @@ module Bsdkrun
80
81
  Volumes
81
82
  end
82
83
 
84
+ # The {Zfs} namespace.
85
+ # @return [Module]
86
+ def zfs
87
+ Zfs
88
+ end
89
+
83
90
  # The {Networks} namespace.
84
91
  # @return [Module]
85
92
  def networks
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bsdkrun
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tsiry Sandratraina
@@ -67,6 +67,7 @@ files:
67
67
  - lib/bsdkrun/volumes.rb
68
68
  - lib/bsdkrun/websocket_frame.rb
69
69
  - lib/bsdkrun/ws_client.rb
70
+ - lib/bsdkrun/zfs.rb
70
71
  homepage: https://github.com/tsirysndr/bsdkrun
71
72
  licenses:
72
73
  - MIT