mockserver-client 8.0.0 → 9.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b32e53f8e5117c75dddf6e9b86e379892b47066fe7dbe3919da8d97232600fce
-  data.tar.gz: 64aa0e6608d0be522249a761e0009fce60058ebe2f6c67dbd9617bd3fffaa3fe
+  metadata.gz: 3b414bb7cc138b2e2a46b674e67743d1145bc004bc7a62be5d25e75fab95409f
+  data.tar.gz: 8d11ed79c2d777ab576c4181e9cb2c6b2730c352afc532d5df4070e9accddaf6
 SHA512:
-  metadata.gz: c87f1c996f7ec3f49502a5465c8990a076bef51262408570706cb520359f6446e9adbfafd0a9b6c1bace45b3164caaf3340fb1f4d848d877047c0f41d361a159
-  data.tar.gz: 741e8bd63ccb4d63edcfd7be2467d6b619fa5be8924f295d2f886da3af0017e201d8891adc8076c6af65c42dbbbf4202d259573e6c55f9a58f0a131993f4294d
+  metadata.gz: f0b346b83cbc825456b2dc85b6b1462e1fa3610f779f9037e77ba2f40f4a780e9c64a793d80df95dbceb0b7d67b57805cce281d75fa8ba36114edb7e35851892
+  data.tar.gz: 5bde30af6fe4e94208ac4a275e52309d77e1d78a94d74ce152c993a656e8db00d98adc88f9556c21f2c1d3939b180e2f7ac9588195a4462a9a99ab035883eaac

data/README.md

@@ -85,7 +85,7 @@ client.close
 
 ## Models
 
-All 26 domain model classes are available under the `MockServer` module:
+All 27 domain model classes are available under the `MockServer` module:
 
 - `Delay`, `Times`, `TimeToLive`
 - `KeyToMultiValue`, `Body`, `SocketAddress`
@@ -94,12 +94,61 @@ All 26 domain model classes are available under the `MockServer` module:
 - `HttpOverrideForwardedRequest`, `HttpRequestAndHttpResponse`
 - `ConnectionOptions`
 - `Expectation`, `ExpectationId`
-- `OpenAPIDefinition`, `OpenAPIExpectation`
+- `OpenAPIDefinition`, `OpenAPIExpectation`, `ConditionalRequestDefinition`
 - `Verification`, `VerificationSequence`, `VerificationTimes`
 - `Ports`
 - `RequestDefinition` (alias for `HttpRequest`)
 - `Jwt` (JWT / bearer-token request matcher)
 
