nonnative 3.9.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef654d45571b49eaf151e67b60a8eaa5c7b6df2b1a2e877d774a30ec80cc3281
-  data.tar.gz: 3526ed68b510ee72ac7b2d92764109bbd729653b5e1ba06b8b7a0f1f60b44c07
+  metadata.gz: 6a7d0e5ea6dab1d00eedd363fc81d05d2dd3e4401a97729043bcd3132a071432
+  data.tar.gz: 53c589eda9e895f3c815446003c97e77859ccec3b0c021182dc1437d0632b267
 SHA512:
-  metadata.gz: f28ca3884eef23d8db41bcef405205e5afca8369622627f415a845340579e54b17102cbdcabd3d44933ae7630a26eb3c6b3ba05c3e50da08092b84ec873a1629
-  data.tar.gz: 69166708a716e13658f5f25c86ccea83c201cccdeeec11296249fc318e7cabbec78816048ca266f9c890538b920d091968bff3275888a2c7bf7d9853343313f6
+  metadata.gz: be0b0b0d4cf1f606fe973f7bb6e38b3f2679b8445d6f24f7f05c4ca37eea62fc36f8910f6d0bcf44c1329b71d6638625d7d4a0d3226a14912662d91980523c1e
+  data.tar.gz: 15caeabfe50acdf2513ac2519bc953fb70effcc662c948c293be646d949bdb60c570359fb0817a6eb528207004f6a7cadfd440628026b58a0e9375003f650389

data/.circleci/config.yml

@@ -32,13 +32,13 @@ jobs:
       - restore_cache:
           name: restore deps
           keys:
-            - nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}-{{ checksum ".source-key" }}
+            - nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}
             - nonnative-ruby-cache-
       - run: make dep
       - run: make clean-dep
       - save_cache:
           name: save deps
-          key: nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}-{{ checksum ".source-key" }}
+          key: nonnative-ruby-cache-{{ checksum "Gemfile.lock" }}-{{ checksum "~/.ruby-version" }}
           paths:
             - vendor
       - run: make lint

data/AGENTS.md

@@ -74,6 +74,11 @@ of dependencies.
   use `nonnative` against real dependencies. Do not flag the in-repository
   service proxy success scenario's connection-only assertion as a test gap
   unless the task is explicitly about changing service proxy forwarding.
+- `Nonnative::FaultInjectionProxy` owns its listener thread and stops it by
+  closing the owned `TCPServer`, which wakes the accept loop before joining the
+  thread. Do not flag the listener `join` as an unbounded reliability gap unless
+  the task is explicitly about proxy shutdown behavior or there is a normal-use
+  reproducer, failing CI evidence, or platform-specific hang evidence.
 
 ## Runtime Model
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.9.0)
+    nonnative (3.11.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)

data/README.md

