empeira 0.1.0.pre.alpha.1

data/lib/empeira/node/ssh_client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Empeira
+  module Node
+    class SSHClient
+      def initialize(credentials:, proxy_command: nil)
+        @credentials = credentials
+        @proxy_command = proxy_command
+      end
+
+      def proxy_options
+        return [] unless @proxy_command
+
+        ['-o', "ProxyCommand=#{Shellwords.join(@proxy_command).gsub('%', '%%')}"]
+      end
+
+      def known_hosts_option
+        path = @credentials.known_hosts.to_s.gsub(/["\\]/) { |character| "\\#{character}" }.gsub('%', '%%')
+        "UserKnownHostsFile=\"#{path}\""
+      end
+    end
+  end
+end

data/lib/empeira/node/ssh_credentials.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Empeira
+  module Node
+    # Per-node credentials and known hosts stay in private workspace storage.
+    class SSHCredentials
+      def initialize(context:, runner:, provider:, hostname:, purpose: nil)
+        @runner = runner
+        raise ArgumentError, 'Unknown SSH credential scope' unless [nil, :system].include?(purpose)
+
+        @purpose = purpose
+        parent = provider == 'vm' ? 'vms' : 'containers'
+        @directory = context.locations.workspace(context.workspace).join(parent, hostname)
+      end
+
+      attr_reader :directory
+
+      def key_path
+        directory.join('id_ed25519')
+      end
+
+      def public_path
+        Pathname("#{key_path}.pub")
+      end
+
+      def known_hosts
+        directory.join(@purpose ? "#{@purpose}_known_hosts" : 'known_hosts')
+      end
+
+      def prepare
+        prepare_hosts
+        generate unless [key_path, public_path].any? { |path| path.exist? || path.symlink? }
+        verify!
+        public_path
+      end
+
+      def prepare_hosts
+        raise Error, 'Managed SSH directory must not be a symlink' if directory.symlink?
+
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        File.chmod(0o700, directory)
+        raise Error, 'Managed SSH known_hosts is unsafe' if known_hosts.symlink? ||
+                                                            (known_hosts.exist? && !known_hosts.file?)
+      end
+
+      def verify!
+        raise Error, 'Managed SSH directory must not be a symlink' if directory.symlink?
+
+        raise Error, 'Managed SSH key material is missing or unsafe; destroy and recreate the node' unless safe_keys?
+        raise Error, 'Managed SSH known_hosts must not be a symlink' if known_hosts.symlink?
+
+        File.chmod(0o600, key_path)
+        File.chmod(0o600, known_hosts) if known_hosts.exist?
+      end
+
+      def cleanup
+        raise Error, 'Managed SSH directory must not be a symlink' if directory.symlink?
+
+        FileUtils.remove_entry_secure(directory) if directory.exist?
+      end
+
+      private
+
+      def safe_keys?
+        [key_path, public_path].all? { |path| path.file? && !path.symlink? && path.readable? }
+      end
+
+      def generate
+        result = @runner.run('ssh-keygen', arguments: ['-q', '-t', 'ed25519', '-C', 'empeira-managed',
+                                                       '-N', '', '-f', key_path.to_s],
+                                           timeout: 15)
+        raise Error, 'Cannot create managed SSH key; install openssh-client on the CLI host' unless result.success?
+      end
+    end
+  end
+end

data/lib/empeira/node/ssh_endpoint.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # The sole allowed container-node publication is managed SSH on host loopback.
+    class SSHEndpoint
+      def self.valid?(resource, record)
+        return resource.fetch('ports').empty? unless record['ssh_host']
+        return false unless record['ssh_host'] == '127.0.0.1'
+        return tunnel?(resource, record) if record['ssh_transport'] == 'tunnel'
+
+        loopback?(resource, record)
+      end
+
+      def self.tunnel?(resource, record)
+        resource.fetch('ports').empty? && resource.fetch('published_ports', {}).values.all?(&:nil?) &&
+          record.dig('definition', 'ports') == [] && record['ssh_port'] == 22
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Compare configured and observed ports against the recorded endpoint.
+      def self.loopback?(resource, record)
+        return false unless managed?(record) && resource.fetch('ports').keys == ['22/tcp']
+
+        bindings = resource.fetch('ports')['22/tcp']
+        return false unless binding?(bindings, record['ssh_port'], pending: record['ssh_port'].nil?)
+        return true unless resource['state'] == 'running'
+
+        publications = resource.fetch('published_ports', {})
+        publications.keys == ['22/tcp'] && binding?(publications['22/tcp'], record['ssh_port'])
+      end
+
+      def self.managed?(record)
+        record['ssh_host'] == '127.0.0.1' && record.dig('definition', 'ports') == ['127.0.0.1::22/tcp']
+      end
+
+      def self.binding?(bindings, port, pending: false)
+        return false unless loopback_binding?(bindings)
+
+        value = bindings[0]['HostPort']
+        return true if pending && value == ''
+
+        valid_port?(value) && (port.nil? || value.to_i == port)
+      end
+
+      def self.loopback_binding?(bindings)
+        bindings.is_a?(Array) && bindings.size == 1 && bindings[0]['HostIp'] == '127.0.0.1'
+      end
+
+      def self.valid_port?(value)
+        value.is_a?(String) && value.match?(/\A[0-9]+\z/) && value.to_i.between?(1, 65_535)
+      end
+
+      def self.port(resource)
+        Integer(resource.fetch('published_ports').fetch('22/tcp').first.fetch('HostPort'), 10)
+      end
+    end
+  end
+end

data/lib/empeira/node/ssh_identity.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Empeira
+  module Node
+    # Validate external private-key paths without reading or copying their contents.
+    class SSHIdentity
+      def initialize(home:)
+        @home = Pathname(home)
+      end
+
+      def resolve(value)
+        path = path_for(value)
+        stat = path.lstat
+        raise ConfigurationError, 'SSH identity must be a readable regular file, without a symlink' unless
+          stat.file? && path.readable?
+        raise ConfigurationError, 'SSH identity permissions must exclude group and other access (use chmod 600)' unless
+          stat.mode.nobits?(0o077)
+
+        path.to_s
+      rescue SystemCallError
+        raise ConfigurationError, 'SSH identity is missing or unreadable', cause: nil
+      end
+
+      private
+
+      def path_for(value)
+        unless value.is_a?(String) && !value.empty? && !value.match?(/[\p{Cc}\p{Cf}]/)
+          raise ConfigurationError, 'SSH identity must be a nonempty file path without control characters'
+        end
+
+        value.start_with?('~/') ? @home.join(value.delete_prefix('~/')).expand_path : Pathname(value).expand_path
+      end
+    end
+  end
+end

data/lib/empeira/node/user_ssh.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'etc'
+
+module Empeira
+  module Node
+    # Provider defaults select authentication; endpoint and host-key policy remain managed.
+    class UserSSH
+      def initialize(runner:, credentials:, proxy_command: nil, default_user: nil, managed_identity: false,
+                     home: Dir.home)
+        @runner = runner
+        @credentials = credentials
+        @proxy_command = proxy_command
+        @default_user = default_user
+        @managed_identity = managed_identity
+        @identity = SSHIdentity.new(home: home)
+      end
+
+      def session(record, user: nil, identity: nil)
+        @credentials.prepare_hosts
+        username = username_for(user)
+        transport = SSHClient.new(credentials: @credentials, proxy_command: @proxy_command)
+        arguments = ['-tt', '-l', username, *options(record, transport), *authentication_options(identity)]
+        @runner.stream('ssh', arguments: [*arguments, record.fetch('hostname')])
+      end
+
+      def username_for(user)
+        username = user || @default_user || Etc.getpwuid(Process.uid).name
+        unless username.is_a?(String) && username.match?(/\A[a-zA-Z0-9_.@-]+\z/)
+          raise ConfigurationError, 'SSH user must be a valid login name'
+        end
+
+        username
+      end
+
+      def authentication_options(identity)
+        return identity ? ['-i', @identity.resolve(identity)] : [] unless @managed_identity
+
+        @credentials.verify! unless identity
+        key = identity ? @identity.resolve(identity) : @credentials.key_path.to_s
+        ['-i', key, '-o', 'IdentitiesOnly=yes', '-o', 'PasswordAuthentication=no',
+         '-o', 'KbdInteractiveAuthentication=no', '-o', 'ForwardAgent=no']
+      end
+
+      def options(record, transport)
+        port = record['ssh_port']
+        unless record.fetch('ssh_host', '127.0.0.1') == '127.0.0.1' && port.is_a?(Integer) && port.between?(1, 65_535)
+          raise Error, 'Managed SSH endpoint is missing or inconsistent'
+        end
+
+        proxy = @proxy_command ? transport.proxy_options : ['-o', 'ProxyCommand=none']
+        ['-p', port.to_s, '-o', 'HostName=127.0.0.1', '-o', "HostKeyAlias=#{record.fetch('hostname')}",
+         '-o', transport.known_hosts_option, '-o', "GlobalKnownHostsFile=#{File::NULL}",
+         '-o', 'StrictHostKeyChecking=accept-new', '-o', 'CanonicalizeHostname=no',
+         '-o', 'ControlMaster=no', '-o', 'ControlPath=none', '-o', 'ClearAllForwardings=yes',
+         *proxy, '-o', 'ProxyJump=none']
+      end
+    end
+  end
+end

data/lib/empeira/node/vm.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # Public logical node provider; QEMU and container networking stay replaceable.
+    class VM < Interface
+      include VMState
+      include VMPreflight
+      include VMPreparation
+      include VMLifecycle
+
+      def initialize(context:, runner:, backend:, runtime:, build_info: BuildInfo.load, progress: Progress.new)
+        super(name: 'vm', context: context, runner: runner, backend: backend)
+        @engine = backend
+        @runtime = runtime
+        @build_info = build_info
+        @progress = progress
+        @store = Infrastructure::Store.new(context: context)
+        prepare_components(context, runner, backend, runtime)
+      end
+
+      # rubocop:disable-next Naming/PredicateMethod -- Reconciliation mutates guest resources.
+      def reconcile_all(state:)
+        load_state(state)
+        vm_records.values.map do |record|
+          record['provisioned'] && @qemu.running?(record) ? reconcile_guest(record) : false
+        end.any?
+      end
+
+      private
+
+      def validate_interfaces(record)
+        ::Empeira::VM::Interfaces.validate_static!(context, record.fetch('hostname'), @state)
+      end
+
+      def reconcile_interfaces(record)
+        ::Empeira::VM::Interfaces.new(context: context, record: record, state: @state, guest: @guest,
+                                      persist: method(:save)).reconcile
+      end
+
+      def reconcile_guest(record)
+        fact_changed = reconcile_provider_fact(record)
+        proxy_changed = reconcile_runtime_proxy(record)
+        tools_changed = reconcile_interactive_tools(record)
+        interfaces_changed = reconcile_interfaces(record)
+        reconcile_command_mocks(record) || interfaces_changed || proxy_changed || tools_changed || fact_changed
+      end
+
+      # rubocop:disable-next Naming/PredicateMethod -- Reconciliation mutates owned guest state and reports changes.
+      def reconcile_provider_fact(record)
+        digest = ExternalFact.fingerprint('vm')
+        return false if record['empeira_fact'] == digest
+
+        VMBootstrap.new(guest: @guest).reconcile(record: record, bootstrap: Bootstrap.new(provider: 'vm'))
+        record['empeira_fact'] = digest
+        save
+        true
+      end
+
+      def reconcile_interactive_tools(record)
+        InteractiveTools.new(record: record, persist: method(:save),
+                             execute: ->(arguments) { @guest.run(record, arguments) }).reconcile
+      end
+
+      def reconcile_runtime_proxy(record)
+        RuntimeProxy.new(context: context, record: record, persist: method(:save),
+                         execute: ->(arguments) { @guest.run(record, arguments) }).reconcile
+      end
+
+      def reconcile_command_mocks(record)
+        CommandMocks.new(context: context, record: record, persist: method(:save),
+                         execute: ->(arguments) { @guest.run(record, arguments) }).reconcile
+      end
+
+      def prepare_components(context, runner, backend, runtime)
+        @peer = Network::Peer::Backend.build(context: context, runtime: runtime, runner: runner, store: @store)
+        @bootstrap_proxy = Network::BootstrapProxy.new(context: context, runtime: runtime, store: @store)
+        @source = ::Empeira::VM::ImageSource.new
+        @cache = ::Empeira::VM::ImageCache.new(locations: context.locations)
+        @disk = ::Empeira::VM::Disk.new(engine: backend, runner: runner,
+                                        workspace_directory: context.locations.workspace(context.workspace))
+        @qemu = ::Empeira::VM::QemuRuntime.new(engine: backend, runner: runner, context: context)
+        @cloud = ::Empeira::VM::CloudInit.new(context: context, runner: runner)
+        @guest = ::Empeira::VM::Guest.new(context: context, runner: runner, qemu: @qemu)
+        @agent = ::Empeira::VM::Agent.new(context: context, guest: @guest, runtime: runtime, progress: @progress)
+      end
+    end
+  end
+end

data/lib/empeira/node/vm_bootstrap.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # Cloud-Init installs shared files; management transport verifies them before Puppet.
+    class VMBootstrap
+      def initialize(guest:)
+        @guest = guest
+      end
+
+      def verify(record:, bootstrap:)
+        bootstrap.files.each { |file| verify_file!(record, file) }
+      end
+
+      # rubocop:disable-next Naming/PredicateMethod, Metrics/AbcSize -- Verify, atomically upload and verify the owned fact.
+      def reconcile(record:, bootstrap:)
+        bootstrap.files.map do |file|
+          content = @guest.run(record, ['cat', file.path])
+          mode = @guest.run(record, ['stat', '-c', '%a', file.path])
+          next false if valid_file?(content, mode, file)
+
+          Tempfile.create('empeira-fact') do |source|
+            source.write(file.content)
+            source.flush
+            @guest.copy_to(record, source.path, file.path, mode: format('%04o', file.mode))
+          end
+          verify_file!(record, file)
+          true
+        end.any?
+      end
+
+      private
+
+      def verify_file!(record, file)
+        content = @guest.run(record, ['cat', file.path])
+        mode = @guest.run(record, ['stat', '-c', '%a', file.path])
+        return if valid_file?(content, mode, file)
+
+        details = [file_diagnostic(content, file, 'content', 'cat'), file_diagnostic(mode, file, 'mode', 'stat')]
+        raise Error, "Cannot verify required Empeira VM bootstrap file #{file.path}; Puppet was not run\n" \
+                     "#{details.join("\n")}", cause: nil
+      end
+
+      def file_diagnostic(result, file, field, tool)
+        Execution::Diagnostics.command(result, operation: "Bootstrap file #{file.path}: #{field}", tool: tool)
+      end
+
+      def valid_file?(content, mode, file)
+        content.success? && content.stdout == file.content && mode.success? && mode.stdout.strip.to_i(8) == file.mode
+      end
+    end
+  end
+end

data/lib/empeira/node/vm_lifecycle.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Empeira
+  module Node
+    # rubocop:disable-next Metrics/ModuleLength -- Node lifecycle and cleanup share the workspace lock.
+    module VMLifecycle
+      def start(name:)
+        mutate do
+          record = fetch_vm(name)
+          unless record['provisioned']
+            raise Error, 'VM bootstrap is incomplete; inspect logs, then destroy and recreate the node'
+          end
+
+          validate_interfaces(record)
+          ready_server
+          return lifecycle_result(name.downcase, :running, changed: reconcile_guest(record)) if @qemu.running?(record)
+
+          @progress.stage(1, 'Checking VM control-plane readiness...')
+          @engine.preflight!(progress: @progress, seeds: false)
+          boot_existing(record)
+          reconcile_guest(record)
+          lifecycle_result(record.fetch('hostname'), :running, changed: true)
+        end
+      end
+
+      def stop(name:)
+        mutate do
+          record = fetch_vm(name)
+          session_lock(record).exclusive do
+            changed = !!@qemu.stop(record)
+            @peer.stop(record)
+            record['state'] = 'stopped'
+            record['pid'] = nil
+            save
+            lifecycle_result(record.fetch('hostname'), :stopped, changed: changed)
+          end
+        end
+      end
+
+      def destroy(name:)
+        Infrastructure::Cleanup.new(context: context, runner: @runner, runtime: @runtime,
+                                    progress: @progress).node(name)
+      end
+
+      def destroy_all(state:)
+        load_state(state)
+        @runtime.check_available!
+        @bootstrap_proxy.cleanup(@state)
+        vm_records.each_key { |name| remove_vm(name, certificates: false) }
+      end
+
+      def puppet(name:)
+        mutate(availability: false) do
+          record = running_vm(name)
+          @progress.stage(30, 'Running Puppet in VM...')
+          puppet_run(record)
+        end
+      end
+
+      def shell(name:)
+        interactive_vm(name) { |record| @guest.shell(record) }
+      end
+
+      def console(name:)
+        interactive_vm(name) { |record| @qemu.console(record) }
+      end
+
+      def exec(name:, arguments:, timeout: nil, output: $stdout, error: $stderr)
+        DiagnosticCommand.validate!(arguments, timeout)
+        interactive_vm(name) do |record|
+          @guest.stream(record, arguments, timeout: timeout, output: output, error: error)
+        end
+      end
+
+      def ssh(name:, user: nil, identity: nil, port: nil)
+        interactive_vm(name) do |record|
+          ::Empeira::VM::SystemSSH.new(context: context, runner: @runner, runtime: @runtime, qemu: @qemu)
+                                  .session(record, user: user, identity: identity, port: port)
+        end
+      end
+
+      def logs(name:)
+        load_state
+        record = fetch_vm(name)
+        path = @qemu.serial_log(record.fetch('hostname'))
+        raise Error, 'VM serial log is unavailable' unless path.file?
+
+        @runner.stream('tail', arguments: ['-n', '200', '-f', path.to_s])
+      end
+
+      private
+
+      def interactive_vm(name)
+        lock = nil
+        record = mutate do
+          current = booted_vm(name)
+          lock = session_lock(current).acquire(shared: true)
+          current
+        end
+        Execution::Terminal.with_interrupts { @progress.streaming { yield record } }
+      ensure
+        lock&.close
+      end
+
+      def session_lock(record)
+        ::Empeira::VM::SessionLock.new(context: context, record: record)
+      end
+
+      def boot_existing(record)
+        session_lock(record).exclusive { resume_vm(record) }
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- Retained VM restart has ordered, visible milestones.
+      def resume_vm(record)
+        @progress.stage(20, 'Checking retained VM storage...')
+        overlay, seed = existing_storage(record)
+        @progress.stage(30, 'Checking VM network prerequisites...')
+        @peer.preflight(@state)
+        @progress.stage(40, 'Preparing VM network...')
+        @peer.prepare(record, @state)
+        attachment = Network::Peer::Attachment.new(backend: @peer, record: record, state: @state)
+        begin
+          @progress.stage(55, 'Starting virtual machine...')
+          record['pid'] = @qemu.launch(record: record, overlay: overlay, seed: seed, network: attachment)
+        ensure
+          save if record['pid']
+        end
+        @progress.stage(80, 'Waiting for VM management readiness...')
+        @guest.wait(record, progress: @progress)
+        record['state'] = 'running'
+        save
+        @progress.stage(95, 'Virtual machine ready.')
+      end
+
+      def existing_storage(record)
+        ::Empeira::VM::Management.validate!(record)
+        base = base_for(record)
+        unless base.file? && !base.symlink? &&
+               OpenSSL::Digest::SHA256.file(base).hexdigest == record.dig('base_image', 'checksum')
+          raise Error, 'Pinned VM base image is missing or corrupt; preserve the overlay and restore the cache'
+        end
+
+        overlay = @disk.verify!(hostname: record.fetch('hostname'), base: base)
+        seed = vm_directory(record).join('seed.iso')
+        raise Error, 'VM cloud-init seed is missing; preserve the node for recovery' unless seed.file?
+
+        [overlay, seed]
+      end
+
+      def running_vm(name)
+        record = booted_vm(name)
+        unless record['provisioned']
+          raise Error,
+                'VM bootstrap is incomplete; inspect logs or shell before recreating it'
+        end
+
+        record
+      end
+
+      def booted_vm(name)
+        record = fetch_vm(name)
+        unless @qemu.running?(record)
+          raise Error, "VM #{record.fetch('hostname')} is stopped; run empeira node start #{record.fetch('hostname')}"
+        end
+
+        record
+      end
+
+      def remove_vm(name, certificates: true)
+        record = vm_records[name]
+        return unless record
+
+        session_lock(record).exclusive { remove_vm_instance(name, record, certificates: certificates) }
+      end
+
+      def remove_vm_instance(name, record, certificates:)
+        @qemu.stop(record)
+        @peer.destroy(record, @state)
+        @qemu.cleanup(record)
+        clean_vm_certificate(record) if certificates && record['certificate_key']
+        remove_vm_disk(record)
+        remove_vm_directory(record)
+        @nodes.delete(name)
+        save
+        record
+      end
+
+      def clean_vm_certificate(record)
+        Certificates.new(runtime: @runtime, server: ready_server).clean(record)
+      end
+
+      def remove_vm_disk(record)
+        base = base_for(record)
+        overlay = vm_directory(record).join('disk.qcow2')
+        @disk.remove(hostname: record.fetch('hostname'), base: base) if overlay.exist? || overlay.symlink?
+      end
+
+      def remove_vm_directory(record)
+        directory = vm_directory(record)
+        return unless directory.exist? || directory.symlink?
+
+        FileUtils.remove_entry_secure(directory)
+      end
+
+      def vm_directory(record)
+        context.locations.workspace(context.workspace).join('vms', record.fetch('hostname'))
+      end
+    end
+  end
+end

data/lib/empeira/node/vm_preflight.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    module VMPreflight
+      private
+
+      def preflight_vm(request)
+        reject_vm_name!(request.hostname.downcase)
+        ::Empeira::VM::Interfaces.validate_static!(context, request.hostname, @state)
+        accelerator = @engine.preflight!(progress: @progress)
+        @progress.stage(15, 'Validating guest image and bootstrap requirements...')
+        validate_bootstrap(request)
+        image = @source.resolve(distribution: request.os, version: request.version,
+                                architecture: context.platform.architecture)
+        [image, accelerator]
+      end
+
+      def validate_bootstrap(request)
+        @cloud.validate!
+        packages = preflight_packages(request)
+        @requirements = ::Empeira::VM::BootstrapRequirements.new(context: context, os: request.os,
+                                                                 version: request.version,
+                                                                 distribution_required: packages.required?)
+        ::Empeira::Agent::Acquisition.new(context: context, runtime: @runtime).preflight!(@requirements)
+        @peer.preflight(@state)
+        @bootstrap_proxy.preflight!(@state) if @requirements.destinations.any?
+        @progress.heartbeat(@requirements.report)
+      end
+
+      def preflight_packages(request)
+        PackageBootstrap.new(config: context.configuration.dig('bootstrap', 'packages'),
+                             os: request.os, execute: nil)
+      end
+    end
+  end
+end