bsdkrun 0.5.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: d1b2ffdacfec58cee3714b8ca96ecc133604655d423e264444d8f41ea88393e5
4
- data.tar.gz: 848ec7c03c5489a41daf404135c3bbfdcfb126449ecb712ddf920ea7377bc822
3
+ metadata.gz: 9b75574627d21db63ed83e7f53f408040625b0d640e6f2746c99c14c3d8c64e4
4
+ data.tar.gz: 25f6eb79d3c448b286ddb310e07e25811d0ad2e0529075755c195c852e66a861
5
5
  SHA512:
6
- metadata.gz: a86228909ae198caab0e630bac039179fc115317118f321a1aa193683ee6fb10ccfdc56ae1d05d42cad3ebad712897b5979c0b3b75cd0fe9b64bef0406d1d5ae
7
- data.tar.gz: aef36636aef92124b1c78695648c929bfee4f60e134b9ef0a2d5588693827994e8023f62c91f39cd2d1a19c74e7e1a6a3d99a99c2aca9df51ba53bf03022368e
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/ci.rb ADDED
@@ -0,0 +1,204 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "json"
5
+ require "tmpdir"
6
+
7
+ module Bsdkrun
8
+ # CI workflows defined in code instead of YAML.
9
+ #
10
+ # The builder produces exactly the file +bsdkrun ci+ (and tangled's spindle)
11
+ # consumes — {CIWorkflow#yaml} is that file, {CIWorkflow#save} commits it to
12
+ # +.tangled/workflows/+, and {CIWorkflow#run} executes it in a microVM
13
+ # without a file ever touching the repository:
14
+ #
15
+ # Bsdkrun.workflow("test")
16
+ # .on_push("main")
17
+ # .deps("ruby", "bundler")
18
+ # .env("CI_FROM", "sdk")
19
+ # .step("install", "bundle install")
20
+ # .step("test", "bundle exec rspec")
21
+ # .run
22
+ #
23
+ # Code is the source of truth and YAML the wire format, in that order —
24
+ # which is why +save+ writes a generated-file header: a hand-edit there will
25
+ # be overwritten by the next +save+.
26
+ class CIWorkflow
27
+ def initialize(name)
28
+ @name = name
29
+ @engine = "nixery"
30
+ @when = []
31
+ @deps = {}
32
+ @env = {}
33
+ @steps = []
34
+ @clone_depth = nil
35
+ @clone_skip = false
36
+ end
37
+
38
+ # Override the engine (+nixery+ by default).
39
+ def engine(engine)
40
+ @engine = engine
41
+ self
42
+ end
43
+
44
+ # Add a push trigger for the given branches.
45
+ def on_push(*branches)
46
+ @when << [["push"], branches]
47
+ self
48
+ end
49
+
50
+ # Add a pull_request trigger targeting the given branches.
51
+ def on_pull_request(*branches)
52
+ @when << [["pull_request"], branches]
53
+ self
54
+ end
55
+
56
+ # Add a trigger with explicit events.
57
+ def on(events, *branches)
58
+ @when << [events, branches]
59
+ self
60
+ end
61
+
62
+ # Add nixpkgs dependencies — the toolchain the steps run against.
63
+ def deps(*packages)
64
+ (@deps["nixpkgs"] ||= []).concat(packages)
65
+ self
66
+ end
67
+
68
+ # Add dependencies from a custom registry (a flake reference).
69
+ def deps_from(registry, *packages)
70
+ (@deps[registry] ||= []).concat(packages)
71
+ self
72
+ end
73
+
74
+ # Set a workflow-level environment variable.
75
+ def env(key, value)
76
+ @env[key] = value
77
+ self
78
+ end
79
+
80
+ # Append a step; steps run serially in one VM, from the workspace root.
81
+ def step(name, command, env: nil)
82
+ @steps << { name: name, command: command, env: env || {} }
83
+ self
84
+ end
85
+
86
+ # Set the clone depth (default 1).
87
+ def clone_depth(depth)
88
+ @clone_depth = depth
89
+ self
90
+ end
91
+
92
+ # Skip the checkout entirely.
93
+ def skip_clone
94
+ @clone_skip = true
95
+ self
96
+ end
97
+
98
+ # The workflow file name {#save} writes: +<name>.yml+.
99
+ def file_name
100
+ @name.match?(/\.ya?ml\z/) ? @name : "#{@name}.yml"
101
+ end
102
+
103
+ # Render the workflow file. Scalars are emitted as JSON strings — valid
104
+ # YAML by construction — and commands as literal blocks when safe, so the
105
+ # SDK needs no YAML dependency.
106
+ def yaml
107
+ out = []
108
+ q = ->(s) { JSON.generate(s) }
109
+
110
+ unless @when.empty?
111
+ out << "when:"
112
+ @when.each do |events, branches|
113
+ out << " - event: [#{events.map(&q).join(', ')}]"
114
+ if branches.length == 1
115
+ out << " branch: #{q.call(branches[0])}"
116
+ elsif branches.length > 1
117
+ out << " branch: [#{branches.map(&q).join(', ')}]"
118
+ end
119
+ end
120
+ out << ""
121
+ end
122
+
123
+ out << "engine: #{@engine}"
124
+
125
+ unless @deps.empty?
126
+ out << "" << "dependencies:"
127
+ @deps.keys.sort.each do |reg|
128
+ out << " #{q.call(reg)}:"
129
+ @deps[reg].each { |p| out << " - #{q.call(p)}" }
130
+ end
131
+ end
132
+
133
+ unless @env.empty?
134
+ out << "" << "environment:"
135
+ @env.keys.sort.each { |k| out << " #{k}: #{q.call(@env[k])}" }
136
+ end
137
+
138
+ if @clone_skip || @clone_depth
139
+ out << "" << "clone:"
140
+ out << " skip: true" if @clone_skip
141
+ out << " depth: #{@clone_depth}" if @clone_depth
142
+ end
143
+
144
+ out << "" << "steps:"
145
+ @steps.each do |s|
146
+ out << " - name: #{q.call(s[:name])}"
147
+ # Literal blocks read well in a committed file, but cannot carry
148
+ # trailing spaces or carriage returns byte-for-byte; fall back to a
149
+ # JSON string rather than silently altering the command.
150
+ block_safe = !s[:command].empty? &&
151
+ !s[:command].include?("\r") &&
152
+ s[:command].split("\n", -1).all? { |l| l == l.sub(/ +\z/, "") }
153
+ if block_safe
154
+ out << " command: |"
155
+ s[:command].sub(/\n+\z/, "").split("\n", -1).each { |l| out << " #{l}" }
156
+ else
157
+ out << " command: #{q.call(s[:command])}"
158
+ end
159
+ next if s[:env].empty?
160
+
161
+ out << " environment:"
162
+ s[:env].keys.sort.each { |k| out << " #{k}: #{q.call(s[:env][k])}" }
163
+ end
164
+ "#{out.join("\n")}\n"
165
+ end
166
+
167
+ # Write into +<repo>/.tangled/workflows/+ and return the path.
168
+ def save(repo)
169
+ dir = File.join(repo, ".tangled", "workflows")
170
+ FileUtils.mkdir_p(dir)
171
+ path = File.join(dir, file_name)
172
+ File.write(
173
+ path,
174
+ "# Generated by the bsdkrun SDK — edit the code that save()d it instead.\n#{yaml}"
175
+ )
176
+ path
177
+ end
178
+
179
+ # Execute the workflow in a microVM, streaming output. The YAML never
180
+ # touches the repository — it goes to a temp file and +bsdkrun ci run -f+.
181
+ # Raises {CommandFailed} when a step fails.
182
+ def run(dir: nil)
183
+ Dir.mktmpdir("bsdkrun-ci-") do |tmp|
184
+ file = File.join(tmp, file_name)
185
+ File.write(file, yaml)
186
+ args = ["ci", "run", "-f", file]
187
+ args += ["-w", dir] if dir
188
+ ok = Process.spawn_interactive(args)
189
+ unless ok
190
+ raise CommandFailed.new(
191
+ exit_code: 1, stdout: "", stderr: "workflow #{@name} failed",
192
+ command: "bsdkrun ci run"
193
+ )
194
+ end
195
+ end
196
+ nil
197
+ end
198
+ end
199
+
200
+ # Start a CI workflow definition.
201
+ def self.workflow(name)
202
+ CIWorkflow.new(name)
203
+ end
204
+ end
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.5.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
@@ -6,11 +6,13 @@ require_relative "bsdkrun/binary"
6
6
  require_relative "bsdkrun/process"
