empeira 0.1.0.pre.alpha.1

data/lib/empeira/control_plane/plan.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+module Empeira
+  module ControlPlane
+    # The plan holds desired, non-secret service definitions. IPs are runtime bindings.
+    # Declarative service specifications share one compatibility and naming boundary.
+    # rubocop:disable-next Metrics/ClassLength
+    class Plan
+      attr_accessor :browser_enabled, :subnet
+      attr_reader :context, :files, :naming, :server_runtime, :puppetdb_runtime, :additional_configurations
+
+      def initialize(context:)
+        @context = context
+        @files = Files.new(context: context)
+        @additional_configurations = AdditionalConfigurations.new(context: context)
+        @naming = Network::Naming.new
+        @server_runtime = Server::Runtime.resolve(config)
+        @puppetdb_runtime = Server::PuppetDBRuntime.resolve(config)
+      end
+
+      def config
+        context.configuration
+      end
+
+      def network
+        Network::Definition.new(workspace: context.workspace, policy: Network::Policy.new).backend_name
+      end
+
+      def proxy?
+        egress = config.dig('network', 'egress')
+        config.dig('proxy', 'enabled') || (egress.is_a?(Hash) && egress['mode'] == 'proxy')
+      end
+
+      def database?
+        config.dig('puppetdb', 'enabled')
+      end
+
+      def volume(key)
+        Services::Definition.new(key: "openvox-#{key}", workspace: context.workspace,
+                                 storage_revision: 1)
+      end
+
+      def volumes
+        keys = %w[ca ssl server-data]
+        keys.push('postgres-data', 'puppetdb-data') if database?
+        keys.to_h { |key| [key, volume(key)] }
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Compose optional managed services into one provider-neutral plan.
+      def definitions(dns: nil)
+        common = { network: network, dns: dns, cpus: 1,
+                   sysctls: { 'net.ipv6.conf.all.disable_ipv6' => '1', 'net.ipv6.conf.default.disable_ipv6' => '1' } }
+        result = {
+          'dns' => dns_service,
+          'gateway' => service('gateway', **common, **gateway),
+          'server' => service('server', **common, **server)
+        }
+        result['proxy'] = service('proxy', **common, **proxy) if proxy?
+        result.merge(database_services(common)).merge(additional_services(common))
+              .merge(browser_enabled ? Browser.new(self).definitions(dns: dns) : {})
+      end
+
+      def additional_services(common = {})
+        config.dig('containers', 'additional').each_with_index.to_h do |entry, index|
+          options = { image: image_reference(entry.fetch('image')), memory: 256,
+                      environment: proxy_environment_for('').merge(entry.fetch('environment', {})),
+                      command: entry.fetch('command', []) }
+          location = "containers.additional[#{index}].configuration"
+          generated = additional_configurations.options(entry, mounts: common.fetch(:mounts, []), location: location)
+          [entry.fetch('name'), service(entry.fetch('name'), **common, **options, **generated)]
+        end
+      end
+
+      def fingerprints
+        definitions.transform_values(&:fingerprint)
+      end
+
+      def validate_dns_rewrites!
+        entries = config.dig('dns', 'rewrites')
+        return if entries.empty?
+
+        targets = definitions.keys.map { |key| naming.hostname(key) }
+        entries.each_with_index do |entry, index|
+          target = Configuration::DNSRewrites.normalize(entry.fetch('to'))
+          next if targets.include?(target)
+
+          raise ConfigurationError, "dns.rewrites[#{index}].to target service #{target} is missing or disabled; " \
+                                    'configure the service before running empeira up'
+        end
+      end
+
+      def validate_network_redirects!(subnet: self.subnet)
+        Network::Redirects.validate!(config.dig('network', 'redirects'), definitions: definitions, subnet: subnet)
+      end
+
+      def bind(source, target, readonly: true)
+        raise ConfigurationError, 'Mount paths must not contain commas or newlines' if source.to_s.match?(/[,\r\n]/)
+
+        "type=bind,src=#{source},dst=#{target}#{',readonly' if readonly}"
+      end
+
+      def repository_mounts
+        [*environment.mounts, *hiera_mounts]
+      end
+
+      def project_server_mounts
+        @project_server_mounts ||= validate_server_mounts!
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Compare resolved data mounts with the actual managed definition.
+      def validate_server_mounts!
+        resolved = Configuration::ServerMounts.new(entries: config.dig('server', 'mounts'),
+                                                   project: context.project.path)
+        targets = managed_server_mounts.map { |mount| mount.split(',').find { |field| field.start_with?('dst=') }[4..] }
+        resolved.verify_targets!(targets)
+        @project_server_mounts = resolved.entries.map do |entry|
+          bind(entry.fetch('source'), entry.fetch('target'), readonly: entry.fetch('readonly'))
+        end
+      end
+
+      def module_request
+        @module_request ||= Modules::Request.new(context: context)
+      end
+
+      def environment
+        @environment ||= Environment.new(context: context, hiera: hiera)
+      end
+
+      def eyaml_mounts
+        destination = eyaml_staged? ? '/empeira-eyaml' : Configuration::Eyaml::DESTINATION
+        Configuration::Eyaml.new(config: config.fetch('eyaml'), project: context.project.path)
+                            .mounts(destination: destination)
+      end
+
+      def eyaml_staged?
+        config.dig('eyaml', 'enabled') && server_runtime.startup.fetch('eyaml_keys', 'direct') == 'staged'
+      end
+
+      def hiera
+        @hiera ||= Configuration::HieraMounts.new(config: config.fetch('hiera'), project: context.project.path,
+                                                  environment: config.dig('server', 'environment'))
+      end
+
+      def hiera_mounts
+        hiera.mounts
+      end
+
+      def bootstrap_proxy(dns:)
+        options = proxy.merge(network: network, dns: dns, cpus: 1,
+                              runtime_ip: subnet && Network::Gateway.address(subnet, 'bootstrap-proxy'),
+                              configuration: 'authenticated bootstrap policy',
+                              ports: [],
+                              command: ['-N', '-f', '/empeira-bootstrap/squid.conf'],
+                              mounts: [bind(files.path('bootstrap-squid.conf'), '/empeira-bootstrap/squid.conf'),
+                                       'type=tmpfs,dst=/var/log/squid', 'type=tmpfs,dst=/var/spool/squid'])
+        service('bootstrap-proxy', **options)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Bind one managed recipe to its embedded helper source and image identity.
+      def gateway_artifact
+        registry = config.dig('images', 'registry')
+        artifact = Images::Configuration.artifact(config.dig('images', 'direct_egress'), registry: registry)
+        script = Pathname(__dir__).join('../../../resources/gateway/configure.rb').realpath
+        files = if artifact[:recipe]
+                  { 'configure.rb' => script.binread,
+                    'bridge.rb' => script.dirname.join('bridge.rb').binread }
+                else
+                  {}
+                end
+        recipe = artifact[:recipe]
+        recipe += "\n# configure-sha256: #{Infrastructure::Definition.fingerprint(files)}\n" if recipe
+        image = recipe ? Images::Configuration.local_image(recipe, purpose: 'gateway') : artifact[:image]
+        artifact.merge(image: image,
+                       recipe: recipe, files: files)
+      end
+
+      def node_proxy_environment
+        return {} unless proxy?
+
+        proxy_environment_for("http://#{naming.hostname('proxy')}:3128")
+      end
+
+      private
+
+      def image_reference(data)
+        Images::Configuration.reference(data, registry: config.dig('images', 'registry'))
+      end
+
+      def service(key, **options)
+        ipv6 = { 'net.ipv6.conf.all.disable_ipv6' => '1', 'net.ipv6.conf.default.disable_ipv6' => '1' }
+        options[:sysctls] = ipv6.merge(options.fetch(:sysctls, {}))
+        Services::Definition.new(key: key, workspace: context.workspace, hostname: naming.hostname(key), **options)
+      end
+
+      def storage(key, destination)
+        "type=volume,src=#{volume(key).name},dst=#{destination}"
+      end
+
+      def dns_service
+        service('dns', image: image_reference(config.dig('images', 'dns')), memory: 64,
+                       network: network, runtime_ip: subnet && Network::Gateway.address(subnet, 'dns'),
+                       sysctls: { 'net.ipv4.ip_forward' => '0', 'net.ipv6.conf.all.disable_ipv6' => '1',
+                                  'net.ipv6.conf.default.disable_ipv6' => '1' },
+                       mounts: [bind(files.directory, '/empeira')],
+                       configuration: files.configuration.fetch('Corefile'),
+                       command: ['-conf', '/empeira/Corefile'])
+      end
+
+      def database_services(common)
+        return {} unless database?
+
+        { 'postgres' => service('postgres', **common, **postgres),
+          'puppetdb-backend' => service('puppetdb-backend', **common, **puppetdb),
+          'puppetdb' => service('puppetdb', **common, **puppetdb_relay(dns: common[:dns])) }
+      end
+
+      def server
+        { hiera: hiera.entries, **server_image, **server_startup, memory: config.dig('server', 'memory'),
+          cpus: config.dig('server', 'cpus'),
+          environment: server_environment, mounts: server_mounts }
+      end
+
+      def server_mounts
+        [*managed_server_mounts, *project_server_mounts]
+      end
+
+      def managed_server_mounts
+        mounts = [storage('ca', '/etc/puppetlabs/puppetserver/ca'),
+                  storage('ssl', '/etc/puppetlabs/puppet/ssl'),
+                  storage('server-data', '/opt/puppetlabs/server/data/puppetserver'),
+                  *repository_mounts, *eyaml_mounts]
+        mounts + managed_server_start_mounts
+      end
+
+      def managed_server_start_mounts
+        mounts = []
+        mounts << "type=tmpfs,dst=#{Configuration::Eyaml::DESTINATION}" if eyaml_staged?
+        mounts << bind(files.path('server-puppetdb.conf'), '/empeira-server/puppetdb.conf') if database?
+        mounts << bind(server_start_script, '/empeira-server/start.sh')
+        mounts << bind(server_environment_script, Server::EnvironmentConfiguration::READER)
+        mounts
+      end
+
+      def server_startup
+        { entrypoint: 'dumb-init',
+          command: ['/bin/sh', '/empeira-server/start.sh', server_runtime.startup.fetch('entrypoint'),
+                    server_runtime.paths.fetch('puppetdb_config'), eyaml_staged? ? 'staged' : 'direct',
+                    database? ? 'puppetdb' : 'no-puppetdb', *server_runtime.startup.fetch('arguments')],
+          configuration: [File.read(server_start_script), File.read(server_environment_script)].join("\n") }
+      end
+
+      def server_start_script
+        Pathname(__dir__).join('../../../resources/relay/server_start.sh').realpath
+      end
+
+      def server_environment_script
+        Pathname(__dir__).join('../../../resources/relay/server_environment.rb').realpath
+      end
+
+      def server_image
+        { image: image_reference(config.dig('images', 'server')) }
+      end
+
+      def server_environment
+        server_runtime.environment(
+          certname: naming.hostname('server'), dns_alt_names: 'server',
+          ca_hostname: naming.hostname('server'), autosign: 'false',
+          server_hostname: naming.hostname('server'), environment_timeout: '0',
+          java_args: '-Xms256m -Xmx768m', max_active_instances: '1',
+          puppetdb_enabled: database?.to_s, storeconfigs: database?.to_s,
+          reports: database? ? 'puppetdb' : 'log',
+          # Upstream entrypoints otherwise rewrite puppetdb.conf from their default URL.
+          puppetdb_server_urls: ''
+        ).merge(proxy_environment)
+      end
+
+      def proxy_environment
+        proxy_environment_for(proxy? ? "http://#{naming.hostname('proxy')}:3128" : '')
+      end
+
+      def proxy_environment_for(url)
+        bypass = Network::DirectEgress.destinations(config.dig('network', 'egress'))
+        no_proxy = naming.no_proxy(bypass)
+        { 'http_proxy' => url, 'https_proxy' => url, 'HTTP_PROXY' => url, 'HTTPS_PROXY' => url,
+          'all_proxy' => '', 'ALL_PROXY' => '', 'no_proxy' => no_proxy, 'NO_PROXY' => no_proxy }
+      end
+
+      def postgres
+        { image: image_reference(config.dig('images', 'postgres')), memory: 256,
+          env_file: files.secret_path,
+          configuration: files.configuration.fetch('database-setup.sql'),
+          environment: { 'POSTGRES_USER' => 'postgres', 'POSTGRES_DB' => 'puppetdb' },
+          mounts: [storage('postgres-data', '/var/lib/postgresql/data'),
+                   bind(files.path('database-setup.sql'), '/empeira/setup.sql')],
+          command: ['postgres', '-c', 'shared_buffers=64MB', '-c', 'max_connections=50'] }
+      end
+
+      def puppetdb
+        { configuration: files.configuration.slice('jetty.ini', 'database.conf', 'puppetdb.conf'),
+          image: image_reference(config.dig('images', 'puppetdb')), memory: config.dig('puppetdb', 'memory'),
+          user: puppetdb_runtime.user, entrypoint: puppetdb_runtime.entrypoint,
+          command: puppetdb_runtime.command, env_file: files.secret_path,
+          mounts: puppetdb_mounts }
+      end
+
+      def puppetdb_mounts
+        [storage('puppetdb-data', puppetdb_runtime.paths.fetch('data')),
+         bind(files.directory, '/empeira'),
+         *%w[jetty.ini database.conf puppetdb.conf].map do |name|
+           bind(files.path(name), "#{puppetdb_runtime.paths.fetch('config')}/#{name}")
+         end]
+      end
+
+      def puppetdb_relay(dns:)
+        script = Pathname(__dir__).join('../../../resources/relay/puppetdb.rb').realpath
+        certificate = Server::RelayCertificate.new(context: context)
+        Browser.new(self).relay_image.merge(
+          memory: 96, cpus: 1, user: '0', entrypoint: 'ruby', command: ['/empeira-relay/puppetdb.rb'],
+          configuration: File.read(script), runtime_environment: { 'EMPEIRA_DNS_IP' => dns },
+          sysctls: { 'net.ipv4.ip_forward' => '0' },
+          mounts: [bind(script, '/empeira-relay/puppetdb.rb'),
+                   bind(certificate.path('cert.pem'), '/empeira-relay/cert.pem'),
+                   bind(certificate.path('key.pem'), '/empeira-relay/key.pem')]
+        )
+      end
+
+      def proxy
+        configured = config.dig('images', 'proxy')
+        {
+          **Images::Configuration.artifact(configured, registry: config.dig('images', 'registry')),
+          memory: 128, runtime_ip: subnet && Network::Gateway.address(subnet, 'proxy'),
+          sysctls: { 'net.ipv4.ip_forward' => '0', 'net.ipv6.conf.all.disable_ipv6' => '1',
+                     'net.ipv6.conf.default.disable_ipv6' => '1' }, entrypoint: '/usr/sbin/squid-gnutls',
+          command: ['-N', '-f', '/empeira-proxy/squid.conf'],
+          mounts: [bind(files.directory, '/empeira-proxy'),
+                   'type=tmpfs,dst=/var/log/squid', 'type=tmpfs,dst=/var/spool/squid']
+        }
+      end
+
+      def gateway
+        artifact = gateway_artifact
+        {
+          **artifact,
+          runtime_ip: subnet && Network::Gateway.address(subnet),
+          build_files: artifact.fetch(:files), memory: 64, read_only: true, cap_drop: ['ALL'], cap_add: ['NET_ADMIN'],
+          security_options: ['no-new-privileges'], sysctls: { 'net.ipv4.ip_forward' => '1',
+                                                              'net.ipv6.conf.all.disable_ipv6' => '1',
+                                                              'net.ipv6.conf.default.disable_ipv6' => '1',
+                                                              'net.ipv4.conf.all.rp_filter' => '0',
+                                                              'net.ipv4.conf.default.rp_filter' => '0' },
+          mounts: [bind(files.directory, '/empeira-gateway'), 'type=tmpfs,dst=/run,tmpfs-size=1048576']
+        }.except(:files)
+      end
+    end
+  end
+end

data/lib/empeira/control_plane/storage.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Empeira
+  module ControlPlane
+    class Storage
+      def initialize(runtime:, plan:, inventory:, persist:)
+        @runtime = runtime
+        @plan = plan
+        @inventory = inventory
+        @persist = persist
+        @changed = false
+      end
+
+      def prepare
+        definitions = @plan.volumes.values.to_h { |definition| [definition.key, definition] }
+        expected = @inventory.fetch('volumes').transform_values { |record| record['id'] }
+        @observed = @runtime.inspect_volumes(definitions, expected_ids: expected)
+        @plan.files.credentials(existing: database_recorded?) if @plan.database?
+        @plan.volumes.each_value { |definition| ensure_volume(definition) }
+        @changed
+      end
+
+      def database_recorded?
+        definition = @plan.volume('postgres-data')
+        @inventory.fetch('volumes').key?(definition.key) || !@observed[definition.key].nil?
+      end
+
+      def ensure_volume(definition)
+        expected = @inventory.fetch('volumes').dig(definition.key, 'id')
+        resource = @observed[definition.key]
+        if !resource && expected
+          raise Error, "Retained volume #{definition.key} is missing; restore it before starting services"
+        end
+
+        resource ||= create_volume(definition)
+        @inventory.fetch('volumes')[definition.key] = { 'id' => resource.fetch('id') }
+        @persist.call
+      end
+
+      def create_volume(definition)
+        @inventory.fetch('volumes')[definition.key] = { 'id' => nil }
+        @persist.call
+        @changed = true
+        @runtime.create_volume(definition)
+      end
+    end
+  end
+end

data/lib/empeira/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Empeira
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ExecutionError < Error; end
+  class UnsupportedPlatform < Error; end
+  class UnavailableFeature < Error; end
+end

data/lib/empeira/execution/console.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require 'socket'
+
+module Empeira
+  module Execution
+    class Console
+      def attach(path, input:, output:, guidance: nil)
+        UNIXSocket.open(path) do |socket|
+          output.write(guidance) if guidance
+          output.flush
+          Terminal.with_interrupts do
+            if input.tty?
+              input.raw { transfer(socket, input, output) }
+            else
+              transfer(socket, input, output)
+            end
+          end
+        end
+        Result.new(stdout: '', stderr: '', exit_status: 0, timed_out: false)
+      rescue SystemCallError, IOError
+        raise ExecutionError, 'VM console connection failed or closed', cause: nil
+      end
+
+      def transfer(socket, input, output)
+        loop do
+          IO.select([socket, input]).first.each do |source|
+            bytes = source.readpartial(4096)
+            if source == socket
+              output.write(bytes)
+              output.flush
+            else
+              before, escape, = bytes.partition("\x1d")
+              socket.write(before) unless before.empty?
+              return nil unless escape.empty?
+            end
+          end
+        end
+      rescue EOFError
+        nil
+      end
+    end
+  end
+end

data/lib/empeira/execution/diagnostics.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'base64'
+
+module Empeira
+  module Execution
+    # Bounded, sanitized diagnostics for direct HTTP responses and native tool failures.
+    # rubocop:disable-next Metrics/ModuleLength -- HTTP, native tools and SSH share the existing redaction boundary.
+    module Diagnostics
+      RELEVANT = %r{permission\sdenied|could\snot|couldn't|cannot\s|unable\sto|failed|failure|fatal:|error:|not\sfound|
+                    does\snot\sexist|not\sa\svalid|not\sappear|connection|timed?\sout|resolve|name\sor\sservice|
+                    server\sresponded|HTTP[\s/]|certificate|host\skey|load\skey|invalid|conflicts|
+                    unauthorized|forbidden|authentication\srequired|denied|insufficient_scope|manifest\sunknown|
+                    name\sunknown|x509|unknown\sauthority|network\sunreachable|DNS\sfailure|timeout|
+                    no\sbasic\sauth\scredentials|toomanyrequests|rate[\s-]limit|too\smany\srequests|
+                    \A(?:Get|Head|Post)\s|
+                    Puppetfile\smoduledir|\AModule\s[a-z][a-z0-9_]*[:\s]}ix
+      SECRET = /[a-z0-9_-]*(?:authorization|token|password|passwd|secret|api[-_]?key|access[-_]?key|credential|cookie)
+                [a-z0-9_-]*/ix
+      LIMIT = 8192
+      URL = %r{\b(?:https?|ssh|docker|oci)://[^\s<>"']+}
+      QUERY_SECRET = /#{SECRET}|auth|(?:\A|[-_])(?:sig|signature|key|session|jwt)\z/i
+
+      # rubocop:disable-next Metrics/ParameterLists -- Keep actual response fields explicit at the diagnostic boundary.
+      def self.http(operation:, url:, status:, reason:, body: nil, content_type: nil, secrets: [])
+        values = secrets + url_secrets(url)
+        response = body.nil? ? '[No response body available]' : response_text(body, content_type, values)
+        "Operation: #{safe_text(operation, secrets: values)}\nURL: #{safe_url(url)}\n" \
+          "HTTP status: #{safe_text("#{status} #{reason}", secrets: values).strip}\nResponse:\n" \
+          "#{response.lines.map { |line| "  #{line}" }.join}"
+      end
+
+      def self.http_response(response, operation:, url:, secrets: [])
+        http(operation: operation, url: url, status: response.code, reason: response.message,
+             body: read_body(response), content_type: response['Content-Type'], secrets: secrets)
+      end
+
+      def self.read_body(response)
+        body = +''.b
+        response.read_body do |chunk|
+          body << chunk
+          break if body.bytesize > LIMIT * 8
+        end
+        body
+      rescue IOError, SystemCallError, Timeout::Error, Net::ProtocolError => e
+        "#{body}\n[Response body incomplete: #{e.class.name}]"
+      end
+
+      def self.transport(operation:, url:, error:, response: nil, secrets: [])
+        response ||= error.response if error.respond_to?(:response) && error.response.respond_to?(:code)
+        status = response ? "#{response.code} #{response.message}" : 'No HTTP response received'
+        "Operation: #{safe_text(operation)}\nURL: #{safe_url(url)}\nConnection: #{connection(error)}\n" \
+          "HTTP status: #{safe_text(status)}\nDetails: " \
+          "#{bounded(safe_text(error.message, secrets: secrets + url_secrets(url)))}"
+      end
+
+      def self.connection(error)
+        case error
+        when OpenSSL::SSL::SSLError then 'TLS connection or certificate verification failed'
+        when SocketError then 'DNS resolution failed'
+        when Errno::ECONNREFUSED then 'Connection refused'
+        when Timeout::Error, Errno::ETIMEDOUT then 'Connection timed out'
+        when Net::HTTPFatalError then 'Proxy connection failed'
+        else 'Connection or transfer failed'
+        end
+      end
+
+      def self.native(result, operation:, tool:, url: nil, secrets: [])
+        text = safe_text("#{result.stderr}\n#{result.stdout}", secrets: secrets)
+        location = url ? safe_url(url) : "Not reported separately by #{tool}; see native output"
+        "Operation: #{safe_text(operation)}\nURL: #{location}\n" \
+          "HTTP status / reason: Not reported separately by #{tool}; see native output\n" \
+          "Response: Not provided separately by #{tool}\n" \
+          "#{tool} output (exit=#{result.exit_status}, timeout=#{result.timed_out}):\n" \
+          "#{text.strip.empty? ? '[No native diagnostic available]' : bounded(text.strip)}"
+      end
+
+      def self.command(result, operation:, tool:, secrets: [])
+        secrets += %w[EMPEIRA_AGENT_REPO_USERNAME EMPEIRA_AGENT_REPO_PASSWORD].filter_map { |key| ENV.fetch(key, nil) }
+        stdout = bounded(safe_text(result.stdout, secrets: secrets))
+        stderr = bounded(safe_text(result.stderr, secrets: secrets))
+        "Operation: #{safe_text(operation, secrets: secrets)}\nTool: #{safe_text(tool)}\n" \
+          "Exit code: #{result.exit_status || 'unavailable'}\nTimeout: #{result.timed_out}\n" \
+          "stdout:\n#{stdout.empty? ? '[Empty]' : stdout}\nstderr:\n#{stderr.empty? ? '[Empty]' : stderr}"
+      end
+
+      def self.response_text(body, content_type, secrets)
+        return '[Empty response body]' if body.empty?
+        return '[Binary response body omitted]' if binary?(body, content_type)
+
+        text = safe_text(body, secrets: secrets)
+        prefix = content_type.to_s.match?(/html/i) ? "[HTML response]\n" : ''
+        "#{prefix}#{bounded(text)}"
+      end
+
+      def self.binary?(body, content_type)
+        body.b.match?(/[\x00-\x08\x0b\x0c\x0e-\x1a\x1c-\x1f]/n) ||
+          content_type.to_s.match?(%r{\A(?:application/octet-stream|image/|audio/|video/)}) ||
+          (!body.dup.force_encoding('UTF-8').valid_encoding? && !content_type.to_s.match?(/text|json|xml/i))
+      end
+
+      def self.bounded(text)
+        return text if text.bytesize <= LIMIT
+
+        "#{text.byteslice(0, LIMIT).scrub}\n[Truncated diagnostic after #{LIMIT} bytes]"
+      end
+
+      def self.safe_url(value)
+        uri = URI(value.to_s)
+        uri.user = nil
+        uri.password = nil
+        uri.fragment = nil
+        if uri.query
+          uri.query = URI.encode_www_form(URI.decode_www_form(uri.query).map do |key, item|
+            [key, key.match?(QUERY_SECRET) ? '[REDACTED]' : item]
+          end)
+        end
+        uri.to_s
+      rescue URI::InvalidURIError, ArgumentError
+        '[Invalid URL omitted]'
+      end
+
+      def self.url_secrets(value)
+        uri = URI(value.to_s)
+        fields = uri.userinfo.to_s.split(':', 2) + URI.decode_www_form(uri.query.to_s).filter_map do |key, item|
+          item if key.match?(QUERY_SECRET)
+        end
+        fields.flat_map { |field| [field, URI.decode_www_form_component(field)] }.reject(&:empty?)
+      rescue URI::InvalidURIError, ArgumentError
+        []
+      end
+
+      # Redact before limiting output; retain actual URL hosts/paths and multiline server details.
+      def self.safe_text(text, secrets: [])
+        value = text.to_s.dup.force_encoding('UTF-8').scrub
+        values = known_values(value, secrets)
+        value = value.gsub(URL) { |url| safe_url(url) }
+        values.each { |item| value = value.gsub(item, '[REDACTED]') }
+        strip_controls(redact_fields(value))
+      end
+
+      def self.known_values(text, secrets)
+        values = secrets + text.scan(URL).flat_map { |url| url_secrets(url) }
+        values << Base64.strict_encode64(secrets.join(':')) if secrets.size == 2
+        values.reject(&:empty?).uniq.sort_by { |item| -item.length }
+      end
+
+      def self.redact_fields(value)
+        value = value.gsub(/-----BEGIN [^-]*PRIVATE KEY-----.*?(?:-----END [^-]*PRIVATE KEY-----|\z)/m, '[REDACTED]')
+        value = value.gsub(/^\s*(?:\S*-)?(?:Authorization|Cookie|Set-Cookie):[^\n]*/i, '[REDACTED HEADER]')
+        value = value.gsub(/\bno basic auth credentials\b/i, 'authentication required (no credentials)')
+        value = value.gsub(/\b(?:Bearer|Basic)\s+\S+/i, '[REDACTED]')
+        value = value.gsub(/((?:#{SECRET})["']?\s*[=:]\s*)(?:"[^"]*"|'[^']*'|\S+)/i, '\1[REDACTED]')
+        value.gsub(/\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|glpat-[A-Za-z0-9_-]+)/, '[REDACTED]')
+      end
+
+      def self.strip_controls(value)
+        value.gsub(/\e\][^\a]*(?:\a|\e\\)/, '').gsub(/\e\[[0-9;]*[A-Za-z]/, '')
+             .gsub(/[\p{Cc}\p{Cf}&&[^\n\t]]/, '')
+      end
+
+      def self.registry_failure(diagnostic, timed_out: false)
+        return :network if timed_out || diagnostic.match?(/timed?\s*out|timeout/i)
+        return :tls if diagnostic.match?(/x509|certificate.*(?:failed|unknown|expired)|unknown authority/i)
+        if diagnostic.match?(/connection\srefused|network\s(?:is\s)?unreachable|no\ssuch\shost|DNS\sfailure|
+                              (?:name|temporary)\sresolution|could\snot\sresolve\s(?:host|hostname)/ix)
+          return :network
+        end
+
+        auth = diagnostic.gsub(/permission denied/i, '')
+        if auth.match?(/\b(?:401|403|unauthorized|forbidden|denied|insufficient_scope)\b|
+                       authentication\srequired|no\sbasic\sauth\scredentials/ix)
+          return :auth
+        end
+        return :missing if diagnostic.match?(/manifest unknown|name unknown|not found/i)
+
+        :unknown
+      end
+
+      def self.clean(text)
+        value = text.to_s.encode('UTF-8', invalid: :replace, undef: :replace)
+        value = value.gsub(/-----BEGIN [^-]*PRIVATE KEY-----.*?(?:-----END [^-]*PRIVATE KEY-----|\z)/m, '[REDACTED]')
+        value.lines.filter_map { |line| diagnostic(line) }.first(20).join("\n")
+      end
+
+      def self.diagnostic(line)
+        line = line.gsub(/\e\][^\a]*(?:\a|\e\\)/, '').gsub(/\e\[[0-9;]*[A-Za-z]/, '')
+                   .gsub(/[\p{Cc}\p{Cf}]/, ' ').strip
+        return if line.empty? || !line.match?(RELEVANT) || line.match?(/authorization|cookie/i)
+        if line.match?(/(?:executing|command|running):|\b(?:git|ssh)\s+(?:-\S+\s+)*(?:clone|fetch|checkout|ls-remote)/i)
+          return
+        end
+
+        sanitize(line)[0, 500]
+      end
+
+      def self.sanitize(line)
+        line = line.gsub(/\bno basic auth credentials\b/i, 'authentication required (no credentials)')
+        line = line.gsub(%r{\b(?:https?|ssh|docker|oci)://[^\s<>"']+}, '[REDACTED URL]')
+        line = line.gsub(/\b(?:Bearer|Basic)\s+\S+/i, '[REDACTED]')
+        line = line.gsub(/((?:#{SECRET})["']?\s*[=:]\s*)(?:"[^"]*"|'[^']*'|\S+)/i, '\1[REDACTED]')
+        line = line.gsub(/\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|glpat-[A-Za-z0-9_-]+)/, '[REDACTED]')
+        line = line.gsub(/((?:load key|identity file|private key)\s*)["'][^"']*["']/i, '\1[REDACTED PATH]')
+        line = line.gsub(%r{"/[^"\n]*"|'/[^'\n]*'}, '[REDACTED PATH]')
+        line.gsub(%r{(?<![\w/])(?:~?/)[^\s"'<>:]+}, '[REDACTED PATH]')
+      end
+    end
+  end
+end