empeira 0.1.0.pre.alpha.1

data/lib/empeira/runtime/image_metadata.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    # Native CLIs own registry authentication, manifest negotiation and transport.
+    module ImageMetadata
+      def with_image_updates
+        previous = @image_metadata
+        @image_metadata = {}
+        yield
+      ensure
+        @image_metadata = previous
+      end
+
+      def remote_digest(image)
+        return @image_metadata.fetch(image) if @image_metadata&.key?(image)
+
+        digest = platform_digest(remote_descriptors(image))
+        @image_metadata[image] = digest if @image_metadata
+        digest
+      rescue Error => e
+        raise Providers::ExecutionError, "Image metadata check failed for #{image}: #{e.message}", cause: nil
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize -- Validate descriptor shape, platform and unambiguous digest together.
+      def platform_digest(descriptors)
+        unless descriptors.is_a?(Array) && descriptors.all?(Hash)
+          raise Providers::ExecutionError, 'Runtime returned malformed image descriptors'
+        end
+
+        selected = descriptors.select { |entry| matching_platform?(entry['platform']) }
+        digests = selected.map { |entry| entry['digest'] }.uniq
+        unless digests.size == 1 && valid_digest?(digests.first)
+          raise Providers::ExecutionError, "No unambiguous Linux/#{architecture} manifest digest in runtime metadata"
+        end
+
+        digests.first
+      end
+
+      def matching_platform?(platform)
+        return false unless platform.is_a?(Hash)
+
+        platform['os'] == 'linux' && platform['architecture'] == architecture &&
+          (platform['variant'].to_s.empty? || (architecture == 'arm64' && platform['variant'] == 'v8'))
+      end
+
+      def valid_digest?(value)
+        value.is_a?(String) && value.match?(Images::Configuration::DIGEST)
+      end
+
+      def metadata_command(arguments, image:, timeout: 30)
+        update_command(arguments, operation: 'remote image metadata', timeout: timeout, registry: image)
+      end
+
+      def local_image(image)
+        result = local_image_inspection(image)
+        return unless result.success?
+
+        data = parse_json(result.stdout)
+        malformed! unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash)
+        data.first
+      end
+
+      def local_digests(data)
+        [data['Digest'], *Array(data['RepoDigests']).map { |value| value.to_s.split('@', 2)[1] }]
+          .select { |digest| valid_digest?(digest) }.uniq
+      end
+
+      def same_remote_image?(image, local, remote)
+        return false unless local && local['Architecture'] == architecture && local['Os'] == 'linux'
+
+        digests = local_digests(local)
+        return true if digests.include?(remote)
+
+        # Docker's classic store can record an index digest. Resolve that immutable
+        # historical reference natively before comparing platform manifests.
+        digests.any? { |digest| remote_digest(Images::Reference.pinned(image, digest)) == remote }
+      end
+    end
+  end
+end

data/lib/empeira/runtime/interface.rb

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

