nonnative 3.13.0 → 3.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 304a9d9d01fafb9f0822e4510c647f87095f78987feecb5a9d2eddc43317a880
-  data.tar.gz: 366157abd34f6ffa48cce159dffd49075e4a98653ea5d3f3b11b2494ad47b4a1
+  metadata.gz: 8c6665f1bde87f38b1ba0622168efd569d1cce78df5773597984ab3eb07e07e6
+  data.tar.gz: 5662743abeb5f331675ef634754c024fed13f876664d5e0beccea21199c47f9a
 SHA512:
-  metadata.gz: 6fa7d92393e3a4df9f400a7f35c857998c13dc026ec85be407fa37d6e8ba2189c5992af70e001c1cdfaf9589d1b6d33a2daf11abf8361f84f07ab8bc3a72fed1
-  data.tar.gz: bf37673b803ff66338009fbbd458d707c6eed9ef0ba618bb53b97e2f5770788708343f6bd34b67758fd6d1a13e464f63edffced76c26591f8ac4fe4ec2267a3e
+  metadata.gz: 1ec6d29ca79065600e123c9ec4e78d3d0b8ca76f06538b88c21b771f7be3ffce428f77949c80da574f7420826385e637de94f164711be82a5c7bc664a8ca9e41
+  data.tar.gz: 0aba7bdf975ef0f28ae9eb5f14ab4a78d8cf160ac09e63ebaff38d8edddbec8bb3fb94855dec864f18972771ad97076bcb0cfae2e5ad3713e6e0f87e65c38de6

data/.circleci/config.yml

@@ -17,7 +17,7 @@ executors:
       - image: alexfalkowski/ruby:3.19
   release:
     docker:
-      - image: alexfalkowski/release:8.19
+      - image: alexfalkowski/release:8.20
   alpine:
     docker:
       - image: alpine:latest

data/AGENTS.md

@@ -79,6 +79,32 @@ of dependencies.
   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.
+- Service readiness is intentionally TCP-only for externally managed
+  dependencies. Do not flag missing HTTP/gRPC service readiness as a feature gap
+  unless the task is explicitly about changing the `Nonnative::Service`
+  readiness model. HTTP/gRPC readiness belongs to managed processes, where the
+  user explicitly models the application health endpoints.
+- Process runners intentionally inherit the parent working directory. Nonnative
+  is normally run from the test folder that owns `test/nonnative.yml`, relative
+  config paths, logs, and reports. Do not flag missing process cwd/chdir support
+  as a feature gap unless the task is explicitly about changing process working
+  directory behavior.
+- Message-specific start/stop assertions and attempted-stop success assertions
+  in `features/step_definitions/lifecycle_steps.rb` are repository-local
+  Cucumber helpers. Do not flag their absence from `lib/nonnative/cucumber.rb`
+  as a feature gap unless downstream usage evidence exists or the task is
+  explicitly about expanding public lifecycle assertion steps.
+- Liveness, readiness, and metrics endpoint assertion steps in
+  `features/step_definitions/servers_steps.rb` are repository-local Cucumber
+  helpers for testing nonnative's own framework assumptions. Do not flag their
+  absence from `lib/nonnative/cucumber.rb` as a feature gap unless downstream
+  usage evidence exists or the task is explicitly about expanding public
+  observability assertion steps.
+- `Nonnative::Configuration` intentionally exposes `process_by_name` without
+  matching `server_by_name` or `service_by_name` helpers. Do not flag missing
+  server/service configuration lookup helpers as a feature gap unless downstream
+  usage evidence exists or the task is explicitly about changing the
+  pre-start configuration lookup API.
 
 ## Runtime Model
 

data/Gemfile.lock

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

data/README.md

