empeira 0.1.0.pre.alpha.1

data/lib/empeira/vm/qemu_runtime.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'socket'
+require 'timeout'
+
+module Empeira
+  module VM
+    # QEMU process control is a replaceable VM-engine concern.
+    # rubocop:disable-next Metrics/ClassLength -- Launch and ownership-safe monitor control form one engine boundary.
+    class QemuRuntime
+      def initialize(engine:, runner:, context:)
+        @engine = engine
+        @runner = runner
+        @context = context
+      end
+
+      def launch(record:, overlay:, seed:, network:)
+        Management.validate!(record)
+        hostname = record.fetch('hostname')
+        monitor = monitor_path(hostname)
+        ensure_launchable_monitor!(record, monitor)
+        execute_launch(record, overlay, seed, network, monitor)
+      end
+
+      def running?(record)
+        monitor = monitor_path(record.fetch('hostname'))
+        return false unless monitor.socket?
+
+        Timeout.timeout(2) do
+          UNIXSocket.open(monitor) do |socket|
+            read_monitor_prompt(socket)
+            verify_monitor_identity!(socket, record)
+            true
+          end
+        end
+      rescue SystemCallError, IOError, Timeout::Error
+        false
+      end
+
+      def observed_running?(record)
+        process_alive?(record) && monitor_path(record.fetch('hostname')).socket?
+      end
+
+      def stop(record)
+        unless running?(record)
+          raise Error, 'QEMU process is alive but monitor is unavailable; VM disk retained' if process_alive?(record)
+
+          return nil
+        end
+
+        monitor_command(record, 'system_powerdown')
+        wait_for_shutdown(record)
+        if running?(record)
+          monitor_command(record, 'quit')
+          wait_for_shutdown(record, seconds: 5)
+        end
+        raise Error, 'QEMU did not stop; VM overlay retained' if running?(record)
+
+        File.unlink(monitor_path(record.fetch('hostname'))) if monitor_path(record.fetch('hostname')).exist?
+        record
+      end
+
+      def cleanup(record)
+        raise Error, 'QEMU process is still alive; monitor state retained' if process_alive?(record)
+
+        directory = monitor_directory(record.fetch('hostname'))
+        return unless directory.exist? || directory.symlink?
+
+        validate_monitor_directory!(directory)
+        validate_management_cleanup!(record)
+        unlink_monitor_socket(directory.join('monitor.sock'))
+        unlink_monitor_socket(directory.join('console.sock'))
+        unlink_management_socket(record)
+        Dir.rmdir(directory)
+      end
+
+      def process_alive?(record)
+        pid = record['pid'] || unrecorded_pid(record)
+        return false unless pid.is_a?(Integer) && pid.positive?
+
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+
+      def unrecorded_pid(record)
+        path = pid_path(record.fetch('hostname'))
+        return unless path.exist? || path.symlink?
+
+        root = @context.locations.workspace(@context.workspace)
+        Infrastructure::OwnedFiles.verify_removable!(path, root: root)
+        value = File.read(path, 32).strip
+        unless value.match?(/\A[1-9][0-9]{0,9}\z/)
+          raise Error, 'QEMU PID file is not safely interpretable; VM disk retained'
+        end
+
+        Integer(value, 10)
+      end
+
+      def serial_log(hostname)
+        node_directory(hostname).join('serial.log')
+      end
+
+      def console(record)
+        raise Error, 'VM is stopped; start it before attaching the console' unless running?(record)
+
+        path = console_path(record.fetch('hostname'))
+        validate_monitor_directory!(path.dirname)
+        metadata = path.lstat
+        unless metadata.socket? && metadata.uid == Process.uid
+          raise Providers::OwnershipError, 'VM console endpoint ownership is invalid'
+        end
+
+        @runner.console(path, guidance: console_guidance(record.fetch('hostname')))
+      rescue Errno::ENOENT
+        raise Error, 'VM console endpoint is missing'
+      end
+
+      def console_path(hostname)
+        monitor_directory(hostname).join('console.sock')
+      end
+
+      def management_socket(record)
+        Management.validate!(record)
+        raise Error, 'VM is stopped; management unavailable' unless running?(record)
+
+        path = management_path(record.fetch('hostname'))
+        verify_management_socket!(record, path)
+        path
+      end
+
+      def with_management_socket(record)
+        Management.validate!(record)
+        raise Error, 'VM is stopped; management unavailable' unless running?(record)
+
+        Management::SLOTS.times do |slot|
+          path = management_path(record.fetch('hostname'), slot)
+          expected = slot.zero? ? record['management_socket'] : record.dig('management_sockets', slot.to_s)
+          verify_management_socket!(record, path, expected: expected)
+          lock = management_slot_lock(path)
+          next unless lock
+
+          begin
+            return yield path, expected
+          ensure
+            lock.close
+          end
+        end
+        raise Error, 'All eight VM management sessions are busy; detach a session and retry'
+      end
+
+      private
+
+      def console_guidance(hostname)
+        message = "Connected to VM serial console.\nPress Ctrl+] to detach. The VM will keep running.\n"
+        return message if @context.configuration.dig('vm', 'console', 'root_password')
+
+        "#{message}No console password is configured. Use empeira node ssh #{hostname} instead.\n"
+      end
+
+      def validate_monitor_directory!(directory)
+        metadata = File.lstat(directory)
+        return if metadata.directory? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+
+        raise Error, 'VM monitor directory ownership changed; cleanup refused'
+      end
+
+      def unlink_monitor_socket(socket)
+        return unless socket.exist? || socket.symlink?
+
+        if socket.symlink? || !socket.lstat.socket? || socket.lstat.uid != Process.uid
+          raise Error, 'Unexpected VM monitor path; cleanup refused'
+        end
+
+        File.unlink(socket) if socket.socket?
+      end
+
+      def ensure_launchable_monitor!(record, monitor)
+        prepare_monitor_directory(record.fetch('hostname'))
+        raise Error, 'Recorded QEMU process is still alive; refusing a second launch' if process_alive?(record)
+
+        unlink_management_socket(record)
+        unlink_monitor_socket(console_path(record.fetch('hostname')))
+        File.unlink(monitor) if monitor.socket? && !running?(record)
+        raise Error, 'VM monitor already exists; inspect the recorded process first' if monitor.exist?
+      end
+
+      def execute_launch(record, overlay, seed, network, monitor)
+        arguments = launch_arguments(record, overlay, seed, network.arguments, monitor)
+        network.launch(@engine.executable, arguments)
+
+        pid = Integer(File.read(pid_path(record.fetch('hostname'))).strip)
+        record['pid'] = pid
+        raise Error, 'QEMU did not create its owned monitor socket' unless running?(record)
+
+        capture_management_socket!(record)
+        network.connect
+
+        pid
+      end
+
+      def wait_for_shutdown(record, seconds: 30)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        while (running?(record) || process_alive?(record)) && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          sleep 0.25
+        end
+      end
+
+      def launch_arguments(record, overlay, seed, network, monitor)
+        hostname = record.fetch('hostname')
+        arch = @context.platform.architecture
+        machine = arch == :arm64 ? 'virt' : 'q35'
+        ['-name', process_name(record), '-machine', machine,
+         '-accel', @engine.accelerator, '-cpu', 'host', '-m', record.fetch('memory').to_s,
+         '-smp', record.fetch('cpus').to_s, '-display', 'none', '-daemonize',
+         '-chardev', console_device(hostname), '-serial', 'chardev:console',
+         '-pidfile', pid_path(hostname).to_s,
+         '-monitor', "unix:#{escape(monitor)},server=on,wait=off",
+         *management_devices(hostname), *boot_drives(overlay, seed), *firmware(arch), *network]
+      end
+
+      def management_devices(hostname)
+        ['-device', 'virtio-serial-pci,id=management', *Management::SLOTS.times.flat_map do |slot|
+          identifier = slot.zero? ? 'management' : "management#{slot}"
+          ['-chardev', "socket,id=#{identifier},path=#{escape(management_path(hostname, slot))},server=on,wait=off",
+           '-device', "virtserialport,chardev=#{identifier},name=org.empeira.management.#{slot}"]
+        end]
+      end
+
+      def management_path(hostname, slot = 0)
+        monitor_directory(hostname).join(slot.zero? ? 'guest.sock' : "guest-#{slot}.sock")
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Pin each private VirtIO endpoint before exposing management.
+      def capture_management_socket!(record)
+        record['management_sockets'] = Management::SLOTS.times.to_h do |slot|
+          path = management_path(record.fetch('hostname'), slot)
+          validate_monitor_directory!(path.dirname)
+          metadata = path.lstat
+          unless metadata.socket? && metadata.uid == Process.uid
+            raise Providers::OwnershipError, 'QEMU management endpoint is unsafe; VM retained'
+          end
+
+          File.chmod(0o600, path)
+          [slot.to_s, { 'device' => metadata.dev, 'inode' => metadata.ino }]
+        end
+        record['management_socket'] = record['management_sockets'].fetch('0')
+        verify_management_socket!(record, management_path(record.fetch('hostname')))
+      end
+
+      def verify_management_socket!(record, path, expected: record['management_socket'])
+        validate_monitor_directory!(path.dirname)
+        metadata = path.lstat
+        unless metadata.socket? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077) &&
+               expected == { 'device' => metadata.dev, 'inode' => metadata.ino }
+          raise Providers::OwnershipError,
+                'VM management socket ownership or recorded identity changed; operation refused'
+        end
+      end
+
+      def validate_management_cleanup!(record)
+        path = management_path(record.fetch('hostname'))
+        verify_management_socket!(record, path) if path.exist? || path.symlink?
+      end
+
+      def unlink_management_socket(record)
+        Management::SLOTS.times do |slot|
+          path = management_path(record.fetch('hostname'), slot)
+          if path.exist? || path.symlink?
+            expected = slot.zero? ? record['management_socket'] : record.dig('management_sockets', slot.to_s)
+            verify_management_socket!(record, path, expected: expected)
+            File.unlink(path)
+          end
+          lock = Pathname("#{path}.lock")
+          unlink_management_lock(lock) if lock.exist? || lock.symlink?
+        end
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity -- Ownership and nonblocking acquisition precede transferring the live descriptor.
+      def management_slot_lock(path)
+        target = Pathname("#{path}.lock")
+        raise Providers::OwnershipError, 'VM management session lock is a symlink' if target.symlink?
+
+        # rubocop:disable-next Style/FileOpen -- The caller owns and closes the acquired slot descriptor.
+        lock = File.open(target, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+        metadata = lock.stat
+        unless metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+          raise Providers::OwnershipError, 'VM management session lock ownership is invalid'
+        end
+
+        acquired = lock.flock(File::LOCK_EX | File::LOCK_NB)
+        acquired ? lock : nil
+      ensure
+        lock&.close unless acquired
+      end
+
+      def unlink_management_lock(path)
+        metadata = path.lstat
+        unless metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+          raise Providers::OwnershipError, 'VM management session lock ownership is invalid'
+        end
+
+        File.unlink(path)
+      end
+
+      def console_device(hostname)
+        "socket,id=console,path=#{escape(console_path(hostname))},server=on,wait=off," \
+          "logfile=#{escape(serial_log(hostname))},logappend=on"
+      end
+
+      def boot_drives(overlay, seed)
+        ['-drive', "file=#{escape(overlay)},if=virtio,format=qcow2,cache=none",
+         '-drive', "file=#{escape(seed)},if=virtio,format=raw,readonly=on"]
+      end
+
+      def firmware(architecture)
+        return [] unless architecture == :arm64
+
+        ['-bios', @engine.firmware.to_s]
+      end
+
+      def escape(path)
+        path.to_s.gsub(',', ',,')
+      end
+
+      def monitor_command(record, command)
+        Timeout.timeout(3) do
+          UNIXSocket.open(monitor_path(record.fetch('hostname'))) do |socket|
+            read_monitor_prompt(socket)
+            verify_monitor_identity!(socket, record)
+            socket.write("#{command}\n")
+            command == 'quit' ? wait_monitor_close(socket) : read_monitor_prompt(socket)
+          end
+        end
+      rescue SystemCallError, IOError, Timeout::Error
+        raise Error, 'Cannot control the recorded QEMU process', cause: nil
+      end
+
+      def process_name(record)
+        "empeira-#{@context.workspace.id}-#{record.fetch('hostname')}-#{record.fetch('peer').fetch('token')}"
+      end
+
+      def verify_monitor_identity!(socket, record)
+        socket.write("info name\n")
+        return if read_monitor_prompt(socket).include?(process_name(record))
+
+        raise Providers::OwnershipError, 'QEMU monitor belongs to a different node instance; control refused'
+      end
+
+      def wait_monitor_close(socket)
+        loop { socket.readpartial(1024) }
+      rescue EOFError
+        nil
+      end
+
+      def read_monitor_prompt(socket)
+        buffer = +''
+        buffer << socket.readpartial(1024) until buffer.include?('(qemu)') || buffer.bytesize > 16_384
+        raise Error, 'Unexpected QEMU monitor response' unless buffer.include?('(qemu)')
+
+        buffer
+      end
+
+      def monitor_path(hostname)
+        path = monitor_directory(hostname).join('monitor.sock')
+        raise Error, 'Temporary path is too long for a QEMU monitor socket' if path.to_s.bytesize > 100
+
+        path
+      end
+
+      def monitor_directory(hostname)
+        identifier = Digest::SHA256.hexdigest("#{@context.workspace.id}:#{hostname}")[0, 24]
+        [@context.locations.temporary, @context.locations.home].each do |root|
+          directory = root.join("empeira-#{identifier}")
+          return directory if directory.join('monitor.sock').to_s.bytesize <= 100
+        end
+
+        raise Error, 'No short private path is available for a QEMU monitor socket'
+      end
+
+      def prepare_monitor_directory(hostname)
+        directory = monitor_directory(hostname)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        metadata = File.lstat(directory)
+        return if metadata.directory? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+
+        raise Error, 'VM monitor directory is not private to the current user'
+      end
+
+      def node_directory(hostname)
+        @context.locations.workspace(@context.workspace).join('vms', hostname)
+      end
+
+      def pid_path(hostname)
+        node_directory(hostname).join('qemu.pid')
+      end
+    end
+  end
+end

data/lib/empeira/vm/removal.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Removal validates host ownership and never contacts the guest or verifies base-image contents.
+    class Removal
+      def initialize(context:, runner:, runtime:, store:)
+        @context = context
+        @runner = runner
+        @runtime = runtime
+        @store = store
+      end
+
+      def remove(record, state)
+        root = @store.directory
+        path = root.join('vms', record.fetch('hostname'))
+        Infrastructure::OwnedFiles.verify_removable!(path, root: root)
+        SessionLock.new(context: @context, record: record).exclusive do
+          engine = VM.registry.build('qemu', context: @context, runner: @runner)
+          qemu = QemuRuntime.new(engine: engine, runner: @runner, context: @context)
+          peer = Network::Peer::Backend.build(context: @context, runtime: @runtime, runner: @runner, store: @store)
+          qemu.stop(record)
+          peer.destroy(record, state)
+          qemu.cleanup(record)
+          Infrastructure::OwnedFiles.remove(path, root: root)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/vm/root_disk.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Empeira
+  module VM
+    # Observe cloud-init growth before package bootstrap without changing guest partitions.
+    class RootDisk
+      ALIGNMENT_MARGIN = 16 * (1024**2)
+
+      def initialize(guest:)
+        @guest = guest
+      end
+
+      def verify!(record, size_gib:)
+        data = JSON.parse(observe(record, %w[lsblk --json --bytes --paths --output NAME,TYPE,SIZE,MOUNTPOINT]))
+        raise TypeError unless data.is_a?(Hash)
+
+        root, disk = root_device(data.fetch('blockdevices'))
+        verify_partition!(root, disk, size_gib * Disk::GIB)
+        verify_filesystem!(record, root)
+      rescue JSON::ParserError, KeyError, TypeError, ArgumentError
+        raise Error, 'Cannot verify VM root disk growth: malformed guest disk metadata; inspect cloud-init logs',
+              cause: nil
+      end
+
+      private
+
+      def verify_filesystem!(record, root)
+        capacity = Integer(observe(record, ['df', '--block-size=1', '--output=size', '/']).lines.last, 10)
+        root_size = byte_size(root)
+        return if capacity.between?(root_size * 95 / 100, root_size)
+
+        raise Error, "VM root filesystem has not grown: #{root.fetch('name')} partition=#{root_size} bytes, " \
+                     "filesystem=#{capacity} bytes; inspect cloud-init logs"
+      end
+
+      def observe(record, arguments)
+        result = @guest.run(record, arguments)
+        return result.stdout if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: 'Verify VM root disk growth', tool: arguments.first)
+        raise Error, "Cannot verify VM root disk growth\n#{details}", cause: nil
+      end
+
+      def root_device(devices)
+        roots = device_pairs(devices).select { |device, _parent| device['mountpoint'] == '/' }
+        unless roots.size == 1
+          raise Error,
+                'Cannot identify a unique VM root partition from lsblk; inspect cloud-init logs'
+        end
+
+        root, disk = roots.first
+        unless root['type'] == 'part' && disk && disk['type'] == 'disk'
+          raise Error, 'Cannot verify VM root growth for this block-device layout; inspect cloud-init logs'
+        end
+
+        [root, disk]
+      end
+
+      def device_pairs(devices, parent = nil)
+        raise TypeError unless devices.is_a?(Array) && devices.all?(Hash)
+
+        devices.flat_map { |device| [[device, parent], *device_pairs(device.fetch('children', []), device)] }
+      end
+
+      def verify_partition!(root, disk, expected)
+        free = unpartitioned(disk)
+        disk_size = byte_size(disk)
+        return if disk_size == expected && free.between?(0, ALIGNMENT_MARGIN)
+
+        raise Error, "VM root partition has not grown: #{root.fetch('name')}, disk=#{disk_size} bytes, " \
+                     "expected=#{expected} bytes, unpartitioned=#{free} bytes; inspect cloud-init logs"
+      end
+
+      def unpartitioned(disk)
+        partitions = disk.fetch('children').select { |device| device['type'] == 'part' }
+        sizes = [byte_size(disk), *partitions.map { |partition| byte_size(partition) }]
+
+        sizes.first - sizes.drop(1).sum
+      end
+
+      def byte_size(device)
+        size = device.fetch('size')
+        size = Integer(size, 10) if size.is_a?(String) && size.match?(/\A[0-9]+\z/)
+        raise TypeError unless size.is_a?(Integer) && size.positive?
+
+        size
+      end
+    end
+  end
+end

