empeira 0.1.0.pre.alpha.1

data/lib/empeira/node/vm_preparation.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # rubocop:disable-next Metrics/ModuleLength -- VM creation and its ordered first-boot preparation are one workflow.
+    module VMPreparation
+      def run(request)
+        @created_vm = nil
+        mutate do
+          server = ready_server
+          image, accelerator = preflight_vm(request)
+          record, overlay, seed = prepare_vm_disk(request, image, accelerator)
+          provision_vm(record, overlay, seed, server)
+          lifecycle_result(record.fetch('hostname'), :running, changed: true)
+        rescue StandardError => e
+          report_retained_vm(e)
+        end
+      end
+
+      private
+
+      def provision_vm(record, overlay, seed, server)
+        packages = package_bootstrap(record)
+        Network::Gateway.new(context: context, runtime: @runtime, state: @state).phase(record, bootstrap: true)
+        boot_vm(record, overlay, seed)
+        @bootstrap_proxy.start(@state, @requirements, source: record.fetch('peer').fetch('ip')) if
+          @requirements.required? || packages.required?
+        finish_vm(record, server, packages)
+      ensure
+        @bootstrap_proxy.cleanup(@state)
+      end
+
+      def report_retained_vm(error)
+        raise error unless @created_vm
+
+        name = @created_vm.fetch('hostname')
+        message = "#{error.message}\nVM #{name} retained for diagnosis. Cleanup: empeira node destroy #{name}"
+        raise error.exception(message), cause: error
+      end
+
+      def prepare_vm_disk(request, image, accelerator)
+        @progress.stage(20, 'Preparing VM image...')
+        base = @cache.fetch(image)
+        record = reserve_vm(request, image.identity, accelerator)
+        @created_vm = record
+        @progress.stage(35, 'Creating overlay and cloud-init seed...')
+        overlay = @disk.create(hostname: record.fetch('hostname'), base: base,
+                               size_gib: context.configuration.dig('vm', 'disk'))
+        [record, overlay, @cloud.prepare(record)]
+      end
+
+      def boot_vm(record, overlay, seed)
+        @progress.stage(50, 'Connecting VM to managed services...')
+        @peer.prepare(record, @state)
+        attachment = Network::Peer::Attachment.new(backend: @peer, record: record, state: @state)
+        refresh_dns
+        @progress.stage(55, 'Starting virtual machine...')
+        begin
+          record['pid'] = @qemu.launch(record: record, overlay: overlay, seed: seed, network: attachment)
+        ensure
+          save if record['pid']
+        end
+        @progress.stage(60, 'Waiting for VM network and bootstrap...')
+        verify_vm_boot(record)
+      end
+
+      def verify_vm_boot(record)
+        @guest.wait(record, progress: @progress)
+        ::Empeira::VM::RootDisk.new(guest: @guest).verify!(record, size_gib: context.configuration.dig('vm', 'disk'))
+        VMBootstrap.new(guest: @guest).verify(record: record, bootstrap: Bootstrap.new(provider: 'vm'))
+        record['empeira_fact'] = ExternalFact.fingerprint('vm')
+        save
+        @cloud.finish(record, guest: @guest)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Verified certificate retirement precedes enrollment and ready-state persistence.
+      def finish_vm(record, server, packages)
+        @progress.stage(70, 'Installing/configuring Puppet agent...')
+        prepare_agent(record, packages)
+        reconcile_interfaces(record)
+        @progress.stage(85, 'Signing VM certificate...')
+        certificate_runtime = ::Empeira::VM::CertificateRuntime.new(runtime: @runtime, guest: @guest, record: record)
+        certificates = Certificates.new(runtime: certificate_runtime, server: server)
+        certificates.clean_retired(@state, record.fetch('hostname')) { save } if @state['retired_certificates']
+        certificates.enroll({ 'vm' => true }, record) { save }
+        reconcile_guest(record)
+        record['provisioned'] = true
+        record['state'] = 'running'
+        save
+        @progress.stage(95, 'Running Puppet...')
+        puppet_run(record)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- Preserve bootstrap cleanup before runtime activation.
+      def prepare_agent(record, packages)
+        execute = ->(arguments) { @guest.run(record, arguments, timeout: 300) }
+        package_configuration(record, execute).preserve do
+          if packages.required?
+            @progress.stage(75, 'Bootstrapping packages...')
+            packages.run(proxy_url: @bootstrap_proxy.url)
+          end
+          @agent.ensure_installed(record, requirements: @requirements, proxy_url: @bootstrap_proxy.url)
+        end
+        PackageSources.verify!(execute: ->(arguments) { @guest.run(record, arguments) })
+        @bootstrap_proxy.cleanup(@state)
+        record['network_phase'] = 'runtime'
+        save
+        Network::Gateway.new(context: context, runtime: @runtime, state: @state).phase(record, bootstrap: false)
+        refresh_dns
+        reconcile_runtime_proxy(record)
+        reconcile_interactive_tools(record)
+        configure_agent(record)
+      end
+
+      def package_configuration(record, execute)
+        family = PackageBootstrap::FAMILIES.fetch(record.fetch('os'))
+        klass = family == 'debian' ? AptConfiguration : RpmConfiguration
+        options = family == 'debian' ? { on_retry: @progress.method(:warning) } : {}
+        klass.new(os: record.fetch('os'), execute: execute, **options)
+      end
+
+      def package_bootstrap(record)
+        PackageBootstrap.new(config: context.configuration.dig('bootstrap', 'packages'), os: record.fetch('os'),
+                             execute: ->(arguments) { @guest.run(record, arguments, timeout: 300) },
+                             copy: lambda { |source, destination, mode|
+                               @guest.copy_to(record, source, destination, mode: mode)
+                             },
+                             rpm_options: @requirements.rpm_options,
+                             progress: @progress.method(:heartbeat))
+      end
+
+      def refresh_dns
+        plan = ControlPlane::Plan.new(context: context)
+        ControlPlane::Discovery.new(plan: plan, runtime: @runtime, state: @state).refresh
+      end
+
+      def configure_agent(record)
+        { 'certname' => record.fetch('hostname'), 'server' => 'server.empeira.internal',
+          'environment' => context.configuration.dig('server', 'environment') }.each do |key, value|
+          result = @guest.run(record, [Certificates::PUPPET, 'config', 'set', key, value, '--section', 'main'])
+          next if result.success?
+
+          details = Execution::Diagnostics.command(result, operation: "VM agent configuration: #{key}", tool: 'puppet')
+          raise Error, "VM agent configuration failed; node retained for diagnosis\n#{details}", cause: nil
+        end
+      end
+
+      def puppet_run(record)
+        reconcile_provider_fact(record)
+        result = @progress.streaming do
+          @guest.stream(record, RuntimeProxy.command(context, PuppetCommand.arguments))
+        end
+        record['last_puppet_exit'] = result.exit_status
+        save
+        return result if [0, 2].include?(result.exit_status)
+
+        raise Error, "Puppet agent failed (exit #{result.exit_status}); VM retained for shell/logs"
+      end
+    end
+  end
+end

