nonnative 2.19.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e83e6a409c77b42f73d52473d360f136255a62f5227bb08b770d129082ccd69b
-  data.tar.gz: f2cb0c6bf4b4bcfa7a9ab95851735b987b16ab180aa4ff9278e334e473863aca
+  metadata.gz: 3f867021d8754e7ef700f5b57991335299ea696410cc268f3ea6b18d4b3ae4d7
+  data.tar.gz: bea097cace138eab114d90b7b43404b0efd50479354c5448f247bafc78d93468
 SHA512:
-  metadata.gz: e282a3e79b1319d47154ffac90b305ef5344eb78d9f960e30b3d6a851303f1b736b2f0456e24816a8459db9b5368f4e90d10777fd385e26da3748ac7a894f29f
-  data.tar.gz: 10b38f3e4b0d3d279add988ae32af3c60990715b1fa0c96e94efa6adad29b6f86868b243d2d000e0005815c1c80c4c28a79889a105ef0cf265555b80e4b60b39
+  metadata.gz: 134bd430de52ad60233ccab7e71e08b593505cf69bcd4c9ee3dee1bc5c001c1416a628f0377c53dbecc1b9d3809ba0ad047c872f266b6ef2dd967ec22aaddeb6
+  data.tar.gz: a9461d8db4fba48d27ebdc9ffcb67916d4feb996769acf450cc0ab595633df94e00279bc415f17e0600e8d2edd9f8e114b2fa958f582b3e760d14129361c144b

data/.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 jobs:
   build:
     docker:
-      - image: alexfalkowski/ruby:3.8
+      - image: alexfalkowski/ruby:3.9
     working_directory: ~/nonnative
     steps:
       - checkout:
@@ -58,7 +58,7 @@ jobs:
     resource_class: arm.large
   wait-all:
     docker:
-      - image: alexfalkowski/ruby:3.8
+      - image: alexfalkowski/ruby:3.9
     steps:
       - run: echo "all applicable jobs finished"
     resource_class: arm.large

data/AGENTS.md

@@ -29,7 +29,8 @@ of dependencies.
 
 Public entry point: `lib/nonnative.rb`.
 
-Main API: `configure`, `start`, `stop`, `clear`, `reset`, `pool`.
+Main API: `configure`, `start`, `stop`, `clear`, `reset`, `pool`,
+`go_argv`, `go_command`.
 
 Configuration is `Nonnative::Configuration`, built with
 `config.process`, `config.server`, `config.service`, or
@@ -81,7 +82,8 @@ Config rules:
 
 - YAML config is loaded as data only via `Nonnative::ConfigurationFile`; ERB is not evaluated and arbitrary Ruby object tags are rejected
 - Runner `host` and nested `proxy.host` default to `127.0.0.1`; use explicit `0.0.0.0` only when external access is intended
-- Process `command` can be a legacy shell string or an argv array; prefer argv arrays for new config, and `go:` config builds argv internally
+- Process `command` can be a legacy shell string or an argv array; prefer argv arrays for new config, and `go:` config builds argv internally with `Nonnative.go_argv`
+- Use `Nonnative.go_argv` for no-shell Go executable argv entries and `Nonnative.go_command` only when a caller needs Ruby shell-style command string spawning
 - YAML services belong under `services:`, not `processes:`
 - There is no top-level `config.wait`; `wait` is per runner
 - Programmatic service config uses `config.service do |s| ... end`, so use `s.host` / `s.port`
@@ -108,6 +110,7 @@ Limitations:
 - Lifecycle: `lib/nonnative.rb`, `lib/nonnative/pool.rb`
 - Readiness/timeouts: `lib/nonnative/port.rb`, `lib/nonnative/timeout.rb`
 - Process lifecycle: `lib/nonnative/process.rb`
+- Go executable command/argv building: `lib/nonnative/go_executable.rb`
 - Proxies: `lib/nonnative/fault_injection_proxy.rb`, `lib/nonnative/socket_pair_factory.rb`
 - Cucumber: `lib/nonnative/cucumber.rb`, `lib/nonnative/startup.rb`, `features/support/env.rb`
 - Config loading: `lib/nonnative/configuration.rb`, `lib/nonnative/configuration_file.rb`, `lib/nonnative/configuration_runner.rb`, `lib/nonnative/configuration_proxy.rb`

