nonnative 2.1.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b47a9f615e36880cdb7d6c7c3de9b716813467b25dd60cff0d2b15662a14e81d
-  data.tar.gz: 59e26bb9aca2094793348170e2f72eec55309619f00131b742728f03c1515e57
+  metadata.gz: 8220ca25997b624a13ebf5f3f6a046af6bf05ee7428b21b96454d7c23ad42bef
+  data.tar.gz: 5a1884b26d92f57b54631ef22a4c2d6b3f16690c81364353ecb3e2d941b39638
 SHA512:
-  metadata.gz: 4de8fc01b094bd20f45fae35b89b8d44367672cce238e03f28155f82dc661ba973293c02c3b7e47c1ff57621f7b0751f6c8ba1a67fe7eeab909505264521576b
-  data.tar.gz: 384b6bfe7d122e6ae44b8902655091e4967b8a04c9ecf15a35316250ee474918a30402bbd725a81c6252bfa1b16864354ffd8bfc1668c148844ad358f82a5925
+  metadata.gz: d026441a2ed85facab82a48a8967e246d6c717c00c5c0039fb434feb585fe35fb23fbfa06732f85ec5491d0febcdda056d1cf4264a014efe432b87dfc705275f
+  data.tar.gz: 2cc84560c80a27144d3176b3e019a6ab9c86e32c2215e774d97d5a58927c34dda006a3da8f3b5b356b19bc7e2e96fb863b2bc168c9f4ac3e7a91f7181f08c57d

data/.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 jobs:
   build:
     docker:
-      - image: alexfalkowski/ruby:2.0
+      - image: alexfalkowski/ruby:2.4
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -24,7 +24,9 @@ jobs:
           paths:
             - vendor
       - run: make lint
-      - run: make features
+      - run: make sec
+      - run: COVERAGE_NAME="Cucumber Features" make features
+      - run: COVERAGE_NAME="Cucumber Benchmarks" make benchmarks
       - store_test_results:
           path: test/reports
       - store_artifacts:
@@ -33,7 +35,7 @@ jobs:
     resource_class: arm.large
   sync:
     docker:
-      - image: alexfalkowski/release:7.0
+      - image: alexfalkowski/release:7.5
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -44,7 +46,7 @@ jobs:
     resource_class: arm.large
   version:
     docker:
-      - image: alexfalkowski/release:7.0
+      - image: alexfalkowski/release:7.5
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -56,7 +58,7 @@ jobs:
     resource_class: arm.large
   wait-all:
     docker:
-      - image: alexfalkowski/ruby:2.0
+      - image: alexfalkowski/ruby:2.4
     steps:
       - run: echo "all applicable jobs finished"
     resource_class: arm.large

data/AGENTS.md

@@ -1,248 +1,147 @@
 # AGENTS.md
 
-This repository is the **`nonnative` Ruby gem**. It provides a Ruby-first harness for end-to-end testing of services implemented in other languages by **starting processes/servers/services**, waiting for readiness (port checks), and optionally running **fault-injection proxies**.
+This repo is the `nonnative` Ruby gem: a Ruby-first harness for end-to-end testing of systems implemented in other languages by starting processes/servers/services, waiting on TCP port readiness, and optionally putting fault-injection proxies in front of them.
 
-Everything below is based on the files currently in this repo (no assumptions).
+## Quick map
 
-## Recent documentation updates (important for future sessions)
+- Library code: `lib/nonnative/**/*.rb`
+- Acceptance tests: `features/**/*.feature`, `features/support/**/*.rb`, `features/step_definitions/**/*.rb`
+- Generated gRPC Ruby stubs for tests: `test/grpc/**/*`
+- Test proto files: `test/nonnative/v1/*.proto`
+- Build wiring: root `Makefile` includes `bin/build/make/*.mak`
 
-- **Public API RDoc pass started**:
-  - Added/expanded RDoc for the module entry point (`Nonnative`) and core configuration/error types.
-  - Goal: document *public APIs only* (gem consumers), not internal/private helpers.
-- **README accuracy pass started**:
-  - Fixed incorrect examples around **services**:
-    - Programmatic example incorrectly used `p.port` inside a `config.service do |s| ... end` block; corrected to `s.host`/`s.port`.
-    - YAML example incorrectly used `processes:` for services; corrected to `services:`.
-  - Removed/avoided implying non-existent config fields (e.g. there is no top-level `config.wait`; `wait` is per-runner).
+## Key repo dependency
 
