nonnative 2.23.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53ded0979e2825948ce16066839a784ef26ee94385d78ba2f557da5ce9e4424a
-  data.tar.gz: 5dbceda50fe7dc82c109a3fec1c4af041a27026a438bb7c51eee52344be13ab1
+  metadata.gz: 3e20a9fa436249c182c4fc90bfaaeeaed91035899d31340eba35d1f4208a31ab
+  data.tar.gz: c68e618e0a2a48cf9958210a8200a96c2aff7c0406eeec332bea01cf9290e860
 SHA512:
-  metadata.gz: d2952d70183482b382509e0088fc5e2c8e4b53a320ddb00d57e9237961355f39bc48828c26779568318bad54552ad373bd341349d2cbb77cedd5dbc0fa84f6c0
-  data.tar.gz: fb7c6404f30ec98145e168c919ad4de609eb4a11436bf0c5f8d8a7832e93bc9fad55c8cd4b820242bdfc9f928640dcd3577b83cf54dd98520c08046d12bd71f2
+  metadata.gz: c228d28fa41f6e9d526c107feedb4aebfed673aca7b47d7262913db7ceb04468772a1ca068fd4cf696a46a50fc52f01f3dfb9934547945c6ef78b03298cd6cc4
+  data.tar.gz: 60ebed64503ac1505ccd4398330290627600f14519d40389ba96a5e02189762e7d54b314ee98fdd31220f9aba560fc6e09ad7340ffc3925b3f3359747bcf0c0f

data/.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 jobs:
   build:
     docker:
-      - image: alexfalkowski/ruby:3.12
+      - image: alexfalkowski/ruby:3.14
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -35,7 +35,7 @@ jobs:
     resource_class: arm.large
   sync:
     docker:
-      - image: alexfalkowski/release:8.11
+      - image: alexfalkowski/release:8.14
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -46,7 +46,7 @@ jobs:
     resource_class: arm.large
   version:
     docker:
-      - image: alexfalkowski/release:8.11
+      - image: alexfalkowski/release:8.14
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -58,7 +58,7 @@ jobs:
     resource_class: arm.large
   wait-all:
     docker:
-      - image: alexfalkowski/ruby:3.12
+      - image: alexfalkowski/ruby:3.14
     steps:
       - run: echo "all applicable jobs finished"
     resource_class: arm.large

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (2.23.0)
+    nonnative (3.1.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)
@@ -30,7 +30,7 @@ GEM
     config (5.6.1)
       deep_merge (~> 1.2, >= 1.2.1)
       ostruct
-    cucumber (11.0.0)
+    cucumber (11.1.0)
       base64 (~> 0.2)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 12)
@@ -64,24 +64,24 @@ GEM
     get_process_mem (1.0.0)
       bigdecimal (>= 2.0)
       ffi (~> 1.0)
-    google-protobuf (4.34.1-x86_64-darwin)
+    google-protobuf (4.35.0-x86_64-darwin)
       bigdecimal
       rake (~> 13.3)
