empeira 0.1.0.pre.alpha.1

data/lib/empeira/progress.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Empeira
+  class Progress
+    Event = Data.define(:percent, :message, :state)
+
+    def initialize(listener: nil)
+      @listener = listener
+      @percent = 0
+      @message = ''
+    end
+
+    def run(message)
+      @active = true
+      @percent = 0
+      emit(message, :active)
+      result = yield
+      @percent = 100
+      emit('Completed.', :complete)
+      result
+    rescue StandardError, Interrupt
+      emit("Failed: #{@message}", :failed)
+      raise
+    ensure
+      @active = false
+    end
+
+    def stage(percent, message)
+      return unless @active
+
+      raise ArgumentError, 'Progress stages must increase and remain below 100' unless percent.between?(@percent, 99)
+
+      @percent = percent
+      emit(message, :active)
+    end
+
+    def heartbeat(message = @message)
+      emit(message, :active) if @active && !@streaming
+    end
+
+    def count(completed, total, message)
+      return unless @active
+      raise ArgumentError, 'Invalid progress counts' unless completed.between?(0, total)
+
+      @percent = completed == total ? 100 : [(100.0 * completed / total).round, 99].min
+      emit(message, :active)
+    end
+
+    def warning(message)
+      @listener&.call(Event.new(percent: @percent, message: message, state: :warning))
+    end
+
+    def streaming
+      @streaming = true
+      emit(@message, :suspended) if @active
+      result = yield
+      emit(@message, :resumed) if @active
+      result
+    ensure
+      @streaming = false
+    end
+
+    private
+
+    def emit(message, state)
+      @message = message
+      @listener&.call(Event.new(percent: @percent, message: message, state: state))
+    end
+  end
+end

data/lib/empeira/project_root.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'shellwords'
+
+module Empeira
+  class ProjectRoot
+    attr_reader :path
+
+    def self.resolve(value, runner: nil, recovery: false)
+      value.is_a?(self) ? value : new(value, runner: runner || Execution::Runner.new, recovery: recovery)
+    end
+
+    def initialize(path, runner: Execution::Runner.new, recovery: false)
+      directory = Pathname(path).realpath
+      raise ConfigurationError, 'project path must be an existing directory' unless directory.directory?
+
+      @path = git_root(directory, runner).freeze
+      require_marker! unless recovery
+      freeze
+    rescue ExecutionError
+      raise ConfigurationError, 'An Empeira Git project is required; ensure Git is installed and accessible.',
+            cause: nil
+    rescue SystemCallError
+      raise ConfigurationError, 'project path must be an existing directory accessible to the current user', cause: nil
+    end
+
+    private
+
+    def git_root(directory, runner)
+      result = runner.run('git', arguments: %w[rev-parse --show-toplevel], directory: directory, timeout: 10)
+      unless result.success? && !result.stdout.strip.empty?
+        raise ConfigurationError, 'An Empeira Git project is required. Enter a Git repository with .empeira.yaml.'
+      end
+
+      Pathname(result.stdout.chomp).realpath
+    end
+
+    def require_marker!
+      marker = @path.join('.empeira.yaml')
+      return if marker.file?
+
+      raise ConfigurationError, "Empeira project #{@path} is missing marker #{marker}. " \
+                                "Opt in with: touch #{Shellwords.escape(marker.to_s)}"
+    end
+  end
+end