-These changes were made to align docs/examples with the actual runtime/config objects under `lib/nonnative/**/*.rb`.
+This repo depends on the `bin/` git submodule.
 
-## Quick orientation
+- `.gitmodules` points to `git@github.com:alexfalkowski/bin.git`
+- CI runs `git submodule sync && git submodule update --init`
+- If `bin/` is missing or you do not have SSH access, `make` targets will fail
 
-- **Library code**: `lib/nonnative/**/*.rb`
-- **Acceptance tests**: `features/**/*.feature` + `features/support/**/*.rb` + `features/step_definitions/**/*.rb` (Cucumber)
-- **Generated gRPC Ruby stubs for tests**: `test/grpc/**/*` (excluded from RuboCop)
-- **Proto definitions for test fixtures**: `test/nonnative/v1/*.proto`
-- **Build system**: `Makefile` includes make fragments from the `bin/` submodule (`bin/build/make/*.mak`).
+## Core commands
 
-## Important repo dependency: `bin/` submodule
+- Install deps: `make dep`
+- Lint: `make lint`
+- Run features: `make features`
+- Run benchmarks only: `make benchmarks`
+- Clean deps: `make clean-dep`
+- Clean reports: `make clean-reports`
 
-This repo uses a git submodule at `bin/`:
+## Runtime model
 
-- `.gitmodules` points to `git@github.com:alexfalkowski/bin.git`.
-- CI runs `git submodule sync && git submodule update --init` before running `make` targets (`.circleci/config.yml`).
+Public entry point is `lib/nonnative.rb`.
 
-If you don’t have SSH access to that repo, `make` targets that include `bin/build/make/*.mak` will fail.
+Main module API:
 
-### Submodule commands
+- `configure`
+- `start`
+- `stop`
+- `clear`
+- `reset`
+- `pool`
 
-```sh
-git submodule sync
-git submodule update --init
-```
+Configuration lives in `Nonnative::Configuration` and is built either:
 
-## Essential commands (from Makefiles)
+- programmatically with `config.process`, `config.server`, `config.service`
+- from YAML with `config.load_file(...)`
 
-### Ruby version
+Runtime runners:
 
-- `nonnative.gemspec` requires Ruby `>= 3.4.0` and `< 4.0.0`.
+- `Nonnative::Process`: manages an OS process
+- `Nonnative::Server`: manages an in-process Ruby server thread
+- `Nonnative::Service`: manages only proxy lifecycle for an externally managed dependency
 
-### Install deps
+`Nonnative::Pool` starts services first, then servers/processes, and stops in the reverse direction.
 
-Ruby deps are managed by Bundler and installed into `vendor/bundle`:
+Readiness and shutdown checks are TCP-only via `Nonnative::Port#open?` and `#closed?`.
 
-```sh
-make dep
-```
+## Cucumber integration
 
-Implementation lives in `bin/build/make/ruby.mak` (included by root `Makefile`).
+Cucumber integration lives in `lib/nonnative/cucumber.rb`.
 
-### Lint
+Treat `lib/nonnative/cucumber.rb` as a public compatibility surface for library consumers.
+Existing hooks and step text should not be removed or renamed unless the user explicitly wants a breaking change.
 
-```sh
-make lint
-```
+Supported tags:
 
-Runs RuboCop:
+- `@startup`: start before scenario, stop after scenario
+- `@manual`: scenario starts manually, stop after scenario
+- `@clear`: call `Nonnative.clear` before scenario
+- `@reset`: reset proxies after scenario
 
-- `bundler exec rubocop` (`bin/build/make/ruby.mak:4-5`)
-- Config: `.rubocop.yml` (TargetRubyVersion 3.4; max line length 150)
+Repo-owned feature files also use suite taxonomy tags:
 
-Auto-fix:
+- `@acceptance`: end-to-end runner and client flows
+- `@contract`: lower-level lifecycle / command coverage
+- `@proxy`: proxy-specific coverage
+- `@config`: scenarios or example sets that load YAML/configuration
+- `@service`: coverage centered on external services
+- `@benchmark`: benchmark-only scenarios
+- `@slow`: slower-running scenarios, currently benchmarks
 