data/lib/empeira/node/vm_state.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'socket'
+
+module Empeira
+  module Node
+    # VM records live in the same locked workspace inventory as container records.
+    # rubocop:disable-next Metrics/ModuleLength -- Workspace state and record validation share one boundary.
+    module VMState
+      def list
+        load_state
+        health = @peer.health(vm_records.values)
+        vm_records.map do |_, record|
+          record.slice('hostname', 'provider', 'os', 'version', 'last_puppet_exit').merge(
+            'runtime' => 'qemu', 'state' => observed_state(record),
+            'network' => if health[record.fetch('hostname')]
+                           'running'
+                         else
+                           (record['state'] == 'stopped' ? 'reserved' : 'degraded')
+                         end
+          )
+        end
+      end
+
+      def inspect_resource(name:)
+        load_state
+        record = vm_records[name.downcase]
+        return unless record
+
+        state = record['provisioned'] && @qemu.observed_running?(record) ? :running : :stopped
+        Providers::Resource.new(name: record.fetch('hostname'), owner: context.workspace.id, state: state)
+      end
+
+      private
+
+      def observed_state(record)
+        return 'incomplete' unless record['provisioned']
+
+        return 'running' if @qemu.observed_running?(record)
+
+        return 'preparing' if record['state'] == 'preparing'
+
+        record['state'] == 'stopped' ? 'stopped' : 'missing'
+      end
+
+      def vm_records
+        @nodes.select { |_, record| record['provider'] == 'vm' }
+      end
+
+      def mutate(availability: true)
+        @build_info.require_compatible!(context.configuration.dig('requirements', 'empeira'))
+        @store.with_lock do
+          load_state
+          check_runtime!(availability: availability)
+          yield
+        end
+      end
+
+      def load_state(state = @store.load)
+        @state = state
+        @nodes = state&.fetch('nodes', {}) || {}
+      end
+
+      def check_runtime!(availability: true)
+        raise Error, 'Control plane is down; run empeira up first' unless @state&.dig('resources', 'network', 'id')
+        if @state.fetch('runtime') != context.container_engine
+          raise Error, 'Node runtime differs from workspace ownership; restore runtime.container_engine'
+        end
+
+        @runtime.check_available! if availability
+      end
+
+      def save
+        @state['nodes'] = @nodes
+        @store.write(@state)
+      end
+
+      def fetch_vm(name)
+        record = vm_records[name.downcase]
+        raise Providers::NotFound, 'VM node does not exist in this workspace' unless record
+
+        record
+      end
+
+      def ready_server
+        plan = ControlPlane::Plan.new(context: context)
+        definition = plan.definitions.fetch('server')
+        expected = @state.dig('control_plane', 'services', 'server', 'id')
+        server = @runtime.inspect_service(definition, expected_id: expected)
+        unless server && server['state'] == 'running' &&
+               server.dig('labels', 'io.empeira.definition') == definition.fingerprint &&
+               ControlPlane::Health.new(runtime: @runtime, plan: plan).ready?('server', 'server' => server)
+          raise Error, 'Configuration server is not ready; run empeira up first'
+        end
+
+        server
+      end
+
+      def reserve_vm(request, identity, accelerator)
+        name = request.hostname.downcase
+        reject_vm_name!(name)
+        record = vm_record(request, identity, accelerator, name)
+        @nodes[name] = record
+        save
+        record
+      end
+
+      def reject_vm_name!(name)
+        aliases = [name, name.delete_suffix('.empeira.internal')]
+        taken = @nodes.keys.any? { |key| aliases.include?(key.delete_suffix('.empeira.internal')) }
+        return unless taken || aliases.intersect?(Network::Naming.new.reserved(context.configuration))
+
+        raise Providers::AlreadyExists, 'Hostname is reserved or already exists in this workspace'
+      end
+
+      def vm_record(request, identity, accelerator, name)
+        request.to_h.transform_keys(&:to_s).merge(
+          'hostname' => name, 'engine' => 'qemu', 'accelerator' => accelerator,
+          'architecture' => context.platform.architecture.to_s, 'base_image' => identity.to_h,
+          'overlay' => "vms/#{name}/disk.qcow2", 'network' => @state.dig('resources', 'network', 'logical_identity'),
+          'mac_address' => vm_mac(name),
+          'peer' => peer_lease,
+          'management_layout' => ::Empeira::VM::Management::VERSION, 'pid' => nil,
+          'network_phase' => 'bootstrap', 'state' => 'preparing', 'provisioned' => false,
+          'certificate_key' => nil, 'last_puppet_exit' => nil,
+          'created_at' => Time.now.utc.iso8601
+        )
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Lease and shared DNS/gateway bindings are one identity.
+      def peer_lease
+        plan = ControlPlane::Plan.new(context: context)
+        dns = @runtime.inspect_service(plan.definitions.fetch('dns'),
+                                       expected_id: @state.dig('control_plane', 'services', 'dns', 'id'))
+        address = dns&.dig('networks', plan.network, 'IPAddress')
+        raise Error, 'CoreDNS is unavailable on the peer network' unless address
+
+        Network::Peer::Layout.new(@state.fetch('peer_network').fetch('subnet')).lease(@nodes)
+                             .merge('backend' => @peer.key, 'dns' => address,
+                                    'gateway' => Network::Gateway.address(@state.fetch('peer_network').fetch('subnet')))
+      end
+
+      def vm_mac(_hostname)
+        hex = SecureRandom.hex(4)
+        "52:54:#{hex.scan(/../).join(':')}"
+      end
+
+      def base_for(record)
+        fields = record.fetch('base_image').transform_keys(&:to_sym)
+        identity = Images::Identity.new(**fields)
+        context.locations.image(identity).join('base.qcow2')
+      end
+
+      def lifecycle_result(name, state, changed:)
+        resource = Providers::Resource.new(name: name, owner: context.workspace.id, state: state)
+        Providers::Result.new(resource: resource, changed: changed)
+      end
+    end
+  end
+end

