nonnative 3.2.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 522cec08aee3855943f6ef6ba38bec3d85acd00aeeb2d6640a6869cf55014518
-  data.tar.gz: ebebc8d342a2111f8fb8538c0bf5b615c549b61127761c3e2ada47397294b47c
+  metadata.gz: ef654d45571b49eaf151e67b60a8eaa5c7b6df2b1a2e877d774a30ec80cc3281
+  data.tar.gz: 3526ed68b510ee72ac7b2d92764109bbd729653b5e1ba06b8b7a0f1f60b44c07
 SHA512:
-  metadata.gz: e4df243398b167fb955324fe12894f8bb5ecaf4ec612f8c55ad73e6cf95d6e04868ad1ee2ff64c1fbbc68322ea96dc953a0329b01f609a31b5409fb38542f09a
-  data.tar.gz: 419ca92810588c41e281cd4d77e49651bee8c412d7285689f196c176473364f1562eabbe1944a121e238e79c9cfb0de6335bbcde05b6e068478c45db4414cef2
+  metadata.gz: f28ca3884eef23d8db41bcef405205e5afca8369622627f415a845340579e54b17102cbdcabd3d44933ae7630a26eb3c6b3ba05c3e50da08092b84ec873a1629
+  data.tar.gz: 69166708a716e13658f5f25c86ccea83c201cccdeeec11296249fc318e7cabbec78816048ca266f9c890538b920d091968bff3275888a2c7bf7d9853343313f6

data/.circleci/config.yml

@@ -1,15 +1,33 @@
 version: 2.1
 
+commands:
+  sync-submodules:
+    steps:
+      - run: git submodule sync
+      - run: git submodule update --init
+  checkout-submodules:
+    steps:
+      - checkout:
+          method: blobless
+      - sync-submodules
+
+executors:
+  ruby:
+    docker:
+      - image: alexfalkowski/ruby:3.17
+  release:
+    docker:
+      - image: alexfalkowski/release:8.18
+  alpine:
+    docker:
+      - image: alpine:latest
+
 jobs:
   build:
-    docker:
-      - image: alexfalkowski/ruby:3.14
+    executor: ruby
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: make source-key
       - restore_cache:
           name: restore deps
@@ -34,34 +52,25 @@ jobs:
       - run: make codecov-upload
     resource_class: arm.large
   sync:
-    docker:
-      - image: alexfalkowski/release:8.15
+    executor: release
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: make sync push
     resource_class: arm.large
   version:
-    docker:
-      - image: alexfalkowski/release:8.15
+    executor: release
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: version
       - run: package
     resource_class: arm.large
   wait-all:
-    docker:
-      - image: alexfalkowski/ruby:3.14
+    executor: alpine
+    resource_class: small
     steps:
       - run: echo "all applicable jobs finished"
-    resource_class: arm.large
 
 workflows:
   nonnative:

data/.gitignore

@@ -1,9 +1,18 @@
 /.bundle/
+.crush/
+.ruby-lsp/
+.source-key
 /.yardoc
 /_yardoc/
 /doc/
 /pkg/
