mockserver-client 8.0.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b32e53f8e5117c75dddf6e9b86e379892b47066fe7dbe3919da8d97232600fce
-  data.tar.gz: 64aa0e6608d0be522249a761e0009fce60058ebe2f6c67dbd9617bd3fffaa3fe
+  metadata.gz: 65c675ce8a2644ccefd09d08e036b68676dc481222d4e0e41f8d2a31f5ee4d9e
+  data.tar.gz: 5ce4a28531387f73bef657eac15879122b9bfce161c29b7ac03fe2e609fea74e
 SHA512:
-  metadata.gz: c87f1c996f7ec3f49502a5465c8990a076bef51262408570706cb520359f6446e9adbfafd0a9b6c1bace45b3164caaf3340fb1f4d848d877047c0f41d361a159
-  data.tar.gz: 741e8bd63ccb4d63edcfd7be2467d6b619fa5be8924f295d2f886da3af0017e201d8891adc8076c6af65c42dbbbf4202d259573e6c55f9a58f0a131993f4294d
+  metadata.gz: 5b3e1a67574cfb21096ded9e3d651ef37f0f0963d077f87829d1ea43940c957f2404a6144772b2d8d72230a568073b8869fd81006e7dde367a046faa436cc83a
+  data.tar.gz: '09436cda59e502b5b89444e0ca7aa32aa8fdd0196445aebc99e7d984c5f21b3ce259dc86cc31b1e08b1949c15a06eb80300fd3d6eca84e921a8a5fb1cd73c791'

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.0.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/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

@@ -928,6 +928,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)
     # -------------------------------------------------------------------