7
7
  require_relative "bsdkrun/args"
8
8
  require_relative "bsdkrun/cache"
9
+ require_relative "bsdkrun/ci"
9
10
  require_relative "bsdkrun/filesystem"
10
11
  require_relative "bsdkrun/types"
11
12
  require_relative "bsdkrun/sandbox"
12
13
  require_relative "bsdkrun/images"
13
14
  require_relative "bsdkrun/volumes"
15
+ require_relative "bsdkrun/zfs"
14
16
  require_relative "bsdkrun/networks"
15
17
  require_relative "bsdkrun/system"
16
18
  require_relative "bsdkrun/websocket_frame"
@@ -79,6 +81,12 @@ module Bsdkrun
79
81
  Volumes
80
82
  end
81
83
 
84
+ # The {Zfs} namespace.
85
+ # @return [Module]
86
+ def zfs
87
+ Zfs
88
+ end
89
+
82
90
  # The {Networks} namespace.
83
91
  # @return [Module]
84
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.5.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tsiry Sandratraina
@@ -52,6 +52,7 @@ files:
52
52
  - lib/bsdkrun/args.rb
53
53
  - lib/bsdkrun/binary.rb
54
54
  - lib/bsdkrun/cache.rb
55
+ - lib/bsdkrun/ci.rb
55
56
  - lib/bsdkrun/client.rb
56
57
  - lib/bsdkrun/errors.rb
57
58
  - lib/bsdkrun/filesystem.rb
@@ -66,6 +67,7 @@ files:
66
67
  - lib/bsdkrun/volumes.rb
67
68
  - lib/bsdkrun/websocket_frame.rb
68
69
  - lib/bsdkrun/ws_client.rb
70
+ - lib/bsdkrun/zfs.rb
69
71
  homepage: https://github.com/tsirysndr/bsdkrun
70
72
  licenses:
71
73
  - MIT