empeira 0.1.0.pre.alpha.1

data/lib/empeira/server/relay_certificate.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Empeira
+  module Server
+    # Export only the CA-issued service identity needed by the owned relay.
+    class RelayCertificate
+      NAME = 'puppetdb.empeira.internal'
+      SSL = '/etc/puppetlabs/puppet/ssl'
+
+      def initialize(context:)
+        @directory = context.locations.workspace(context.workspace).join('puppetdb-relay')
+      end
+
+      def path(name)
+        @directory.join(name).to_s
+      end
+
+      def prepare(runtime:, server:)
+        raise Error, 'Relay certificate directory is an unsafe symlink' if @directory.symlink?
+        return if File.file?(path('cert.pem')) && File.file?(path('key.pem'))
+
+        reject_partial_identity!
+
+        FileUtils.mkdir_p(@directory, mode: 0o700)
+        File.chmod(0o700, @directory)
+        issue(runtime, server)
+        export(runtime, server)
+      ensure
+        remove_files(%w[cert.pem.pending key.pem.pending]) unless @directory.symlink?
+      end
+
+      def issue(runtime, server)
+        result = runtime.service_exec(server, [Node::Certificates::CA, 'ca', 'generate', '--certname', NAME],
+                                      timeout: 60)
+        raise Error, 'Puppet CA could not issue the relay certificate; inspect server logs' unless result.success?
+      end
+
+      def export(runtime, server)
+        { 'cert.pem' => "#{SSL}/certs/#{NAME}.pem",
+          'key.pem' => "#{SSL}/private_keys/#{NAME}.pem" }.each do |name, source|
+          temporary = path("#{name}.pending")
+          runtime.copy_from(server, source, temporary)
+          File.chmod(name == 'key.pem' ? 0o600 : 0o644, temporary)
+          File.rename(temporary, path(name))
+        end
+      end
+
+      def reject_partial_identity!
+        return unless File.exist?(path('cert.pem')) || File.exist?(path('key.pem'))
+
+        raise Error, 'PuppetDB relay certificate is incomplete; restore or destroy the workspace'
+      end
+
+      def cleanup
+        raise Error, 'Relay certificate directory is an unsafe symlink' if @directory.symlink?
+        return unless @directory.directory?
+
+        remove_files(%w[cert.pem key.pem cert.pem.pending key.pem.pending])
+        @directory.rmdir if @directory.children.empty?
+      end
+
+      private
+
+      def remove_files(names)
+        names.each do |name|
+          file = path(name)
+          File.unlink(file) if File.exist?(file) || File.symlink?(file)
+        end
+      rescue SystemCallError
+        raise Error, 'Cannot remove owned relay certificate files; cleanup is incomplete'
+      end
+    end
+  end
+end