data/lib/empeira/vm/session_lock.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Pin one node instance during access without retaining the workspace mutation lock.
+    class SessionLock
+      def initialize(context:, record:)
+        directory = context.locations.workspace(context.workspace)
+        @path = directory.join("vm-session-#{record.fetch('peer').fetch('token')}.lock")
+      end
+
+      def acquire(shared:)
+        lock = open_lock
+        mode = shared ? File::LOCK_SH : File::LOCK_EX
+        unless lock.flock(mode | File::LOCK_NB)
+          raise Infrastructure::Locked, 'VM instance has active access or lifecycle operations; detach and retry'
+        end
+
+        lock.close_on_exec = true
+        acquired = true
+        lock
+      ensure
+        lock&.close unless acquired
+      end
+
+      def exclusive
+        lock = acquire(shared: false)
+        yield
+      ensure
+        lock&.close
+      end
+
+      private
+
+      def open_lock
+        raise Providers::OwnershipError, 'VM session lock path is unsafe' if @path.dirname.symlink? || @path.symlink?
+
+        # A successful open passes descriptor ownership to acquire.
+        # rubocop:disable-next Style/FileOpen
+        lock = File.open(@path, File::RDWR | File::CREAT, 0o600)
+        verify_lock!(lock.stat)
+
+        opened = true
+        lock
+      ensure
+        lock&.close unless opened
+      end
+
+      def verify_lock!(metadata)
+        return if metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+
+        raise Providers::OwnershipError, 'VM session lock ownership is invalid'
+      end
+    end
+  end
+end

