nonnative 3.22.0 → 3.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fa10a31c57c45551a417924990d2d870e137d7561c1581577a6e965099472cc
-  data.tar.gz: dcd07b46e9ce599562c9c0f517ff7b6f46b529dfcf70c8f462cef3fd548704eb
+  metadata.gz: 59db521cea52e4a8c1d2aa8d76e79b50e7a9b76876b63ed8be4e46a665614a5d
+  data.tar.gz: 45f21fd21830aab99ce440d65d7cb80720449169684320f814a9e767881d8a1f
 SHA512:
-  metadata.gz: cb3cf0ffe148327fb056ad6a16851156b060373d69a06dc13b615197bb6a3aec5cb70faf412c4f31a68f8e92ce297646201fd3151c068758cc22017f5c1a745f
-  data.tar.gz: 8caa697ae5eb5c0b005da119b5ff518f68407c52cf876ca065a522147bc98d3064fff7899e54da1897408b9b963b87124ba1f62fd729913c073e3e1de8016dab
+  metadata.gz: 47d05d9b12dc2601470b87af8a880018a0be1808aee7f501f48a703db422b57db37d041b4f93fbb4ebb5afd4545bccf1ed3bf9b15b7a9d9909ca9134dc1d0111
+  data.tar.gz: 0d191245bdedd04c73096cfc4c3cd1871966c6aa9b09a1e5295c835a76798afea4633638f2d6f3bc1179d20f683484c6b033a8c655b45c047c9c468d18aa7fca

data/README.md

@@ -465,6 +465,30 @@ module Nonnative
 end
 ```
 
+To run multiple Rack services on one managed port, pass a non-empty mount map. Each key must start
+with `/`, and the mounted application receives the remaining `PATH_INFO`:
+
+```ruby
+module Nonnative
+  module Features
+    class HealthService < Nonnative::HTTPService
+      get '/' do
+        'ok'
+      end
+    end
+
+    class HTTPServer < Nonnative::HTTPServer
+      def initialize(service)
+        super({ '/api' => HelloService.new, '/health' => HealthService.new }, service)
+      end
+    end
+  end
+end
+```
+
+The existing single-service form remains supported. Nonnative converts a mount map to a
+`Rack::URLMap` and keeps one server lifecycle and port. An empty mount map raises `ArgumentError`.
+
 Set it up programmatically:
 
 ```ruby
@@ -517,6 +541,8 @@ end
 
 The system allows you to define an in-process HTTP forward proxy server for external systems, e.g. `api.github.com`. This is a server implementation, not a fault-injection service proxy.
 
+The proxy preserves the upstream status, body, and safe end-to-end response headers such as `Content-Type`, `ETag`, and application-specific metadata. It removes hop-by-hop, connection-nominated, proxy-authentication, and framing headers; `Set-Cookie`, `Location`, and `Content-Encoding` are not forwarded.
+
 Define your server:
 
 ```ruby
@@ -603,6 +629,30 @@ module Nonnative
 end
 ```
 
