nonnative 3.11.0 → 3.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a7d0e5ea6dab1d00eedd363fc81d05d2dd3e4401a97729043bcd3132a071432
-  data.tar.gz: 53c589eda9e895f3c815446003c97e77859ccec3b0c021182dc1437d0632b267
+  metadata.gz: 802f0ee020ba8e7c6cef867895d30c6491ace313fec8103aa6b99726c8402666
+  data.tar.gz: 70d522685a3c9cfbc872ee36549d9ba8274be60138a79db68e64c83115fd7cb5
 SHA512:
-  metadata.gz: be0b0b0d4cf1f606fe973f7bb6e38b3f2679b8445d6f24f7f05c4ca37eea62fc36f8910f6d0bcf44c1329b71d6638625d7d4a0d3226a14912662d91980523c1e
-  data.tar.gz: 15caeabfe50acdf2513ac2519bc953fb70effcc662c948c293be646d949bdb60c570359fb0817a6eb528207004f6a7cadfd440628026b58a0e9375003f650389
+  metadata.gz: a0b3e8502437cfd6d3a556a8a6f10901a2a89d85a4689fbad3c68d6819e03b4cccf5a51de3cfd66b86827d66f768891f68ee41c91b3ea504345c7f25d22178c8
+  data.tar.gz: b16ef6cfe6099e9a62be954178c71a743fb297ece661be2651239c8501707af30e1609e58abfe99bc58d007777a45c99505eb374484c0ba9788e886d0b876e42

data/.circleci/config.yml

@@ -14,10 +14,10 @@ commands:
 executors:
   ruby:
     docker:
-      - image: alexfalkowski/ruby:3.17
+      - image: alexfalkowski/ruby:3.19
   release:
     docker:
-      - image: alexfalkowski/release:8.18
+      - image: alexfalkowski/release:8.20
   alpine:
     docker:
       - image: alpine:latest

data/AGENTS.md

@@ -79,6 +79,32 @@ of dependencies.
   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.
+- Service readiness is intentionally TCP-only for externally managed
+  dependencies. Do not flag missing HTTP/gRPC service readiness as a feature gap
+  unless the task is explicitly about changing the `Nonnative::Service`
+  readiness model. HTTP/gRPC readiness belongs to managed processes, where the
+  user explicitly models the application health endpoints.
+- Process runners intentionally inherit the parent working directory. Nonnative
+  is normally run from the test folder that owns `test/nonnative.yml`, relative
+  config paths, logs, and reports. Do not flag missing process cwd/chdir support
+  as a feature gap unless the task is explicitly about changing process working
+  directory behavior.
+- Message-specific start/stop assertions and attempted-stop success assertions
+  in `features/step_definitions/lifecycle_steps.rb` are repository-local
+  Cucumber helpers. Do not flag their absence from `lib/nonnative/cucumber.rb`
+  as a feature gap unless downstream usage evidence exists or the task is
+  explicitly about expanding public lifecycle assertion steps.
+- Liveness, readiness, and metrics endpoint assertion steps in
+  `features/step_definitions/servers_steps.rb` are repository-local Cucumber
+  helpers for testing nonnative's own framework assumptions. Do not flag their
+  absence from `lib/nonnative/cucumber.rb` as a feature gap unless downstream
+  usage evidence exists or the task is explicitly about expanding public
+  observability assertion steps.
+- `Nonnative::Configuration` intentionally exposes `process_by_name` without
+  matching `server_by_name` or `service_by_name` helpers. Do not flag missing
+  server/service configuration lookup helpers as a feature gap unless downstream
+  usage evidence exists or the task is explicitly about changing the
+  pre-start configuration lookup API.
 
 ## Runtime Model
 

data/Gemfile.lock

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

data/README.md

@@ -11,7 +11,7 @@ It helps you:
 - start **OS processes** (e.g. your Go/Java/Rust service binary),
 - start **in-process Ruby servers** (e.g. small HTTP/TCP/gRPC fakes for dependencies),
 - optionally start **service proxies** for fault-injection in front of externally managed dependencies,
-- wait for readiness/shutdown using **TCP port checks**.
+- wait for readiness/shutdown using **TCP port checks**, optional process HTTP/gRPC checks, and optional service TCP checks.
 
 Once started, you can test however you like (TCP, HTTP, gRPC, etc).
 