data/lib/empeira/server/runtime.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Server
+    # One Puppet-compatible runtime contract, with OpenVox defaults in configuration.
+    class Runtime
+      ENVIRONMENT_KEY = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+      SEMANTICS = %w[certname dns_alt_names ca_hostname autosign server_hostname environment_timeout java_args
+                     max_active_instances puppetdb_enabled storeconfigs reports puppetdb_server_urls].freeze
+      STARTUP_REQUIRED = %w[entrypoint arguments].freeze
+      STARTUP = [*STARTUP_REQUIRED, 'eyaml_keys'].freeze
+      PATHS = %w[puppetdb_config].freeze
+      FIELDS = { 'startup' => STARTUP, 'paths' => PATHS, 'environment_keys' => SEMANTICS }.freeze
+
+      def self.validate!(definition, path = 'server.runtime', effective: false)
+        validate_definition!(definition, path, effective: effective)
+      end
+
+      def self.validate_definition!(definition, location, effective:)
+        validate_fields!(definition, FIELDS.keys, location, effective: effective)
+        definition.each do |key, value|
+          child = "#{location}.#{key}"
+          validate_fields!(value, FIELDS.fetch(key), child, effective: effective)
+          validate_component!(key, value, child)
+        end
+      end
+
+      def self.validate_component!(key, value, location)
+        value.each do |field, item|
+          raise ConfigurationError, "#{location}.#{field} is invalid" unless valid_item?(key, field, item)
+        end
+        return unless key == 'environment_keys' && value.values.uniq.size != value.size
+
+        raise ConfigurationError, "#{location} must not reuse an environment variable name"
+      end
+
+      def self.valid_item?(component, field, item)
+        case component
+        when 'startup'
+          return valid_arguments?(item) if field == 'arguments'
+          return %w[direct staged].include?(item) if field == 'eyaml_keys'
+
+          safe_path?(item)
+        when 'paths' then safe_path?(item)
+        else item.is_a?(String) && item.match?(ENVIRONMENT_KEY)
+        end
+      end
+
+      def self.validate_fields!(value, allowed, location, effective:)
+        raise ConfigurationError, "#{location} must be a mapping" unless value.is_a?(Hash)
+
+        raise ConfigurationError, "#{location} contains an unsupported field" unless (value.keys - allowed).empty?
+        return unless effective
+
+        required = location.end_with?('.startup') ? STARTUP_REQUIRED : allowed
+        missing = required - value.keys
+        raise ConfigurationError, "#{location}.#{missing.first} is required" unless missing.empty?
+      end
+
+      def self.safe_path?(value)
+        value.is_a?(String) && value.start_with?('/') && value != '/' &&
+          value.match?(%r{\A/[A-Za-z0-9_./-]+\z}) && !value.split('/').intersect?(%w[. ..]) &&
+          !value.include?('//')
+      end
+
+      def self.valid_arguments?(value)
+        value.is_a?(Array) && value.all? do |item|
+          item.is_a?(String) && !item.empty? && !item.match?(/[\x00-\x1f\x7f]/)
+        end
+      end
+
+      def self.resolve(config)
+        definition = config.fetch('server').fetch('runtime')
+        validate!(definition, effective: true)
+        new(definition)
+      end
+      attr_reader :startup, :paths, :environment_keys
+
+      def initialize(definition)
+        @startup = definition.fetch('startup')
+        @paths = definition.fetch('paths')
+        @environment_keys = definition.fetch('environment_keys')
+      end
+
+      def environment(values)
+        values.to_h { |semantic, value| [environment_keys.fetch(semantic.to_s), value] }
+      end
+    end
+  end
+end

data/lib/empeira/services/definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Services
+    # This domain describes containers without selecting a container engine.
+    class Definition
+      attr_reader :key, :options, :workspace
+
+      def initialize(key:, workspace:, **options)
+        @key = key
+        @workspace = workspace
+        @options = Immutable.deep_freeze(options.transform_keys(&:to_s))
+      end
+
+      def name
+        "empeira-#{workspace.id}-#{key}"
+      end
+
+      def fingerprint
+        Infrastructure::Definition.fingerprint(options.except('dns', 'runtime_environment', 'runtime_ip'))
+      end
+
+      def ownership_labels
+        { 'io.empeira.managed-by' => 'empeira', 'io.empeira.workspace' => workspace.id,
+          'io.empeira.purpose' => key }
+      end
+
+      def labels
+        ownership_labels.merge('io.empeira.definition' => fingerprint)
+      end
+
+      def verify!(resource, expected_id: nil)
+        return unless resource
+        return if resource.fetch('name') == name &&
+                  ownership_labels.all? { |key, value| resource.fetch('labels')[key] == value } &&
+                  (expected_id.nil? || expected_id == resource.fetch('id'))
+
+        raise Providers::OwnershipError, "Service resource ownership or recorded ID conflicts: #{key}"
+      end
+    end
+  end
+end

