empeira 0.1.0.pre.alpha.1

data/lib/empeira/infrastructure/service.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Infrastructure
+    # Keep version gating and the single workspace mutation boundary together.
+    # rubocop:disable-next Metrics/ClassLength
+    class Service
+      def initialize(context:, runner:, runtimes:, build_info:, store: Store.new(context: context),
+                     progress: Progress.new)
+        @progress = progress
+        @context = context
+        @runner = runner
+        @runtimes = runtimes
+        @build_info = build_info
+        @store = store
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Read-only artifact validation precedes runtime mutation.
+      def up
+        require_compatible!
+        @store.with_lock do
+          @progress.stage(5, 'Checking runtime and workspace ownership...')
+          state = @store.load
+          runtime = mutation_runtime(state)
+          resource = observe(runtime, state)
+          verify_current!(state, resource)
+          plane = control_plane(runtime)
+          plane.preflight
+          @progress.stage(15, 'Preparing isolated network...')
+          result = ensure_network(runtime, state, resource)
+          changed = plane.up
+          changed = reconcile_nodes || changed
+
+          Providers::Result.new(resource: result.resource, changed: result.changed || changed)
+        end
+      end
+
+      def browser
+        require_compatible!
+        state = @store.load
+        raise Error, browser_workspace_error unless state
+
+        @store.with_lock do
+          state = @store.load
+          raise Error, browser_workspace_error unless state
+
+          @progress.stage(5, 'Checking runtime and workspace ownership...')
+          runtime = mutation_runtime(state)
+          resource = observe(runtime, state)
+          raise Error, browser_network_error unless resource
+
+          verify_current!(state, resource)
+          control_plane(runtime).browser
+        end
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Keep version checks and retained-storage teardown in one lock boundary.
+      def down
+        require_compatible!
+        @store.with_lock do
+          @progress.stage(5, 'Checking runtime and workspace ownership...')
+          state = @store.load
+          runtime = mutation_runtime(state)
+          resource = observe(runtime, state)
+          require_no_nodes!(state)
+
+          changed = control_plane(runtime).down
+          result = runtime.remove_network(definition: definition.network, expected_id: resource&.id)
+          retain_storage
+          Providers::Result.new(resource: result.resource, changed: result.changed || changed)
+        end
+      end
+
+      def destroy
+        Cleanup.new(context: @context, runner: @runner, runtimes: @runtimes, progress: @progress).destroy
+      end
+
+      def status
+        status = Status.new(context: @context, build_info: @build_info, definition: definition)
+        state = @store.load
+        status.record(state)
+        runtime = runtime_for(state&.fetch('runtime') || @context.container_engine)
+        runtime.check_available!
+        status.observe(observe(runtime, state))
+        health_report(status, runtime, state)
+      rescue Error => e
+        status.report.merge('Infrastructure' => 'unknown', 'Diagnostic' => e.message)
+      end
+
+      private
+
+      def definition
+        @definition ||= Definition.new(context: @context)
+      end
+
+      def browser_workspace_error
+        "Workspace is not initialized. Start it with 'empeira up' first."
+      end
+
+      def browser_network_error
+        "Required workspace network is not running. Start the workspace with 'empeira up' first."
+      end
+
+      def reconcile_nodes
+        Node::Service.new(context: @context, runner: @runner, runtimes: @runtimes,
+                          build_info: @build_info, progress: @progress).reconcile(state: @store.load)
+      end
+
+      def destroy_nodes(runtime, state)
+        Node::Container.new(context: @context, runner: @runner, backend: runtime).destroy_all(state: state)
+        engine = VM.registry.build('qemu', context: @context, runner: @runner)
+        Node::VM.new(context: @context, runner: @runner, backend: engine, runtime: runtime)
+                .destroy_all(state: state)
+      end
+
+      def require_no_nodes!(state)
+        return unless state&.fetch('nodes', {})&.any?
+
+        raise Error, 'Nodes exist; destroy them before empeira down, or use empeira destroy for complete removal'
+      end
+
+      def health_report(status, runtime, state)
+        report = status.report.merge(control_plane(runtime).status(state: state))
+        if report['Infrastructure'] == 'up' && report['Control plane'] == 'degraded'
+          report['Infrastructure'] = 'degraded'
+        end
+        report
+      end
+
+      def allocate_network(runtime, state)
+        @peer_network = state&.fetch('peer_network', nil) || {
+          'subnet' => Network::Peer::Allocation.new(context: @context, runtime: runtime, runner: @runner).choose
+        }
+        definition.network.allocation = @peer_network.fetch('subnet')
+        definition.plan.validate_network_redirects!(subnet: @peer_network.fetch('subnet'))
+      end
+
+      def ensure_network(runtime, state, resource)
+        allocate_network(runtime, state)
+        definition.network.policy.require_support!(**runtime.capabilities)
+        persist(state, resource)
+        result = if resource
+                   Providers::Result.new(resource: resource, changed: false)
+                 else
+                   runtime.create_network(definition: definition.network)
+                 end
+        persist(state, result.resource)
+        result
+      end
+
+      def retain_storage
+        retained = @store.load
+        if retained&.dig('control_plane', 'volumes')&.any?
+          retained['resources']['network']['id'] = nil
+          @store.write(retained)
+        else
+          @store.clear
+        end
+      end
+
+      def control_plane(runtime)
+        ControlPlane::Controller.new(context: @context, runtime: runtime, store: @store, runner: @runner,
+                                     plan: definition.plan, progress: @progress)
+      end
+
+      def requirement
+        @context.configuration.fetch('requirements').fetch('empeira')
+      end
+
+      def require_compatible!
+        @build_info.require_compatible!(requirement)
+      end
+
+      def runtime_for(name)
+        @runtimes.build(name, context: @context, runner: @runner)
+      end
+
+      def runtime_mismatch?(state)
+        state && state.fetch('runtime') != @context.container_engine
+      end
+
+      def mutation_runtime(state)
+        if runtime_mismatch?(state)
+          raise Error, "Existing infrastructure belongs to #{state.fetch('runtime')}, configured runtime is " \
+                       "#{@context.container_engine}. Restore the owning runtime and remove retained infrastructure " \
+                       'before switching. ' \
+                       'Runtime migration is not implemented.'
+        end
+        runtime = runtime_for(@context.container_engine)
+        runtime.check_available!
+        runtime
+      end
+
+      def observe(runtime, state)
+        network = definition.network
+        expected_id = state&.dig('resources', 'network', 'id')
+        resource = runtime.inspect_network(identifier: network.backend_name)
+        network.verify_ownership!(resource, expected_id: expected_id)
+        if resource.nil? && expected_id && runtime.inspect_network(identifier: expected_id)
+          raise Providers::OwnershipError,
+                'Recorded network ID exists under a different name; automatic removal refused'
+        end
+
+        resource
+      end
+
+      def verify_current!(state, resource)
+        if state && (state.dig('definition', 'revision') != definition.metadata['revision'] ||
+                     state.dig('component_fingerprints', 'network') != definition.component_fingerprints['network'])
+          raise Error,
+                'Infrastructure definition is stale. Inspect status, then explicitly run ' \
+                'empeira destroy and empeira up.'
+        end
+        return unless resource
+
+        definition.network.verify_definition!(resource)
+        definition.network.verify_isolation!(resource)
+      end
+
+      # The inventory envelope is deliberately written atomically in one operation.
+      # rubocop:disable-next Metrics/AbcSize
+      def persist(previous, resource)
+        now = Time.now.utc.iso8601
+        @store.write(
+          'schema_version' => Store::SCHEMA_VERSION, 'workspace' => @context.workspace.id,
+          'runtime' => @context.container_engine,
+          'resources' => { 'network' => { 'logical_identity' => definition.network.identity,
+                                          'name' => definition.network.backend_name, 'id' => resource&.id } },
+          'fingerprint' => definition.fingerprint, 'definition' => definition.metadata,
+          'component_fingerprints' => definition.component_fingerprints, 'peer_network' => @peer_network,
+          'created_at' => previous&.fetch('created_at') || now, 'reconciled_at' => now,
+          **previous.to_h.slice('nodes', 'retired_certificates', 'control_plane')
+        )
+      end
+    end
+  end
+end

data/lib/empeira/infrastructure/status.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Infrastructure
+    class Status
+      attr_reader :report
+
+      def initialize(context:, build_info:, definition:)
+        @context = context
+        @definition = definition
+        requirement = context.configuration.fetch('requirements').fetch('empeira')
+        @report = {
+          'Workspace' => context.workspace.id, 'Platform' => "#{context.platform.os}/#{context.platform.architecture}",
+          'Empeira version' => build_info.version, 'Project Empeira requirement' => requirement || 'none',
+          'Version requirement' => build_info.requirement_status(requirement),
+          'Configured runtime' => context.container_engine, 'Owning runtime' => 'unknown',
+          'Network' => 'unknown', 'Infrastructure' => 'unknown', 'Infrastructure fingerprint' => 'unknown'
+        }
+      end
+
+      def record(state)
+        @state = state
+        report['Owning runtime'] = state&.fetch('runtime') || 'none recorded'
+        report['Infrastructure fingerprint'] = fingerprint_status
+        report['Runtime ownership'] =
+          if state && state.fetch('runtime') != @context.container_engine
+            'mismatch; restore owning runtime for cleanup'
+          else
+            'consistent'
+          end
+      end
+
+      def observe(resource)
+        report['Network'] = network_status(resource)
+        report['Infrastructure'] = infrastructure_status(resource)
+        return unless resource
+        return if resource.labels['io.empeira.definition'] == @definition.network.labels.fetch('io.empeira.definition')
+
+        report['Infrastructure fingerprint'] = 'stale runtime definition'
+        report['Infrastructure'] = 'stale'
+      end
+
+      private
+
+      def network_status(resource)
+        return 'absent' unless resource
+
+        resource.isolated ? 'isolated' : 'unsafe isolation'
+      end
+
+      def fingerprint_status
+        return 'unrecorded' unless @state
+
+        @state.fetch('fingerprint') == @definition.fingerprint ? 'current' : 'stale'
+      end
+
+      def missing_status
+        return 'down; persistent data retained' if @state&.dig('control_plane', 'stopped')
+
+        @state ? 'missing; reconciliation required' : 'down'
+      end
+
+      def infrastructure_status(resource)
+        return missing_status unless resource
+
+        return 'unsafe; isolation cannot be verified' unless resource.isolated
+        return 'recoverable; local state incomplete' unless @state&.dig('resources', 'network', 'id')
+
+        fingerprint_status == 'current' ? 'up' : 'stale'
+      end
+    end
+  end
+end