@@ -79,15 +79,20 @@ Process/server fields:
 - `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-only `path`.
+- `readiness`: optional list of startup readiness checks. Supported kinds are `http` and `grpc`.
+  HTTP checks require explicit `port` and path-only `path`. gRPC checks require explicit `port` and
+  health `service`.
 
 Service fields:
-- `port`: client-facing service port. Services do not get TCP readiness/shutdown checks from Nonnative.
+- `port`: client-facing service port.
+- `timeout`: max time (seconds) for opt-in service readiness checks. Defaults to `1.0`.
+- `readiness`: optional list of startup readiness checks. Supported kind is `tcp`, which requires
+  explicit `host` and `port`.
 
-Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into an HTTP readiness check that runs after TCP readiness succeeds. HTTP readiness paths must be path-only values, such as `/test/readyz`; absolute URLs and scheme-relative URLs are rejected.
+Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into HTTP and gRPC readiness checks that run after TCP readiness succeeds. Services do not get automatic TCP readiness/shutdown checks, but can opt into TCP startup readiness for externally managed dependencies. HTTP readiness paths must be path-only values, such as `/test/readyz`; absolute URLs and scheme-relative URLs are rejected.
 
 > [!WARNING]
-> TCP readiness and shutdown checks only prove that a TCP port opened or closed. HTTP readiness is process-only, checks for a 2xx response, and does not verify gRPC health, schema readiness, migrations, or other application-specific health.
+> TCP readiness and shutdown checks only prove that a TCP port opened or closed. HTTP and gRPC readiness are process-only. Service readiness is TCP-only and should target the dependency endpoint that must be reachable before managed servers/processes start.
 
 Start and stop Nonnative around the test scope that should own the configured runners:
 
@@ -162,6 +167,19 @@ response = Nonnative.observability.health(
 expect(response.code).to eq(200)
 ```
 
+`Nonnative.grpc_health` is a helper for the standard gRPC health checking protocol:
+
+```ruby
+health = Nonnative.grpc_health(
+  host: '127.0.0.1',
+  port: 12_322,
+  service: 'example.v1.ExampleService',
+  timeout: 2
+)
+
+expect(health.serving?).to eq(true)
+```
+
 ### 🔁 Lifecycle strategies (Cucumber integration)
 
 Nonnative ships Cucumber hooks (when loaded) that support these tags/strategies:
@@ -210,7 +228,10 @@ 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.readiness = [
+      { kind: 'http', port: 12_321, path: '/test/readyz' },
+      { kind: 'grpc', port: 12_322, service: 'example.v1.ExampleService' }
+    ]
     p.environment = { # Pass environment variables to process.
       'TEST' => 'true'
     }
@@ -247,8 +268,12 @@ processes:
     log: 12_321.log
     signal: INT # Possible values are described in Signal.list.keys.
     readiness:
-      port: 12321
-      path: /test/readyz
+      - kind: http
+        port: 12321
+        path: /test/readyz
+      - kind: grpc
+        port: 12322
+        service: example.v1.ExampleService
     environment: # Pass environment variables to process.
       TEST: true
   -
@@ -593,7 +618,7 @@ end
 
 A service is an external dependency to your system that you **do not** want Nonnative to start (no OS process, no Ruby thread).
 
-Services do not get process lifecycle management or TCP readiness/shutdown checks from Nonnative. They provide a named endpoint for a dependency that another tool already manages.
+Services do not get process lifecycle management or automatic TCP readiness/shutdown checks from Nonnative. They provide a named endpoint for a dependency that another tool already manages, and can opt into TCP startup readiness when the dependency must be reachable before managed servers/processes start.
 
 Set it up programmatically:
 
@@ -610,6 +635,8 @@ Nonnative.configure do |config|
     s.name = 'postgres'
     s.host = '127.0.0.1'
     s.port = 5432
+    s.timeout = 5
+    s.readiness = [{ kind: 'tcp', host: '127.0.0.1', port: 5432 }]
   end
 
   config.service do |s|
@@ -632,6 +659,11 @@ services:
     name: postgres
     host: 127.0.0.1
     port: 5432
+    timeout: 5
+    readiness:
+      - kind: tcp
+        host: 127.0.0.1
+        port: 5432
   -
     name: redis
     host: 127.0.0.1
