nonnative 1.107.0 → 1.108.0

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.108.0'
 end

data/lib/nonnative.rb

@@ -1,5 +1,46 @@
 # frozen_string_literal: true
 
+# = Nonnative
+#
+# Nonnative is a Ruby-first harness for end-to-end testing of services implemented in other languages.
+# It can:
+#
+# - start external processes and in-process servers
+# - wait for readiness via port checks
+# - optionally run fault-injection proxies in front of services
+#
+# The public entry points are exposed as module-level methods on {Nonnative}.
+#
+# == Basic usage
+#
+# Configure the system under test:
+#
+#   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
+#
+# Start and stop around your test suite:
+#
+#   Nonnative.start
+#   # run tests...
+#   Nonnative.stop
+#
+# == Notes
+#
+# This file also requires integration helpers used by acceptance tests. If you require `nonnative` outside a
+# Cucumber runtime, loading `nonnative/cucumber` may not be desirable for your environment.
+#
 require 'socket'
 require 'timeout'
 require 'yaml'
@@ -56,46 +97,116 @@ require 'nonnative/go_command'
 require 'nonnative/cucumber'
 require 'nonnative/header'
 
+# The main namespace for the gem.
+#
+# Most consumers will interact with module-level methods:
+#
+# - {Nonnative.configure} / {Nonnative.configuration}
+# - {Nonnative.start} / {Nonnative.stop}
+# - {Nonnative.clear} / {Nonnative.reset}
+#
+# @see Nonnative::Configuration for the configuration DSL
+# @see Nonnative::Pool for lifecycle orchestration once started
 module Nonnative
   class << self
+    # Returns the current runner pool (created on {Nonnative.start}).
+    #
+    # @return [Nonnative::Pool, nil] the pool instance, or `nil` if not started yet
     attr_reader :pool
 
+    # Loads one or more configuration files using the `config` gem.
+    #
+    # This is primarily used by {Nonnative::Configuration#load_file}, but is public for advanced cases.
+    #
+    # @param files [Array<String>] paths to configuration files
+    # @return [Config::Options] the loaded configuration object
     def configurations(*files)
       Config.load_files(files)
     end
 
+    # Returns the current configuration (memoized).
+    #
+    # @return [Nonnative::Configuration]
     def configuration
       @configuration ||= Nonnative::Configuration.new
     end
 
+    # Yields the configuration to a block for programmatic setup.
+    #
+    # @yieldparam config [Nonnative::Configuration]
+    # @return [void]
+    #
+    # @example
+    #   Nonnative.configure do |config|
+    #     config.name = 'my-service'
+    #     # ...
+    #   end
     def configure
       yield configuration
     end
 
+    # Returns the gem logger (memoized).
+    #
+    # The logger writes to the path configured at {Nonnative::Configuration#log}.
+    #
+    # @return [Logger]
     def logger
       @logger ||= Logger.new(configuration.log)
     end
 
+    # Reads a file and returns only lines matching the given predicate.
+    #
+    # @param path [String] file path to read
+    # @param predicate [#call] callable that receives a line and returns truthy/falsey
+    # @return [Array<String>] matching lines
     def log_lines(path, predicate)
       File.readlines(path).select { |l| predicate.call(l) }
     end
 
+    # Builds a Go test executable command line with optional profiling/trace/coverage flags.
+    #
+    # This is used when process configuration specifies a `go` section.
+    #
+    # @param tools [Array<String>] enabled tool names (e.g. `["prof", "trace", "cover"]`)
+    # @param output [String] directory where outputs should be written
+    # @param exec [String] the test binary (or wrapper) to execute
+    # @param cmd [String] the command argument passed to the test binary
+    # @param params [Array<String>] extra parameters for the command
+    # @return [String] executable command string
     def go_executable(tools, output, exec, cmd, *params)
       Nonnative::GoCommand.new(tools, exec, output).executable(cmd, params)
     end
 
+    # Returns an HTTP client for common health/readiness endpoints.
+    #
+    # @return [Nonnative::Observability]
     def observability
       @observability ||= Nonnative::Observability.new(configuration.url)
     end
 
+    # Returns the configured proxy kinds mapped to proxy classes.
+    #
+    # Consumers can extend this map to add custom proxy implementations.
+    #
+    # @return [Hash{String=>Class}]
     def proxies
       @proxies ||= { 'fault_injection' => Nonnative::FaultInjectionProxy }.freeze
     end
 
+    # Resolves a proxy implementation for a configured kind.
+    #
+    # @param kind [String] proxy kind name (for example `"fault_injection"`)
+    # @return [Class] a subclass of {Nonnative::Proxy}
     def proxy(kind)
       Nonnative.proxies[kind] || Nonnative::NoProxy
     end
 
+    # Starts all configured services, servers, and processes, and waits for readiness.
+    #
+    # Readiness is determined by attempting to connect to each runner's configured host/port.
+    #
+    # @return [void]
+    # @raise [Nonnative::StartError] if one or more runners fail to start or become ready in time
     def start
       @pool ||= Nonnative::Pool.new(configuration)
       errors = []
@@ -108,6 +219,10 @@ module Nonnative
       raise Nonnative::StartError, errors.join("\n") unless errors.empty?
     end
 
+    # Stops all configured processes and servers, then services, and waits for shutdown.
+    #
+    # @return [void]
+    # @raise [Nonnative::StopError] if one or more runners fail to stop in time
     def stop
       return if @pool.nil?
 
@@ -120,19 +235,32 @@ module Nonnative
       raise Nonnative::StopError, errors.join("\n") unless errors.empty?
     end
 
+    # Clears the memoized configuration instance.
+    #
+    # @return [void]
     def clear_configuration
       @configuration = nil
     end
 
+    # Clears the memoized pool instance.
+    #
+    # @return [void]
     def clear_pool
       @pool = nil
     end
 
+    # Clears memoized configuration and pool.
+    #
+    # @return [void]
     def clear
       clear_configuration
       clear_pool
     end
 
+    # Resets proxies for all currently started runners.
+    #
+    # @return [void]
+    # @raise [NoMethodError] if called before {Nonnative.start} (because {Nonnative.pool} is nil)
     def reset
       Nonnative.pool.reset
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 1.107.0
+  version: 1.108.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -264,6 +264,7 @@ files:
 - ".gitignore"
 - ".gitmodules"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -330,7 +331,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Allows you to keep using the power of ruby to test other systems
 test_files: []