empeira 0.1.0.pre.alpha.1

data/lib/empeira/network/direct_egress.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'socket'
+
+module Empeira
+  module Network
+    module DirectEgress
+      DNS_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?'
+      DNS_NAME = /\A#{DNS_LABEL}(?:\.#{DNS_LABEL})*\z/
+      MAX_HOSTS = 256
+      BENCHMARK = IPAddr.new('198.18.0.0/15').freeze
+
+      Resolved = Data.define(:entries) do
+        def fingerprint
+          Infrastructure::Definition.fingerprint(entries)
+        end
+
+        def configuration
+          JSON.generate('version' => 1, 'entries' => entries)
+        end
+      end
+
+      module_function
+
+      def validate!(value, path = 'network.egress')
+        return legacy!(value, path) if value.is_a?(Hash)
+        unless value.is_a?(Array) && value.size <= MAX_HOSTS
+          raise ConfigurationError, "#{path} must be an array with at most #{MAX_HOSTS} destination entries"
+        end
+
+        hosts = value.each_with_index.map { |entry, index| validate_entry!(entry, "#{path}[#{index}]") }
+        raise ConfigurationError, "#{path} contains duplicate destinations" unless hosts.uniq.size == hosts.size
+      end
+
+      def legacy!(value, path)
+        return if value.keys == ['mode'] && %w[none proxy].include?(value['mode'])
+
+        raise ConfigurationError, "#{path} must be a host array (legacy mode accepts only none or proxy)"
+      end
+
+      def destinations(value)
+        return [] unless value.is_a?(Array)
+
+        value.map { |entry| entry.fetch('host') { entry.fetch('ip') } }
+      end
+
+      def validate_entry!(entry, path)
+        unless entry.is_a?(Hash) && [%w[host ports], %w[ip ports]].include?(entry.keys.sort)
+          raise ConfigurationError, "#{path} must contain ports and exactly one of host or ip"
+        end
+
+        entry.key?('host') ? validate_host!(entry['host'], path) : validate_ip!(entry['ip'], path)
+        validate_ports!(entry['ports'], path)
+        entry.slice('host', 'ip')
+      end
+
+      def validate_host!(host, path)
+        if host.is_a?(String) && host.size <= 253 && host.match?(DNS_NAME) &&
+           host.include?('.') && !host.match?(/\A[\d.]+\z/)
+          return
+        end
+
+        raise ConfigurationError, "#{path}.host must be a lowercase DNS hostname"
+      end
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- Exact IPv4 syntax and scoped benchmark exception share validation.
+      def validate_ip!(value, path, allow_benchmark: false)
+        raise IPAddr::InvalidAddressError unless value.is_a?(String) && !value.include?('/')
+
+        ip = IPAddr.new(value)
+        raise ConfigurationError, "#{path}.ip: IPv6 is not supported; the workspace is IPv4-only" if ip.ipv6?
+        if BENCHMARK.include?(ip) && !allow_benchmark
+          raise ConfigurationError, "#{path}.ip: benchmark addresses are reserved for validated redirect sources"
+        end
+        return if ip.to_s == value
+
+        raise ConfigurationError, "#{path}.ip must be an explicit IPv4 address"
+      rescue IPAddr::InvalidAddressError
+        raise ConfigurationError, "#{path}.ip must be an explicit IPv4 address", cause: nil
+      end
+
+      def validate_ports!(ports, path)
+        valid = ports.is_a?(Array) && !ports.empty? && ports.uniq.size == ports.size &&
+                ports.all? { |port| port.is_a?(Integer) && port.between?(1, 65_535) }
+        return if valid
+
+        raise ConfigurationError, "#{path}.ports must contain unique TCP ports from 1 through 65535"
+      end
+
+      class Resolver
+        def initialize(lookup: nil, logger: nil)
+          @lookup = lookup || method(:addresses)
+          @logger = logger
+        end
+
+        def resolve(config)
+          entries = config.is_a?(Array) ? config : []
+          return Resolved.new([].freeze) if entries.empty?
+
+          resolved = entries.map { |entry| resolve_entry(entry) }.sort_by { |entry| entry['host'] || entry['ip'] }
+          Resolved.new(resolved.freeze)
+        end
+
+        private
+
+        # rubocop:disable-next Metrics/AbcSize -- Resolve one complete nonsecret destination including the benchmark exclusion.
+        def resolve_entry(entry)
+          host = entry['host']
+          addresses = entry.key?('ip') ? [entry.fetch('ip')] : ipv4_addresses(host)
+          if addresses.any? { |address| BENCHMARK.include?(address) }
+            raise Error, 'Direct-egress resolution includes a benchmark address reserved for redirect sources'
+          end
+          raise Error, "Direct-egress host did not resolve to a supported IPv4 address: #{host}" if addresses.empty?
+
+          ports = entry.fetch('ports').sort
+          @logger&.call(operation: 'direct_egress_resolution', host: host, addresses: addresses, ports: ports)
+          entry.slice('host', 'ip').merge('addresses' => addresses, 'ports' => ports).freeze
+        rescue IPAddr::InvalidAddressError, SocketError
+          raise Error, "Direct-egress host could not be resolved: #{host}", cause: nil
+        end
+
+        def ipv4_addresses(host)
+          @lookup.call(host).map { |value| IPAddr.new(value) }.select(&:ipv4?).map(&:to_s).uniq.sort
+        end
+
+        def addresses(host)
+          Socket.getaddrinfo(host, nil, Socket::AF_UNSPEC, Socket::SOCK_STREAM).map { |entry| entry[3] }
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/egress.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    class Egress < Definition
+      def identity
+        "#{workspace.id}:egress"
+      end
+
+      def backend_name
+        "empeira-#{workspace.id}-egress"
+      end
+
+      def ownership_labels
+        super.merge('io.empeira.purpose' => 'proxy-egress-network')
+      end
+
+      def verify_isolation!(resource)
+        raise UnsupportedPolicy, 'Proxy egress network unexpectedly isolated' unless resource && !resource.isolated
+      end
+
+      def to_h
+        super.merge('policy' => { 'isolated' => false, 'proxy_only' => true })
+      end
+    end
+  end
+end

data/lib/empeira/network/gateway.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    # One policy, addressing and TCP translation boundary for every peer backend.
+    class Gateway
+      OFFSETS = { 'gateway' => 2, 'dns' => 3, 'proxy' => 4, 'bootstrap-proxy' => 5 }.freeze
+      EXECUTABLE = '/usr/local/libexec/empeira-gateway'
+
+      def self.address(subnet, key = 'gateway')
+        Peer::Layout.new(subnet).address(OFFSETS.fetch(key))
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Compose the complete provider-independent firewall input.
+      def self.plan(state:, resolved:, upstreams:, routes:, additional: nil, redirects: [])
+        subnet = state.fetch('peer_network').fetch('subnet')
+        resolvers = (upstreams + routes.values.flatten + additional_addresses(additional)).uniq.sort
+        unless resolvers.all? { |address| IPAddr.new(address).ipv4? }
+          raise Error, 'Gateway is IPv4-only; configure reachable IPv4 DNS upstreams'
+        end
+
+        { 'version' => 1, 'subnet' => subnet, 'gateway' => address(subnet),
+          'dns' => address(subnet, 'dns'), 'resolvers' => resolvers,
+          'proxies' => %w[proxy bootstrap-proxy].map { |key| address(subnet, key) },
+          'blocked' => blocked_addresses(state), 'entries' => resolved.entries, 'redirects' => redirects }
+      end
+
+      def self.blocked_addresses(state)
+        state.fetch('nodes', {}).values.filter_map do |node|
+          node.dig('peer', 'ip') || node.dig('definition', 'ip') if node['network_phase'] == 'bootstrap'
+        end.sort
+      end
+
+      def self.additional_addresses(value)
+        return [] if value.nil? || value.end_with?('.empeira.internal')
+
+        return [value] if value.match?(/\A[\d.]+\z/)
+
+        Socket.getaddrinfo(value, nil, Socket::AF_INET, Socket::SOCK_STREAM).map { |entry| entry[3] }.uniq
+      rescue SocketError
+        raise Error, "Gateway DNS resolution failed for additional resolver #{value}", cause: nil
+      end
+
+      def initialize(context:, runtime:, state:)
+        @context = context
+        @runtime = runtime
+        @state = state
+      end
+
+      def route(resource)
+        subnet = @state.fetch('peer_network').fetch('subnet')
+        @runtime.configure_workspace_route(resource, gateway: self.class.address(subnet),
+                                                     image: ControlPlane::Plan.new(context: @context)
+                                                                              .gateway_artifact.fetch(:image))
+      end
+
+      def update_phase_plan(ip, bootstrap:)
+        files = ControlPlane::Files.new(context: @context)
+        plan = JSON.parse(File.binread(files.path('gateway.json')))
+        plan['blocked'] = (plan.fetch('blocked') - [ip] + (bootstrap ? [ip] : [])).sort
+        files.write('gateway.json', JSON.generate(plan))
+      end
+
+      # Bootstrap exclusion is changed inside the gateway, before a new node starts.
+      def phase(record, bootstrap:)
+        identity = Services::Definition.new(key: 'gateway', workspace: @context.workspace)
+        resource = @runtime.inspect_service(identity,
+                                            expected_id: @state.dig('control_plane', 'services', 'gateway', 'id'))
+        raise Error, 'Gateway is unavailable; run empeira up' unless resource && resource['state'] == 'running'
+
+        ip = record.dig('peer', 'ip') || record.dig('definition', 'ip')
+        result = @runtime.service_exec(resource, [EXECUTABLE, bootstrap ? 'block' : 'unblock', ip])
+        raise Error, 'Gateway bootstrap firewall reconcile failed' unless result.success?
+
+        update_phase_plan(ip, bootstrap: bootstrap)
+      end
+    end
+  end
+end

