nonnative 1.107.0 → 1.109.0

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}'"
 

data/lib/nonnative/process.rb

@@ -1,13 +1,32 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Runtime runner that manages an OS-level child process.
+  #
+  # A process runner:
+  # - starts the configured proxy (if any),
+  # - spawns a child process using the configured command and environment,
+  # - waits briefly (via the runner `wait`), and
+  # - participates in readiness/shutdown via TCP port checks orchestrated by {Nonnative::Pool}.
+  #
+  # The underlying configuration is a {Nonnative::ConfigurationProcess}.
+  #
+  # @see Nonnative::ConfigurationProcess
+  # @see Nonnative::Pool
   class Process < Runner
+    # @param service [Nonnative::ConfigurationProcess] process configuration
     def initialize(service)
       super
 
       @timeout = Nonnative::Timeout.new(service.timeout)
     end
 
+    # Starts the proxy (if any) and spawns the configured process if it is not already running.
+    #
+    # @return [Array<(Integer, Boolean)>]
+    #   a tuple of:
+    #   - the spawned process id (pid)
+    #   - whether the process appears to still be running (non-blocking wait result)
     def start
       unless process_exists?
         proxy.start
@@ -18,6 +37,11 @@ module Nonnative
       [pid, ::Process.waitpid2(pid, ::Process::WNOHANG).nil?]
     end
 
+    # Stops the process (if running) and stops the proxy (if any).
+    #
+    # The process is signalled using the configured signal (defaults to `INT` when not set).
+    #
+    # @return [Integer, nil] the pid that was stopped (or `nil` if the process was never started)
     def stop
       if process_exists?
         process_kill
@@ -28,6 +52,11 @@ module Nonnative
       pid
     end
 
+    # Returns a memoized memory reader for the spawned process.
+    #
+    # This is primarily used by acceptance tests to assert memory usage.
+    #
+    # @return [GetProcessMem, nil] a memory reader for the pid, or `nil` if not started
     def memory
       return if pid.nil?
 

data/lib/nonnative/proxy.rb

@@ -1,15 +1,39 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Base class for proxy implementations.
+  #
+  # A proxy is responsible for interposing behavior between a client and a target service.
+  # Runners ({Nonnative::Process}, {Nonnative::Server}, and {Nonnative::Service}) create a proxy
+  # instance via {Nonnative::ProxyFactory} based on `service.proxy.kind`.
+  #
+  # Concrete proxies typically implement these public methods:
+  # - `start`: begin proxying (bind/listen, start threads, etc)
+  # - `stop`: stop proxying and release resources
+  # - `reset`: return proxy behavior to a healthy/default state
+  # - `host` / `port`: endpoint clients should connect to when the proxy is enabled
+  #
+  # @see Nonnative::ProxyFactory
+  # @see Nonnative::NoProxy
+  # @see Nonnative::FaultInjectionProxy
   class Proxy
+    # @param service [Nonnative::ConfigurationRunner] runner configuration with an attached proxy configuration
     def initialize(service)
       @service = service
     end
 
     protected
 
+    # Returns the underlying runner configuration.
+    #
+    # @return [Nonnative::ConfigurationRunner]
     attr_reader :service
 
+    # Sleeps for the proxy wait interval configured on `service.proxy.wait`.
+    #
+    # Proxies can use this to allow state transitions to take effect.
+    #
+    # @return [void]
     def wait
       sleep service.proxy.wait
     end

data/lib/nonnative/proxy_factory.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Factory for creating proxy instances for runners.
+  #
+  # Each runtime runner ({Nonnative::Process}, {Nonnative::Server}, {Nonnative::Service}) constructs
+  # a proxy via this factory. The proxy implementation is selected by `service.proxy.kind` and resolved
+  # using {Nonnative.proxy}.
+  #
+  # If the kind is unknown (or `"none"`), {Nonnative.proxy} returns {Nonnative::NoProxy}.
+  #
+  # @see Nonnative.proxy
+  # @see Nonnative.proxies
+  # @see Nonnative::Proxy
+  # @see Nonnative::NoProxy
   class ProxyFactory
     class << self
+      # Creates a proxy instance for the given runner configuration.
+      #
+      # @param service [Nonnative::ConfigurationRunner] runner configuration with an attached proxy configuration
+      # @return [Nonnative::Proxy] proxy instance (may be a {Nonnative::NoProxy})
       def create(service)
         proxy = Nonnative.proxy(service.proxy.kind)
 

data/lib/nonnative/runner.rb