data/lib/empeira/platform/facts.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module Empeira
+  module Platform
+    class Facts
+      attr_reader :os, :architecture
+
+      def initialize(host_os: RbConfig::CONFIG.fetch('host_os'), host_cpu: RbConfig::CONFIG.fetch('host_cpu'),
+                     environment: ENV, kernel_release: nil)
+        @os = detect_os(host_os, environment, kernel_release)
+        @architecture = normalize_architecture(host_cpu)
+        freeze
+      end
+
+      def process_groups?
+        true
+      end
+
+      def vm_install_hint
+        return 'Install QEMU, xorriso and OpenSSH, for example: brew install qemu xorriso' if os == :macos
+
+        release = File.read('/etc/os-release')
+        if release.match?(/^(?:ID|ID_LIKE)=.*(?:ubuntu|debian)/)
+          package = architecture == :arm64 ? 'qemu-system-arm qemu-efi-aarch64' : 'qemu-system-x86'
+          return "Install missing dependencies: sudo apt install #{package} qemu-utils xorriso openssh-client"
+        end
+        'Install QEMU system tools, qemu-img, xorriso and OpenSSH using your host distribution package manager.'
+      rescue SystemCallError
+        'Install QEMU system tools, qemu-img, xorriso and OpenSSH using your host distribution package manager.'
+      end
+
+      private
+
+      def detect_os(host_os, environment, kernel_release)
+        case host_os.downcase
+        when /linux/ then wsl?(environment, kernel_release) ? :wsl : :linux
+        when /darwin/ then :macos
+        else raise UnsupportedPlatform, 'Unsupported operating system (expected Linux, macOS, or WSL2)'
+        end
+      end
+
+      def wsl?(environment, kernel_release)
+        return true if %w[WSL_INTEROP WSL_DISTRO_NAME].any? { |key| !environment[key].to_s.empty? }
+
+        release = kernel_release || read_kernel_release
+        release.match?(/microsoft|wsl/i)
+      end
+
+      def read_kernel_release
+        File.read('/proc/sys/kernel/osrelease')
+      rescue SystemCallError
+        ''
+      end
+
+      def normalize_architecture(cpu)
+        case cpu.downcase
+        when /\A(?:x86_64|amd64|x64)(?:\W|\z)/ then :amd64
+        when /\A(?:aarch64|arm64)(?:\W|\z)/ then :arm64
+        else raise UnsupportedPlatform, 'Unsupported architecture (expected amd64 or arm64)'
+        end
+      end
+    end
+  end
+end

