empeira 0.1.0.pre.alpha.1

data/lib/empeira/vm/cloud_init.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+
+module Empeira
+  module VM
+    # Private NoCloud material is removed after initial guest configuration.
+    # rubocop:disable-next Metrics/ClassLength -- Seed, key and bootstrap material are one guest boundary.
+    class CloudInit
+      USER = 'empeira'
+
+      def initialize(context:, runner:, executable_path: ENV.fetch('PATH', ''))
+        @context = context
+        @runner = runner
+        @executable_path = executable_path
+      end
+
+      def prepare(record)
+        Management.validate!(record)
+        directory = node_directory(record.fetch('hostname'))
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        credentials = Node::SSHCredentials.new(context: @context, runner: @runner, provider: 'vm',
+                                               hostname: record.fetch('hostname'))
+        credentials.prepare
+        key = credentials.key_path
+        files = seed_files(directory, record, File.read("#{key}.pub").strip)
+        create_iso(directory, files)
+      end
+
+      def finish(record, guest:)
+        directory = node_directory(record.fetch('hostname'))
+        files = seed_files(directory, record, File.read("#{key_path(record.fetch('hostname'))}.pub").strip,
+                           console: false)
+        create_iso(directory, files)
+        paths = %w[user-data.txt user-data.txt.i cloud-config.txt obj.pkl].map do |name|
+          "/var/lib/cloud/instance/#{name}"
+        end
+        result = guest.run(record, ['rm', '-f', *paths])
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: 'Guest cloud-init credential cleanup', tool: 'rm')
+        raise Error, "Cannot remove temporary guest cloud-init credentials\n#{details}", cause: nil
+      end
+
+      def key_path(hostname)
+        node_directory(hostname).join('id_ed25519')
+      end
+
+      def validate!
+        bootstrap_files
+      end
+
+      private
+
+      def create_iso(directory, files)
+        output = directory.join('seed.iso')
+        tool = locate('xorriso') || raise(UnavailableFeature, 'xorriso is required for VM cloud-init seeds')
+        Tempfile.create(['seed-', '.iso'], directory) do |temporary|
+          result = @runner.run(tool, arguments: ['-as', 'mkisofs', '-quiet', '-volid', 'cidata',
+                                                 '-output', temporary.path, *files.map(&:to_s)], timeout: 30)
+          raise Error, 'Cannot create VM cloud-init seed' unless result.success?
+
+          File.chmod(0o600, temporary.path)
+          File.rename(temporary.path, output)
+        end
+        output
+      ensure
+        files&.each { |path| FileUtils.rm_f(path) }
+      end
+
+      def seed_files(directory, record, public_key, console: true)
+        data = cloud_config(record, public_key, console: console)
+        metadata = { 'instance-id' => "#{@context.workspace.id}-#{record.fetch('hostname')}",
+                     'local-hostname' => record.fetch('hostname') }
+        network = network_config(record)
+        { 'user-data' => "#cloud-config\n#{YAML.dump(data)}", 'meta-data' => YAML.dump(metadata),
+          'network-config' => YAML.dump(network) }.map do |name, content|
+          path = directory.join(name)
+          File.write(path, content, mode: 'w', perm: 0o600)
+          File.chmod(0o600, path)
+          path
+        end
+      end
+
+      def network_config(record)
+        { 'version' => 2, 'ethernets' => {
+          'peer' => { 'match' => { 'macaddress' => record.fetch('mac_address') }, 'set-name' => 'eth0',
+                      'addresses' => ["#{record.fetch('peer').fetch('ip')}/24"], 'dhcp4' => false, 'dhcp6' => false,
+                      'routes' => [{ 'to' => '0.0.0.0/0', 'via' => record.fetch('peer').fetch('gateway') }],
+                      'link-local' => [], 'nameservers' => { 'addresses' => [record.fetch('peer').fetch('dns')] } }
+        } }
+      end
+
+      def cloud_config(record, public_key, console: true)
+        scripts = bootstrap_files
+        { 'hostname' => record.fetch('hostname'), 'prefer_fqdn_over_hostname' => true,
+          'fqdn' => record.fetch('hostname'), 'manage_etc_hosts' => true,
+          'users' => [system_user],
+          'ssh_pwauth' => false, 'disable_root' => true,
+          'write_files' => cloud_files(scripts) + management_files(record, public_key),
+          'runcmd' => cloud_commands(scripts),
+          **(console ? console_password : {}) }
+      end
+
+      def console_password
+        password = @context.configuration.dig('vm', 'console', 'root_password')
+        return {} unless password
+
+        { 'chpasswd' => { 'expire' => false,
+                          'users' => [{ 'name' => 'root', 'password' => password, 'type' => 'text' }] } }
+      end
+
+      def cloud_files(scripts)
+        Node::Bootstrap.new(provider: 'vm').files.map do |file|
+          { 'path' => file.path, 'permissions' => format('%04o', file.mode), 'content' => file.content }
+        end + [{ 'path' => '/etc/cloud/cloud.cfg.d/99-empeira-hostname.cfg', 'permissions' => '0644',
+                 'content' => "preserve_hostname: true\n" },
+               { 'path' => '/etc/sysctl.d/90-empeira-ipv4.conf', 'permissions' => '0644',
+                 'content' => "net.ipv6.conf.all.disable_ipv6=1\nnet.ipv6.conf.default.disable_ipv6=1\n" }] + scripts
+      end
+
+      def cloud_commands(scripts)
+        management = [[Management::SETUP]]
+        [['sysctl', '--system'], *management, *scripts.map { |entry| [entry.fetch('path')] }]
+      end
+
+      def system_user
+        { 'name' => USER, 'system' => true, 'homedir' => '/var/lib/empeira',
+          'lock_passwd' => true, 'shell' => '/bin/bash' }
+      end
+
+      def management_files(record, public_key)
+        Management.files(record, system_key: public_key)
+      end
+
+      def bootstrap_files
+        config = @context.configuration.fetch('bootstrap')
+        return [] unless config.fetch('enabled')
+
+        config.fetch('scripts').each_with_index.map { |relative, index| bootstrap_entry(relative, index) }
+      end
+
+      def bootstrap_entry(relative, index)
+        source = @context.project.path.join(relative).realpath
+        unless source.file? && source.to_s.start_with?("#{@context.project.path}/") && source.size <= 1_000_000
+          raise ConfigurationError, "bootstrap.scripts.#{index} must be a project-local file below 1 MB"
+        end
+
+        content = File.read(source, encoding: 'UTF-8')
+        raise ConfigurationError, "bootstrap.scripts.#{index} must be UTF-8" unless content.valid_encoding?
+
+        { 'path' => "/usr/local/libexec/empeira-bootstrap-#{index}", 'permissions' => '0700',
+          'content' => content }
+      rescue SystemCallError
+        raise ConfigurationError, "bootstrap.scripts.#{index} must resolve to a project-local file", cause: nil
+      end
+
+      def node_directory(hostname)
+        @context.locations.workspace(@context.workspace).join('vms', hostname)
+      end
+
+      def locate(name)
+        @executable_path.split(File::PATH_SEPARATOR).filter_map do |directory|
+          path = Pathname(directory).join(name)
+          path.to_s if path.file? && path.executable?
+        end.first
+      end
+    end
+  end
+end