data/lib/empeira/runtime/mount_probe.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    # Prove that an engine sees this client's canonical directory, including VM-backed engines.
+    class MountProbe
+      def initialize(runtime:)
+        @runtime = runtime
+      end
+
+      def verify(resource, mounts)
+        mounts.each do |mount|
+          fields = mount.split(',').select { |field| field.include?('=') }.to_h { |field| field.split('=', 2) }
+          if File.file?(fields.fetch('src'))
+            verify_file(resource, fields.fetch('src'), fields.fetch('dst'))
+          else
+            verify_directory(resource, fields.fetch('src'), fields.fetch('dst'))
+          end
+        end
+      end
+
+      private
+
+      def verify_file(resource, source, destination)
+        code = 'exit(File.file?(ARGV[0]) && File.readable?(ARGV[0]) ? 0 : 1)'
+        result = @runtime.service_exec(resource, [ControlPlane::Health::RUBY, '-e', code, destination])
+        return if result.success?
+
+        failed_probe!(result, source, destination, 'Cannot verify the configured file mount (EYAML or server.mounts)')
+      end
+
+      def verify_directory(resource, source, destination)
+        code = 'require "digest"; print Digest::SHA256.hexdigest(Dir.children(ARGV.fetch(0)).sort.join("\0"))'
+        expected = Digest::SHA256.hexdigest(Dir.children(source).sort.join("\0"))
+        result = @runtime.service_exec(resource, [ControlPlane::Health::RUBY, '-e', code, destination])
+        return if result.success? && result.stdout == expected
+
+        reason = if result.success?
+                   'Container directory listing differs from the local mount source'
+                 else
+                   'Cannot execute the container directory mount probe'
+                 end
+        failed_probe!(result, source, destination, reason)
+      rescue SystemCallError
+        location = Execution::Diagnostics.safe_text(source.to_s)
+        raise Error, "Cannot read local mount directory to verify the mount: #{location}", cause: nil
+      end
+
+      def failed_probe!(result, source, destination, reason)
+        paths = Execution::Diagnostics.safe_text("Source: #{source}\nDestination: #{destination}")
+        details = Execution::Diagnostics.command(result, operation: 'Verify server mount visibility',
+                                                         tool: ControlPlane::Health::RUBY)
+        raise Error, "#{reason}\n#{paths}\n#{details}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/runtime/podman.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    class Podman < Container
+      def node_ssh_publication?
+        true
+      end
+
+      def initialize(context:, runner:)
+        super(name: 'podman', context: context, runner: runner)
+      end
+
+      protected
+
+      # A disposable manifest forces registry access even if the tag exists locally.
+      # Podman resolves both single manifests and indexes without downloading layers.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- Keep manifest ownership, deadline and cleanup in one transaction.
+      def remote_descriptors(image)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30
+        temporary = "localhost/empeira-metadata-#{SecureRandom.hex(16)}"
+        result = update_command(['manifest', 'create', temporary], operation: 'temporary metadata creation', timeout: 5)
+        identifier = result.stdout.strip
+        unless identifier.match?(/\A[0-9a-f]{64}\z/)
+          raise Providers::ExecutionError,
+                'Invalid temporary manifest identity'
+        end
+
+        metadata_command(['manifest', 'add', '--all', identifier, "docker://#{image}"],
+                         image: image, timeout: metadata_remaining(deadline))
+        result = metadata_command(['manifest', 'inspect', identifier], image: image,
+                                                                       timeout: metadata_remaining(deadline))
+        data = parse_json(result.stdout)
+        malformed! unless data.is_a?(Hash) && data['manifests'].is_a?(Array)
+        data['manifests']
+      ensure
+        if identifier&.match?(/\A[0-9a-f]{64}\z/)
+          update_command(['manifest', 'rm', identifier], operation: 'temporary metadata cleanup', timeout: 5)
+        end
+      end
+
+      def metadata_remaining(deadline)
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise Providers::ExecutionError, 'Remote metadata timeout' unless remaining.positive?
+
+        remaining
+      end
+
+      def update_helper_user
+        ['--userns', 'keep-id', *super]
+      end
+
+      def update_helper_network
+        'podman'
+      end
+
+      def info_arguments
+        ['info', '--format', 'json']
+      end
+
+      def validate_info!(info)
+        malformed! unless info.is_a?(Hash) && info['host'].is_a?(Hash)
+        return if info.dig('host', 'networkBackend') == 'netavark' &&
+                  bridge_available?(info['plugins'])
+
+        raise UnsupportedCapability, 'Podman requires the Netavark network backend with bridge support'
+      end
+
+      def bridge_available?(plugins)
+        plugins.is_a?(Hash) && plugins['network'].is_a?(Array) && plugins['network'].include?('bridge')
+      end
+
+      def network_entries
+        entries = json_command(['network', 'ls', '--format', 'json'], operation: 'network inventory')
+        malformed! unless entries.is_a?(Array) && entries.all?(Hash)
+        validate_entries(entries.map { |item| { 'id' => item['id'], 'name' => item['name'] } })
+      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', '--disable-dns',
+         '--opt', 'isolate=true', *peer_network_options(definition), *label_arguments(definition),
+         definition.backend_name]
+      end
+
+      def attachment_count(identifier)
+        entries = json_command(['ps', '--all', '--filter', "network=#{identifier}", '--format', 'json'],
+                               operation: 'network membership')
+        malformed! unless entries.is_a?(Array) && entries.all?(Hash)
+        entries.size
+      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,
+         '--interface-name', "ep#{context.workspace.id[0, 10]}"]
+      end
+
+      def isolated?(data)
+        data['internal'] && data['driver'] == 'bridge' && data['dns_enabled'] == false &&
+          data['options']['isolate'] == 'true'
+      end
+
+      def normalize_network_binding(data)
+        data = data.merge('options' => data['options'] || {})
+        malformed! unless [true, false].include?(data['internal']) && data['options'].is_a?(Hash)
+        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)
+        Network::Resource.new(**binding.to_h, attachment_count: attachment_count(binding.id))
+      end
+    end
+  end
+end