@@ -38,6 +38,18 @@ Or install it yourself as:
 gem install nonnative
 ```
 
+## 🛠️ Contributor Bootstrap
+
+Fresh clones need the shared `bin/` submodule before Make targets can load:
+
+```bash
+git submodule sync && git submodule update --init
+make help
+```
+
+Use `make dep` before local validation when dependencies are missing. The CI-parity checks are
+`make lint`, `make sec`, `make features`, and `make benchmarks`.
+
 ## 🚀 Usage
 
 Nonnative is configured via `Nonnative.configure` (programmatic) or `config.load_file(...)` (YAML).
@@ -67,12 +79,12 @@ Process/server fields:
 - `log`: per-runner log file used by process output redirection or server implementations.
 
 Process-only fields:
-- `readiness`: optional HTTP startup readiness check with explicit `port` and `path`.
+- `readiness`: optional HTTP startup readiness check with explicit `port` and path-only `path`.
 
 Service fields:
 - `port`: client-facing service port. Services do not get TCP readiness/shutdown checks from Nonnative.
 
-Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into an HTTP readiness check that runs after TCP readiness succeeds.
+Nonnative readiness and shutdown checks are TCP port checks by default. Configure process/server ports that are dedicated to the test run; if another process is already listening on the same endpoint, results are undefined. Processes can also opt into an HTTP readiness check that runs after TCP readiness succeeds. HTTP readiness paths must be path-only values, such as `/test/readyz`; absolute URLs and scheme-relative URLs are rejected.
 
 > [!WARNING]
 > TCP readiness and shutdown checks only prove that a TCP port opened or closed. HTTP readiness is process-only, checks for a 2xx response, and does not verify gRPC health, schema readiness, migrations, or other application-specific health.
@@ -94,7 +106,40 @@ Nonnative.stop
 `Nonnative.start` starts services first, then servers and processes. `Nonnative.stop` stops processes and servers first, then services. If startup fails, Nonnative rolls back runners that already started and raises `Nonnative::StartError`; shutdown failures raise `Nonnative::StopError`.
 
 > [!NOTE]
-> `Nonnative.clear` clears memoized configuration, logger, observability client, and pool. Use it before reconfiguring Nonnative in the same Ruby process.
+> `Nonnative.start` / `Nonnative.stop` manage one lifecycle for the current pool.
+> Call `Nonnative.clear` before reconfiguring Nonnative or starting a new lifecycle in the same Ruby process.
+> `Nonnative.clear` clears memoized configuration, logger, observability client, and pool.
+
+### 🧩 Test framework setup
+
+For Cucumber, load and configure Nonnative in `features/support/env.rb`, then use lifecycle tags on scenarios:
+
+```ruby
+require 'nonnative'
+
+Nonnative.configure do |config|
+  config.load_file('configuration.yml')
+end
+```
+
+```cucumber
+@startup
+Scenario: run with Nonnative around this scenario
+```
+
+For RSpec or another suite that should start Nonnative once per test run, configure first and then require the startup integration:
+
+```ruby
+require 'nonnative'
+
+Nonnative.configure do |config|
+  config.load_file('configuration.yml')
+end
+
+require 'nonnative/startup'
+```
+
+`nonnative/startup` calls `Nonnative.start` immediately and registers an `at_exit` stop, so load configuration before requiring it.
 
 ### 📈 Observability
 
@@ -121,7 +166,7 @@ expect(response.code).to eq(200)
 
 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)
+- `@manual`: stop after scenario; use `When I start the system` to start manually
 - `@clear`: clears memoized configuration, logger, observability client, and pool before scenario
 - `@reset`: resets proxies after scenario
 
@@ -138,14 +183,6 @@ The repo’s own Cucumber suite also uses taxonomy tags to classify coverage:
 
 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
-require 'nonnative/startup'
-```
-
-This calls `Nonnative.start` immediately and registers an `at_exit` stop.
-
 ### ⚙️ Processes
 
 A process is some sort of command that you would run locally.

data/lib/nonnative/configuration_readiness.rb

@@ -9,7 +9,7 @@ module Nonnative
     # @return [Integer] process HTTP readiness port
     attr_accessor :port
 
-    # @return [String] HTTP readiness path
+    # @return [String] path-only HTTP readiness path
     attr_accessor :path
 
     # @param value [Hash, #to_h] readiness attributes
@@ -30,6 +30,15 @@ module Nonnative
     def validate!
       raise ArgumentError, "Process readiness requires 'port'" if port.nil?
       raise ArgumentError, "Process readiness requires 'path'" if path.nil?
+      raise ArgumentError, 'Process readiness path must be path-only' unless path_only?
+    end
+
+    def path_only?
+      uri = URI.parse(path.to_s)
+
+      uri.scheme.nil? && uri.host.nil?
+    rescue URI::InvalidURIError
+      false
     end
   end
 end

data/lib/nonnative/cucumber.rb

@@ -43,10 +43,11 @@ module Nonnative
       end
 
       def install_hooks
+        # Register @clear before startup hooks so combined tags reset stale state before creating a pool.
+        Before('@clear') { Nonnative.clear }
         Before('@startup') { Nonnative.start }
         After('@startup') { Nonnative.stop }
         After('@manual') { Nonnative.stop }
-        Before('@clear') { Nonnative.clear }
         After('@reset') { Nonnative.reset }
       end
     end

data/lib/nonnative/http_probe.rb

@@ -28,7 +28,7 @@ module Nonnative
       Nonnative.logger.info "checking if readiness '#{endpoint}' is ready"
 
       timeout.perform do
-        response = get(readiness.path)
+        response = get(path)
         raise Nonnative::Error unless ready_response?(response)
 
         true

data/lib/nonnative/no_proxy.rb

@@ -4,8 +4,8 @@ module Nonnative
   # No-op proxy implementation.
   #
   # This is the default proxy when `service.proxy.kind` is `"none"`.
-  # It does not bind/listen or alter traffic; it simply exposes the underlying runner's configured
-  # `host` and primary `port`.
+  # It does not bind/listen or alter traffic; it simply exposes the service configuration's
+  # client-facing `host` and `port`.
   #
   # Services can always call `start`, `stop`, and `reset` safely on this proxy.
   #
