nonnative 3.10.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a276b7ac5edae149fc6eb065909773b73c5c7e1684e4502244d88a0cdd6c521
-  data.tar.gz: 82545f52a383ba1f67af5c1d01c72653adee7339a3e1968fb987eabc9236421e
+  metadata.gz: 304a9d9d01fafb9f0822e4510c647f87095f78987feecb5a9d2eddc43317a880
+  data.tar.gz: 366157abd34f6ffa48cce159dffd49075e4a98653ea5d3f3b11b2494ad47b4a1
 SHA512:
-  metadata.gz: 0eea335efd1554822d7153077244d2f8ff5d19c46af6b19e153bd0298e99e4902f090b933899d4614e46a88252d9b95e9f7ec92b3d6e9e824c96f00694d579f9
-  data.tar.gz: ce2d8e41f9313b289c3531fe8c605e869dd856a1eb8ae47bb1671ebc12aa1f97a3a8e795cad16681c11857b2a70ce4f2250b0310dd57286162cc9aed7efa764e
+  metadata.gz: 6fa7d92393e3a4df9f400a7f35c857998c13dc026ec85be407fa37d6e8ba2189c5992af70e001c1cdfaf9589d1b6d33a2daf11abf8361f84f07ab8bc3a72fed1
+  data.tar.gz: bf37673b803ff66338009fbbd458d707c6eed9ef0ba618bb53b97e2f5770788708343f6bd34b67758fd6d1a13e464f63edffced76c26591f8ac4fe4ec2267a3e

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.19
   alpine:
     docker:
       - image: alpine:latest

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.10.0)
+    nonnative (3.13.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).
 
@@ -38,6 +38,18 @@ Or install it yourself as:
 gem install nonnative
 ```
 
+## 🛠️ Contributor Bootstrap
+
+Fresh clones need the shared `bin/` submodule before Make targets can load:
+
+```bash
+git submodule sync && git submodule update --init
+make help
+```
+
+Use `make dep` before local validation when dependencies are missing. The CI-parity checks are
+`make lint`, `make sec`, `make features`, and `make benchmarks`.
+
 ## 🚀 Usage
 
 Nonnative is configured via `Nonnative.configure` (programmatic) or `config.load_file(...)` (YAML).
@@ -67,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`.
+- `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.
+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:
 
@@ -98,6 +115,37 @@ Nonnative.stop
 > 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.
 
+### 🧩 Test framework setup
+
+For Cucumber, load and configure Nonnative in `features/support/env.rb`, then use lifecycle tags on scenarios:
+
+```ruby
+require 'nonnative'
+
+Nonnative.configure do |config|
+  config.load_file('configuration.yml')
+end
+```
+
+```cucumber
+@startup
+Scenario: run with Nonnative around this scenario
+```
+
+For RSpec or another suite that should start Nonnative once per test run, configure first and then require the startup integration:
+
+```ruby
+require 'nonnative'
+
+Nonnative.configure do |config|
+  config.load_file('configuration.yml')
+end
+
+require 'nonnative/startup'
+```
+
+`nonnative/startup` calls `Nonnative.start` immediately and registers an `at_exit` stop, so load configuration before requiring it.
+
 ### 📈 Observability
 
 `Nonnative.observability` is an HTTP client for common service endpoints under the configured `name` and `url`:
@@ -119,11 +167,24 @@ 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:
 - `@startup`: start before scenario; stop after scenario
-- `@manual`: stop after scenario (start is expected to be triggered manually in steps)
+- `@manual`: stop after scenario; use `When I start the system` to start manually
 - `@clear`: clears memoized configuration, logger, observability client, and pool before scenario
 - `@reset`: resets proxies after scenario
 
@@ -140,14 +201,6 @@ The repo’s own Cucumber suite also uses taxonomy tags to classify coverage:
 
 Requiring `nonnative` is enough; the Cucumber hooks and step definitions are installed lazily once Cucumber’s Ruby DSL is ready.
 
-If you want "start once per test run", require:
-
-```ruby
-require 'nonnative/startup'
-```
-
-This calls `Nonnative.start` immediately and registers an `at_exit` stop.
-
 ### ⚙️ Processes
 
 A process is some sort of command that you would run locally.
@@ -175,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'
     }
@@ -212,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
   -
@@ -558,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:
 
@@ -575,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|
@@ -597,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
@@ -630,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
 
@@ -653,6 +721,8 @@ config.service do |s|
       delay: 5
     }
   }
+
+  s.readiness = [{ kind: 'tcp', host: '127.0.0.1', port: 6379 }]
 end
 ```
 
