empeira 0.1.0.pre.alpha.1

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'io/wait'
+
+module Empeira
+  module Network
+    module Peer
+      class ChannelServer
+        def initialize(path, runner: Execution::Runner.new)
+          @directory = Pathname(path).dirname
+          @config = JSON.parse(File.read(path))
+          @runner = runner
+        end
+
+        def run
+          File.umask(0o077)
+          control = @directory.join('control.sock')
+          @listener = UNIXServer.new(control)
+          File.chmod(0o600, control)
+          File.write(@directory.join('channel.pid'), Process.pid.to_s, mode: 'w', perm: 0o600)
+          @connection = UNIXSocket.new(@directory.join('ethernet.sock'))
+          @worker = Thread.new { forward }
+          serve
+        ensure
+          cleanup
+        end
+
+        private
+
+        def cleanup
+          begin
+            @connection&.shutdown
+          rescue StandardError
+            nil
+          end
+          @worker.kill.join if @worker && !@worker.join(10)
+          @listener&.close
+          FileUtils.rm_f(@directory.join('control.sock'))
+          FileUtils.rm_f(@directory.join('channel.pid'))
+        end
+
+        def forward
+          File.open(@directory.join('channel.log'), 'w', 0o600) do |log|
+            command = @config.fetch('command')
+            @result = @runner.stream(command.first, arguments: command.drop(1),
+                                                    input: @connection, output: @connection, error: log)
+          end
+        end
+
+        def serve
+          loop do
+            break unless @worker.alive?
+            next unless @listener.wait_readable(0.2)
+
+            client = @listener.accept
+            begin
+              message = JSON.parse(client.gets(4096))
+              next unless message['token'] == @config.fetch('token')
+
+              client.puts(JSON.generate('token' => @config.fetch('token'), 'running' => @worker.alive?))
+              stop = message['operation'] == 'stop'
+            ensure
+              client.close
+            end
+            break if stop
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      # The same whole-NIC transport serves local Docker and Docker Desktop.
+      # rubocop:disable-next Metrics/ClassLength -- Owned NIC and system SSH share adapter security checks.
+      class DockerAdapter < Backend
+        def preflight(state)
+          super
+          return if runtime.architecture == context.platform.architecture.to_s
+
+          raise Error, 'Peer adapter and VM architecture differ; emulation is not supported'
+        end
+
+        def prepare(record, state)
+          check_record(record)
+          channel(record).prepare
+          @image = AdapterImage.new(context: context)
+          @image.ensure!(runtime)
+          resource = ensure_adapter(record, state)
+          runtime.start_service(resource) unless resource['state'] == 'running'
+          verify_adapter(record)
+          store.write(state)
+          attach_bridge(resource)
+        end
+
+        def arguments(record)
+          ['-netdev', "stream,id=peer,addr.type=unix,addr.path=#{channel(record).socket},server=on",
+           '-device', "virtio-net-pci,netdev=peer,mac=#{record.fetch('mac_address')}"]
+        end
+
+        def launch(executable, arguments)
+          command(executable, *arguments)
+        end
+
+        def connect(record, _state)
+          File.chmod(0o600, channel(record).socket)
+          channel(record).start(packet_command(record))
+        end
+
+        def stop(record)
+          channel(record).stop
+        end
+
+        def destroy(record, state)
+          channel(record).destroy
+          runtime.remove_service(identity(record), expected_id: record.dig('peer', 'adapter_id'))
+          record.fetch('peer')['adapter_id'] = nil
+          store.write(state)
+        end
+
+        def healthy?(record)
+          channel(record).healthy?
+        end
+
+        def system_ssh_command(record, port:)
+          address = system_address(record, port)
+          @image = AdapterImage.new(context: context)
+          verify_adapter(record)
+          resource = runtime.inspect_service(identity(record), expected_id: record.dig('peer', 'adapter_id'))
+          verify_definition!(record, resource)
+          raise Providers::OwnershipError, 'VM peer channel is not active' unless healthy?(record)
+
+          source = system_source(resource, address)
+          [*connector_engine, 'exec', '-i', resource.fetch('id'), '/adapter', 'connect', address, port.to_s, source]
+        end
+
+        protected
+
+        def connector_engine
+          [runtime.name]
+        end
+
+        def system_source(resource, target)
+          source = resource.dig('networks', network_name, 'IPAddress')
+          unless source.is_a?(String) && IPAddr.new("#{target}/24").include?(IPAddr.new(source))
+            raise Providers::OwnershipError, 'Peer connector address is outside its owned subnet'
+          end
+
+          source
+        rescue IPAddr::InvalidAddressError
+          raise Providers::OwnershipError, 'Peer connector address is unavailable', cause: nil
+        end
+
+        def capless_adapter_definition(record)
+          Services::Definition.new(key: identity(record).key, workspace: context.workspace,
+                                   network: network_name, image: @image.image, memory: 64, cpus: 1,
+                                   command: ['hold'], read_only: true, cap_drop: ['ALL'],
+                                   security_options: ['no-new-privileges'])
+        end
+
+        def channel(record)
+          Channel.new(context: context, runner: runner, record: record)
+        end
+
+        def identity(record)
+          Services::Definition.new(key: "peer-#{record.fetch('peer').fetch('token')[0, 16]}",
+                                   workspace: context.workspace)
+        end
+
+        def adapter_definition(record)
+          Services::Definition.new(key: identity(record).key, workspace: context.workspace,
+                                   network: network_name, image: @image.image, memory: 64, cpus: 1,
+                                   command: ['hold'], read_only: true, cap_drop: ['ALL'], cap_add: ['NET_ADMIN'],
+                                   devices: ['/dev/net/tun'], security_options: ['no-new-privileges'],
+                                   sysctls: { 'net.ipv4.ip_forward' => '0', 'net.ipv6.conf.all.disable_ipv6' => '1',
+                                              'net.ipv6.conf.default.disable_ipv6' => '1' })
+        end
+
+        def ensure_adapter(record, state)
+          expected = record.dig('peer', 'adapter_id')
+          resource = runtime.inspect_service(identity(record), expected_id: expected)
+          verify_definition!(record, resource) if resource
+          # The random per-instance token and adapter identity were persisted with the lease.
+          resource ||= runtime.create_service(adapter_definition(record))
+          record.fetch('peer')['adapter_id'] = resource.fetch('id')
+          store.write(state)
+          resource
+        end
+
+        def verify_definition!(record, resource)
+          return if resource.dig('labels', 'io.empeira.definition') == adapter_definition(record).fingerprint
+
+          raise Providers::OwnershipError, 'Unexpected peer adapter definition'
+        end
+
+        def packet_command(record)
+          ['docker', 'exec', '-i', record.fetch('peer').fetch('adapter_id'), '/adapter', 'tap', tap(record), 'peerbr']
+        end
+
+        def validate_exposure!(resource)
+          unless resource && resource.fetch('networks').keys == [network_name] && resource.fetch('ports').empty? &&
+                 resource.fetch('published_ports').values.all?(&:nil?)
+            raise Providers::OwnershipError, 'Peer helper has unexpected network or port exposure'
+          end
+        end
+
+        def attach_bridge(resource)
+          result = runtime.service_exec(resource, %w[/adapter bridge peerbr eth0])
+          raise Error, 'Cannot attach the Docker peer adapter bridge' unless result.success?
+        end
+
+        def binary_digest(resource)
+          result = runtime.service_exec(resource, %w[/adapter sha256])
+          digest = result.stdout.strip
+          return digest if result.success? && digest.match?(/\A[0-9a-f]{64}\z/)
+
+          raise Error, 'Cannot verify peer adapter binary integrity'
+        end
+
+        def verify_adapter(record)
+          resource = runtime.inspect_service(identity(record), expected_id: record.dig('peer', 'adapter_id'))
+          validate_exposure!(resource)
+          HelperSecurity.verify!(resource, privileged_tap: key == 'DockerAdapter')
+          digest = binary_digest(resource)
+          expected = record.dig('peer', 'helper_sha256')
+          raise Providers::OwnershipError, 'Peer helper checksum changed' if expected && expected != digest
+
+          record.fetch('peer')['helper_sha256'] = digest
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      module HelperSecurity
+        def self.verify!(resource, privileged_tap:)
+          config = resource.fetch('host_config')
+          return if base_valid?(config) && resource.fetch('mounts').empty? &&
+                    capabilities_valid?(config, privileged_tap) && devices_valid?(config, privileged_tap)
+
+          raise Providers::OwnershipError, 'Peer helper privileges or mounts differ from the managed definition'
+        end
+
+        def self.base_valid?(config)
+          config['Privileged'] == false && config['ReadonlyRootfs'] == true &&
+            Array(config['SecurityOpt']).include?('no-new-privileges')
+        end
+
+        def self.capabilities_valid?(config, tap)
+          caps = Array(config['CapAdd']).map { |cap| cap.delete_prefix('CAP_') }
+          dropped = Array(config['CapDrop'])
+          return dropped == ['ALL'] && caps == ['NET_ADMIN'] if tap
+
+          !dropped.empty? && caps.empty?
+        end
+
+        def self.devices_valid?(config, tap)
+          devices = Array(config['Devices'])
+          return devices.empty? unless tap
+
+          devices.size == 1 && devices.first['PathOnHost'] == '/dev/net/tun' &&
+            devices.first['PathInContainer'] == '/dev/net/tun' &&
+            config.dig('Sysctls', 'net.ipv4.ip_forward') == '0' &&
+            config.dig('Sysctls', 'net.ipv6.conf.all.disable_ipv6') == '1'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'securerandom'
+
+module Empeira
+  module Network
+    module Peer
+      # Addresses belong to node instances, under the existing workspace mutation lock.
+      class Layout
+        attr_reader :subnet
+
+        def initialize(subnet)
+          @subnet = subnet
+          @range = IPAddr.new(subnet)
+          unless @range.ipv4? && @range.private? && @range.prefix == 24 && "#{@range}/24" == subnet
+            raise Infrastructure::StateError, 'Invalid workspace peer subnet'
+          end
+        rescue IPAddr::InvalidAddressError
+          raise Infrastructure::StateError, 'Invalid workspace peer subnet', cause: nil
+        end
+
+        def address(offset)
+          IPAddr.new(@range.to_i + offset, Socket::AF_INET).to_s
+        end
+
+        def container_pool
+          "#{address(128)}/25"
+        end
+
+        def lease(nodes)
+          used = nodes.values.filter_map { |record| record.dig('peer', 'ip') }
+          ip = (32..95).map { |offset| address(offset) }.find { |candidate| !used.include?(candidate) }
+          raise Error, 'Workspace VM address pool exhausted; destroy an unused VM to release its lease' unless ip
+
+          { 'ip' => ip, 'token' => SecureRandom.hex(16), 'adapter_id' => nil }
+        end
+
+        def container_lease(nodes)
+          used = nodes.values.filter_map { |record| record.dig('definition', 'ip') }
+          ip = (96..127).map { |offset| address(offset) }.find { |candidate| !used.include?(candidate) }
+          raise Error, 'Workspace container node pool exhausted; destroy an unused node' unless ip
+
+          ip
+        end
+
+        def valid_lease?(entry)
+          entry.is_a?(Hash) && (32..95).any? { |offset| address(offset) == entry['ip'] } &&
+            entry['token'].is_a?(String) && entry['token'].match?(/\A[0-9a-f]{32}\z/) &&
+            Node::Inventory.valid_id?(entry['adapter_id'])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module Peer
+      class LinuxPodman < DockerAdapter
+        def preflight(state)
+          super
+          info = JSON.parse(command('podman', '--remote=false', 'info', '--format', 'json'))
+          unless info.dig('host', 'security', 'rootless') && info.dig('host', 'networkBackend') == 'netavark'
+            raise Error, 'VM peer networking requires local rootless Podman/Netavark; no rootful fallback'
+          end
+
+          namespace('test', '-r', '/dev/net/tun')
+          namespace('test', '-w', '/dev/net/tun')
+          namespace('test', '-r', '/dev/kvm')
+          namespace('test', '-w', '/dev/kvm')
+          verify_forwarding
+        end
+
+        def prepare(record, state)
+          check_record(record)
+          verify_tap_absent!(record)
+          @image = AdapterImage.new(context: context)
+          @image.ensure!(runtime)
+          resource = ensure_adapter(record, state)
+          runtime.start_service(resource) unless resource['state'] == 'running'
+          verify_adapter(record)
+          store.write(state)
+        end
+
+        def arguments(record)
+          ['-netdev', "tap,id=peer,ifname=#{tap(record)},script=no,downscript=no",
+           '-device', "virtio-net-pci,netdev=peer,mac=#{record.fetch('mac_address')}"]
+        end
+
+        def launch(executable, arguments)
+          namespace(executable, *arguments)
+        end
+
+        def connect(record, _state)
+          # QEMU owns the nonpersistent TAP FD. Closing it removes the interface.
+          namespace('ip', 'link', 'set', 'dev', tap(record), 'alias', record.fetch('peer').fetch('token'))
+          namespace('ip', 'link', 'set', 'dev', tap(record), 'master', bridge)
+          namespace('ip', 'link', 'set', 'dev', tap(record), 'up')
+          verify_forwarding
+        end
+
+        def stop(record)
+          links = JSON.parse(namespace('ip', '-j', 'link', 'show'))
+          return unless links.any? { |link| link['ifname'] == tap(record) }
+
+          raise Error, 'VM TAP is still present after shutdown; refusing to release the node lease'
+        end
+
+        def destroy(record, state)
+          stop(record)
+          runtime.remove_service(identity(record), expected_id: record.dig('peer', 'adapter_id'))
+          record.fetch('peer')['adapter_id'] = nil
+          store.write(state)
+        end
+
+        def healthy?(record)
+          health([record]).fetch(record.fetch('hostname'))
+        end
+
+        def health(records)
+          return {} if records.empty?
+
+          links = JSON.parse(namespace('ip', '-j', 'link', 'show', timeout: 2))
+          records.to_h { |record| [record.fetch('hostname'), attached?(record, links)] }
+        rescue Error, JSON::ParserError
+          records.to_h { |record| [record.fetch('hostname'), false] }
+        end
+
+        protected
+
+        def adapter_definition(record)
+          capless_adapter_definition(record)
+        end
+
+        def connector_engine
+          %w[podman --remote=false]
+        end
+
+        private
+
+        def verify_tap_absent!(record)
+          links = JSON.parse(namespace('ip', '-j', 'link', 'show'))
+          return unless links.any? { |link| link['ifname'] == tap(record) }
+
+          raise Providers::OwnershipError, 'VM TAP already exists; inspect its owning process'
+        end
+
+        def namespace(*, **)
+          command('podman', '--remote=false', 'unshare', '--rootless-netns', *, **)
+        end
+
+        def attached?(record, links)
+          links.any? do |link|
+            link['ifname'] == tap(record) && link['ifalias'] == record.dig('peer', 'token') &&
+              link['master'] == bridge && link.fetch('flags', []).include?('UP')
+          end
+        end
+
+        def verify_forwarding
+          return if namespace('cat', "/proc/sys/net/ipv4/conf/#{bridge}/forwarding").strip == '0'
+
+          raise Error, 'Peer bridge routing is enabled; refusing VM attachment'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Empeira
+  module Network
+    module Peer
+      class PodmanMachine < DockerAdapter
+        def preflight(state)
+          super
+          select_machine
+          verify_rootless
+          namespace('test', '-w', '/dev/net/tun')
+          raise Error, 'Machine peer bridge routing is enabled' unless
+            namespace('cat', "/proc/sys/net/ipv4/conf/#{bridge}/forwarding").strip == '0'
+        end
+
+        def prepare(record, state)
+          check_record(record)
+          bind_machine(record, state)
+          channel(record).prepare
+          @image = AdapterImage.new(context: context)
+          @image.ensure!(runtime)
+          resource = ensure_adapter(record, state)
+          runtime.start_service(resource) unless resource['state'] == 'running'
+          export_helper(record, resource)
+          store.write(state)
+        end
+
+        protected
+
+        def adapter_definition(record)
+          capless_adapter_definition(record)
+        end
+
+        def packet_command(record)
+          machine = record.fetch('peer').fetch('machine')
+          namespace_command(machine, helper_path(record).to_s, 'tap', tap(record), bridge)
+        end
+
+        def helper_path(record)
+          context.locations.workspace(context.workspace).join('vms', record.fetch('hostname'), 'peer-adapter')
+        end
+
+        private
+
+        def bind_machine(record, state)
+          if record.dig('peer', 'machine') && record.dig('peer', 'machine') != @machine
+            raise Providers::OwnershipError, 'Node belongs to a different Podman Machine'
+          end
+
+          record.fetch('peer')['machine'] = @machine
+          store.write(state)
+        end
+
+        def selected_connection
+          connections = JSON.parse(command('podman', 'system', 'connection', 'list', '--format', 'json'))
+          connections.select { |entry| entry['Default'] }
+        end
+
+        def select_machine
+          machines = JSON.parse(command('podman', 'machine', 'list', '--format', 'json'))
+          active = machines.select { |entry| entry['Running'] }
+          selected = selected_connection
+          unless active.size == 1 && selected.size == 1 && selected.first['Name'] == active.first['Name']
+            raise Error, 'Select one unambiguous running rootless Podman Machine and its default connection'
+          end
+
+          @machine = active.first.fetch('Name')
+        end
+
+        def verify_rootless
+          info = JSON.parse(command('podman', 'info', '--format', 'json'))
+          return if info.dig('host', 'security', 'rootless') && info.dig('host', 'networkBackend') == 'netavark'
+
+          raise Error, 'Podman Machine peer networking requires rootless Netavark; no rootful fallback'
+        end
+
+        def verify_empty_capabilities(resource)
+          result = runtime.service_exec(resource, %w[/adapter capabilities])
+          return if result.success? && result.stdout.strip.match?(/\A0{16}\z/)
+
+          raise Providers::OwnershipError, 'Podman staging helper must have no effective capabilities'
+        end
+
+        def export_helper(record, resource)
+          path = helper_path(record)
+          runtime.copy_from(resource, '/adapter', path)
+          verify_empty_capabilities(resource)
+          digest = verify_adapter(record)
+          raise Error, 'Exported peer helper checksum mismatch' unless Digest::SHA256.file(path).hexdigest == digest
+
+          File.chmod(0o700, path)
+          observed = command('podman', 'machine', 'ssh', @machine,
+                             Shellwords.join(['sha256sum', path.to_s])).split.first
+          return if observed == digest
+
+          raise Error, 'Podman Machine cannot verify the peer helper at its host path; configure its shared mount'
+        end
+
+        def namespace(*)
+          executable, *arguments = namespace_command(@machine, *)
+          command(executable, *arguments)
+        end
+
+        def namespace_command(machine, *)
+          ['podman', 'machine', 'ssh', machine, Shellwords.join(['podman', 'unshare', '--rootless-netns', *])]
+        end
+      end
+    end
+  end
+end