data/lib/empeira/vm/disk.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'tempfile'
+
+module Empeira
+  module VM
+    # One writable QCOW2 overlay per node; the shared base remains read-only.
+    class Disk
+      GIB = 1024**3
+
+      def initialize(engine:, runner:, workspace_directory:)
+        @engine = engine
+        @runner = runner
+        @workspace_directory = workspace_directory
+      end
+
+      def create(hostname:, base:, size_gib:)
+        require_base!(base)
+        verify_capacity!(base, size_gib)
+        directory = node_directory(hostname)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        overlay = directory.join('disk.qcow2')
+        raise Providers::AlreadyExists, 'VM overlay already exists' if overlay.exist? || overlay.symlink?
+
+        Tempfile.create(['disk-', '.qcow2'], directory) do |temporary|
+          staging = Pathname(temporary.path)
+          prepare_overlay!(base, staging, size_gib)
+          File.link(staging, overlay)
+        end
+        overlay
+      end
+
+      def verify!(hostname:, base:)
+        overlay = node_directory(hostname).join('disk.qcow2')
+        raise Error, 'VM overlay is missing or unsafe' unless overlay.file? && !overlay.symlink?
+
+        verify_backing!(overlay_metadata(overlay), base)
+        overlay
+      end
+
+      def remove(hostname:, base:)
+        overlay = verify!(hostname: hostname, base: base)
+        File.unlink(overlay)
+        overlay
+      end
+
+      private
+
+      def prepare_overlay!(base, overlay, size_gib)
+        create_overlay!(base, overlay)
+        resize_overlay!(overlay, size_gib)
+        data = overlay_metadata(overlay)
+        verify_backing!(data, base)
+        raise Error, 'VM overlay capacity differs from vm.disk' unless data['virtual-size'] == size_gib * GIB
+      end
+
+      def verify_backing!(data, base)
+        return if data['format'] == 'qcow2' && data['backing-filename'] == base.to_s &&
+                  data['backing-filename-format'] == 'qcow2'
+
+        raise Providers::OwnershipError, 'VM overlay backing image differs from recorded base'
+      end
+
+      def verify_capacity!(base, size_gib)
+        raise ConfigurationError, 'vm.disk must be an integer from 1 to 2048 GiB' unless
+          size_gib.is_a?(Integer) && (1..2048).cover?(size_gib)
+
+        capacity = verify_base!(base).fetch('virtual-size', nil)
+        raise Error, 'VM base image virtual capacity is missing or invalid' unless
+          capacity.is_a?(Integer) && capacity.positive?
+        return if size_gib * GIB >= capacity
+
+        raise ConfigurationError, "vm.disk (#{size_gib} GiB) is smaller than the base image (#{capacity} bytes)"
+      end
+
+      def require_base!(base)
+        raise Error, 'Verified VM base image is missing' unless base.file? && !base.symlink?
+      end
+
+      def verify_base!(base)
+        result = @runner.run(@engine.image_tool, arguments: ['info', '--output=json', base.to_s], timeout: 10)
+        verify_result!(result, 'Cannot inspect verified VM base image')
+
+        metadata = JSON.parse(result.stdout)
+        return metadata if metadata.is_a?(Hash) && metadata['format'] == 'qcow2' && !metadata.key?('backing-filename')
+
+        raise Error, 'VM base image must be a standalone QCOW2 image'
+      rescue JSON::ParserError
+        raise Error, 'Malformed QEMU base-image metadata', cause: nil
+      end
+
+      def create_overlay!(base, overlay)
+        result = @runner.run(@engine.image_tool, arguments: ['create', '-f', 'qcow2', '-F', 'qcow2',
+                                                             '-b', base.to_s, overlay.to_s], timeout: 30)
+        verify_result!(result, 'QEMU overlay creation failed')
+
+        File.chmod(0o600, overlay)
+      end
+
+      def resize_overlay!(overlay, size_gib)
+        result = @runner.run(@engine.image_tool,
+                             arguments: ['resize', '--preallocation=off', '-f', 'qcow2', overlay.to_s, "#{size_gib}G"],
+                             timeout: 30)
+        verify_result!(result, 'QEMU overlay sizing failed for vm.disk')
+      end
+
+      def verify_result!(result, operation)
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: operation, tool: 'qemu-img')
+        raise Error, "#{operation}\n#{details}", cause: nil
+      end
+
+      def overlay_metadata(overlay)
+        result = @runner.run(@engine.image_tool, arguments: ['info', '--output=json', overlay.to_s], timeout: 10)
+        verify_result!(result, 'Cannot inspect VM overlay')
+
+        data = JSON.parse(result.stdout)
+        raise Error, 'Malformed QEMU overlay metadata' unless data.is_a?(Hash)
+
+        data
+      rescue JSON::ParserError
+        raise Error, 'Malformed QEMU overlay metadata', cause: nil
+      end
+
+      def node_directory(hostname)
+        raise Error, 'Invalid VM hostname' unless Node::Inventory.valid_name?(hostname) &&
+                                                  hostname == hostname.downcase
+
+        @workspace_directory.join('vms', hostname)
+      end
+    end
+  end
+end

