nonnative 3.2.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 522cec08aee3855943f6ef6ba38bec3d85acd00aeeb2d6640a6869cf55014518
-  data.tar.gz: ebebc8d342a2111f8fb8538c0bf5b615c549b61127761c3e2ada47397294b47c
+  metadata.gz: 0fb25075ea94da70b097c6b60e7a47fea1a73b7e80d4903f32b2a2d00675b50e
+  data.tar.gz: 33c1c4310fa48a1a8dacf792d9ce6af73f9a406f67185f61fb292f07d06d2345
 SHA512:
-  metadata.gz: e4df243398b167fb955324fe12894f8bb5ecaf4ec612f8c55ad73e6cf95d6e04868ad1ee2ff64c1fbbc68322ea96dc953a0329b01f609a31b5409fb38542f09a
-  data.tar.gz: 419ca92810588c41e281cd4d77e49651bee8c412d7285689f196c176473364f1562eabbe1944a121e238e79c9cfb0de6335bbcde05b6e068478c45db4414cef2
+  metadata.gz: c1c7e788eacbf1ed02100d4fc954f3ab7781c17a4e8c46c8ca8764becea615d54c6dee3be60404901228b37397533a809873c3ae27a157ac53463ff048ce8d50
+  data.tar.gz: fc73665d0141f943beca8dd9d43adbee088a214d1d31dad757fed1502df707f8ae599f10f4d5b3eb0b0c7e8c7db4b43b860cdd655e90d49c194320148df65439

data/.circleci/config.yml

@@ -1,15 +1,33 @@
 version: 2.1
 
+commands:
+  sync-submodules:
+    steps:
+      - run: git submodule sync
+      - run: git submodule update --init
+  checkout-submodules:
+    steps:
+      - checkout:
+          method: blobless
+      - sync-submodules
+
+executors:
+  ruby:
+    docker:
+      - image: alexfalkowski/ruby:3.17
+  release:
+    docker:
+      - image: alexfalkowski/release:8.18
+  alpine:
+    docker:
+      - image: alpine:latest
+
 jobs:
   build:
-    docker:
-      - image: alexfalkowski/ruby:3.14
+    executor: ruby
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: make source-key
       - restore_cache:
           name: restore deps
@@ -34,34 +52,25 @@ jobs:
       - run: make codecov-upload
     resource_class: arm.large
   sync:
-    docker:
-      - image: alexfalkowski/release:8.15
+    executor: release
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: make sync push
     resource_class: arm.large
   version:
-    docker:
-      - image: alexfalkowski/release:8.15
+    executor: release
     working_directory: ~/nonnative
     steps:
-      - checkout:
-          method: blobless
-      - run: git submodule sync
-      - run: git submodule update --init
+      - checkout-submodules
       - run: version
       - run: package
     resource_class: arm.large
   wait-all:
-    docker:
-      - image: alexfalkowski/ruby:3.14
+    executor: alpine
+    resource_class: small
     steps:
       - run: echo "all applicable jobs finished"
-    resource_class: arm.large
 
 workflows:
   nonnative:

data/.gitignore

@@ -1,9 +1,18 @@
 /.bundle/
+.crush/
+.ruby-lsp/
+.source-key
 /.yardoc
 /_yardoc/
 /doc/
 /pkg/
