nonnative 1.107.0 → 1.109.0

data/lib/nonnative/configuration_service.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Service-specific configuration.
+  #
+  # A "service" is proxy-only: it does not start a Ruby thread or OS process. It exists so Nonnative can
+  # start and control a proxy in front of an external dependency.
+  #
+  # Instances are usually created through {Nonnative::Configuration#service}.
+  #
+  # @see Nonnative::Configuration
+  # @see Nonnative::Service
   class ConfigurationService < ConfigurationRunner
   end
 end

data/lib/nonnative/cucumber.rb

@@ -49,12 +49,8 @@ Given('I should see {string} as unhealthy') do |service|
     read_timeout: 10, open_timeout: 10
   }
 
-  wait_for do
-    @response = Nonnative.observability.health(opts)
-    @response.code
-  end.to eq(503)
-
-  expect(@response.body).to include(service)
+  wait_for { Nonnative.observability.health(opts).code }.to eq(503)
+  wait_for { Nonnative.observability.health(opts).body }.to include(service)
 end
 
 Then('I should reset the proxy for process {string}') do |name|
@@ -104,10 +100,6 @@ Then('I should see {string} as healthy') do |service|
     read_timeout: 10, open_timeout: 10
   }
 
-  wait_for do
-    @response = Nonnative.observability.health(opts)
-    @response.code
-  end.to eq(200)
-
-  expect(@response.body).to_not include(service)
+  wait_for { Nonnative.observability.health(opts).code }.to eq(200)
+  wait_for { Nonnative.observability.health(opts).body }.to_not include(service)
 end

data/lib/nonnative/delay_socket_pair.rb

@@ -1,7 +1,22 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate slow or stalled connections.
+  #
+  # When active, reads from the socket are delayed by a configured duration before being forwarded.
+  #
+  # The delay duration is controlled by `proxy.options[:delay]` and defaults to 2 seconds.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#delay}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
   class DelaySocketPair < SocketPair
+    # Reads from the socket after sleeping for the configured delay duration.
+    #
+    # @param socket [IO] the socket to read from
+    # @return [String] the bytes read from the socket
     def read(socket)
       Nonnative.logger.info "delaying socket '#{socket.inspect}' for 'delay' pair"
 

data/lib/nonnative/error.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Base class for all Nonnative errors.
+  #
+  # Catch this error type if you want to handle any exception raised by this gem.
+  #
+  # @see Nonnative::StartError
+  # @see Nonnative::StopError
+  # @see Nonnative::NotFoundError
   class Error < StandardError
   end
 end

data/lib/nonnative/fault_injection_proxy.rb

@@ -1,7 +1,41 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Fault-injection proxy for TCP services.
+  #
+  # This proxy accepts incoming TCP connections and forwards traffic to the configured upstream
+  # (`service.proxy.host` / `service.proxy.port`) via a socket-pair implementation. It can also inject
+  # failures to help validate client resilience.
+  #
+  # This class exposes a small public control surface for tests:
+  #
+  # - {#close_all}: close connections immediately on accept
+  # - {#delay}: delay reads by a configured duration (default: 2 seconds)
+  # - {#invalid_data}: corrupt outbound data by shuffling characters
+  # - {#reset}: return to healthy pass-through behavior
+  #
+  # State changes terminate any active connections so new connections observe the new behavior.
+  #
+  # ## Wiring
+  #
+  # When enabled, your test/client should typically connect to {#host}:{#port} (the proxy endpoint),
+  # and the proxy will connect onward to the underlying service.
+  #
+  # ## Configuration
+  #
+  # The proxy is configured via the runner’s `proxy` hash:
+  #
+  # - `kind`: `"fault_injection"`
+  # - `host` / `port`: where the proxy should be reached by clients (exposed via {#host}/{#port})
+  # - `log`: file path used by this proxy’s internal logger
+  # - `wait`: sleep interval (seconds) applied after state changes
+  # - `options`:
+  #   - `delay`: delay duration in seconds used by {#delay}
+  #
+  # @see Nonnative::Proxy
+  # @see Nonnative::SocketPairFactory
   class FaultInjectionProxy < Nonnative::Proxy