data/Gemfile.lock

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

data/README.md

@@ -37,7 +37,7 @@ gem install nonnative
 
 ## Usage
 
-Nonnative is configured via {#Nonnative.configure} (programmatic) or `config.load_file(...)` (YAML).
+Nonnative is configured via `Nonnative.configure` (programmatic) or `config.load_file(...)` (YAML).
 YAML configuration is loaded as data only: ERB is not evaluated and arbitrary Ruby objects are not
 deserialized.
 
@@ -50,11 +50,14 @@ High-level configuration fields:
 - `servers`: in-process Ruby servers started in threads.
 - `services`: external dependencies (proxy-only; no process/thread started by Nonnative).
 
-Runner fields (process/server/service):
+Common runner fields:
+- `name`: runner name used for lookup.
+- `host`/`port`: client-facing address. `host` defaults to `127.0.0.1`. For processes and servers, this address is also used for readiness/shutdown port checks. When a `fault_injection` proxy is enabled, this is the endpoint your tests/clients should hit.
+
+Process/server fields:
 - `timeout`: max time (seconds) for readiness/shutdown port checks.
 - `wait`: small sleep (seconds) between lifecycle steps.
-- `host`/`port`: client-facing address used for readiness/shutdown port checks. `host` defaults to `127.0.0.1`. 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).
+- `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. Nested `proxy.host` also defaults to `127.0.0.1`. In-process server implementations typically bind there via `proxy.host` / `proxy.port`.
 
@@ -95,7 +98,7 @@ A process is some sort of command that you would run locally.
 Commands can be strings or argv arrays. String commands preserve legacy shell semantics, while argv arrays
 avoid shell interpretation and are preferred for new configuration.
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -121,7 +124,7 @@ Nonnative.configure do |config|
 
   config.process do |p|
     p.name = 'start_2'
-    p.command = -> { 'features/support/bin/start 12_322' }
+    p.command = -> { ['features/support/bin/start', '12_322'] }
     p.timeout = 0.5
     p.wait = 0.1
     p.port = 12_322
@@ -130,7 +133,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -152,7 +155,9 @@ processes:
       TEST: true
   -
     name: start_2
-    command: features/support/bin/start 12_322
+    command:
+      - features/support/bin/start
+      - "12_322"
     timeout: 5
     wait: 1
     port: 12322
@@ -211,7 +216,7 @@ module Nonnative
 end
 ```
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -224,7 +229,7 @@ Nonnative.configure do |config|
 
   config.server do |s|
     s.name = 'server_1'
-    s.klass = Nonnative::EchoServer
+    s.klass = Nonnative::TCPServer
     s.timeout = 1
     s.port = 12_323
     s.log = 'server_1.log'
@@ -232,7 +237,7 @@ Nonnative.configure do |config|
 
   config.server do |s|
     s.name = 'server_2'
-    s.klass = Nonnative::EchoServer
+    s.klass = Nonnative::TCPServer
     s.timeout = 1
     s.port = 12_324
     s.log = 'server_2.log'
@@ -240,7 +245,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -250,13 +255,13 @@ log: nonnative.log
 servers:
   -
     name: server_1
-    class: Nonnative::EchoServer
+    class: Nonnative::TCPServer
     timeout: 1
     port: 12323
     log: server_1.log
   -
     name: server_2
-    class: Nonnative::EchoServer
+    class: Nonnative::TCPServer
     timeout: 1
     port: 12324
     log: server_2.log
@@ -294,7 +299,7 @@ module Nonnative
 end
 ```
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -315,7 +320,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -359,7 +364,7 @@ module Nonnative
 end
 ```
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -380,7 +385,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -428,7 +433,7 @@ module Nonnative
 end
 ```
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 require 'nonnative'
@@ -449,7 +454,7 @@ Nonnative.configure do |config|
 end
 ```
 
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -711,7 +716,7 @@ Clients connect to the runner `host`/`port`, while the proxy forwards traffic to
 
 ###### Fault Injection Processes
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 name = 'name of process in configuration'
@@ -730,7 +735,7 @@ Then I should reset the proxy for process 'process_1'
 
 ###### Fault Injection Servers
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 name = 'name of server in configuration'
@@ -749,7 +754,7 @@ Then I should reset the proxy for server 'server_1'
 
 ###### Fault Injection Services
 