@@ -665,6 +697,7 @@ Nonnative.proxies['custom'] = CustomProxy
 ```
 
 Only services support proxies. For `fault_injection`, keep the service `host`/`port` as the client-facing proxy endpoint and use nested `proxy.host`/`proxy.port` for the upstream target behind the proxy.
+When service readiness is configured for a proxied dependency, set the readiness `host`/`port` to the upstream dependency, not the client-facing proxy listener.
 
 ##### 🧩 Service Proxies
 
@@ -688,6 +721,8 @@ config.service do |s|
       delay: 5
     }
   }
+
+  s.readiness = [{ kind: 'tcp', host: '127.0.0.1', port: 6379 }]
 end
 ```
 
@@ -701,6 +736,10 @@ services:
     name: redis
     host: 127.0.0.1
     port: 16379
+    readiness:
+      - kind: tcp
+        host: 127.0.0.1
+        port: 6379
     proxy:
       kind: fault_injection
       host: 127.0.0.1
@@ -719,6 +758,7 @@ Clients connect to the service `host`/`port`, while the proxy forwards traffic t
 
 - `close_all` - Closes the socket as soon as it connects.
 - `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through options.
+- `timeout` - Accepts the connection and stalls traffic until reset or stop closes the connection, so clients exercise their own read timeout behavior.
 - `invalid_data` - Forwards client requests unchanged, then corrupts upstream responses before they reach the client.
 
 ###### 🧩 Fault Injection Services
@@ -730,6 +770,7 @@ name = 'name of service in configuration'
 service = Nonnative.pool.service_by_name(name)
 
 service.proxy.close_all # To use close_all.
+service.proxy.timeout # To stall traffic until reset or stop.
 service.proxy.reset # To reset it back to a good state.
 ```
 
@@ -737,6 +778,7 @@ Use the Cucumber proxy steps:
 
 ```cucumber
 Given I set the proxy for service 'service_1' to 'close_all'
+Given I set the proxy for service 'service_1' to 'timeout'
 Then I should reset the proxy for service 'service_1'
 ```
 

data/lib/nonnative/configuration.rb

@@ -22,7 +22,7 @@ module Nonnative
   #       p.ports = [8080, 9090]
   #       p.timeout = 10
   #       p.log = 'api.log'
-  #       p.readiness = { port: 8080, path: '/example/readyz' }
+  #       p.readiness = [{ kind: 'http', port: 8080, path: '/example/readyz' }]
   #     end
   #   end
   #
@@ -177,11 +177,11 @@ 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
+          service_config.timeout = loaded_service.timeout if loaded_service.timeout
+          service_config.readiness = loaded_service.readiness if loaded_service.readiness
           assign_service_port(service_config, loaded_service)
 
           assign_proxy(service_config, loaded_service.proxy)

data/lib/nonnative/configuration_process.rb

@@ -28,7 +28,7 @@ module Nonnative
     # @return [Hash, nil] environment variables to pass to the spawned process
     attr_accessor :environment
 
-    # @return [Nonnative::ConfigurationReadiness, nil] optional HTTP readiness check
+    # @return [Array<Nonnative::ConfigurationReadiness>] optional readiness checks
     attr_reader :readiness
 
     # Creates a process configuration with bounded lifecycle defaults.
@@ -41,14 +41,23 @@ module Nonnative
       super
 
       self.timeout = DEFAULT_TIMEOUT
+      self.readiness = []
     end
 
-    # Sets optional HTTP readiness configuration.
+    # Sets optional process readiness checks.
     #
-    # @param value [Hash, #to_h, nil] readiness attributes with required `port` and `path`
+    # @param value [Array<Hash, #to_h>, nil] readiness checks with required `kind` and `port`
     # @return [void]
     def readiness=(value)
-      @readiness = value.nil? ? nil : Nonnative::ConfigurationReadiness.new(value)
+      @readiness = value.nil? ? [] : build_readiness(value)
+    end
+
+    private
+
+    def build_readiness(value)
+      raise ArgumentError, 'Process readiness must be a list of checks' unless value.is_a?(Array)
+
+      value.map { |check| Nonnative::ConfigurationReadiness.new(check) }
     end
   end
 end

data/lib/nonnative/configuration_proxy.rb

@@ -4,8 +4,8 @@ module Nonnative
   # Proxy configuration attached to a service configuration.
   #
   # A proxy allows you to interpose behavior between a client and a real service. For example,
-  # the built-in `"fault_injection"` proxy can close connections, introduce delays, or corrupt data
-  # for resilience testing.
+  # the built-in `"fault_injection"` proxy can close connections, introduce delays, stall traffic,
+  # or corrupt data for resilience testing.
   #
   # This object is created automatically for each service via {Nonnative::ConfigurationService}.
   # When `kind` is set to `"none"`, no proxy is started and the service will use its configured