@@ -1,26 +1,56 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Base runtime wrapper for a configured runnable unit.
+  #
+  # A runner wraps a configuration object (a subclass of {Nonnative::ConfigurationRunner}) and
+  # exposes lifecycle behavior via specialized subclasses:
+  #
+  # - {Nonnative::Process} for OS-level child processes
+  # - {Nonnative::Server} for in-process Ruby servers (threads)
+  # - {Nonnative::Service} for proxy-only external dependencies
+  #
+  # Each runner has an associated proxy instance created via {Nonnative::ProxyFactory}.
+  #
+  # @see Nonnative::Process
+  # @see Nonnative::Server
+  # @see Nonnative::Service
   class Runner
+    # Returns the proxy instance for this runner.
+    #
+    # @return [Nonnative::Proxy]
     attr_reader :proxy
 
+    # @param service [Nonnative::ConfigurationRunner] runner configuration
     def initialize(service)
       @service = service
       @proxy = Nonnative::ProxyFactory.create(service)
     end
 
+    # Returns the configured runner name.
+    #
+    # @return [String, nil]
     def name
       service.name
     end
 
     protected
 
+    # Returns the underlying configuration object.
+    #
+    # @return [Nonnative::ConfigurationRunner]
     attr_reader :service
 
+    # Sleeps for the configured `wait` interval after start-related work.
+    #
+    # @return [void]
     def wait_start
       sleep service.wait
     end
 
+    # Sleeps for the configured `wait` interval after stop-related work.
+    #
+    # @return [void]
     def wait_stop
       sleep service.wait
     end

data/lib/nonnative/server.rb

@@ -1,13 +1,36 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Runtime runner that manages an in-process Ruby server.
+  #
+  # A server runner:
+  # - starts the configured proxy (if any),
+  # - starts a Ruby thread that runs {#perform_start},
+  # - waits briefly (via the runner `wait`), and
+  # - participates in readiness/shutdown via TCP port checks orchestrated by {Nonnative::Pool}.
+  #
+  # Concrete server implementations are expected to subclass {Nonnative::Server} and implement:
+  # - {#perform_start} (to bind/listen and begin serving), and
+  # - {#perform_stop} (to gracefully shut down).
+  #
+  # The underlying configuration is a {Nonnative::ConfigurationServer}.
+  #
+  # @see Nonnative::ConfigurationServer
+  # @see Nonnative::Pool
   class Server < Runner
+    # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(service)
       super
 
       @timeout = Nonnative::Timeout.new(service.timeout)
     end
 
+    # Starts the proxy (if any) and starts the server thread if not already started.
+    #
+    # @return [Array<(Integer, TrueClass)>]
+    #   a tuple of:
+    #   - a stable identifier for this server instance (`object_id`)
+    #   - `true` (thread creation itself is considered started; readiness is checked separately)
     def start
       unless thread
         proxy.start
@@ -21,6 +44,11 @@ module Nonnative
       [object_id, true]
     end
 
+    # Stops the server if it is running.
+    #
+    # Calls {#perform_stop}, terminates the server thread, stops the proxy (if any), and waits briefly.
+    #
+    # @return [Integer] the server identifier (`object_id`)
     def stop
       if thread
         perform_stop

data/lib/nonnative/service.rb

@@ -1,13 +1,29 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Runtime runner for an external dependency.
+  #
+  # A service runner does not manage an OS process or Ruby thread. It exists so Nonnative can manage
+  # a proxy lifecycle (start/stop/reset) for an external service that is managed elsewhere (for example
+  # a database running in Docker).
+  #
+  # The underlying configuration is a {Nonnative::ConfigurationService}.
+  #
+  # @see Nonnative::ConfigurationService
+  # @see Nonnative::Proxy
   class Service < Runner
+    # Starts the configured proxy (if any).
+    #
+    # @return [void]
     def start
       proxy.start
 
       Nonnative.logger.info "started service '#{service.name}'"
     end
 
+    # Stops the configured proxy (if any).
+    #
+    # @return [void]
     def stop
       proxy.stop
 

data/lib/nonnative/socket_pair.rb

@@ -1,11 +1,32 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Base socket-pair implementation used by TCP proxies.
+  #
+  # A socket-pair connects an accepted local socket to a remote upstream socket and forwards bytes
+  # in both directions until one side closes.
+  #
+  # This is used by {Nonnative::FaultInjectionProxy} to implement pass-through forwarding, and is
+  # subclassed to inject failures (close immediately, delay reads, corrupt writes, etc).
+  #
+  # The `proxy` argument is expected to provide `host` and `port` for the upstream connection
+  # (typically a {Nonnative::ConfigurationProxy}).
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::CloseAllSocketPair
+  # @see Nonnative::DelaySocketPair
+  # @see Nonnative::InvalidDataSocketPair
   class SocketPair
+    # @param proxy [#host, #port, #options] proxy configuration used to connect upstream
     def initialize(proxy)
       @proxy = proxy
     end
 