data/lib/empeira/vm/guest.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Shared guest execution/upload/readiness API; no host or guest SSH credentials.
+    class Guest
+      class TransportError < Error
+        attr_reader :timed_out
+
+        def initialize(message, transient: false, timed_out: false)
+          @timed_out = timed_out
+          @transient = transient
+          super(message)
+        end
+
+        def transient? = @transient
+
+        def with_context(message)
+          self.class.new("#{message}\n#{self.message}", transient: transient?, timed_out: timed_out)
+        end
+      end
+
+      def initialize(context:, runner:, qemu:)
+        @context = context
+        @runner = runner
+        @qemu = qemu
+      end
+
+      def run(record, arguments, timeout: 30)
+        execute(record, arguments, timeout: timeout)
+      end
+
+      def stream(record, arguments, timeout: 3600, output: $stdout, error: $stderr)
+        execute(record, arguments, timeout: timeout, output: output, error: error)
+      end
+
+      def shell(record, input: $stdin, output: $stdout)
+        raise Error, 'Node shell requires a local terminal' unless input.tty? && output.tty?
+
+        transfer(record) { |channel| GuestShell.new(input: input, output: output).consume(channel) }
+      end
+
+      def copy_to(record, source, destination, mode: '0644')
+        File.open(source, 'rb') do |file|
+          transfer(record) { |channel| GuestUpload.new(channel).write(file, destination, mode: mode) }
+        end
+      end
+
+      # rubocop:disable-next Metrics/MethodLength -- Readiness alone retries harmless status probes before bootstrap.
+      def wait(record, progress: nil, seconds: 300)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        loop do
+          begin
+            result = run(record, ['cloud-init', 'status', '--wait', '--long'], timeout: 20)
+            return if result.success?
+
+            details = Execution::Diagnostics.command(result, operation: 'VM cloud-init readiness',
+                                                             tool: 'VirtIO management')
+          rescue TransportError => e
+            details = e.message
+          end
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise Error,
+                  "VM management or cloud-init did not become ready; inspect node shell and serial log\n#{details}"
+          end
+
+          progress&.heartbeat('Waiting for VM management and cloud-init...')
+          sleep 2
+        end
+      end
+
+      private
+
+      def execute(record, arguments, timeout:, output: nil, error: nil)
+        validate_command!(arguments, timeout)
+
+        transfer(record) do |channel|
+          channel.send_frame('type' => 'exec', 'argv' => arguments, 'timeout' => timeout)
+          GuestOutput.new(output: output, error: error).consume(channel, timeout: timeout && (timeout + 5))
+        end
+      end
+
+      def validate_command!(arguments, timeout)
+        unless arguments.is_a?(Array) && !arguments.empty? && arguments.all? do |arg|
+          arg.is_a?(String) && !arg.include?("\0")
+        end
+          raise ExecutionError, 'Guest command arguments must be nonempty strings without null bytes'
+        end
+
+        validate_timeout!(timeout)
+      end
+
+      def validate_timeout!(timeout)
+        return if timeout.nil?
+
+        return if timeout.is_a?(Numeric) && timeout.finite? && timeout.positive? && timeout <= 86_400
+
+        raise ExecutionError, 'Guest timeout must be positive and at most one day'
+      end
+
+      # rubocop:disable-next Metrics/MethodLength -- Completion and cancellation must share the same ensure boundary.
+      def transfer(record)
+        Management.validate!(record)
+        GuestChannel.new(record: record, qemu: @qemu).open do |channel|
+          completed = false
+          begin
+            value = yield channel
+            completed = true
+            value
+          ensure
+            channel.cancel unless completed
+          end
+        end
+      rescue SystemCallError, IOError, Timeout::Error => e
+        raise TransportError.new("VM VirtIO management transport failed (#{e.class.name}); " \
+                                 'guest completion is unknown; ' \
+                                 'VM retained. Inspect node shell, serial log and the management service journal.',
+                                 transient: e.is_a?(Errno::ENOENT) || e.is_a?(Errno::ECONNREFUSED),
+                                 timed_out: e.is_a?(Timeout::Error)), cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/vm/guest_channel.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'securerandom'
+require 'io/wait'
+
+module Empeira
+  module VM
+    # One private, instance-bound VirtIO-Serial session; never logs protocol payloads.
+    class GuestChannel
+      LIMIT = 131_072
+      CHUNK = 16_384
+
+      def initialize(record:, qemu:)
+        @record = record
+        @qemu = qemu
+        @id = SecureRandom.hex(16)
+        @buffer = +''.b
+      end
+
+      def open
+        @qemu.with_management_socket(@record) do |path, expected|
+          connect(path, expected) { yield self }
+        end
+      end
+
+      def connect(path, expected)
+        original = path.lstat
+        @socket = UNIXSocket.new(path)
+        current = path.lstat
+        unless [original.dev, original.ino] == [current.dev, current.ino] &&
+               expected == { 'device' => current.dev, 'inode' => current.ino }
+          raise Providers::OwnershipError, 'VM management socket changed while connecting'
+        end
+
+        handshake!
+
+        yield self
+      ensure
+        @socket&.close
+      end
+
+      def readable?
+        @buffer.include?("\n")
+      end
+
+      def io
+        @socket
+      end
+
+      def handshake!
+        send_frame('type' => 'hello', 'token' => @record.fetch('peer').fetch('token'))
+        response = receive(timeout: 5)
+        unless response['type'] == 'hello' && response['version'] == Management::VERSION &&
+               response['token'] == @record.fetch('peer').fetch('token')
+          raise Providers::OwnershipError, 'VM management identity mismatch; operation refused'
+        end
+      end
+
+      def send_frame(frame)
+        message = "#{JSON.generate(frame.merge('id' => @id))}\n"
+        raise Error, 'VM management request is too large' if message.bytesize > LIMIT
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+        until message.empty?
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Timeout::Error if remaining <= 0 || !@socket.wait_writable(remaining)
+
+          written = @socket.write_nonblock(message, exception: false)
+          message = message.byteslice(written..) unless written == :wait_writable
+        end
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- Frame size, deadline and session identity are checked together.
+      def receive(timeout:)
+        deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+        until @buffer.include?("\n")
+          remaining = deadline && (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          raise Timeout::Error if (remaining && remaining <= 0) || !@socket.wait_readable(remaining)
+
+          @buffer << @socket.readpartial(CHUNK)
+          raise Error, 'VM management response is oversized' if @buffer.bytesize > LIMIT
+        end
+        line, @buffer = @buffer.split("\n", 2)
+        result = JSON.parse(line)
+        unless result.is_a?(Hash) && result['id'] == @id
+          raise Providers::OwnershipError, 'VM management response belongs to another operation'
+        end
+
+        result
+      rescue JSON::ParserError
+        raise Error, 'VM management returned malformed protocol data', cause: nil
+      end
+
+      def cancel
+        send_frame('type' => 'cancel')
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 3
+        loop do
+          frame = receive(timeout: deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          next unless frame['type'] == 'exit'
+
+          GuestOutput.new.consume_completion(frame)
+          break
+        end
+      rescue StandardError
+        raise Guest::TransportError, 'VM guest session cancellation is unconfirmed; node retained', cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/vm/guest_network.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Empeira
+  module VM
+    # All observations and mutations use the existing guest management transport.
+    class GuestNetwork
+      attr_reader :links, :addresses, :routes
+
+      def initialize(guest:, record:)
+        @guest = guest
+        @record = record
+      end
+
+      def refresh
+        @links = read(%w[ip -j -d link show]).to_h { |link| [link.fetch('ifname'), link] }
+        @addresses = read(%w[ip -j address show]).to_h { |link| [link.fetch('ifname'), link.fetch('addr_info')] }
+        @routes = read(%w[ip -j -4 route show table all])
+        self
+      rescue KeyError, TypeError
+        raise Error, "Host #{@record.fetch('hostname')}, vm.interfaces: incomplete guest network observation",
+              cause: nil
+      end
+
+      def load_modules(vlan:)
+        # Prevent module autoload from creating an unowned default dummy0.
+        command(%w[modprobe dummy numdummies=0]) unless @guest.run(@record, %w[test -d /sys/module/dummy]).success?
+        command(%w[modprobe 8021q]) if vlan && !@guest.run(@record, %w[test -d /sys/module/8021q]).success?
+      end
+
+      def command(arguments)
+        result = @guest.run(@record, arguments)
+        return result if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: operation(arguments), tool: arguments.first)
+        raise Error, "Cannot reconcile VM interfaces; guest operation failed\n#{details}", cause: nil
+      rescue Guest::TransportError => e
+        raise e.with_context(operation(arguments)), cause: nil
+      end
+
+      def operation(arguments)
+        position = arguments.index('dev') || arguments.index('name')
+        interface = position ? ", interface #{arguments[position + 1]}" : ''
+        "Host #{@record.fetch('hostname')}#{interface}, vm.interfaces: #{arguments.first}"
+      end
+
+      def read(arguments)
+        value = JSON.parse(command(arguments).stdout)
+        return value if value.is_a?(Array) && value.all?(Hash)
+
+        raise TypeError
+      rescue JSON::ParserError, TypeError
+        raise Error, "Host #{@record.fetch('hostname')}, vm.interfaces: cannot verify guest #{arguments.first} JSON",
+              cause: nil
+      end
+
+      def ipv4(name)
+        addresses.fetch(name, []).select { |address| address['family'] == 'inet' }
+      end
+
+      def parent_name(link)
+        return link['link'] if link['link'].is_a?(String)
+        return unless link['link_index'].is_a?(Integer)
+
+        links.values.find { |candidate| candidate['ifindex'] == link['link_index'] }&.fetch('ifname')
+      end
+
+      def defaults
+        routes.select { |route| %w[default 0.0.0.0/0].include?(route['dst']) }
+      end
+
+      def verify_facter!(desired)
+        result = command(['/opt/puppetlabs/bin/facter', 'networking', '--json'])
+        facts = JSON.parse(result.stdout).fetch('networking').fetch('interfaces')
+        desired.each do |name, definition|
+          binding = facts.dig(name, 'bindings')&.first
+          next if correct_binding?(binding, definition.fetch('network'))
+
+          raise Error, "Host #{@record.fetch('hostname')}, interface #{name}, vm.interfaces: " \
+                       'regular Facter networking.interfaces bindings do not match; Puppet was not run'
+        end
+      rescue JSON::ParserError, KeyError, TypeError, NoMethodError
+        raise Error, "Host #{@record.fetch('hostname')}, vm.interfaces: cannot verify regular Facter networking JSON",
+              cause: nil
+      end
+
+      def correct_binding?(binding, network)
+        binding.is_a?(Hash) && binding['address'] == network.split('/').first &&
+          binding['netmask'] == IPAddr.new(network).netmask.to_s
+      end
+    end
+  end
+end

data/lib/empeira/vm/guest_output.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Frame output is drained without truncation; streaming sinks receive it before completion.
+    class GuestOutput
+      def initialize(output: nil, error: nil)
+        @stdout = +''.b
+        @stderr = +''.b
+        @output = output || @stdout
+        @error = error || @stderr
+      end
+
+      def consume(channel, timeout:)
+        deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+        loop do
+          frame = channel.receive(timeout: deadline && (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)))
+          case frame['type']
+          when 'started' then next
+          when 'stdout', 'stderr' then emit(frame)
+          when 'exit' then return completion(frame)
+          else raise Error, 'VM management returned an unexpected protocol message'
+          end
+        end
+      rescue ArgumentError, KeyError
+        raise Error, 'VM management returned malformed output data', cause: nil
+      end
+
+      def consume_completion(frame)
+        completion(frame)
+      end
+
+      private
+
+      def emit(frame)
+        sink = frame['type'] == 'stdout' ? @output : @error
+        sink << Base64.strict_decode64(frame.fetch('data'))
+        sink.flush if sink.respond_to?(:flush)
+      end
+
+      def completion(frame)
+        status, timed_out = frame.values_at('status', 'timed_out')
+        unless [true, false].include?(timed_out) &&
+               ((status.is_a?(Integer) && status.between?(0, 255)) || (status.nil? && timed_out))
+          raise Error, 'VM management returned invalid guest completion status'
+        end
+
+        Execution::Result.new(stdout: @stdout, stderr: @stderr, exit_status: status, timed_out: timed_out)
+      end
+    end
+  end
+end