empeira 0.1.0.pre.alpha.1

data/lib/empeira/vm/guest_shell.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # A guest controlling PTY with local raw-mode restoration; no login or input logging.
+    class GuestShell
+      def initialize(input:, output:)
+        @input = input
+        @output = output
+      end
+
+      def consume(channel)
+        raise Error, 'Node shell requires a local input and output terminal' unless @input.tty? && @output.tty?
+
+        @channel = channel
+        previous = Signal.trap('WINCH') { @resized = true } if Thread.current == Thread.main
+        channel.send_frame('type' => 'shell', 'size' => @input.winsize, 'term' => ENV.fetch('TERM', 'xterm'))
+        Execution::Terminal.with_interrupts { @input.raw { exchange } }
+      ensure
+        Signal.trap('WINCH', previous) if previous
+      end
+
+      private
+
+      def exchange
+        @keyboard = @input
+        loop do
+          resize
+          sources = readable_sources
+          if sources.include?(@channel.io) || @channel.readable?
+            result = consume_frame
+            return result if result
+
+            next
+          end
+          forward_input if @keyboard && sources.include?(@keyboard)
+        end
+      end
+
+      def resize
+        return unless @resized
+
+        @channel.send_frame('type' => 'resize', 'size' => @input.winsize)
+        @resized = false
+      end
+
+      def readable_sources
+        keyboard = @credit ? @keyboard : nil
+        IO.select([@channel.io, keyboard].compact, nil, nil, @channel.readable? ? 0 : 0.1)&.first || []
+      end
+
+      def forward_input
+        bytes = @keyboard.read_nonblock(GuestChannel::CHUNK, exception: false)
+        return if bytes == :wait_readable
+
+        @channel.send_frame('type' => bytes ? 'input' : 'eof', 'data' => Base64.strict_encode64(bytes || ''))
+        @credit = false
+        @keyboard = nil unless bytes
+      end
+
+      def consume_frame
+        frame = @channel.receive(timeout: 5)
+        case frame['type']
+        when 'started' then nil
+        when 'ready'
+          @credit = true
+          nil
+        when 'stdout'
+          @output.write(Base64.strict_decode64(frame.fetch('data')))
+          @output.flush
+          nil
+        when 'exit'
+          GuestOutput.new.consume_completion(frame)
+        else raise Error, 'VM shell returned an unexpected protocol message'
+        end
+      end
+    end
+  end
+end

data/lib/empeira/vm/guest_upload.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Integrity-pinned binary uploads are atomically published by the guest adapter.
+    class GuestUpload
+      def initialize(channel)
+        @channel = channel
+      end
+
+      def write(file, destination, mode:)
+        @channel.send_frame('type' => 'upload')
+        ready!
+        digest = write_chunks(file)
+        @channel.send_frame('type' => 'install', 'destination' => destination, 'mode' => mode,
+                            'sha256' => digest.hexdigest)
+        result = GuestOutput.new.consume(@channel, timeout: 35)
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: 'VM upload', tool: 'VirtIO management')
+        raise Error, "VM upload failed; staging cleaned up, VM retained\n#{details}", cause: nil
+      end
+
+      private
+
+      def write_chunks(file)
+        digest = OpenSSL::Digest.new('SHA256')
+        while (chunk = file.read(GuestChannel::CHUNK))
+          digest.update(chunk)
+          @channel.send_frame('type' => 'chunk', 'data' => Base64.strict_encode64(chunk))
+          ready!
+        end
+        digest
+      end
+
+      def ready!
+        return if @channel.receive(timeout: 30)['type'] == 'ready'
+
+        raise Error, 'VM upload protocol did not acknowledge staging'
+      end
+    end
+  end
+end