data/lib/nonnative/configuration_readiness.rb

@@ -1,26 +1,44 @@
 # frozen_string_literal: true
 
 module Nonnative
-  # HTTP readiness configuration for a managed process.
+  # Readiness check 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.
+  # Readiness is optional. When present, each check declares a `kind` and explicit endpoint details
+  # to poll after TCP readiness succeeds.
   class ConfigurationReadiness
-    # @return [Integer] process HTTP readiness port
+    KINDS = %w[http grpc].freeze
+
+    # @return [String] readiness check kind
+    attr_accessor :kind
+
+    # @return [Integer] process readiness port
     attr_accessor :port
 
     # @return [String] path-only HTTP readiness path
     attr_accessor :path
 
-    # @param value [Hash, #to_h] readiness attributes
+    # @return [String] gRPC health service name
+    attr_accessor :service
+
+    # @param value [Hash, #to_h] readiness check attributes
     def initialize(value)
       attributes = value.respond_to?(:to_h) ? value.to_h : value
+      self.kind = attribute(attributes, :kind)&.to_s
       self.port = attribute(attributes, :port)
       self.path = attribute(attributes, :path)
+      self.service = attribute(attributes, :service)
 
       validate!
     end
 
+    def http?
+      kind == 'http'
+    end
+
+    def grpc?
+      kind == 'grpc'
+    end
+
     private
 
     def attribute(attributes, name)
@@ -28,11 +46,23 @@ module Nonnative
     end
 
     def validate!
+      raise ArgumentError, "Process readiness requires 'kind'" if kind.nil?
+      raise ArgumentError, "Process readiness kind must be one of: #{KINDS.join(', ')}" unless KINDS.include?(kind)
       raise ArgumentError, "Process readiness requires 'port'" if port.nil?
+
+      validate_http! if http?
+      validate_grpc! if grpc?
+    end
+
+    def validate_http!
       raise ArgumentError, "Process readiness requires 'path'" if path.nil?
       raise ArgumentError, 'Process readiness path must be path-only' unless path_only?
     end
 
+    def validate_grpc!
+      raise ArgumentError, "Process readiness requires 'service'" if service.nil?
+    end
+
     def path_only?
       uri = URI.parse(path.to_s)
 

data/lib/nonnative/configuration_service.rb

@@ -14,11 +14,17 @@ module Nonnative
     # @return [Integer] client-facing port used by the service proxy
     attr_accessor :port
 
+    # @return [Numeric] readiness timeout (seconds) used when waiting for service readiness
+    attr_accessor :timeout
+
     # Proxy configuration for this service.
     #
     # @return [Nonnative::ConfigurationProxy]
     attr_reader :proxy
 
+    # @return [Array<Nonnative::ConfigurationServiceReadiness>] optional service readiness checks
+    attr_reader :readiness
+
     # Creates a service configuration with defaults.
     #
     # @return [void]
@@ -26,9 +32,19 @@ module Nonnative
       super
 
       self.port = 0
+      self.timeout = DEFAULT_TIMEOUT
+      @readiness = []
       @proxy = Nonnative::ConfigurationProxy.new
     end
 
+    # Sets optional service readiness checks.
+    #
+    # @param value [Array<Hash, #to_h>, nil] readiness checks with required `kind`, `host`, and `port`
+    # @return [void]
+    def readiness=(value)
+      @readiness = value.nil? ? [] : build_readiness(value)
+    end
+
     # Sets proxy configuration using a hash-like value.
     #
     # This is primarily used when loading YAML configuration files, where proxy attributes are
@@ -67,5 +83,13 @@ module Nonnative
     def ports=(_value)
       raise ArgumentError, "Use 'port' instead of 'ports' for service '#{name}'"
     end
+
+    private
+
+    def build_readiness(value)
+      raise ArgumentError, 'Service readiness must be a list of checks' unless value.is_a?(Array)
+
+      value.map { |check| Nonnative::ConfigurationServiceReadiness.new(check) }
+    end
   end
 end