data/lib/empeira/updates/images.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Updates
+    # Container artifacts only; existing containers and immutable VM bases stay attached to their revisions.
+    class Images
+      def initialize(context:, runtime:, progress: Progress.new)
+        @context = context
+        @config = context.configuration
+        @runtime = runtime
+        @progress = progress
+      end
+
+      def refresh
+        @state = Infrastructure::Store.new(context: @context).load
+        if @state && @state.fetch('runtime') != @context.container_engine
+          raise Error, 'Workspace belongs to another runtime; select its owning runtime before updating images'
+        end
+
+        artifacts = catalog
+        @runtime.with_image_updates do
+          artifacts.each_with_index do |entry, index|
+            update(entry, index, artifacts.size)
+          end
+        end
+      end
+
+      private
+
+      def update(entry, index, total)
+        label = entry.fetch(:label)
+        @progress.count(index, total, "#{label} (#{index}/#{total})")
+        result = @runtime.refresh_image(entry.fetch(:image), **entry.except(:image, :label)) do |status|
+          @progress.count(index, total, "#{label} — #{status} (#{index + 1}/#{total})")
+        end
+        @progress.count(index + 1, total, "#{label} — #{result} (#{index + 1}/#{total})")
+      rescue Error => e
+        raise e.class, "#{label} (#{entry.fetch(:image)}): #{e.message}", cause: nil
+      end
+
+      def catalog
+        (service_images + utility_images + node_images).uniq { |entry| entry.fetch(:image) }
+      end
+
+      def service_images
+        references = [
+          ['Configuration server', reference(@config.dig('images', 'server'))],
+          ['CoreDNS', reference(@config.dig('images', 'dns'))],
+          ['Browser', reference(@config.dig('browser', 'image'))]
+        ]
+        references.concat(database_images)
+        references.concat(@config.dig('containers', 'additional').map do |entry|
+          [entry.fetch('name'), reference(entry.fetch('image'))]
+        end)
+        references.map { |label, image| { image: image, label: label } }
+      end
+
+      def database_images
+        return [] unless @config.dig('puppetdb', 'enabled')
+
+        [['PuppetDB', reference(@config.dig('images', 'puppetdb'))],
+         ['PostgreSQL', reference(@config.dig('images', 'postgres'))]]
+      end
+
+      def utility_images
+        installer = Empeira::Modules::Image.new(@config.dig('images', 'r10k'),
+                                                registry: @config.dig('images', 'registry'))
+        adapter = Network::Peer::AdapterImage.new(context: @context)
+        direct = ControlPlane::Plan.new(context: @context).gateway_artifact
+        [utility_artifact('relay', 'Service relay', purpose: 'relay'), utility_artifact('proxy', 'Squid proxy'),
+         direct.merge(label: 'Workspace gateway'),
+         { label: 'r10k helper', image: installer.reference, recipe: installer.recipe, files: installer.files },
+         { label: 'VM network helper', image: adapter.image, recipe: adapter.recipe, files: adapter.files }]
+      end
+
+      def utility_artifact(key, label, **)
+        Empeira::Images::Configuration.artifact(
+          @config.dig('images', key), registry: @config.dig('images', 'registry'), **
+        ).merge(label: label)
+      end
+
+      def node_images
+        architecture = @runtime.architecture
+        node_variants.map do |os, version|
+          request = Node::RunRequest.from_config(hostname: 'image-update', provider: 'container', config: @config)
+                                    .with(os: os, version: version)
+          image = Node::Image.new(config: @config, request: request, architecture: architecture)
+          { label: "#{os.capitalize} #{version} node image", image: image.reference,
+            recipe: image.recipe, files: image.build_files }
+        end
+      end
+
+      def node_variants
+        used = @state.to_h.fetch('nodes', {}).values.select { |record| record['provider'] == 'container' }
+        [@config.fetch('node_defaults').values_at('os', 'version'),
+         *used.map { |record| record.values_at('os', 'version') }].uniq
+      end
+
+      def reference(config)
+        Empeira::Images::Configuration.reference(config, registry: @config.dig('images', 'registry'))
+      end
+    end
+  end
+end

data/lib/empeira/updates/modules.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Updates
+    # Caller owns the existing workspace lock. r10k updates the live module directory in place.
+    class Modules
+      def initialize(context:, runtime:, runner:, progress: Progress.new)
+        @context = context
+        @runtime = runtime
+        @runner = runner
+        @progress = progress
+        @storage = Empeira::Modules::Storage.new(context: context)
+        @state = Empeira::Modules::State.new(context: context)
+      end
+
+      def synchronize
+        request = Empeira::Modules::Request.new(context: @context)
+        request.warnings.each { |message| @progress.warning(message) }
+        return unless request.present?
+
+        Empeira::Modules::GitSafety.new(project: @context.project.path, runner: @runner, progress: @progress)
+                                   .verify(@storage.root, recommend: true)
+        install(request)
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize -- Preserve the ordered direct-sync and success-marker boundary.
+      def install(request)
+        @progress.stage(0, 'Reading Puppetfile...')
+        image = Empeira::Modules::Image.new(@context.configuration.dig('images', 'r10k'),
+                                            registry: @context.configuration.dig('images', 'registry'))
+        @runtime.ensure_image(image.reference, recipe: image.recipe, files: image.files)
+        @storage.prepare
+        @state.prepare
+        @state.invalidate
+        git = Empeira::Modules::HostGit.new(runner: @runner, project: @context.project.path, progress: @progress)
+        installer = Empeira::Modules::Installer.new(runtime: @runtime, image: image.reference,
+                                                    git: git, progress: @progress)
+        names = installer.synchronize(request, @storage.root, state: @state)
+        @state.record(@storage.root, names)
+      end
+    end
+  end
+end

