nonnative 3.29.0 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d81874eb81ecd99758c560530adaf6dd701ac6136258ec36b04a074312e45e65
-  data.tar.gz: 05e90f242c9cd70a7c544705d2db49c593e7615ff7edfc28e6864154036e758b
+  metadata.gz: 954eb6b4c3c122729406d275f3befa59e19b8db405e14cb2ee8fd759354f97ba
+  data.tar.gz: 39291c978f15b62b187aeb51b5d51f8b0479d314261f1eaab85e6d9f441b3a54
 SHA512:
-  metadata.gz: 59abcf2ef7f4c1cf0785ab43dbca7af059441f8a65379601adc1204c8860955b462fc7fa8dac8b1bbb93cd7a449296cac36ea18bee692b67baad567b83cea3ad
-  data.tar.gz: ac4407b3205ca54a8e2496e9e2ce2594ee8bf8d7fff8f9c0ae5bce929fdf4b707732c54c8b45ccb038e79bb34601cf52823a7ee99ae6c7ae05a8bbdfb60cc05a
+  metadata.gz: f2a6efd54e9af260f1e0261347e0f2d93825392833bbbc8818e073dfd13359eb3739afa8bd535fea01e502fbe3d0664abbae49b41eb17fed1531c1a19019e0f1
+  data.tar.gz: 3b6f5e46899a77d275500d7d5edca75a46f739db103d7b006ca8cbe8699a24edc362679226ba7e67221dd2fb1cc200e09c4c366b9b3faa8a42fa17be61b9b246

data/README.md

@@ -57,7 +57,10 @@ YAML configuration is loaded as data only: ERB is not evaluated and arbitrary Ru
 deserialized.
 
 > [!CAUTION]
-> Treat YAML configuration as plain data. ERB is not evaluated and arbitrary Ruby object tags are rejected.
+> Treat YAML configuration as plain data. ERB is not evaluated, `${VAR}` values are not expanded,
+> and arbitrary Ruby object tags are rejected. Unknown structural keys may be ignored, although YAML
+> syntax, object safety, and supported value shapes are still validated. Keep values that vary by
+> environment in programmatic Ruby configuration, where Ruby's `ENV` is available.
 
 High-level configuration fields:
 - `version`: configuration version (example: `"1.0"`).
@@ -74,7 +77,8 @@ Common runner fields:
 
 Process/server fields:
 - `ports`: client-facing ports. These are also used for readiness/shutdown port checks.
-- `timeout`: max time (seconds) for readiness/shutdown port checks. Defaults to `1.0`.
+- `timeout`: max time (seconds) for each readiness/shutdown check. For processes, the same value also
+  bounds optional HTTP/gRPC probes and graceful child exit after the stop signal. Defaults to `1.0`.
 - `wait`: small sleep (seconds) between lifecycle steps.
 - `log`: per-runner log file used by process output redirection or server implementations.
 
@@ -89,7 +93,7 @@ Service fields:
 - `readiness`: optional list of startup readiness checks. Supported kind is `tcp`, which requires
   explicit `host` and `port`.
 
-Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into HTTP and gRPC readiness checks that run after TCP readiness succeeds. Services do not get automatic TCP readiness/shutdown checks, but can opt into TCP startup readiness for externally managed dependencies. HTTP readiness paths must be path-only values, such as `/test/readyz`; absolute URLs and scheme-relative URLs are rejected.
+Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into HTTP and gRPC readiness checks that run after TCP readiness succeeds. HTTP readiness sends a plain HTTP `GET` without configurable request headers and is ready only when the final response is 2xx. gRPC readiness uses the standard health `Check` over an insecure channel and is ready only for `SERVING`. Non-ready responses are retried until the process timeout elapses. Services do not get automatic TCP readiness/shutdown checks, but can opt into TCP startup readiness for externally managed dependencies. HTTP readiness paths must be path-only values, such as `/test/readyz`; absolute URLs and scheme-relative URLs are rejected.
 
 > [!WARNING]
 > TCP readiness and shutdown checks only prove that a TCP port opened or closed. HTTP and gRPC readiness are process-only. Service readiness is TCP-only and should target the dependency endpoint that must be reachable before managed servers/processes start.