data/lib/empeira/platform/kvm.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'shellwords'
+
+module Empeira
+  module Platform
+    class Kvm
+      DEVICE = '/dev/kvm'
+
+      def initialize(platform:)
+        @platform = platform
+      end
+
+      def verify!
+        version = File.open(DEVICE, File::RDWR) do |device|
+          device.ioctl(0xae00)
+        rescue SystemCallError => e
+          raise UnavailableFeature, "KVM device opens but KVM_GET_API_VERSION ioctl fails (#{e.class})", cause: nil
+        end
+        return version if version == 12
+
+        raise UnavailableFeature, "KVM returned unsupported API version #{version} (expected 12)"
+      rescue Errno::ENOENT
+        raise UnavailableFeature, 'KVM is unavailable: /dev/kvm is missing; enable host KVM virtualization', cause: nil
+      rescue Errno::EACCES, Errno::EPERM
+        raise UnavailableFeature, permission_diagnostic, cause: nil
+      rescue SystemCallError => e
+        raise UnavailableFeature, "KVM device cannot be opened (#{e.class}); check host device policy", cause: nil
+      end
+
+      private
+
+      def permission_diagnostic
+        stat = File.stat(DEVICE)
+        groups = current_groups
+        ["KVM is unavailable: #{DEVICE} is #{access_description}.",
+         "Owner: #{user(stat.uid)}:#{group(stat.gid)} (mode #{format('%04o', stat.mode & 0o777)})",
+         "Current user: #{user(Process.euid)}", "Current groups: #{group_names(groups)}",
+         permission_hint(stat, groups)].join("\n")
+      rescue SystemCallError
+        'KVM is unavailable: device permissions deny access; inspect /dev/kvm ownership and host device policy'
+      end
+
+      def group_names(groups)
+        groups.map { |id| group(id) }.join(' ')
+      end
+
+      def current_groups
+        (Process.groups + [Process.egid]).uniq
+      end
+
+      def access_description
+        access = []
+        access << 'unreadable' unless File.readable?(DEVICE)
+        access << 'unwritable' unless File.writable?(DEVICE)
+        access << 'denied by device policy' if access.empty?
+        access.join(' and ')
+      end
+
+      def missing_group?(stat, groups)
+        Process.euid != stat.uid && !groups.include?(stat.gid) && stat.mode.allbits?(0o060) &&
+          (!File.readable?(DEVICE) || !File.writable?(DEVICE))
+      end
+
+      def permission_hint(stat, groups)
+        unless missing_group?(stat, groups)
+          return 'Device permissions or host security policy deny access; check mode, ACLs and device restrictions.'
+        end
+
+        required_group = Shellwords.escape(group(stat.gid))
+        hint = "Required group: #{group(stat.gid)}\nSuggested fix: sudo usermod -aG #{required_group} \"$USER\"\n" \
+               'Start a new login session for group membership to take effect.'
+        hint += "\nOn WSL2 restart the instance/session: wsl.exe --shutdown" if @platform.os == :wsl
+        hint
+      end
+
+      def user(id)
+        Etc.getpwuid(id).name
+      rescue ArgumentError
+        id.to_s
+      end
+
+      def group(id)
+        Etc.getgrgid(id).name
+      rescue ArgumentError
+        id.to_s
+      end
+    end
+  end
+end