-Setup it up programmatically:
+Set it up programmatically:
 
 ```ruby
 name = 'name of service in configuration'
@@ -768,11 +773,28 @@ Then I should reset the proxy for service 'service_1'
 
 ### Go
 
-As we love using go as a language for services we have added support to start binaries with defined parameters. This expects that you build your services in the format of `command sub_command --params`. YAML `go:` configuration is executed as argv entries, without shell interpretation.
+As we love using Go as a language for services we have added support to start binaries with defined parameters.
+
+Programmatic Go binaries can be configured as normal argv process commands:
+
+```ruby
+Nonnative.configure do |config|
+  config.process do |p|
+    p.name = 'go'
+    p.command = -> { Nonnative.go_argv(%w[cover], 'reports', 'your_binary', 'sub_command', '-i file:.config/server.yml') }
+    p.port = 12_345
+  end
+end
+```
+
+Use `Nonnative.go_argv(...)` when a process should execute without shell interpretation, and `Nonnative.go_command(...)` when a caller needs a command string for Ruby's shell-style `spawn` behavior.
+
+YAML `go:` configuration is for Go test binaries compiled with `go test -c`. It builds argv entries in this order: executable, optional `-test.*` profiling/trace/coverage flags, command, then parameters. Parameter strings are parsed into argv words with shell-style quoting, but the argv entries are executed without shell interpretation.
 
 To get this to work you will need to create a `main_test.go` file with these contents:
 
 ```go
+//go:build features
 // +build features
 
 package main
@@ -780,7 +802,7 @@ package main
 import "testing"
 
 func TestFeatures(t *testing.T) {
- main()
+    main()
 }
 ```
 
@@ -790,19 +812,7 @@ Then to compile this binary you will need to do the following:
 go test -mod vendor -c -tags features -covermode=count -o your_binary -coverpkg=./... github.com/your_location
 ```
 