data/lib/nonnative/configuration_service_readiness.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Service readiness check configuration.
+  #
+  # Service readiness is for externally managed dependencies. The TCP target should be the dependency
+  # endpoint that must be reachable before managed servers and processes start.
+  class ConfigurationServiceReadiness
+    KINDS = %w[tcp].freeze
+
+    # @return [String] readiness check kind
+    attr_reader :kind
+
+    # @return [String] readiness target host
+    attr_reader :host
+
+    # @return [Integer] readiness target port
+    attr_reader :port
+
+    # @param value [Hash, #to_h] readiness check attributes
+    # @return [void]
+    def initialize(value)
+      attributes = value.to_h.transform_keys(&:to_sym)
+
+      @kind = attributes[:kind]&.to_s
+      @host = attributes[:host]
+      @port = attributes[:port]
+
+      validate!
+    end
+
+    # Returns whether this is a TCP readiness check.
+    #
+    # @return [Boolean]
+    def tcp?
+      kind == 'tcp'
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "Service readiness requires 'kind'" if kind.nil?
+      raise ArgumentError, "Service readiness kind must be one of: #{KINDS.join(', ')}" unless KINDS.include?(kind)
+      raise ArgumentError, "Service readiness requires 'host'" if host.nil?
+      raise ArgumentError, "Service readiness requires 'port'" if port.nil?
+    end
+  end
+end

data/lib/nonnative/cucumber.rb

@@ -56,6 +56,7 @@ module Nonnative
       PROXY_OPERATIONS = {
         'close_all' => :close_all,
         'delay' => :delay,
+        'timeout' => :timeout,
         'invalid_data' => :invalid_data,
         'reset' => :reset
       }.freeze

data/lib/nonnative/fault_injection_proxy.rb

@@ -11,6 +11,7 @@ module Nonnative
   #
   # - {#close_all}: close connections immediately on accept
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
+  # - {#timeout}: accept connections and keep them silent until clients time out
   # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
   # - {#reset}: return to healthy pass-through behavior
   #
@@ -107,6 +108,17 @@ module Nonnative
       apply_state :delay
     end
 
+    # Accepts connections and stalls without forwarding bytes.
+    #
+    # This simulates a dependency that accepts a TCP connection but leaves clients waiting until
+    # their own read timeout fires. The proxy keeps the connection silent until reset or stop closes
+    # active connections.
+    #
+    # @return [void]
+    def timeout
+      apply_state :timeout
+    end
+
     # Mutates upstream responses while forwarding client requests unchanged.
     #
     # @return [void]

data/lib/nonnative/grpc_health.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Client helper for the standard gRPC health checking protocol.
+  class GRPCHealth
+    NETWORK_ERRORS = [
+      GRPC::BadStatus,
+      GRPC::Core::CallError
+    ].freeze
+
+    # @param host [String] gRPC server host
+    # @param port [Integer] gRPC server port
+    # @param service [String] gRPC health service name
+    # @param timeout [Numeric] default call timeout in seconds
+    def initialize(host:, port:, service:, timeout: 1)
+      @host = host
+      @port = port
+      @service = service.to_s
+      @timeout = timeout
+    end
+
+    # Calls the gRPC health check endpoint.
+    #
+    # @param deadline [Time] gRPC deadline
+    # @return [Grpc::Health::V1::HealthCheckResponse]
+    def check(deadline: Time.now + timeout)
+      stub.check(request, deadline: deadline)
+    end
+
+    # Returns true when the gRPC health endpoint reports SERVING.
+    #
+    # @param deadline [Time] gRPC deadline
+    # @return [Boolean]
+    def serving?(deadline: Time.now + timeout)
+      check(deadline: deadline).status == :SERVING
+    rescue *NETWORK_ERRORS
+      false
+    end
+
+    # Returns the checked gRPC health endpoint for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoint
+      service.empty? ? "grpc://#{host}:#{port}" : "grpc://#{host}:#{port}/#{service}"
+    end
+
+    private
+
+    attr_reader :host, :port, :service, :timeout
+
+    def request
+      Grpc::Health::V1::HealthCheckRequest.new(service: service)
+    end
+
+    def stub
+      @stub ||= Grpc::Health::V1::Health::Stub.new("#{host}:#{port}", :this_channel_is_insecure)
+    end
+  end
+end