@@ -666,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

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_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] HTTP readiness path
+    # @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,8 +46,29 @@ 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)
+
+      uri.scheme.nil? && uri.host.nil?
+    rescue URI::InvalidURIError
+      false
     end
   end
 end

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

@@ -43,10 +43,11 @@ module Nonnative
       end
 
       def install_hooks
+        # Register @clear before startup hooks so combined tags reset stale state before creating a pool.
+        Before('@clear') { Nonnative.clear }
         Before('@startup') { Nonnative.start }
         After('@startup') { Nonnative.stop }
         After('@manual') { Nonnative.stop }
-        Before('@clear') { Nonnative.clear }
         After('@reset') { Nonnative.reset }
       end
     end

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)
 
@@ -28,7 +29,7 @@ module Nonnative
       Nonnative.logger.info "checking if readiness '#{endpoint}' is ready"
 
       timeout.perform do
-        response = get(readiness.path)
+        response = get(path)
         raise Nonnative::Error unless ready_response?(response)
 
         true

data/lib/nonnative/no_proxy.rb

@@ -4,8 +4,8 @@ module Nonnative
   # No-op proxy implementation.
   #
   # 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`.
+  # It does not bind/listen or alter traffic; it simply exposes the service configuration's
+  # client-facing `host` and `port`.
   #
   # Services can always call `start`, `stop`, and `reset` safely on this proxy.
   #
@@ -41,7 +41,7 @@ module Nonnative
 
     # Returns the host clients should connect to.
     #
-    # For {NoProxy}, this is the underlying runner configuration host.
+    # For {NoProxy}, this is the service configuration's client-facing `host`.
     #
     # @return [String]
     def host
@@ -50,7 +50,7 @@ module Nonnative
 
     # Returns the port clients should connect to.
     #
-    # For {NoProxy}, this is the first underlying runner configuration port.
+    # For {NoProxy}, this is the service configuration's client-facing `port`.
     #
     # @return [Integer]
     def port

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/startup.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Starts the configured Nonnative pool immediately and registers an `at_exit` stop hook.
+#
+# Configure Nonnative before requiring this file; it is intended for suites that keep one
+# Nonnative lifecycle open for the whole Ruby process.
+
 at_exit do
   Nonnative.stop
 end

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/version.rb

@@ -4,5 +4,5 @@ module Nonnative
   # The current gem version.
   #
   # @return [String]
-  VERSION = '3.10.0'
+  VERSION = '3.13.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
 #
@@ -48,8 +48,10 @@ require 'yaml'
 require 'open3'
 require 'securerandom'
 require 'shellwords'
+require 'uri'
 
 require 'grpc'
+require 'grpc/health/v1/health_services_pb'
 require 'sinatra'
 require 'rest-client'
 require 'retriable'
@@ -74,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'
@@ -84,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'
@@ -189,9 +195,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.
     #
@@ -204,8 +217,12 @@ module Nonnative
 
     # Resolves a proxy implementation for a configured kind.
     #
+    # `nil` and `"none"` resolve to {Nonnative::NoProxy}; any other kind must be registered in
+    # {Nonnative.proxies}.
+    #
     # @param kind [String] proxy kind name (for example `"fault_injection"`)
     # @return [Class] a subclass of {Nonnative::Proxy}
+    # @raise [ArgumentError] if the kind is not `"none"` and has not been registered
     def proxy(kind)
       kind.nil? || kind == 'none' ? NoProxy : proxies.fetch(kind) { raise ArgumentError, "Unsupported proxy kind '#{kind}'" }
     end

data/nonnative.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Alejandro Falkowski']
   spec.email         = ['alexrfalkowski@gmail.com']
 
-  spec.summary       = 'Allows you to keep using the power of Ruby to test other systems'
-  spec.description   = spec.summary
+  spec.summary       = 'Ruby-first end-to-end harness for testing systems implemented in other languages'
+  spec.description   = 'Starts OS processes, in-process Ruby servers, and proxy-only services with TCP readiness checks and fault-injection proxies.'
   spec.homepage      = 'https://github.com/alexfalkowski/nonnative'
   spec.license       = 'MIT'
   spec.files         = Dir.chdir(File.expand_path(__dir__)) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.13.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -263,7 +263,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
-description: Allows you to keep using the power of Ruby to test other systems
+description: Starts OS processes, in-process Ruby servers, and proxy-only services
+  with TCP readiness checks and fault-injection proxies.
 email:
 - alexrfalkowski@gmail.com
 executables: []
@@ -295,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
@@ -324,6 +328,7 @@ 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/version.rb
 - nonnative.gemspec
@@ -351,5 +356,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.11
 specification_version: 4
-summary: Allows you to keep using the power of Ruby to test other systems
+summary: Ruby-first end-to-end harness for testing systems implemented in other languages
 test_files: []