Module: Nonnative

Defined in:
lib/nonnative.rb,
lib/nonnative/pool.rb,
lib/nonnative/port.rb,
lib/nonnative/error.rb,
lib/nonnative/ports.rb,
lib/nonnative/proxy.rb,
lib/nonnative/token.rb,
lib/nonnative/header.rb,
lib/nonnative/runner.rb,
lib/nonnative/server.rb,
lib/nonnative/process.rb,
lib/nonnative/service.rb,
lib/nonnative/timeout.rb,
lib/nonnative/version.rb,
lib/nonnative/cucumber.rb,
lib/nonnative/no_proxy.rb,
lib/nonnative/jwt_token.rb,
lib/nonnative/ssh_token.rb,
lib/nonnative/tcp_probe.rb,
lib/nonnative/grpc_probe.rb,
lib/nonnative/http_probe.rb,
lib/nonnative/stop_error.rb,
lib/nonnative/ed25519_key.rb,
lib/nonnative/grpc_health.rb,
lib/nonnative/grpc_server.rb,
lib/nonnative/http_client.rb,
lib/nonnative/http_server.rb,
lib/nonnative/socket_pair.rb,
lib/nonnative/start_error.rb,
lib/nonnative/http_service.rb,
lib/nonnative/paseto_token.rb,
lib/nonnative/configuration.rb,
lib/nonnative/go_executable.rb,
lib/nonnative/observability.rb,
lib/nonnative/proxy_factory.rb,
lib/nonnative/not_found_error.rb,
lib/nonnative/delay_socket_pair.rb,
lib/nonnative/http_proxy_server.rb,
lib/nonnative/configuration_file.rb,
lib/nonnative/configuration_proxy.rb,
lib/nonnative/socket_pair_factory.rb,
lib/nonnative/timeout_socket_pair.rb,
lib/nonnative/configuration_runner.rb,
lib/nonnative/configuration_server.rb,
lib/nonnative/bandwidth_socket_pair.rb,
lib/nonnative/close_all_socket_pair.rb,
lib/nonnative/configuration_process.rb,
lib/nonnative/configuration_service.rb,
lib/nonnative/fault_injection_proxy.rb,
lib/nonnative/limit_data_socket_pair.rb,
lib/nonnative/reset_peer_socket_pair.rb,
lib/nonnative/configuration_readiness.rb,
lib/nonnative/invalid_data_socket_pair.rb,
lib/nonnative/configuration_service_readiness.rb

Overview

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, 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:

Notes:

See Also:

Defined Under Namespace

Modules: Cucumber Classes: BandwidthSocketPair, CloseAllSocketPair, Configuration, ConfigurationFile, ConfigurationProcess, ConfigurationProxy, ConfigurationReadiness, ConfigurationRunner, ConfigurationServer, ConfigurationService, ConfigurationServiceReadiness, DelaySocketPair, Ed25519Key, Error, FaultInjectionProxy, GRPCHealth, GRPCProbe, GRPCServer, GoExecutable, HTTPClient, HTTPProbe, HTTPProxy, HTTPProxyServer, HTTPServer, HTTPService, Header, InvalidDataSocketPair, JwtToken, LimitDataSocketPair, NoProxy, NotFoundError, Observability, PasetoToken, Pool, Port, Ports, Process, Proxy, ProxyFactory, ResetPeerSocketPair, Runner, Server, Service, SocketPair, SocketPairFactory, SshToken, StartError, StopError, TCPProbe, Timeout, TimeoutSocketPair, Token

Constant Summary collapse

VERSION =

The current gem version.

Returns:

  • (String) 
'3.30.0'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.pool ⇒ Nonnative::Pool?

Returns or overrides the current runner pool (created on start).

Returns:



145
146
147
 
# File 'lib/nonnative.rb', line 145

def pool
  @pool
end

Class Method Details

.clear ⇒ void

This method returns an undefined value.

Clears memoized configuration, logger, observability client, and pool.

This does not stop processes, server threads, or proxies. To reconfigure in the same Ruby process, call stop, then clear, configure the next system, and call start.



343
344
345
346
347
348
 
# File 'lib/nonnative.rb', line 343

def clear
  clear_logger
  clear_observability
  clear_configuration
  clear_pool