+    # @param service [Nonnative::ConfigurationRunner] runner configuration with proxy settings
     def initialize(service)
       @connections = Concurrent::Hash.new
       @logger = Logger.new(service.proxy.log)
@@ -11,6 +45,12 @@ module Nonnative
       super
     end
 
+    # Starts the proxy accept loop in a background thread.
+    #
+    # This binds a TCP server on the underlying runner’s `service.host` / `service.port`.
+    # Clients should connect to {#host}:{#port}.
+    #
+    # @return [void]
     def start
       @tcp_server = ::TCPServer.new(service.host, service.port)
       @thread = Thread.new { perform_start }
@@ -18,6 +58,9 @@ module Nonnative
       Nonnative.logger.info "started with host '#{service.host}' and port '#{service.port}' for proxy 'fault_injection'"
     end
 
+    # Stops the proxy and closes its listening socket.
+    #
+    # @return [void]
     def stop
       thread&.terminate
       tcp_server&.close
@@ -25,26 +68,46 @@ module Nonnative
       Nonnative.logger.info "stopped with host '#{service.host}' and port '#{service.port}' for proxy 'fault_injection'"
     end
 
+    # Forces new connections to be closed immediately.
+    #
+    # @return [void]
     def close_all
       apply_state :close_all
     end
 
+    # Delays reads before forwarding.
+    #
+    # The delay duration is controlled by `service.proxy.options[:delay]` and defaults to 2 seconds.
+    #
+    # @return [void]
     def delay
       apply_state :delay
     end
 
+    # Corrupts forwarded data by shuffling characters.
+    #
+    # @return [void]
     def invalid_data
       apply_state :invalid_data
     end
 
+    # Resets the proxy back to healthy pass-through behavior.
+    #
+    # @return [void]
     def reset
       apply_state :none
     end
 
+    # Returns the host clients should connect to when using this proxy.
+    #
+    # @return [String]
     def host
       service.proxy.host
     end
 
+    # Returns the port clients should connect to when using this proxy.
+    #
+    # @return [Integer]
     def port
       service.proxy.port
     end

data/lib/nonnative/go_command.rb

@@ -1,13 +1,47 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Builds command lines for running a Go test binary with optional profiling/trace/coverage flags.
+  #
+  # This helper is used by {Nonnative.go_executable} and by YAML configuration when a process has a
+  # `go:` section (see {Nonnative::Configuration}).
+  #
+  # The generated flags use Go's `testing` package flags (e.g. `-test.cpuprofile=...`), so this
+  # is intended to run a binary compiled from `go test -c`.
+  #
+  # ## Tools
+  #
+  # Tools can be enabled/disabled via the `tools` list. Supported values:
+  #
+  # - `"prof"`: cpu/mem/block/mutex profiles
+  # - `"trace"`: execution trace output
+  # - `"cover"`: coverage profile output
+  #
+  # If `tools` is `nil` or empty, all tools (`prof`, `trace`, `cover`) are enabled.
+  #
+  # @example
+  #   cmd = Nonnative::GoCommand.new(%w[prof cover], './svc.test', 'reports')
+  #   cmd.executable('serve', '--config', 'config.yaml')
+  #   # => "./svc.test -test.cpuprofile=... -test.coverprofile=... serve --config config.yaml"
+  #
+  # @see Nonnative.go_executable
   class GoCommand
+    # @param tools [Array<String>, nil] tool names to enable (see class docs)
+    # @param exec [String] path to the compiled Go test binary
+    # @param output [String] output directory for generated files
     def initialize(tools, exec, output)
       @tools = tools.nil? || tools.empty? ? %w[prof trace cover] : tools
       @exec = exec
       @output = output
     end
 
+    # Returns an executable command string including enabled `-test.*` flags.
+    #
+    # A short random suffix is appended to output filenames to reduce collisions across runs.
+    #
+    # @param cmd [String] command/sub-command argument passed to the Go test binary
+    # @param params [Array<String>] additional parameters passed after `cmd`
+    # @return [String] the full command to execute
     def executable(cmd, *params)
       params = params.join(' ')
       "#{exec} #{flags(cmd).join(' ')} #{cmd} #{params}".strip

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