+ISSUES.md
+TESTS.md
+DOCS.md
+FEATURES.md
+PROJECTS.md
+RELIABILITY.md
 test/reports/*
+!test/reports/.keep
 /tmp/
-vendor
-ISSUES.md
+vendor/

data/AGENTS.md

@@ -1,10 +1,8 @@
 # AGENTS.md
 
-## Shared skills
+## Shared guidance
 
-This repository uses the shared skills from `bin/skills/`. Read
-`bin/AGENTS.md` for the canonical shared skill list and use the smallest
-matching skill for the task.
+Use `bin/AGENTS.md` for shared skills and cross-repository defaults.
 
 `nonnative` is a Ruby gem for end-to-end testing systems implemented in other
 languages. It starts processes, in-process servers, and proxy-only services,
@@ -18,18 +16,16 @@ of dependencies.
 - Generated gRPC test stubs: `test/grpc/**/*`
 - Test protos: `test/nonnative/v1/*.proto`
 - Build wiring: root `Makefile` includes `bin/build/make/*.mak`
-- Required submodule: `bin/` from `git@github.com:alexfalkowski/bin.git`; missing SSH/submodule setup breaks `make`
+- Required submodule: `bin/`; missing submodule setup breaks `make`
 - Install deps: `make dep`
 - Lint: `make lint`
+- Security checks: `make sec`
 - Features: `make features`
 - Benchmarks only: `make benchmarks`
 - Cleanup: `make clean-dep`, `make clean-reports`
 
 ## Intentional Design Choices
 
-- Root `make` compatibility is GNU Make 4+/`gmake` oriented through the shared
-  `bin/build/make/*.mak` fragments. Do not flag GNU Make 3.81 parsing failures
-  as code issues unless the task is explicitly about supporting GNU Make 3.81.
 - The configured HTTP proxy feature intentionally uses the external
   `www.afalkowski.com` host through `features/support/http_proxy_server.rb`.
   Do not flag this external dependency as a code issue unless the task is
@@ -54,6 +50,10 @@ of dependencies.
   test proto changes. Do not flag the absence of an automatic generated-stub
   freshness check as a test gap unless the task is explicitly about changing
   test proto generation or generated-file validation.
+- Generated gRPC test stubs may carry manual require-path adjustments after
+  generation. Do not treat `make -C test stale` as a required validation target
+  unless the task is explicitly about changing test proto generation; verify
+  the generated Ruby loads before accepting generator-only rewrites.
 - Buf linting for the test-only proto module is intentionally not part of the
   required local validation surface. Do not flag missing root-level validation
   for `test/buf.yaml` as a test gap unless the task is explicitly about test

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nonnative (3.2.1)
+    nonnative (3.6.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)
@@ -26,7 +26,7 @@ GEM
     benchmark-trend (0.4.0)
     bigdecimal (4.1.2)
     builder (3.3.0)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.7)
     config (5.6.1)
       deep_merge (~> 1.2, >= 1.2.1)
       ostruct
@@ -64,24 +64,24 @@ GEM
     get_process_mem (1.0.0)
       bigdecimal (>= 2.0)
       ffi (~> 1.0)
-    google-protobuf (4.35.0-x86_64-darwin)
+    google-protobuf (4.35.1-x86_64-darwin)
       bigdecimal
       rake (~> 13.3)
-    google-protobuf (4.35.0-x86_64-linux-gnu)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
     googleapis-common-protos-types (1.23.0)
       google-protobuf (~> 4.26)
-    grpc (1.81.0-x86_64-darwin)
+    grpc (1.81.1-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.81.0-x86_64-linux-gnu)
+    grpc (1.81.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.1.6)
       domain_name (~> 0.5)
-    json (2.19.8)
+    json (2.20.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -114,7 +114,7 @@ GEM
       rack (>= 3.0.0)
     rainbow (3.1.1)
     rake (13.4.2)
-    rbs (4.0.2)
+    rbs (4.0.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -146,7 +146,7 @@ GEM
     rspec-support (3.13.7)
     rspec-wait (1.0.2)
       rspec (>= 3.4)
-    rubocop (1.87.0)
+    rubocop (1.88.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -169,7 +169,7 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (3.1.0)
+    simplecov-cobertura (3.2.0)
       rexml
       simplecov (~> 0.19)
     simplecov-html (0.13.2)

data/README.md

@@ -62,7 +62,7 @@ Common runner fields:
 
 Process/server fields:
 - `ports`: client-facing ports. These are also used for readiness/shutdown port checks.
-- `timeout`: max time (seconds) for readiness/shutdown port checks.
+- `timeout`: max time (seconds) for readiness/shutdown port checks. Defaults to `1.0`.
 - `wait`: small sleep (seconds) between lifecycle steps.
 - `log`: per-runner log file used by process output redirection or server implementations.
 
@@ -164,7 +164,7 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.name = 'start_1'
-    p.command = -> { ['features/support/bin/start', '12_321'] }
+    p.command = -> { ['bin/start-test-service', '12_321'] }
     p.timeout = 5
     p.wait = 0.1
     p.ports = [12_321]
@@ -177,7 +177,7 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.name = 'start_2'
-    p.command = -> { ['features/support/bin/start', '12_322'] }
+    p.command = -> { ['bin/start-test-service', '12_322'] }
     p.timeout = 0.5
     p.wait = 0.1
     p.ports = [12_322]
@@ -197,7 +197,7 @@ processes:
   -
     name: start_1
     command:
-      - features/support/bin/start
+      - bin/start-test-service
       - "12_321"
     timeout: 5
     wait: 1
@@ -210,7 +210,7 @@ processes:
   -
     name: start_2
     command:
-      - features/support/bin/start
+      - bin/start-test-service
       - "12_322"
     timeout: 5
     wait: 1
@@ -474,6 +474,8 @@ end
 
 Define your server:
 
+Assume the gRPC service base class and response types below come from your generated gRPC stubs.
+
 ```ruby
 module Nonnative
   module Features
@@ -530,6 +532,9 @@ servers:
     log: grpc_server_1.log
 ```
 
+The `grpc` gem uses a global logger, so per-server gRPC log files are not independent. The first
+initialized gRPC server sets the logger used by later gRPC servers in the same Ruby process.
+
 Then load the file with:
 
 ```ruby

data/lib/nonnative/configuration.rb

@@ -42,13 +42,25 @@ module Nonnative
     end
 
     # @return [String, nil] logical system name (used for observability endpoints)
+    attr_accessor :name
+
     # @return [String, nil] configuration version
+    attr_accessor :version
+
     # @return [String, nil] base URL for observability queries (for example `"http://127.0.0.1:8080"`)
+    attr_accessor :url
+
     # @return [String, nil] path to the Nonnative log file
+    attr_accessor :log
+
     # @return [Array<Nonnative::ConfigurationProcess>] configured processes
+    attr_accessor :processes
+
     # @return [Array<Nonnative::ConfigurationServer>] configured in-process servers
+    attr_accessor :servers
+
     # @return [Array<Nonnative::ConfigurationService>] configured services (proxy-only)
-    attr_accessor :name, :version, :url, :log, :processes, :servers, :services
+    attr_accessor :services
 
     # Loads a configuration file and appends its runners to this instance.
     #
@@ -179,7 +191,8 @@ module Nonnative
 
     def runner_attributes(runner, loaded)
       runner.name = loaded.name
-      runner.timeout = loaded.timeout
+      timeout = loaded.timeout
+      runner.timeout = timeout unless timeout.nil?
       runner.wait = loaded.wait if loaded.wait
       runner.host = loaded.host if loaded.host
       assign_ports(runner, loaded)

data/lib/nonnative/configuration_process.rb

@@ -19,7 +19,7 @@ module Nonnative
     # @return [String, nil] signal name to use for stopping (defaults to `"INT"` when not set)
     attr_accessor :signal
 
-    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close (defaults to `1.0`)
     attr_accessor :timeout
 
     # @return [String] log file path to append process stdout/stderr to
@@ -27,5 +27,17 @@ module Nonnative
 
     # @return [Hash, nil] environment variables to pass to the spawned process
     attr_accessor :environment
+
+    # Creates a process configuration with bounded lifecycle defaults.
+    #
+    # Defaults:
+    # - `timeout`: `1.0`
+    #
+    # @return [void]
+    def initialize
+      super
+
+      self.timeout = DEFAULT_TIMEOUT
+    end
   end
 end

data/lib/nonnative/configuration_proxy.rb

@@ -15,12 +15,21 @@ module Nonnative
   # @see Nonnative.proxies
   class ConfigurationProxy
     # @return [String] proxy kind name (for example `"none"` or `"fault_injection"`)
+    attr_accessor :kind
+
     # @return [String] upstream host used by proxy implementations (defaults to `"127.0.0.1"`)
+    attr_accessor :host
+
     # @return [Integer] upstream port used by proxy implementations (defaults to `0`)
+    attr_accessor :port
+
     # @return [String, nil] path to proxy log file (implementation-dependent)
+    attr_accessor :log
+
     # @return [Numeric] wait interval (seconds) after proxy state changes (defaults to `0.1`)
+    attr_accessor :wait
+
     # @return [Hash] proxy implementation options (implementation-dependent)
-    attr_accessor :kind, :host, :port, :log, :wait
     attr_reader :options
 
     # Creates a proxy configuration with defaults.

data/lib/nonnative/configuration_runner.rb

@@ -12,11 +12,17 @@ module Nonnative
   # @see Nonnative::ConfigurationServer
   # @see Nonnative::ConfigurationService
   class ConfigurationRunner
+    # Default bounded readiness/shutdown timeout for process and server runners.
+    DEFAULT_TIMEOUT = 1.0
+
     # @return [String, nil] runner name used for lookup (for example via `pool.process_by_name`)
+    attr_accessor :name
+
     # @return [String] host to bind/connect to (defaults to `"127.0.0.1"`)
-    # @return [Array<Integer>] ports to bind/connect to
+    attr_accessor :host
+
     # @return [Numeric] wait interval (seconds) used by runners between lifecycle steps
-    attr_accessor :name, :host, :wait
+    attr_accessor :wait
 
     # @return [Array<Integer>] client-facing ports used for readiness/shutdown checks
     attr_reader :ports

data/lib/nonnative/configuration_server.rb

@@ -11,9 +11,25 @@ module Nonnative
   # @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 ports to open/close
+    # @return [Class] a class that implements `#initialize(service)` and the hooks expected by {Nonnative::Server}
+    attr_accessor :klass
+
+    # @return [Numeric] readiness timeout (seconds) used when waiting for ports to open/close (defaults to `1.0`)
+    attr_accessor :timeout
+
     # @return [String] log file path used by server implementations (for example Puma/gRPC log files)
-    attr_accessor :klass, :timeout, :log
+    attr_accessor :log
+
+    # Creates a server configuration with bounded lifecycle defaults.
+    #
+    # Defaults:
+    # - `timeout`: `1.0`
+    #
+    # @return [void]
+    def initialize
+      super
+
+      self.timeout = DEFAULT_TIMEOUT
+    end
   end
 end

data/lib/nonnative/cucumber.rb

@@ -8,6 +8,26 @@ module Nonnative
   # Requiring `nonnative` outside a running Cucumber environment should not fail, but when Cucumber
   # does finish booting its support-code registry this installer still needs to register the hooks
   # and step definitions defined here.
+  #
+  # Supported hooks:
+  # - `@startup`: start before scenario, stop after scenario
+  # - `@manual`: stop after scenario; use `When I start the system` to start manually
+  # - `@clear`: clear memoized Nonnative state before scenario
+  # - `@reset`: reset proxies after scenario
+  #
+  # Installed step definitions:
+  # - `Given I set the proxy for service {string} to {string}`
+  # - `Then I should reset the proxy for service {string}`
+  # - `When I start the system`
+  # - `When I attempt to start the system`
+  # - `When I attempt to stop the system`
+  # - `Then I should see {string} as unhealthy`
+  # - `Then I should see {string} as healthy`
+  # - `Then the process {string} should consume less than {string} of memory`
+  # - `Then starting the system should raise an error`
+  # - `Then stopping the system should raise an error`
+  # - `Then I should see a log entry of {string} for process {string}`
+  # - `Then I should see a log entry of {string} in the file {string}`
   module Cucumber
     module LanguageHook
       def rb_language=(value)

data/lib/nonnative/fault_injection_proxy.rb

@@ -11,7 +11,7 @@ module Nonnative
   #
   # - {#close_all}: close connections immediately on accept
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
-  # - {#invalid_data}: corrupt outbound data by shuffling characters
+  # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
   # - {#reset}: return to healthy pass-through behavior
   #
   # State changes terminate any active connections so new connections observe the new behavior.
@@ -107,7 +107,7 @@ module Nonnative
       apply_state :delay
     end
 
-    # Corrupts forwarded data by shuffling characters.
+    # Mutates upstream responses while forwarding client requests unchanged.
     #
     # @return [void]
     def invalid_data

data/lib/nonnative/http_proxy_server.rb

@@ -23,6 +23,14 @@ module Nonnative
   #
   # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
   class HTTPProxy < Sinatra::Application
+    NON_FORWARDABLE_HEADERS = %w[
+      Host
+      Accept-Encoding
+      Version
+      Proxy-Authenticate
+      Proxy-Authorization
+    ].freeze
+
     # Extracts request headers from the Rack environment and normalizes them to standard HTTP names.
     #
     # Certain hop-by-hop or proxy-specific headers are removed.
@@ -36,7 +44,7 @@ module Nonnative
         result[normalized_header_name(header)] = value
       end
 
-      headers.except('Host', 'Accept-Encoding', 'Version')
+      headers.except(*NON_FORWARDABLE_HEADERS)
     end
 
     # Builds the upstream URL for the given request.

data/lib/nonnative/http_server.rb

@@ -9,14 +9,20 @@ module Nonnative
   # The server is started and stopped by {Nonnative::Server} via {#perform_start} / {#perform_stop}.
   #
   # @example Running a Sinatra app
-  #   app = Sinatra.new do
-  #     get('/hello') { 'Hello World!' }
+  #   class HelloHTTPServer < Nonnative::HTTPServer
+  #     def initialize(service)
+  #       app = Sinatra.new do
+  #         get('/hello') { 'Hello World!' }
+  #       end
+  #
+  #       super(app, service)
+  #     end
   #   end
   #
   #   Nonnative.configure do |config|
   #     config.server do |s|
   #       s.name = 'http'
-  #       s.klass = ->(service) { Nonnative::HTTPServer.new(app, service) }
+  #       s.klass = HelloHTTPServer
   #       s.timeout = 2
   #       s.host = '127.0.0.1'
   #       s.ports = [4567]
@@ -24,7 +30,7 @@ module Nonnative
   #     end
   #   end
   #
-  # Note: In YAML configuration you typically set `class` to a concrete subclass that calls `super(app, service)`.
+  # YAML configuration uses the same concrete subclass name in its `class` field.
   #
   # @see Nonnative::Server
   class HTTPServer < Nonnative::Server
@@ -33,7 +39,8 @@ module Nonnative
     # @param app [#call] a Rack-compatible application (e.g. Sinatra/Rack app)
     # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(app, service)
-      log = File.open(service.log, 'a')
+      # Keep the log IO so the server lifecycle can release Puma's file handle on stop.
+      @log = File.open(service.log, 'a')
       options = {
         log_writer: Puma::LogWriter.new(log, log),
         force_shutdown_after: service.timeout
@@ -60,10 +67,16 @@ module Nonnative
     # @return [void]
     def perform_stop
       server.graceful_shutdown
+    ensure
+      close_log
     end
 
     private
 
-    attr_reader :server
+    attr_reader :server, :log
+
+    def close_log
+      log.close unless log.closed?
+    end
   end
 end

data/lib/nonnative/process.rb

@@ -49,6 +49,7 @@ module Nonnative
       if process_exists?
         process_kill
         stopped = wait_stop != false
+        force_stop unless stopped
       end
 
       [pid, stopped]
@@ -82,6 +83,13 @@ module Nonnative
       ::Process.kill(signal, pid)
     end
 
+    def force_stop
+      ::Process.kill('KILL', pid)
+      wait_stop
+    rescue Errno::ESRCH, Errno::ECHILD
+      true
+    end
+
     def process_spawn
       environment = service.environment.to_h
       environment = environment.transform_keys(&:to_s).transform_values(&:to_s)

data/lib/nonnative/proxy.rb

@@ -6,11 +6,14 @@ module Nonnative
   # A proxy is responsible for interposing behavior between a client and a target service.
   # Runtime services create a proxy instance via {Nonnative::ProxyFactory} based on `service.proxy.kind`.
   #
+  # Service configuration `host` and `port` are the client-facing endpoint. Concrete proxy methods are
+  # implementation-specific; for example {Nonnative::FaultInjectionProxy#host} and
+  # {Nonnative::FaultInjectionProxy#port} return the upstream target behind the proxy.
+  #
   # 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

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -36,10 +36,10 @@
 #   # run tests...
 #   Nonnative.stop
 #
-# == Notes
+# == Cucumber integration
 #
-# 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.
+# Requiring `nonnative` loads the lazy Cucumber integration. It is safe outside a booted Cucumber
+# runtime; hooks and step definitions are installed once Cucumber's Ruby DSL is ready.
 #
 require 'socket'
 require 'timeout'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.6.0
 platform: ruby
 authors:
 - Alejandro Falkowski