+Every model can also be built from the expectation JSON with `from_hash`. Keys
+may be strings (`'httpRequest' => {...}`, as `JSON.parse` returns them) or
+symbols (`"httpRequest": {...}` or `httpRequest: {...}`):
+
+```ruby
+client.upsert(MockServer::Expectation.from_hash({
+  "httpRequest": { "path": '/some/path' },
+  "httpResponse": { "statusCode": 200, "body": 'some_response_body' }
+}))
+```
+
+Symbol keys need a client released after 8.0.0; 8.0.0 and earlier read only <!-- version-ref:keep -->
+string keys and build an empty expectation from a symbol-keyed hash.
+
+Headers, query parameters, path parameters, trailers and cookies can be given
+in the same shapes the JSON uses. A key match style sets whether at least one
+value of each listed key must match (`SUB_SET`, the default) or every value of
+it (`MATCHING_KEY`):
+
+```ruby
+MockServer::HttpRequest.new(
+  path: '/view/cart',
+  headers: { 'Accept' => ['application/json'] },
+  headers_key_match_style: 'MATCHING_KEY',
+  query_string_parameters: [{ name: 'cartId', values: ['055CA455'] }],
+  cookies: { 'session' => '4930456C' }
+)
+```
+
+An `httpRequest` holding `specUrlOrPayload` is read as an `OpenAPIDefinition`
+matcher, and `HttpOverrideForwardedRequest` carries `request_override`,
+`response_override` and `response_template`. These need a client released
+after 8.0.0. <!-- version-ref:keep -->
+
+An `httpRequest` holding `if` is read as a `ConditionalRequestDefinition`: when
+`if_request` matches, `then_request` must match too, otherwise `else_request`
+must. A load scenario `LoadStep` takes `checks`, a list of `LoadCheck`
+assertions on each step's response. These need a client released after 8.0.0. <!-- version-ref:keep -->
+
+```ruby
+client.when(
+  MockServer::ConditionalRequestDefinition.new(
+    if_request: MockServer::HttpRequest.new(method: 'POST'),
+    then_request: MockServer::HttpRequest.new(path: '/orders'),
+    else_request: MockServer::HttpRequest.new(method: 'GET')
+  )
+).respond(MockServer::HttpResponse.new(status_code: 200))
+```
+
 ## JWT and combined body matchers
 
 Match a request by the claims in its JWT (carried by default in the
@@ -280,6 +329,21 @@ client.start_chaos_experiment(
 SLO tracking must be enabled on the server (`sloTrackingEnabled=true`) or
 `verify_slo` raises `MockServer::Error` on HTTP 400.
 
+## Diagnose Matching
+
+`explain(correlation_id)` tells you which expectation would serve a recorded request now and why
+each expectation ahead of it was passed over; `debug_mismatch(request)` compares a request with
+every active expectation; `explain_unmatched(limit:, suggest_fixes:)` explains recent requests
+that matched nothing. Each returns a typed result (`RequestExplanation`, `DebugMismatchResult`,
+`ExplainUnmatchedResult`) and raises `MockServer::Error` with the server's reason on failure.
+
+```ruby
+explanation = client.explain('abc-123-def-456')
+explanation.skipped_expectations.each do |skipped|
+  puts "#{skipped.expectation_id} #{skipped.reason}: #{skipped.explanation}"
+end
+```
+
 ## Interactive Breakpoints
 
 The client supports matcher-driven interactive breakpoints over the callback WebSocket. Register a breakpoint matcher to pause forwarded/proxied exchanges at specific phases and inspect/modify/continue them via callback handlers.
@@ -353,7 +417,7 @@ launcher_path = MockServer::BinaryLauncher.ensure_launcher
 ### Specify a version
 
 ```ruby
-handle = MockServer::BinaryLauncher.start(port: 1080, version: '8.0.0')
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '9.1.0')
 ```
 
 ### API reference
@@ -364,6 +428,8 @@ handle = MockServer::BinaryLauncher.start(port: 1080, version: '8.0.0')
 | `MockServer::BinaryLauncher.start(port:, version:, extra_args:, log:)` | Ensure the binary and start MockServer. Returns a `ServerHandle`. |
 | `MockServer::BinaryLauncher::ServerHandle` | Handle to the running process. Methods: `stop(timeout:)`, `running?`. Attributes: `pid`, `port`, `launcher`. |
 
+On Windows the launcher runs `mockserver.bat` through `cmd.exe` with every argument quoted, so characters such as `^`, `!` and parentheses reach MockServer unchanged. `start` raises `MockServer::Error` if the launcher path or an `extra_args` entry contains `"`, `<`, `>`, `|`, `&`, a line break or NUL, or if together they contain more than one `%` (which `cmd.exe` would expand as a `%NAME%` variable); it also needs a native Windows Ruby (mswin or mingw, such as RubyInstaller). No shell is used on Linux or macOS.
+
 ### Supported platforms
 
 | OS | Architecture |

data/lib/mockserver/a2a.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'uri'
+require_relative 'mcp'
 
 module MockServer
   # Fluent builder for mocking an A2A (Agent-to-Agent) agent.
@@ -45,11 +46,11 @@ module MockServer
     end
 
     # Escape Velocity metacharacters so literal +$+ / +#+ survive rendering.
+    # Shares the MCP builder's rules (backslash runs before +$+, +#+ or the end
+    # of the value are escaped too).
     # @api private
     def self.escape_velocity(value)
-      return value if value.nil?
-
-      value.to_s.gsub('$', '${esc.d}').gsub('#', '${esc.h}')
+      MCP.escape_velocity(value)
     end
 
     # @api private

data/lib/mockserver/binary_launcher.rb

@@ -48,6 +48,9 @@ module MockServer
     # Strict pattern for version strings — blocks path separators and '..'.
     VERSION_PATTERN = /\A[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.]+)?\z/
 
+    # Characters refused in the launcher path and arguments on Windows (see +windows_command_line+).
+    WINDOWS_UNSAFE = /["<>|&\r\n\0]/
+
     class << self
       # Resolve the current platform to the bundle naming tokens.
       #
@@ -241,18 +244,53 @@ module MockServer
         launcher = ensure_launcher(version: version, log: log)
         args = ['-serverPort', port.to_s] + extra_args
 
-        # H4: On Windows, .bat files must be invoked via cmd.exe /c.
         # H5: Drain stdout/stderr via :out/:err redirection to avoid pipe-buffer deadlock.
+        # On Unix the [command, argv0] form never goes through a shell, even with no args.
         pid = if windows?
-                Process.spawn('cmd.exe', '/c', launcher, *args,
+                Process.spawn(windows_command_line(launcher, args),
                               out: File::NULL, err: File::NULL)
               else
-                Process.spawn(launcher, *args,
+                Process.spawn([launcher, launcher], *args,
                               out: File::NULL, err: File::NULL)
               end
         ServerHandle.new(pid: pid, port: port, launcher: launcher)
       end
 
+      # Build the cmd.exe command line that runs the +.bat+ launcher on Windows.
+      #
+      # Native Windows Ruby passes a single command string to CreateProcess
+      # unchanged unless it sees a redirection (+<+, +>+, +|+, +&+, a line break
+      # or +%NAME%+), so those are refused, which keeps the line away from a
+      # second shell. Each part is double-quoted so cmd.exe takes +^+, +(+, +)+
+      # and +!+ literally (+/v:off+), and +/d+ skips AutoRun. cmd.exe expands
+      # +%NAME%+ even inside quotes, so a line with two or more +%+ is refused.
+      #
+      # @param launcher [String] path of the +.bat+ launcher
+      # @param args [Array<String>] arguments for the launcher
+      # @return [String]
+      # @raise [Error] if a part cannot be passed to cmd.exe safely, or Ruby is not a native Windows build
+      def windows_command_line(launcher, args)
+        unless RbConfig::CONFIG['host_os'] =~ /mswin|mingw/i
+          raise Error, 'starting the Windows launcher needs a native Windows Ruby (mswin or mingw, ' \
+                       "such as RubyInstaller); this Ruby is #{RbConfig::CONFIG['host_os']}"
+        end
+        # Messages name the part, never its value, which may be a secret.
+        parts = [launcher, *args].map(&:to_s)
+        parts.each_with_index do |part, i|
+          next unless part.match?(WINDOWS_UNSAFE)
+
+          name = i.zero? ? 'the launcher path' : "argument #{i - 1}"
+          raise Error, "#{name} cannot be passed through cmd.exe safely " \
+                       '(contains ", <, >, |, &, a line break or NUL)'
+        end
+        line = parts.map { |part| quote_cmd_arg(part) }.join(' ')
+        if line.count('%') > 1
+          raise Error, 'the launcher path and arguments contain more than one %, which cmd.exe would expand ' \
+                       'as an environment variable reference (%NAME%); remove the % characters to run on Windows'
+        end
+        %(cmd.exe /d /v:off /s /c "#{line}")
+      end
+
       # Remove old version directories from the cache, keeping the current version
       # and at most MAX_PREVIOUS_VERSIONS_TO_KEEP previous versions.
       #
@@ -329,6 +367,13 @@ module MockServer
 
       private
 
+      # Double-quote one cmd.exe argument, doubling a trailing run of backslashes
+      # so it cannot escape the closing quote when the program splits its command line.
+      def quote_cmd_arg(arg)
+        trailing = arg[/\\*\z/]
+        %("#{arg}#{trailing}")
+      end
+
       # Build a clear, actionable error message for a missing release bundle.
       #
       # Explains that no downloadable bundle exists for +version+ and lists the

data/lib/mockserver/client.rb

@@ -912,14 +912,15 @@ module MockServer
     #
     # @param experiment [Hash, #to_h] the experiment definition
     # @return [Hash] the started status, e.g. { "status" => "started", "name" => ... }
-    # @raise [Error] if the experiment definition is invalid or chaos is disabled
-    #   (HTTP 400/403), or on any other failure
+    # @raise [Error] if the experiment definition is invalid (HTTP 400), if
+    #   control-plane authorization rejects the request (HTTP 403), or on any other
+    #   failure; there is no server setting that disables chaos experiments
     def start_chaos_experiment(experiment)
       payload = experiment.respond_to?(:to_h) ? experiment.to_h : experiment
       body = JSON.generate(payload)
       status, response_body = request('PUT', '/mockserver/chaosExperiment', body)
       if status == 403
-        raise Error, 'Chaos experiment rejected (status=403): chaos is disabled on the server'
+        raise Error, "Chaos experiment rejected (status=403): control-plane authorization denied: #{response_body}"
       end
       if status >= 400
         raise Error, "Failed to start chaos experiment (status=#{status}): #{response_body}"
@@ -928,6 +929,85 @@ module MockServer
       response_body && !response_body.empty? ? JSON.parse(response_body) : {}
     end
 
+    # -------------------------------------------------------------------
+    # Diagnostics (explain / debug_mismatch / explain_unmatched)
+    # -------------------------------------------------------------------
+
+    # Explain how a recorded request would be served now
+    # (PUT /mockserver/explain?correlationId=<id>): re-checks it against the
+    # current expectations, in the order MockServer evaluates them, and returns
+    # the expectation that would serve it, why each expectation ahead of that
+    # one was passed over, and which lower-priority expectations it shadows.
+    # Read-only: it consumes no Times and moves no scenario.
+    #
+    # @param correlation_id [String] the correlation id of the request's log entries
+    # @return [RequestExplanation]
+    # @raise [ArgumentError] if +correlation_id+ is nil or blank
+    # @raise [Error] with the server's reason when no request is recorded with
+    #   this id (never received, cleared or evicted) or it is not an HTTP request
+    def explain(correlation_id)
+      if correlation_id.nil? || correlation_id.to_s.strip.empty?
+        raise ArgumentError, 'explain requires a non blank correlation_id'
+      end
+
+      RequestExplanation.from_hash(
+        diagnostic_request('/mockserver/explain', nil, { 'correlationId' => correlation_id.to_s },
+                           "explain failed for correlationId \"#{correlation_id}\"")
+      )
+    end
+
+    # Compare a request with every active expectation
+    # (PUT /mockserver/debugMismatch): for each, whether it matches and the
+    # per-field differences, plus the closest match. Only an HTTP request is
+    # supported.
+    #
+    # @param request [HttpRequest, Hash] the request to check
+    # @return [DebugMismatchResult]
+    # @raise [Error] with the server's reason for a non-HTTP request definition
+    def debug_mismatch(request)
+      payload = request.respond_to?(:to_h) ? request.to_h : request
+      DebugMismatchResult.from_hash(
+        diagnostic_request('/mockserver/debugMismatch', JSON.generate(payload), nil, 'debugMismatch failed')
+      )
+    end
+
+    # Explain why recent requests matched no expectation
+    # (PUT /mockserver/explainUnmatched): each recent unmatched request with its
+    # closest expectations, closest first.
+    #
+    # @param limit [Integer, nil] how many recent unmatched requests to analyse (server default 10)
+    # @param suggest_fixes [Boolean, nil] add a suggested JSON patch to each of
+    #   the five closest non-matching expectations (nothing is applied)
+    # @return [ExplainUnmatchedResult]
+    def explain_unmatched(limit: nil, suggest_fixes: nil)
+      options = {}
+      options['limit'] = limit unless limit.nil?
+      options['suggestFixes'] = suggest_fixes unless suggest_fixes.nil?
+      ExplainUnmatchedResult.from_hash(
+        diagnostic_request('/mockserver/explainUnmatched', options.empty? ? nil : JSON.generate(options), nil,
+                           'explainUnmatched failed')
+      )
+    end
+
+    # @api private
+    # PUT a diagnostic request and return the parsed 200 body; any other status,
+    # or a body that is not a JSON object, raises {Error} with the server's
+    # +error+ or the body.
+    def diagnostic_request(path, body, query_params, failure)
+      status, response_body = do_request('PUT', path, body, query_params)
+      parsed = begin
+        response_body.nil? || response_body.empty? ? {} : JSON.parse(response_body)
+      rescue JSON::ParserError
+        nil
+      end
+      if status != 200 || !parsed.is_a?(Hash)
+        reason = parsed.is_a?(Hash) ? parsed['error'] : nil
+        raise Error, "#{failure} (status=#{status}): #{reason || response_body}"
+      end
+
+      parsed
+    end
+
     # -------------------------------------------------------------------
     # Stateful scenarios (state machine control plane)
     # -------------------------------------------------------------------

data/lib/mockserver/mcp.rb

@@ -31,20 +31,37 @@ module MockServer
       quoted[1...-1]
     end
 
+    VELOCITY_METACHARACTER_ESCAPES = { '$' => '${esc.d}', '#' => '${esc.h}' }.freeze
+    private_constant :VELOCITY_METACHARACTER_ESCAPES
+
     # Escape Velocity metacharacters so literal +$+ / +#+ survive rendering.
+    # Velocity consumes backslashes written before a reference or directive, so
+    # a run of backslashes followed by +$+, +#+ or the end of the value is
+    # escaped too; other backslashes are literal to Velocity and left as-is.
     # @api private
     def self.escape_velocity(value)
       return value if value.nil?
 
-      value.to_s.gsub('$', '${esc.d}').gsub('#', '${esc.h}')
+      # group 2 consumes the metacharacter after a run, is empty at the end and
+      # unset (empty alternative) otherwise, so no lookaround is needed
+      value.to_s.gsub(/(\\+)(?:([$#]|\z)|)|[$#]/) do |match|
+        run = Regexp.last_match(1)
+        next VELOCITY_METACHARACTER_ESCAPES[match] if run.nil?
+
+        following = Regexp.last_match(2)
+        next run if following.nil?
+
+        ('${esc.b}' * run.length) + VELOCITY_METACHARACTER_ESCAPES.fetch(following, '')
+      end
     end
 
-    # Escape single quotes for safe inclusion inside a JSONPath string literal.
+    # Escape backslashes, then single quotes, for safe inclusion inside a
+    # single-quoted JSONPath string literal.
     # @api private
     def self.escape_json_path(value)
       return '' if value.nil?
 
-      value.to_s.gsub("'", "\\\\'")
+      value.to_s.gsub('\\') { '\\\\' }.gsub("'") { "\\'" }
     end
 
     # Parse + re-serialize JSON (compact) to validate it. Raises on invalid JSON.