@@ -41,7 +41,7 @@ module Nonnative
 
     # Returns the host clients should connect to.
     #
-    # For {NoProxy}, this is the underlying runner configuration host.
+    # For {NoProxy}, this is the service configuration's client-facing `host`.
     #
     # @return [String]
     def host
@@ -50,7 +50,7 @@ module Nonnative
 
     # Returns the port clients should connect to.
     #
-    # For {NoProxy}, this is the first underlying runner configuration port.
+    # For {NoProxy}, this is the service configuration's client-facing `port`.
     #
     # @return [Integer]
     def port

data/lib/nonnative/process.rb

@@ -20,6 +20,9 @@ module Nonnative
       @timeout = Nonnative::Timeout.new(service.timeout)
     end
 
+    # @return [GetProcessMem, nil] memory reader for the current process lifecycle
+    attr_reader :memory
+
     # Spawns the configured process if it is not already running.
     #
     # @return [Array<(Integer, Boolean)>]
@@ -29,6 +32,8 @@ module Nonnative
     def start
       unless process_exists?
         @pid = process_spawn
+        # Keep memory reads bound to the child spawned for this lifecycle.
+        @memory = GetProcessMem.new(pid)
         wait_start
       end
 
@@ -53,17 +58,8 @@ module Nonnative
       end
 
       [pid, stopped]
-    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?
-
-      @memory ||= GetProcessMem.new(pid)
+    ensure
+      @memory = nil
     end
 
     protected

data/lib/nonnative/startup.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Starts the configured Nonnative pool immediately and registers an `at_exit` stop hook.
+#
+# Configure Nonnative before requiring this file; it is intended for suites that keep one
+# Nonnative lifecycle open for the whole Ruby process.
+
 at_exit do
   Nonnative.stop
 end

data/lib/nonnative/version.rb

@@ -4,5 +4,5 @@ module Nonnative
   # The current gem version.
   #
   # @return [String]
-  VERSION = '3.9.0'
+  VERSION = '3.11.0'
 end

data/lib/nonnative.rb

@@ -48,6 +48,7 @@ require 'yaml'
 require 'open3'
 require 'securerandom'
 require 'shellwords'
+require 'uri'
 
 require 'grpc'
 require 'sinatra'
@@ -204,8 +205,12 @@ module Nonnative
 
     # Resolves a proxy implementation for a configured kind.
     #
+    # `nil` and `"none"` resolve to {Nonnative::NoProxy}; any other kind must be registered in
+    # {Nonnative.proxies}.
+    #
     # @param kind [String] proxy kind name (for example `"fault_injection"`)
     # @return [Class] a subclass of {Nonnative::Proxy}
+    # @raise [ArgumentError] if the kind is not `"none"` and has not been registered
     def proxy(kind)
       kind.nil? || kind == 'none' ? NoProxy : proxies.fetch(kind) { raise ArgumentError, "Unsupported proxy kind '#{kind}'" }
     end
@@ -286,6 +291,9 @@ module Nonnative
 
     # Clears memoized configuration, logger, observability client, and pool.
     #
+    # Call this before reconfiguring Nonnative or starting a new lifecycle in the same Ruby process.
+    # `start`/`stop` are intended to manage one lifecycle for the current pool.
+    #
     # @return [void]
     def clear
       clear_logger

data/nonnative.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Alejandro Falkowski']
   spec.email         = ['alexrfalkowski@gmail.com']
 
-  spec.summary       = 'Allows you to keep using the power of Ruby to test other systems'
-  spec.description   = spec.summary
+  spec.summary       = 'Ruby-first end-to-end harness for testing systems implemented in other languages'
+  spec.description   = 'Starts OS processes, in-process Ruby servers, and proxy-only services with TCP readiness checks and fault-injection proxies.'
   spec.homepage      = 'https://github.com/alexfalkowski/nonnative'
   spec.license       = 'MIT'
   spec.files         = Dir.chdir(File.expand_path(__dir__)) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.11.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -263,7 +263,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
-description: Allows you to keep using the power of Ruby to test other systems
+description: Starts OS processes, in-process Ruby servers, and proxy-only services
+  with TCP readiness checks and fault-injection proxies.
 email:
 - alexrfalkowski@gmail.com
 executables: []
@@ -351,5 +352,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.11
 specification_version: 4
-summary: Allows you to keep using the power of Ruby to test other systems
+summary: Ruby-first end-to-end harness for testing systems implemented in other languages
 test_files: []