empeira 0.1.0.pre.alpha.1

data/lib/empeira/modules/git_safety.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    class GitSafety
+      def initialize(project:, runner:, progress: Progress.new)
+        @project = project
+        @runner = runner
+        @progress = progress
+      end
+
+      def verify(path, recommend: false)
+        relative = relative_path(path)
+        return unless relative
+        raise Error, 'The managed module path cannot be the control-repository root' if relative == '.'
+
+        tracked = git('ls-files', '--cached', '-z', '--', ":(literal)#{relative}")
+        raise Error, 'Cannot verify Git-tracked contents of the managed module path' unless tracked.success?
+        unless tracked.stdout.empty?
+          raise Error,
+                'The managed module path contains Git-tracked files; refusing to modify it'
+        end
+
+        recommend_ignore(relative) if recommend
+      end
+
+      def self.canonical_path(path)
+        return path.realpath if path.exist? || path.symlink?
+
+        canonical_path(path.parent).join(path.basename)
+      rescue SystemCallError
+        raise Error, 'Cannot resolve the managed module path for Git safety checks', cause: nil
+      end
+
+      private
+
+      def relative_path(path)
+        canonical = self.class.canonical_path(path.expand_path)
+        return unless canonical == @project || canonical.to_s.start_with?("#{@project}/")
+
+        canonical.relative_path_from(@project).to_s
+      end
+
+      def recommend_ignore(relative)
+        ignored = git('check-ignore', '--quiet', '--', "#{relative}/")
+        return if ignored.success? || @recommended
+        unless ignored.exit_status == 1 && !ignored.timed_out
+          raise Error, 'Cannot determine whether Git ignores the managed module path'
+        end
+
+        @progress.warning("Recommendation: #{relative}/ is not ignored by Git. Add /#{relative}/ to .gitignore.")
+        @recommended = true
+      end
+
+      def git(*arguments)
+        @runner.run('git', arguments: arguments, directory: @project, timeout: 15)
+      end
+    end
+  end
+end

data/lib/empeira/modules/host_git.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Empeira
+  module Modules
+    # Source acquisition deliberately uses the invoking user's Git/OpenSSH context.
+    # Persistent bare repositories are mounted read-only; SSH credentials never enter the helper.
+    class HostGit
+      def initialize(runner:, project:, progress: Progress.new, passive: false)
+        @runner = runner
+        @project = project
+        @progress = progress
+        @passive = passive
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Acquire each host source and notify its module before network access.
+      def prepare(entries, directory:)
+        validate!(entries)
+        entries.to_h do |entry|
+          block_given? ? yield(entry.fetch('name')) : @progress.heartbeat(entry.fetch('name'))
+          mirror = source_path(directory, entry.fetch('remote'))
+
+          result = clone(acquisition_arguments(entry.fetch('remote'), mirror))
+          fail_acquisition(entry.fetch('name'), result) unless result.success?
+          [entry.fetch('name'), mirror.to_s]
+        end
+      end
+
+      def self.valid_remote?(remote)
+        return false unless remote.is_a?(String) && !remote.start_with?('-') && !remote.match?(/[\x00-\x1f]/)
+        return remote.match?(/\A(?:[\w.-]+@)?[\w.-]+:[^:].*\z/) unless remote.include?('://')
+
+        valid_uri?(URI.parse(remote))
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def self.valid_uri?(uri)
+        %w[ssh http https].include?(uri.scheme) && uri.host && !uri.host.start_with?('-') &&
+          (uri.scheme == 'ssh' ? uri.password.nil? : uri.userinfo.nil?)
+      end
+
+      private
+
+      def source_path(directory, remote)
+        path = Pathname(directory).join("#{Digest::SHA256.hexdigest(remote)}.git")
+        raise Error, 'Git source cache must not be a symlink' if path.symlink?
+
+        path
+      end
+
+      def acquisition_arguments(remote, mirror)
+        return ['clone', '--mirror', '--template=', '--', remote, mirror.to_s] unless mirror.exist?
+
+        ['-C', mirror.to_s, 'fetch', '--prune', '--force', '--', remote, '+refs/*:refs/*']
+      end
+
+      def fail_acquisition(name, result)
+        diagnostic = Execution::Diagnostics.native(result, operation: "Acquire Git source for #{name}", tool: 'git/ssh')
+        raise Error, "Module: #{name}\nError: Git source acquisition failed" \
+                     "#{' (timed out)' if result.timed_out}\n\ngit/ssh output:\n#{diagnostic}", cause: nil
+      end
+
+      def clone(arguments)
+        if @passive
+          arguments = ['-c', "core.hooksPath=#{File::NULL}", '-c', 'core.fsmonitor=false',
+                       '-c', 'submodule.recurse=false', '-c', 'protocol.ext.allow=never', *arguments]
+        end
+        if $stdin.tty? && $stderr.tty?
+          @runner.buffered('git', arguments: arguments, directory: @project)
+        else
+          @runner.run('git', arguments: arguments, directory: @project, timeout: 300)
+        end
+      end
+
+      def validate!(entries)
+        unless entries.is_a?(Array) && entries.all? { |entry| valid_entry?(entry) } &&
+               entries.map { |entry| entry['name'] }.uniq.size == entries.size
+          raise Error, 'Puppetfile installer returned an invalid Git source plan'
+        end
+      end
+
+      def valid_entry?(entry)
+        entry.is_a?(Hash) && entry.keys.sort == %w[name remote] &&
+          entry['name'].is_a?(String) && entry['name'].match?(Configuration::HieraMountSchema::NAME) &&
+          self.class.valid_remote?(entry['remote'])
+      end
+    end
+  end
+end