data/lib/empeira/providers/lifecycle.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/UnusedMethodArgument -- Preserve explicit adapter keyword contracts.
+
+module Empeira
+  module Providers
+    # Adapters implement the protected operations. Public semantics stay shared.
+    class Lifecycle
+      attr_reader :name, :context, :runner
+
+      def initialize(name:, context:, runner:)
+        @name = name.dup.freeze
+        @context = context
+        @runner = runner
+      end
+
+      def available?
+        false
+      end
+
+      def inspect_resource(name:)
+        resource = lookup(name: name)
+        return if resource.nil?
+
+        verify_resource!(resource, name)
+      end
+
+      def run(name:, request:)
+        raise AlreadyExists, 'Resource already exists' if inspect_resource(name: name)
+
+        resource = verify_resource!(create(name: name, request: request), name)
+        raise ExecutionError, 'Provider did not start the resource' unless resource.state == :running
+
+        Result.new(resource: resource, changed: true)
+      end
+
+      def start(name:)
+        change_state(name, :running)
+      end
+
+      def stop(name:)
+        change_state(name, :stopped)
+      end
+
+      def destroy(name:)
+        resource = inspect_resource(name: name)
+        return Result.new(resource: nil, changed: false) unless resource
+
+        remove(resource: resource)
+        Result.new(resource: nil, changed: true)
+      end
+
+      protected
+
+      def lookup(name:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+
+      def create(name:, request:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+
+      def transition(resource:, state:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+
+      def remove(resource:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+
+      private
+
+      def verify_resource!(resource, expected_name)
+        unless resource.is_a?(Resource) && resource.name == expected_name
+          raise ExecutionError, 'Provider returned an invalid resource'
+        end
+        raise OwnershipError, 'Resource belongs to another workspace' unless resource.owner == context.workspace.id
+
+        resource
+      end
+
+      def change_state(name, state)
+        resource = inspect_resource(name: name)
+        raise NotFound, 'Resource does not exist' unless resource
+        return Result.new(resource: resource, changed: false) if resource.state == state
+
+        updated = verify_resource!(transition(resource: resource, state: state), name)
+        raise ExecutionError, 'Provider did not reach the requested state' unless updated.state == state
+
+        Result.new(resource: updated, changed: true)
+      end
+    end
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/lib/empeira/providers/registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Providers
+    class Registry
+      def initialize(factories)
+        @factories = factories.transform_keys(&:to_s).transform_values(&:freeze).freeze
+        @names = @factories.keys.freeze
+      end
+
+      attr_reader :names
+
+      def build(name, **dependencies)
+        factory = @factories.fetch(name.to_s) do
+          raise Error, "Unknown provider. Choose one of: #{names.join(', ')}"
+        end
+        factory.call(**dependencies)
+      end
+    end
+  end
+end

data/lib/empeira/providers/resource.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Providers
+    class NotFound < Error; end
+    class AlreadyExists < Error; end
+    class OwnershipError < Error; end
+    class ExecutionError < Error; end
+
+    Resource = Data.define(:name, :owner, :state) do
+      def initialize(name:, owner:, state:)
+        unless [name, owner].all? { |value| value.is_a?(String) && !value.empty? }
+          raise Error, 'Resource name and owner must be non-empty strings'
+        end
+        raise Error, 'Resource state must be running or stopped' unless %i[running stopped].include?(state)
+
+        super(name: name.dup.freeze, owner: owner.dup.freeze, state: state)
+      end
+    end
+
+    Result = Data.define(:resource, :changed) do
+      def initialize(resource:, changed:)
+        unless resource.nil? || resource.is_a?(Resource) || resource.is_a?(Network::Resource)
+          raise Error, 'Result resource must be a resource or null'
+        end
+        raise Error, 'Result changed must be boolean' unless [true, false].include?(changed)
+
+        super
+      end
+    end
+  end
+end

data/lib/empeira/providers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/UnusedBlockArgument -- Factories share explicit composition dependencies.
+
+module Empeira
+  module Runtime
+    CATALOG = Providers::Registry.new(
+      'podman' => ->(**dependencies) { Podman.new(**dependencies) },
+      'docker' => ->(**dependencies) { Docker.new(**dependencies) }
+    ).freeze
+
+    def self.registry
+      CATALOG
+    end
+  end
+
+  module VM
+    CATALOG = Providers::Registry.new(
+      'qemu' => ->(**dependencies) { Qemu.new(**dependencies) }
+    ).freeze
+
+    def self.registry
+      CATALOG
+    end
+  end
+
+  module Node
+    CATALOG = Providers::Registry.new(
+      'container' => lambda { |context:, runner:, runtimes:, engines:, build_info:, progress:|
+        runtime = runtimes.build(context.container_engine, context: context, runner: runner)
+        Container.new(context: context, runner: runner, backend: runtime, build_info: build_info, progress: progress)
+      },
+      'vm' => lambda { |context:, runner:, runtimes:, engines:, build_info:, progress:|
+        engine = engines.build('qemu', context: context, runner: runner)
+        runtime = runtimes.build(context.container_engine, context: context, runner: runner)
+        VM.new(context: context, runner: runner, backend: engine, runtime: runtime,
+               build_info: build_info, progress: progress)
+      }
+    ).freeze
+
+    def self.registry
+      CATALOG
+    end
+  end
+
+  module Images
+    CATALOG = Providers::Registry.new('upstream' => -> { Source.new }, 'custom' => -> { Source.new }).freeze
+
+    def self.registry
+      CATALOG
+    end
+  end
+end
+
+# rubocop:enable Lint/UnusedBlockArgument

data/lib/empeira/runtime/agent_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    # Reuses helper ownership and observed default-network verification, without host bind mounts.
+    module AgentHelper
+      def with_agent_helper(image:)
+        identity = Empeira::Services::Definition.new(key: "agent-#{SecureRandom.hex(16)}", workspace: context.workspace)
+        update_command(agent_helper_arguments(identity, image), operation: 'agent helper creation')
+        resource = inspect_service(identity)
+        raise Providers::ExecutionError, 'Agent helper creation could not be verified' unless resource
+
+        update_command(['start', resource.fetch('id')], operation: 'agent helper start')
+        verify_helper_network!(identity, resource.fetch('id'))
+        yield resource
+      ensure
+        remove_update_helper(identity, resource&.fetch('id')) if identity
+      end
+
+      private
+
+      def agent_helper_arguments(identity, image)
+        ['create', '--name', identity.name, '--network', update_helper_network,
+         '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+         *%w[CHOWN DAC_OVERRIDE FOWNER SETUID SETGID].flat_map { |capability| ['--cap-add', capability] },
+         *label_arguments(identity),
+         *UpdateHelper::PROXY_VARIABLES.select { |key| ENV.key?(key) }.flat_map { |key| ['--env', key] },
+         '--entrypoint', 'sleep', image, 'infinity']
+      end
+    end
+
+    Container.include(AgentHelper)
+  end
+end

data/lib/empeira/runtime/container.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Empeira
+  module Runtime
+    class Unavailable < Providers::ExecutionError; end
+    class UnsupportedCapability < Providers::ExecutionError; end
+
+    # Keep the common network lifecycle and its failure semantics in one adapter boundary.
+    # rubocop:disable-next Metrics/ClassLength
+    class Container < Interface
+      def available?
+        check_available!
+        true
+      rescue Unavailable, UnsupportedCapability
+        false
+      end
+
+      def check_available!
+        @engine_info = json_command(info_arguments, operation: 'engine detection')
+        validate_info!(@engine_info)
+        true
+      rescue Providers::ExecutionError => e
+        raise if e.is_a?(UnsupportedCapability)
+
+        raise Unavailable, "#{name} is unavailable. Install its CLI and start/reach its engine. #{e.message}",
+              cause: nil
+      end
+
+      def architecture
+        check_available! unless @engine_info
+        cpu = @engine_info['Architecture'] || @engine_info.dig('host', 'arch')
+        Platform::Facts.new(host_os: 'linux', host_cpu: cpu.to_s).architecture.to_s
+      end
+
+      def require_systemd!
+        check_available! unless @engine_info
+        return if name == 'podman' && @engine_info.dig('host', 'cgroupVersion') == 'v2'
+
+        raise UnsupportedCapability, 'systemd nodes require Podman with cgroup v2; select node_defaults.init=process'
+      end
+
+      def node_ssh_publication?
+        false
+      end
+
+      def capabilities
+        { isolated: true, controlled_egress: false }
+      end
+
+      def inspect_network(identifier:)
+        entry = network_entries.find { |item| [item.fetch('id'), item.fetch('name')].include?(identifier) }
+        return unless entry
+
+        inspect_entry(entry)
+      end
+
+      # rubocop:disable-next Naming/PredicateMethod -- Verification raises on failure.
+      def verify_isolated_network(definition, expected_id:)
+        data = json_command(['network', 'inspect', definition.backend_name],
+                            operation: 'node network verification')
+        malformed! unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash)
+        binding = normalize_network_binding(data.first)
+        definition.verify_ownership!(binding, expected_id: expected_id)
+        definition.verify_definition!(binding)
+        definition.verify_isolation!(binding)
+        true
+      end
+
+      def create_network(definition:)
+        definition.policy.require_support!(**capabilities)
+        existing = inspect_network(identifier: definition.backend_name)
+        if existing
+          definition.verify_ownership!(existing)
+          definition.verify_definition!(existing)
+          definition.verify_isolation!(existing)
+          return Providers::Result.new(resource: existing, changed: false)
+        end
+
+        mutate_network(definition, 'create', create_arguments(definition))
+        resource = inspect_network(identifier: definition.backend_name)
+        definition.verify_ownership!(resource)
+        definition.verify_isolation!(resource)
+        Providers::Result.new(resource: resource, changed: true)
+      end
+
+      def remove_network(definition:, expected_id: nil)
+        resource = inspect_network(identifier: definition.backend_name)
+        definition.verify_ownership!(resource, expected_id: expected_id)
+        return Providers::Result.new(resource: nil, changed: false) unless resource
+
+        raise Providers::ExecutionError, "#{name} network still has attached resources; detach them before down" unless
+          resource.attachment_count.zero?
+
+        mutate_network(definition, 'remove', ['network', 'rm', resource.id])
+        if inspect_network(identifier: definition.backend_name)
+          raise Providers::ExecutionError, "#{name} network removal could not be verified"
+        end
+
+        Providers::Result.new(resource: nil, changed: true)
+      end
+
+      def network_subnets
+        network_entries.flat_map do |entry|
+          data = json_command(['network', 'inspect', entry.fetch('id')], operation: 'subnet inventory').first
+          subnets = data['subnets'] || data.dig('IPAM', 'Config') || []
+          subnets.filter_map { |item| item['subnet'] || item['Subnet'] }
+        end
+      end
+
+      def network_details(identifier)
+        json_command(['network', 'inspect', identifier], operation: 'peer network inspection').first
+      end
+
+      protected
+
+      def command(arguments, operation:)
+        result = runner.run(name, arguments: arguments, timeout: 30)
+        return result if result.success?
+
+        outcome = result.timed_out ? 'timed out' : "exit #{result.exit_status.inspect}"
+        raise Providers::ExecutionError,
+              "#{name} #{operation} failed (#{outcome}) for workspace #{context.workspace.id}"
+      rescue Empeira::ExecutionError
+        raise Providers::ExecutionError,
+              "#{name} #{operation} could not execute. Check CLI installation and permissions.",
+              cause: nil
+      end
+
+      def json_command(arguments, operation:)
+        parse_json(command(arguments, operation: operation).stdout)
+      end
+
+      def parse_json(output)
+        JSON.parse(output)
+      rescue JSON::ParserError
+        malformed!
+      end
+
+      def malformed!
+        raise Providers::ExecutionError, "#{name} returned malformed network/engine data", cause: nil
+      end
+
+      def label_arguments(definition)
+        definition.labels.flat_map { |key, value| ['--label', "#{key}=#{value}"] }
+      end
+
+      def validate_entries(entries)
+        unless entries.is_a?(Array) && entries.all? do |item|
+          item.is_a?(Hash) && %w[id name].all? do |key|
+            item[key].is_a?(String) && item[key].match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/)
+          end
+        end
+          malformed!
+        end
+        entries
+      end
+
+      private
+
+      def inspect_entry(entry)
+        data = json_command(['network', 'inspect', entry.fetch('id')], operation: 'network inspection')
+        malformed! unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash)
+        resource = normalize_network(data.first)
+        malformed! unless resource.id == entry.fetch('id') && resource.name == entry.fetch('name')
+        resource
+      end
+
+      def mutate_network(definition, operation, arguments)
+        command(arguments, operation: "network #{operation}")
+      rescue Providers::ExecutionError, Interrupt => e
+        # A failed command may have committed. Inspect once, never blindly retry.
+        observed = inspect_network(identifier: definition.backend_name)
+        definition.verify_ownership!(observed)
+        raise e if e.is_a?(Interrupt)
+
+        outcome = observed ? 'present' : 'absent'
+        raise Providers::ExecutionError, "#{e.message}. Network observed #{outcome}; run status before retrying.",
+              cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/runtime/diagnostic_execution.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    module DiagnosticExecution
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- Stream, cancellation receipt and pipe closure share one transaction.
+      def diagnostic_exec(resource, arguments, timeout: nil, output: $stdout, error: $stderr)
+        token = SecureRandom.hex(16)
+        code = Pathname(__dir__).join('../../../resources/nodes/diagnostic_exec.rb').read
+        IO.pipe do |input, control|
+          native = runner.controlled_stream(name, arguments: ['exec', '--interactive', '--user', '0',
+                                                              resource.fetch('id'), ControlPlane::Health::RUBY,
+                                                              '-e', code, '--', 'run', token,
+                                                              timeout ? timeout.to_s : 'none', *arguments],
+                                                  input: input, control: control, output: output, error: error)
+          diagnostic_completion(resource, code, token, native)
+        rescue SignalException
+          native = Execution::Result.new(stdout: '', stderr: '', exit_status: 130, timed_out: false)
+          diagnostic_completion(resource, code, token, native)
+          raise
+        ensure
+          control.close unless control.closed?
+        end
+      end
+
+      private
+
+      def valid_diagnostic_completion?(data)
+        data.is_a?(Hash) && [true, false].include?(data['timed_out']) &&
+          ((data['status'].is_a?(Integer) && data['status'].between?(0, 255)) ||
+            (data['status'].nil? && data['timed_out']))
+      end
+
+      def diagnostic_completion(resource, code, token, native)
+        result = runner.run(name, arguments: ['exec', '--user', '0', resource.fetch('id'),
+                                              ControlPlane::Health::RUBY, '-e', code, '--', 'read', token], timeout: 10)
+        data = JSON.parse(result.stdout) if result.success?
+        if valid_diagnostic_completion?(data)
+          return Execution::Result.new(stdout: '', stderr: '', exit_status: data['status'],
+                                       timed_out: data['timed_out'])
+        end
+
+        details = Execution::Diagnostics.command(native, operation: 'Container diagnostic transport', tool: name)
+        raise Error, "Container command completion or cancellation is unconfirmed; node retained\n#{details}"
+      rescue JSON::ParserError
+        raise Error, 'Container command completion is malformed; node retained', cause: nil
+      end
+    end
+  end
+end
+
+Empeira::Runtime::Container.include(Empeira::Runtime::DiagnosticExecution)

data/lib/empeira/runtime/docker.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    class Docker < Container
+      def initialize(context:, runner:)
+        super(name: 'docker', context: context, runner: runner)
+      end
+
+      protected
+
+      def remote_descriptors(image)
+        result = metadata_command(['manifest', 'inspect', '--verbose', image], image: image)
+        data = parse_json(result.stdout)
+        entries = data.is_a?(Array) ? data : [data]
+        entries.map { |entry| entry.is_a?(Hash) ? entry['Descriptor'] : nil }
+      end
+
+      def info_arguments
+        ['info', '--format', '{{json .}}']
+      end
+
+      def validate_info!(info)
+        malformed! unless info.is_a?(Hash) && info['ServerVersion'].is_a?(String)
+        version = info['ServerVersion'][/\A\d+/].to_i
+        return if version >= 28 && bridge_available?(info['Plugins']) && info['OSType'] == 'linux'
+
+        raise UnsupportedCapability, 'Docker requires a Linux engine >= 28 with bridge and isolated gateway support'
+      end
+
+      def bridge_available?(plugins)
+        plugins.is_a?(Hash) && plugins['Network'].is_a?(Array) && plugins['Network'].include?('bridge')
+      end
+
+      def network_entries
+        output = command(['network', 'ls', '--no-trunc', '--format', '{{json .}}'],
+                         operation: 'network inventory').stdout
+        entries = output.lines.reject { |line| line.strip.empty? }.map do |line|
+          item = parse_json(line)
+          malformed! unless item.is_a?(Hash)
+          { 'id' => item['ID'], 'name' => item['Name'] }
+        end
+        validate_entries(entries)
+      end
+
+      def create_arguments(definition)
+        if definition.is_a?(Network::Egress)
+          return ['network', 'create', '--driver', 'bridge', *label_arguments(definition), definition.backend_name]
+        end
+
+        ['network', 'create', '--driver', 'bridge', '--internal',
+         '--opt', 'com.docker.network.bridge.gateway_mode_ipv4=isolated',
+         '--opt', 'com.docker.network.bridge.gateway_mode_ipv6=isolated',
+         *peer_network_options(definition), *label_arguments(definition), definition.backend_name]
+      end
+
+      def peer_network_options(definition)
+        return [] unless definition.allocation
+
+        layout = Network::Peer::Layout.new(definition.allocation)
+        ['--subnet', layout.subnet, '--ip-range', layout.container_pool,
+         '--opt', "com.docker.network.bridge.name=ep#{context.workspace.id[0, 10]}"]
+      end
+
+      def isolated_gateways?(options)
+        %w[ipv4 ipv6].all? { |family| options["com.docker.network.bridge.gateway_mode_#{family}"] == 'isolated' }
+      end
+
+      def isolated?(data)
+        data['Internal'] && data['Driver'] == 'bridge' && isolated_gateways?(data['Options'])
+      end
+
+      def normalize_network_binding(data)
+        malformed! unless data['Options'].is_a?(Hash) && [true, false].include?(data['Internal'])
+        Network::Binding.new(id: data['Id'], name: data['Name'], labels: data['Labels'] || {},
+                             isolated: isolated?(data))
+      end
+
+      def normalize_network(data)
+        binding = normalize_network_binding(data)
+        containers = data['Containers']
+        malformed! unless containers.is_a?(Hash)
+        Network::Resource.new(**binding.to_h, attachment_count: containers.size)
+      end
+    end
+  end
+end