-```sh
-make fix-lint
-# or
-make format
-```
+`make features` excludes `@benchmark`; `make benchmarks` runs only `@benchmark`.
 
-### Run acceptance tests (Cucumber)
+`Nonnative.clear` now clears:
 
-```sh
-make features
-```
+- configuration
+- logger
+- observability client
+- pool
 
-This calls `bin/quality/ruby/feature`, which runs:
+`require 'nonnative'` still loads the Cucumber integration, but hook/step registration is lazy, so plain `require 'nonnative'` is safe outside a booted Cucumber runtime.
 
-- `bundler exec cucumber --profile report ... --tags "not @benchmark" ...`
-- Cucumber profile `report` is defined in `.config/cucumber.yml` and writes:
-  - JUnit XML to `test/reports`
-  - HTML report to `test/reports/index.html`
+For “start once per test run”, use `require 'nonnative/startup'`.
 
-Run only benchmarks:
+## Proxy wiring
 
-```sh
-make benchmarks
-```
+This is the easiest thing to get wrong.
 
-### Coverage
+- Runner `host` / `port` are the client-facing endpoint and the values used by readiness/shutdown checks
+- For `fault_injection`, nested `proxy.host` / `proxy.port` are the upstream target behind the proxy
+- Clients should connect to the runner `host` / `port` when a proxy is enabled
 
-Cucumber loads SimpleCov via `features/support/env.rb` and writes coverage output under `test/reports/`.
+Available proxy kinds:
 
-Codecov config exists in `.codecov.yml` and CI uploads coverage in `.circleci/config.yml`.
+- `none`
+- `fault_injection`
 
-Local upload target:
+Fault injection states:
 
-```sh
-make codecov-upload
-```
+- `none`
+- `close_all`
+- `delay`
+- `invalid_data`
 
-### Clean deps / reports
+## Config gotchas
 
-```sh
-make clean-dep
-make clean-reports
-```
+- Services must be declared under `services:` in YAML, not `processes:`
+- There is no top-level `config.wait`; `wait` is per runner
+- Service configs use `config.service do |s| ... end`, so use `s.host` / `s.port`
+- Proxy examples need both sides of the split:
+  - runner `host` / `port` = proxy endpoint
+  - nested `proxy.host` / `proxy.port` = upstream target
 
-## Testing patterns and hooks
+## Test fixtures worth knowing
 
-### Cucumber hooks and tags
+- Local process fixture: `features/support/bin/start`
+- HTTP fixtures: `features/support/http_server.rb`, `features/support/http_proxy_server.rb`
+- TCP fixture: `features/support/tcp_server.rb`
+- gRPC fixtures: `features/support/grpc_server.rb`, plus generated stubs under `test/grpc/`
 
-Cucumber integration lives in `lib/nonnative/cucumber.rb`:
+## Important limitations / gotchas
 
-- `@startup`: starts and stops Nonnative around each scenario.
-- `@manual`: only stops after scenario (start is expected to be triggered manually in steps).
-- `@clear`: calls `Nonnative.clear` before scenario.
-- `@reset`: resets proxies after scenario.
+- Ruby version is constrained by `nonnative.gemspec` to `>= 4.0.0` and `< 5.0.0`
+- The `grpc` Ruby library uses a global logger; per-server gRPC loggers are not really supported
+- `make` depends on the `bin/` submodule being present
+- Local Ruby/Bundler mismatches can break native extensions on macOS
+- Coverage output and Cucumber reports are written under `test/reports`
+- Port checks can be flaky if tests reuse ports unexpectedly
 