@@ -410,7 +410,7 @@ Define your server:
 ```ruby
 module Nonnative
   module Features
-    class Hello < Sinatra::Application
+    class HelloService < Nonnative::HTTPService
       get '/hello' do
         'Hello World!'
       end
@@ -418,7 +418,7 @@ module Nonnative
 
     class HTTPServer < Nonnative::HTTPServer
       def initialize(service)
-        super(Sinatra.new(Hello), service)
+        super(HelloService.new, service)
       end
     end
   end
@@ -543,7 +543,7 @@ end
 
 Define your server:
 
-Assume the gRPC service base class and response types below come from your generated gRPC stubs.
+Assume the gRPC service type and response types below come from your generated gRPC stubs.
 
 ```ruby
 module Nonnative
@@ -758,6 +758,7 @@ Clients connect to the service `host`/`port`, while the proxy forwards traffic t
 
 - `close_all` - Closes the socket as soon as it connects.
 - `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through options.
+- `timeout` - Accepts the connection and stalls traffic until reset or stop closes the connection, so clients exercise their own read timeout behavior.
 - `invalid_data` - Forwards client requests unchanged, then corrupts upstream responses before they reach the client.
 
 ###### 🧩 Fault Injection Services
@@ -769,6 +770,7 @@ name = 'name of service in configuration'
 service = Nonnative.pool.service_by_name(name)
 
 service.proxy.close_all # To use close_all.
+service.proxy.timeout # To stall traffic until reset or stop.
 service.proxy.reset # To reset it back to a good state.
 ```
 
@@ -776,6 +778,7 @@ Use the Cucumber proxy steps:
 
 ```cucumber
 Given I set the proxy for service 'service_1' to 'close_all'
+Given I set the proxy for service 'service_1' to 'timeout'
 Then I should reset the proxy for service 'service_1'
 ```
 

data/lib/nonnative/configuration_proxy.rb

@@ -4,8 +4,8 @@ module Nonnative
   # Proxy configuration attached to a service 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.
+  # the built-in `"fault_injection"` proxy can close connections, introduce delays, stall traffic,
+  # or corrupt data for resilience testing.
   #
   # This object is created automatically for each service via {Nonnative::ConfigurationService}.
   # When `kind` is set to `"none"`, no proxy is started and the service will use its configured

data/lib/nonnative/cucumber.rb

@@ -56,6 +56,7 @@ module Nonnative
       PROXY_OPERATIONS = {
         'close_all' => :close_all,
         'delay' => :delay,
+        'timeout' => :timeout,
         'invalid_data' => :invalid_data,
         'reset' => :reset
       }.freeze

data/lib/nonnative/error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Nonnative
-  # Base class for all Nonnative errors.
+  # Parent error for all Nonnative errors.
   #
   # Catch this error type if you want to handle any exception raised by this gem.
   #

data/lib/nonnative/fault_injection_proxy.rb

@@ -11,6 +11,7 @@ module Nonnative
   #
   # - {#close_all}: close connections immediately on accept
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
+  # - {#timeout}: accept connections and keep them silent until clients time out
   # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
   # - {#reset}: return to healthy pass-through behavior
   #
@@ -107,6 +108,17 @@ module Nonnative
       apply_state :delay
     end
 
+    # Accepts connections and stalls without forwarding bytes.
+    #
+    # This simulates a dependency that accepts a TCP connection but leaves clients waiting until
+    # their own read timeout fires. The proxy keeps the connection silent until reset or stop closes
+    # active connections.
+    #
+    # @return [void]
+    def timeout
+      apply_state :timeout
+    end
+
     # Mutates upstream responses while forwarding client requests unchanged.
     #
     # @return [void]

data/lib/nonnative/http_proxy_server.rb

@@ -7,7 +7,7 @@
 #
 # This file defines two classes:
 #
-# - {Nonnative::HTTPProxy}: a Sinatra application that implements the proxying behavior.
+# - {Nonnative::HTTPProxy}: an HTTP service that implements the proxying behavior.
 # - {Nonnative::HTTPProxyServer}: a {Nonnative::HTTPServer} wrapper that runs the proxy app under Puma.
 #
 # Notes:
