nonnative 3.6.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb25075ea94da70b097c6b60e7a47fea1a73b7e80d4903f32b2a2d00675b50e
-  data.tar.gz: 33c1c4310fa48a1a8dacf792d9ce6af73f9a406f67185f61fb292f07d06d2345
+  metadata.gz: 6a276b7ac5edae149fc6eb065909773b73c5c7e1684e4502244d88a0cdd6c521
+  data.tar.gz: 82545f52a383ba1f67af5c1d01c72653adee7339a3e1968fb987eabc9236421e
 SHA512:
-  metadata.gz: c1c7e788eacbf1ed02100d4fc954f3ab7781c17a4e8c46c8ca8764becea615d54c6dee3be60404901228b37397533a809873c3ae27a157ac53463ff048ce8d50
-  data.tar.gz: fc73665d0141f943beca8dd9d43adbee088a214d1d31dad757fed1502df707f8ae599f10f4d5b3eb0b0c7e8c7db4b43b860cdd655e90d49c194320148df65439
+  metadata.gz: 0eea335efd1554822d7153077244d2f8ff5d19c46af6b19e153bd0298e99e4902f090b933899d4614e46a88252d9b95e9f7ec92b3d6e9e824c96f00694d579f9
+  data.tar.gz: ce2d8e41f9313b289c3531fe8c605e869dd856a1eb8ae47bb1671ebc12aa1f97a3a8e795cad16681c11857b2a70ce4f2250b0310dd57286162cc9aed7efa764e

data/.circleci/config.yml

@@ -32,13 +32,13 @@ jobs:
       - restore_cache:
           name: restore deps
           keys:
-            - nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}-{{ checksum ".source-key" }}
+            - nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}
             - nonnative-ruby-cache-
       - run: make dep
       - run: make clean-dep
       - save_cache:
           name: save deps
-          key: nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}-{{ checksum ".source-key" }}
+          key: nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}
           paths:
             - vendor
       - run: make lint

data/AGENTS.md

@@ -74,6 +74,11 @@ of dependencies.
   use `nonnative` against real dependencies. Do not flag the in-repository
   service proxy success scenario's connection-only assertion as a test gap
   unless the task is explicitly about changing service proxy forwarding.
+- `Nonnative::FaultInjectionProxy` owns its listener thread and stops it by
+  closing the owned `TCPServer`, which wakes the accept loop before joining the
+  thread. Do not flag the listener `join` as an unbounded reliability gap unless
+  the task is explicitly about proxy shutdown behavior or there is a normal-use
+  reproducer, failing CI evidence, or platform-specific hang evidence.
 
 ## Runtime Model
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.6.0)
+    nonnative (3.10.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)

data/README.md

@@ -66,13 +66,16 @@ Process/server fields:
 - `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:
 
@@ -91,7 +94,9 @@ 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.
+> `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.
 
 ### 📈 Observability
 
@@ -170,6 +175,7 @@ Nonnative.configure do |config|
     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'
     }
@@ -205,6 +211,9 @@ 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
   -
@@ -612,7 +621,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
   #
@@ -142,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
@@ -163,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))
@@ -174,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
@@ -220,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

@@ -28,6 +28,9 @@ 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:
@@ -39,5 +42,13 @@ module Nonnative
 
       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_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/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/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

@@ -20,6 +20,9 @@ module Nonnative
       @timeout = Nonnative::Timeout.new(service.timeout)
     end
 
+    # @return [GetProcessMem, nil] memory reader for the current process lifecycle
+    attr_reader :memory
+
     # Spawns the configured process if it is not already running.
     #
     # @return [Array<(Integer, Boolean)>]
@@ -29,6 +32,8 @@ module Nonnative
     def start
       unless process_exists?
         @pid = process_spawn
+        # Keep memory reads bound to the child spawned for this lifecycle.
+        @memory = GetProcessMem.new(pid)
         wait_start
       end
 
@@ -53,17 +58,8 @@ module Nonnative
       end
 
       [pid, stopped]
-    end
-
-    # Returns a memoized memory reader for the spawned process.
-    #
-    # This is primarily used by acceptance tests to assert memory usage.
-    #
-    # @return [GetProcessMem, nil] a memory reader for the pid, or `nil` if not started
-    def memory
-      return if pid.nil?
-
-      @memory ||= GetProcessMem.new(pid)
+    ensure
+      @memory = nil
     end
 
     protected

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.6.0'
+  VERSION = '3.10.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
 #
@@ -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
@@ -283,6 +286,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.
+    #
     # @return [void]
     def clear
       clear_logger
@@ -305,9 +311,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.6.0
+  version: 3.10.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