+    # Connects the given local socket to an upstream socket and pipes data until the connection ends.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
     def connect(local_socket)
       remote_socket = create_remote_socket
 
@@ -24,12 +45,24 @@ module Nonnative
 
     protected
 
+    # Returns the proxy configuration.
+    #
+    # @return [Object]
     attr_reader :proxy
 
+    # Creates the upstream socket connection.
+    #
+    # @return [TCPSocket]
     def create_remote_socket
       ::TCPSocket.new(proxy.host, proxy.port)
     end
 
+    # Pipes data from `socket1` to `socket2` if `socket1` is readable.
+    #
+    # @param ready [Array<Array<IO>>] the result from `select`
+    # @param socket1 [IO] readable side
+    # @param socket2 [IO] writable side
+    # @return [Boolean] whether the piping loop should terminate
     def pipe?(ready, socket1, socket2)
       if ready[0].include?(socket1)
         data = read(socket1)
@@ -41,10 +74,23 @@ module Nonnative
       false
     end
 
+    # Reads bytes from the given socket.
+    #
+    # Subclasses can override this to inject behavior (e.g. delay).
+    #
+    # @param socket [IO]
+    # @return [String]
     def read(socket)
       socket.recv(1024) || ''
     end
 
+    # Writes bytes to the given socket.
+    #
+    # Subclasses can override this to inject behavior (e.g. corrupt data).
+    #
+    # @param socket [IO]
+    # @param data [String]
+    # @return [Integer] number of bytes written
     def write(socket, data)
       socket.write(data)
     end

data/lib/nonnative/socket_pair_factory.rb

@@ -1,8 +1,29 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Factory for creating socket-pair implementations used by {Nonnative::FaultInjectionProxy}.
+  #
+  # A socket-pair is responsible for wiring a local accepted socket to a remote upstream socket,
+  # optionally injecting failures (close connections, add delays, corrupt data, etc).
+  #
+  # Proxy states are mapped as follows:
+  # - `:none` (or any unknown value) -> {Nonnative::SocketPair} (pass-through)
+  # - `:close_all` -> {Nonnative::CloseAllSocketPair}
+  # - `:delay` -> {Nonnative::DelaySocketPair}
+  # - `:invalid_data` -> {Nonnative::InvalidDataSocketPair}
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPair
+  # @see Nonnative::CloseAllSocketPair
+  # @see Nonnative::DelaySocketPair
+  # @see Nonnative::InvalidDataSocketPair
   class SocketPairFactory
     class << self
+      # Creates a socket-pair instance for the given proxy state.
+      #
+      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:delay`, `:invalid_data`)
+      # @param proxy [Nonnative::ConfigurationProxy] proxy configuration (host/port/options)
+      # @return [Nonnative::SocketPair] a socket-pair implementation instance
       def create(kind, proxy)
         pair = case kind
                when :close_all

data/lib/nonnative/start_error.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Raised when {Nonnative.start} fails to start one or more configured runners.
+  #
+  # The error message typically contains one line per failing runner.
+  #
+  # @see Nonnative.start
   class StartError < Nonnative::Error
   end
 end

data/lib/nonnative/stop_error.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Raised when {Nonnative.stop} fails to stop one or more configured runners within the configured timeouts.
+  #
+  # The error message typically contains one line per runner that did not stop cleanly in time.
+  #
+  # @see Nonnative.stop
   class StopError < Nonnative::Error
   end
 end

data/lib/nonnative/timeout.rb

@@ -1,11 +1,31 @@
 # frozen_string_literal: true
 
 module Nonnative
+  # Small helper to run a block with a timeout and convert timeout errors into `false`.
+  #
+  # This is used internally for readiness/shutdown loops (for example port checks) where the common
+  # control-flow is “keep retrying until the timeout elapses”.
+  #
+  # @example
+  #   timeout = Nonnative::Timeout.new(1) # seconds
+  #   ok = timeout.perform do
+  #     # do work that may take time
+  #     true
+  #   end
+  #   # ok is either the block result or false if the timeout elapsed
+  #
   class Timeout
+    # @param time [Numeric] timeout duration in seconds
     def initialize(time)
       @time = time
     end
 
+    # Executes the given block with the configured timeout.
+    #
+    # If the timeout elapses, returns `false` instead of raising `Timeout::Error`.
+    #
+    # @yield the work to execute under a timeout
+    # @return [Object, false] the block's return value, or `false` if the timeout elapsed
     def perform(&)
       ::Timeout.timeout(time, &)
     rescue ::Timeout::Error

data/lib/nonnative/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module Nonnative
-  VERSION = '1.107.0'
+  # The current gem version.
+  #
+  # @return [String]
+  VERSION = '1.109.0'
 end