data/lib/nonnative/grpc_probe.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Probes a managed process gRPC health endpoint.
+  class GRPCProbe
+    # @param process [Nonnative::ConfigurationProcess] process configuration
+    # @param readiness [Nonnative::ConfigurationReadiness] gRPC readiness attributes
+    def initialize(process, readiness)
+      @health = Nonnative::GRPCHealth.new(
+        host: process.host,
+        port: readiness.port,
+        service: readiness.service,
+        timeout: process.timeout
+      )
+      @timeout = Nonnative::Timeout.new(process.timeout)
+    end
+
+    # Returns whether the configured gRPC health endpoint reports SERVING before timeout.
+    #
+    # @return [Boolean]
+    def ready?
+      Nonnative.logger.info "checking if readiness '#{endpoint}' is ready"
+
+      timeout.perform do
+        raise Nonnative::Error unless health.serving?
+
+        true
+      rescue Nonnative::Error
+        sleep_interval
+        retry
+      end
+    end
+
+    # Returns the gRPC health endpoint for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoint
+      health.endpoint
+    end
+
+    private
+
+    attr_reader :health, :timeout
+
+    def sleep_interval
+      sleep 0.01
+    end
+  end
+end

data/lib/nonnative/http_probe.rb

@@ -12,9 +12,10 @@ module Nonnative
       RestClient::ServerBrokeConnection
     ].freeze
 
-    # @param process [Nonnative::ConfigurationProcess] process configuration with readiness attributes
-    def initialize(process)
-      @readiness = process.readiness
+    # @param process [Nonnative::ConfigurationProcess] process configuration
+    # @param readiness [Nonnative::ConfigurationReadiness] HTTP readiness attributes
+    def initialize(process, readiness)
+      @readiness = readiness
       @base_url = "http://#{process.host}:#{readiness.port}"
       @timeout = Nonnative::Timeout.new(process.timeout)
 

data/lib/nonnative/pool.rb

@@ -25,7 +25,8 @@ module Nonnative
 
     # Starts all configured runners and yields results for each process/server.
     #
-    # Services are started first (proxy-only), then servers and processes are started and checked for readiness.
+    # Services are started first (proxy-only) and checked for opt-in readiness, then servers and processes are
+    # started and checked for readiness.
     #
     # @yieldparam name [String, nil] runner name
     # @yieldparam values [Object] runner-specific return value from `start` (e.g. `[pid, running]` for processes)
@@ -36,6 +37,10 @@ module Nonnative
       errors = []
 
       errors.concat(service_lifecycle(services, :start, :start))
+      service_readiness_errors = check_service_readiness(services)
+      errors.concat(service_readiness_errors)
+      return errors if service_readiness_errors.any?
+
       [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start, &)) }
 
       errors
@@ -180,6 +185,15 @@ module Nonnative
       end
     end
 
+    def check_service_readiness(all)
+      all.each_with_object([]) do |service, errors|
+        next unless service.respond_to?(:readiness)
+
+        checks = service.readiness.map { |readiness| Nonnative::TCPProbe.new(readiness, timeout: service.timeout) }
+        errors << service_readiness_error(service, checks) unless checks.all?(&:ready?)
+      end
+    end
+
     def run_lifecycle_checks(runners, lifecycle_method, port_method, action, &)
       checks = []
       errors = []
@@ -220,6 +234,10 @@ module Nonnative
       "#{check.capitalize} check failed for #{runner_name(type)}: #{error.class} - #{error.message}"
     end
 
+    def service_readiness_error(service, checks)
+      "Started #{runner_name(service)}, though did not respond in time for readiness: #{checks.map(&:endpoint).join(', ')}"
+    end
+
     def runner_name(type)
       name = type.name
       return "runner '#{name}'" if name

data/lib/nonnative/ports.rb

@@ -12,14 +12,14 @@ module Nonnative
     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
+      @readiness = readiness_probes
     end
 
     # Returns whether all configured ports become connectable before their timeouts elapse.
     #
     # @return [Boolean]
     def open?
-      ports.all?(&:open?) && (readiness.nil? || readiness.ready?)
+      ports.all?(&:open?) && readiness.all?(&:ready?)
     end
 
     # Returns whether all configured ports become non-connectable before their timeouts elapse.
@@ -41,7 +41,7 @@ module Nonnative
     # @return [String]
     def description
       details = []
-      details << "readiness: #{readiness.endpoint}" if readiness
+      details << "readiness: #{readiness.map(&:endpoint).join(', ')}" if readiness.any?
       log = runner.log if runner.respond_to?(:log)
       details << "log: #{log}" if log
 
@@ -51,5 +51,20 @@ module Nonnative
     private
 
     attr_reader :ports, :readiness, :runner
