nonnative 3.19.0 → 3.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 011e40916b32666c33c2a0374ee97c3e96d563cf950f5c68e12b8afa7c18e986
-  data.tar.gz: 7b21a33ad8fc14077751e679b66a14523c79c0783004934f55fa61ea5608e477
+  metadata.gz: 59db521cea52e4a8c1d2aa8d76e79b50e7a9b76876b63ed8be4e46a665614a5d
+  data.tar.gz: 45f21fd21830aab99ce440d65d7cb80720449169684320f814a9e767881d8a1f
 SHA512:
-  metadata.gz: 0e24fea055ed0e972507bfcb8ebbdf2c604d41e1a6908333a1863f1ba44dd356ea518936d3d6076f73fb37d0c3a9f593b6321ef1392d51d6d1cdf4c145b5ad6d
-  data.tar.gz: ec70302587120b093bb506d5d324821e880b10e406974822f44e1efa7c3fdee29465847eb8f71466ab3806ddd0eb328f2e0788bca28196066c6b3636ce0edb83
+  metadata.gz: 47d05d9b12dc2601470b87af8a880018a0be1808aee7f501f48a703db422b57db37d041b4f93fbb4ebb5afd4545bccf1ed3bf9b15b7a9d9909ca9134dc1d0111
+  data.tar.gz: 0d191245bdedd04c73096cfc4c3cd1871966c6aa9b09a1e5295c835a76798afea4633638f2d6f3bc1179d20f683484c6b033a8c655b45c047c9c468d18aa7fca

data/README.md

@@ -211,6 +211,15 @@ Nonnative::Token.http_audience('GET', '/v1/things')        # => "GET /v1/things"
 Nonnative::Token.grpc_audience('/health.v1.Health/Check')  # => "/health.v1.Health/Check"
 ```
 
+By default the time claims are pinned to the current time (`iat`/`nbf` at now, `exp` at `now + expiration`). To write negative auth tests, `generate` accepts optional absolute `Time` overrides — `issued_at`, `not_before`, and `expires_at` — for minting not-yet-valid or clock-skewed tokens:
+
+```ruby
+# a token that is not valid until an hour from now
+token.generate(aud: 'GET /v1/things', sub: 'user-1', not_before: Time.now + 3600)
+```
+
+`ssh` tokens have no `nbf` claim, so passing `not_before` for the `ssh` kind raises `ArgumentError`.
+
 ### 🔁 Lifecycle strategies (Cucumber integration)
 
 Nonnative ships Cucumber hooks (when loaded) that support these tags/strategies:
@@ -456,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
@@ -508,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
@@ -594,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
@@ -789,9 +848,10 @@ Clients connect to the service `host`/`port`, while the proxy forwards traffic t
 
 - `close_all` - Closes the socket as soon as it connects.
 - `reset_peer` - Resets the socket as soon as it connects, so clients observe a TCP reset (`Errno::ECONNRESET`) rather than the graceful close performed by `close_all`.
-- `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through options.
+- `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through `options.delay`. An optional `options.jitter` (seconds) adds a random offset in `-jitter..jitter` to each delay (a negative value uses its magnitude), so clients see variable, tail-latency-like timing instead of a flat value.
 - `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.
 
 ###### 🧩 Fault Injection Services
 

data/lib/nonnative/bandwidth_socket_pair.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate a bandwidth-limited link.
+  #
+  # When active, each forwarded read is throttled so throughput does not exceed
+  # `proxy.options[:rate]` kilobytes per second (1 KB = 1024 bytes), by sleeping in proportion to the
+  # bytes read. Both directions are throttled, so a client under test sees a slow-but-alive
+  # dependency. When `rate` is absent or not positive the connection forwards at full speed.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#bandwidth}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
+  class BandwidthSocketPair < SocketPair
+    # One kilobyte in bytes; `proxy.options[:rate]` is expressed in KB/s.
+    KILOBYTE = 1024
+
+    # Reads from the socket, then sleeps so the forwarded throughput stays within the configured rate.
+    #
+    # @param socket [IO] the socket to read from
+    # @return [String] the bytes read from the socket
+    def read(socket)
+      super.tap { |data| throttle(data.bytesize) }
+    end
+
+    private
+
+    # Sleeps in proportion to the bytes read so throughput does not exceed `rate` KB/s. A missing or
+    # non-positive rate (or an empty read) forwards at full speed.
+    #
+    # @param bytes [Integer] the number of bytes just read
+    # @return [void]
+    def throttle(bytes)
+      rate = proxy.options[:rate]
+      return if rate.nil? || rate <= 0 || bytes.zero?
+
+      sleep(bytes / (rate * KILOBYTE.to_f))
+    end
+  end
+end

data/lib/nonnative/cucumber.rb

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

data/lib/nonnative/delay_socket_pair.rb

@@ -5,7 +5,11 @@ module Nonnative
   #
   # When active, reads from the socket are delayed by a configured duration before being forwarded.
   #