-The “start once per test run” strategy is implemented by requiring `nonnative/startup`:
-
-- `lib/nonnative/startup.rb` calls `Nonnative.start` and registers an `at_exit` stop.
-
-### README gotchas that matter in practice
-
-- **Service vs process YAML keys**:
-  - Services must be declared under `services:` in YAML (not `processes:`). Code reads `cfg.services` and maps them to `Nonnative::ConfigurationService`.
-- **No top-level `wait`**:
-  - `wait` is defined on runner configurations (`ConfigurationRunner#wait`) and is per process/server/service.
-- **Proxy wiring is easy to misunderstand**:
-  - When a proxy kind like `fault_injection` is enabled, the proxy binds to `service.proxy.host`/`service.proxy.port`.
-  - Readiness checks and traffic should typically target the **proxy host/port**, not the underlying service host/port.
-
-### Feature support code
-
-`features/support/` contains small servers/clients used by cucumber scenarios (HTTP/TCP/gRPC). Example:
-
-- `features/support/http_server.rb` defines a Sinatra app for `/hello` and health endpoints.
-
-### Process fixture
-
-Scenarios start a local process via `features/support/bin/start` (referenced in step definitions and YAML configs like `features/configs/processes.yml`).
-
-## Library architecture (high level)
-
-### Entry point and global state
-
-- `lib/nonnative.rb` defines the `Nonnative` module singleton API:
-  - `configure { |config| ... }`
-  - `start` / `stop`
-  - `clear`, `reset`
-  - `pool` is created on `start` (`Nonnative::Pool.new(configuration)`).
-
-### Configuration objects
-
-- `Nonnative::Configuration` (`lib/nonnative/configuration.rb`) holds arrays of:
-  - `processes` (`Nonnative::ConfigurationProcess`)
-  - `servers` (`Nonnative::ConfigurationServer`)
-  - `services` (`Nonnative::ConfigurationService`)
-
-It can be populated either:
-
-- programmatically via `config.process { ... }`, `config.server { ... }`, `config.service { ... }`
-- via YAML using `config.load_file(path)` which calls `Config.load_files(...)` (the `config` gem)
-
-Proxies are configured via `ConfigurationProxy` (`lib/nonnative/configuration_proxy.rb`) and attached to runners as a hash.
-
-### Runners and lifecycle
-
-There are three runtime “runner” types, all subclassing `Runner` (`lib/nonnative/runner.rb`):
-
-- `Nonnative::Process` (`lib/nonnative/process.rb`): `spawn(...)` + `Process.kill` / `waitpid2`.
-- `Nonnative::Server` (`lib/nonnative/server.rb`): `Thread.new { perform_start }` + `perform_stop`.
-- `Nonnative::Service` (`lib/nonnative/service.rb`): no process management; proxy only.
-
-`Nonnative::Pool` (`lib/nonnative/pool.rb`) owns collections of runners and orchestrates start/stop:
-
-- starts **services first**, then servers/processes
-- stops **processes/servers first**, then services
-- readiness is determined via `Nonnative::Port#open?` / `#closed?` (`lib/nonnative/port.rb`) which repeatedly tries `TCPSocket.new(host, port)` inside a timeout.
-
-### Proxies
-
-Proxy selection is keyed by `kind`:
-
-- mapping: `Nonnative.proxies` in `lib/nonnative.rb`
-- default proxy config values: `ConfigurationProxy#initialize` sets kind `none`, host `0.0.0.0`, wait `0.1`, etc.
-
-Implemented proxies:
-
-- `Nonnative::NoProxy` (`lib/nonnative/no_proxy.rb`)
-- `Nonnative::FaultInjectionProxy` (`lib/nonnative/fault_injection_proxy.rb`)
-  - states: `:none`, `:close_all`, `:delay`, `:invalid_data`
-  - delegates behavior to socket-pair classes via `SocketPairFactory` (`lib/nonnative/socket_pair_factory.rb`).
-
-### Go executable helper
-
-There is a helper for building a Go *test binary* command line with optional profiling/trace/coverage flags:
-
-- `Nonnative.go_executable` in `lib/nonnative.rb`
-- `Nonnative::GoCommand` in `lib/nonnative/go_command.rb`
-
-This is used when YAML process config has a `go:` section (see `Configuration#command` in `lib/nonnative/configuration.rb`).
-
-## Style and conventions
-
-- Ruby style is enforced by RuboCop (`.rubocop.yml`):
-  - Target Ruby 3.4
-  - Line length 150
-  - `Style/Documentation` disabled
-- `.editorconfig`:
-  - `indent_size = 2` for most files
-  - **Makefiles use tabs**
-- Many Ruby files use `# frozen_string_literal: true`.
-
-## CI notes
-
-CircleCI runs (see `.circleci/config.yml`):
-
-- `make source-key` (defined in `bin/build/make/git.mak`) to generate `.source-key` used for caching
-- `make dep`, `make clean-dep`
-- `make lint`, `make features`
-- uploads `test/reports` artifacts
-
-## Common gotchas
-
-- **Submodule required**: root `Makefile` only includes `bin/...` make fragments; without `bin/` present/updated, `make` won’t work.
-- **SSH-only submodule URL**: `.gitmodules` uses `git@github.com:...`; CI or local environments without SSH keys will fail to init the submodule.
-- **Local Ruby/Bundler mismatch can break native extensions**: on macOS, `make lint`/`bundle exec ...` may fail if the Ruby used to install gems differs from the Ruby used to run them (example error seen: `prism.bundle` missing `libruby.3.4.dylib`).
-- **Requiring `nonnative` loads Cucumber DSL**: `lib/nonnative.rb` requires `lib/nonnative/cucumber.rb`, which calls `World(...)`. Outside a Cucumber runtime this can raise (example error seen: `Cucumber::Glue::Dsl.build_rb_world_factory`).
-- **Reports directory**: Cucumber report profile writes into `test/reports/` and the repo keeps a `test/reports/.keep` file.
-- **Port checks can be flaky if ports are reused**: readiness is purely `TCPSocket`-based (`lib/nonnative/port.rb`), so ensure test fixtures bind expected ports.
-
-## Where to look first when changing behavior
+## Where to look first
 
 - Lifecycle orchestration: `lib/nonnative.rb`, `lib/nonnative/pool.rb`
 - Readiness / timeouts: `lib/nonnative/port.rb`, `lib/nonnative/timeout.rb`
