nonnative 1.107.0 → 1.109.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (1.107.0)
+    nonnative (1.109.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 11)
@@ -18,94 +18,102 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark-malloc (0.2.0)
     benchmark-perf (0.6.0)
     benchmark-trend (0.4.0)
-    bigdecimal (3.2.3)
+    bigdecimal (4.0.1)
     builder (3.3.0)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     config (5.6.1)
       deep_merge (~> 1.2, >= 1.2.1)
       ostruct
-    cucumber (10.1.0)
+    cucumber (10.2.0)
       base64 (~> 0.2)
       builder (~> 3.2)
-      cucumber-ci-environment (> 9, < 11)
+      cucumber-ci-environment (> 9, < 12)
       cucumber-core (> 15, < 17)
-      cucumber-cucumber-expressions (> 17, < 19)
-      cucumber-html-formatter (> 20.3, < 22)
+      cucumber-cucumber-expressions (> 17, < 20)
+      cucumber-html-formatter (> 21, < 23)
       diff-lcs (~> 1.5)
       logger (~> 1.6)
       mini_mime (~> 1.1)
       multi_test (~> 1.1)
       sys-uname (~> 1.3)
-    cucumber-ci-environment (10.0.1)
-    cucumber-core (15.2.1)
-      cucumber-gherkin (> 27, < 33)
-      cucumber-messages (> 26, < 30)
-      cucumber-tag-expressions (> 5, < 7)
+    cucumber-ci-environment (11.0.0)
+    cucumber-core (16.2.0)
+      cucumber-gherkin (> 36, < 40)
+      cucumber-messages (> 31, < 33)
+      cucumber-tag-expressions (> 6, < 9)
     cucumber-cucumber-expressions (18.0.1)
       bigdecimal
-    cucumber-gherkin (32.2.0)
-      cucumber-messages (> 25, < 28)
-    cucumber-html-formatter (21.14.0)
-      cucumber-messages (> 19, < 28)
-    cucumber-messages (27.2.0)
-    cucumber-tag-expressions (6.1.2)
+    cucumber-gherkin (39.0.0)
+      cucumber-messages (>= 31, < 33)
+    cucumber-html-formatter (22.3.0)
+      cucumber-messages (> 23, < 33)
+    cucumber-messages (32.2.0)
+    cucumber-tag-expressions (8.1.0)
     deep_merge (1.2.2)
     diff-lcs (1.6.2)
     docile (1.4.1)
     domain_name (0.6.20240107)
-    ffi (1.17.2-x86_64-darwin)
-    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
     get_process_mem (1.0.0)
       bigdecimal (>= 2.0)
       ffi (~> 1.0)
-    google-protobuf (4.32.0-x86_64-darwin)
+    google-protobuf (4.34.0-x86_64-darwin)
       bigdecimal
-      rake (>= 13)
-    google-protobuf (4.32.0-x86_64-linux-gnu)
+      rake (~> 13.3)
+    google-protobuf (4.34.0-x86_64-linux-gnu)
       bigdecimal
-      rake (>= 13)
-    googleapis-common-protos-types (1.21.0)
+      rake (~> 13.3)
+    googleapis-common-protos-types (1.22.0)
       google-protobuf (~> 4.26)
-    grpc (1.74.1-x86_64-darwin)
+    grpc (1.78.1-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.74.1-x86_64-linux-gnu)
+    grpc (1.78.1-x86_64-linux-gnu)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
     http-accept (1.7.0)
-    http-cookie (1.0.8)
+    http-cookie (1.1.0)
       domain_name (~> 0.5)
-    json (2.13.2)
+    json (2.18.1)
+    json-schema (6.1.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
     memoist3 (1.0.0)
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0902)
+    mime-types-data (3.2026.0303)
     mini_mime (1.1.5)
     multi_test (1.1.0)
     mustermann (3.0.4)
       ruby2_keywords (~> 0.0.1)
     netrc (0.11.0)
-    nio4r (2.7.4)
+    nio4r (2.7.5)
     ostruct (0.6.3)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
-    puma (7.0.0)
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    puma (7.2.0)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.1)
-    rack-protection (4.1.1)
+    rack (3.2.5)
+    rack-protection (4.2.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
       rack (>= 3.0.0, < 4)
@@ -113,18 +121,19 @@ GEM
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rainbow (3.1.1)
-    rake (13.3.0)
-    rbs (3.9.4)
+    rake (13.3.1)
+    rbs (3.10.3)
       logger
-    regexp_parser (2.11.2)
+      tsort
+    regexp_parser (2.11.3)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
-    retriable (3.1.2)
-    rexml (3.4.2)
-    rspec (3.13.1)
+    retriable (3.4.1)
+    rexml (3.4.4)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
@@ -133,32 +142,33 @@ GEM
       benchmark-perf (~> 0.6)
       benchmark-trend (~> 0.4)
       rspec (>= 3.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.5)
+    rspec-support (3.13.7)
     rspec-wait (1.0.2)
       rspec (>= 3.4)
-    rubocop (1.80.2)
+    rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    ruby-lsp (0.26.1)
+      prism (~> 1.7)
+    ruby-lsp (0.26.8)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -173,20 +183,21 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    sinatra (4.1.1)
+    sinatra (4.2.1)
       logger (>= 1.6.0)
       mustermann (~> 3.0)
       rack (>= 3.0.0, < 4)
-      rack-protection (= 4.1.1)
+      rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
-    sys-uname (1.4.1)
+    sys-uname (1.5.0)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
-    tilt (2.6.1)
-    unicode-display_width (3.1.5)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    tilt (2.7.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   x86_64-darwin-21
@@ -202,4 +213,4 @@ DEPENDENCIES
   simplecov-cobertura
 
 BUNDLED WITH
-   2.6.9
+  4.0.8

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