data/lib/empeira/runtime/recipe_build.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    module RecipeBuild
+      private
+
+      def base_state(recipe, refresh:)
+        Images::Recipe.bases(recipe).sort.to_h.transform_values do |reference|
+          digest = refresh ? remote_digest(reference) : available_base_digest(reference)
+          { 'reference' => reference, 'digest' => digest }
+        end
+      end
+
+      def available_base_digest(reference)
+        ensure_image(reference)
+        data = local_image(reference)
+        unless data && data['Architecture'] == architecture && data['Os'] == 'linux'
+          raise Providers::ExecutionError, "Build base has an incompatible platform: #{reference}"
+        end
+
+        digest = local_digests(data).first
+        raise Providers::ExecutionError, "Build base has no registry digest: #{reference}" unless digest
+
+        digest
+      end
+
+      def bases_current?(labels, expected)
+        text = labels['io.empeira.base-inputs']
+        return false unless text
+
+        previous = recorded_bases(text, labels['io.empeira.base-fingerprint'])
+        return false unless previous.keys.sort == expected.keys.sort
+
+        normalized = previous.to_h do |key, base|
+          value = normalized_base(base, expected.fetch(key))
+          return false unless value
+
+          [key, value]
+        end
+        Infrastructure::Definition.fingerprint(normalized) == Infrastructure::Definition.fingerprint(expected)
+      end
+
+      def recorded_bases(text, fingerprint)
+        previous = JSON.parse(text)
+        unless previous.is_a?(Hash) && Infrastructure::Definition.fingerprint(previous) == fingerprint
+          raise Providers::OwnershipError, 'Invalid local build base metadata'
+        end
+
+        previous
+      rescue JSON::ParserError
+        raise Providers::OwnershipError, 'Unreadable local build base metadata', cause: nil
+      end
+
+      def normalized_base(base, current)
+        return unless base.is_a?(Hash) && base['reference'] == current['reference'] && valid_digest?(base['digest'])
+
+        digest = base['digest']
+        digest = remote_digest(Images::Reference.pinned(base['reference'], digest)) if digest != current['digest']
+        base.merge('digest' => digest)
+      end
+
+      def build_image(image, recipe, files, refresh: false, bases: nil)
+        @local_image_inspections&.delete(image)
+        bases ||= base_state(recipe, refresh: refresh)
+        Dir.mktmpdir('empeira-image-') do |directory|
+          write_build_context(directory, recipe, files)
+          labels = build_labels(recipe, files, bases)
+          arguments = ['build', *(refresh ? ['--pull'] : []), '--tag', image,
+                       *labels.flat_map { |key, value| ['--label', "#{key}=#{value}"] },
+                       *base_arguments(bases),
+                       '--file', File.join(directory, 'Containerfile'), directory]
+          update_command(arguments, operation: 'managed image build', timeout: 600)
+        end
+      end
+
+      def build_labels(recipe, files, bases)
+        { 'io.empeira.recipe' => Digest::SHA256.hexdigest(recipe),
+          'io.empeira.build-inputs' => Infrastructure::Definition.fingerprint(files),
+          'io.empeira.base-inputs' => JSON.generate(bases),
+          'io.empeira.base-fingerprint' => Infrastructure::Definition.fingerprint(bases) }
+      end
+
+      def base_arguments(bases)
+        bases.flat_map do |key, base|
+          reference = Images::Reference.pinned(base.fetch('reference'), base.fetch('digest'))
+          ['--build-arg', "#{key}=#{reference}"]
+        end
+      end
+
+      def write_build_context(directory, recipe, files)
+        files.each do |name, content|
+          unless name.match?(/\A[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*\z/) && content.is_a?(String)
+            raise ConfigurationError, 'Image context must contain named reviewed resource files'
+          end
+
+          File.write(File.join(directory, name), content)
+        end
+        File.write(File.join(directory, 'Containerfile'), recipe)
+      end
+    end
+  end
+end

data/lib/empeira/runtime/registry_diagnostics.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    module RegistryDiagnostics
+      private
+
+      def registry_failure_hint(image, diagnostic, timed_out:)
+        host = Images::Reference.host(image)
+        case Execution::Diagnostics.registry_failure(diagnostic, timed_out: timed_out)
+        when :auth
+          "Registry authentication or authorization failed for #{host}. " \
+          "Authenticate with the selected container runtime, check repository permissions and retry:\n  " \
+          "#{name} login #{host}"
+        when :missing then "Registry image or tag is unavailable: #{image}. Check the repository and tag."
+        when :network then "Registry network access failed for #{host}. Check connectivity and DNS."
+        when :tls then "Registry TLS verification failed for #{host}. Check the selected runtime's CA trust."
+        else 'Check the selected runtime registry access and diagnostic below.'
+        end
+      end
+    end
+  end
+end

data/lib/empeira/runtime/service_arguments.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    class ServiceArguments
+      SCALARS = { 'dns' => '--dns', 'user' => '--user', 'entrypoint' => '--entrypoint',
+                  'env_file' => '--env-file', 'shm_size' => '--shm-size', 'mac_address' => '--mac-address',
+                  'ip' => '--ip', 'runtime_ip' => '--ip' }.freeze
+
+      def initialize(definition)
+        @definition = definition
+        @options = definition.options
+      end
+
+      # One declarative argument vector makes runtime options auditable.
+      # rubocop:disable-next Metrics/AbcSize
+      def build
+        ['create', '--pull=never', '--name', @definition.name,
+         '--hostname', @options.fetch('hostname', @definition.key),
+         '--network', @options.fetch('network'), '--memory', "#{@options.fetch('memory')}m",
+         '--cpus', @options.fetch('cpus', 1).to_s, '--no-healthcheck',
+         *init_options, *security_options, *pairs('--label', @definition.labels), *scalar_options,
+         *pairs('--env', @options.fetch('environment', {}).merge(@options.fetch('runtime_environment', {}))),
+         *pairs('--sysctl', @options.fetch('sysctls', {})),
+         *@options.fetch('mounts', []).flat_map { |mount| ['--mount', mount] },
+         *@options.fetch('ports', []).flat_map { |port| ['--publish', port] },
+         @options.fetch('image'), *@options.fetch('command', [])]
+      end
+
+      private
+
+      def security_options
+        values = { 'cap_drop' => '--cap-drop', 'cap_add' => '--cap-add', 'devices' => '--device',
+                   'security_options' => '--security-opt' }
+        [*(@options['read_only'] ? ['--read-only'] : []),
+         *values.flat_map { |key, flag| @options.fetch(key, []).flat_map { |value| [flag, value] } }]
+      end
+
+      def init_options
+        return ['--init'] if @options['init'] == 'process'
+        return [] unless @options['init'] == 'systemd'
+
+        ['--systemd=always', '--cgroupns=private', '--tmpfs', '/run', '--tmpfs', '/tmp']
+      end
+
+      def scalar_options
+        SCALARS.flat_map { |key, option| @options[key] ? [option, @options[key]] : [] }
+      end
+
+      def pairs(option, values)
+        values.flat_map { |key, value| [option, "#{key}=#{value}"] }
+      end
+    end
+  end
+end

data/lib/empeira/runtime/service_images.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Runtime
+    module ServiceImages
+      def with_local_images
+        return yield if @local_image_inspections
+
+        @local_image_inspections = {}
+        begin
+          yield
+        ensure
+          @local_image_inspections = nil
+        end
+      end
+
+      def ensure_image(image, recipe: nil, files: {})
+        result = local_image_inspection(image)
+        return verify_recipe!(result, recipe) if result.success?
+
+        @local_image_inspections&.delete(image)
+        return build_image(image, recipe, files) if recipe
+
+        update_command(['pull', image], operation: "image pull #{image}", registry: image)
+      end
+
+      def refresh_image(image, recipe: nil, files: {}, &progress)
+        unless @image_metadata
+          return with_image_updates { refresh_image(image, recipe: recipe, files: files, &progress) }
+        end
+
+        observed = local_image(image)
+        return refresh_recipe(image, recipe, files, observed, &progress) if recipe
+
+        digest = remote_digest(image)
+        return :unchanged if same_remote_image?(image, observed, digest)
+
+        progress&.call(:updating)
+        @local_image_inspections&.delete(image)
+        update_command(['pull', image], operation: "image pull #{image}", registry: image)
+        :updated
+      end
+
+      def image_id(image)
+        result = required_image_inspection(image, operation: 'image identity')
+        data = parse_json(result.stdout)
+        unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash) && data.first['Id'].is_a?(String)
+          malformed!
+        end
+        data.first.fetch('Id')
+      end
+
+      def image_architecture(image)
+        result = required_image_inspection(image, operation: 'node image architecture')
+        data = parse_json(result.stdout)
+        malformed! unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash)
+        architecture = data.first['Architecture']
+        malformed! unless %w[amd64 arm64].include?(architecture)
+        architecture
+      end
+
+      private
+
+      def local_image_inspection(image)
+        return @local_image_inspections.fetch(image) if @local_image_inspections&.key?(image)
+
+        result = runner.run(name, arguments: ['image', 'inspect', image], timeout: 30)
+        @local_image_inspections[image] = result if @local_image_inspections
+        result
+      end
+
+      def required_image_inspection(image, operation:)
+        result = local_image_inspection(image)
+        return result if result.success?
+
+        raise Providers::ExecutionError,
+              "#{name} #{operation} failed; run empeira status\n" \
+              "#{Execution::Diagnostics.native(result, operation: operation, tool: name)}", cause: nil
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Compare all three build inputs before deciding whether to rebuild.
+      def refresh_recipe(image, recipe, files, observed)
+        labels = observed.to_h.fetch('Config', {}).to_h.fetch('Labels', {}).to_h
+        if observed && labels['io.empeira.recipe'] != Digest::SHA256.hexdigest(recipe)
+          raise Providers::OwnershipError, 'Local service image does not match the recorded build recipe'
+        end
+
+        bases = base_state(recipe, refresh: true)
+        if observed && labels['io.empeira.build-inputs'] == Infrastructure::Definition.fingerprint(files) &&
+           bases_current?(labels, bases)
+          return :unchanged
+        end
+
+        yield :updating if block_given?
+        build_image(image, recipe, files, refresh: true, bases: bases)
+        :updated
+      end
+
+      def verify_recipe!(result, recipe)
+        return unless recipe
+
+        return if image_labels(result.stdout)['io.empeira.recipe'] == Digest::SHA256.hexdigest(recipe)
+
+        raise Providers::OwnershipError, 'Local service image does not match the recorded build recipe'
+      end
+
+      def image_labels(stdout)
+        data = parse_json(stdout)
+        malformed! unless data.is_a?(Array) && data.size == 1 && data.first.is_a?(Hash)
+        config = data.first.fetch('Config', {})
+        malformed! unless config.is_a?(Hash)
+        labels = config.fetch('Labels', {})
+        malformed! unless labels.is_a?(Hash)
+        labels
+      end
+    end
+  end
+end