+
+    def readiness_probes
+      return [] unless runner.respond_to?(:readiness)
+
+      runner.readiness.map { |check| readiness_probe(check) }
+    end
+
+    def readiness_probe(check)
+      case check.kind
+      when 'http'
+        Nonnative::HTTPProbe.new(runner, check)
+      when 'grpc'
+        Nonnative::GRPCProbe.new(runner, check)
+      end
+    end
   end
 end

data/lib/nonnative/service.rb

@@ -24,6 +24,20 @@ module Nonnative
       @proxy = Nonnative::ProxyFactory.create(service)
     end
 
+    # Returns configured service readiness checks.
+    #
+    # @return [Array<Nonnative::ConfigurationServiceReadiness>]
+    def readiness
+      service.readiness
+    end
+
+    # Returns the configured service readiness timeout.
+    #
+    # @return [Numeric]
+    def timeout
+      service.timeout
+    end
+
     # Starts the configured proxy (if any).
     #
     # @return [void]

data/lib/nonnative/socket_pair.rb

@@ -16,6 +16,7 @@ module Nonnative
   # @see Nonnative::SocketPairFactory
   # @see Nonnative::CloseAllSocketPair
   # @see Nonnative::DelaySocketPair
+  # @see Nonnative::TimeoutSocketPair
   # @see Nonnative::InvalidDataSocketPair
   class SocketPair
     # @param proxy [#host, #port, #options] proxy configuration used to connect upstream

data/lib/nonnative/socket_pair_factory.rb

@@ -10,18 +10,20 @@ module Nonnative
   # - `:none` (or any unknown value) -> {Nonnative::SocketPair} (pass-through)
   # - `:close_all` -> {Nonnative::CloseAllSocketPair}
   # - `:delay` -> {Nonnative::DelaySocketPair}
+  # - `:timeout` -> {Nonnative::TimeoutSocketPair}
   # - `:invalid_data` -> {Nonnative::InvalidDataSocketPair}
   #
   # @see Nonnative::FaultInjectionProxy
   # @see Nonnative::SocketPair
   # @see Nonnative::CloseAllSocketPair
   # @see Nonnative::DelaySocketPair
+  # @see Nonnative::TimeoutSocketPair
   # @see Nonnative::InvalidDataSocketPair
   class SocketPairFactory
     class << self
       # Creates a socket-pair instance for the given proxy state.
       #
-      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:delay`, `:invalid_data`)
+      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:delay`, `:timeout`, `:invalid_data`)
       # @param proxy [Nonnative::ConfigurationProxy] proxy configuration (host/port/options)
       # @return [Nonnative::SocketPair] a socket-pair implementation instance
       def create(kind, proxy)
@@ -30,6 +32,8 @@ module Nonnative
                  CloseAllSocketPair
                when :delay
                  DelaySocketPair
+               when :timeout
+                 TimeoutSocketPair
                when :invalid_data
                  InvalidDataSocketPair
                else

data/lib/nonnative/tcp_probe.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Probes a TCP readiness endpoint.
+  class TCPProbe
+    Target = Struct.new(:host, :timeout, keyword_init: true)
+
+    # @param readiness [#host, #port] TCP readiness attributes
+    # @param timeout [Numeric] maximum time to wait for the TCP endpoint
+    def initialize(readiness, timeout:)
+      @port = Nonnative::Port.new(Target.new(host: readiness.host, timeout:), readiness.port)
+    end
+
+    # Returns whether the TCP endpoint becomes connectable before the timeout elapses.
+    #
+    # @return [Boolean]
+    def ready?
+      port.open?
+    end
+
+    # Returns the checked endpoint for lifecycle diagnostics.
+    #
+    # @return [String]
+    def endpoint
+      port.endpoint
+    end
+
+    private
+
+    attr_reader :port
+  end
+end

data/lib/nonnative/timeout_socket_pair.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate read timeouts.
+  #
+  # When active, the proxy accepts the client connection and keeps it open without forwarding bytes.
+  # Clients with read deadlines should observe their own timeout behavior.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#timeout}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
+  class TimeoutSocketPair < SocketPair
+    # Keeps the accepted socket silent until reset or stop closes active proxy connections.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
+    def connect(local_socket)
+      @local_socket = local_socket
+
+      Nonnative.logger.info "stalling socket '#{local_socket.inspect}' for 'timeout' pair"
+
+      # Do not call super: the base implementation opens the upstream socket and forwards traffic.
+      sleep 0.1 until local_socket.closed?
+    ensure
+      close
+    end
+  end
+end