@@ -108,12 +112,19 @@ Nonnative.start
 Nonnative.stop
 ```
 
-`Nonnative.start` starts services first, then servers and processes. `Nonnative.stop` stops processes and servers first, then services. If startup fails, Nonnative rolls back runners that already started and raises `Nonnative::StartError`; shutdown failures raise `Nonnative::StopError`.
+`Nonnative.start` runs ordered tiers: service lifecycle calls and optional readiness checks complete,
+then server lifecycle and readiness checks complete, then process lifecycle and readiness checks run.
+A failed service readiness check prevents later tiers; other collected startup errors trigger rollback
+after the attempted tiers finish. `Nonnative.stop` reverses the tiers: processes, servers, then
+services. Model dependencies in that direction; a managed server can satisfy a process dependency,
+but a server cannot wait on a managed process. Startup failures raise `Nonnative::StartError`, and
+shutdown failures raise `Nonnative::StopError`.
 
-> [!NOTE]
-> `Nonnative.start` / `Nonnative.stop` manage one lifecycle for the current pool.
-> Call `Nonnative.clear` before reconfiguring Nonnative or starting a new lifecycle in the same Ruby process.
-> `Nonnative.clear` clears memoized configuration, logger, observability client, and pool.
+> [!WARNING]
+> `Nonnative.clear` forgets the current pool; it does not stop live processes, server threads, or
+> proxies. To reuse the same Ruby process, call `Nonnative.stop`, then `Nonnative.clear`, configure
+> the next system, and call `Nonnative.start`. `clear` also clears the memoized configuration,
+> logger, and observability client.
 
 ### 🧩 Test framework setup
 
@@ -167,6 +178,10 @@ response = Nonnative.observability.health(
 expect(response.code).to eq(200)
 ```
 
+HTTP error statuses are returned as response objects so callers can inspect `.code` and `.body`.
+Request timeouts and broken connections raise their RestClient exceptions; observability requests are
+not retried automatically.
+
 `Nonnative.grpc_health` is a helper for the standard gRPC health checking protocol:
 
 ```ruby
@@ -180,6 +195,10 @@ health = Nonnative.grpc_health(
 expect(health.serving?).to eq(true)
 ```
 
+The helper always uses an insecure plaintext gRPC channel. Pass `service: ''` or `nil` to check the
+overall server. `check` returns the full `HealthCheckResponse` and propagates gRPC failures, while
+`serving?` returns `false` for any non-`SERVING` status or gRPC failure.
+
 ### 🔑 Tokens
 
 `Nonnative.token` builds a signer for authenticating requests against a service under test. You pass the signing parameters directly (parsed from your own configuration); it is not coupled to any service's config format. The generated string is ready for `Nonnative::Header.auth_bearer`.
@@ -241,6 +260,32 @@ The repo’s own Cucumber suite also uses taxonomy tags to classify coverage:
 
 Requiring `nonnative` is enough; the Cucumber hooks and step definitions are installed lazily once Cucumber’s Ruby DSL is ready.
 
+#### 🥒 Public Cucumber steps
+
+The shipped steps are compatibility surface for downstream suites:
+
+- `When I start the system` starts immediately. For expected failures, pair
+  `When I attempt to start the system` with `Then starting the system should raise an error`, or use
+  the equivalent stop steps.
+- `Then I should see {string} as healthy` expects the configured health endpoint to return `200` and
+  a body containing neither the supplied service name nor `service unavailable`; `unhealthy` expects
+  `503` and a body identifying the service or `service unavailable`.
+- `Then the process {string} should consume less than {string} of memory` accepts values such as
+  `25mb` for a started process.
+- The two log steps search either a configured process log or an explicit file path for the requested
+  text: `Then I should see a log entry of {string} for process {string}` and
+  `Then I should see a log entry of {string} in the file {string}`.
+- `Given I set the proxy for service {string} to {string}` accepts `close_all`, `reset_peer`, `delay`,
+  `timeout`, `invalid_data`, `bandwidth`, `limit_data`, or `reset`; the reset action step is
+  `Then I should reset the proxy for service {string}`.
+
+```cucumber
+@manual
+Scenario: startup is expected to fail
+  When I attempt to start the system
+  Then starting the system should raise an error
+```
+
 ### ⚙️ Processes
 
 A process is some sort of command that you would run locally.