-Setup it up programmatically as an argv process command:
-
-```ruby
-Nonnative.configure do |config|
-  config.process do |p|
-    p.name = 'go'
-    p.command = -> { ['your_binary', 'sub_command', '--config', 'config.yaml'] }
-    p.port = 12_345
-  end
-end
-```
-
-Setup it up through configuration:
+Set it up through configuration:
 
 ```yaml
 version: "1.0"
@@ -818,7 +828,7 @@ processes:
       executable: your_binary
       command: sub_command
       parameters:
-        - --config config.yaml
+        - "-i file:.config/server.yml"
     timeout: 5
     port: 8000
     log: go.log

data/lib/nonnative/configuration.rb

@@ -141,7 +141,7 @@ module Nonnative
         params = go.parameters || []
         tools = go.tools || []
 
-        -> { Nonnative.go_executable_args(tools, go.output, go.executable, go.command, *params) }
+        -> { Nonnative.go_argv(tools, go.output, go.executable, go.command, *params) }
       else
         -> { process.command }
       end

data/lib/nonnative/{go_command.rb → go_executable.rb}

@@ -19,13 +19,16 @@ module Nonnative
   #
   # If `tools` is `nil` or empty, all tools (`prof`, `trace`, `cover`) are enabled.
   #
+  # Parameter strings are parsed into argv words using shell-style quoting.
+  #
   # @example
-  #   cmd = Nonnative::GoCommand.new(%w[prof cover], './svc.test', 'reports')
-  #   cmd.executable_args('serve', '--config', 'config.yaml')
+  #   executable = Nonnative::GoExecutable.new(%w[prof cover], './svc.test', 'reports')
+  #   executable.argv('serve', '--config', 'config.yaml')
   #   # => ["./svc.test", "-test.cpuprofile=...", "-test.coverprofile=...", "serve", "--config", "config.yaml"]
   #
-  # @see Nonnative.go_executable_args
-  class GoCommand
+  # @see Nonnative.go_command
+  # @see Nonnative.go_argv
+  class GoExecutable
     # @param tools [Array<String>, nil] tool names to enable (see class docs)
     # @param exec [String] path to the compiled Go test binary
     # @param output [String] output directory for generated files
@@ -40,16 +43,29 @@ module Nonnative
     # A short random suffix is appended to output filenames to reduce collisions across runs.
     #
     # @param cmd [String] command/sub-command argument passed to the Go test binary
-    # @param params [Array<String>] additional parameters passed after `cmd`
+    # @param params [Array<String>] additional parameter strings passed after `cmd`
     # @return [Array<String>] argv entries to execute
-    def executable_args(cmd, *params)
-      [exec, *flags(cmd), cmd, *params.flatten.compact.map(&:to_s)]
+    def argv(cmd, *params)
+      [exec, *flags(cmd), cmd, *parameter_args(params)]
+    end
+
+    # Returns an executable command string including enabled `-test.*` flags.
+    #
+    # @param cmd [String] command/sub-command argument passed to the Go test binary
+    # @param params [Array<String>] additional parameter strings passed after `cmd`
+    # @return [String] the full command to execute
+    def command(cmd, *params)
+      Shellwords.join(argv(cmd, *params))
     end
 
     private
 
     attr_reader :tools, :exec, :output
 
+    def parameter_args(params)
+      params.flatten.compact.flat_map { |p| Shellwords.split(p.to_s) }
+    end
+
     def flags(cmd)
       suffix = SecureRandom.alphanumeric(4)
       m = File.basename(exec, File.extname(exec))

data/lib/nonnative/version.rb

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

data/lib/nonnative.rb

@@ -46,6 +46,7 @@ require 'timeout'
 require 'yaml'
 require 'open3'
 require 'securerandom'
+require 'shellwords'
 
 require 'grpc'
 require 'sinatra'
@@ -93,7 +94,7 @@ require 'nonnative/close_all_socket_pair'
 require 'nonnative/delay_socket_pair'
 require 'nonnative/invalid_data_socket_pair'
 require 'nonnative/socket_pair_factory'
-require 'nonnative/go_command'
+require 'nonnative/go_executable'
 require 'nonnative/cucumber'
 require 'nonnative/header'
 
@@ -153,18 +154,32 @@ module Nonnative
       File.readlines(path).select { |l| predicate.call(l) }
     end
 
+    # Builds a Go test executable command string with optional profiling/trace/coverage flags.
+    #
+    # Use this when passing a command string directly to `spawn`.
+    #
+    # @param tools [Array<String>] enabled tool names (e.g. `["prof", "trace", "cover"]`)
+    # @param output [String] directory where outputs should be written
+    # @param exec [String] the test binary (or wrapper) to execute
+    # @param cmd [String] the command argument passed to the test binary
+    # @param params [Array<String>] extra parameter strings for the command
+    # @return [String] executable command string
+    def go_command(tools, output, exec, cmd, *params)
+      Nonnative::GoExecutable.new(tools, exec, output).command(cmd, *params)
+    end
+
     # Builds a Go test executable argv array with optional profiling/trace/coverage flags.
     #
-    # This is used when process configuration specifies a `go` section.
+    # Use this when passing argv entries directly to `spawn`.
     #
     # @param tools [Array<String>] enabled tool names (e.g. `["prof", "trace", "cover"]`)
     # @param output [String] directory where outputs should be written
     # @param exec [String] the test binary (or wrapper) to execute
     # @param cmd [String] the command argument passed to the test binary
-    # @param params [Array<String>] extra parameters for the command
+    # @param params [Array<String>] extra parameter strings for the command
     # @return [Array<String>] executable argv entries
-    def go_executable_args(tools, output, exec, cmd, *params)
-      Nonnative::GoCommand.new(tools, exec, output).executable_args(cmd, *params)
+    def go_argv(tools, output, exec, cmd, *params)
+      Nonnative::GoExecutable.new(tools, exec, output).argv(cmd, *params)
     end
 
     # Returns an HTTP client for common health/readiness endpoints.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 2.19.0
+  version: 2.20.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -298,7 +298,7 @@ files:
 - lib/nonnative/delay_socket_pair.rb
 - lib/nonnative/error.rb
 - lib/nonnative/fault_injection_proxy.rb
-- lib/nonnative/go_command.rb
+- lib/nonnative/go_executable.rb
 - lib/nonnative/grpc_server.rb
 - lib/nonnative/header.rb
 - lib/nonnative/http_client.rb