@@ -17,12 +17,12 @@
 # @see Nonnative::HTTPServer
 # @see Nonnative::Server
 module Nonnative
-  # Sinatra application implementing a simple forward proxy.
+  # HTTP service implementing a simple forward proxy.
   #
-  # The upstream host is configured via Sinatra settings (see {Nonnative::HTTPProxyServer}).
+  # The upstream host is configured via service settings (see {Nonnative::HTTPProxyServer}).
   #
   # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
-  class HTTPProxy < Sinatra::Application
+  class HTTPProxy < Nonnative::HTTPService
     NON_FORWARDABLE_HEADERS = %w[
       Host
       Accept-Encoding
@@ -135,13 +135,11 @@ module Nonnative
     # @param host [String] upstream host to proxy to (HTTPS)
     # @param service [Nonnative::ConfigurationServer] server configuration
     def initialize(host, service)
-      app = Sinatra.new(Nonnative::HTTPProxy) do
-        configure do
-          set :host, host
-        end
+      http_service = Class.new(Nonnative::HTTPProxy) do
+        set :host, host
       end
 
-      super(app, service)
+      super(http_service.new, service)
     end
   end
 end

data/lib/nonnative/http_server.rb

@@ -3,19 +3,19 @@
 module Nonnative
   # Puma-based HTTP server runner.
   #
-  # This is a convenience server implementation for running a Rack/Sinatra application in-process
-  # under Nonnative's server lifecycle. It binds to the configured server `host` and first `ports` entry.
+  # This is a convenience server implementation for running an HTTP service in-process under
+  # Nonnative's server lifecycle. It binds to the configured server `host` and first `ports` entry.
   #
   # The server is started and stopped by {Nonnative::Server} via {#perform_start} / {#perform_stop}.
   #
-  # @example Running a Sinatra app
+  # @example Running an HTTP service
+  #   class HelloHTTPService < Nonnative::HTTPService
+  #     get('/hello') { 'Hello World!' }
+  #   end
+  #
   #   class HelloHTTPServer < Nonnative::HTTPServer
   #     def initialize(service)
-  #       app = Sinatra.new do
-  #         get('/hello') { 'Hello World!' }
-  #       end
-  #
-  #       super(app, service)
+  #       super(HelloHTTPService.new, service)
   #     end
   #   end
   #
@@ -34,18 +34,18 @@ module Nonnative
   #
   # @see Nonnative::Server
   class HTTPServer < Nonnative::Server
-    # Creates a Puma server for the given Rack app and runner configuration.
+    # Creates a Puma server for the given HTTP service and runner configuration.
     #
-    # @param app [#call] a Rack-compatible application (e.g. Sinatra/Rack app)
+    # @param http_service [#call] an HTTP service instance
     # @param service [Nonnative::ConfigurationServer] server configuration
-    def initialize(app, service)
+    def initialize(http_service, service)
       # 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
       }
-      @server = Puma::Server.new(app, Puma::Events.new, options)
+      @server = Puma::Server.new(http_service, Puma::Events.new, options)
 
       super(service)
     end

data/lib/nonnative/http_service.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # HTTP service run by {Nonnative::HTTPServer}.
+  #
+  # Subclass this instead of `Sinatra::Application` when defining an in-process HTTP server for
+  # Nonnative. {Nonnative::HTTPServer} accepts a service instance and runs it under Puma.
+  class HTTPService < Sinatra::Application
+  end
+end

data/lib/nonnative/proxy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Nonnative
-  # Base class for proxy implementations.
+  # Parent type for proxy implementations.
   #
   # 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`.

data/lib/nonnative/socket_pair.rb

@@ -16,6 +16,7 @@ module Nonnative
   # @see Nonnative::SocketPairFactory
   # @see Nonnative::CloseAllSocketPair
   # @see Nonnative::DelaySocketPair