data/lib/empeira/vm/system_ssh.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Direct peer transport; system login never invokes the privileged management channel.
+    class SystemSSH
+      def initialize(context:, runner:, runtime:, qemu:)
+        @context = context
+        @runner = runner
+        @qemu = qemu
+        @peer = Network::Peer::Backend.build(context: context, runner: runner, runtime: runtime,
+                                             store: Infrastructure::Store.new(context: context))
+      end
+
+      def session(record, user: nil, identity: nil, port: nil)
+        selected = Configuration::SSHPreferences.port!(port || 22)
+        raise Error, 'Recorded VM is not running; system SSH refused' unless @qemu.running?(record)
+
+        proxy = @peer.system_ssh_command(record, port: selected)
+        endpoint = record.merge('ssh_port' => selected)
+        credentials = Node::SSHCredentials.new(context: @context, runner: @runner, provider: 'vm',
+                                               hostname: record.fetch('hostname'), purpose: :system)
+        Node::UserSSH.new(runner: @runner, credentials: credentials, proxy_command: proxy,
+                          default_user: CloudInit::USER, managed_identity: true,
+                          home: @context.locations.home).session(endpoint, user: user, identity: identity)
+      end
+    end
+  end
+end

data/lib/empeira/workspace.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'pathname'
+
+module Empeira
+  class Workspace
+    attr_reader :id, :path
+
+    def self.recover(path, user_home: Dir.home)
+      root = recovery_root(path)
+      user = Pathname(user_home).realpath.to_s
+      identity = allocate
+      identity.instance_variable_set(:@id, Digest::SHA256.hexdigest(JSON.generate([user, root.to_s]))[0, 24].freeze)
+      identity.instance_variable_set(:@path, root.freeze)
+      identity.freeze
+    rescue SystemCallError
+      raise ConfigurationError, 'Recovery project path and user home must be accessible'
+    end
+
+    def self.recovery_root(path)
+      unless path.is_a?(String) && !path.include?("\0") && Pathname(path).absolute?
+        raise ConfigurationError, 'Recovery project path must be an absolute former Git root path'
+      end
+
+      root = Pathname(path).cleanpath
+      root.exist? ? root.realpath : root
+    end
+
+    def initialize(path: Dir.pwd, user_home: Dir.home)
+      @path = ProjectRoot.resolve(path).path
+      raise ConfigurationError, 'project path must be a directory' unless @path.directory?
+
+      user = Pathname(user_home).realpath.to_s
+      @id = Digest::SHA256.hexdigest(JSON.generate([user, @path.to_s]))[0, 24].freeze
+      freeze
+    rescue SystemCallError
+      raise ConfigurationError, 'project path and user home must exist and be accessible'
+    end
+  end
+end