-- Process management: `lib/nonnative/process.rb`
+- Process lifecycle: `lib/nonnative/process.rb`
 - Proxies / fault injection: `lib/nonnative/fault_injection_proxy.rb`, `lib/nonnative/socket_pair_factory.rb`
 - Cucumber integration: `lib/nonnative/cucumber.rb`, `lib/nonnative/startup.rb`, `features/support/env.rb`
+- Config loading: `lib/nonnative/configuration.rb`, `lib/nonnative/configuration_runner.rb`, `lib/nonnative/configuration_proxy.rb`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (2.1.0)
+    nonnative (2.10.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 11)
@@ -24,7 +24,7 @@ GEM
     benchmark-malloc (0.2.0)
     benchmark-perf (0.6.0)
     benchmark-trend (0.4.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.1)
     builder (3.3.0)
     concurrent-ruby (1.3.6)
     config (5.6.1)
@@ -47,7 +47,7 @@ GEM
       cucumber-gherkin (> 36, < 40)
       cucumber-messages (> 31, < 33)
       cucumber-tag-expressions (> 6, < 9)
-    cucumber-cucumber-expressions (18.0.1)
+    cucumber-cucumber-expressions (18.1.0)
       bigdecimal
     cucumber-gherkin (39.0.0)
       cucumber-messages (>= 31, < 33)
@@ -59,29 +59,29 @@ GEM
     diff-lcs (1.6.2)
     docile (1.4.1)
     domain_name (0.6.20240107)
-    ffi (1.17.3-x86_64-darwin)
-    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
     get_process_mem (1.0.0)
       bigdecimal (>= 2.0)
       ffi (~> 1.0)
-    google-protobuf (4.34.0-x86_64-darwin)
+    google-protobuf (4.34.1-x86_64-darwin)
       bigdecimal
       rake (~> 13.3)
-    google-protobuf (4.34.0-x86_64-linux-gnu)
+    google-protobuf (4.34.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
     googleapis-common-protos-types (1.22.0)
       google-protobuf (~> 4.26)
-    grpc (1.78.1-x86_64-darwin)
+    grpc (1.80.0-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.78.1-x86_64-linux-gnu)
+    grpc (1.80.0-x86_64-linux-gnu)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
     http-accept (1.7.0)
-    http-cookie (1.1.0)
+    http-cookie (1.1.4)
       domain_name (~> 0.5)
-    json (2.19.2)
+    json (2.19.3)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -89,7 +89,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2026.0303)
+    mime-types-data (3.2026.0407)
     mini_mime (1.1.5)
     multi_test (1.1.0)
     mustermann (3.0.4)
@@ -97,28 +97,29 @@ GEM
     netrc (0.11.0)
     nio4r (2.7.5)
     ostruct (0.6.3)