data/lib/empeira/network/host_policy.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    class HostPolicy
+      def self.validate!(rules, path = 'proxy.rules')
+        raise ConfigurationError, "#{path} must be an array" unless rules.is_a?(Array)
+
+        rules.each_with_index { |rule, index| validate_rule!(rule, "#{path}.#{index}") }
+      end
+
+      def self.validate_rule!(rule, location)
+        raise ConfigurationError, "#{location} requires hosts and allow arrays" unless valid_rule_keys?(rule)
+        unless valid_hosts?(rule['hosts'])
+          raise ConfigurationError, "#{location}.hosts must contain lowercase hostname globs using * and ?"
+        end
+        return if rule['allow'].is_a?(Array) && rule['allow'].all? { |v| ProxyPolicy.valid_domain?(v) }
+
+        raise ConfigurationError, "#{location}.allow must contain DNS domains or *.domain entries"
+      end
+
+      def self.valid_rule_keys?(rule)
+        rule.is_a?(Hash) && rule.keys.sort_by(&:to_s) == %w[allow hosts]
+      end
+
+      def self.valid_hosts?(hosts)
+        hosts.is_a?(Array) && !hosts.empty? && hosts.all? { |v| valid_glob?(v) }
+      end
+
+      def self.valid_glob?(value)
+        HostnamePattern.valid?(value) && value == value.downcase
+      end
+
+      def initialize(config)
+        @config = config
+      end
+
+      def self.matches?(pattern, hostname)
+        HostnamePattern.matches?(pattern, hostname)
+      end
+
+      def matching(hostname)
+        @config.fetch('rules').select do |rule|
+          rule.fetch('hosts').any? { |pattern| HostnamePattern.matches?(pattern, hostname) }
+        end
+      end
+
+      def resolve(hostname)
+        (@config.fetch('global') + matching(hostname).flat_map { |rule| rule.fetch('allow') }).uniq
+      end
+    end
+  end
+end