+  # @see Nonnative::TimeoutSocketPair
   # @see Nonnative::InvalidDataSocketPair
   class SocketPair
     # @param proxy [#host, #port, #options] proxy configuration used to connect upstream

data/lib/nonnative/socket_pair_factory.rb

@@ -10,18 +10,20 @@ module Nonnative
   # - `:none` (or any unknown value) -> {Nonnative::SocketPair} (pass-through)
   # - `:close_all` -> {Nonnative::CloseAllSocketPair}
   # - `:delay` -> {Nonnative::DelaySocketPair}
+  # - `:timeout` -> {Nonnative::TimeoutSocketPair}
   # - `:invalid_data` -> {Nonnative::InvalidDataSocketPair}
   #
   # @see Nonnative::FaultInjectionProxy
   # @see Nonnative::SocketPair
   # @see Nonnative::CloseAllSocketPair
   # @see Nonnative::DelaySocketPair
+  # @see Nonnative::TimeoutSocketPair
   # @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 kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:delay`, `:timeout`, `:invalid_data`)
       # @param proxy [Nonnative::ConfigurationProxy] proxy configuration (host/port/options)
       # @return [Nonnative::SocketPair] a socket-pair implementation instance
       def create(kind, proxy)
@@ -30,6 +32,8 @@ module Nonnative
                  CloseAllSocketPair
                when :delay
                  DelaySocketPair
+               when :timeout
+                 TimeoutSocketPair
                when :invalid_data
                  InvalidDataSocketPair
                else

data/lib/nonnative/timeout_socket_pair.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate read timeouts.
+  #
+  # When active, the proxy accepts the client connection and keeps it open without forwarding bytes.
+  # Clients with read deadlines should observe their own timeout behavior.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#timeout}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
+  class TimeoutSocketPair < SocketPair
+    # Keeps the accepted socket silent until reset or stop closes active proxy connections.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
+    def connect(local_socket)
+      @local_socket = local_socket
+
+      Nonnative.logger.info "stalling socket '#{local_socket.inspect}' for 'timeout' pair"
+
+      # Do not call super: the base implementation opens the upstream socket and forwards traffic.
+      sleep 0.1 until local_socket.closed?
+    ensure
+      close
+    end
+  end
+end

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -91,6 +91,7 @@ require 'nonnative/tcp_probe'
 require 'nonnative/http_probe'
 require 'nonnative/grpc_health'
 require 'nonnative/grpc_probe'
+require 'nonnative/http_service'
 require 'nonnative/http_server'
 require 'nonnative/http_proxy_server'
 require 'nonnative/grpc_server'
@@ -102,6 +103,7 @@ require 'nonnative/fault_injection_proxy'
 require 'nonnative/socket_pair'
 require 'nonnative/close_all_socket_pair'
 require 'nonnative/delay_socket_pair'
+require 'nonnative/timeout_socket_pair'
 require 'nonnative/invalid_data_socket_pair'
 require 'nonnative/socket_pair_factory'
 require 'nonnative/go_executable'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.13.0
+  version: 3.15.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -310,6 +310,7 @@ files:
 - lib/nonnative/http_probe.rb
 - lib/nonnative/http_proxy_server.rb
 - lib/nonnative/http_server.rb
+- lib/nonnative/http_service.rb
 - lib/nonnative/invalid_data_socket_pair.rb
 - lib/nonnative/no_proxy.rb
 - lib/nonnative/not_found_error.rb
@@ -330,6 +331,7 @@ files:
 - lib/nonnative/stop_error.rb
 - lib/nonnative/tcp_probe.rb
 - lib/nonnative/timeout.rb
+- lib/nonnative/timeout_socket_pair.rb
 - lib/nonnative/version.rb
 - nonnative.gemspec
 homepage: https://github.com/alexfalkowski/nonnative