end

.clear_configuration ⇒ void

This method returns an undefined value.

Clears the memoized configuration instance.



307
308
309
 
# File 'lib/nonnative.rb', line 307

def clear_configuration
  @configuration = nil
end

.clear_logger ⇒ void

This method returns an undefined value.

Closes and clears the memoized logger instance.



314
315
316
317
318
 
# File 'lib/nonnative.rb', line 314

def clear_logger
  @logger&.close
ensure
  @logger = nil
end

.clear_observability ⇒ void

This method returns an undefined value.

Clears the memoized observability client.



323
324
325
 
# File 'lib/nonnative.rb', line 323

def clear_observability
  @observability = nil
end

.clear_pool ⇒ void

This method returns an undefined value.

Clears the memoized pool instance.

This does not stop runners owned by the pool. Call stop before clearing a live pool.



332
333
334
 
# File 'lib/nonnative.rb', line 332

def clear_pool
  @pool = nil
end

.configuration ⇒ Nonnative::Configuration

Returns the current configuration (memoized).

Returns:



150
151
152
 
# File 'lib/nonnative.rb', line 150

def configuration
  @configuration ||= Nonnative::Configuration.new
end

.configure {|config| ... } ⇒ void

This method returns an undefined value.

Yields the configuration to a block for programmatic setup.

Examples:

Nonnative.configure do |config|
  config.name = 'my-service'
  # ...
end

Yield Parameters:



164
165
166
 
# File 'lib/nonnative.rb', line 164

def configure
  yield configuration
end

.go_argv(tools, output, exec, cmd, *params) ⇒ Array<String>

Builds a Go test executable argv array with optional profiling/trace/coverage flags.

Use this when passing argv entries directly to spawn.

Parameters:

  • tools (Array<String>) —

    enabled tool names (e.g. ["prof", "trace", "cover"])

  • output (String) —

    existing writable directory where outputs should be written

  • exec (String) —

    the test binary (or wrapper) to execute

  • cmd (String) —

    the command argument passed to the test binary

  • params (Array<String>) —

    extra parameter strings for the command

Returns:

  • (Array<String>) —

    executable argv entries



210
211
212
 
# File 'lib/nonnative.rb', line 210

def go_argv(tools, output, exec, cmd, *params)
  Nonnative::GoExecutable.new(tools, exec, output).argv(cmd, *params)
end

.go_command(tools, output, exec, cmd, *params) ⇒ String

Builds a Go test executable command string with optional profiling/trace/coverage flags.

Use this when passing a command string directly to spawn.

Parameters:

  • tools (Array<String>) —

    enabled tool names (e.g. ["prof", "trace", "cover"])

  • output (String) —

    existing writable directory where outputs should be written

  • exec (String) —

    the test binary (or wrapper) to execute

  • cmd (String) —

    the command argument passed to the test binary

  • params (Array<String>) —

    extra parameter strings for the command

Returns:

  • (String) —

    executable command string



196
197
198
 
# File 'lib/nonnative.rb', line 196

def go_command(tools, output, exec, cmd, *params)
  Nonnative::GoExecutable.new(tools, exec, output).command(cmd, *params)
end

.grpc_health(host:, port:, service:, timeout: 1) ⇒ Nonnative::GRPCHealth

Returns a client helper for the standard gRPC health checking protocol.

Parameters:

  • host (String) —

    gRPC server host

  • port (Integer) —

    gRPC server port

  • service (String, nil) —

    gRPC health service name, or empty/nil for overall server health

  • timeout (Numeric) (defaults to: 1) —

    default call timeout in seconds

Returns:



243
 
# File 'lib/nonnative.rb', line 243

def grpc_health(host:, port:, service:, timeout: 1) = Nonnative::GRPCHealth.new(host: host, port: port, service: service, timeout: timeout)

.log_lines(path, predicate) ⇒ Array<String>

Reads a file and returns only lines matching the given predicate.