data/lib/empeira/modules/image.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    class Image
+      def initialize(config, registry: nil)
+        @config = config
+        @registry = registry
+      end
+
+      def files
+        %w[Gemfile Gemfile.lock worker.rb].to_h do |name|
+          [name, File.read(File.join(Images::Configuration::ROOT, 'modules', name))]
+        end
+      end
+
+      def recipe
+        source = Images::Configuration.recipe(@config, registry: @registry)
+        "#{source}\n# Managed build inputs: #{Infrastructure::Definition.fingerprint(files)}\n"
+      end
+
+      def reference
+        Images::Configuration.local_image(recipe, purpose: 'r10k')
+      end
+    end
+  end
+end

data/lib/empeira/modules/installer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    class Installer
+      def initialize(runtime:, image:, git:, progress: Progress.new)
+        @git = git
+        @runtime = runtime
+        @image = image
+        @progress = progress
+        @events = Events.new(progress: progress)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Plan, host acquisition, sync and cleanup share one disposable helper.
+      def synchronize(request, destination, state:)
+        request.data.fetch('overrides').each { |name| @progress.heartbeat("#{name} (local override)") }
+        Dir.mktmpdir('empeira-puppetfile-') do |input|
+          write_input(request, input, state)
+          @sources = state.sources
+          @runtime.with_update_helper(image: @image, input: input, output: destination,
+                                      sources: state.sources, cache: state.cache) do |resource|
+            @resource = resource
+            execute('plan')
+            acquire_git
+            execute('sync')
+            @events.finish!
+            @names | request.data.fetch('overrides')
+          end
+        end
+      end
+
+      private
+
+      def execute(mode)
+        command = ['ruby', '/opt/empeira-modules/worker.rb', '/work', mode]
+        result = @runtime.service_exec(@resource, command, timeout: 600, on_stdout: @events.method(:observe))
+        return if result.success?
+
+        diagnostic = Execution::Diagnostics.native(result, operation: "Puppetfile #{mode}", tool: 'r10k')
+        raise Error, "Puppetfile synchronization failed#{' (timed out)' if result.timed_out}:\n" \
+                     "#{"Module: #{@events.name}\n" if @events.name}#{diagnostic}", cause: nil
+      end
+
+      def acquire_git
+        Dir.mktmpdir('empeira-git-sources-') do |directory|
+          plan = File.join(directory, 'git-sources.json')
+          @runtime.copy_from(@resource, '/work/git-sources.json', plan)
+          plan_data = JSON.parse(File.read(plan))
+          @names = plan_data.fetch('names')
+          acquired = @git.prepare(plan_data.fetch('git'), directory: @sources) { |name| @events.start(name) }
+          path = File.join(directory, 'acquired.json')
+          File.write(path, JSON.generate(acquired))
+          @runtime.copy_to(@resource, path, '/work/acquired.json') unless acquired.empty?
+        end
+      rescue JSON::ParserError, SystemCallError
+        raise Error, 'Cannot transfer the Puppetfile Git source plan or cache locations', cause: nil
+      end
+
+      def write_input(request, directory, state)
+        data = request.data.merge('sources' => state.sources.to_s, 'cache' => state.cache.to_s)
+        { 'Puppetfile' => request.puppetfile, 'request.json' => JSON.generate(data) }.each do |name, content|
+          File.write(File.join(directory, name), content, mode: 'wx', perm: 0o600)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/modules/request.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    class Request
+      attr_reader :puppetfile, :data
+
+      def initialize(context:)
+        @context = context
+        @project = context.project.path
+        @config = context.configuration
+        @hiera = Configuration::HieraMounts.new(config: @config.fetch('hiera'), project: @project,
+                                                environment: @config.dig('server', 'environment'))
+        @overrides = @hiera.entries.select { |entry| entry['type'] == 'module' && entry['status'] == 'available' }
+                           .map { |entry| entry.fetch('name') }.sort
+        load_file
+      end
+
+      def warnings
+        @hiera.warnings
+      end
+
+      def present?
+        !puppetfile.nil?
+      end
+
+      def verify_available!
+        return unless present?
+
+        root = Storage.new(context: @context).root
+        return if State.new(context: @context).available?(root, overrides: data.fetch('overrides'))
+
+        raise Error, "Puppetfile modules are not available.\nRun: empeira update modules"
+      end
+
+      private
+
+      def load_file
+        path = @project.join('Puppetfile')
+        return unless path.exist? || path.symlink?
+        raise ConfigurationError, 'Puppetfile must be a readable regular file inside the control repository' unless
+          path.file? && path.realpath.to_s.start_with?("#{@project}/")
+
+        verify_modulepath!
+        validate_environment_mounts!
+        @puppetfile = path.binread
+        @data = { 'overrides' => @overrides }
+      rescue SystemCallError
+        raise ConfigurationError, 'Cannot read Puppetfile or control-repository modules', cause: nil
+      end
+
+      def verify_modulepath!
+        environment = @config.dig('server', 'environment')
+        Configuration::HieraModulepath.new(project: @project, environment: environment).verify!
+      end
+
+      def validate_environment_mounts!
+        @hiera.entries.each_with_index do |entry, index|
+          next unless entry['status'] == 'available' && entry['type'] == 'environment'
+          next unless Configuration::HieraMountSchema.overlap?(entry.fetch('target'), 'modules')
+
+          raise ConfigurationError,
+                "hiera.mounts.#{index}.target overlaps Puppetfile modules; use type: module for local overrides"
+        end
+      end
+    end
+  end
+end