-    google-protobuf (4.34.1-x86_64-linux-gnu)
+    google-protobuf (4.35.0-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    googleapis-common-protos-types (1.22.0)
+    googleapis-common-protos-types (1.23.0)
       google-protobuf (~> 4.26)
-    grpc (1.80.0-x86_64-darwin)
+    grpc (1.81.0-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.80.0-x86_64-linux-gnu)
+    grpc (1.81.0-x86_64-linux-gnu)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
     http-accept (1.7.0)
     http-cookie (1.1.6)
       domain_name (~> 0.5)
-    json (2.19.5)
+    json (2.19.8)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -101,7 +101,7 @@ GEM
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
-    puma (7.2.0)
+    puma (7.2.1)
       nio4r (~> 2.0)
     racc (1.8.1)
     rack (3.2.6)
@@ -124,7 +124,7 @@ GEM
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
-    retriable (3.4.1)
+    retriable (3.8.0)
     rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -146,7 +146,7 @@ GEM
     rspec-support (3.13.7)
     rspec-wait (1.0.2)
       rspec (>= 3.4)
-    rubocop (1.86.2)
+    rubocop (1.87.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/nonnative.svg)](https://badge.fury.io/rb/nonnative)
 [![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)
 
-# Nonnative
+# 🧪 Nonnative
 
 Nonnative is a Ruby-first harness for end-to-end testing of systems implemented in other languages.
 
@@ -15,7 +15,10 @@ It helps you:
 
 Once started, you can test however you like (TCP, HTTP, gRPC, etc).
 
-## Installation
+## 📦 Installation
+
+> [!IMPORTANT]
+> Nonnative currently supports Ruby `>= 4.0.0` and `< 5.0.0`.
 
 Add this line to your application's Gemfile:
 
@@ -35,12 +38,15 @@ Or install it yourself as:
 gem install nonnative
 ```
 
-## Usage
+## 🚀 Usage
 
 Nonnative is configured via `Nonnative.configure` (programmatic) or `config.load_file(...)` (YAML).
 YAML configuration is loaded as data only: ERB is not evaluated and arbitrary Ruby objects are not
 deserialized.
 
+> [!CAUTION]
+> Treat YAML configuration as plain data. ERB is not evaluated and arbitrary Ruby object tags are rejected.
+
 High-level configuration fields:
 - `version`: configuration version (example: `"1.0"`).
 - `name`: logical system name (used by `Nonnative.observability` for `/<name>/healthz`, etc).
@@ -52,18 +58,68 @@ High-level configuration fields:
 
 Common runner fields:
 - `name`: runner name used for lookup.
-- `host`/`port`: client-facing address. `host` defaults to `127.0.0.1`. For processes and servers, this address is also used for readiness/shutdown port checks. When a `fault_injection` proxy is enabled, this is the endpoint your tests/clients should hit.
+- `host`: client-facing host. Defaults to `127.0.0.1`.
 
 Process/server fields:
+- `ports`: client-facing ports. These are also used for readiness/shutdown port checks. When a `fault_injection` proxy is enabled, clients should hit the first configured port.
 - `timeout`: max time (seconds) for readiness/shutdown port checks.
 - `wait`: small sleep (seconds) between lifecycle steps.
 - `log`: per-runner log file used by process output redirection or server implementations.
 
+Service fields:
+- `port`: client-facing proxy port. Services do not get TCP readiness/shutdown checks from Nonnative.
+
 For `fault_injection`, the nested `proxy.host`/`proxy.port` describe the upstream target behind the proxy. Nested `proxy.host` also defaults to `127.0.0.1`. In-process server implementations typically bind there via `proxy.host` / `proxy.port`.
 
-Nonnative readiness and shutdown checks are TCP-only. Configure ports that are dedicated to the test run; if another process is already listening on the same `host`/`port`, results are undefined.
+> [!IMPORTANT]
+> When a proxy is enabled, tests and clients connect to the runner `host` and client-facing endpoint (`ports` first entry for processes/servers, `port` for services); the nested `proxy.host`/`proxy.port` is the upstream target behind the proxy.
+
+Nonnative readiness and shutdown checks are TCP-only. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined.
+
+> [!WARNING]
+> Readiness and shutdown checks only prove that a TCP port opened or closed. They do not verify HTTP status, gRPC health, schema readiness, migrations, or application-specific health.
+
+Start and stop Nonnative around the test scope that should own the configured runners:
+
+```ruby
+require 'nonnative'
+
+Nonnative.configure do |config|
+  config.load_file('configuration.yml')
+end
+
+Nonnative.start
+# run tests...
+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`.
+
+> [!NOTE]
+> `Nonnative.clear` clears memoized configuration, logger, observability client, and pool. Use it before reconfiguring Nonnative in the same Ruby process.
 
-### Lifecycle strategies (Cucumber integration)
+### 📈 Observability
+
+`Nonnative.observability` is an HTTP client for common service endpoints under the configured `name` and `url`:
+
+- `health(...)`: calls `/<name>/healthz`.
+- `liveness(...)`: calls `/<name>/livez`.
+- `readiness(...)`: calls `/<name>/readyz`.
+- `metrics(...)`: calls `/<name>/metrics`.
+
+Each method accepts RestClient options such as `headers`, `open_timeout`, and `read_timeout`.
+
+```ruby
+response = Nonnative.observability.health(
+  headers: { content_type: :json, accept: :json },
+  open_timeout: 2,
+  read_timeout: 2
+)
+
+expect(response.code).to eq(200)
+```
+
+### 🔁 Lifecycle strategies (Cucumber integration)
 
 Nonnative ships Cucumber hooks (when loaded) that support these tags/strategies:
 - `@startup`: start before scenario; stop after scenario
@@ -84,7 +140,7 @@ 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.
 
-If you want “start once per test run”, require:
+If you want "start once per test run", require:
 
 ```ruby
 require 'nonnative/startup'
@@ -92,11 +148,13 @@ require 'nonnative/startup'
 
 This calls `Nonnative.start` immediately and registers an `at_exit` stop.
 
-### Processes
+### ⚙️ Processes
 
 A process is some sort of command that you would run locally.
-Commands can be strings or argv arrays. String commands preserve legacy shell semantics, while argv arrays
-avoid shell interpretation and are preferred for new configuration.
+Programmatic `p.command` values must be callables that return a shell string or an argv array. YAML `command` values can be scalars or lists and are wrapped internally. String commands preserve legacy shell semantics, while argv arrays avoid shell interpretation and are preferred for new configuration.
+
+> [!TIP]
+> Prefer argv arrays for new process commands. Use shell strings only when you intentionally need shell parsing, expansion, or redirection.
 
 Set it up programmatically:
 
@@ -114,7 +172,7 @@ Nonnative.configure do |config|
     p.command = -> { ['features/support/bin/start', '12_321'] }
     p.timeout = 5
     p.wait = 0.1
-    p.port = 12_321
+    p.ports = [12_321]
     p.log = '12_321.log'
     p.signal = 'INT' # Possible values are described in Signal.list.keys.
     p.environment = { # Pass environment variables to process.
@@ -127,7 +185,7 @@ Nonnative.configure do |config|
     p.command = -> { ['features/support/bin/start', '12_322'] }
     p.timeout = 0.5
     p.wait = 0.1
-    p.port = 12_322
+    p.ports = [12_322]
     p.log = '12_322.log'
   end
 end
@@ -148,7 +206,8 @@ processes:
       - "12_321"
     timeout: 5
     wait: 1
-    port: 12321
+    ports:
+      - 12321
     log: 12_321.log
     signal: INT # Possible values are described in Signal.list.keys.
     environment: # Pass environment variables to process.
@@ -160,7 +219,8 @@ processes:
       - "12_322"
     timeout: 5
     wait: 1
-    port: 12322
+    ports:
+      - 12322
     log: 12_322.log
 ```
 
@@ -180,9 +240,9 @@ With cucumber you can also verify how much memory is used by the process:
 Then the process 'start_1' should consume less than '25mb' of memory
 ```
 
-### Servers
+### 🖥️ Servers
 
-A server is a dependency to some external API.
+A server is an in-process Ruby fake or helper server that Nonnative starts in a thread. Use servers for dependencies that are easiest to model inside the test process, such as small TCP, HTTP, or gRPC fakes.
 
 Define your server:
 
@@ -231,7 +291,7 @@ Nonnative.configure do |config|
     s.name = 'server_1'
     s.klass = Nonnative::TCPServer
     s.timeout = 1
-    s.port = 12_323
+    s.ports = [12_323]
     s.log = 'server_1.log'
   end
 
@@ -239,7 +299,7 @@ Nonnative.configure do |config|
     s.name = 'server_2'
     s.klass = Nonnative::TCPServer
     s.timeout = 1
-    s.port = 12_324
+    s.ports = [12_324]
     s.log = 'server_2.log'
   end
 end
@@ -257,13 +317,15 @@ servers:
     name: server_1
     class: Nonnative::TCPServer
     timeout: 1
-    port: 12323
+    ports:
+      - 12323
     log: server_1.log
   -
     name: server_2
     class: Nonnative::TCPServer
     timeout: 1
-    port: 12324
+    ports:
+      - 12324
     log: server_2.log
 ```
 
@@ -277,7 +339,7 @@ Nonnative.configure do |config|
 end
 ```
 
-#### HTTP
+#### 🌐 HTTP
 
 Define your server:
 
@@ -314,7 +376,7 @@ Nonnative.configure do |config|
     s.name = 'http_server_1'
     s.klass = Nonnative::Features::HTTPServer
     s.timeout = 1
-    s.port = 4567
+    s.ports = [4567]
     s.log = 'http_server_1.log'
   end
 end
@@ -332,7 +394,8 @@ servers:
     name: http_server_1
     class: Nonnative::Features::HTTPServer
     timeout: 1
-    port: 4567
+    ports:
+      - 4567
     log: http_server_1.log
 ```
 
@@ -346,9 +409,9 @@ Nonnative.configure do |config|
 end
 ```
 
-##### Proxy
+##### 🔀 Proxy
 
-The system allows you to define a http proxy for external systems, e.g api.github.com
+The system allows you to define an HTTP proxy for external systems, e.g. `api.github.com`.
 
 Define your server:
 
@@ -379,7 +442,7 @@ Nonnative.configure do |config|
     s.name = 'http_server_proxy'
     s.klass = Nonnative::Features::HTTPProxyServer
     s.timeout = 1
-    s.port = 4567
+    s.ports = [4567]
     s.log = 'http_server_proxy.log'
   end
 end
@@ -397,7 +460,8 @@ servers:
     name: http_server_proxy
     class: Nonnative::Features::HTTPProxyServer
     timeout: 1
-    port: 4567
+    ports:
+      - 4567
     log: http_server_proxy.log
 ```
 
@@ -411,7 +475,7 @@ Nonnative.configure do |config|
 end
 ```
 
-#### gRPC
+#### 📡 gRPC
 
 Define your server:
 
@@ -448,7 +512,7 @@ Nonnative.configure do |config|
     s.name = 'grpc_server_1'
     s.klass = Nonnative::Features::GRPCServer
     s.timeout = 1
-    s.port = 9002
+    s.ports = [9002]
     s.log = 'grpc_server_1.log'
   end
 end
@@ -466,7 +530,8 @@ servers:
     name: grpc_server_1
     class: Nonnative::Features::GRPCServer
     timeout: 1
-    port: 9002
+    ports:
+      - 9002
     log: grpc_server_1.log
 ```
 
@@ -480,10 +545,12 @@ Nonnative.configure do |config|
 end
 ```
 
-### Services
+### 🧩 Services
 
 A service is an external dependency to your system that you **do not** want Nonnative to start (no OS process, no Ruby thread). Services are primarily useful when paired with proxies, because they let you inject failures into dependencies that are managed elsewhere (e.g. a DB running in Docker).
 
+Services do not get process lifecycle management or TCP readiness/shutdown checks from Nonnative. They only provide a named runner and optional proxy lifecycle for a dependency that another tool already manages.
+
 Set it up programmatically:
 
 ```ruby
@@ -537,16 +604,25 @@ Nonnative.configure do |config|
 end
 ```
 
-#### Proxies
+#### 🕸️ Proxies
 
-We allow different proxies to be configured. These proxies can be used to simulate all kind of situations. The proxies that can be configured are:
+These proxies can simulate different situations. Available proxy kinds are:
 
 - `none` (this is the default)
 - `fault_injection`
 
-For `fault_injection`, keep the runner `host`/`port` as the client-facing endpoint and use nested `proxy.host`/`proxy.port` for the upstream target behind the proxy.
+> [!WARNING]
+> Unknown proxy kinds fall back to `none`. If fault injection is not taking effect, check the `kind` spelling or register the custom kind before loading the configuration.
+
+Custom proxy kinds can be registered through `Nonnative.proxies`:
+
+```ruby
+Nonnative.proxies['custom'] = CustomProxy
+```
 
-##### Proxies Processes
+For `fault_injection`, keep the runner `host` and first `ports` entry as the client-facing endpoint and use nested `proxy.host`/`proxy.port` for the upstream target behind the proxy.
+
+##### ⚙️ Process Proxies
 
 Add this to an existing process configuration:
 
@@ -561,7 +637,7 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.host = '127.0.0.1'
-    p.port = 20_000
+    p.ports = [20_000]
 
     p.proxy = {
       kind: 'fault_injection',
@@ -587,7 +663,8 @@ log: nonnative.log
 processes:
   -
     host: 127.0.0.1
-    port: 20000
+    ports:
+      - 20000
     proxy:
       kind: fault_injection
       host: 127.0.0.1
@@ -598,7 +675,7 @@ processes:
         delay: 5
 ```
 
-##### Proxies Servers
+##### 🖥️ Server Proxies
 
 Add this to an existing server configuration:
 
@@ -613,7 +690,7 @@ Nonnative.configure do |config|
 
   config.server do |s|
     s.host = '127.0.0.1'
-    s.port = 20_000
+    s.ports = [20_000]
 
     s.proxy = {
       kind: 'fault_injection',
@@ -639,7 +716,8 @@ log: nonnative.log
 servers:
   -
     host: 127.0.0.1
-    port: 20000
+    ports:
+      - 20000
     proxy:
       kind: fault_injection
       host: 127.0.0.1
@@ -650,7 +728,7 @@ servers:
         delay: 5
 ```
 
-##### Proxies Services
+##### 🧩 Service Proxies
 
 Add this to an existing service configuration:
 
@@ -704,17 +782,17 @@ services:
         delay: 5
 ```
 
-##### Fault Injection
+##### 🧪 Fault Injection
 
 The `fault_injection` proxy allows you to simulate failures by injecting them. We currently support the following:
 
-Clients connect to the runner `host`/`port`, while the proxy forwards traffic to nested `proxy.host`/`proxy.port`.
+Clients connect to the runner `host` and client-facing endpoint, while the proxy forwards traffic to nested `proxy.host`/`proxy.port`.
 
 - `close_all` - Closes the socket as soon as it connects.
-- `delay` - This delays the communication between the connection. Default is 2 secs can be configured through options.
-- `invalid_data` - This takes the input and rearranges it to produce invalid data.
+- `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through options.
+- `invalid_data` - Forwards client requests unchanged, then corrupts upstream responses before they reach the client.
 
-###### Fault Injection Processes
+###### ⚙️ Fault Injection Processes
 
 Set it up programmatically:
 
@@ -733,7 +811,7 @@ Given I set the proxy for process 'process_1' to 'close_all'
 Then I should reset the proxy for process 'process_1'
 ```
 
-###### Fault Injection Servers
+###### 🖥️ Fault Injection Servers
 
 Set it up programmatically:
 
@@ -752,7 +830,7 @@ Given I set the proxy for server 'server_1' to 'close_all'
 Then I should reset the proxy for server 'server_1'
 ```
 
-###### Fault Injection Services
+###### 🧩 Fault Injection Services
 
 Set it up programmatically:
 
@@ -771,7 +849,7 @@ Given I set the proxy for service 'service_1' to 'close_all'
 Then I should reset the proxy for service 'service_1'
 ```
 
-### Go
+### 🐹 Go
 
 As we love using Go as a language for services we have added support to start binaries with defined parameters.
 
@@ -782,7 +860,7 @@ Nonnative.configure do |config|
   config.process do |p|
     p.name = 'go'
     p.command = -> { Nonnative.go_argv(%w[cover], 'reports', 'your_binary', 'sub_command', '-i file:.config/server.yml') }
-    p.port = 12_345
+    p.ports = [12_345]
   end
 end
 ```
@@ -791,6 +869,9 @@ Use `Nonnative.go_argv(...)` when a process should execute without shell interpr
 
 YAML `go:` configuration is for Go test binaries compiled with `go test -c`. It builds argv entries in this order: executable, optional `-test.*` profiling/trace/coverage flags, command, then parameters. Parameter strings are parsed into argv words with shell-style quoting, but the argv entries are executed without shell interpretation.
 
+> [!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.
+
 To get this to work you will need to create a `main_test.go` file with these contents:
 
 ```go
@@ -830,6 +911,7 @@ processes:
       parameters:
         - "-i file:.config/server.yml"
     timeout: 5
-    port: 8000
+    ports:
+      - 8000
     log: go.log
 ```

data/lib/nonnative/configuration.rb

@@ -19,7 +19,7 @@ module Nonnative
   #       p.name = 'api'
   #       p.command = -> { './bin/api' }
   #       p.host = '127.0.0.1'
-  #       p.port = 8080
+  #       p.ports = [8080, 9090]
   #       p.timeout = 10
   #       p.log = 'api.log'
   #     end
@@ -123,14 +123,14 @@ module Nonnative
 
     def add_processes(cfg)
       processes = cfg.processes || []
-      processes.each do |fd|
-        process do |d|
-          d.command = command(fd)
-          d.signal = fd.signal
-          d.environment = fd.environment
-          runner_attributes(d, fd)
-
-          proxy d, fd.proxy
+      processes.each do |loaded_process|
+        process do |process_config|
+          process_config.command = command(loaded_process)
+          process_config.signal = loaded_process.signal
+          process_config.environment = loaded_process.environment
+          runner_attributes(process_config, loaded_process)
+
+          assign_proxy(process_config, loaded_process.proxy)
         end
       end
     end
@@ -149,25 +149,25 @@ module Nonnative
 
     def add_servers(cfg)
       servers = cfg.servers || []
-      servers.each do |fd|
-        server do |s|
-          s.klass = Object.const_get(server_class_name(fd))
-          runner_attributes(s, fd)
+      servers.each do |loaded_server|
+        server do |server_config|
+          server_config.klass = Object.const_get(server_class_name(loaded_server))
+          runner_attributes(server_config, loaded_server)
 
-          proxy s, fd.proxy
+          assign_proxy(server_config, loaded_server.proxy)
         end
       end
     end
 
     def add_services(cfg)
       services = cfg.services || []
-      services.each do |fd|
-        service do |s|
-          s.name = fd.name
-          s.host = fd.host if fd.host
-          s.port = fd.port
+      services.each do |loaded_service|
+        service do |service_config|
+          service_config.name = loaded_service.name
+          service_config.host = loaded_service.host if loaded_service.host
+          assign_service_port(service_config, loaded_service)
 
-          proxy s, fd.proxy
+          assign_proxy(service_config, loaded_service.proxy)
         end
       end
     end
@@ -182,24 +182,38 @@ module Nonnative
       runner.timeout = loaded.timeout
       runner.wait = loaded.wait if loaded.wait
       runner.host = loaded.host if loaded.host
-      runner.port = loaded.port
+      assign_ports(runner, loaded)
       runner.log = loaded.log if loaded.respond_to?(:log)
     end
 
-    def proxy(runner, proxy)
-      return unless proxy
+    def assign_ports(runner, loaded)
+      values = loaded.to_h
+      raise ArgumentError, "Use 'ports' instead of 'port' for runner '#{loaded.name}'" if values.key?(:port) || values.key?('port')
 
-      p = {
-        kind: proxy.kind,
-        port: proxy.port,
-        log: proxy.log,
-        options: proxy.options
+      runner.ports = loaded.ports if loaded.ports
+    end
+
+    def assign_service_port(service, loaded)
+      values = loaded.to_h
+      raise ArgumentError, "Use 'port' instead of 'ports' for service '#{loaded.name}'" if values.key?(:ports) || values.key?('ports')
+
+      service.port = loaded.port if loaded.port
+    end
+
+    def assign_proxy(runner, loaded_proxy)
+      return unless loaded_proxy
+
+      proxy_attributes = {
+        kind: loaded_proxy.kind,
+        port: loaded_proxy.port,
+        log: loaded_proxy.log,
+        options: loaded_proxy.options
       }
 
-      p[:host] = proxy.host if proxy.host
-      p[:wait] = proxy.wait if proxy.wait
+      proxy_attributes[:host] = loaded_proxy.host if loaded_proxy.host
+      proxy_attributes[:wait] = loaded_proxy.wait if loaded_proxy.wait
 
-      runner.proxy = p
+      runner.proxy = proxy_attributes
     end
   end
 end

data/lib/nonnative/configuration_process.rb

@@ -19,7 +19,7 @@ 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 the port to open/close
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close
     attr_accessor :timeout
 
     # @return [String] log file path to append process stdout/stderr to

data/lib/nonnative/configuration_runner.rb

@@ -15,9 +15,12 @@ module Nonnative
   class ConfigurationRunner
     # @return [String, nil] runner name used for lookup (for example via `pool.process_by_name`)
     # @return [String] host to bind/connect to (defaults to `"127.0.0.1"`)
-    # @return [Integer] port to bind/connect to
+    # @return [Array<Integer>] ports to bind/connect to
     # @return [Numeric] wait interval (seconds) used by runners between lifecycle steps
-    attr_accessor :name, :host, :port, :wait
+    attr_accessor :name, :host, :wait
+
+    # @return [Array<Integer>] client-facing ports used for readiness/shutdown checks
+    attr_reader :ports
 
     # Proxy configuration for this runner.
     #
@@ -31,19 +34,37 @@ module Nonnative
     #
     # Defaults:
     # - `host`: `"127.0.0.1"`
-    # - `port`: `0`
+    # - `ports`: `[0]`
     # - `wait`: `0.1`
     # - `proxy`: a new {Nonnative::ConfigurationProxy} with its own defaults
     #
     # @return [void]
     def initialize
       self.host = '127.0.0.1'
-      self.port = 0
+      @ports = [0]
       self.wait = 0.1
 
       @proxy = Nonnative::ConfigurationProxy.new
     end
 
+    # Sets the client-facing ports for this runner.
+    #
+    # @param value [Array<Integer>] ports to check for readiness/shutdown
+    # @return [void]
+    def ports=(value)
+      @ports = Array(value)
+    end
+
+    # Returns the primary client-facing port.
+    #
+    # This preserves a single endpoint for proxy binding and client helpers while the public
+    # configuration contract uses {#ports}.
+    #
+    # @return [Integer]
+    def port
+      ports.first
+    end
+
     # Sets proxy configuration using a hash-like value.
     #
     # This is primarily used when loading YAML configuration files, where proxy attributes are

data/lib/nonnative/configuration_server.rb

@@ -12,7 +12,7 @@ module Nonnative
   # @see Nonnative::Server
   class ConfigurationServer < ConfigurationRunner
     # @return [Class] a class that implements `#initialize(service)`, and lifecycle hooks expected by {Nonnative::Server}
-    # @return [Numeric] readiness timeout (seconds) used when waiting for the port to open/close
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close
     # @return [String] log file path used by server implementations (for example Puma/gRPC log files)
     attr_accessor :klass, :timeout, :log
   end

data/lib/nonnative/configuration_service.rb

@@ -11,5 +11,33 @@ module Nonnative
   # @see Nonnative::Configuration
   # @see Nonnative::Service
   class ConfigurationService < ConfigurationRunner
+    # @return [Integer] client-facing port used by the service proxy
+    attr_accessor :port
+
+    # Creates a service configuration with defaults.
+    #
+    # @return [void]
+    def initialize
+      super
+
+      self.port = 0
+    end
+
+    # Services expose a single proxy listener, so plural runner ports are not supported.
+    #
+    # @return [void]
+    # @raise [ArgumentError] when plural service ports are read
+    def ports
+      raise ArgumentError, "Use 'port' instead of 'ports' for service '#{name}'"
+    end
+
+    # Services expose a single proxy listener, so plural runner ports are not supported.
+    #
+    # @param _value [Array<Integer>] ignored plural ports
+    # @return [void]
+    # @raise [ArgumentError] when plural service ports are assigned
+    def ports=(_value)
+      raise ArgumentError, "Use 'port' instead of 'ports' for service '#{name}'"
+    end
   end
 end

data/lib/nonnative/fault_injection_proxy.rb

@@ -18,8 +18,8 @@ module Nonnative
   #
   # ## Wiring
   #
-  # When enabled, your test/client should connect to the runner `host` / `port` (the proxy endpoint),
-  # and the proxy will forward traffic to the upstream target exposed by {#host}:{#port}.
+  # When enabled, your test/client should connect to the runner `host` and primary port (the proxy
+  # endpoint), and the proxy will forward traffic to the upstream target exposed by {#host}:{#port}.
   #
   # ## Configuration
   #
@@ -62,7 +62,7 @@ module Nonnative
 
     # Starts the proxy accept loop in a background thread.
     #
-    # This binds a TCP server on the underlying runner’s `service.host` / `service.port`.
+    # This binds a TCP server on the underlying runner’s `service.host` and primary port.
     # Clients connect to that runner endpoint, while upstream traffic is forwarded to {#host}:{#port}.
     #
     # @return [void]

data/lib/nonnative/grpc_server.rb

@@ -34,7 +34,7 @@ module Nonnative
     # Binds the gRPC server and begins serving requests.
     #
     # The server binds to the upstream proxy host/port so the fault-injection proxy can expose the
-    # runner host/port as the client-facing endpoint used by readiness checks.
+    # runner host and first configured port as the client-facing endpoint used by readiness checks.
     #
     # @return [void]
     def perform_start

data/lib/nonnative/http_proxy_server.rb

@@ -50,9 +50,10 @@ module Nonnative
 
     # Executes the upstream request and returns the response.
     #
-    # @param verb [String] HTTP verb name (e.g. `"get"`)
-    # @param uri [String] upstream URI
-    # @param opts [Hash] RestClient options (e.g. headers)
+    # @param method [Symbol] HTTP verb name (e.g. `:get`)
+    # @param url [String] upstream URL
+    # @param headers [Hash] request headers
+    # @param payload [String, nil] request payload
     # @return [RestClient::Response] response for error statuses, otherwise RestClient return value
     def api_response(method:, url:, headers:, payload: nil)
       options = { method:, url:, headers: }
@@ -109,7 +110,7 @@ module Nonnative
   #       s.klass = Nonnative::Features::HTTPProxyServer
   #       s.timeout = 2
   #       s.host = '127.0.0.1'
-  #       s.port = 4567
+  #       s.ports = [4567]
   #       s.log = 'proxy.log'
   #     end
   #   end

data/lib/nonnative/http_server.rb

@@ -20,7 +20,7 @@ module Nonnative
   #       s.klass = ->(service) { Nonnative::HTTPServer.new(app, service) }
   #       s.timeout = 2
   #       s.host = '127.0.0.1'
-  #       s.port = 4567
+  #       s.ports = [4567]
   #       s.log = 'http.log'
   #     end
   #   end
@@ -49,7 +49,7 @@ module Nonnative
     # Binds the Puma server and begins serving.
     #
     # The listener binds to the upstream proxy host/port so the fault-injection proxy can expose the
-    # runner host/port as the client-facing endpoint used by readiness checks.
+    # runner host and first configured port as the client-facing endpoint used by readiness checks.
     #
     # @return [void]
     def perform_start
@@ -66,6 +66,6 @@ module Nonnative
 
     private
 
-    attr_reader :queue, :server
+    attr_reader :server
   end
 end

data/lib/nonnative/no_proxy.rb

@@ -5,7 +5,7 @@ module Nonnative
   #
   # This is the default proxy when `service.proxy.kind` is `"none"` (or an unknown kind is provided).
   # It does not bind/listen or alter traffic; it simply exposes the underlying runner's configured
-  # `host` and `port`.
+  # `host` and primary `port`.
   #
   # Runners can always call `start`, `stop`, and `reset` safely on this proxy.
   #
@@ -50,7 +50,7 @@ module Nonnative
 
     # Returns the port clients should connect to.
     #
-    # For {NoProxy}, this is the underlying runner configuration port.
+    # For {NoProxy}, this is the first underlying runner configuration port.
     #
     # @return [Integer]
     def port

data/lib/nonnative/pool.rb

@@ -9,7 +9,7 @@ module Nonnative
   # - On start: services first, then servers/processes (in parallel port-check threads)
   # - On stop: processes/servers first, then services
   #
-  # Readiness and shutdown are determined via TCP port checks ({Nonnative::Port#open?} / {Nonnative::Port#closed?}).
+  # Readiness and shutdown are determined via TCP port checks ({Nonnative::Ports#open?} / {Nonnative::Ports#closed?}).
   #
   # @see Nonnative.start
   # @see Nonnative.stop
@@ -35,7 +35,7 @@ module Nonnative
       errors = []
 
       errors.concat(service_lifecycle(services, :start, :start))
-      [servers, processes].each { |t| errors.concat(process(t, :start, :open?, :start, &)) }
+      [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start, &)) }
 
       errors
     end
@@ -51,7 +51,7 @@ module Nonnative
     def stop(&)
       errors = []
 
-      [processes, servers].each { |t| errors.concat(process(t, :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,7 +69,9 @@ module Nonnative
     def rollback(&)
       errors = []
 
-      [existing_processes, existing_servers].each { |t| errors.concat(process(t, :stop, :closed?, :stop, &)) }
+      [existing_processes, existing_servers].each do |runners|
+        errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop, &))
+      end
       errors.concat(service_lifecycle(existing_services, :stop, :stop))
 
       errors
@@ -129,7 +131,7 @@ module Nonnative
 
       @processes = []
       configuration.processes.each do |p|
-        @processes << [Nonnative::Process.new(p), Nonnative::Port.new(p)]
+        @processes << [Nonnative::Process.new(p), Nonnative::Ports.new(p)]
       end
 
       @processes
@@ -140,7 +142,7 @@ module Nonnative
 
       @servers = []
       configuration.servers.each do |s|
-        @servers << [s.klass.new(s), Nonnative::Port.new(s)]
+        @servers << [s.klass.new(s), Nonnative::Ports.new(s)]
       end
 
       @servers
@@ -177,15 +179,15 @@ module Nonnative
       end
     end
 
-    def process(all, type_method, port_method, action, &)
+    def run_lifecycle_checks(runners, lifecycle_method, port_method, action, &)
       checks = []
       errors = []
 
-      all.each do |type, port|
-        values = type.send(type_method)
-        checks << [type, values, Thread.new { check_port(port, port_method) }]
+      runners.each do |runner, port|
+        values = runner.send(lifecycle_method)
+        checks << [runner, values, Thread.new { check_port(port, port_method) }]
       rescue StandardError => e
-        errors << lifecycle_error(action, type, e)
+        errors << lifecycle_error(action, runner, e)
       end
 
       errors.concat(yield_results(checks, action, &))

data/lib/nonnative/port.rb

@@ -3,21 +3,23 @@
 module Nonnative
   # Performs TCP port readiness/shutdown checks for a configured runner.
   #
-  # Nonnative uses this to decide whether a process/server is ready after start, and whether it has
-  # shut down after stop. The checks repeatedly attempt to open a TCP connection to `process.host`
-  # and `process.port` until either:
+  # Nonnative uses this to decide whether a process/server port is ready after start, and whether it
+  # has shut down after stop. The checks repeatedly attempt to open a TCP connection to `process.host`
+  # and the configured `port` until either:
   #
   # - the expected condition is met, or
   # - the configured timeout elapses (in which case the method returns `false`)
   #
   # The `process` argument is a runner configuration object (e.g. {Nonnative::ConfigurationProcess}
-  # or {Nonnative::ConfigurationServer}) that responds to `host`, `port`, and `timeout`.
+  # or {Nonnative::ConfigurationServer}) that responds to `host` and `timeout`.
   #
   # @see Nonnative::Pool for how these checks are orchestrated during start/stop
   class Port
-    # @param process [#host, #port, #timeout] runner configuration providing connection details
-    def initialize(process)
+    # @param process [#host, #timeout] runner configuration providing connection details
+    # @param port [Integer] port to check
+    def initialize(process, port = process.port)
       @process = process
+      @port = port
       @timeout = Nonnative::Timeout.new(process.timeout)
     end
 
@@ -28,7 +30,7 @@ module Nonnative
     #
     # @return [Boolean] `true` if the port opened in time; otherwise `false`
     def open?
-      Nonnative.logger.info "checking if port '#{process.port}' is open on host '#{process.host}'"
+      Nonnative.logger.info "checking if port '#{port}' is open on host '#{process.host}'"
 
       timeout.perform do
         open_socket
@@ -46,7 +48,7 @@ module Nonnative
     #
     # @return [Boolean] `true` if the port closed in time; otherwise `false`
     def closed?
-      Nonnative.logger.info "checking if port '#{process.port}' is closed on host '#{process.host}'"
+      Nonnative.logger.info "checking if port '#{port}' is closed on host '#{process.host}'"
 
       timeout.perform do
         open_socket
@@ -61,10 +63,10 @@ module Nonnative
 
     private
 
-    attr_reader :process, :timeout
+    attr_reader :process, :port, :timeout
 
     def open_socket
-      TCPSocket.new(process.host, process.port).close
+      TCPSocket.new(process.host, port).close
     end
 
     def sleep_interval

data/lib/nonnative/ports.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Performs aggregate TCP readiness/shutdown checks for all configured runner ports.
+  #
+  # A runner is considered ready only when every configured port is open, and stopped only when every
+  # configured port is closed.
+  #
+  # @see Nonnative::Port
+  class Ports
+    # @param runner [#host, #ports, #timeout] runner configuration providing connection details
+    def initialize(runner)
+      @ports = runner.ports.map { |port| Nonnative::Port.new(runner, port) }
+    end
+
+    # Returns whether all configured ports become connectable before their timeouts elapse.
+    #
+    # @return [Boolean]
+    def open?
+      ports.all?(&:open?)
+    end
+
+    # Returns whether all configured ports become non-connectable before their timeouts elapse.
+    #
+    # @return [Boolean]
+    def closed?
+      ports.all?(&:closed?)
+    end
+
+    private
+
+    attr_reader :ports
+  end
+end

data/lib/nonnative/socket_pair.rb

@@ -65,18 +65,18 @@ module Nonnative
       ::TCPSocket.new(proxy.host, proxy.port)
     end
 
-    # Pipes data from `socket1` to `socket2` if `socket1` is readable.
+    # Pipes data from `source_socket` to `destination_socket` when the source is readable.
     #
     # @param ready [Array<Array<IO>>] the result from `select`
-    # @param socket1 [IO] readable side
-    # @param socket2 [IO] writable side
+    # @param source_socket [IO] readable side
+    # @param destination_socket [IO] writable side
     # @return [Boolean] whether the piping loop should terminate
-    def pipe?(ready, socket1, socket2)
-      if ready[0].include?(socket1)
-        data = read(socket1)
+    def pipe?(ready, source_socket, destination_socket)
+      if ready[0].include?(source_socket)
+        data = read(source_socket)
         return true if data.empty?
 
-        write socket2, data
+        write destination_socket, data
       end
 
       false

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -24,7 +24,7 @@
 #       p.name = 'api'
 #       p.command = -> { './bin/api' }
 #       p.host = '127.0.0.1'
-#       p.port = 8080
+#       p.ports = [8080, 9090]
 #       p.timeout = 10
 #       p.log = 'api.log'
 #     end
@@ -68,6 +68,7 @@ require 'nonnative/stop_error'
 require 'nonnative/not_found_error'
 require 'nonnative/timeout'
 require 'nonnative/port'
+require 'nonnative/ports'
 require 'nonnative/configuration_file'
 require 'nonnative/configuration'
 require 'nonnative/configuration_runner'
@@ -208,7 +209,7 @@ 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/port.
+    # Readiness is determined by attempting to connect to each runner's configured host/ports.
     #
     # @return [void]
     # @raise [Nonnative::StartError] if one or more runners fail to start or become ready in time

data/nonnative.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Alejandro Falkowski']
   spec.email         = ['alexrfalkowski@gmail.com']
 
-  spec.summary       = 'Allows you to keep using the power of ruby to test other systems'
+  spec.summary       = 'Allows you to keep using the power of Ruby to test other systems'
   spec.description   = spec.summary
   spec.homepage      = 'https://github.com/alexfalkowski/nonnative'
   spec.license       = 'MIT'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 2.23.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -263,7 +263,7 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
-description: Allows you to keep using the power of ruby to test other systems
+description: Allows you to keep using the power of Ruby to test other systems
 email:
 - alexrfalkowski@gmail.com
 executables: []
@@ -310,6 +310,7 @@ files:
 - lib/nonnative/observability.rb
 - lib/nonnative/pool.rb
 - lib/nonnative/port.rb
+- lib/nonnative/ports.rb
 - lib/nonnative/process.rb
 - lib/nonnative/proxy.rb
 - lib/nonnative/proxy_factory.rb
@@ -348,5 +349,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.11
 specification_version: 4
-summary: Allows you to keep using the power of ruby to test other systems
+summary: Allows you to keep using the power of Ruby to test other systems
 test_files: []