data/lib/nonnative/version.rb

@@ -4,5 +4,5 @@ module Nonnative
   # The current gem version.
   #
   # @return [String]
-  VERSION = '3.11.0'
+  VERSION = '3.14.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 and optional process HTTP readiness
+# - wait for readiness via port checks, optional process HTTP/gRPC readiness, and optional service TCP readiness
 # - optionally run fault-injection proxies in front of services
 #
 # The public entry points are exposed as module-level methods on {Nonnative}.
@@ -27,7 +27,7 @@
 #       p.ports = [8080, 9090]
 #       p.timeout = 10
 #       p.log = 'api.log'
-#       p.readiness = { port: 8080, path: '/example/readyz' }
+#       p.readiness = [{ kind: 'http', port: 8080, path: '/example/readyz' }]
 #     end
 #   end
 #
@@ -51,6 +51,7 @@ require 'shellwords'
 require 'uri'
 
 require 'grpc'
+require 'grpc/health/v1/health_services_pb'
 require 'sinatra'
 require 'rest-client'
 require 'retriable'
@@ -75,6 +76,7 @@ require 'nonnative/configuration_file'
 require 'nonnative/configuration'
 require 'nonnative/configuration_runner'
 require 'nonnative/configuration_readiness'
+require 'nonnative/configuration_service_readiness'
 require 'nonnative/configuration_process'
 require 'nonnative/configuration_server'
 require 'nonnative/configuration_service'
@@ -85,7 +87,10 @@ require 'nonnative/server'
 require 'nonnative/service'
 require 'nonnative/pool'
 require 'nonnative/http_client'
+require 'nonnative/tcp_probe'
 require 'nonnative/http_probe'
+require 'nonnative/grpc_health'
+require 'nonnative/grpc_probe'
 require 'nonnative/http_server'
 require 'nonnative/http_proxy_server'
 require 'nonnative/grpc_server'
@@ -97,6 +102,7 @@ require 'nonnative/fault_injection_proxy'
 require 'nonnative/socket_pair'
 require 'nonnative/close_all_socket_pair'
 require 'nonnative/delay_socket_pair'
+require 'nonnative/timeout_socket_pair'
 require 'nonnative/invalid_data_socket_pair'
 require 'nonnative/socket_pair_factory'
 require 'nonnative/go_executable'
@@ -190,9 +196,16 @@ module Nonnative
     # Returns an HTTP client for common health/readiness endpoints.
     #
     # @return [Nonnative::Observability]
-    def observability
-      @observability ||= Nonnative::Observability.new(configuration.url)
-    end
+    def observability = (@observability ||= Nonnative::Observability.new(configuration.url))
+
+    # Returns a client helper for the standard gRPC health checking protocol.
+    #
+    # @param host [String] gRPC server host
+    # @param port [Integer] gRPC server port
+    # @param service [String] gRPC health service name
+    # @param timeout [Numeric] default call timeout in seconds
+    # @return [Nonnative::GRPCHealth]
+    def grpc_health(host:, port:, service:, timeout: 1) = Nonnative::GRPCHealth.new(host: host, port: port, service: service, timeout: timeout)
 
     # Returns the configured proxy kinds mapped to proxy classes.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.11.0
+  version: 3.14.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -296,11 +296,14 @@ files:
 - lib/nonnative/configuration_runner.rb
 - lib/nonnative/configuration_server.rb
 - lib/nonnative/configuration_service.rb
+- lib/nonnative/configuration_service_readiness.rb
 - lib/nonnative/cucumber.rb
 - lib/nonnative/delay_socket_pair.rb
 - lib/nonnative/error.rb
 - lib/nonnative/fault_injection_proxy.rb
 - lib/nonnative/go_executable.rb
+- lib/nonnative/grpc_health.rb
+- lib/nonnative/grpc_probe.rb
 - lib/nonnative/grpc_server.rb
 - lib/nonnative/header.rb
 - lib/nonnative/http_client.rb
@@ -325,7 +328,9 @@ files:
 - lib/nonnative/start_error.rb
 - lib/nonnative/startup.rb
 - lib/nonnative/stop_error.rb
+- lib/nonnative/tcp_probe.rb
 - lib/nonnative/timeout.rb
+- lib/nonnative/timeout_socket_pair.rb
 - lib/nonnative/version.rb
 - nonnative.gemspec
 homepage: https://github.com/alexfalkowski/nonnative