nonnative 3.6.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb25075ea94da70b097c6b60e7a47fea1a73b7e80d4903f32b2a2d00675b50e
-  data.tar.gz: 33c1c4310fa48a1a8dacf792d9ce6af73f9a406f67185f61fb292f07d06d2345
+  metadata.gz: ef654d45571b49eaf151e67b60a8eaa5c7b6df2b1a2e877d774a30ec80cc3281
+  data.tar.gz: 3526ed68b510ee72ac7b2d92764109bbd729653b5e1ba06b8b7a0f1f60b44c07
 SHA512:
-  metadata.gz: c1c7e788eacbf1ed02100d4fc954f3ab7781c17a4e8c46c8ca8764becea615d54c6dee3be60404901228b37397533a809873c3ae27a157ac53463ff048ce8d50
-  data.tar.gz: fc73665d0141f943beca8dd9d43adbee088a214d1d31dad757fed1502df707f8ae599f10f4d5b3eb0b0c7e8c7db4b43b860cdd655e90d49c194320148df65439
+  metadata.gz: f28ca3884eef23d8db41bcef405205e5afca8369622627f415a845340579e54b17102cbdcabd3d44933ae7630a26eb3c6b3ba05c3e50da08092b84ec873a1629
+  data.tar.gz: 69166708a716e13658f5f25c86ccea83c201cccdeeec11296249fc318e7cabbec78816048ca266f9c890538b920d091968bff3275888a2c7bf7d9853343313f6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.6.0)
+    nonnative (3.9.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:
 
@@ -170,6 +173,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 +209,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 +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
   #
@@ -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/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.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
 #
@@ -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.6.0
+  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