@@ -249,6 +294,12 @@ Programmatic `p.command` values must be callables that return a shell string or
 > [!TIP]
 > Prefer argv arrays for new process commands. Use shell strings only when you intentionally need shell parsing, expansion, or redirection.
 
+Managed processes inherit the Ruby parent's working directory and environment; loading YAML from a
+different directory does not change the child working directory. Relative command, config, log, and
+generated-output paths resolve from that inherited directory. Configured `environment` values are
+stringified and override variables with the same names while preserving the rest of the parent
+environment.
+
 Set it up programmatically:
 
 ```ruby
@@ -338,6 +389,10 @@ Nonnative.configure do |config|
 end
 ```
 
+On stop, Nonnative sends the configured signal (`INT` by default) and waits up to `timeout` for the
+child to exit. If it remains alive, Nonnative sends `KILL` and reports the stop as unsuccessful, so
+`Nonnative.stop` raises `Nonnative::StopError` even if the configured shutdown ports close.
+
 With cucumber you can also verify how much memory is used by the process:
 
 ```cucumber
@@ -465,8 +520,9 @@ 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`:
+To run multiple Rack services on one managed port, pass a non-empty `Rack::URLMap` mount map. Keys
+can be path prefixes beginning with `/` or host-qualified URLs; the mounted application receives the
+remaining `PATH_INFO`:
 
 ```ruby
 module Nonnative
@@ -541,6 +597,10 @@ 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 upstream scheme is always HTTPS. The proxy forwards the request path and query for `GET`, `HEAD`,
+`POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`, while removing proxy credentials plus `Host` and
+`Accept-Encoding` before the upstream request.
+
 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:
@@ -783,9 +843,28 @@ These proxies can simulate different situations. Available proxy kinds are:
 Custom proxy kinds can be registered through `Nonnative.proxies`:
 
 ```ruby
+class CustomProxy < Nonnative::Proxy
+  # Inherit #initialize(service), or call super from a custom initializer.
+  def start; end
+  def stop; end
+  def reset; end
+end
+
 Nonnative.proxies['custom'] = CustomProxy
+
+Nonnative.configure do |config|
+  config.service do |s|
+    s.name = 'dependency'
+    s.host = '127.0.0.1'
+    s.port = 12_345
+    s.proxy.kind = 'custom'
+  end
+end
 ```
 
+Custom proxies must accept the service configuration and implement `start`, `stop`, and `reset`;
+Nonnative invokes those methods during service lifecycle and pool reset.
+
 Only services support proxies. For `fault_injection`, keep the service `host`/`port` as the client-facing proxy endpoint and use nested `proxy.host`/`proxy.port` for the upstream target behind the proxy.
 When service readiness is configured for a proxied dependency, set the readiness `host`/`port` to the upstream dependency, not the client-facing proxy listener.
 
@@ -856,6 +935,10 @@ Clients connect to the service `host`/`port`, while the proxy forwards traffic t
 
 ###### 🧩 Fault Injection Services
 
+> [!WARNING]
+> Every proxy state change closes active client connections so that new connections observe the new
+> state. Apply the state before connecting, and reconnect after changing or resetting it.
+
 Set the proxy state programmatically:
 
 ```ruby
@@ -902,6 +985,11 @@ YAML `go:` configuration is for Go test binaries compiled with `go test -c`. It
 > [!IMPORTANT]
 > If `tools` is omitted or empty, Nonnative enables all Go tools: `prof`, `trace`, and `cover`. Provide a subset, such as `tools: [cover]`, to limit the generated `-test.*` flags.
 
