nonnative 1.107.0 → 1.108.0

data/lib/nonnative/grpc_server.rb

@@ -1,7 +1,22 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # gRPC server runner implemented using {GRPC::RpcServer}.
+  #
+  # This is a convenience server implementation for running a gRPC service in-process under
+  # Nonnative's server lifecycle. It binds to the configured proxy `host`/`port` and is started/stopped
+  # by {Nonnative::Server} via {#perform_start} / {#perform_stop}.
+  #
+  # Important note about logging: the `grpc` gem uses a global logger. This implementation sets
+  # `GRPC.logger` to write to the configured `service.log`, and whichever gRPC server is initialized
+  # first "wins" that global logger.
+  #
+  # @see Nonnative::Server
   class GRPCServer < Nonnative::Server
+    # Creates a gRPC server and registers the provided service handler.
+    #
+    # @param svc [Object] a gRPC service implementation (typically a `...::Service` subclass instance)
+    # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(svc, service)
       @server = GRPC::RpcServer.new
       server.handle(svc)
@@ -16,21 +31,36 @@ module Nonnative
 
     protected
 
+    # Binds the gRPC server and begins serving requests.
+    #
+    # The server binds to the proxy host/port so that enabling a proxy results in traffic and readiness
+    # checks consistently targeting the proxy endpoint.
+    #
+    # @return [void]
     def perform_start
       server.add_http2_port("#{proxy.host}:#{proxy.port}", :this_port_is_insecure)
       server.run
     end
 
+    # Stops the gRPC server.
+    #
+    # @return [void]
     def perform_stop
       server.stop
     end
 
+    # Waits until the gRPC server reports it is running, or the configured timeout elapses.
+    #
+    # @return [Object, false] the last evaluated expression from the timeout block, or `false` on timeout
     def wait_start
       timeout.perform do
         super until server.running?
       end
     end
 
+    # Waits until the gRPC server reports it has stopped, or the configured timeout elapses.
+    #
+    # @return [Object, false] the last evaluated expression from the timeout block, or `false` on timeout
     def wait_stop
       timeout.perform do
         super until server.stopped?

data/lib/nonnative/header.rb

@@ -1,20 +1,64 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Helper utilities for building request headers for HTTP and gRPC clients.
+  #
+  # This class returns Ruby hashes suitable for passing into client libraries (for example
+  # RestClient for HTTP or gRPC call metadata).
+  #
+  # @example HTTP user-agent (RestClient style)
+  #   headers = Nonnative::Header.http_user_agent('my-client/1.0')
+  #   # => { user_agent: "my-client/1.0" }
+  #
+  # @example gRPC user-agent (metadata)
+  #   metadata = Nonnative::Header.grpc_user_agent('my-client/1.0')
+  #   # => { "grpc.primary_user_agent" => "my-client/1.0" }
+  #
+  # @example Basic auth header
+  #   headers = Nonnative::Header.auth_basic('user:pass')
+  #   # => { authorization: "Basic dXNlcjpwYXNz" }
+  #
+  # @example Bearer auth header
+  #   headers = Nonnative::Header.auth_bearer('token')
+  #   # => { authorization: "Bearer token" }
+  #
+  # @see https://github.com/rest-client/rest-client RestClient
+  # @see https://grpc.io/docs/guides/concepts/ gRPC concepts (metadata)
   class Header
     class << self
+      # Builds an HTTP `User-Agent` header hash.
+      #
+      # This uses the key style commonly used by RestClient (`user_agent:`).
+      #
+      # @param user_agent [String] user agent value
+      # @return [Hash{Symbol=>String}] header hash containing the user agent
       def http_user_agent(user_agent)
         { user_agent: }
       end
 
+      # Builds gRPC metadata for setting the primary user agent.
+      #
+      # @param user_agent [String] user agent value
+      # @return [Hash{String=>String}] gRPC metadata hash
       def grpc_user_agent(user_agent)
         { 'grpc.primary_user_agent' => user_agent }
       end
 
+      # Builds an HTTP Basic Authorization header.
+      #
+      # The credentials are base64-encoded using strict encoding. The `credentials` string should
+      # typically be in the form `"username:password"`.
+      #
+      # @param credentials [String] basic auth credentials in `"user:pass"` form
+      # @return [Hash{Symbol=>String}] header hash containing the Authorization header
       def auth_basic(credentials)
         { authorization: "Basic #{Base64.strict_encode64(credentials)}" }
       end
 