data/lib/empeira/updates/service.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Updates
+    class Service
+      TARGETS = %w[images modules all].freeze
+
+      def initialize(context: nil, runner: nil, runtimes: nil, build_info: BuildInfo.load, progress: Progress.new)
+        @context = context
+        @runner = runner
+        @runtimes = runtimes
+        @build_info = build_info
+        @progress = progress
+      end
+
+      def self_update
+        raise UnavailableFeature,
+              'Empeira self-update is not implemented yet. Package replacement requires release packaging.'
+      end
+
+      def update(target)
+        raise Error, "Select an update target: #{TARGETS.join(', ')}" unless TARGETS.include?(target)
+        return update_artifacts(target) unless target == 'all'
+
+        raise UnavailableFeature,
+              'update all is unavailable: it includes Empeira itself, and self-update is not implemented.'
+      end
+
+      private
+
+      def update_artifacts(target)
+        @build_info.require_compatible!(@context.configuration.dig('requirements', 'empeira'))
+        Infrastructure::Store.new(context: @context).with_lock do
+          runtime = @runtimes.build(@context.container_engine, context: @context, runner: @runner)
+          runtime.check_available!
+          if target == 'modules'
+            Modules.new(context: @context, runtime: runtime, runner: @runner, progress: @progress).synchronize
+          else
+            Images.new(context: @context, runtime: runtime, progress: @progress).refresh
+          end
+        end
+      end
+    end
+  end
+end

data/lib/empeira/version_requirement.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rubygems/requirement'
+require 'rubygems/version'
+
+module Empeira
+  class VersionRequirement
+    def self.parse(value)
+      return if value.nil?
+
+      raise ArgumentError unless valid?(value)
+
+      Gem::Requirement.new(*value.split(',').map(&:strip))
+    rescue ArgumentError
+      raise ConfigurationError, 'requirements.empeira must be a RubyGems version requirement or null', cause: nil
+    end
+
+    def self.valid?(value)
+      value.is_a?(String) && !value.strip.empty? && value.split(',', -1).none? { |part| part.strip.empty? }
+    end
+    private_class_method :valid?
+  end
+end