-  # The delay duration is controlled by `proxy.options[:delay]` and defaults to 2 seconds.
+  # The delay duration is controlled by `proxy.options[:delay]` and defaults to 2 seconds. An
+  # optional `proxy.options[:jitter]` (seconds) adds a random offset in `-jitter..jitter` to each
+  # delay so clients see variable, tail-latency-like timing instead of a flat value; a negative
+  # jitter uses its magnitude and the resulting delay is never negative. When `jitter` is absent the
+  # delay is the flat duration.
   #
   # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#delay}.
   #
@@ -20,10 +24,22 @@ module Nonnative
     def read(socket)
       Nonnative.logger.info "delaying socket '#{socket.inspect}' for 'delay' pair"
 
-      duration = proxy.options[:delay] || 2
-      sleep duration
+      sleep delay_duration
 
       super
     end
+
+    private
+
+    # The delay applied before a read, optionally jittered by `proxy.options[:jitter]`.
+    #
+    # @return [Numeric] seconds to sleep (never negative)
+    def delay_duration
+      duration = proxy.options[:delay] || 2
+      jitter = proxy.options[:jitter]&.abs
+      return duration unless jitter
+
+      [duration + rand(-jitter..jitter), 0].max
+    end
   end
 end

data/lib/nonnative/fault_injection_proxy.rb

@@ -14,6 +14,7 @@ module Nonnative
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
   # - {#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)
   # - {#reset}: return to healthy pass-through behavior
   #
   # State changes terminate any active connections so new connections observe the new behavior.
@@ -33,6 +34,8 @@ module Nonnative
   # - `wait`: sleep interval (seconds) applied after state changes
   # - `options`:
   #   - `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
   #
   # @see Nonnative::Proxy
   # @see Nonnative::SocketPairFactory
@@ -137,6 +140,16 @@ module Nonnative
       apply_state :invalid_data
     end
 
+    # Throttles forwarded throughput to a configured rate.
+    #
+    # The rate is controlled by `service.proxy.options[:rate]` (kilobytes per second); when it is
+    # absent or not positive the connection forwards at full speed.
+    #
+    # @return [void]
+    def bandwidth
+      apply_state :bandwidth
+    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,6 +80,18 @@ 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
+
     # Creates a RestClient resource for a relative path.
     #
     # @param pathname [String] path relative to `host`

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:
 #
@@ -23,7 +24,25 @@ module Nonnative
   #
   # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
   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,11 +105,43 @@ 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
 
@@ -99,10 +150,11 @@ module Nonnative
         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/jwt_token.rb

@@ -27,16 +27,19 @@ module Nonnative
     #
     # @param aud [String] the `aud` claim (for example `"GET /v1/things"` or a gRPC full method)
     # @param sub [String] the `sub` claim
+    # @param issued_at [Time, nil] overrides the `iat` claim (default: now)
+    # @param not_before [Time, nil] overrides the `nbf` claim (default: `issued_at`)
+    # @param expires_at [Time, nil] overrides the `exp` claim (default: `issued_at` plus `expiration`)
     # @return [String] the signed JWT
-    def generate(aud:, sub:)
-      now = Time.now.to_i
+    def generate(aud:, sub:, issued_at: nil, not_before: nil, expires_at: nil)
+      now = issued_at || Time.now
       payload = {
         iss: @issuer,
         aud: aud,
         sub: sub,
-        iat: now,
-        nbf: now,
-        exp: now + @expiration,
+        iat: now.to_i,
+        nbf: (not_before || now).to_i,
+        exp: (expires_at || (now + @expiration)).to_i,
         jti: SecureRandom.uuid
       }
 

data/lib/nonnative/paseto_token.rb

@@ -28,18 +28,21 @@ module Nonnative
     #
     # @param aud [String] the `aud` claim (for example `"GET /v1/things"` or a gRPC full method)
     # @param sub [String] the `sub` claim
+    # @param issued_at [Time, nil] overrides the `iat` claim (default: now)
+    # @param not_before [Time, nil] overrides the `nbf` claim (default: `issued_at`)
+    # @param expires_at [Time, nil] overrides the `exp` claim (default: `issued_at` plus `expiration`)
     # @return [String] the signed PASETO token
-    def generate(aud:, sub:)
+    def generate(aud:, sub:, issued_at: nil, not_before: nil, expires_at: nil)
       load_dependencies!
 
-      now = Time.now.utc
+      now = (issued_at || Time.now).utc
       claims = {
         'iss' => @issuer,
         'aud' => aud,
         'sub' => sub,
         'iat' => now.iso8601,
-        'nbf' => now.iso8601,
-        'exp' => (now + @expiration).iso8601,
+        'nbf' => (not_before || now).utc.iso8601,
+        'exp' => (expires_at || (now + @expiration)).utc.iso8601,
         'jti' => SecureRandom.uuid
       }
 

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)