data/lib/empeira/modules/state.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    # Native tooling caches and a small optional list of installed names, never input/tree fingerprints.
+    class State
+      attr_reader :sources, :cache
+
+      def initialize(context:)
+        @workspace = context.workspace.id
+        @directory = context.locations.workspace(context.workspace)
+        @path = @directory.join('module-sync.json')
+        @sources = @directory.join('r10k', 'sources')
+        @cache = @directory.join('r10k', 'cache')
+      end
+
+      def available?(root, overrides: [])
+        return false unless root.directory?
+
+        names = installed_names(root)
+        !names.nil? && names.all? { |name| overrides.include?(name) || populated?(root.join(name)) }
+      rescue SystemCallError, JSON::ParserError
+        raise Error, 'Cannot read module synchronization metadata', cause: nil
+      end
+
+      def prepare
+        [sources.parent, sources, cache].each do |path|
+          raise Error, 'r10k cache directories must not be symlinks' if path.symlink?
+
+          FileUtils.mkdir_p(path, mode: 0o700)
+        end
+      end
+
+      def invalidate
+        raise Error, 'Module synchronization metadata must not be a symlink' if @path.symlink?
+
+        @path.unlink if @path.exist?
+      end
+
+      def record(root, names)
+        data = { 'version' => 1, 'workspace' => @workspace, 'path' => root.to_s, 'names' => names }
+        Tempfile.create(['module-sync-', '.json'], @directory) do |file|
+          file.chmod(0o600)
+          file.write(JSON.generate(data))
+          file.flush
+          File.rename(file.path, @path)
+        end
+      end
+
+      private
+
+      def installed_names(root)
+        raise Error, 'Module synchronization metadata must not be a symlink' if @path.symlink?
+
+        data = read if @path.exist?
+        data && data['path'] == root.to_s ? data['names'] : existing_names(root)
+      end
+
+      def read
+        data = JSON.parse(@path.read)
+        raise Error, 'Invalid module synchronization metadata; inspect the workspace state' unless valid?(data)
+
+        data
+      end
+
+      def valid?(data)
+        data.is_a?(Hash) && data['workspace'] == @workspace && data['version'] == 1 &&
+          data['path'].is_a?(String) && valid_names?(data['names'])
+      end
+
+      def valid_names?(names)
+        names.is_a?(Array) && names.all? { |name| name.is_a?(String) && name.match?(Configuration::HieraMountSchema::NAME) }
+      end
+
+      def existing_names(root)
+        names = root.children.filter_map do |path|
+          path.basename.to_s if populated?(path) && path.basename.to_s.match?(Configuration::HieraMountSchema::NAME)
+        end
+        names unless names.empty?
+      end
+
+      def populated?(path)
+        path.directory? && !path.symlink? && !path.children.empty?
+      end
+    end
+  end
+end

