nonnative 1.107.0 → 1.108.0

data/README.md

@@ -5,15 +5,15 @@
 
 # Nonnative
 
-Do you love building microservices using different languages?
+Nonnative is a Ruby-first harness for end-to-end testing of systems implemented in other languages.
 
-Do you love testing applications using [cucumber](https://cucumber.io/) with [ruby](https://www.ruby-lang.org/en/)?
+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 **proxies** in front of processes/servers/services for fault-injection,
+- wait for readiness/shutdown using **TCP port checks**.
 
-Well so do I. The issue is that most languages the cucumber implementation is not always complete or you have to write a lot of code to get it working.
-
-So why not test the way you want and build the microservice how you want. These kind of tests will make sure your application is tested properly by going end-to-end.
-
-The way it works is it spawns processes or servers you configure and waits for it to start. Then you communicate with your microservice however you like (TCP, HTTP, gRPC, etc)
+Once started, you can test however you like (TCP, HTTP, gRPC, etc).
 
 ## Installation
 
@@ -37,27 +37,38 @@ gem install nonnative
 
 ## Usage
 
-Configure nonnative with the following:
+Nonnative is configured via {#Nonnative.configure} (programmatic) or `config.load_file(...)` (YAML).
+
+High-level configuration fields:
+- `version`: configuration version (example: `"1.0"`).
+- `name`: logical system name (used by `Nonnative.observability` for `/<name>/healthz`, etc).
+- `url`: base URL for observability queries (example: `http://localhost:4567`).
+- `log`: path for the Nonnative logger output.
+- `processes`: child processes to `spawn`.
+- `servers`: in-process Ruby servers started in threads.
+- `services`: external dependencies (proxy-only; no process/thread started by Nonnative).
 
-- The version of the configuration (1.0).
-- The name of the service.
-- The URL of the service.
-- A log file.
-- Process, Server or Service that you want to start.
-- A timeout value.
-- A time to wait.
-- Port to verify.
-- The class for servers.
-- The log for servers/processes
-- The strategy for processes, servers and services.
+Runner fields (process/server/service):
+- `timeout`: max time (seconds) for readiness/shutdown port checks.
+- `wait`: small sleep (seconds) between lifecycle steps.
+- `host`/`port`: address used for port checks; when a proxy is enabled, reads happen via the proxy.
+- `log`: per-runner log file (used by process output redirection or server implementations).
 
-### Strategy
+### Lifecycle strategies (Cucumber integration)
 
-The strategy can be one of the following values:
+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)
+- `@clear`: clears memoized configuration and pool before scenario
+- `@reset`: resets proxies after scenario
 
-- startup - When we include `nonnative/startup`, it will start it once.
-- before - When we tag our features with `@startup` it will start and stop after the scenario.
-- manual - When we tag our features with `@manual` it will stop after the scenario.
+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
 
@@ -443,9 +454,9 @@ end
 
 ### Services
 
-A service is an external dependency to your system. This is usually an expensive process to start like a DB and you would prefer to be managed externally. Services are not really exciting by themselves, it's when we add proxies that they allow us to do some extra work.
+A service is an external dependency to your system that you **do not** want Nonnative to start (no OS process, no Ruby thread). Services are primarily useful when paired with proxies, because they let you inject failures into dependencies that are managed elsewhere (e.g. a DB running in Docker).
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -458,33 +469,37 @@ Nonnative.configure do |config|
 
   config.service do |s|
     s.name = 'postgres'
-    p.port = 5432
+    s.host = '127.0.0.1'
+    s.port = 5432
   end
 
   config.service do |s|
     s.name = 'redis'
+    s.host = '127.0.0.1'
     s.port = 6379
   end
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration (YAML):
 
 ```yaml
 version: "1.0"
 name: test
 url: http://localhost:4567
 log: nonnative.log
-processes:
+services:
   -
     name: postgres
+    host: 127.0.0.1
     port: 5432
   -
     name: redis
+    host: 127.0.0.1
     port: 6379
 ```
 
-Then load the file with
+Then load the file with:
 
 ```ruby
 require 'nonnative'
@@ -593,7 +608,7 @@ servers:
 
 ##### Proxies Services
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -603,11 +618,15 @@ Nonnative.configure do |config|
   config.name = 'test'
   config.url = 'http://localhost:4567'
   config.log = 'nonnative.log'
-  config.wait = 1
 
   config.service do |s|
+    s.name = 'redis'
+    s.host = '127.0.0.1'
+    s.port = 6379
+
     s.proxy = {
       kind: 'fault_injection',
+      host: '127.0.0.1',
       port: 20_000,
       log: 'proxy_server.log',
       wait: 1,

data/lib/nonnative/close_all_socket_pair.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate immediate connection failure.
+  #
+  # When active, the proxy accepts a TCP connection and closes it immediately without forwarding any
+  # bytes to the upstream service.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#close_all}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
   class CloseAllSocketPair < SocketPair
+    # Closes the accepted socket immediately.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
     def connect(local_socket)
       Nonnative.logger.info "closing socket '#{local_socket.inspect}' for 'close_all' pair"
 

data/lib/nonnative/configuration.rb

@@ -1,15 +1,62 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # The gem configuration object.
+  #
+  # You can populate configuration either programmatically via the DSL ({#process}, {#server}, {#service}),
+  # or by loading a YAML file via {#load_file}.
+  #
+  # The configuration is consumed when {Nonnative.start} is called.
+  #
+  # == Programmatic configuration
+  #
+  #   Nonnative.configure do |config|
+  #     config.name = 'example'
+  #     config.url = 'http://127.0.0.1:8080'
+  #     config.log = 'test.log'
+  #
+  #     config.process do |p|
+  #       p.name = 'api'
+  #       p.command = -> { './bin/api' }
+  #       p.host = '127.0.0.1'
+  #       p.port = 8080
+  #       p.timeout = 10
+  #       p.log = 'api.log'
+  #     end
+  #   end
+  #
+  # == File-based configuration
+  #
+  #   Nonnative.configure do |config|
+  #     config.load_file('features/configs/processes.yml')
+  #   end
+  #
   class Configuration
+    # Creates an empty configuration.
+    #
+    # @return [void]
     def initialize
       @processes = []
       @servers = []
       @services = []
     end
 
+    # @return [String, nil] logical system name (used for observability endpoints)
+    # @return [String, nil] configuration version
+    # @return [String, nil] base URL for observability queries (for example `"http://127.0.0.1:8080"`)
+    # @return [String, nil] path to the Nonnative log file
+    # @return [Array<Nonnative::ConfigurationProcess>] configured processes
+    # @return [Array<Nonnative::ConfigurationServer>] configured in-process servers
+    # @return [Array<Nonnative::ConfigurationService>] configured services (proxy-only)
     attr_accessor :name, :version, :url, :log, :processes, :servers, :services
 
+    # Loads a configuration file and appends its runners to this instance.
+    #
+    # The file is loaded using the `config` gem via {Nonnative.configurations}. Top-level attributes are
+    # copied onto this object, and runner sections are transformed into configuration runner objects.
+    #
+    # @param path [String] path to a configuration file (typically YAML)
+    # @return [void]
     def load_file(path)
       cfg = Nonnative.configurations(path)
 
@@ -23,6 +70,10 @@ module Nonnative
       add_services(cfg)
     end
 
+    # Adds a process configuration entry.
+    #
+    # @yieldparam process [Nonnative::ConfigurationProcess]
+    # @return [void]
     def process
       process = Nonnative::ConfigurationProcess.new
       yield process
@@ -30,6 +81,10 @@ module Nonnative
       processes << process
     end
 
+    # Adds a server configuration entry.
+    #
+    # @yieldparam server [Nonnative::ConfigurationServer]
+    # @return [void]
     def server
       server = Nonnative::ConfigurationServer.new
       yield server
@@ -37,6 +92,13 @@ module Nonnative
       servers << server
     end
 
+    # Adds a service configuration entry.
+    #
+    # A "service" does not manage a Ruby thread or OS process; it exists so that a proxy can be started
+    # and controlled for an external dependency.
+    #
+    # @yieldparam service [Nonnative::ConfigurationService]
+    # @return [void]
     def service
       service = Nonnative::ConfigurationService.new
       yield service
@@ -44,6 +106,11 @@ module Nonnative
       services << service
     end
 
+    # Finds a configured process by name.
+    #
+    # @param name [String]
+    # @return [Nonnative::ConfigurationProcess]
+    # @raise [Nonnative::NotFoundError] if no matching process exists
     def process_by_name(name)
       process = processes.find { |s| s.name == name }
       raise NotFoundError, "Could not find process with name '#{name}'" if process.nil?

data/lib/nonnative/configuration_process.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Process-specific configuration.
+  #
+  # A "process" is an OS-level child process started via `spawn` and stopped via signals.
+  # It is managed by {Nonnative::Process} at runtime.
+  #
+  # Instances are usually created through {Nonnative::Configuration#process}.
+  #
+  # @see Nonnative::Configuration
+  # @see Nonnative::Process
   class ConfigurationProcess < ConfigurationRunner
+    # @return [Proc] a callable that returns the command string to execute (e.g. `-> { "./bin/api" }`)
+    # @return [String, nil] signal name to use for stopping (defaults to `"INT"` when not set)
+    # @return [Numeric] readiness timeout (seconds) used when waiting for the port to open/close
+    # @return [String] log file path to append process stdout/stderr to
+    # @return [Hash, nil] environment variables to pass to the spawned process
     attr_accessor :command, :signal, :timeout, :log, :environment
   end
 end

data/lib/nonnative/configuration_proxy.rb

@@ -1,9 +1,37 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Proxy configuration attached to a runner 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.
+  #
+  # This object is created automatically for each runner via {Nonnative::ConfigurationRunner}.
+  # When `kind` is set to `"none"`, no proxy is started and the runner will use its configured
+  # `host`/`port` directly.
+  #
+  # @see Nonnative::ConfigurationRunner#proxy
+  # @see Nonnative.proxies
   class ConfigurationProxy
+    # @return [String] proxy kind name (for example `"none"` or `"fault_injection"`)
+    # @return [String] proxy bind host (defaults to `"0.0.0.0"`)
+    # @return [Integer] proxy bind port (defaults to `0`)
+    # @return [String, nil] path to proxy log file (implementation-dependent)
+    # @return [Numeric] wait interval (seconds) after proxy state changes (defaults to `0.1`)
+    # @return [Hash] proxy implementation options (implementation-dependent)
     attr_accessor :kind, :host, :port, :log, :wait, :options
 
+    # Creates a proxy configuration with defaults.
+    #
+    # Defaults:
+    # - `kind`: `"none"`
+    # - `host`: `"0.0.0.0"`
+    # - `port`: `0`
+    # - `wait`: `0.1`
+    # - `options`: `{}`
+    #
+    # @return [void]
     def initialize
       self.kind = 'none'
       self.host = '0.0.0.0'

data/lib/nonnative/configuration_runner.rb

@@ -1,10 +1,41 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Base configuration for a runnable unit managed by Nonnative.
+  #
+  # This class holds connection and timing attributes common to processes, servers and services,
+  # as well as a nested {Nonnative::ConfigurationProxy} describing how/if a proxy should be started.
+  #
+  # Instances of this type are typically created via {Nonnative::Configuration#process},
+  # {Nonnative::Configuration#server}, or {Nonnative::Configuration#service}.
+  #
+  # @see Nonnative::ConfigurationProcess
+  # @see Nonnative::ConfigurationServer
+  # @see Nonnative::ConfigurationService
   class ConfigurationRunner
+    # @return [String, nil] runner name used for lookup (for example via `pool.process_by_name`)
+    # @return [String] host to bind/connect to (defaults to `"0.0.0.0"`)
+    # @return [Integer] port to bind/connect to
+    # @return [Numeric] wait interval (seconds) used by runners between lifecycle steps
     attr_accessor :name, :host, :port, :wait
+
+    # Proxy configuration for this runner.
+    #
+    # Note that this returns a configuration object even if no proxy is enabled; by default
+    # the proxy kind is `"none"`.
+    #
+    # @return [Nonnative::ConfigurationProxy]
     attr_reader :proxy
 
+    # Creates a runner configuration with defaults.
+    #
+    # Defaults:
+    # - `host`: `"0.0.0.0"`
+    # - `port`: `0`
+    # - `wait`: `0.1`
+    # - `proxy`: a new {Nonnative::ConfigurationProxy} with its own defaults
+    #
+    # @return [void]
     def initialize
       self.host = '0.0.0.0'
       self.port = 0
@@ -13,6 +44,19 @@ module Nonnative
       @proxy = Nonnative::ConfigurationProxy.new
     end
 
+    # Sets proxy configuration using a hash-like value.
+    #
+    # This is primarily used when loading YAML configuration files, where proxy attributes are
+    # represented as scalar values.
+    #
+    # @param value [Hash] proxy attributes
+    # @option value [String] :kind proxy kind name (for example `"fault_injection"`)
+    # @option value [String] :host proxy bind host (optional)
+    # @option value [Integer] :port proxy bind port
+    # @option value [String] :log proxy log file path
+    # @option value [Numeric] :wait wait interval (seconds) after state changes (optional)
+    # @option value [Hash] :options proxy implementation specific options
+    # @return [void]
     def proxy=(value)
       proxy.kind = value[:kind]
       proxy.host = value[:host] if value[:host]

data/lib/nonnative/configuration_server.rb

@@ -1,7 +1,19 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Server-specific configuration.
+  #
+  # A "server" is an in-process Ruby component started in a background thread and stopped via a
+  # server-specific shutdown routine. It is managed by {Nonnative::Server} at runtime.
+  #
+  # Instances are usually created through {Nonnative::Configuration#server}.
+  #
+  # @see Nonnative::Configuration
+  # @see Nonnative::Server
   class ConfigurationServer < ConfigurationRunner
+    # @return [Class] a class that implements `#initialize(service)`, and lifecycle hooks expected by {Nonnative::Server}
+    # @return [Numeric] readiness timeout (seconds) used when waiting for the port to open/close
+    # @return [String] log file path used by server implementations (for example Puma/gRPC log files)
     attr_accessor :klass, :timeout, :log
   end
 end

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/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