data/lib/empeira/platform/locations.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'tmpdir'
+
+module Empeira
+  module Platform
+    class Locations
+      attr_reader :cache, :state, :temporary, :home
+
+      def initialize(facts: Facts.new, home: Dir.home, environment: ENV, temporary_root: Dir.tmpdir)
+        @home = Pathname(home)
+        @environment = environment
+        @cache, @state = roots(facts.os).map { |path| path.join('empeira') }
+        @temporary = Pathname(temporary_root)
+      end
+
+      def workspace(identity)
+        state.join('workspaces', identity.id)
+      end
+
+      def user_configuration
+        home.join('.empeira.yaml')
+      end
+
+      def addons
+        home.join('.empeira', 'addons').expand_path
+      end
+
+      def image(identity)
+        cache.join('images', identity.cache_key)
+      end
+
+      private
+
+      def roots(os)
+        case os
+        when :macos then [@home.join('Library/Caches'), @home.join('Library/Application Support')]
+        else
+          [absolute_environment('XDG_CACHE_HOME', @home.join('.cache')),
+           absolute_environment('XDG_STATE_HOME', @home.join('.local/state'))]
+        end
+      end
+
+      def absolute_environment(key, fallback)
+        value = @environment[key]
+        value && Pathname(value).absolute? ? Pathname(value) : fallback
+      end
+    end
+  end
+end