+To serve multiple gRPC services on one managed port, pass a non-empty array of handler classes or
+instances:
+
+```ruby
+module Nonnative
+  module Features
+    class HealthService < Grpc::Health::V1::Health::Service
+      def check(_request, _call)
+        Grpc::Health::V1::HealthCheckResponse.new(status: :SERVING)
+      end
+    end
+
+    class GRPCServer < Nonnative::GRPCServer
+      def initialize(service)
+        super([Greeter.new, HealthService.new], service)
+      end
+    end
+  end
+end
+```
+
+The existing single-handler form remains supported. Nonnative registers each handler before the
+server starts, so application and standard health handlers can share one lifecycle and endpoint.
+
 Set it up programmatically:
 
 ```ruby

data/lib/nonnative/grpc_server.rb

@@ -12,13 +12,18 @@ module Nonnative
   #
   # @see Nonnative::Server
   class GRPCServer < Nonnative::Server
-    # Creates a gRPC server and registers the provided service handler.
+    # Creates a gRPC server and registers the provided service handler(s).
     #
-    # @param svc [Object] a gRPC service implementation (typically a `...::Service` subclass instance)
+    # @param svc [Object, Array<Object>] a gRPC service implementation or a non-empty array of
+    #   implementations (typically `...::Service` subclasses or instances)
     # @param service [Nonnative::ConfigurationServer] server configuration
+    # @raise [ArgumentError] if `svc` is an empty array
     def initialize(svc, service)
       @server = GRPC::RpcServer.new
-      server.handle(svc)
+      handlers = svc.is_a?(Array) ? svc : [svc]
+      raise ArgumentError, 'gRPC server requires at least one service handler' if handlers.empty?
+
+      handlers.each { |handler| server.handle(handler) }
 
       # Unfortunately gRPC has only one logger so the first server wins.
       GRPC.define_singleton_method(:logger) do

data/lib/nonnative/http_client.rb

@@ -80,6 +80,18 @@ module Nonnative
       end
     end
 
+    # Performs a PATCH request.
+    #
+    # @param pathname [String] path relative to `host`
+    # @param payload [Object] request payload
+    # @param opts [Hash] RestClient request options
+    # @return [RestClient::Response, String] response for non-2xx errors, otherwise the RestClient result
+    def patch(pathname, payload, opts = {})
+      with_exception do
+        resource(pathname, opts).patch(payload)
+      end
+    end
+
     # Creates a RestClient resource for a relative path.
     #
     # @param pathname [String] path relative to `host`

data/lib/nonnative/http_proxy_server.rb

@@ -3,7 +3,8 @@
 # Sinatra-based HTTP forward proxy server used as an in-process Nonnative server.
 #
 # The proxy receives inbound HTTP requests and forwards them to an upstream host over HTTPS, returning
-# the upstream response status and body.
+# the upstream response status, body, and safe end-to-end response headers. Hop-by-hop,
+# connection-nominated, proxy-authentication, framing, and deferred response headers are not forwarded.
 #
 # This file defines two classes:
 #
@@ -23,7 +24,25 @@ module Nonnative
   #
   # Supported HTTP verbs: GET, POST, PUT, PATCH, DELETE.
   class HTTPProxy < Nonnative::HTTPService
-    NON_FORWARDABLE_HEADERS = %w[
+    NON_FORWARDABLE_RESPONSE_HEADERS = %w[
+      connection
+      content-encoding
+      content-length
+      keep-alive
+      location
+      proxy-authenticate
+      proxy-authorization
+      proxy-authentication-info
+      proxy-connection
+      set-cookie
+      status
+      te
+      trailer
+      transfer-encoding
+      upgrade
+    ].freeze
+
+    NON_FORWARDABLE_REQUEST_HEADERS = %w[
       Host
       Accept-Encoding
       Version
@@ -37,14 +56,14 @@ module Nonnative
     #
     # @param request [Sinatra::Request] the incoming request
     # @return [Hash{String=>String}] headers to forward to the upstream
-    def retrieve_headers(request)
+    def forward_request_headers(request)
       headers = request.env.each_with_object({}) do |(header, value), result|
-        next unless forward_header?(header)
+        next unless forward_request_header?(header)
 
-        result[normalized_header_name(header)] = value
+        result[normalized_request_header_name(header)] = value
       end
 
-      headers.except(*NON_FORWARDABLE_HEADERS)
+      headers.except(*NON_FORWARDABLE_REQUEST_HEADERS)
     end
 
     # Builds the upstream URL for the given request.
@@ -86,11 +105,43 @@ module Nonnative
 
     private
 
-    def forward_header?(header)
+    def forward_response_headers(response)
+      raw_headers = response.raw_headers
+      connection_headers = response_connection_headers(raw_headers)
+
+      raw_headers.each_with_object({}) do |(header, value), result|
+        normalized_header = normalized_response_header_name(header)
+        next unless forward_response_header?(normalized_header, connection_headers)
+
+        result[normalized_header] = Array(value).join(', ')
+      end
+    end
+
+    def response_connection_headers(raw_headers)
+      connection_headers = raw_headers.each_with_object([]) do |(header, values), result|
+        next unless normalized_response_header_name(header) == 'connection'
+
+        Array(values).each { |value| result.concat(value.to_s.split(',')) }
+      end
+
+      connection_headers.map { |header| normalized_response_header_name(header) }
+    end
+
+    def forward_response_header?(header, connection_headers)
+      !NON_FORWARDABLE_RESPONSE_HEADERS.include?(header) &&
+        !connection_headers.include?(header) &&
+        !header.start_with?('rack.')
+    end
+
+    def normalized_response_header_name(header)
+      header.to_s.strip.downcase
+    end
+
+    def forward_request_header?(header)
       header.start_with?('HTTP_') || %w[CONTENT_TYPE CONTENT_LENGTH].include?(header)
     end
 
-    def normalized_header_name(header)
+    def normalized_request_header_name(header)
       header.delete_prefix('HTTP_').split('_').map(&:capitalize).join('-')
     end
 
@@ -99,10 +150,11 @@ module Nonnative
         res = api_response(
           method: verb.to_sym,
           url: build_url(request, settings),
-          headers: retrieve_headers(request),
+          headers: forward_request_headers(request),
           payload: retrieve_payload(request, verb)
         )
 
+        headers(forward_response_headers(res))
         status res.code
         res.body
       end

data/lib/nonnative/http_server.rb

@@ -36,9 +36,16 @@ module Nonnative
   class HTTPServer < Nonnative::Server
     # Creates a Puma server for the given HTTP service and runner configuration.
     #
-    # @param http_service [#call] an HTTP service instance
+    # @param http_service [#call, Hash<String, #call>] an HTTP service instance or mount map
     # @param service [Nonnative::ConfigurationServer] server configuration
+    # @raise [ArgumentError] if `http_service` is an empty mount map
     def initialize(http_service, service)
+      if http_service.is_a?(Hash)
+        raise ArgumentError, 'HTTP server requires at least one service mount' if http_service.empty?
+
+        http_service = Rack::URLMap.new(http_service)
+      end
+
       # Keep the log IO so the server lifecycle can release Puma's file handle on stop.
       @log = File.open(service.log, 'a')
       options = {

data/lib/nonnative/pool.rb

@@ -23,17 +23,14 @@ module Nonnative
       @processes = nil
     end
 
-    # Starts all configured runners and yields results for each process/server.
+    # Starts all configured runners and collects lifecycle and readiness errors.
     #
     # Services are started first (proxy-only) and checked for opt-in readiness, then servers and processes are
-    # started and checked for readiness.
+    # started and checked for readiness. Each readiness failure is described with the runner and, for a process
+    # that exited early, its termination detail.
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam values [Object] runner-specific return value from `start` (e.g. `[pid, running]` for processes)
-    # @yieldparam result [Boolean] result of the port readiness check (`true` if ready in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and readiness-check errors collected while starting
-    def start(&)
+    def start
       errors = []
 
       errors.concat(service_lifecycle(services, :start, :start))
@@ -41,24 +38,20 @@ module Nonnative
       errors.concat(service_readiness_errors)
       return errors if service_readiness_errors.any?
 
-      [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start, &)) }
+      [servers, processes].each { |runners| errors.concat(run_lifecycle_checks(runners, :start, :open?, :start)) }
 
       errors
     end
 
-    # Stops all configured runners and yields results for each process/server.
+    # Stops all configured runners and collects lifecycle and shutdown errors.
     #
     # Processes and servers are stopped first and checked for shutdown, then services are stopped (proxy-only).
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam id [Object] runner-specific identifier returned by `stop` (e.g. pid or object_id)
-    # @yieldparam result [Boolean] result of the port shutdown check (`true` if closed in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and shutdown-check errors collected while stopping
-    def stop(&)
+    def stop
       errors = []
 
-      [processes, servers].each { |runners| errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop, &)) }
+      [processes, servers].each { |runners| errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop)) }
       errors.concat(service_lifecycle(services, :stop, :stop))
 
       errors
@@ -69,16 +62,12 @@ module Nonnative
     # This is used to rollback partial startup after a failed {#start} without constructing new runner
     # wrappers as a side effect.
     #
-    # @yieldparam name [String, nil] runner name
-    # @yieldparam id [Object] runner-specific identifier returned by `stop`
-    # @yieldparam result [Boolean] result of the port shutdown check (`true` if closed in time)
-    # @yieldparam port [Nonnative::Ports] checked port group
     # @return [Array<String>] lifecycle and shutdown-check errors collected while rolling back
-    def rollback(&)
+    def rollback
       errors = []
 
       [existing_processes, existing_servers].each do |runners|
-        errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :stop, &))
+        errors.concat(run_lifecycle_checks(runners, :stop, :closed?, :rollback))
       end
       errors.concat(service_lifecycle(existing_services, :stop, :stop))
 
@@ -196,7 +185,8 @@ module Nonnative
       end
     end
 
-    def run_lifecycle_checks(runners, lifecycle_method, port_method, action, &)
+    def run_lifecycle_checks(runners, lifecycle_method, port_method, phase)
+      action = phase == :start ? :start : :stop
       checks = []
       errors = []
 
@@ -207,7 +197,7 @@ module Nonnative
         errors << lifecycle_error(action, runner, e)
       end
 
-      errors.concat(yield_results(checks, action, &))
+      errors.concat(lifecycle_results(checks, phase, action))
     end
 
     def check_port(port, port_method)
@@ -216,17 +206,50 @@ module Nonnative
       { error: e }
     end
 
-    def yield_results(checks, action, &)
-      checks.each_with_object([]) do |(type, values, port, thread), errors|
+    def lifecycle_results(checks, phase, action)
+      checks.each_with_object([]) do |(runner, values, port, thread), errors|
         result = thread.value
         if result[:error]
-          errors << port_error(action, type, result[:error])
-        elsif block_given?
-          yield type.name, values, result[:result], port
+          errors << port_error(action, runner, result[:error])
+        else
+          errors.concat(readiness_errors(phase, runner, values, result[:result], port))
         end
       end
     end
 
+    def readiness_errors(phase, runner, values, ready, port)
+      case phase
+      when :start then start_errors(runner, values, ready, port)
+      when :stop then stop_errors(runner, values, ready, port)
+      else rollback_errors(runner, values, ready, port)
+      end
+    end
+
+    def start_errors(runner, values, ready, port)
+      id, started = values
+      return [] if started && ready
+
+      message = "Started #{runner.name} with id #{id}, though did not respond in time for #{port.description}"
+      detail = runner.termination
+      [detail ? "#{message}; #{detail}" : message]
+    end
+
+    def stop_errors(runner, values, ready, port)
+      id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
+      errors = []
+      errors << "Stopped #{runner.name} with id #{id}, though did not respond in time for #{port.description}" unless ready
+      errors << "Stopped #{runner.name} with id #{id}, though the process did not exit in time" unless stopped
+      errors
+    end
+
+    def rollback_errors(runner, values, ready, port)
+      id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
+      errors = []
+      errors << "Rollback failed for #{runner.name} with id #{id}, because it did not stop in time for #{port.description}" unless ready
+      errors << "Rollback failed for #{runner.name} with id #{id}, because the process did not exit in time" unless stopped
+      errors
+    end
+
     def lifecycle_error(action, type, error)
       "#{action.to_s.capitalize} failed for #{runner_name(type)}: #{error.class} - #{error.message}"
     end

data/lib/nonnative/process.rb

@@ -37,7 +37,10 @@ module Nonnative
         wait_start
       end
 
-      [pid, ::Process.waitpid2(pid, ::Process::WNOHANG).nil?]
+      # Retain the reaped status for this lifecycle so startup diagnostics can report it.
+      status = ::Process.waitpid2(pid, ::Process::WNOHANG)
+      @status = status&.last
+      [pid, status.nil?]
     end
 
     # Stops the process if it is running.
@@ -62,6 +65,20 @@ module Nonnative
       @memory = nil
     end
 
+    # Describes how the process terminated when it exited before becoming ready.
+    #
+    # Returns `nil` while the process is still running, so callers can distinguish an early exit
+    # from a live process that merely missed its readiness window. The check is non-blocking and
+    # reuses the status captured during {#start} when available.
+    #
+    # @return [String, nil] termination detail (exit status or terminating signal), or `nil`
+    def termination
+      status = captured_status
+      return if status.nil?
+
+      terminated_description(status)
+    end
+
     protected
 
     def wait_stop
@@ -74,6 +91,28 @@ module Nonnative
 
     attr_reader :pid, :timeout
 
+    def captured_status
+      return @status unless @status.nil?
+      return if pid.nil?
+
+      # A process that exited during the readiness window has not been reaped yet.
+      @status = ::Process.waitpid2(pid, ::Process::WNOHANG)&.last
+    rescue Errno::ECHILD, Errno::ESRCH
+      nil
+    end
+
+    def terminated_description(status)
+      return "process exited before readiness with exit status #{status.exitstatus}" if status.exited?
+      return "process exited before readiness after being killed by signal #{signal_description(status.termsig)}" if status.signaled?
+
+      "process exited before readiness (#{status})"
+    end
+
+    def signal_description(signal)
+      name = Signal.signame(signal)
+      name ? "SIG#{name} (#{signal})" : signal.to_s
+    end
+
     def process_kill
       signal = Signal.list[service.signal || 'INT'] || Signal.list['INT']
       ::Process.kill(signal, pid)

data/lib/nonnative/runner.rb

@@ -26,6 +26,15 @@ module Nonnative
       service.name
     end
 
+    # Describes how the runner terminated before becoming ready, for lifecycle diagnostics.
+    #
+    # Base runners report nothing; {Nonnative::Process} overrides this to describe an early exit.
+    #
+    # @return [String, nil]
+    def termination
+      nil
+    end
+
     protected
 
     # Returns the underlying configuration object.

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -271,10 +271,7 @@ module Nonnative
     def start
       @pool ||= Nonnative::Pool.new(configuration)
       errors = []
-      errors.concat(@pool.start do |name, values, result, ports|
-        id, started = values
-        errors << "Started #{name} with id #{id}, though did not respond in time for #{ports.description}" if !started || !result
-      end)
+      errors.concat(@pool.start)
       nil
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:start, e)
@@ -294,11 +291,7 @@ module Nonnative
       errors = []
       return if @pool.nil?
 
-      errors.concat(@pool.stop do |name, values, result, ports|
-        id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Stopped #{name} with id #{id}, though did not respond in time for #{ports.description}" unless result
-        errors << "Stopped #{name} with id #{id}, though the process did not exit in time" unless stopped
-      end)
+      errors.concat(@pool.stop)
       nil
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:stop, e)
@@ -363,11 +356,7 @@ module Nonnative
       errors = []
       return errors if @pool.nil?
 
-      errors.concat(@pool.rollback do |name, values, result, ports|
-        id, stopped = Array(values).then { |v| [v.first, v.fetch(1, true)] }
-        errors << "Rollback failed for #{name} with id #{id}, because it did not stop in time for #{ports.description}" unless result
-        errors << "Rollback failed for #{name} with id #{id}, because the process did not exit in time" unless stopped
-      end)
+      errors.concat(@pool.rollback)
     rescue StandardError => e
       errors << unexpected_lifecycle_error(:rollback, e)
     ensure

metadata

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