data/lib/empeira/network/naming.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    # Logical identities remain independent of runtime container names and addresses.
+    class Naming
+      DOMAIN = 'empeira.internal'
+
+      def hostname(service)
+        "#{service}.#{DOMAIN}"
+      end
+
+      def aliases(service)
+        [service, hostname(service)]
+      end
+
+      def reserved(config)
+        additional = config.dig('containers', 'additional').map { |entry| entry.fetch('name') }
+        Configuration::AdditionalServices::RESERVED + additional
+      end
+
+      def no_proxy(additional = [])
+        ['localhost', '127.0.0.1', '::1', ".#{DOMAIN}", 'server', 'puppetdb', 'postgres', 'dns', 'proxy',
+         *additional].uniq.join(',')
+      end
+    end
+  end
+end

data/lib/empeira/network/peer/adapter_image.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      class AdapterImage
+        attr_reader :image, :recipe, :files
+
+        # rubocop:disable-next Metrics/AbcSize -- Assemble the reviewed source and resolved builder identity together.
+        def initialize(context:)
+          root = Pathname(__dir__).join('../../../../resources/network/adapter').realpath
+          @files = source_files(root)
+          builder = Images::Configuration.reference(context.configuration.dig('images', 'network_adapter_builder'),
+                                                    registry: context.configuration.dig('images', 'registry'))
+          digest = Infrastructure::Definition.fingerprint(@files)
+          @recipe = root.join('Containerfile').read.gsub('@BUILDER@', builder) + "\n# source-sha256: #{digest}\n"
+          @image = Images::Configuration.local_image(@recipe, purpose: 'peer-adapter')
+        end
+
+        def source_files(root)
+          files = root.children.select { |path| path.extname == '.go' || path.basename.to_s == 'go.mod' }
+                      .to_h { |path| [path.basename.to_s, path.binread] }
+          files.merge('LICENSE' => Pathname(__dir__).join('../../../../LICENSE').read)
+        end
+
+        def ensure!(runtime)
+          runtime.ensure_image(image, recipe: recipe, files: files)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/peer/allocation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      class Allocation
+        def initialize(context:, runtime:, runner:)
+          @context = context
+          @runtime = runtime
+          @runner = runner
+        end
+
+        def choose
+          occupied = @runtime.network_subnets + host_routes
+          candidates.find { |candidate| occupied.none? { |route| overlap?(candidate, route) } } ||
+            raise(Error, 'No safe private peer subnet is available; inspect host/VPN and runtime routes')
+        end
+
+        private
+
+        def candidates
+          offset = Digest::SHA256.hexdigest(@context.workspace.id)[0, 4].to_i(16)
+          candidates = (0...256).map { |i| "10.#{160 + ((offset + i) % 64)}.#{(offset + i) % 256}.0/24" }
+          candidates + alternatives(offset)
+        end
+
+        def alternatives(offset)
+          (16..31).map { |i| "172.#{i}.#{offset % 256}.0/24" } +
+            (0...256).map { |i| "192.168.#{(offset + i) % 256}.0/24" }
+        end
+
+        def overlap?(candidate, route)
+          left, right = [candidate, route].map { |value| IPAddr.new(value) }
+          left.include?(right.to_range.first) || right.include?(left.to_range.first)
+        rescue IPAddr::InvalidAddressError
+          raise Error, 'Cannot verify route overlap for the peer network', cause: nil
+        end
+
+        def host_routes
+          Platform::Routes.new(platform: @context.platform, runner: @runner).ipv4
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/peer/attachment.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      class Attachment
+        def initialize(backend:, record:, state:)
+          @backend = backend
+          @record = record
+          @state = state
+        end
+
+        def arguments
+          @backend.arguments(@record)
+        end
+
+        def launch(executable, arguments)
+          @backend.launch(executable, arguments)
+        end
+
+        def connect
+          @backend.connect(@record, @state)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/peer/backend.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      class Backend
+        attr_reader :context, :runtime, :runner, :store
+
+        def self.build(context:, **)
+          klass = if context.container_engine == 'docker'
+                    DockerAdapter
+                  elsif context.platform.os == :macos
+                    PodmanMachine
+                  else
+                    LinuxPodman
+                  end
+          klass.new(context: context, **)
+        end
+
+        def initialize(context:, runtime:, runner:, store:)
+          @context = context
+          @runtime = runtime
+          @runner = runner
+          @store = store
+        end
+
+        def key
+          self.class.name.split('::').last
+        end
+
+        def preflight(state)
+          raise Error, 'Old VM network state requires explicit teardown and recreation' unless state['peer_network']
+
+          resource = owned_network(state)
+          details = runtime.network_details(resource.id)
+          verify_subnet(details, state.fetch('peer_network').fetch('subnet'))
+        end
+
+        def owned_network(state)
+          definition = Network::Definition.new(workspace: context.workspace, policy: Network::Policy.new)
+          resource = runtime.inspect_network(identifier: definition.backend_name)
+          definition.verify_ownership!(resource, expected_id: state.dig('resources', 'network', 'id'))
+          definition.verify_isolation!(resource)
+          raise Error, 'Owned peer network is missing; run empeira up' unless resource
+
+          resource
+        end
+
+        def verify_subnet(details, expected)
+          subnets = details['subnets'] || details.dig('IPAM', 'Config') || []
+          return if subnets.any? { |entry| (entry['subnet'] || entry['Subnet']) == expected }
+
+          raise Providers::OwnershipError, 'Observed peer subnet differs from workspace inventory'
+        end
+
+        def network_name
+          Network::Definition.new(workspace: context.workspace, policy: Network::Policy.new).backend_name
+        end
+
+        def bridge
+          "ep#{context.workspace.id[0, 10]}"
+        end
+
+        def tap(record)
+          "et#{record.fetch('peer').fetch('token')[0, 12]}"
+        end
+
+        def command(executable, *arguments, timeout: 30)
+          result = runner.run(executable, arguments: arguments, timeout: timeout)
+          return result.stdout if result.success?
+
+          raise Error,
+                "Peer network #{executable} operation failed (exit=#{result.exit_status}, timeout=#{result.timed_out})"
+        end
+
+        def check_record(record)
+          return if record.dig('peer', 'backend') == key
+
+          raise Error, 'Peer backend differs from the node instance; restore its runtime and platform'
+        end
+
+        def health(records)
+          records.to_h { |record| [record.fetch('hostname'), healthy?(record)] }
+        end
+
+        def system_address(record, port)
+          Configuration::SSHPreferences.port!(port)
+          check_record(record)
+          address = IPAddr.new(record.fetch('peer').fetch('ip'))
+          subnet = system_subnet
+          unless address.ipv4? && address.private? && subnet.include?(address)
+            raise Providers::OwnershipError, 'System SSH target is outside the owned peer subnet'
+          end
+
+          address.to_s
+        end
+
+        def system_subnet
+          state = store.load
+          resource = owned_network(state)
+          subnet = state.fetch('peer_network').fetch('subnet')
+          verify_subnet(runtime.network_details(resource.id), subnet)
+          IPAddr.new(subnet)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/peer/channel.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      # Control is private and token-bound. The packet stream never carries application configuration.
+      class Channel
+        def initialize(context:, runner:, record:)
+          @runner = runner
+          @token = record.fetch('peer').fetch('token')
+          paths = [context.locations.temporary, context.locations.home].map { |root| root.join("ep-#{@token[0, 24]}") }
+          @directory = paths.find { |path| path.join('ethernet.sock').to_s.bytesize < 100 }
+          raise Error, 'No short private path is available for the peer packet channel' unless @directory
+        end
+
+        def socket
+          @directory.join('ethernet.sock').to_s
+        end
+
+        def prepare
+          FileUtils.mkdir_p(@directory, mode: 0o700)
+          verify_directory
+          raise Error, 'Peer channel is still active; stop its owning VM before retrying' if live?
+
+          %w[control.sock ethernet.sock].each { |name| remove_socket(@directory.join(name)) }
+        end
+
+        def start(command)
+          launch(command)
+          Timeout.timeout(10) do
+            loop do
+              return if healthy?
+
+              sleep 0.1
+            end
+          end
+        rescue Timeout::Error
+          raise Error, 'Peer packet channel did not become ready; inspect adapter/runtime availability'
+        end
+
+        def healthy?
+          reply = request('status')
+          reply['token'] == @token && reply['running'] == true
+        rescue SystemCallError, IOError, Timeout::Error, JSON::ParserError
+          false
+        end
+
+        def stop
+          return unless @directory.exist?
+
+          verify_directory
+          if live?
+            reply = request('stop')
+            raise Providers::OwnershipError, 'Peer channel ownership changed' unless reply['token'] == @token
+
+            Timeout.timeout(15) { sleep 0.1 while live? }
+          end
+          %w[control.sock ethernet.sock].each { |name| remove_socket(@directory.join(name)) }
+        rescue SystemCallError, Timeout::Error
+          raise Error, 'Peer channel shutdown is uncertain; resources retained for recovery', cause: nil
+        end
+
+        def destroy
+          stop
+          FileUtils.remove_entry_secure(@directory) if @directory.exist?
+        end
+
+        private
+
+        def launch(command)
+          config = @directory.join('channel.json')
+          File.write(config, JSON.generate('token' => @token, 'command' => command), mode: 'w', perm: 0o600)
+          helper = Pathname(__dir__).join('../../../../resources/network/channel.rb').realpath
+          result = @runner.run(RbConfig.ruby, arguments: [helper.to_s, config.to_s], timeout: 10)
+          raise Error, 'Cannot launch peer packet channel' unless result.success?
+        end
+
+        def request(operation)
+          Timeout.timeout(2) do
+            UNIXSocket.open(@directory.join('control.sock')) do |connection|
+              connection.puts(JSON.generate('token' => @token, 'operation' => operation))
+              JSON.parse(connection.gets(4096))
+            end
+          end
+        end
+
+        def live?
+          path = @directory.join('channel.pid')
+          return false unless path.file?
+
+          Process.kill(0, Integer(path.read))
+          true
+        rescue Errno::ESRCH
+          false
+        end
+
+        def verify_directory
+          metadata = @directory.lstat
+          unless metadata.directory? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+            raise Providers::OwnershipError, 'Peer channel directory is not private to its owner'
+          end
+
+          verify_saved_token
+        end
+
+        def verify_saved_token
+          path = @directory.join('channel.json')
+          return unless path.exist? || path.symlink?
+
+          metadata = path.lstat
+          unless private_file?(metadata) && JSON.parse(path.read)['token'] == @token
+            raise Providers::OwnershipError, 'Peer channel ownership token changed; cleanup refused'
+          end
+        rescue JSON::ParserError
+          raise Providers::OwnershipError, 'Invalid peer channel ownership file', cause: nil
+        end
+
+        def private_file?(metadata)
+          metadata.file? && metadata.uid == Process.uid && metadata.mode.nobits?(0o077)
+        end
+
+        def remove_socket(path)
+          return unless path.exist? || path.symlink?
+          unless path.lstat.socket? && path.lstat.uid == Process.uid
+            raise Providers::OwnershipError, 'Unexpected file at the peer socket path'
+          end
+
+          File.unlink(path)
+        end
+      end
+    end
+  end
+end