data/lib/empeira/vm/image_cache.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'net/http'
+require 'openssl'
+require 'tempfile'
+require 'uri'
+
+module Empeira
+  module VM
+    # Base images are immutable and addressed by all source and checksum fields.
+    class ImageCache
+      def initialize(locations:, downloader: nil)
+        @locations = locations
+        @downloader = downloader || method(:download)
+      end
+
+      def fetch(image)
+        directory = @locations.image(image.identity)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        destination = directory.join('base.qcow2')
+        return destination if verified?(destination, image.identity.checksum)
+
+        cache_image(image, directory, destination)
+        destination
+      rescue SystemCallError, IOError => e
+        raise Error, "Cannot cache the verified VM image (#{e.class.name})", cause: nil
+      end
+
+      private
+
+      def cache_image(image, directory, destination)
+        Tempfile.create(['vm-image-', '.part'], directory) do |temporary|
+          temporary.binmode
+          @downloader.call(image.url, temporary)
+          temporary.flush
+          temporary.fsync
+          raise Error, 'Downloaded VM image failed SHA-256 verification' unless
+            verified?(temporary.path, image.identity.checksum)
+
+          temporary.chmod(0o444)
+          File.rename(temporary.path, destination)
+        end
+      end
+
+      def verified?(path, checksum)
+        File.file?(path) && !File.symlink?(path) && OpenSSL::Digest::SHA256.file(path).hexdigest == checksum
+      end
+
+      def download(url, file)
+        received = nil
+        uri = URI(url)
+        raise Error, 'VM image source must use HTTPS' unless uri.is_a?(URI::HTTPS)
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 60) do |http|
+          http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
+            received = response
+            validate_response!(response, url)
+            response.read_body { |chunk| file.write(chunk) }
+          end
+        end
+      rescue SocketError, OpenSSL::SSL::SSLError, IOError, SystemCallError, Timeout::Error, Net::ProtocolError => e
+        diagnostic = Execution::Diagnostics.transport(operation: 'Download VM base image', url: url, error: e,
+                                                      response: received)
+        raise Error, "VM image download failed\n#{diagnostic}", cause: nil
+      end
+
+      def validate_response!(response, url)
+        return if response.is_a?(Net::HTTPSuccess)
+
+        diagnostic = Execution::Diagnostics.http_response(response, operation: 'Download VM base image', url: url)
+        raise Error, "VM image download failed\n#{diagnostic}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/vm/image_source.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Empeira
+  module VM
+    # Resolve moving upstream aliases to a content-addressed image before downloading.
+    class ImageSource
+      Image = Data.define(:identity, :url, :filename)
+      UBUNTU = { '22.04' => 'jammy', '24.04' => 'noble' }.freeze
+      ARCHITECTURES = { 'amd64' => 'x86_64', 'arm64' => 'aarch64' }.freeze
+
+      def initialize(fetch_text: nil)
+        @fetch_text = fetch_text || method(:read_text)
+      end
+
+      def resolve(distribution:, version:, architecture:)
+        arch = architecture.to_s
+        raise UnavailableFeature, 'VM image architecture must be amd64 or arm64' unless ARCHITECTURES.key?(arch)
+
+        url, manifest = case distribution
+                        when 'ubuntu' then ubuntu(version, arch)
+                        when 'rocky' then rocky(version, arch)
+                        else raise UnavailableFeature, "No verified VM image source for #{distribution} #{version}"
+                        end
+        filename = URI(url).path.split('/').last
+        checksum = checksum_for(@fetch_text.call(manifest), filename)
+        identity = Images::Identity.new(distribution: distribution, version: version, architecture: arch,
+                                        source: url, revision: checksum, checksum: checksum)
+        Image.new(identity: identity, url: url, filename: filename)
+      end
+
+      private
+
+      def ubuntu(version, arch)
+        codename = UBUNTU[version]
+        raise UnavailableFeature, "Ubuntu #{version} VM image is not supported" unless codename
+
+        base = "https://cloud-images.ubuntu.com/releases/#{codename}/release"
+        ["#{base}/ubuntu-#{version}-server-cloudimg-#{arch}.img", "#{base}/SHA256SUMS"]
+      end
+
+      def rocky(version, arch)
+        raise UnavailableFeature, "Rocky Linux #{version} VM image is not supported" unless %w[8 9].include?(version)
+
+        arch_name = ARCHITECTURES.fetch(arch)
+        base = "https://dl.rockylinux.org/pub/rocky/#{version}/images/#{arch_name}"
+        image = "Rocky-#{version}-GenericCloud-Base.latest.#{arch_name}.qcow2"
+        ["#{base}/#{image}", "#{base}/#{image}.CHECKSUM"]
+      end
+
+      def checksum_for(text, filename)
+        escaped = Regexp.escape(filename)
+        ubuntu = /\A([0-9a-f]{64}) \*?#{escaped}\s*\z/i
+        rocky = /\ASHA256 \(#{escaped}\) = ([0-9a-f]{64})\s*\z/i
+        text.each_line do |line|
+          match = ubuntu.match(line)
+          return match[1].downcase if match
+
+          match = rocky.match(line)
+          return match[1].downcase if match
+        end
+        raise Error, 'Upstream image checksum is missing or malformed'
+      end
+
+      def read_text(url)
+        uri = URI(url)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
+          http.get(uri.request_uri)
+        end
+        validate_text!(response, url)
+      rescue SocketError, OpenSSL::SSL::SSLError, IOError, SystemCallError, Timeout::Error, Net::ProtocolError => e
+        diagnostic = Execution::Diagnostics.transport(operation: 'Retrieve VM image checksum', url: url, error: e)
+        raise Error, "Cannot retrieve upstream VM image checksum\n#{diagnostic}", cause: nil
+      end
+
+      def validate_text!(response, url)
+        unless response.is_a?(Net::HTTPSuccess)
+          diagnostic = Execution::Diagnostics.http(operation: 'Retrieve VM image checksum', url: url,
+                                                   status: response.code, reason: response.message,
+                                                   body: response.body, content_type: response['Content-Type'])
+          raise Error, "Cannot retrieve upstream VM image checksum\n#{diagnostic}", cause: nil
+        end
+        raise Error, 'Upstream VM image checksum is too large' if response.body.bytesize > 100_000
+
+        response.body
+      end
+    end
+  end
+end

data/lib/empeira/vm/interface.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    class Interface < Providers::Lifecycle
+    end
+  end
+end

data/lib/empeira/vm/interface_ownership.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    class InterfaceOwnership
+      PARENT = Configuration::VMInterfaces::PARENT
+
+      def initialize(context:, record:, inventory:, guest:)
+        @record = record
+        @inventory = inventory
+        @guest = guest
+        node = Digest::SHA256.hexdigest(record.fetch('hostname'))[0, 16]
+        @owner = "empeira:#{context.workspace.id}:#{node}:#{inventory.fetch('token')}"
+      end
+
+      def marker(name, definition)
+        "#{@owner}:#{name}:#{Infrastructure::Definition.fingerprint(definition)}"
+      end
+
+      def address(name, definition)
+        ['02', *Digest::SHA256.hexdigest(marker(name, definition))[0, 10].scan(/../)].join(':')
+      end
+
+      def accepted(name)
+        return [{}] if name == PARENT && @inventory.fetch('parent')
+
+        entry = @inventory.fetch('devices')[name]
+        entry ? [entry.fetch('definition'), entry['previous']].compact.uniq : []
+      end
+
+      def observed_definition(name)
+        link = @guest.links[name]
+        return unless link
+
+        definition = accepted(name).find { |candidate| marker_matches?(name, link, candidate) }
+        unless definition
+          conflict!(name,
+                    'existing interface is foreign: MAC/alias ownership marker does not match recorded intent')
+        end
+        unless correct_type?(name, link, definition) && !link.key?('master') && !link.key?('link_netnsid')
+          conflict!(name, 'existing interface is foreign, has changed type/parent, or is attached to another network')
+        end
+        verify_addresses!(name)
+        definition
+      end
+
+      def marker_matches?(name, link, definition)
+        link['address'] == address(name, definition) &&
+          (link.fetch('ifalias', '').empty? || link['ifalias'] == marker(name, definition))
+      end
+
+      def correct_type?(name, link, definition)
+        info = link.fetch('linkinfo', {})
+        return info['info_kind'] == 'dummy' if name == PARENT || !definition.key?('vlan_id')
+
+        correct_vlan?(link, info, definition)
+      end
+
+      def correct_vlan?(link, info, definition)
+        parent = @guest.links[PARENT]
+        info['info_kind'] == 'vlan' && info.dig('info_data', 'id') == definition.fetch('vlan_id') &&
+          info.dig('info_data', 'protocol').to_s.downcase == '802.1q' && parent && @guest.parent_name(link) == PARENT
+      end
+
+      def verify_addresses!(name)
+        addresses = @guest.addresses.fetch(name, [])
+        networks = accepted(name).filter_map { |definition| definition['network'] }
+        return if addresses.all? do |address|
+          address['family'] == 'inet' && networks.include?("#{address['local']}/#{address['prefixlen']}")
+        end
+
+        conflict!(name, 'interface contains an unowned address; preserve it and investigate')
+      end
+
+      def validate!(names)
+        names.each { |name| observed_definition(name) }
+        validate_markers!(names)
+        validate_dependencies!(names)
+      end
+
+      def validate_markers!(names)
+        @guest.links.each do |name, link|
+          next unless owned_marker?(link, names)
+          next if names.include?(name)
+
+          conflict!(name, 'owned marker appears on an unrecorded or renamed interface')
+        end
+      end
+
+      def owned_marker?(link, names)
+        link.fetch('ifalias', '').start_with?("#{@owner}:") || names.any? do |name|
+          accepted(name).any? { |definition| link['address'] == address(name, definition) }
+        end
+      end
+
+      def validate_dependencies!(names)
+        names.each do |name|
+          link = @guest.links[name]
+          next unless link
+
+          children = @guest.links.values.select { |child| @guest.parent_name(child) == name }
+          children.each do |child|
+            child_name = child.fetch('ifname')
+            conflict!(name, "dependent interface #{child_name} is foreign") unless names.include?(child_name)
+          end
+        end
+      end
+
+      def deletable!(name)
+        observed_definition(name)
+        link = @guest.links[name]
+        return unless link
+        return unless @guest.links.values.any? { |child| @guest.parent_name(child) == name }
+
+        conflict!(name, 'dependent interfaces still exist; parent deletion refused')
+      end
+
+      def conflict!(name, reason)
+        raise Providers::OwnershipError,
+              "Host #{@record.fetch('hostname')}, interface #{name}, vm.interfaces: #{reason}"
+      end
+    end
+  end
+end

data/lib/empeira/vm/interface_routes.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    class InterfaceRoutes
+      def self.validate_static!(desired, hostname:, config:, subnet:)
+        protected = [subnet].compact + config.dig('network', 'redirects').map do |entry|
+          entry.fetch('from').fetch('ip')
+        end
+        desired.each do |name, definition|
+          protected.each { |range| reject_overlap!(definition.fetch('network'), range, hostname, name) }
+        end
+      end
+
+      def self.reject_overlap!(network, range, hostname, name)
+        return unless Configuration::VMInterfaces.overlap?(IPAddr.new(network), IPAddr.new(range))
+
+        raise ConfigurationError, "Host #{hostname}, interface #{name}, vm.interfaces: network #{network} " \
+                                  "conflicts with protected route/address #{range} (including network.redirects)"
+      end
+
+      def initialize(guest:, ownership:, hostname:)
+        @guest = guest
+        @ownership = ownership
+        @hostname = hostname
+      end
+
+      def validate!(desired)
+        protected = foreign_addresses + foreign_routes
+        desired.each do |name, definition|
+          protected.each { |range| self.class.reject_overlap!(definition.fetch('network'), range, @hostname, name) }
+        end
+      rescue IPAddr::InvalidAddressError, KeyError, TypeError
+        raise Error, "Host #{@hostname}, vm.interfaces: guest routes/addresses cannot be verified", cause: nil
+      end
+
+      def foreign_addresses
+        @guest.addresses.flat_map do |name, addresses|
+          next [] unless @ownership.accepted(name).empty?
+
+          addresses.filter_map do |address|
+            "#{address.fetch('local')}/#{address.fetch('prefixlen')}" if address['family'] == 'inet'
+          end
+        end
+      end
+
+      def foreign_routes
+        @guest.routes.filter_map do |route|
+          raise Error, "Host #{@hostname}, vm.interfaces: route destination is missing" if route['dst'].nil?
+          raise Error, "Host #{@hostname}, vm.interfaces: unresolved route nexthop ID" if route.key?('nhid')
+          next if foreign_default?(route)
+          next if automatic_owned_route?(route)
+
+          owned = owned_route_device(route)
+          @ownership.conflict!(owned, 'interface carries a non-generated route; mutation refused') if owned
+
+          route.fetch('dst')
+        end
+      end
+
+      def foreign_default?(route)
+        %w[default 0.0.0.0/0].include?(route['dst']) && owned_route_device(route).nil?
+      end
+
+      def owned_route_device(route)
+        hops = route.values_at('multipath', 'nexthops').compact.flatten
+        devices = [route['dev'], *hops.map { |hop| hop.fetch('dev') }].compact
+        devices.find { |name| !@ownership.accepted(name).empty? }
+      end
+
+      def automatic_owned_route?(route)
+        return false unless ordinary_kernel_route?(route)
+
+        @ownership.accepted(route['dev']).any? do |definition|
+          next false unless definition['network']
+
+          generated_route?(route, definition.fetch('network'))
+        end
+      end
+
+      def ordinary_kernel_route?(route)
+        route['protocol'] == 'kernel' && !route.key?('gateway') && !route.key?('multipath') &&
+          !route.key?('nexthops') && [nil, 'main', 'local', 254, 255].include?(route['table'])
+      end
+
+      def generated_route?(route, network)
+        subnet = IPAddr.new(network)
+        target = IPAddr.new(route.fetch('dst'))
+        case route['type']
+        when 'local' then target.prefix == 32 && target.to_s == network.split('/').first
+        when 'broadcast' then broadcast?(target, subnet)
+        else route['scope'] == 'link' && target == subnet && target.prefix == subnet.prefix
+        end
+      end
+
+      def broadcast?(target, subnet)
+        target.prefix == 32 && [subnet.to_range.first.to_s, subnet.to_range.last.to_s].include?(target.to_s)
+      end
+    end
+  end
+end