data/lib/empeira/infrastructure/store.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+require 'time'
+
+module Empeira
+  module Infrastructure
+    class StateError < Error; end
+    class Locked < Error; end
+
+    # Keep atomic persistence and the complete inventory envelope validator together.
+    # rubocop:disable-next Metrics/ClassLength
+    class Store
+      SCHEMA_VERSION = 2
+      attr_reader :directory
+
+      def initialize(context:, recovery: false)
+        @recovery = recovery
+        @workspace_id = context.workspace.id
+        @state_root = context.locations.state
+        @network = Network::Definition.new(workspace: context.workspace, policy: Network::Policy.new)
+        @directory = context.locations.workspace(context.workspace)
+      end
+
+      # rubocop:disable-next Metrics/MethodLength -- Stable lock ownership, acquisition and release share an ensure boundary.
+      def with_lock
+        verify_paths!(inventory: false)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        verify_paths!(inventory: false)
+        File.open(directory.join('mutation.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+          verify_lock!(lock)
+          unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise Locked, "Another Empeira mutation owns workspace #{@workspace_id}. Wait and retry."
+          end
+
+          begin
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+      rescue SystemCallError
+        raise StateError, 'Cannot access workspace mutation lock', cause: nil
+      end
+
+      def load
+        verify_paths!
+        data = JSON.parse(File.read(path))
+        validate!(data)
+        data
+      rescue Errno::ENOENT
+        raise StateError, 'Infrastructure state is an unreadable symlink' if path.symlink?
+
+        nil
+      rescue JSON::ParserError, SystemCallError
+        raise StateError, 'Cannot read infrastructure state. Preserve it and investigate before retrying.', cause: nil
+      end
+
+      def write(data)
+        verify_paths!
+        validate!(data)
+        Tempfile.create(['state-', '.json'], directory) do |file|
+          file.chmod(0o600)
+          file.write(JSON.pretty_generate(data))
+          file.flush
+          file.fsync
+          File.rename(file.path, path)
+        end
+      rescue SystemCallError, IOError
+        raise StateError, 'Cannot persist infrastructure state. Run status before retrying.', cause: nil
+      end
+
+      def clear
+        verify_paths!
+        File.unlink(path) if path.exist?
+      rescue SystemCallError
+        raise StateError, 'Cannot clear infrastructure state. Run status before retrying.', cause: nil
+      end
+
+      private
+
+      def verify_lock!(lock)
+        metadata = lock.stat
+        return if metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+
+        raise StateError, 'Workspace mutation lock ownership is invalid'
+      end
+
+      def verify_paths!(inventory: true)
+        [@state_root, directory.dirname, directory].each do |entry|
+          verify_directory!(entry)
+        end
+        if directory.exist? && !directory.lstat.mode.nobits?(0o077)
+          raise StateError, 'Workspace state directory is not private'
+        end
+
+        verify_inventory_file! if inventory
+      end
+
+      def verify_directory!(entry)
+        return unless entry.exist? || entry.symlink?
+
+        raise StateError, 'Workspace state directory is an unsafe symlink' if entry.symlink?
+
+        metadata = entry.lstat
+        return if metadata.directory? && metadata.uid == Process.uid
+
+        raise StateError, 'Workspace state directory ownership or path is unsafe'
+      end
+
+      def verify_inventory_file!
+        return unless path.exist? || path.symlink?
+
+        raise StateError, 'Infrastructure state is an unsafe symlink' if path.symlink?
+
+        metadata = path.lstat
+        return if metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+
+        raise StateError, 'Infrastructure state ownership or path is unsafe'
+      end
+
+      def path
+        directory.join('infrastructure.json')
+      end
+
+      def validate!(data)
+        return RecoveryInventory.validate!(data, workspace: @workspace_id) if @recovery
+
+        unless data.is_a?(Hash) && data['schema_version'] == SCHEMA_VERSION && data['workspace'] == @workspace_id
+          raise StateError,
+                'Invalid infrastructure state schema or workspace. Preserve the state and inspect its ownership.'
+        end
+        if legacy_vm_network?(data)
+          raise StateError,
+                'Legacy VM gateway state: use the previous Empeira version to destroy this workspace, then recreate it'
+        end
+        validate_vm_layouts!(data)
+        return if valid_inventory?(data)
+
+        raise StateError, 'Invalid infrastructure inventory. Preserve it for recovery.'
+      end
+
+      def validate_vm_layouts!(data)
+        nodes = data['nodes']
+        return unless nodes.is_a?(Hash)
+
+        nodes.each_value do |record|
+          VM::Management.validate!(record) if record.is_a?(Hash) && record['provider'] == 'vm'
+        end
+      end
+
+      def legacy_vm_network?(data)
+        return true if data.key?('vm_gateway')
+        return false if data.key?('peer_network') || !data['nodes'].is_a?(Hash)
+
+        data['nodes'].values.any? { |record| record.is_a?(Hash) && record['provider'] == 'vm' }
+      end
+
+      def valid_inventory?(data)
+        Runtime.registry.names.include?(data['runtime']) &&
+          data['resources'].is_a?(Hash) && data['resources'].keys == ['network'] &&
+          valid_network?(data['resources']['network']) &&
+          valid_definition?(data) && valid_extensions?(data)
+      end
+
+      def valid_extensions?(data)
+        valid_timestamps?(data) && valid_control_plane?(data) &&
+          (!data.key?('nodes') || Node::Inventory.valid?(data['nodes'])) && valid_peer_network?(data) &&
+          valid_bootstrap_proxy?(data['bootstrap_proxy']) && RecoveryInventory.valid_retired_certificates?(data)
+      end
+
+      def valid_peer_network?(data)
+        return true unless data.key?('peer_network')
+
+        entry = data['peer_network']
+        return false unless entry.is_a?(Hash) && entry.keys == ['subnet']
+
+        layout = Network::Peer::Layout.new(entry['subnet'])
+        valid_peer_leases?(data, layout) && valid_container_leases?(data, layout)
+      rescue Infrastructure::StateError
+        false
+      end
+
+      def valid_peer_leases?(data, layout)
+        leases = data.fetch('nodes', {}).values.select { |record| record['provider'] == 'vm' }
+                     .map { |record| record['peer'] }
+        leases.all? { |lease| layout.valid_lease?(lease) && valid_transport?(lease) } &&
+          leases.map { |lease| lease['ip'] }.uniq.size == leases.size
+      end
+
+      def valid_transport?(lease)
+        %w[LinuxPodman DockerAdapter PodmanMachine].include?(lease['backend']) &&
+          lease['dns'].is_a?(String) && IPAddr.new(lease['dns']).ipv4? &&
+          Node::Inventory.valid_id?(lease['machine']) &&
+          Node::Inventory.valid_certificate?(lease['helper_sha256'])
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      def valid_container_leases?(data, layout)
+        records = data.fetch('nodes', {}).values.select { |record| record['provider'] == 'container' }
+        addresses = records.map { |record| record.dig('definition', 'ip') }
+        addresses.uniq.size == addresses.size && addresses.all? do |ip|
+          (96..127).any? { |offset| layout.address(offset) == ip }
+        end
+      end
+
+      def valid_bootstrap_proxy?(entry)
+        entry.nil? || (entry.is_a?(Hash) && entry.keys == ['id'] && valid_resource_id?(entry['id']))
+      end
+
+      def valid_control_plane?(data)
+        plane = data['control_plane']
+        return true if plane.nil?
+        return false unless plane.is_a?(Hash)
+
+        !plane.key?('provider') &&
+          valid_records?(plane['services'], /\A[a-z][a-z0-9]*(?:-[a-z0-9]+)*\z/) &&
+          valid_records?(plane['volumes'],
+                         /\Aopenvox-(?:ca|ssl|server-data|postgres-data|puppetdb-data)\z/) &&
+          valid_resource_id?(plane['egress']) &&
+          valid_plane_metadata?(plane)
+      end
+
+      def valid_plane_metadata?(plane)
+        flags = [plane['stopped'], plane['bridge_prepared']]
+        flags.all? { |flag| [nil, true, false].include?(flag) } &&
+          (plane['bridge_image'].nil? || plane['bridge_image'].is_a?(String)) &&
+          (plane['gateway_policy'].nil? || valid_code_digest?(plane['gateway_policy'])) &&
+          valid_proxy_reload?(plane['proxy_reload'])
+      end
+
+      def valid_proxy_reload?(checkpoint)
+        return true if checkpoint.nil?
+
+        checkpoint.is_a?(Hash) && checkpoint.keys.sort == %w[fingerprint id] &&
+          checkpoint['id'].is_a?(String) && valid_resource_id?(checkpoint['id']) &&
+          valid_code_digest?(checkpoint['fingerprint'])
+      end
+
+      def valid_code_digest?(value)
+        value.is_a?(String) && value.match?(/\A[a-f0-9]{64}\z/)
+      end
+
+      def valid_records?(records, pattern)
+        records.is_a?(Hash) && records.all? do |key, value|
+          key.is_a?(String) && key.match?(pattern) && value.is_a?(Hash) &&
+            value.keys == ['id'] && valid_resource_id?(value['id'])
+        end
+      end
+
+      def valid_definition?(data)
+        data['definition'].is_a?(Hash) && data['definition']['revision'].is_a?(Integer) &&
+          data['definition']['runtime'] == data['runtime'] &&
+          data['fingerprint'] == Definition.fingerprint(data['definition'])
+      end
+
+      def valid_timestamps?(data)
+        %w[created_at reconciled_at].all? { |key| data[key].is_a?(String) }
+      end
+
+      def valid_resource_id?(id)
+        id.nil? || (id.is_a?(String) && id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/))
+      end
+
+      def valid_network?(network)
+        network.is_a?(Hash) && network['logical_identity'] == @network.identity &&
+          network['name'] == @network.backend_name &&
+          valid_resource_id?(network['id'])
+      end
+    end
+  end
+end

data/lib/empeira/modules/events.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Modules
+    # Only controlled worker records affect counts; ordinary tool output stays buffered.
+    class Events
+      attr_reader :name
+
+      def initialize(progress:)
+        @progress = progress
+        @pending = +''.b
+        @completed = []
+      end
+
+      def observe(chunk)
+        @pending << chunk
+        while (line = @pending.slice!(/.*?\n/m))
+          event = line.match(/\AEMPEIRA_MODULE_(TOTAL|START|DONE):([a-z0-9_]+)\n\z/)
+          receive(*event.captures) if event
+        end
+        @pending.clear if @pending.bytesize > 1024
+      end
+
+      def start(name)
+        @name = name
+        show
+      end
+
+      def finish!
+        raise Error, 'Incomplete Puppetfile module progress protocol' unless @total == @completed.size
+      end
+
+      private
+
+      def receive(kind, value)
+        case kind
+        when 'TOTAL' then total(value)
+        when 'START' then start(value)
+        when 'DONE' then done(value)
+        end
+      end
+
+      def total(value)
+        raise Error, 'Invalid Puppetfile module total' unless @total.nil? && value.match?(/\A\d+\z/)
+
+        @total = Integer(value, 10)
+        @name = 'Puppetfile modules'
+        show
+      end
+
+      def done(name)
+        unless name == @name && @total && @completed.size < @total && !@completed.include?(name)
+          raise Error, 'Invalid Puppetfile module completion record'
+        end
+
+        @completed << name
+        show
+      end
+
+      def show
+        return @progress.heartbeat(@name) unless @total
+
+        @progress.count(@completed.size, @total, "#{@name} (#{@completed.size}/#{@total})")
+      end
+    end
+  end
+end