+      # Builds an HTTP Bearer Authorization header.
+      #
+      # @param token [String] bearer token
+      # @return [Hash{Symbol=>String}] header hash containing the Authorization header
       def auth_bearer(token)
         { authorization: "Bearer #{token}" }
       end

data/lib/nonnative/http_client.rb

@@ -1,7 +1,19 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Minimal RestClient-based HTTP client with consistent exception handling.
+  #
+  # This class is intended to be subclassed by higher-level clients (for example
+  # {Nonnative::Observability}). It provides protected helpers for common HTTP verbs and a retry
+  # wrapper.
+  #
+  # Error handling behavior:
+  # - Timeouts and broken connections (see {#initialize}) are re-raised so callers can handle them explicitly.
+  # - Other `RestClient::Exception` errors return the underlying `response` object.
+  #
+  # @see Nonnative::Observability
   class HTTPClient
+    # @param host [String] base URL used to build request URLs (e.g. `"http://127.0.0.1:8080"`)
     def initialize(host)
       @host = host
       @exceptions = [
@@ -12,34 +24,67 @@ module Nonnative
 
     protected
 
+    # Executes the given block with retries for the configured network exceptions.
+    #
+    # @param tries [Integer] number of attempts
+    # @param wait [Numeric] base interval between retries (seconds)
+    # @yield the work to retry
+    # @return [Object] the block result
     def with_retry(tries, wait, &)
       Retriable.retriable(tries: tries, base_interval: wait, on: exceptions, &)
     end
 
+    # Performs a GET request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param opts [Hash] RestClient request options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def get(pathname, opts = {})
       with_exception do
         resource(pathname, opts).get
       end
     end
 
+    # Performs a POST request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param payload [Object] request payload
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def post(pathname, payload, opts = {})
       with_exception do
         resource(pathname, opts).post(payload)
       end
     end
 
+    # Performs a DELETE request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def delete(pathname, opts = {})
       with_exception do
         resource(pathname, opts).delete
       end
     end
 
+    # Performs a PUT request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param payload [Object] request payload
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def put(pathname, payload, opts = {})
       with_exception do
         resource(pathname, opts).put(payload)
       end
     end
 
+    # Creates a RestClient resource for a relative path.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Resource]
     def resource(pathname, opts)
       RestClient::Resource.new(URI.join(host, pathname).to_s, opts)
     end

data/lib/nonnative/http_proxy_server.rb

@@ -1,8 +1,34 @@
 # frozen_string_literal: true
 
-# Adapted from https://gist.github.com/RaVbaker/d9ead3c92b915f997dab25c7f0c0ab65
+# Sinatra-based HTTP forward proxy server used as an in-process Nonnative server.
+#
+# The proxy receives inbound HTTP requests and forwards them to an upstream host over HTTPS, returning
+# the upstream response status and body.
+#
+# This file defines two classes:
+#
+# - {Nonnative::HTTPProxy}: a Sinatra application that implements the proxying behavior.
+# - {Nonnative::HTTPProxyServer}: a {Nonnative::HTTPServer} wrapper that runs the proxy app under Puma.
+#
+# Notes:
+# - This code is adapted from https://gist.github.com/RaVbaker/d9ead3c92b915f997dab25c7f0c0ab65
+# - Only a subset of request headers are forwarded; certain headers are removed to avoid conflicts.
+#
+# @see Nonnative::HTTPServer
+# @see Nonnative::Server
 module Nonnative
+  # Sinatra application implementing a simple forward proxy.
+  #
+  # The upstream host is configured via Sinatra settings (see {Nonnative::HTTPProxyServer}).
+  #
+  # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
   class HTTPProxy < Sinatra::Application
+    # Extracts request headers from the Rack environment and normalizes them to standard HTTP names.
+    #
+    # Certain hop-by-hop or proxy-specific headers are removed.
+    #
+    # @param request [Sinatra::Request] the incoming request
+    # @return [Hash{String=>String}] headers to forward to the upstream
     def retrieve_headers(request)
       headers = request.env.map do |header, value|
         [header[5..].split('_').map(&:capitalize).join('-'), value] if header.start_with?('HTTP_')
@@ -12,10 +38,21 @@ module Nonnative
       headers.except('Host', 'Accept-Encoding', 'Version')
     end
 
+    # Builds the upstream URL for the given request.
+    #
+    # @param request [Sinatra::Request] the incoming request
+    # @param settings [Sinatra::Base] Sinatra settings, expected to include `host`
+    # @return [String] HTTPS URL for the upstream request
     def build_url(request, settings)
       URI::HTTPS.build(host: settings.host, path: request.path_info, query: request.query_string).to_s
     end
 
+    # Executes the upstream request and returns the response.
+    #
+    # @param verb [String] HTTP verb name (e.g. `"get"`)
+    # @param uri [String] upstream URI
+    # @param opts [Hash] RestClient options (e.g. headers)
+    # @return [RestClient::Response] response for error statuses, otherwise RestClient return value
     def api_response(verb, uri, opts)
       client = RestClient::Resource.new(uri, opts)
 
@@ -36,7 +73,31 @@ module Nonnative
     end
   end
 
+  # Runs {Nonnative::HTTPProxy} as a Puma-based in-process server under Nonnative.
+  #
+  # @example
+  #   Nonnative.configure do |config|
+  #     config.server do |s|
+  #       s.name = 'github-proxy'
+  #       s.klass = Nonnative::Features::HTTPProxyServer
+  #       s.timeout = 2
+  #       s.host = '127.0.0.1'
+  #       s.port = 4567
+  #       s.log = 'proxy.log'
+  #     end
+  #   end
+  #
+  #   # In your server subclass:
+  #   # class HTTPProxyServer < Nonnative::HTTPProxyServer
+  #   #   def initialize(service)
+  #   #     super('api.github.com', service)
+  #   #   end
+  #   # end
+  #
+  # @see Nonnative::HTTPServer
   class HTTPProxyServer < Nonnative::HTTPServer
+    # @param host [String] upstream host to proxy to (HTTPS)
+    # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(host, service)
       app = Sinatra.new(Nonnative::HTTPProxy) do
         configure do

data/lib/nonnative/http_server.rb

@@ -1,7 +1,38 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Puma-based HTTP server runner.
+  #
+  # This is a convenience server implementation for running a Rack/Sinatra application in-process
+  # under Nonnative's server lifecycle. It binds to the configured proxy `host`/`port` (so it works
+  # consistently with proxy configuration) and uses Puma for HTTP serving.
+  #
+  # The server is started and stopped by {Nonnative::Server} via {#perform_start} / {#perform_stop}.
+  #
+  # @example Running a Sinatra app
+  #   app = Sinatra.new do
+  #     get('/hello') { 'Hello World!' }
+  #   end
+  #
+  #   Nonnative.configure do |config|
+  #     config.server do |s|
+  #       s.name = 'http'
+  #       s.klass = ->(service) { Nonnative::HTTPServer.new(app, service) }
+  #       s.timeout = 2
+  #       s.host = '127.0.0.1'
+  #       s.port = 4567
+  #       s.log = 'http.log'
+  #     end
+  #   end
+  #
+  # Note: In YAML configuration you typically set `class` to a concrete subclass that calls `super(app, service)`.
+  #
+  # @see Nonnative::Server
   class HTTPServer < Nonnative::Server
+    # Creates a Puma server for the given Rack app and runner configuration.
+    #
+    # @param app [#call] a Rack-compatible application (e.g. Sinatra/Rack app)
+    # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(app, service)
       log = File.open(service.log, 'a')
       options = {
@@ -15,11 +46,20 @@ module Nonnative
 
     protected
 
+    # Binds the Puma server and begins serving.
+    #
+    # The listener binds to the proxy host/port so that enabling a proxy results in traffic and
+    # readiness checks consistently targeting the proxy endpoint.
+    #
+    # @return [void]
     def perform_start
       server.add_tcp_listener proxy.host, proxy.port
       server.run false
     end
 
+    # Gracefully shuts down the Puma server.
+    #
+    # @return [void]
     def perform_stop
       server.graceful_shutdown
     end

data/lib/nonnative/invalid_data_socket_pair.rb

@@ -1,7 +1,22 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate corrupted/incoherent traffic.
+  #
+  # When active, data written to the upstream socket is corrupted by shuffling the characters in the
+  # payload before forwarding.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#invalid_data}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
   class InvalidDataSocketPair < SocketPair
+    # Writes corrupted data to the socket by shuffling characters.
+    #
+    # @param socket [IO] the socket to write to
+    # @param data [String] the original payload
+    # @return [Integer] number of bytes written
     def write(socket, data)
       Nonnative.logger.info "shuffling socket data '#{socket.inspect}' for 'invalid_data' pair"
 

data/lib/nonnative/no_proxy.rb

@@ -1,23 +1,58 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # No-op proxy implementation.
+  #
+  # This is the default proxy when `service.proxy.kind` is `"none"` (or an unknown kind is provided).
+  # It does not bind/listen or alter traffic; it simply exposes the underlying runner's configured
+  # `host` and `port`.
+  #
+  # Runners can always call `start`, `stop`, and `reset` safely on this proxy.
+  #
+  # @see Nonnative.proxy
+  # @see Nonnative::Proxy
   class NoProxy < Proxy
+    # Starts the proxy.
+    #
+    # This implementation does nothing.
+    #
+    # @return [void]
     def start
       # Do nothing.
     end
 
+    # Stops the proxy.
+    #
+    # This implementation does nothing.
+    #
+    # @return [void]
     def stop
       # Do nothing.
     end
 
+    # Resets the proxy state.
+    #
+    # This implementation does nothing.
+    #
+    # @return [void]
     def reset
       # Do nothing.
     end
 
+    # Returns the host clients should connect to.
+    #
+    # For {NoProxy}, this is the underlying runner configuration host.
+    #
+    # @return [String]
     def host
       service.host
     end
 
+    # Returns the port clients should connect to.
+    #
+    # For {NoProxy}, this is the underlying runner configuration port.
+    #
+    # @return [Integer]
     def port
       service.port
     end

data/lib/nonnative/not_found_error.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Raised when a configured runner cannot be found by name.
+  #
+  # This is typically raised by lookup helpers such as:
+  # - {Nonnative::Configuration#process_by_name}
+  # - {Nonnative::Pool#process_by_name}
+  # - {Nonnative::Pool#server_by_name}
+  # - {Nonnative::Pool#service_by_name}
   class NotFoundError < Nonnative::Error
   end
 end

data/lib/nonnative/observability.rb

@@ -1,25 +1,69 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # HTTP client for common observability endpoints exposed by the system under test.
+  #
+  # This client is returned by {Nonnative.observability} and builds endpoint paths from
+  # {Nonnative::Configuration#name}.
+  #
+  # Endpoints:
+  # - `/<name>/healthz`
+  # - `/<name>/livez`
+  # - `/<name>/readyz`
+  # - `/<name>/metrics`
+  #
+  # Requests are performed using {Nonnative::HTTPClient}, so callers may pass RestClient options
+  # such as `headers`, `open_timeout`, and `read_timeout`.
+  #
+  # @example
+  #   Nonnative.configure do |config|
+  #     config.name = 'my-service'
+  #     config.url = 'http://127.0.0.1:8080'
+  #   end
+  #
+  #   response = Nonnative.observability.health(read_timeout: 2, open_timeout: 2)
+  #   response.code # => 200
+  #
+  # @see Nonnative.observability
+  # @see Nonnative::HTTPClient
   class Observability < Nonnative::HTTPClient
+    # Calls `/<name>/healthz`.
+    #
+    # @param opts [Hash] RestClient options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def health(opts = {})
       get("#{name}/healthz", opts)
     end
 
+    # Calls `/<name>/livez`.
+    #
+    # @param opts [Hash] RestClient options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def liveness(opts = {})
       get("#{name}/livez", opts)
     end
 
+    # Calls `/<name>/readyz`.
+    #
+    # @param opts [Hash] RestClient options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def readiness(opts = {})
       get("#{name}/readyz", opts)
     end
 
+    # Calls `/<name>/metrics`.
+    #
+    # @param opts [Hash] RestClient options (e.g. `headers`, `read_timeout`, `open_timeout`)
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
     def metrics(opts = {})
       get("#{name}/metrics", opts)
     end
 
     protected
 
+    # Returns the configured system name used as the endpoint prefix.
+    #
+    # @return [String, nil]
     def name
       Nonnative.configuration.name
     end

data/lib/nonnative/pool.rb

@@ -1,33 +1,83 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Orchestrates lifecycle for configured processes, servers and services.
+  #
+  # A pool is created when {Nonnative.start} is called and is accessible via {Nonnative.pool}.
+  #
+  # Lifecycle order is important:
+  # - On start: services first, then servers/processes (in parallel port-check threads)
+  # - On stop: processes/servers first, then services
+  #
+  # Readiness and shutdown are determined via TCP port checks ({Nonnative::Port#open?} / {Nonnative::Port#closed?}).
+  #
+  # @see Nonnative.start
+  # @see Nonnative.stop
+  # @see Nonnative::Port
   class Pool
+    # @param configuration [Nonnative::Configuration] the configuration to run
     def initialize(configuration)
       @configuration = configuration
     end
 
+    # 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.
+    #
+    # @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)
+    # @return [void]
     def start(&)
       services.each(&:start)
       [servers, processes].each { |t| process(t, :start, :open?, &) }
     end
 
+    # Stops all configured runners and yields results for each process/server.
+    #
+    # Processes and servers are stopped first and checked for shutdown, then services are stopped (proxy-only).
+    #
+    # @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)
+    # @return [void]
     def stop(&)
       [processes, servers].each { |t| process(t, :stop, :closed?, &) }
       services.each(&:stop)
     end
 
+    # Finds a running process runner by configured name.
+    #
+    # @param name [String]
+    # @return [Nonnative::Process]
+    # @raise [Nonnative::NotFoundError] if no configured process matches the given name
     def process_by_name(name)
       processes[runner_index(configuration.processes, name)].first
     end
 
+    # Finds a running server runner by configured name.
+    #
+    # @param name [String]
+    # @return [Nonnative::Server]
+    # @raise [Nonnative::NotFoundError] if no configured server matches the given name
     def server_by_name(name)
       servers[runner_index(configuration.servers, name)].first
     end
 
+    # Finds a running service runner by configured name.
+    #
+    # @param name [String]
+    # @return [Nonnative::Service]
+    # @raise [Nonnative::NotFoundError] if no configured service matches the given name
     def service_by_name(name)
       services[runner_index(configuration.services, name)]
     end
 
+    # Resets proxies for all runners in this pool.
+    #
+    # This is used by the Cucumber `@reset` hook and is safe to call any time after the pool is created.
+    #
+    # @return [void]
     def reset
       services.each { |s| s.proxy.reset }
       servers.each { |s| s.first.proxy.reset }

data/lib/nonnative/port.rb

@@ -1,12 +1,32 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Performs TCP port readiness/shutdown checks for a configured runner.
+  #
+  # Nonnative uses this to decide whether a process/server is ready after start, and whether it has
+  # shut down after stop. The checks repeatedly attempt to open a TCP connection to `process.host`
+  # and `process.port` until either:
+  #
+  # - the expected condition is met, or
+  # - the configured timeout elapses (in which case the method returns `false`)
+  #
+  # The `process` argument is a runner configuration object (e.g. {Nonnative::ConfigurationProcess}
+  # or {Nonnative::ConfigurationServer}) that responds to `host`, `port`, and `timeout`.
+  #
+  # @see Nonnative::Pool for how these checks are orchestrated during start/stop
   class Port
+    # @param process [#host, #port, #timeout] runner configuration providing connection details
     def initialize(process)
       @process = process
       @timeout = Nonnative::Timeout.new(process.timeout)
     end
 
+    # Returns whether the configured host/port becomes connectable before the timeout elapses.
+    #
+    # This method retries on common connection errors until either a connection succeeds
+    # (returns `true`) or the timeout elapses (returns `false`).
+    #
+    # @return [Boolean] `true` if the port opened in time; otherwise `false`
     def open?
       Nonnative.logger.info "checking if port '#{process.port}' is open on host '#{process.host}'"
 
@@ -19,6 +39,12 @@ module Nonnative
       end
     end
 
+    # Returns whether the configured host/port becomes non-connectable before the timeout elapses.
+    #
+    # This method treats a successful connection as “not closed yet” and keeps retrying until it
+    # observes connection failure (returns `true`) or the timeout elapses (returns `false`).
+    #
+    # @return [Boolean] `true` if the port closed in time; otherwise `false`
     def closed?
       Nonnative.logger.info "checking if port '#{process.port}' is closed on host '#{process.host}'"