-    parallel (1.27.0)
-    parser (3.3.10.2)
+    parallel (1.28.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
     puma (7.2.0)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.5)
+    rack (3.2.6)
     rack-protection (4.2.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
       rack (>= 3.0.0, < 4)
-    rack-session (2.1.1)
+    rack-session (2.1.2)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rainbow (3.1.1)
     rake (13.3.1)
-    rbs (3.10.3)
+    rbs (4.0.2)
       logger
+      prism (>= 1.6.0)
       tsort
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
@@ -160,7 +161,7 @@ GEM
     rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    ruby-lsp (0.26.8)
+    ruby-lsp (0.26.9)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -182,7 +183,7 @@ GEM
       rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
-    sys-uname (1.5.0)
+    sys-uname (1.5.1)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
     tilt (2.7.0)

data/README.md

@@ -51,17 +51,32 @@ High-level configuration fields:
 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.
+- `host`/`port`: client-facing address used for readiness/shutdown port checks. When a `fault_injection` proxy is enabled, this is the endpoint your tests/clients should hit.
 - `log`: per-runner log file (used by process output redirection or server implementations).
 
+For `fault_injection`, the nested `proxy.host`/`proxy.port` describe the upstream target behind the proxy. In-process server implementations typically bind there via `proxy.host` / `proxy.port`.
+
 ### Lifecycle strategies (Cucumber integration)
 
 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
+- `@clear`: clears memoized configuration, logger, observability client, and pool before scenario
 - `@reset`: resets proxies after scenario
 
+The repo’s own Cucumber suite also uses taxonomy tags to classify coverage:
+- `@acceptance`: end-to-end behavior across configured runners and clients
+- `@contract`: lower-level contract and lifecycle behavior
+- `@proxy`: proxy-specific behavior and failure injection
+- `@config`: coverage that exercises YAML/config loading
+- `@service`: scenarios centered on externally managed dependencies
+- `@benchmark`: benchmark-only scenarios run by `make benchmarks`
+- `@slow`: slower scenarios, currently used by benchmark coverage
+
+`make features` excludes `@benchmark`, while `make benchmarks` runs only `@benchmark`.
+
+Requiring `nonnative` is enough; the Cucumber hooks and step definitions are installed lazily once Cucumber’s Ruby DSL is ready.
+
 If you want “start once per test run”, require:
 
 ```ruby
@@ -516,9 +531,11 @@ We allow different proxies to be configured. These proxies can be used to simula
 - `none` (this is the default)
 - `fault_injection`
 
+For `fault_injection`, keep the runner `host`/`port` as the client-facing endpoint and use nested `proxy.host`/`proxy.port` for the upstream target behind the proxy.
+
 ##### Proxies Processes
 
-Setup it up programmatically:
+Add this to an existing process configuration:
 
 ```ruby
 require 'nonnative'
@@ -543,7 +560,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+YAML fragment:
 
 ```yaml
 version: "1.0"
@@ -563,7 +580,7 @@ processes:
 
 ##### Proxies Servers
 
-Setup it up programmatically:
+Add this to an existing server configuration:
 
 ```ruby
 require 'nonnative'
@@ -588,7 +605,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+YAML fragment:
 
 ```yaml
 version: "1.0"
@@ -608,7 +625,7 @@ servers:
 
 ##### Proxies Services
 
-Set it up programmatically:
+Add this to an existing service configuration:
 
 ```ruby
 require 'nonnative'
@@ -622,12 +639,12 @@ Nonnative.configure do |config|
   config.service do |s|
     s.name = 'redis'
     s.host = '127.0.0.1'
-    s.port = 6379
+    s.port = 16_379
 
     s.proxy = {
       kind: 'fault_injection',
       host: '127.0.0.1',
-      port: 20_000,
+      port: 6379,
       log: 'proxy_server.log',
       wait: 1,
       options: {
@@ -638,19 +655,22 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+YAML fragment:
 
 ```yaml
 version: "1.0"
 name: test
 url: http://localhost:4567
 log: nonnative.log
-wait: 1
 services:
   -
+    name: redis
+    host: 127.0.0.1
+    port: 16379
     proxy:
       kind: fault_injection
-      port: 20000
+      host: 127.0.0.1
+      port: 6379
       log: proxy_server.log
       wait: 1
       options: