nonnative 3.22.0 → 3.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fa10a31c57c45551a417924990d2d870e137d7561c1581577a6e965099472cc
-  data.tar.gz: dcd07b46e9ce599562c9c0f517ff7b6f46b529dfcf70c8f462cef3fd548704eb
+  metadata.gz: d81874eb81ecd99758c560530adaf6dd701ac6136258ec36b04a074312e45e65
+  data.tar.gz: 05e90f242c9cd70a7c544705d2db49c593e7615ff7edfc28e6864154036e758b
 SHA512:
-  metadata.gz: cb3cf0ffe148327fb056ad6a16851156b060373d69a06dc13b615197bb6a3aec5cb70faf412c4f31a68f8e92ce297646201fd3151c068758cc22017f5c1a745f
-  data.tar.gz: 8caa697ae5eb5c0b005da119b5ff518f68407c52cf876ca065a522147bc98d3064fff7899e54da1897408b9b963b87124ba1f62fd729913c073e3e1de8016dab
+  metadata.gz: 59abcf2ef7f4c1cf0785ab43dbca7af059441f8a65379601adc1204c8860955b462fc7fa8dac8b1bbb93cd7a449296cac36ea18bee692b67baad567b83cea3ad
+  data.tar.gz: ac4407b3205ca54a8e2496e9e2ce2594ee8bf8d7fff8f9c0ae5bce929fdf4b707732c54c8b45ccb038e79bb34601cf52823a7ee99ae6c7ae05a8bbdfb60cc05a

data/README.md

@@ -465,6 +465,30 @@ module Nonnative
 end
 ```
 
+To run multiple Rack services on one managed port, pass a non-empty mount map. Each key must start
+with `/`, and the mounted application receives the remaining `PATH_INFO`:
+
+```ruby
+module Nonnative
+  module Features
+    class HealthService < Nonnative::HTTPService
+      get '/' do
+        'ok'
+      end
+    end
+
+    class HTTPServer < Nonnative::HTTPServer
+      def initialize(service)
+        super({ '/api' => HelloService.new, '/health' => HealthService.new }, service)
+      end
+    end
+  end
+end
+```
+
+The existing single-service form remains supported. Nonnative converts a mount map to a
+`Rack::URLMap` and keeps one server lifecycle and port. An empty mount map raises `ArgumentError`.
+
 Set it up programmatically:
 
 ```ruby
@@ -517,6 +541,8 @@ end
 
 The system allows you to define an in-process HTTP forward proxy server for external systems, e.g. `api.github.com`. This is a server implementation, not a fault-injection service proxy.
 
+The proxy preserves the upstream status, body, and safe end-to-end response headers such as `Content-Type`, `ETag`, and application-specific metadata. It removes hop-by-hop, connection-nominated, proxy-authentication, and framing headers; `Set-Cookie`, `Location`, and `Content-Encoding` are not forwarded.
+
 Define your server:
 
 ```ruby
@@ -603,6 +629,30 @@ module Nonnative
 end
 ```
 
+To serve multiple gRPC services on one managed port, pass a non-empty array of handler classes or
+instances:
+
+```ruby
+module Nonnative
+  module Features
+    class HealthService < Grpc::Health::V1::Health::Service
+      def check(_request, _call)
+        Grpc::Health::V1::HealthCheckResponse.new(status: :SERVING)
+      end
+    end
+
+    class GRPCServer < Nonnative::GRPCServer
+      def initialize(service)
+        super([Greeter.new, HealthService.new], service)
+      end
+    end
+  end
+end
+```
+
+The existing single-handler form remains supported. Nonnative registers each handler before the
+server starts, so application and standard health handlers can share one lifecycle and endpoint.
+
 Set it up programmatically:
 
 ```ruby
@@ -802,6 +852,7 @@ Clients connect to the service `host`/`port`, while the proxy forwards traffic t
 - `timeout` - Accepts the connection and stalls traffic until reset or stop closes the connection, so clients exercise their own read timeout behavior.
 - `invalid_data` - Forwards client requests unchanged, then corrupts upstream responses before they reach the client.
 - `bandwidth` - Throttles forwarded throughput to `options.rate` kilobytes per second (1 KB = 1024 bytes) by sleeping in proportion to the bytes read, in both directions, so clients see a slow-but-alive dependency. When `rate` is absent or not positive, traffic forwards at full speed.
+- `limit_data` - Forwards client requests unchanged, then sends the first `options.bytes` bytes of the upstream byte stream on each connection and gracefully closes the connection. When `bytes` is absent or not positive, traffic forwards at full speed.
 
 ###### 🧩 Fault Injection Services
 
@@ -814,6 +865,7 @@ service = Nonnative.pool.service_by_name(name)
 service.proxy.close_all # To use close_all.
 service.proxy.reset_peer # To reset (RST) client connections.
 service.proxy.timeout # To stall traffic until reset or stop.
+service.proxy.limit_data # To truncate the upstream byte stream at options.bytes.
 service.proxy.reset # To reset it back to a good state.
 ```
 
@@ -823,6 +875,7 @@ Use the Cucumber proxy steps:
 Given I set the proxy for service 'service_1' to 'close_all'
 Given I set the proxy for service 'service_1' to 'reset_peer'
 Given I set the proxy for service 'service_1' to 'timeout'
+Given I set the proxy for service 'service_1' to 'limit_data'
 Then I should reset the proxy for service 'service_1'
 ```
 

data/lib/nonnative/cucumber.rb

@@ -60,6 +60,7 @@ module Nonnative
         'timeout' => :timeout,
         'invalid_data' => :invalid_data,
         'bandwidth' => :bandwidth,
+        'limit_data' => :limit_data,
         'reset' => :reset
       }.freeze
 

data/lib/nonnative/fault_injection_proxy.rb

@@ -15,6 +15,7 @@ module Nonnative
   # - {#timeout}: accept connections and keep them silent until clients time out
   # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
   # - {#bandwidth}: throttle forwarded throughput to a configured rate (KB/s)
+  # - {#limit_data}: forward a configured number of response bytes, then gracefully close
   # - {#reset}: return to healthy pass-through behavior
   #
   # State changes terminate any active connections so new connections observe the new behavior.
@@ -36,6 +37,8 @@ module Nonnative
   #   - `delay`: delay duration in seconds used by {#delay}
   #   - `jitter`: optional random offset (seconds) added in `-jitter..jitter` to each `delay` (a
   #     negative value uses its magnitude), so clients see variable latency instead of a flat value
+  #   - `bytes`: positive response byte limit used by {#limit_data}; absent or non-positive values
+  #     use pass-through behavior
   #
   # @see Nonnative::Proxy
   # @see Nonnative::SocketPairFactory
@@ -150,6 +153,17 @@ module Nonnative
       apply_state :bandwidth
     end
 
+    # Truncates the upstream byte stream after a configured number of bytes.
+    #
+    # Client requests are forwarded unchanged. The response byte limit is read from
+    # `service.proxy.options[:bytes]`; when it is absent or not positive, the connection forwards at
+    # full speed without truncation.
+    #
+    # @return [void]
+    def limit_data
+      apply_state :limit_data
+    end
+
     # Resets the proxy back to healthy pass-through behavior.
     #
     # @return [void]

data/lib/nonnative/grpc_server.rb

@@ -12,13 +12,18 @@ module Nonnative
   #
   # @see Nonnative::Server
   class GRPCServer < Nonnative::Server
-    # Creates a gRPC server and registers the provided service handler.
+    # Creates a gRPC server and registers the provided service handler(s).
     #
-    # @param svc [Object] a gRPC service implementation (typically a `...::Service` subclass instance)
+    # @param svc [Object, Array<Object>] a gRPC service implementation or a non-empty array of
+    #   implementations (typically `...::Service` subclasses or instances)
     # @param service [Nonnative::ConfigurationServer] server configuration
+    # @raise [ArgumentError] if `svc` is an empty array
     def initialize(svc, service)
       @server = GRPC::RpcServer.new
-      server.handle(svc)
+      handlers = svc.is_a?(Array) ? svc : [svc]
+      raise ArgumentError, 'gRPC server requires at least one service handler' if handlers.empty?
+
+      handlers.each { |handler| server.handle(handler) }
 
       # Unfortunately gRPC has only one logger so the first server wins.
       GRPC.define_singleton_method(:logger) do

data/lib/nonnative/http_client.rb

@@ -80,19 +80,57 @@ module Nonnative
       end
     end
 
+    # Performs a PATCH request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param payload [Object] request payload
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
+    def patch(pathname, payload, opts = {})
+      with_exception do
+        resource(pathname, opts).patch(payload)
+      end
+    end
+
+    # Performs a HEAD request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param opts [Hash] RestClient request options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
+    def head(pathname, opts = {})
+      with_exception do
+        resource(pathname, opts).head
+      end
+    end
+
+    # Performs an OPTIONS request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param opts [Hash] RestClient request options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
+    def options(pathname, opts = {})
+      with_exception do
+        RestClient::Request.execute(opts.merge(method: :options, url: request_url(pathname)))
+      end
+    end
+
     # Creates a RestClient resource for a relative path.
     #
     # @param pathname [String] path relative to `host`
     # @param opts [Hash] RestClient request options
     # @return [RestClient::Resource]
     def resource(pathname, opts)
-      RestClient::Resource.new(URI.join(host, pathname).to_s, opts)
+      RestClient::Resource.new(request_url(pathname), opts)
     end
 
     private
 
     attr_reader :host, :exceptions
 
+    def request_url(pathname)
+      URI.join(host, pathname).to_s
+    end
+
     def with_exception
       yield
     rescue *exceptions => e

data/lib/nonnative/http_proxy_server.rb

@@ -3,7 +3,8 @@
 # Sinatra-based HTTP forward proxy server used as an in-process Nonnative server.
 #
 # The proxy receives inbound HTTP requests and forwards them to an upstream host over HTTPS, returning
-# the upstream response status and body.
+# the upstream response status, body, and safe end-to-end response headers. Hop-by-hop,
+# connection-nominated, proxy-authentication, framing, and deferred response headers are not forwarded.
 #
 # This file defines two classes:
 #
@@ -21,9 +22,27 @@ module Nonnative
   #
   # The upstream host is configured via service settings (see {Nonnative::HTTPProxyServer}).
   #
-  # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
+  # Supported HTTP verbs: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.
   class HTTPProxy < Nonnative::HTTPService
-    NON_FORWARDABLE_HEADERS = %w[
+    NON_FORWARDABLE_RESPONSE_HEADERS = %w[
+      connection
+      content-encoding
+      content-length
+      keep-alive
+      location
+      proxy-authenticate
+      proxy-authorization
+      proxy-authentication-info
+      proxy-connection
+      set-cookie
+      status
+      te
+      trailer
+      transfer-encoding
+      upgrade
+    ].freeze
+
+    NON_FORWARDABLE_REQUEST_HEADERS = %w[
       Host
       Accept-Encoding
       Version
@@ -37,14 +56,14 @@ module Nonnative
     #
     # @param request [Sinatra::Request] the incoming request
     # @return [Hash{String=>String}] headers to forward to the upstream
-    def retrieve_headers(request)
+    def forward_request_headers(request)
       headers = request.env.each_with_object({}) do |(header, value), result|
-        next unless forward_header?(header)
+        next unless forward_request_header?(header)
 
-        result[normalized_header_name(header)] = value
+        result[normalized_request_header_name(header)] = value
       end
 
-      headers.except(*NON_FORWARDABLE_HEADERS)
+      headers.except(*NON_FORWARDABLE_REQUEST_HEADERS)
     end
 
     # Builds the upstream URL for the given request.
@@ -86,23 +105,65 @@ module Nonnative
 
     private
 
-    def forward_header?(header)
+    def forward_response_headers(response)
+      raw_headers = response.raw_headers
+      connection_headers = response_connection_headers(raw_headers)
+
+      raw_headers.each_with_object({}) do |(header, value), result|
+        normalized_header = normalized_response_header_name(header)
+        next unless forward_response_header?(normalized_header, connection_headers)
+
+        result[normalized_header] = Array(value).join(', ')
+      end
+    end
+
+    def response_connection_headers(raw_headers)
+      connection_headers = raw_headers.each_with_object([]) do |(header, values), result|
+        next unless normalized_response_header_name(header) == 'connection'
+
+        Array(values).each { |value| result.concat(value.to_s.split(',')) }
+      end
+
+      connection_headers.map { |header| normalized_response_header_name(header) }
+    end
+
+    def forward_response_header?(header, connection_headers)
+      !NON_FORWARDABLE_RESPONSE_HEADERS.include?(header) &&
+        !connection_headers.include?(header) &&
+        !header.start_with?('rack.')
+    end
+
+    def normalized_response_header_name(header)
+      header.to_s.strip.downcase
+    end
+
+    def forward_request_header?(header)
       header.start_with?('HTTP_') || %w[CONTENT_TYPE CONTENT_LENGTH].include?(header)
     end
 
-    def normalized_header_name(header)
+    def normalized_request_header_name(header)
       header.delete_prefix('HTTP_').split('_').map(&:capitalize).join('-')
     end
 
-    %w[get post put patch delete].each do |verb|
+    # Registered before `get` so it takes precedence over Sinatra's GET-generated HEAD route,
+    # which would otherwise forward HEAD requests upstream as GET.
+    head(/.*/) do
+      res = api_response(method: :head, url: build_url(request, settings), headers: forward_request_headers(request))
+
+      headers(forward_response_headers(res))
+      status res.code
+    end
+
+    %w[get post put patch delete options].each do |verb|
       send(verb, /.*/) do
         res = api_response(
           method: verb.to_sym,
           url: build_url(request, settings),
-          headers: retrieve_headers(request),
+          headers: forward_request_headers(request),
           payload: retrieve_payload(request, verb)
         )
 
+        headers(forward_response_headers(res))
         status res.code
         res.body
       end

data/lib/nonnative/http_server.rb

@@ -36,9 +36,16 @@ module Nonnative
   class HTTPServer < Nonnative::Server
     # Creates a Puma server for the given HTTP service and runner configuration.
     #
-    # @param http_service [#call] an HTTP service instance
+    # @param http_service [#call, Hash<String, #call>] an HTTP service instance or mount map
     # @param service [Nonnative::ConfigurationServer] server configuration
+    # @raise [ArgumentError] if `http_service` is an empty mount map
     def initialize(http_service, service)
+      if http_service.is_a?(Hash)
+        raise ArgumentError, 'HTTP server requires at least one service mount' if http_service.empty?
+
+        http_service = Rack::URLMap.new(http_service)
+      end
+
       # Keep the log IO so the server lifecycle can release Puma's file handle on stop.
       @log = File.open(service.log, 'a')
       options = {

data/lib/nonnative/limit_data_socket_pair.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to truncate upstream responses.
+  #
+  # When active, client requests pass through unchanged, while the first `proxy.options[:bytes]`
+  # bytes of the upstream stream are forwarded to the client on each connection. Once the limit is
+  # reached, the pair's normal connection lifecycle closes both sockets gracefully. A missing or
+  # non-positive limit leaves the connection in pass-through mode.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#limit_data}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
+  class LimitDataSocketPair < SocketPair
+    # Tracks the client socket and response byte budget for this connection.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
+    def connect(local_socket)
+      @local_socket = local_socket
+      @remaining = proxy.options[:bytes]
+      @limit_reached = false
+
+      super
+    ensure
+      @local_socket = nil
+      @remaining = nil
+      @limit_reached = nil
+    end
+
+    protected
+
+    # Stops the base forwarding loop after the response budget has been written.
+    #
+    # @param ready [Array<Array<IO>>] the result from `select`
+    # @param source_socket [IO] readable side
+    # @param destination_socket [IO] writable side
+    # @return [Boolean] whether the forwarding loop should terminate
+    def pipe?(ready, source_socket, destination_socket)
+      return true if @limit_reached
+
+      super || @limit_reached
+    end
+
+    # Limits writes to the client while leaving writes to the upstream unchanged.
+    #
+    # @param socket [IO] the socket to write to
+    # @param data [String] the original payload
+    # @return [Integer] number of bytes written
+    def write(socket, data)
+      return super unless socket.equal?(@local_socket)
+      return super if @remaining.nil? || @remaining <= 0
+
+      data = data.byteslice(0, @remaining)
+      @remaining -= data.bytesize
+      @limit_reached = @remaining.zero?
+
+      super
+    end
+  end
+end

data/lib/nonnative/pool.rb

@@ -23,17 +23,14 @@ module Nonnative
       @processes = nil
     end
 
-    # Starts all configured runners and yields results for each process/server.
+    # Starts all configured runners and collects lifecycle and readiness errors.
     #
     # Services are started first (proxy-only) and checked for opt-in readiness, then servers and processes are
-    # started and checked for readiness.
+    # started and checked for readiness. Each readiness failure is described with the runner and, for a process
+    # that exited early, its termination detail.
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam values [Object] runner-specific return value from `start` (e.g. `[pid, running]` for processes)
-    # @yieldparam result [Boolean] result of the port readiness check (`true` if ready in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and readiness-check errors collected while starting
-    def start(&)
+    def start
       errors = []
 
       errors.concat(service_lifecycle(services, :start, :start))
@@ -41,24 +38,20 @@ module Nonnative
       errors.concat(service_readiness_errors)
       return errors if service_readiness_errors.any?
 
-      [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start, &)) }
+      [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start)) }
 
       errors
     end
 
-    # Stops all configured runners and yields results for each process/server.
+    # Stops all configured runners and collects lifecycle and shutdown errors.
     #
     # Processes and servers are stopped first and checked for shutdown, then services are stopped (proxy-only).
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam id [Object] runner-specific identifier returned by `stop` (e.g. pid or object_id)
-    # @yieldparam result [Boolean] result of the port shutdown check (`true` if closed in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and shutdown-check errors collected while stopping
-    def stop(&)
+    def stop
       errors = []
 
-      [processes, servers].each { |runners| errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop, &)) }
+      [processes, servers].each { |runners| errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop)) }
       errors.concat(service_lifecycle(services, :stop, :stop))
 
       errors
@@ -69,16 +62,12 @@ module Nonnative
     # This is used to rollback partial startup after a failed {#start} without constructing new runner
     # wrappers as a side effect.
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam id [Object] runner-specific identifier returned by `stop`
-    # @yieldparam result [Boolean] result of the port shutdown check (`true` if closed in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and shutdown-check errors collected while rolling back
-    def rollback(&)
+    def rollback
       errors = []
 
       [existing_processes, existing_servers].each do |runners|
-        errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop, &))
+        errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :rollback))
       end
       errors.concat(service_lifecycle(existing_services, :stop, :stop))
 
@@ -196,7 +185,8 @@ module Nonnative
       end
     end
 
-    def run_lifecycle_checks(runners, lifecycle_method, port_method, action, &)
+    def run_lifecycle_checks(runners, lifecycle_method, port_method, phase)
+      action = phase == :start ? :start : :stop
       checks = []
       errors = []
 
@@ -207,7 +197,7 @@ module Nonnative
         errors << lifecycle_error(action, runner, e)
       end
 
-      errors.concat(yield_results(checks, action, &))
+      errors.concat(lifecycle_results(checks, phase, action))
     end
 
     def check_port(port, port_method)
@@ -216,17 +206,50 @@ module Nonnative
       { error: e }
     end
 
-    def yield_results(checks, action, &)
-      checks.each_with_object([]) do |(type, values, port, thread), errors|
+    def lifecycle_results(checks, phase, action)
+      checks.each_with_object([]) do |(runner, values, port, thread), errors|
         result = thread.value
         if result[:error]
-          errors << port_error(action, type, result[:error])
-        elsif block_given?
-          yield type.name, values, result[:result], port
+          errors << port_error(action, runner, result[:error])
+        else
+          errors.concat(readiness_errors(phase, runner, values, result[:result], port))
         end
       end
     end
 
+    def readiness_errors(phase, runner, values, ready, port)
+      case phase
+      when :start then start_errors(runner, values, ready, port)
+      when :stop then stop_errors(runner, values, ready, port)
+      else rollback_errors(runner, values, ready, port)
+      end
+    end
+
+    def start_errors(runner, values, ready, port)
+      id, started = values
+      return [] if started && ready
+
+      message = "Started #{runner.name} with id #{id}, though did not respond in time for #{port.description}"
+      detail = runner.termination
+      [detail ? "#{message}; #{detail}" : message]
+    end
+
+    def stop_errors(runner, values, ready, port)
+      id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
+      errors = []
+      errors << "Stopped #{runner.name} with id #{id}, though did not respond in time for #{port.description}" unless ready
+      errors << "Stopped #{runner.name} with id #{id}, though the process did not exit in time" unless stopped
+      errors
+    end
+
+    def rollback_errors(runner, values, ready, port)
+      id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
+      errors = []
+      errors << "Rollback failed for #{runner.name} with id #{id}, because it did not stop in time for #{port.description}" unless ready
+      errors << "Rollback failed for #{runner.name} with id #{id}, because the process did not exit in time" unless stopped
+      errors
+    end
+
     def lifecycle_error(action, type, error)
       "#{action.to_s.capitalize} failed for #{runner_name(type)}: #{error.class} - #{error.message}"
     end

data/lib/nonnative/process.rb

@@ -37,7 +37,10 @@ module Nonnative
         wait_start
       end
 
-      [pid, ::Process.waitpid2(pid, ::Process::WNOHANG).nil?]
+      # Retain the reaped status for this lifecycle so startup diagnostics can report it.
+      status = ::Process.waitpid2(pid, ::Process::WNOHANG)
+      @status = status&.last
+      [pid, status.nil?]
     end
 
     # Stops the process if it is running.
@@ -62,6 +65,20 @@ module Nonnative
       @memory = nil
     end
 
+    # Describes how the process terminated when it exited before becoming ready.
+    #
+    # Returns `nil` while the process is still running, so callers can distinguish an early exit
+    # from a live process that merely missed its readiness window. The check is non-blocking and
+    # reuses the status captured during {#start} when available.
+    #
+    # @return [String, nil] termination detail (exit status or terminating signal), or `nil`
+    def termination
+      status = captured_status
+      return if status.nil?
+
+      terminated_description(status)
+    end
+
     protected
 
     def wait_stop
@@ -74,6 +91,28 @@ module Nonnative
 
     attr_reader :pid, :timeout
 
+    def captured_status
+      return @status unless @status.nil?
+      return if pid.nil?
+
+      # A process that exited during the readiness window has not been reaped yet.
+      @status = ::Process.waitpid2(pid, ::Process::WNOHANG)&.last
+    rescue Errno::ECHILD, Errno::ESRCH
+      nil
+    end
+
+    def terminated_description(status)
+      return "process exited before readiness with exit status #{status.exitstatus}" if status.exited?
+      return "process exited before readiness after being killed by signal #{signal_description(status.termsig)}" if status.signaled?
+
+      "process exited before readiness (#{status})"
+    end
+
+    def signal_description(signal)
+      name = Signal.signame(signal)
+      name ? "SIG#{name} (#{signal})" : signal.to_s
+    end
+
     def process_kill
       signal = Signal.list[service.signal || 'INT'] || Signal.list['INT']
       ::Process.kill(signal, pid)

data/lib/nonnative/runner.rb

@@ -26,6 +26,15 @@ module Nonnative
       service.name
     end
 
+    # Describes how the runner terminated before becoming ready, for lifecycle diagnostics.
+    #
+    # Base runners report nothing; {Nonnative::Process} overrides this to describe an early exit.
+    #
+    # @return [String, nil]
+    def termination
+      nil
+    end
+
     protected
 
     # Returns the underlying configuration object.

data/lib/nonnative/server.rb

@@ -32,7 +32,14 @@ module Nonnative
     #   - `true` (thread creation itself is considered started; readiness is checked separately)
     def start
       unless thread
-        @thread = Thread.new { perform_start }
+        @error = nil
+        @thread = Thread.new do
+          perform_start
+        rescue StandardError => e
+          @error = e
+          raise
+        end
+        @thread.report_on_exception = true
 
         wait_start
 
@@ -61,8 +68,22 @@ module Nonnative
       object_id
     end
 
+    # Describes how the server thread terminated before becoming ready, for lifecycle diagnostics.
+    #
+    # Returns `nil` while the thread is still alive, so callers can distinguish a dead thread from a
+    # live server that merely missed its readiness window.
+    #
+    # @return [String, nil] termination detail (clean early return or uncaught exception), or `nil`
+    def termination
+      return if thread.nil? || thread.alive?
+
+      return "server thread raised #{error.class}: #{error.message}" if error
+
+      'server thread exited before readiness'
+    end
+
     private
 
-    attr_reader :thread, :timeout
+    attr_reader :thread, :timeout, :error
   end
 end

data/lib/nonnative/socket_pair_factory.rb

@@ -14,6 +14,7 @@ module Nonnative
   # - `:timeout` -> {Nonnative::TimeoutSocketPair}
   # - `:invalid_data` -> {Nonnative::InvalidDataSocketPair}
   # - `:bandwidth` -> {Nonnative::BandwidthSocketPair}
+  # - `:limit_data` -> {Nonnative::LimitDataSocketPair}
   #
   # @see Nonnative::FaultInjectionProxy
   # @see Nonnative::SocketPair
@@ -23,30 +24,28 @@ module Nonnative
   # @see Nonnative::TimeoutSocketPair
   # @see Nonnative::InvalidDataSocketPair
   # @see Nonnative::BandwidthSocketPair
+  # @see Nonnative::LimitDataSocketPair
   class SocketPairFactory
+    PAIR_BY_STATE = {
+      close_all: CloseAllSocketPair,
+      reset_peer: ResetPeerSocketPair,
+      delay: DelaySocketPair,
+      timeout: TimeoutSocketPair,
+      invalid_data: InvalidDataSocketPair,
+      bandwidth: BandwidthSocketPair,
+      limit_data: LimitDataSocketPair
+    }.freeze
+    private_constant :PAIR_BY_STATE
+
     class << self
       # Creates a socket-pair instance for the given proxy state.
       #
-      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:reset_peer`, `:delay`, `:timeout`, `:invalid_data`, `:bandwidth`)
+      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:reset_peer`, `:delay`, `:timeout`,
+      #   `:invalid_data`, `:bandwidth`, `:limit_data`)
       # @param proxy [Nonnative::ConfigurationProxy] proxy configuration (host/port/options)
       # @return [Nonnative::SocketPair] a socket-pair implementation instance
       def create(kind, proxy)
-        pair = case kind
-               when :close_all
-                 CloseAllSocketPair
-               when :reset_peer
-                 ResetPeerSocketPair
-               when :delay
-                 DelaySocketPair
-               when :timeout
-                 TimeoutSocketPair
-               when :invalid_data
-                 InvalidDataSocketPair
-               when :bandwidth
-                 BandwidthSocketPair
-               else
-                 SocketPair
-               end
+        pair = PAIR_BY_STATE.fetch(kind, SocketPair)
 
         pair.new(proxy)
       end

data/lib/nonnative/version.rb

@@ -4,5 +4,5 @@ module Nonnative
   # The current gem version.
   #
   # @return [String]
-  VERSION = '3.22.0'
+  VERSION = '3.29.0'
 end

data/lib/nonnative.rb

@@ -116,6 +116,7 @@ require 'nonnative/delay_socket_pair'
 require 'nonnative/timeout_socket_pair'
 require 'nonnative/invalid_data_socket_pair'
 require 'nonnative/bandwidth_socket_pair'
+require 'nonnative/limit_data_socket_pair'
 require 'nonnative/socket_pair_factory'
 require 'nonnative/go_executable'
 require 'nonnative/cucumber'
@@ -271,10 +272,7 @@ module Nonnative
     def start
       @pool ||= Nonnative::Pool.new(configuration)
       errors = []
-      errors.concat(@pool.start do |name, values, result, ports|
-        id, started = values
-        errors << "Started #{name} with id #{id}, though did not respond in time for #{ports.description}" if !started || !result
-      end)
+      errors.concat(@pool.start)
       nil
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:start, e)
@@ -294,11 +292,7 @@ module Nonnative
       errors = []
       return if @pool.nil?
 
-      errors.concat(@pool.stop do |name, values, result, ports|
-        id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Stopped #{name} with id #{id}, though did not respond in time for #{ports.description}" unless result
-        errors << "Stopped #{name} with id #{id}, though the process did not exit in time" unless stopped
-      end)
+      errors.concat(@pool.stop)
       nil
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:stop, e)
@@ -363,11 +357,7 @@ module Nonnative
       errors = []
       return errors if @pool.nil?
 
-      errors.concat(@pool.rollback do |name, values, result, ports|
-        id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Rollback failed for #{name} with id #{id}, because it did not stop in time for #{ports.description}" unless result
-        errors << "Rollback failed for #{name} with id #{id}, because the process did not exit in time" unless stopped
-      end)
+      errors.concat(@pool.rollback)
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:rollback, e)
     ensure

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.22.0
+  version: 3.29.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -422,6 +422,7 @@ files:
 - lib/nonnative/http_service.rb
 - lib/nonnative/invalid_data_socket_pair.rb
 - lib/nonnative/jwt_token.rb
+- lib/nonnative/limit_data_socket_pair.rb
 - lib/nonnative/no_proxy.rb
 - lib/nonnative/not_found_error.rb
 - lib/nonnative/observability.rb