data/lib/empeira/platform/resolvers.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Platform
+    class Resolvers
+      attr_reader :routes
+
+      def initialize(platform:, runner:, reader: File)
+        @platform = platform
+        @runner = runner
+        @reader = reader
+        @routes = {}
+      end
+
+      def resolve(config)
+        return usable(config.fetch('servers')) if config.fetch('mode') == 'explicit'
+
+        usable(@platform.os == :macos ? macos : linux)
+      end
+
+      private
+
+      def linux
+        addresses = read('/etc/resolv.conf').scan(/^nameserver\s+(\S+)/).flatten
+        return addresses if addresses.any? { |address| reachable?(address) }
+
+        read('/run/systemd/resolve/resolv.conf').scan(/^nameserver\s+(\S+)/).flatten
+      end
+
+      def macos
+        result = @runner.run('scutil', arguments: ['--dns'], timeout: 10)
+        unless result.success?
+          raise Error,
+                'Cannot discover macOS DNS; configure dns.upstream.mode=explicit and servers'
+        end
+
+        parse_macos(result.stdout)
+      end
+
+      def parse_macos(output)
+        defaults = []
+        output.split(/^resolver #/).each do |block|
+          next if block.match?(/options\s*:\s*mdns/)
+
+          addresses = macos_addresses(block)
+          domain = block[/^\s*domain\s*:\s*([a-zA-Z0-9.-]+)\s*$/, 1]&.downcase
+          defaults = route_or_default(domain, addresses, defaults)
+        end
+        defaults
+      end
+
+      def route_or_default(domain, addresses, defaults)
+        return defaults if domain&.end_with?('empeira.internal')
+        return defaults.empty? ? addresses : defaults unless domain
+
+        @routes[domain] = addresses unless addresses.empty?
+        defaults
+      end
+
+      def macos_addresses(block)
+        block.scan(/nameserver\[\d+\]\s*:\s*(\S+)/).flatten.select { |ip| reachable?(ip) }
+      end
+
+      def read(path)
+        @reader.read(path)
+      rescue SystemCallError
+        ''
+      end
+
+      def reachable?(address)
+        ip = IPAddr.new(address)
+        !ip.loopback? && !ip.link_local? && ip.to_i.positive?
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      def usable(addresses)
+        result = addresses.select { |address| reachable?(address) }.uniq
+        return result unless result.empty?
+
+        raise Error, 'No container-reachable DNS upstream found; configure dns.upstream.mode=explicit and servers'
+      end
+    end
+  end
+end

data/lib/empeira/platform/routes.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Platform
+    class Routes
+      def initialize(platform:, runner:)
+        @platform = platform
+        @runner = runner
+      end
+
+      def ipv4
+        return linux_routes if @platform.os != :macos
+
+        mac_routes
+      end
+
+      private
+
+      def mac_routes
+        result = @runner.run('netstat', arguments: %w[-rn -f inet], timeout: 10)
+        raise Error, 'Cannot inspect host IPv4 routes before allocating the peer network' unless result.success?
+
+        result.stdout.lines.filter_map do |line|
+          destination = line.split.first
+          next unless destination&.match?(/\A\d/)
+
+          expand_destination(destination)
+        end
+      end
+
+      def expand_destination(destination)
+        address, prefix = destination.split('/')
+        octets = address.split('.')
+        "#{(octets + (['0'] * (4 - octets.size))).join('.')}/#{prefix || (octets.size * 8)}"
+      end
+
+      def linux_routes
+        result = @runner.run('ip', arguments: %w[-j -4 route show table all], timeout: 10)
+        raise Error, 'iproute2 is required to verify host routes before peer subnet allocation' unless result.success?
+
+        JSON.parse(result.stdout).filter_map do |route|
+          destination = route.fetch('dst')
+          destination unless %w[default 0.0.0.0/0].include?(destination)
+        end
+      rescue JSON::ParserError, KeyError
+        raise Error, 'Cannot verify host IPv4 route inventory', cause: nil
+      end
+    end
+  end
+end