empeira 0.1.0.pre.alpha.1

data/lib/empeira/execution/launch_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Execution
+    class LaunchError < ExecutionError
+      attr_reader :exit_status
+
+      def initialize(message, exit_status:)
+        @exit_status = exit_status
+        super(message)
+      end
+    end
+  end
+end

data/lib/empeira/execution/result.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Execution
+    Result = Data.define(:stdout, :stderr, :exit_status, :timed_out) do
+      def success?
+        !timed_out && exit_status.is_a?(Integer) && exit_status.zero?
+      end
+    end
+  end
+end

data/lib/empeira/execution/runner.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+require_relative 'launch_error'
+
+module Empeira
+  module Execution
+    # rubocop:disable-next Metrics/ClassLength -- Capture, process streams and direct consoles share one execution boundary.
+    class Runner
+      def initialize(platform: Platform::Facts.new, logger: nil)
+        @platform = platform
+        @logger = logger
+      end
+
+      def run(executable, arguments: [], environment: {}, directory: nil, timeout: nil, on_stdout: nil)
+        validate!(executable, arguments, environment, timeout)
+        log(arguments, environment)
+        options = { pgroup: true }
+        options[:chdir] = directory.to_s if directory
+        result = capture(environment, executable, arguments, options, timeout, on_stdout)
+        @logger&.debug({ operation: 'execute', exit_status: result.exit_status, timed_out: result.timed_out })
+        result
+      rescue SystemCallError => e
+        # OS exception messages can include command arguments and credentials.
+        raise ExecutionError, "Process could not be executed (#{e.class.name})", cause: nil
+      end
+
+      # Inherit caller streams for terminals and unbounded logs; never buffer them.
+      # Explicit stream handles avoid hidden globals in process-execution tests.
+      # rubocop:disable-next Metrics/ParameterLists
+      def stream(executable, arguments: [], environment: {}, directory: nil,
+                 input: $stdin, output: $stdout, error: $stderr)
+        validate!(executable, arguments, environment, nil)
+        log(arguments, environment)
+        options = { in: input, out: output, err: error }
+        options[:chdir] = directory.to_s if directory
+        pid = Process.spawn(environment, [executable, executable], *arguments, **options)
+        _, status = Process.wait2(pid)
+        pid = nil
+        Result.new(stdout: '', stderr: '', exit_status: status.exitstatus || (128 + status.termsig), timed_out: false)
+      rescue SystemCallError => e
+        raise ExecutionError, "Streaming process could not execute (#{e.class.name})", cause: nil
+      ensure
+        reap_stream(pid) if pid
+      end
+
+      def console(path, input: $stdin, output: $stdout, guidance: nil)
+        Console.new.attach(path, input: input, output: output, guidance: guidance)
+      end
+
+      # A terminal-preserving handoff: signals, process identity and status belong
+      # directly to the standalone program, with no forwarding proxy or shell.
+      def replace(executable, arguments: [], environment: {})
+        validate!(executable, arguments, environment, nil)
+        explicit_format!(executable)
+        log(arguments, environment)
+        Kernel.exec(environment, [executable, executable], *arguments)
+      rescue Errno::ENOENT
+        raise LaunchError.new('executable or its interpreter was not found', exit_status: 127), cause: nil
+      rescue Errno::E2BIG
+        raise LaunchError.new('environment and arguments exceed the operating system size limit', exit_status: 126),
+              cause: nil
+      rescue SystemCallError
+        raise LaunchError.new('executable could not be started', exit_status: 126), cause: nil
+      end
+
+      # Inherited output streams immediately; closing control cancels the owned guest session.
+      def controlled_stream(executable, arguments:, input:, control:, output: $stdout, error: $stderr)
+        validate!(executable, arguments, {}, nil)
+        log(arguments, {})
+        pid = Process.spawn([executable, executable], *arguments, in: input, out: output, err: error, pgroup: true)
+        _, status = Process.wait2(pid)
+        pid = nil
+        Result.new(stdout: '', stderr: '', exit_status: status.exitstatus || (128 + status.termsig), timed_out: false)
+      rescue SystemCallError => e
+        raise ExecutionError, "Cannot start diagnostic transport (#{e.class.name})", cause: nil
+      ensure
+        control.close unless control.closed?
+        reap_controlled_stream(pid) if pid
+      end
+
+      def debug(message)
+        @logger&.debug(message)
+      end
+
+      # Keep the caller's input and foreground terminal for authentication, but capture tool output.
+      # rubocop:disable-next Metrics/AbcSize -- Paired pipes and reader cleanup bracket one foreground process.
+      def buffered(executable, arguments: [], environment: {}, directory: nil, input: $stdin)
+        IO.pipe do |stdout, output|
+          IO.pipe do |stderr, error|
+            readers = [stdout, stderr].map { |io| Thread.new { io.binmode.read } }
+            result = stream(executable, arguments: arguments, environment: environment, directory: directory,
+                                        input: input, output: output, error: error)
+            output.close
+            error.close
+            Result.new(stdout: readers[0].value, stderr: readers[1].value,
+                       exit_status: result.exit_status, timed_out: result.timed_out)
+          ensure
+            readers&.each { |thread| thread.kill.join }
+          end
+        end
+      end
+
+      private
+
+      # Ruby otherwise silently interprets plain executable text with /bin/sh.
+      # Native ELF/Mach-O binaries and scripts with an explicit interpreter are
+      # the executable formats supported by Linux, WSL2 and macOS.
+      def explicit_format!(executable)
+        header = File.binread(executable, 4)
+        native = ["\x7fELF".b, "\xfe\xed\xfa\xce".b, "\xce\xfa\xed\xfe".b,
+                  "\xfe\xed\xfa\xcf".b, "\xcf\xfa\xed\xfe".b, "\xca\xfe\xba\xbe".b,
+                  "\xbe\xba\xfe\xca".b, "\xca\xfe\xba\xbf".b, "\xbf\xba\xfe\xca".b]
+        return if header.start_with?('#!') || native.include?(header)
+
+        raise LaunchError.new('entrypoint must be a native executable or a script with a shebang', exit_status: 126)
+      end
+
+      def reap_controlled_stream(pid)
+        Timeout.timeout(4) { Process.wait(pid) }
+      rescue Timeout::Error
+        terminate(pid)
+        Process.wait(pid)
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def reap_stream(pid)
+        Process.kill('TERM', pid)
+        Timeout.timeout(2) { Process.wait(pid) }
+      rescue Timeout::Error
+        Process.kill('KILL', pid)
+        Process.wait(pid)
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil
+      end
+
+      def validate!(executable, arguments, environment, timeout)
+        unless command_string?(executable) && !executable.empty? &&
+               arguments.is_a?(Array) && arguments.all? { |arg| command_string?(arg) }
+          raise ExecutionError, 'Executable and arguments must be strings without null bytes'
+        end
+
+        validate_environment!(environment)
+        validate_timeout!(timeout)
+      end
+
+      def command_string?(value)
+        value.is_a?(String) && !value.include?("\0")
+      end
+
+      def validate_environment!(environment)
+        return if environment.is_a?(Hash) && environment.all? { |key, value| environment_entry?(key, value) }
+
+        raise ExecutionError, 'Environment must map valid variable names to strings or null'
+      end
+
+      def environment_entry?(key, value)
+        command_string?(key) && !key.empty? && !key.include?('=') && (value.nil? || command_string?(value))
+      end
+
+      def validate_timeout!(timeout)
+        return if timeout.nil? || (timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?)
+
+        raise ExecutionError, 'Timeout must be a positive finite number'
+      end
+
+      def log(arguments, environment)
+        @logger&.debug({ operation: 'execute', arguments: arguments.map { '[REDACTED]' },
+                         environment: environment.transform_values { '[REDACTED]' } })
+      end
+
+      def capture(environment, executable, arguments, options, timeout, on_stdout)
+        # The two-element executable form prevents Ruby's single-string shell fallback.
+        Open3.popen3(environment, [executable, executable], *arguments, **options) do |stdin, stdout, stderr, process|
+          completed = false
+          stdin.close
+          streams = [Thread.new { read_output(stdout, on_stdout) }, Thread.new { stderr.binmode.read }]
+          result = collect(process, streams, timeout)
+          completed = true
+          result
+        ensure
+          cleanup(process, streams, completed)
+        end
+      end
+
+      def read_output(io, observer)
+        return io.binmode.read unless observer
+
+        buffer = +''.b
+        loop do
+          chunk = io.readpartial(16_384)
+          buffer << chunk
+          observer.call(chunk)
+        end
+      rescue EOFError
+        buffer
+      end
+
+      def collect(process, streams, timeout)
+        Timeout.timeout(timeout) do
+          status = process.value
+          Result.new(stdout: streams[0].value.freeze, stderr: streams[1].value.freeze,
+                     exit_status: status.exitstatus, timed_out: false)
+        end
+      rescue Timeout::Error
+        timed_out(process, streams)
+      end
+
+      def timed_out(process, streams)
+        terminate(process.pid)
+        process.join
+        output = streams.map { |stream| stream.join(1) ? stream.value : '' }
+        Result.new(stdout: output[0], stderr: output[1], exit_status: nil, timed_out: true)
+      end
+
+      def cleanup(process, streams, completed)
+        unless completed
+          # A reaped group leader does not mean its descendants have exited.
+          terminate(process.pid)
+          process.join
+        end
+      ensure
+        streams&.each { |thread| thread.kill.join }
+      end
+
+      def terminate(pid)
+        Process.kill('KILL', -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/empeira/execution/terminal.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Execution
+    module Terminal
+      CLEAN_EXIT_SIGNALS = %w[QUIT TSTP].map { |signal| Signal.list.fetch(signal) }.freeze
+
+      # rubocop:disable-next Metrics/AbcSize -- Signal status and restored handlers share the session cleanup boundary.
+      def self.with_interrupts
+        return yield unless Thread.current == Thread.main
+
+        previous = %w[TERM HUP QUIT TSTP].to_h do |signal|
+          [signal, Signal.trap(signal) { raise SignalException, signal }]
+        end
+        yield
+      rescue SignalException => e
+        raise unless CLEAN_EXIT_SIGNALS.include?(e.signo)
+
+        # Preserve the signal status after cleanup without a core dump or a suspended raw terminal.
+        raise SystemExit, 128 + e.signo
+      ensure
+        previous&.each { |signal, handler| Signal.trap(signal, handler) }
+      end
+
+      def self.interactive?(output: $stdout, error: $stderr, environment: ENV)
+        [output, error].all? { |io| io.respond_to?(:tty?) && io.tty? } &&
+          environment['TERM'].to_s.downcase != 'dumb' && environment['CI'].to_s.empty?
+      end
+
+      def self.color?(**options)
+        interactive?(**options) && options.fetch(:environment, ENV)['NO_COLOR'].to_s.empty?
+      end
+    end
+  end
+end

data/lib/empeira/hostname_pattern.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Empeira
+  # Full-hostname glob semantics shared by independent hostname policies.
+  module HostnamePattern
+    def self.valid?(value)
+      value.is_a?(String) && value.size.between?(1, 253) && value.match?(/\A[a-z0-9*?][a-z0-9.*?-]*\z/i)
+    end
+
+    def self.matches?(pattern, hostname)
+      File.fnmatch?(pattern.downcase, hostname.downcase)
+    end
+  end
+end

data/lib/empeira/images/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Images
+    module Configuration
+      REPOSITORY = %r{\A[a-z0-9]+(?:[._:/-][a-z0-9]+)*\z}
+      TAG = /\A\w[\w.-]{0,127}\z/
+      DIGEST = /\Asha256:[a-f0-9]{64}\z/
+      ROOT = File.expand_path('../../../resources', __dir__)
+
+      def self.reference(data, registry: nil)
+        return data.fetch('reference') if data['reference']
+
+        repository = Reference.repository(data.fetch('repository'), registry: registry)
+        return "#{repository}@#{data['digest']}" if data['digest']
+
+        tag = data.fetch('tag')
+        "#{repository}:#{tag}"
+      end
+
+      def self.recipe(data, registry: nil)
+        relative = data.fetch('build')
+        path = Pathname.new(ROOT).join(relative).realpath
+        unless path.to_s.start_with?("#{ROOT}/")
+          raise ConfigurationError,
+                'images build resource must be packaged with Empeira'
+        end
+
+        Recipe.render(File.read(path), registry: registry)
+      rescue SystemCallError
+        raise ConfigurationError, 'images build resource is unavailable', cause: nil
+      end
+
+      def self.artifact(data, purpose: 'squid', registry: nil)
+        recipe = self.recipe(data, registry: registry) if data['build'] && !data['reference']
+        { image: recipe ? local_image(recipe, purpose: purpose) : reference(data, registry: registry), recipe: recipe }
+      end
+
+      def self.local_image(recipe, purpose: 'squid')
+        "localhost/empeira-#{purpose}:#{Digest::SHA256.hexdigest(recipe)}"
+      end
+    end
+  end
+end

data/lib/empeira/images/identity.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Empeira
+  module Images
+    class Identity
+      attr_reader :cache_key, :distribution, :version, :architecture, :source, :revision, :checksum
+
+      def to_h
+        { 'distribution' => distribution, 'version' => version, 'architecture' => architecture,
+          'source' => source, 'revision' => revision, 'checksum' => checksum }
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- All fields participate in the immutable identity.
+      def initialize(distribution:, version:, architecture:, source:, revision:, checksum:)
+        fields = [distribution, version, architecture, source, revision, checksum]
+        unless fields.all? { |value| value.is_a?(String) && !value.strip.empty? }
+          raise Error, 'Image identity fields must be non-empty strings'
+        end
+        raise Error, 'Image checksum must be a SHA-256 hex digest' unless checksum.match?(/\A[0-9a-f]{64}\z/i)
+
+        @distribution, @version, @architecture, @source, @revision, @checksum = fields
+        @cache_key = Digest::SHA256.hexdigest(JSON.generate(fields[0...-1] + [checksum.downcase])).freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/empeira/images/recipe.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Images
+    # Only reviewed EMPEIRA_BASE_* ARG declarations are dependencies. This is not a Dockerfile parser.
+    module Recipe
+      BASE = /^ARG (EMPEIRA_BASE_[A-Z0-9_]+)=([^\s]+)$/
+
+      def self.render(source, registry: nil)
+        source.gsub(BASE) do
+          name, value = Regexp.last_match.captures
+          value = Reference.base(value, registry: registry) unless value.start_with?('@') || value == 'scratch'
+          "ARG #{name}=#{value}"
+        end
+      end
+
+      def self.bases(recipe)
+        recipe.scan(BASE).to_h.reject { |_, value| value == 'scratch' }
+      end
+    end
+  end
+end

data/lib/empeira/images/reference.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Images
+    # Registry selection applies to repository fields, never exact reference overrides.
+    module Reference
+      HOST = /\A(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::[0-9]+)?\z/
+
+      def self.hosted?(repository)
+        first = repository.split('/').first
+        first.include?('.') || first.include?(':') || first == 'localhost'
+      end
+
+      def self.registry?(value)
+        return true if value.nil?
+        return false unless value.is_a?(String) && value.match?(HOST) && hosted?(value)
+
+        port = value.split(':', 2)[1]
+        port.nil? || (1..65_535).cover?(port.to_i)
+      end
+
+      def self.repository(value, registry: nil)
+        hosted?(value) ? value : "#{registry || 'docker.io'}/#{value}"
+      end
+
+      # Reserved recipe base declarations contain a tag or digest, not a YAML reference override.
+      def self.base(value, registry: nil)
+        path = value.split('@', 2).first.sub(%r{:[^/:]+\z}, '')
+        repository(path, registry: registry) + value.delete_prefix(path)
+      end
+
+      def self.pinned(reference, digest)
+        repository = reference.split('@').first.sub(%r{:[^/:]+\z}, '')
+        "#{repository}@#{digest}"
+      end
+
+      def self.host(reference)
+        first, path = reference.split('/', 2)
+        path && registry?(first) ? first : 'docker.io'
+      end
+    end
+  end
+end

data/lib/empeira/images/source.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/UnusedMethodArgument -- Preserve explicit adapter keyword contracts.
+
+module Empeira
+  module Images
+    class Source
+      def resolve(identity:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+
+      def fetch(identity:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+    end
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/lib/empeira/immutable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Immutable
+    module_function
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each do |key, child|
+          deep_freeze(key)
+          deep_freeze(child)
+        end
+      when Array then value.each { |child| deep_freeze(child) }
+      end
+      value.freeze
+    end
+  end
+end