data/lib/empeira/vm/agent.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Guest package installation uses only the existing allowlisted HTTP/HTTPS proxy.
+    class Agent
+      PUPPET = Node::Certificates::PUPPET
+
+      def initialize(context:, guest:, runtime: nil, progress: Progress.new)
+        @context = context
+        @guest = guest
+        @runtime = runtime
+        @progress = progress
+      end
+
+      def ensure_installed(record, requirements: nil, proxy_url: nil)
+        requirements ||= BootstrapRequirements.new(context: @context, os: record.fetch('os'),
+                                                   version: record.fetch('version'),
+                                                   architecture: record.fetch('architecture'))
+        unless requirements.required?
+          verify_existing_agent!(record)
+          return
+        end
+        raise Error, 'Managed agent installation requires the bootstrap proxy' unless proxy_url
+
+        @proxy_url = proxy_url
+        @requirements = requirements
+        install_selected_agent(record, requirements)
+      ensure
+        @proxy_url = nil
+      end
+
+      private
+
+      attr_reader :proxy_url
+
+      def verify_existing_agent!(record)
+        result = @guest.run(record, [PUPPET, '--version'])
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: 'Existing VM Puppet agent verification',
+                                                         tool: 'puppet')
+        raise Error, 'No usable agent was found and managed bootstrap is unavailable; ' \
+                     "check bootstrap.guests metadata\n#{details}", cause: nil
+      end
+
+      def install_selected_agent(record, requirements)
+        execute = ->(arguments) { @guest.run(record, arguments, timeout: 300) }
+        copy = ->(source, destination, mode) { @guest.copy_to(record, source, destination, mode: mode) }
+        @runtime ||= Runtime.registry.build(@context.container_engine, context: @context, runner: Execution::Runner.new)
+        installer = Node::AgentInstaller.build(context: @context, runtime: @runtime, requirements: requirements,
+                                               execute: execute, copy: copy, progress: @progress)
+        installer.install(proxy_url: proxy_url)
+        execute!(record, [PUPPET, '--version'], 'VM Puppet agent verification')
+      end
+
+      def execute!(record, arguments, operation)
+        result = @guest.run(record, arguments, timeout: 300)
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: operation, tool: arguments.first)
+        raise Error, "#{operation} failed; VM retained for diagnosis\n#{details}", cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/vm/bootstrap_requirements.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Empeira
+  module VM
+    # Reviewed image metadata determines installation needs before any download.
+    class BootstrapRequirements
+      attr_reader :repository, :agent, :guest, :target
+
+      def initialize(context:, os:, version:, agent_required: nil, distribution_required: false,
+                     architecture: context.platform.architecture)
+        config = context.configuration
+        @target = ::Empeira::Agent::Target.new(os: os, release: version, architecture: architecture.to_s)
+        @os = os
+        @architecture = architecture.to_s
+        @guest = config.fetch('bootstrap').fetch('guests').fetch(os).fetch(version)
+        @agent_required = agent_required.nil? ? !guest.fetch('agent_preinstalled') : agent_required
+        @distribution_required = distribution_required || @agent_required
+        return unless @agent_required || @distribution_required
+
+        load_agent(config) if @agent_required
+      rescue KeyError
+        raise ConfigurationError,
+              'No reviewed agent source exists for this guest'
+      end
+
+      def required?
+        @agent_required
+      end
+
+      def destinations
+        distribution_destinations = @distribution_required ? guest_destinations : []
+        distribution_destinations.uniq
+      end
+
+      def report
+        "Managed bootstrap destinations: #{destinations.join(', ')}"
+      end
+
+      def rpm_options
+        return [] unless %w[rocky almalinux].include?(@os)
+
+        architecture = ImageSource::ARCHITECTURES.fetch(@architecture)
+        base = guest.fetch('baseurl')
+        { 'baseos' => 'BaseOS', 'appstream' => 'AppStream', 'extras' => 'extras' }.flat_map do |id, directory|
+          ["--setopt=#{id}.mirrorlist=", "--setopt=#{id}.metalink=",
+           "--setopt=#{id}.baseurl=#{base}/#{directory}/#{architecture}/os/"]
+        end
+      end
+
+      private
+
+      def guest_destinations
+        destinations = guest.fetch('destinations')
+        return destinations unless @os == 'ubuntu'
+
+        irrelevant = @architecture == 'arm64' ? %w[archive.ubuntu.com security.ubuntu.com] : ['ports.ubuntu.com']
+        destinations - irrelevant
+      end
+
+      def load_agent(config)
+        @agent = config.fetch('agent')
+        install = @agent.fetch('install')
+        @repository = target.source(install)
+      end
+    end
+  end
+end

data/lib/empeira/vm/certificate_runtime.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Reuse the same targeted CA enrollment rules as container nodes.
+    class CertificateRuntime
+      def initialize(runtime:, guest:, record:)
+        @runtime = runtime
+        @guest = guest
+        @record = record
+      end
+
+      def service_exec(resource, arguments, timeout: 60)
+        return @guest.run(@record, arguments, timeout: timeout) if resource['vm']
+
+        @runtime.service_exec(resource, arguments, timeout: timeout)
+      end
+
+      def copy_from(resource, source, destination)
+        @runtime.copy_from(resource, source, destination)
+      end
+
+      def copy_to(resource, source, destination)
+        return @guest.copy_to(@record, source, destination) if resource['vm']
+
+        @runtime.copy_to(resource, source, destination)
+      end
+    end
+  end
+end