+Create the configured `output` directory before starting Nonnative; the helper does not create it and
+the Go test binary must be able to write there. Artifact names include the executable basename
+without its extension, the command, and a random four-character suffix, for example
+`reports/your_binary-sub_command-Ab12-cpu.prof`.
+
 To get this to work you will need to create a `main_test.go` file with these contents:
 
 ```go

data/lib/nonnative/configuration.rb

@@ -60,14 +60,15 @@ module Nonnative
     # @return [Array<Nonnative::ConfigurationServer>] configured in-process servers
     attr_accessor :servers
 
-    # @return [Array<Nonnative::ConfigurationService>] configured services (proxy-only)
+    # @return [Array<Nonnative::ConfigurationService>] configured external dependencies
     attr_accessor :services
 
     # Loads a configuration file and appends its runners to this instance.
     #
-    # The file is loaded using safe YAML parsing. ERB is not evaluated,
-    # arbitrary object deserialization is not allowed, top-level attributes are copied onto this object,
-    # and runner sections are transformed into configuration runner objects.
+    # The file is loaded using safe YAML parsing. ERB and environment placeholders are not evaluated,
+    # arbitrary object deserialization is not allowed, and unknown structural keys may be ignored.
+    # Top-level supported attributes are copied onto this object, and runner sections are transformed
+    # into configuration runner objects.
     #
     # @param path [String] path to a configuration file (typically YAML)
     # @return [void]
@@ -108,8 +109,8 @@ module Nonnative
 
     # Adds a service configuration entry.
     #
-    # A "service" does not manage a Ruby thread or OS process; it exists so that a proxy can be started
-    # and controlled for an external dependency.
+    # A "service" represents an externally managed dependency. It does not manage a Ruby thread or OS
+    # process, but it can wait for TCP readiness and optionally control a proxy for the dependency.
     #
     # @yieldparam service [Nonnative::ConfigurationService]
     # @return [void]

data/lib/nonnative/configuration_process.rb

@@ -11,6 +11,8 @@ module Nonnative
   # @see Nonnative::Configuration
   # @see Nonnative::Process
   class ConfigurationProcess < ConfigurationRunner
+    # The child inherits the parent Ruby process's working directory.
+    #
     # @return [Proc] a callable that returns the command to execute
     #   as a shell string or argv array
     #   (e.g. `-> { "./bin/api" }` or `-> { ["./bin/api", "--port", "8080"] }`)
@@ -19,12 +21,15 @@ module Nonnative
     # @return [String, nil] signal name to use for stopping (defaults to `"INT"` when not set)
     attr_accessor :signal
 
-    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close (defaults to `1.0`)
+    # @return [Numeric] timeout (seconds) independently applied to child exit, port checks, and each
+    #   optional HTTP/gRPC readiness probe (defaults to `1.0`)
     attr_accessor :timeout
 
     # @return [String] log file path to append process stdout/stderr to
     attr_accessor :log
 
+    # Values are stringified and override matching variables in the inherited parent environment.
+    #
     # @return [Hash, nil] environment variables to pass to the spawned process
     attr_accessor :environment
 

data/lib/nonnative/configuration_readiness.rb

@@ -4,7 +4,9 @@ module Nonnative
   # Readiness check configuration for a managed process.
   #
   # Readiness is optional. When present, each check declares a `kind` and explicit endpoint details
-  # to poll after TCP readiness succeeds.
+  # to poll after TCP readiness succeeds. HTTP checks issue a plain unauthenticated GET and accept a
+  # final 2xx response. gRPC checks use the standard health Check over an insecure channel and accept
+  # only SERVING. Non-ready results are retried until the process timeout elapses.
   class ConfigurationReadiness
     KINDS = %w[http grpc].freeze
 

data/lib/nonnative/configuration_runner.rb

@@ -12,7 +12,7 @@ module Nonnative
   # @see Nonnative::ConfigurationServer
   # @see Nonnative::ConfigurationService
   class ConfigurationRunner
-    # Default bounded readiness/shutdown timeout for process and server runners.
+    # Default bounded lifecycle/readiness timeout for configured runners.
     DEFAULT_TIMEOUT = 1.0
 
     # @return [String, nil] runner name used for lookup (for example via `pool.process_by_name`)

data/lib/nonnative/configuration_service.rb

@@ -3,15 +3,15 @@
 module Nonnative
   # Service-specific configuration.
   #
-  # A "service" is proxy-only: it does not start a Ruby thread or OS process. It exists so Nonnative can
-  # start and control a proxy in front of an external dependency.
+  # A "service" represents an externally managed dependency. It does not start a Ruby thread or OS
+  # process. It can wait for TCP readiness and can optionally run a proxy in front of the dependency.
   #
   # Instances are usually created through {Nonnative::Configuration#service}.
   #
   # @see Nonnative::Configuration
   # @see Nonnative::Service
   class ConfigurationService < ConfigurationRunner
-    # @return [Integer] client-facing port used by the service proxy
+    # @return [Integer] client-facing dependency port, used as the listener when a proxy is enabled
     attr_accessor :port
 
     # @return [Numeric] readiness timeout (seconds) used when waiting for service readiness

data/lib/nonnative/error.rb

@@ -3,7 +3,8 @@
 module Nonnative
   # Parent error for all Nonnative errors.
   #
-  # Catch this error type if you want to handle any exception raised by this gem.
+  # Rescue this type to handle Nonnative-specific errors. Public APIs may also raise standard Ruby,
+  # dependency, filesystem, or transport exceptions that are not subclasses of this class.
   #
   # @see Nonnative::StartError
   # @see Nonnative::StopError

data/lib/nonnative/fault_injection_proxy.rb

@@ -37,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
+  #   - `rate`: positive throughput limit in KB/s used by {#bandwidth}; absent or non-positive
+  #     values forward at full speed
   #   - `bytes`: positive response byte limit used by {#limit_data}; absent or non-positive values
   #     use pass-through behavior
   #

data/lib/nonnative/go_executable.rb

@@ -20,6 +20,7 @@ module Nonnative
   # If `tools` is `nil` or empty, all tools (`prof`, `trace`, `cover`) are enabled.
   #
   # Parameter strings are parsed into argv words using shell-style quoting.
+  # The output directory must already exist and be writable; this helper does not create it.
   #
   # @example
   #   executable = Nonnative::GoExecutable.new(%w[prof cover], './svc.test', 'reports')
@@ -31,7 +32,7 @@ module Nonnative
   class GoExecutable
     # @param tools [Array<String>, nil] tool names to enable (see class docs)
     # @param exec [String] path to the compiled Go test binary
-    # @param output [String] output directory for generated files
+    # @param output [String] existing writable output directory for generated files
     def initialize(tools, exec, output)
       @tools = tools.nil? || tools.empty? ? %w[prof trace cover] : tools
       @exec = exec

data/lib/nonnative/grpc_health.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Nonnative
-  # Client helper for the standard gRPC health checking protocol.
+  # Client helper for the standard gRPC health checking protocol over an insecure plaintext channel.
+  # An empty or nil service name checks overall server health.
   class GRPCHealth
     NETWORK_ERRORS = [
       GRPC::BadStatus,
@@ -10,7 +11,7 @@ module Nonnative
 
     # @param host [String] gRPC server host
     # @param port [Integer] gRPC server port
-    # @param service [String] gRPC health service name
+    # @param service [String, nil] gRPC health service name, or empty/nil for overall server health
     # @param timeout [Numeric] default call timeout in seconds
     def initialize(host:, port:, service:, timeout: 1)
       @host = host
@@ -21,6 +22,8 @@ module Nonnative
 
     # Calls the gRPC health check endpoint.
     #
+    # gRPC status and network failures are propagated to the caller.
+    #
     # @param deadline [Time] gRPC deadline
     # @return [Grpc::Health::V1::HealthCheckResponse]
     def check(deadline: Time.now + timeout)
@@ -29,6 +32,8 @@ module Nonnative
 
     # Returns true when the gRPC health endpoint reports SERVING.
     #
+    # Returns `false` for non-SERVING responses and gRPC status/network failures.
+    #
     # @param deadline [Time] gRPC deadline
     # @return [Boolean]
     def serving?(deadline: Time.now + timeout)

data/lib/nonnative/http_server.rb

@@ -36,9 +36,10 @@ module Nonnative
   class HTTPServer < Nonnative::Server
     # Creates a Puma server for the given HTTP service and runner configuration.
     #
-    # @param http_service [#call, Hash<String, #call>] an HTTP service instance or mount map
+    # @param http_service [#call, Hash<String, #call>] an HTTP service instance or `Rack::URLMap`
+    #   mount map using path prefixes or host-qualified URLs
     # @param service [Nonnative::ConfigurationServer] server configuration
-    # @raise [ArgumentError] if `http_service` is an empty mount map
+    # @raise [ArgumentError] if `http_service` is an empty mount map or contains an invalid mount path
     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?

data/lib/nonnative/observability.rb

@@ -13,7 +13,9 @@ module Nonnative
   # - `/<name>/metrics`
   #
   # Requests are performed using {Nonnative::HTTPClient}, so callers may pass RestClient options
-  # such as `headers`, `open_timeout`, and `read_timeout`.
+  # such as `headers`, `open_timeout`, and `read_timeout`. HTTP error statuses are returned as response
+  # objects; timeouts and broken connections raise their RestClient exceptions. Requests are not
+  # retried automatically.
   #
   # @example
   #   Nonnative.configure do |config|

data/lib/nonnative/pool.rb

@@ -6,10 +6,11 @@ module Nonnative
   # A pool is created when {Nonnative.start} is called and is accessible via {Nonnative.pool}.
   #
   # Lifecycle order is important:
-  # - On start: services first, then servers/processes (in parallel port-check threads)
-  # - On stop: processes/servers first, then services
+  # - On start: services, then servers, then processes; each tier completes readiness before the next
+  # - On stop: processes, then servers, then services
   #
-  # Readiness and shutdown are determined via TCP port checks ({Nonnative::Ports#open?} / {Nonnative::Ports#closed?}).
+  # Readiness uses TCP port checks plus optional process HTTP/gRPC probes and optional service TCP
+  # checks. Shutdown uses configured TCP port checks.
   #
   # @see Nonnative.start
   # @see Nonnative.stop
@@ -25,9 +26,9 @@ module Nonnative
 
     # 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. Each readiness failure is described with the runner and, for a process
-    # that exited early, its termination detail.
+    # Externally managed services are handled first and checked for opt-in readiness. Servers are then
+    # started and checked for readiness, followed by processes. Each readiness failure is described
+    # with the runner and, for a process that exited early, its termination detail.
     #
     # @return [Array<String>] lifecycle and readiness-check errors collected while starting
     def start
@@ -45,7 +46,8 @@ module Nonnative
 
     # 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).
+    # Processes and servers are stopped first and checked for shutdown, then service proxies are
+    # stopped when configured.
     #
     # @return [Array<String>] lifecycle and shutdown-check errors collected while stopping
     def stop

data/lib/nonnative/ports.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Nonnative
-  # Performs aggregate TCP readiness/shutdown checks for all configured runner ports.
+  # Performs aggregate readiness and shutdown checks for a configured runner.
   #
-  # A runner is considered ready only when every configured port is open, and stopped only when every
-  # configured port is closed.
+  # A runner is considered ready only when every configured port is open and every configured
+  # HTTP/gRPC readiness probe reports ready, and stopped only when every configured port is closed.
   #
   # @see Nonnative::Port
   class Ports
@@ -15,7 +15,8 @@ module Nonnative
       @readiness = readiness_probes
     end
 
-    # Returns whether all configured ports become connectable before their timeouts elapse.
+    # Returns whether all configured ports become connectable and all configured HTTP/gRPC readiness
+    # probes report ready before their timeouts elapse.
     #
     # @return [Boolean]
     def open?

data/lib/nonnative/process.rb

@@ -6,7 +6,8 @@ module Nonnative
   # A process runner:
   # - spawns a child process using the configured command and environment,
   # - waits briefly (via the runner `wait`), and
-  # - participates in readiness/shutdown via TCP port checks orchestrated by {Nonnative::Pool}.
+  # - participates in TCP readiness/shutdown checks plus optional HTTP/gRPC readiness probes
+  #   orchestrated by {Nonnative::Pool}.
   #
   # The underlying configuration is a {Nonnative::ConfigurationProcess}.
   #
@@ -46,6 +47,8 @@ module Nonnative
     # Stops the process if it is running.
     #
     # The process is signalled using the configured signal (defaults to `INT` when not set).
+    # If it does not exit before the configured timeout, it is killed and the returned success value
+    # is `false`; {Nonnative.stop} reports that outcome as a {Nonnative::StopError}.
     #
     # @return [Array<(Integer, Boolean)>]
     #   a tuple of:

data/lib/nonnative/proxy.rb

@@ -10,7 +10,8 @@ module Nonnative
   # implementation-specific; for example {Nonnative::FaultInjectionProxy#host} and
   # {Nonnative::FaultInjectionProxy#port} return the upstream target behind the proxy.
   #
-  # Concrete proxies typically implement these public methods:
+  # Custom proxies must accept the service configuration in `initialize` and implement these public
+  # methods, which the service and pool invoke unconditionally:
   # - `start`: begin proxying (bind/listen, start threads, etc)
   # - `stop`: stop proxying and release resources
   # - `reset`: return proxy behavior to a healthy/default state

data/lib/nonnative/runner.rb

@@ -8,7 +8,7 @@ module Nonnative
   #
   # - {Nonnative::Process} for OS-level child processes
   # - {Nonnative::Server} for in-process Ruby servers (threads)
-  # - {Nonnative::Service} for proxy-only external dependencies
+  # - {Nonnative::Service} for externally managed dependencies with optional readiness/proxying
   #
   # @see Nonnative::Process
   # @see Nonnative::Server

data/lib/nonnative/service.rb

@@ -3,9 +3,9 @@
 module Nonnative
   # Runtime runner for an external dependency.
   #
-  # A service runner does not manage an OS process or Ruby thread. It exists so Nonnative can manage
-  # a proxy lifecycle (start/stop/reset) for an external service that is managed elsewhere (for example
-  # a database running in Docker).
+  # A service runner does not manage an OS process or Ruby thread. It represents a dependency managed
+  # elsewhere (for example a database running in Docker), supports optional TCP readiness, and manages
+  # an optional proxy lifecycle (start/stop/reset).
   #
   # The underlying configuration is a {Nonnative::ConfigurationService}.
   #

data/lib/nonnative/socket_pair.rb

@@ -4,7 +4,9 @@ module Nonnative
   # Base socket-pair implementation used by TCP proxies.
   #
   # A socket-pair connects an accepted local socket to a remote upstream socket and forwards bytes
-  # in both directions until one side closes.
+  # in both directions. When one direction reaches EOF (for example a client that half-closes its
+  # write side after sending a request), the paired write side is closed and the other direction
+  # keeps forwarding until it too ends, so an in-flight response is delivered rather than dropped.
   #
   # This is used by {Nonnative::FaultInjectionProxy} to implement pass-through forwarding, and is
   # subclassed to inject failures (close immediately, delay reads, corrupt writes, etc).
@@ -31,12 +33,14 @@ module Nonnative
     def connect(local_socket)
       @local_socket = local_socket
       @remote_socket = create_remote_socket
+      @open = [@local_socket, @remote_socket]
 
       loop do
-        ready = select([@local_socket, @remote_socket], nil, nil)
+        ready = select(@open, nil, nil)
 
         break if pipe?(ready, @local_socket, @remote_socket)
         break if pipe?(ready, @remote_socket, @local_socket)
+        break if @open.empty?
       end
     ensure
       Nonnative.logger.info "finished connect for local socket '#{@local_socket.inspect}' and '#{@remote_socket&.inspect}' for 'socket_pair'"
@@ -68,6 +72,10 @@ module Nonnative
 
     # Pipes data from `source_socket` to `destination_socket` when the source is readable.
     #
+    # On EOF the source is half-closed rather than terminating the whole connection: the destination
+    # write side is closed and the source is removed from the forwarding set, so the opposite
+    # direction keeps forwarding until it also ends.
+    #
     # @param ready [Array<Array<IO>>] the result from `select`
     # @param source_socket [IO] readable side
     # @param destination_socket [IO] writable side
@@ -75,7 +83,7 @@ module Nonnative
     def pipe?(ready, source_socket, destination_socket)
       if ready[0].include?(source_socket)
         data = read(source_socket)
-        return true if data.empty?
+        return half_close(source_socket, destination_socket) if data.empty?
 
         write destination_socket, data
       end
@@ -104,6 +112,21 @@ module Nonnative
       socket.write(data)
     end
 
+    # Half-closes one direction after its source reaches EOF: closes the destination write side and
+    # removes the source from the forwarding set, so the opposite direction keeps forwarding.
+    #
+    # @param source_socket [IO] the side that reached EOF
+    # @param destination_socket [IO] the paired side whose write half is closed
+    # @return [false] so the forwarding loop continues until both directions have ended
+    def half_close(source_socket, destination_socket)
+      @open.delete(source_socket)
+      destination_socket.close_write
+
+      false
+    rescue IOError, SystemCallError
+      false
+    end
+
     def close_socket(socket)
       return if socket.nil? || socket.closed?
 

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -188,7 +188,7 @@ module Nonnative
     # Use this when passing a command string directly to `spawn`.
     #
     # @param tools [Array<String>] enabled tool names (e.g. `["prof", "trace", "cover"]`)
-    # @param output [String] directory where outputs should be written
+    # @param output [String] existing writable directory where outputs should be written
     # @param exec [String] the test binary (or wrapper) to execute
     # @param cmd [String] the command argument passed to the test binary
     # @param params [Array<String>] extra parameter strings for the command
@@ -202,7 +202,7 @@ module Nonnative
     # Use this when passing argv entries directly to `spawn`.
     #
     # @param tools [Array<String>] enabled tool names (e.g. `["prof", "trace", "cover"]`)
-    # @param output [String] directory where outputs should be written
+    # @param output [String] existing writable directory where outputs should be written
     # @param exec [String] the test binary (or wrapper) to execute
     # @param cmd [String] the command argument passed to the test binary
     # @param params [Array<String>] extra parameter strings for the command
@@ -237,7 +237,7 @@ module Nonnative
     #
     # @param host [String] gRPC server host
     # @param port [Integer] gRPC server port
-    # @param service [String] gRPC health service name
+    # @param service [String, nil] gRPC health service name, or empty/nil for overall server health
     # @param timeout [Numeric] default call timeout in seconds
     # @return [Nonnative::GRPCHealth]
     def grpc_health(host:, port:, service:, timeout: 1) = Nonnative::GRPCHealth.new(host: host, port: port, service: service, timeout: timeout)
@@ -265,7 +265,8 @@ module Nonnative
 
     # Starts all configured services, servers, and processes, and waits for readiness.
     #
-    # Readiness is determined by attempting to connect to each runner's configured host/ports.
+    # Readiness is determined by port checks, plus optional process HTTP/gRPC readiness and optional
+    # service TCP readiness.
     #
     # @return [void]
     # @raise [Nonnative::StartError] if one or more runners fail to start or become ready in time
@@ -325,6 +326,8 @@ module Nonnative
 
     # Clears the memoized pool instance.
     #
+    # This does not stop runners owned by the pool. Call {Nonnative.stop} before clearing a live pool.
+    #
     # @return [void]
     def clear_pool
       @pool = nil
@@ -332,8 +335,9 @@ module Nonnative
 
     # Clears memoized configuration, logger, observability client, and pool.
     #
-    # Call this before reconfiguring Nonnative or starting a new lifecycle in the same Ruby process.
-    # `start`/`stop` are intended to manage one lifecycle for the current pool.
+    # This does not stop processes, server threads, or proxies. To reconfigure in the same Ruby
+    # process, call {Nonnative.stop}, then `clear`, configure the next system, and call
+    # {Nonnative.start}.
     #
     # @return [void]
     def clear

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.29.0
+  version: 3.30.0
 platform: ruby
 authors:
 - Alejandro Falkowski