data/lib/empeira/modules/storage.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    # The configured path is the module directory itself, never a deployment cache.
+    class Storage
+      attr_reader :root
+
+      def initialize(context:)
+        project = context.project.path
+        @root = GitSafety.canonical_path(Pathname(context.configuration.dig('modules', 'path')).expand_path(project))
+        validate_root!(project)
+      end
+
+      def prepare
+        raise Error, 'modules.path must be a directory' if root.exist? && !root.directory?
+
+        FileUtils.mkdir_p(root)
+      rescue SystemCallError
+        raise Error, 'Cannot create the configured module directory', cause: nil
+      end
+
+      private
+
+      def validate_root!(project)
+        git = project.join('.git')
+        return unless root == project || project.to_s.start_with?("#{root}/") || root == root.parent ||
+                      root == git || root.to_s.start_with?("#{git}/")
+
+        raise ConfigurationError,
+              'modules.path must not contain the control repository, a filesystem root or Git metadata'
+      end
+    end
+  end
+end

data/lib/empeira/network/bootstrap_proxy.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Empeira
+  module Network
+    # A temporary authenticated Squid gateway, managed under the workspace transaction.
+    # No credentials enter inventory, image definitions, guest seeds or logs.
+    # rubocop:disable-next Metrics/ClassLength -- One ownership transaction coordinates temporary gateway recovery.
+    class BootstrapProxy
+      attr_reader :url
+
+      def initialize(context:, runtime:, store:)
+        @context = context
+        @runtime = runtime
+        @store = store
+        @plan = ControlPlane::Plan.new(context: context)
+        @files = @plan.files
+      end
+
+      def preflight!(state)
+        @plan.subnet = state.fetch('peer_network').fetch('subnet')
+        @dns = service_address(state, 'dns')
+        service_address(state, 'gateway')
+        egress = Network::Egress.new(workspace: @context.workspace, policy: Network::Policy.new)
+        resource = @runtime.inspect_network(identifier: egress.backend_name)
+        egress.verify_ownership!(resource, expected_id: state.dig('control_plane', 'egress'))
+        raise Error, 'Control-plane egress is unavailable; run empeira up first' unless resource
+
+        egress.verify_isolation!(resource)
+      end
+
+      def start(state, requirements, source:)
+        preflight!(state)
+        cleanup(state)
+        reject_unrecorded!
+        token = SecureRandom.hex(32)
+        prepare_policy(token, requirements, source)
+        definition = @plan.bootstrap_proxy(dns: @dns)
+        @runtime.ensure_image(definition.options.fetch('image'), recipe: definition.options['recipe'])
+        resource = create(state, definition)
+        address = connect_and_verify(resource, definition, state)
+        @url = "http://bootstrap:#{token}@#{address}:3128"
+        wait_ready(state, address)
+        address
+      end
+
+      def cleanup(state)
+        return unless state.key?('bootstrap_proxy')
+
+        entry = state.fetch('bootstrap_proxy')
+        definition = Services::Definition.new(key: 'bootstrap-proxy', workspace: @context.workspace)
+        remove_owned(definition, entry.fetch('id'))
+        policy = @files.path('bootstrap-squid.conf')
+        File.unlink(policy) if File.exist?(policy) || File.symlink?(policy)
+        state.delete('bootstrap_proxy')
+        @store.write(state)
+        @url = nil
+      rescue SystemCallError
+        raise Error, 'Cannot remove bootstrap proxy credentials; cleanup is incomplete and Puppet was not run'
+      end
+
+      private
+
+      def connect_and_verify(resource, definition, state)
+        @runtime.start_service(resource)
+        observed = @runtime.inspect_service(definition, expected_id: resource.fetch('id'))
+        address = verify_endpoint(observed)
+        Gateway.new(context: @context, runtime: @runtime, state: state).route(observed)
+        address
+      end
+
+      def reject_unrecorded!
+        definition = Services::Definition.new(key: 'bootstrap-proxy', workspace: @context.workspace)
+        return unless @runtime.inspect_service(definition)
+
+        raise Providers::OwnershipError, 'Unrecorded bootstrap proxy exists; refusing adoption'
+      end
+
+      def remove_owned(definition, id)
+        @runtime.remove_service(definition, expected_id: id)
+      rescue Providers::ExecutionError
+        resource = @runtime.inspect_service(definition, expected_id: id)
+        @runtime.stop_service(resource) if resource && resource['state'] == 'running'
+        raise
+      end
+
+      def create(state, definition)
+        state['bootstrap_proxy'] = { 'id' => nil }
+        @store.write(state)
+        resource = @runtime.create_service(definition)
+        state['bootstrap_proxy']['id'] = resource.fetch('id')
+        @store.write(state)
+        resource
+      end
+
+      def service_address(state, key)
+        expected = state.dig('control_plane', 'services', key, 'id')
+        raise Error, "#{key} is not recorded; run empeira up first" unless expected
+
+        resource = @runtime.inspect_service(@plan.definitions.fetch(key), expected_id: expected)
+        address = resource&.dig('networks', @plan.network, 'IPAddress')
+        raise Error, "#{key} is unavailable; run empeira up first" unless resource&.dig('state') == 'running' && address
+
+        IPAddr.new(address).to_s
+      end
+
+      def prepare_policy(token, requirements, source)
+        authorization = ["bootstrap:#{token}"].pack('m0')
+        config = { 'global' => requirements.destinations }
+        policy = ProxyPolicy.new(config, authorization: authorization)
+        content = policy.configuration.gsub('@EMPEIRA_DNS@', @dns)
+        IPAddr.new(source)
+        content = "acl provisioning_vm src #{source}/32\nhttp_access deny !provisioning_vm\n#{content}"
+        @files.write('bootstrap-squid.conf', content)
+      end
+
+      def verify_endpoint(resource)
+        expected = [@plan.network]
+        unless resource && resource['state'] == 'running' && resource.fetch('networks').keys.sort == expected &&
+               unpublished?(resource)
+          raise Providers::OwnershipError, 'Bootstrap proxy has unexpected network attachments or published ports'
+        end
+
+        IPAddr.new(resource.fetch('networks').fetch(@plan.network).fetch('IPAddress')).to_s
+      end
+
+      def unpublished?(resource)
+        resource.fetch('ports').empty? && resource.fetch('published_ports').values.all?(&:nil?)
+      end
+
+      def readiness_probe
+        's=TCPSocket.new(ARGV[0],3128);s.write("GET http://bootstrap.invalid/ HTTP/1.0\r\n\r\n");' \
+          'line=s.gets.to_s;abort(line) unless line.match?(/HTTP\/1\.[01] 403 /)'
+      end
+
+      def wait_ready(state, address)
+        server = @runtime.inspect_service(@plan.definitions.fetch('server'),
+                                          expected_id: state.dig('control_plane', 'services', 'server', 'id'))
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30
+        loop do
+          result = @runtime.service_exec(server, [Node::Certificates::RUBY, '-rsocket', '-e',
+                                                  readiness_probe, address], timeout: 3)
+          return if result.success?
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            detail = Execution::Diagnostics.native(result, operation: 'Bootstrap proxy readiness', tool: 'ruby',
+                                                           url: 'http://bootstrap.invalid/')
+            raise Error, "Bootstrap proxy did not become reachable on the peer network\n#{detail}", cause: nil
+          end
+
+          sleep 0.2
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/definition.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    class Definition
+      LABEL_PREFIX = 'io.empeira'
+      attr_reader :workspace, :policy
+      attr_accessor :allocation
+
+      def initialize(workspace:, policy:, revision: 2)
+        @workspace = workspace
+        @policy = policy
+        @revision = revision
+      end
+
+      def identity
+        "#{workspace.id}:environment"
+      end
+
+      def backend_name
+        "empeira-#{workspace.id}-network"
+      end
+
+      def labels
+        ownership_labels.merge('io.empeira.definition' => Infrastructure::Definition.fingerprint(to_h))
+      end
+
+      def ownership_labels
+        { "#{LABEL_PREFIX}.managed-by" => 'empeira', "#{LABEL_PREFIX}.workspace" => workspace.id,
+          "#{LABEL_PREFIX}.purpose" => 'environment-network' }
+      end
+
+      def verify_ownership!(resource, expected_id: nil)
+        return unless resource
+
+        owned = resource.name == backend_name && ownership_labels.all? { |key, value| resource.labels[key] == value }
+        return if owned && (expected_id.nil? || resource.id == expected_id)
+
+        raise Providers::OwnershipError, "Network ownership or recorded ID conflicts for workspace #{workspace.id}"
+      end
+
+      def verify_definition!(resource)
+        return if resource.labels['io.empeira.definition'] == labels.fetch('io.empeira.definition')
+
+        raise Error, 'Network definition is stale or unknown. Run empeira down before recreating it.'
+      end
+
+      def verify_isolation!(resource)
+        return if resource&.isolated == true
+
+        raise UnsupportedPolicy, "Cannot verify isolated network for workspace #{workspace.id}"
+      end
+
+      def to_h
+        { 'identity' => identity, 'backend_name' => backend_name,
+          'policy' => { 'isolated' => true, 'controlled_egress' => false },
+          'labels' => ownership_labels, 'revision' => @revision }
+      end
+    end
+  end
+end