data/lib/empeira/network/policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/UnusedMethodArgument -- Preserve explicit adapter keyword contracts.
+
+module Empeira
+  module Network
+    class UnsupportedPolicy < Error; end
+
+    Policy = Data.define do
+      def require_support!(isolated:, controlled_egress:)
+        raise UnsupportedPolicy, 'Isolated networking is required' unless isolated == true
+      end
+    end
+
+    class Interface
+      def initialize(context:, runner:)
+        @context = context
+        @runner = runner
+      end
+
+      def provision(policy:)
+        policy.require_support!(**capabilities)
+        create(policy: policy)
+      end
+
+      protected
+
+      def capabilities
+        { isolated: false, controlled_egress: false }
+      end
+
+      def create(policy:)
+        raise UnavailableFeature, 'This command is not implemented yet.'
+      end
+    end
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/lib/empeira/network/proxy_bindings.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    class ProxyBindings
+      def initialize(context:, resources:, network:, nodes:)
+        @context = context
+        @resources = resources
+        @network = network
+        @nodes = nodes
+        @config = context.configuration.fetch('proxy')
+      end
+
+      def configuration
+        entries = %w[server].map do |name|
+          rules(name.tr('-', '_'), address(name), @config.fetch('global'))
+        end
+        @nodes.sort.each_with_index do |(hostname, record), index|
+          entries << node_rules(hostname, record, index)
+        end
+        "#{entries.compact.join("\n")}\n"
+      end
+
+      private
+
+      def node_rules(hostname, record, index)
+        return if record['network_phase'] == 'bootstrap'
+
+        domains = HostPolicy.new(@config).resolve(hostname)
+        rules("node_#{index}", address(hostname), domains)
+      end
+
+      def address(name)
+        @resources[name]&.dig('networks', @network, 'IPAddress')
+      end
+
+      def rules(name, address, domains, authorization = nil)
+        return unless address && !address.empty? && !domains.empty?
+
+        IPAddr.new(address)
+        entries = ["acl #{name}_source src #{address}"]
+        condition = "#{name}_source"
+        if authorization
+          entries << "acl #{name}_identity req_header Proxy-Authorization " \
+                     "^Basic[[:space:]]#{Regexp.escape(authorization)}$"
+          condition += " #{name}_identity"
+        end
+        entries.concat(ProxyPolicy.domain_rules(domains, name: "#{name}_domains", condition: condition)).join("\n")
+      end
+    end
+  end
+end