Parameters:

  • path (String) —

    file path to read

  • predicate (#call) —

    callable that receives a line and returns truthy/falsey

Returns:

  • (Array<String>) —

    matching lines



182
183
184
 
# File 'lib/nonnative.rb', line 182

def log_lines(path, predicate)
  File.readlines(path).select { |l| predicate.call(l) }
end

.logger ⇒ Logger

Returns the gem logger (memoized).

The logger writes to the path configured at Nonnative::Configuration#log.

Returns:

  • (Logger) 


173
174
175
 
# File 'lib/nonnative.rb', line 173

def logger
  @logger ||= Logger.new(configuration.log)
end

.observability ⇒ Nonnative::Observability

Returns an HTTP client for common health/readiness endpoints.

Returns:



234
 
# File 'lib/nonnative.rb', line 234

def observability = (@observability ||= Nonnative::Observability.new(configuration.url))

.proxies ⇒ Hash{String=>Class}

Returns the configured proxy kinds mapped to proxy classes.

Consumers can extend this map to add custom proxy implementations.

Returns:

  • (Hash{String=>Class}) 


250
251
252
 
# File 'lib/nonnative.rb', line 250

def proxies
  @proxies ||= { 'fault_injection' => Nonnative::FaultInjectionProxy }
end

.proxy(kind) ⇒ Class

Resolves a proxy implementation for a configured kind.

nil and "none" resolve to NoProxy; any other kind must be registered in proxies.

Parameters:

  • kind (String) —

    proxy kind name (for example "fault_injection")

Returns:

  • (Class) —

    a subclass of Proxy

Raises:

  • (ArgumentError) —

    if the kind is not "none" and has not been registered



262
263
264
 
# File 'lib/nonnative.rb', line 262

def proxy(kind)
  kind.nil? || kind == 'none' ? NoProxy : proxies.fetch(kind) { raise ArgumentError, "Unsupported proxy kind '#{kind}'" }
end

.reset ⇒ void

This method returns an undefined value.

Resets proxies for all currently started runners.

Raises:

  • (NoMethodError) —

    if called before start (because pool is nil)



354
355
356
 
# File 'lib/nonnative.rb', line 354

def reset
  Nonnative.pool.reset
end

.start ⇒ void

This method returns an undefined value.

Starts all configured services, servers, and processes, and waits for readiness.

Readiness is determined by port checks, plus optional process HTTP/gRPC readiness and optional service TCP readiness.

Raises:



273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/nonnative.rb', line 273

def start
  @pool ||= Nonnative::Pool.new(configuration)
  errors = []
  errors.concat(@pool.start)
  nil
rescue StandardError => e
  errors << unexpected_lifecycle_error(:start, e)
ensure
  if errors.any?
    errors.concat(rollback_start)

    raise Nonnative::StartError, errors.join("\n")
  end
end

.stop ⇒ void

This method returns an undefined value.

Stops all configured processes and servers, then services, and waits for shutdown.

Raises:



292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/nonnative.rb', line 292

def stop
  errors = []
  return if @pool.nil?

  errors.concat(@pool.stop)
  nil
rescue StandardError => e
  errors << unexpected_lifecycle_error(:stop, e)
ensure
  raise Nonnative::StopError, errors.join("\n") unless errors.empty?
end

.token(kind:, issuer:, key:, private_key:, expiration:) ⇒ Nonnative::Token

Builds a token generator for authenticating against a service under test.

The signing parameters are passed in directly; this is not coupled to any service's configuration format. The generated token string is ready for Nonnative::Header.auth_bearer.

Examples:

token = Nonnative.token(kind: 'jwt', issuer: 'iss', key: 'key-1', private_key: 'config/ed25519.pem', expiration: 3600)
Nonnative::Header.auth_bearer(token.generate(aud: 'GET /v1/things', sub: 'user-1'))

Parameters:

  • kind (String) —

    token kind, one of "jwt", "paseto", or "ssh"

  • issuer (String) —

    the iss claim (unused by the ssh kind)

  • key (String) —

    the key id (JWT kid header, PASETO kid footer, or SSH kid claim)

  • private_key (String) —

    path to the Ed25519 private key file (PKCS#8 PEM for jwt/paseto, OpenSSH format for ssh)

  • expiration (Integer) —

    token lifetime in seconds (drives exp)

Returns:



229
 
# File 'lib/nonnative.rb', line 229

def token(kind:, issuer:, key:, private_key:, expiration:) = Nonnative::Token.new(kind:, issuer:, key:, private_key:, expiration:)