+ISSUES.md
+TESTS.md
+DOCS.md
+FEATURES.md
+PROJECTS.md
+RELIABILITY.md
 test/reports/*
+!test/reports/.keep
 /tmp/
-vendor
-ISSUES.md
+vendor/

data/AGENTS.md

@@ -1,10 +1,8 @@
 # AGENTS.md
 
-## Shared skills
+## Shared guidance
 
-This repository uses the shared skills from `bin/skills/`. Read
-`bin/AGENTS.md` for the canonical shared skill list and use the smallest
-matching skill for the task.
+Use `bin/AGENTS.md` for shared skills and cross-repository defaults.
 
 `nonnative` is a Ruby gem for end-to-end testing systems implemented in other
 languages. It starts processes, in-process servers, and proxy-only services,
@@ -18,18 +16,16 @@ of dependencies.
 - Generated gRPC test stubs: `test/grpc/**/*`
 - Test protos: `test/nonnative/v1/*.proto`
 - Build wiring: root `Makefile` includes `bin/build/make/*.mak`
-- Required submodule: `bin/` from `git@github.com:alexfalkowski/bin.git`; missing SSH/submodule setup breaks `make`
+- Required submodule: `bin/`; missing submodule setup breaks `make`
 - Install deps: `make dep`
 - Lint: `make lint`
+- Security checks: `make sec`
 - Features: `make features`
 - Benchmarks only: `make benchmarks`
 - Cleanup: `make clean-dep`, `make clean-reports`
 
 ## Intentional Design Choices
 
-- Root `make` compatibility is GNU Make 4+/`gmake` oriented through the shared
-  `bin/build/make/*.mak` fragments. Do not flag GNU Make 3.81 parsing failures
-  as code issues unless the task is explicitly about supporting GNU Make 3.81.
 - The configured HTTP proxy feature intentionally uses the external
   `www.afalkowski.com` host through `features/support/http_proxy_server.rb`.
   Do not flag this external dependency as a code issue unless the task is
@@ -54,6 +50,10 @@ of dependencies.
   test proto changes. Do not flag the absence of an automatic generated-stub
   freshness check as a test gap unless the task is explicitly about changing
   test proto generation or generated-file validation.
+- Generated gRPC test stubs may carry manual require-path adjustments after
+  generation. Do not treat `make -C test stale` as a required validation target
+  unless the task is explicitly about changing test proto generation; verify
+  the generated Ruby loads before accepting generator-only rewrites.
 - Buf linting for the test-only proto module is intentionally not part of the
   required local validation surface. Do not flag missing root-level validation
   for `test/buf.yaml` as a test gap unless the task is explicitly about test

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.2.1)
+    nonnative (3.9.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)
@@ -26,7 +26,7 @@ GEM
     benchmark-trend (0.4.0)
     bigdecimal (4.1.2)
     builder (3.3.0)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.7)
     config (5.6.1)
       deep_merge (~> 1.2, >= 1.2.1)
       ostruct
@@ -64,24 +64,24 @@ GEM
     get_process_mem (1.0.0)
       bigdecimal (>= 2.0)
       ffi (~> 1.0)
-    google-protobuf (4.35.0-x86_64-darwin)
+    google-protobuf (4.35.1-x86_64-darwin)
       bigdecimal
       rake (~> 13.3)
-    google-protobuf (4.35.0-x86_64-linux-gnu)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
     googleapis-common-protos-types (1.23.0)
       google-protobuf (~> 4.26)
-    grpc (1.81.0-x86_64-darwin)
+    grpc (1.81.1-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.81.0-x86_64-linux-gnu)
+    grpc (1.81.1-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.8)
+    json (2.20.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -114,7 +114,7 @@ GEM
       rack (>= 3.0.0)
     rainbow (3.1.1)
     rake (13.4.2)
-    rbs (4.0.2)
+    rbs (4.0.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -146,7 +146,7 @@ GEM
     rspec-support (3.13.7)
     rspec-wait (1.0.2)
       rspec (>= 3.4)
-    rubocop (1.87.0)
+    rubocop (1.88.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -169,7 +169,7 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (3.1.0)
+    simplecov-cobertura (3.2.0)
       rexml
       simplecov (~> 0.19)
     simplecov-html (0.13.2)

data/README.md

@@ -62,17 +62,20 @@ 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.
+- `timeout`: max time (seconds) for readiness/shutdown port checks. Defaults to `1.0`.
 - `wait`: small sleep (seconds) between lifecycle steps.
 - `log`: per-runner log file used by process output redirection or server implementations.
 
+Process-only fields:
+- `readiness`: optional HTTP startup readiness check with explicit `port` and `path`.
+
 Service fields:
 - `port`: client-facing service port. Services do not get TCP readiness/shutdown checks from Nonnative.
 
-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.
+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 an HTTP readiness check that runs after TCP readiness succeeds.
 
 > [!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.
+> TCP readiness and shutdown checks only prove that a TCP port opened or closed. HTTP readiness is process-only, checks for a 2xx response, and does not verify gRPC health, schema readiness, migrations, or other application-specific health.
 
 Start and stop Nonnative around the test scope that should own the configured runners:
 
@@ -164,12 +167,13 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.name = 'start_1'
-    p.command = -> { ['features/support/bin/start', '12_321'] }
+    p.command = -> { ['bin/start-test-service', '12_321'] }
     p.timeout = 5
     p.wait = 0.1
     p.ports = [12_321]
     p.log = '12_321.log'
     p.signal = 'INT' # Possible values are described in Signal.list.keys.
+    p.readiness = { port: 12_321, path: '/test/readyz' }
     p.environment = { # Pass environment variables to process.
       'TEST' => 'true'
     }
@@ -177,7 +181,7 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.name = 'start_2'
-    p.command = -> { ['features/support/bin/start', '12_322'] }
+    p.command = -> { ['bin/start-test-service', '12_322'] }
     p.timeout = 0.5
     p.wait = 0.1
     p.ports = [12_322]
@@ -197,7 +201,7 @@ processes:
   -
     name: start_1
     command:
-      - features/support/bin/start
+      - bin/start-test-service
       - "12_321"
     timeout: 5
     wait: 1
@@ -205,12 +209,15 @@ processes:
       - 12321
     log: 12_321.log
     signal: INT # Possible values are described in Signal.list.keys.
+    readiness:
+      port: 12321
+      path: /test/readyz
     environment: # Pass environment variables to process.
       TEST: true
   -
     name: start_2
     command:
-      - features/support/bin/start
+      - bin/start-test-service
       - "12_322"
     timeout: 5
     wait: 1
@@ -474,6 +481,8 @@ end
 
 Define your server:
 
+Assume the gRPC service base class and response types below come from your generated gRPC stubs.
+
 ```ruby
 module Nonnative
   module Features
@@ -530,6 +539,9 @@ servers:
     log: grpc_server_1.log
 ```
 
+The `grpc` gem uses a global logger, so per-server gRPC log files are not independent. The first
+initialized gRPC server sets the logger used by later gRPC servers in the same Ruby process.
+
 Then load the file with:
 
 ```ruby
@@ -607,7 +619,7 @@ These proxies can simulate different situations. Available proxy kinds are:
 - `fault_injection`
 
 > [!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.
+> Unknown proxy kinds raise an error. If fault injection is not taking effect, check the `kind` spelling or register the custom kind before starting the system.
 
 Custom proxy kinds can be registered through `Nonnative.proxies`:
 

data/lib/nonnative/configuration.rb

@@ -22,6 +22,7 @@ module Nonnative
   #       p.ports = [8080, 9090]
   #       p.timeout = 10
   #       p.log = 'api.log'
+  #       p.readiness = { port: 8080, path: '/example/readyz' }
   #     end
   #   end
   #
@@ -42,13 +43,25 @@ module Nonnative
     end
 
     # @return [String, nil] logical system name (used for observability endpoints)
+    attr_accessor :name
+
     # @return [String, nil] configuration version
+    attr_accessor :version
+
     # @return [String, nil] base URL for observability queries (for example `"http://127.0.0.1:8080"`)
+    attr_accessor :url
+
     # @return [String, nil] path to the Nonnative log file
+    attr_accessor :log
+
     # @return [Array<Nonnative::ConfigurationProcess>] configured processes
+    attr_accessor :processes
+
     # @return [Array<Nonnative::ConfigurationServer>] configured in-process servers
+    attr_accessor :servers
+
     # @return [Array<Nonnative::ConfigurationService>] configured services (proxy-only)
-    attr_accessor :name, :version, :url, :log, :processes, :servers, :services
+    attr_accessor :services
 
     # Loads a configuration file and appends its runners to this instance.
     #
@@ -130,6 +143,7 @@ module Nonnative
           process_config.command = command(loaded_process)
           process_config.signal = loaded_process.signal
           process_config.environment = loaded_process.environment
+          process_config.readiness = loaded_process.readiness if loaded_process.readiness
           runner_attributes(process_config, loaded_process)
         end
       end
@@ -151,6 +165,7 @@ module Nonnative
       servers = cfg.servers || []
       servers.each do |loaded_server|
         reject_proxy(loaded_server, 'servers')
+        reject_readiness(loaded_server, 'servers')
 
         server do |server_config|
           server_config.klass = Object.const_get(server_class_name(loaded_server))
@@ -162,6 +177,8 @@ module Nonnative
     def add_services(cfg)
       services = cfg.services || []
       services.each do |loaded_service|
+        reject_readiness(loaded_service, 'services')
+
         service do |service_config|
           service_config.name = loaded_service.name
           service_config.host = loaded_service.host if loaded_service.host
@@ -179,7 +196,8 @@ module Nonnative
 
     def runner_attributes(runner, loaded)
       runner.name = loaded.name
-      runner.timeout = loaded.timeout
+      timeout = loaded.timeout
+      runner.timeout = timeout unless timeout.nil?
       runner.wait = loaded.wait if loaded.wait
       runner.host = loaded.host if loaded.host
       assign_ports(runner, loaded)
@@ -207,6 +225,13 @@ module Nonnative
       raise ArgumentError, "Use 'services' for proxy configuration; #{kind} do not support 'proxy'"
     end
 
+    def reject_readiness(loaded, kind)
+      values = loaded.to_h
+      return unless values.key?(:readiness) || values.key?('readiness')
+
+      raise ArgumentError, "Use 'processes' for readiness configuration; #{kind} do not support 'readiness'"
+    end
+
     def assign_proxy(service, loaded_proxy)
       return unless loaded_proxy
 

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 ports to open/close
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close (defaults to `1.0`)
     attr_accessor :timeout
 
     # @return [String] log file path to append process stdout/stderr to
@@ -27,5 +27,28 @@ module Nonnative
 
     # @return [Hash, nil] environment variables to pass to the spawned process
     attr_accessor :environment
+
+    # @return [Nonnative::ConfigurationReadiness, nil] optional HTTP readiness check
+    attr_reader :readiness
+
+    # Creates a process configuration with bounded lifecycle defaults.
+    #
+    # Defaults:
+    # - `timeout`: `1.0`
+    #
+    # @return [void]
+    def initialize
+      super
+
+      self.timeout = DEFAULT_TIMEOUT
+    end
+
+    # Sets optional HTTP readiness configuration.
+    #
+    # @param value [Hash, #to_h, nil] readiness attributes with required `port` and `path`
+    # @return [void]
+    def readiness=(value)
+      @readiness = value.nil? ? nil : Nonnative::ConfigurationReadiness.new(value)
+    end
   end
 end

data/lib/nonnative/configuration_proxy.rb

@@ -15,12 +15,21 @@ module Nonnative
   # @see Nonnative.proxies
   class ConfigurationProxy
     # @return [String] proxy kind name (for example `"none"` or `"fault_injection"`)
+    attr_accessor :kind
+
     # @return [String] upstream host used by proxy implementations (defaults to `"127.0.0.1"`)
+    attr_accessor :host
+
     # @return [Integer] upstream port used by proxy implementations (defaults to `0`)
+    attr_accessor :port
+
     # @return [String, nil] path to proxy log file (implementation-dependent)
+    attr_accessor :log
+
     # @return [Numeric] wait interval (seconds) after proxy state changes (defaults to `0.1`)
+    attr_accessor :wait
+
     # @return [Hash] proxy implementation options (implementation-dependent)
-    attr_accessor :kind, :host, :port, :log, :wait
     attr_reader :options
 
     # Creates a proxy configuration with defaults.

data/lib/nonnative/configuration_readiness.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # HTTP readiness configuration for a managed process.
+  #
+  # Readiness is optional. When present, both `port` and `path` are required so the startup
+  # check has an explicit application endpoint to poll after TCP readiness succeeds.
+  class ConfigurationReadiness
+    # @return [Integer] process HTTP readiness port
+    attr_accessor :port
+
+    # @return [String] HTTP readiness path
+    attr_accessor :path
+
+    # @param value [Hash, #to_h] readiness attributes
+    def initialize(value)
+      attributes = value.respond_to?(:to_h) ? value.to_h : value
+      self.port = attribute(attributes, :port)
+      self.path = attribute(attributes, :path)
+
+      validate!
+    end
+
+    private
+
+    def attribute(attributes, name)
+      attributes[name] || attributes[name.to_s]
+    end
+
+    def validate!
+      raise ArgumentError, "Process readiness requires 'port'" if port.nil?
+      raise ArgumentError, "Process readiness requires 'path'" if path.nil?
+    end
+  end
+end

data/lib/nonnative/configuration_runner.rb

@@ -12,11 +12,17 @@ module Nonnative
   # @see Nonnative::ConfigurationServer
   # @see Nonnative::ConfigurationService
   class ConfigurationRunner
+    # Default bounded readiness/shutdown timeout for process and server runners.
+    DEFAULT_TIMEOUT = 1.0
+
     # @return [String, nil] runner name used for lookup (for example via `pool.process_by_name`)
+    attr_accessor :name
+
     # @return [String] host to bind/connect to (defaults to `"127.0.0.1"`)
-    # @return [Array<Integer>] ports to bind/connect to
+    attr_accessor :host
+
     # @return [Numeric] wait interval (seconds) used by runners between lifecycle steps
-    attr_accessor :name, :host, :wait
+    attr_accessor :wait
 
     # @return [Array<Integer>] client-facing ports used for readiness/shutdown checks
     attr_reader :ports

data/lib/nonnative/configuration_server.rb

@@ -11,9 +11,25 @@ module Nonnative
   # @see Nonnative::Configuration
   # @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 ports to open/close
+    # @return [Class] a class that implements `#initialize(service)` and the hooks expected by {Nonnative::Server}
+    attr_accessor :klass
+
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close (defaults to `1.0`)
+    attr_accessor :timeout
+
     # @return [String] log file path used by server implementations (for example Puma/gRPC log files)
-    attr_accessor :klass, :timeout, :log
+    attr_accessor :log
+
+    # Creates a server configuration with bounded lifecycle defaults.
+    #
+    # Defaults:
+    # - `timeout`: `1.0`
+    #
+    # @return [void]
+    def initialize
+      super
+
+      self.timeout = DEFAULT_TIMEOUT
+    end
   end
 end

data/lib/nonnative/cucumber.rb

@@ -8,6 +8,26 @@ module Nonnative
   # Requiring `nonnative` outside a running Cucumber environment should not fail, but when Cucumber
   # does finish booting its support-code registry this installer still needs to register the hooks
   # and step definitions defined here.
+  #
+  # Supported hooks:
+  # - `@startup`: start before scenario, stop after scenario
+  # - `@manual`: stop after scenario; use `When I start the system` to start manually
+  # - `@clear`: clear memoized Nonnative state before scenario
+  # - `@reset`: reset proxies after scenario
+  #
+  # Installed step definitions:
+  # - `Given I set the proxy for service {string} to {string}`
+  # - `Then I should reset the proxy for service {string}`
+  # - `When I start the system`
+  # - `When I attempt to start the system`
+  # - `When I attempt to stop the system`
+  # - `Then I should see {string} as unhealthy`
+  # - `Then I should see {string} as healthy`
+  # - `Then the process {string} should consume less than {string} of memory`
+  # - `Then starting the system should raise an error`
+  # - `Then stopping the system should raise an error`
+  # - `Then I should see a log entry of {string} for process {string}`
+  # - `Then I should see a log entry of {string} in the file {string}`
   module Cucumber
     module LanguageHook
       def rb_language=(value)

data/lib/nonnative/fault_injection_proxy.rb

@@ -11,7 +11,7 @@ module Nonnative
   #
   # - {#close_all}: close connections immediately on accept
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
-  # - {#invalid_data}: corrupt outbound data by shuffling characters
+  # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
   # - {#reset}: return to healthy pass-through behavior
   #
   # State changes terminate any active connections so new connections observe the new behavior.
@@ -107,7 +107,7 @@ module Nonnative
       apply_state :delay
     end
 
-    # Corrupts forwarded data by shuffling characters.
+    # Mutates upstream responses while forwarding client requests unchanged.
     #
     # @return [void]
     def invalid_data

data/lib/nonnative/http_probe.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Probes a managed process HTTP readiness endpoint.
+  class HTTPProbe < Nonnative::HTTPClient
+    NETWORK_ERRORS = [
+      Errno::ECONNREFUSED,
+      Errno::EHOSTUNREACH,
+      Errno::ECONNRESET,
+      SocketError,
+      RestClient::Exceptions::Timeout,
+      RestClient::ServerBrokeConnection
+    ].freeze
+
+    # @param process [Nonnative::ConfigurationProcess] process configuration with readiness attributes
+    def initialize(process)
+      @readiness = process.readiness
+      @base_url = "http://#{process.host}:#{readiness.port}"
+      @timeout = Nonnative::Timeout.new(process.timeout)
+
+      super(base_url)
+    end
+
+    # Returns whether the configured HTTP endpoint returns a 2xx response before timeout.
+    #
+    # @return [Boolean]
+    def ready?
+      Nonnative.logger.info "checking if readiness '#{endpoint}' is ready"
+
+      timeout.perform do
+        response = get(readiness.path)
+        raise Nonnative::Error unless ready_response?(response)
+
+        true
+      rescue Nonnative::Error, *NETWORK_ERRORS
+        sleep_interval
+        retry
+      end
+    end
+
+    # Returns the HTTP readiness endpoint for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoint
+      "#{base_url}#{path}"
+    end
+
+    private
+
+    attr_reader :base_url, :readiness, :timeout
+
+    def path
+      readiness.path.start_with?('/') ? readiness.path : "/#{readiness.path}"
+    end
+
+    def ready_response?(response)
+      response.respond_to?(:code) && response.code.to_i.between?(200, 299)
+    end
+
+    def sleep_interval
+      sleep 0.01
+    end
+  end
+end

data/lib/nonnative/http_proxy_server.rb

@@ -23,6 +23,14 @@ module Nonnative
   #
   # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
   class HTTPProxy < Sinatra::Application
+    NON_FORWARDABLE_HEADERS = %w[
+      Host
+      Accept-Encoding
+      Version
+      Proxy-Authenticate
+      Proxy-Authorization
+    ].freeze
+
     # Extracts request headers from the Rack environment and normalizes them to standard HTTP names.
     #
     # Certain hop-by-hop or proxy-specific headers are removed.
@@ -36,7 +44,7 @@ module Nonnative
         result[normalized_header_name(header)] = value
       end
 
-      headers.except('Host', 'Accept-Encoding', 'Version')
+      headers.except(*NON_FORWARDABLE_HEADERS)
     end
 
     # Builds the upstream URL for the given request.

data/lib/nonnative/http_server.rb

@@ -9,14 +9,20 @@ module Nonnative
   # The server is started and stopped by {Nonnative::Server} via {#perform_start} / {#perform_stop}.
   #
   # @example Running a Sinatra app
-  #   app = Sinatra.new do
-  #     get('/hello') { 'Hello World!' }
+  #   class HelloHTTPServer < Nonnative::HTTPServer
+  #     def initialize(service)
+  #       app = Sinatra.new do
+  #         get('/hello') { 'Hello World!' }
+  #       end
+  #
+  #       super(app, service)
+  #     end
   #   end
   #
   #   Nonnative.configure do |config|
   #     config.server do |s|
   #       s.name = 'http'
-  #       s.klass = ->(service) { Nonnative::HTTPServer.new(app, service) }
+  #       s.klass = HelloHTTPServer
   #       s.timeout = 2
   #       s.host = '127.0.0.1'
   #       s.ports = [4567]
@@ -24,7 +30,7 @@ module Nonnative
   #     end
   #   end
   #
-  # Note: In YAML configuration you typically set `class` to a concrete subclass that calls `super(app, service)`.
+  # YAML configuration uses the same concrete subclass name in its `class` field.
   #
   # @see Nonnative::Server
   class HTTPServer < Nonnative::Server
@@ -33,7 +39,8 @@ module Nonnative
     # @param app [#call] a Rack-compatible application (e.g. Sinatra/Rack app)
     # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(app, service)
-      log = File.open(service.log, 'a')
+      # Keep the log IO so the server lifecycle can release Puma's file handle on stop.
+      @log = File.open(service.log, 'a')
       options = {
         log_writer: Puma::LogWriter.new(log, log),
         force_shutdown_after: service.timeout
@@ -60,10 +67,16 @@ module Nonnative
     # @return [void]
     def perform_stop
       server.graceful_shutdown
+    ensure
+      close_log
     end
 
     private
 
-    attr_reader :server
+    attr_reader :server, :log
+
+    def close_log
+      log.close unless log.closed?
+    end
   end
 end

data/lib/nonnative/no_proxy.rb

@@ -3,7 +3,7 @@
 module Nonnative
   # No-op proxy implementation.
   #
-  # This is the default proxy when `service.proxy.kind` is `"none"` (or an unknown kind is provided).
+  # This is the default proxy when `service.proxy.kind` is `"none"`.
   # It does not bind/listen or alter traffic; it simply exposes the underlying runner's configured
   # `host` and primary `port`.
   #

data/lib/nonnative/pool.rb

@@ -30,6 +30,7 @@ module Nonnative
     # @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(&)
       errors = []
@@ -47,6 +48,7 @@ module Nonnative
     # @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(&)
       errors = []
@@ -65,6 +67,7 @@ module Nonnative
     # @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(&)
       errors = []
@@ -183,7 +186,7 @@ module Nonnative
 
       runners.each do |runner, port|
         values = runner.send(lifecycle_method)
-        checks << [runner, values, Thread.new { check_port(port, port_method) }]
+        checks << [runner, values, port, Thread.new { check_port(port, port_method) }]
       rescue StandardError => e
         errors << lifecycle_error(action, runner, e)
       end
@@ -198,12 +201,12 @@ module Nonnative
     end
 
     def yield_results(checks, action, &)
-      checks.each_with_object([]) do |(type, values, thread), errors|
+      checks.each_with_object([]) do |(type, 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]
+          yield type.name, values, result[:result], port
         end
       end
     end

data/lib/nonnative/port.rb

@@ -61,6 +61,13 @@ module Nonnative
       end
     end
 
+    # Returns a human-readable endpoint for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoint
+      "#{process.host}:#{port}"
+    end
+
     private
 
     attr_reader :process, :port, :timeout

data/lib/nonnative/ports.rb

@@ -10,14 +10,16 @@ module Nonnative
   class Ports
     # @param runner [#host, #ports, #timeout] runner configuration providing connection details
     def initialize(runner)
+      @runner = runner
       @ports = runner.ports.map { |port| Nonnative::Port.new(runner, port) }
+      @readiness = Nonnative::HTTPProbe.new(runner) if runner.respond_to?(:readiness) && runner.readiness
     end
 
     # Returns whether all configured ports become connectable before their timeouts elapse.
     #
     # @return [Boolean]
     def open?
-      ports.all?(&:open?)
+      ports.all?(&:open?) && (readiness.nil? || readiness.ready?)
     end
 
     # Returns whether all configured ports become non-connectable before their timeouts elapse.
@@ -27,8 +29,27 @@ module Nonnative
       ports.all?(&:closed?)
     end
 
+    # Returns the checked endpoints for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoints
+      ports.map(&:endpoint).join(', ')
+    end
+
+    # Returns endpoint and log context for lifecycle errors.
+    #
+    # @return [String]
+    def description
+      details = []
+      details << "readiness: #{readiness.endpoint}" if readiness
+      log = runner.log if runner.respond_to?(:log)
+      details << "log: #{log}" if log
+
+      details.empty? ? endpoints : "#{endpoints} (#{details.join('; ')})"
+    end
+
     private
 
-    attr_reader :ports
+    attr_reader :ports, :readiness, :runner
   end
 end

data/lib/nonnative/process.rb

@@ -49,6 +49,7 @@ module Nonnative
       if process_exists?
         process_kill
         stopped = wait_stop != false
+        force_stop unless stopped
       end
 
       [pid, stopped]
@@ -82,6 +83,13 @@ module Nonnative
       ::Process.kill(signal, pid)
     end
 
+    def force_stop
+      ::Process.kill('KILL', pid)
+      wait_stop
+    rescue Errno::ESRCH, Errno::ECHILD
+      true
+    end
+
     def process_spawn
       environment = service.environment.to_h
       environment = environment.transform_keys(&:to_s).transform_values(&:to_s)

data/lib/nonnative/proxy.rb

@@ -6,11 +6,14 @@ module Nonnative
   # A proxy is responsible for interposing behavior between a client and a target service.
   # Runtime services create a proxy instance via {Nonnative::ProxyFactory} based on `service.proxy.kind`.
   #
+  # Service configuration `host` and `port` are the client-facing endpoint. Concrete proxy methods are
+  # 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:
   # - `start`: begin proxying (bind/listen, start threads, etc)
   # - `stop`: stop proxying and release resources
   # - `reset`: return proxy behavior to a healthy/default state
-  # - `host` / `port`: endpoint clients should connect to when the proxy is enabled
   #
   # @see Nonnative::ProxyFactory
   # @see Nonnative::NoProxy

data/lib/nonnative/proxy_factory.rb

@@ -6,7 +6,9 @@ module Nonnative
   # A runtime service constructs a proxy via this factory. The proxy implementation is selected by
   # `service.proxy.kind` and resolved using {Nonnative.proxy}.
   #
-  # If the kind is unknown (or `"none"`), {Nonnative.proxy} returns {Nonnative::NoProxy}.
+  # If the kind is `"none"`, {Nonnative.proxy} returns {Nonnative::NoProxy}.
+  # Unknown non-`"none"` kinds raise an error so proxy configuration typos do not silently disable
+  # fault injection.
   #
   # @see Nonnative.proxy
   # @see Nonnative.proxies

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -6,7 +6,7 @@
 # It can:
 #
 # - start external processes and in-process servers
-# - wait for readiness via port checks
+# - wait for readiness via port checks and optional process HTTP readiness
 # - optionally run fault-injection proxies in front of services
 #
 # The public entry points are exposed as module-level methods on {Nonnative}.
@@ -27,6 +27,7 @@
 #       p.ports = [8080, 9090]
 #       p.timeout = 10
 #       p.log = 'api.log'
+#       p.readiness = { port: 8080, path: '/example/readyz' }
 #     end
 #   end
 #
@@ -36,10 +37,10 @@
 #   # run tests...
 #   Nonnative.stop
 #
-# == Notes
+# == Cucumber integration
 #
-# This file also requires integration helpers used by acceptance tests. If you require `nonnative` outside a
-# Cucumber runtime, loading `nonnative/cucumber` may not be desirable for your environment.
+# Requiring `nonnative` loads the lazy Cucumber integration. It is safe outside a booted Cucumber
+# runtime; hooks and step definitions are installed once Cucumber's Ruby DSL is ready.
 #
 require 'socket'
 require 'timeout'
@@ -72,6 +73,7 @@ require 'nonnative/ports'
 require 'nonnative/configuration_file'
 require 'nonnative/configuration'
 require 'nonnative/configuration_runner'
+require 'nonnative/configuration_readiness'
 require 'nonnative/configuration_process'
 require 'nonnative/configuration_server'
 require 'nonnative/configuration_service'
@@ -82,6 +84,7 @@ require 'nonnative/server'
 require 'nonnative/service'
 require 'nonnative/pool'
 require 'nonnative/http_client'
+require 'nonnative/http_probe'
 require 'nonnative/http_server'
 require 'nonnative/http_proxy_server'
 require 'nonnative/grpc_server'
@@ -204,7 +207,7 @@ module Nonnative
     # @param kind [String] proxy kind name (for example `"fault_injection"`)
     # @return [Class] a subclass of {Nonnative::Proxy}
     def proxy(kind)
-      Nonnative.proxies[kind] || Nonnative::NoProxy
+      kind.nil? || kind == 'none' ? NoProxy : proxies.fetch(kind) { raise ArgumentError, "Unsupported proxy kind '#{kind}'" }
     end
 
     # Starts all configured services, servers, and processes, and waits for readiness.
@@ -216,9 +219,9 @@ module Nonnative
     def start
       @pool ||= Nonnative::Pool.new(configuration)
       errors = []
-      errors.concat(@pool.start do |name, values, result|
+      errors.concat(@pool.start do |name, values, result, ports|
         id, started = values
-        errors << "Started #{name} with id #{id}, though did not respond in time" if !started || !result
+        errors << "Started #{name} with id #{id}, though did not respond in time for #{ports.description}" if !started || !result
       end)
       nil
     rescue StandardError => e
@@ -239,9 +242,9 @@ module Nonnative
       errors = []
       return if @pool.nil?
 
-      errors.concat(@pool.stop do |name, values, result|
+      errors.concat(@pool.stop do |name, values, result, ports|
         id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Stopped #{name} with id #{id}, though did not respond in time" unless result
+        errors << "Stopped #{name} with id #{id}, though did not respond in time for #{ports.description}" unless result
         errors << "Stopped #{name} with id #{id}, though the process did not exit in time" unless stopped
       end)
       nil
@@ -305,9 +308,9 @@ module Nonnative
       errors = []
       return errors if @pool.nil?
 
-      errors.concat(@pool.rollback do |name, values, result|
+      errors.concat(@pool.rollback do |name, values, result, ports|
         id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Rollback failed for #{name} with id #{id}, because it did not stop in time" unless result
+        errors << "Rollback failed for #{name} with id #{id}, because it did not stop in time for #{ports.description}" unless result
         errors << "Rollback failed for #{name} with id #{id}, because the process did not exit in time" unless stopped
       end)
     rescue StandardError => e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.9.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -291,6 +291,7 @@ files:
 - lib/nonnative/configuration_file.rb
 - lib/nonnative/configuration_process.rb
 - lib/nonnative/configuration_proxy.rb
+- lib/nonnative/configuration_readiness.rb
 - lib/nonnative/configuration_runner.rb
 - lib/nonnative/configuration_server.rb
 - lib/nonnative/configuration_service.rb
@@ -302,6 +303,7 @@ files:
 - lib/nonnative/grpc_server.rb
 - lib/nonnative/header.rb
 - lib/nonnative/http_client.rb
+- lib/nonnative/http_probe.rb
 - lib/nonnative/http_proxy_server.rb
 - lib/nonnative/http_server.rb
 - lib/nonnative/invalid_data_socket_pair.rb