mockserver-client 7.6.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5058c222282161435bc425f0993f4795a0d4d8ca0f8fd1a921f5848ebe7b7fe8
-  data.tar.gz: 91e14949df3f145e9c107374ee8edc6edea90343c91d509922495ea5eb220c37
+  metadata.gz: 65c675ce8a2644ccefd09d08e036b68676dc481222d4e0e41f8d2a31f5ee4d9e
+  data.tar.gz: 5ce4a28531387f73bef657eac15879122b9bfce161c29b7ac03fe2e609fea74e
 SHA512:
-  metadata.gz: b038601c5a23e3d510d85f3a7843d9f53cf87b849c1b0c76e9bab0a7dfca5a30daf81e036384c36afdae28e09504ec4ff8ff27ebf2d31bbd03f0c348a5f567ba
-  data.tar.gz: 1b2958cd9f90ad4f8570f061d75fe20faf255eb427303056f8d7fdd4c6872c74dd504a05ed28a30694ecb0a4fc759411bdacf584c330e4f2b9bfd00b3b1d6398
+  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: '7.6.0')
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '9.0.0')
 ```
 
 ### API reference
@@ -364,6 +428,8 @@ handle = MockServer::BinaryLauncher.start(port: 1080, version: '7.6.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

@@ -862,8 +862,8 @@ module MockServer
     # (PUT /mockserver/verifySLO).
     #
     # The server encodes the verdict in the HTTP status: 200 for PASS or
-    # INCONCLUSIVE, 406 for FAIL, 400 for malformed criteria or when SLO tracking
-    # is disabled (+sloTrackingEnabled=false+). The decoded verdict Hash carries
+    # INCONCLUSIVE, 406 for FAIL, 403 when SLO tracking is disabled
+    # (+sloTrackingEnabled=false+) and 400 for malformed criteria. The decoded verdict Hash carries
     # the overall +result+ and the per-objective +objectiveResults+ so callers can
     # inspect why an SLO failed.
     #
@@ -875,7 +875,7 @@ module MockServer
     # @param criteria [Hash, #to_h] the SLO criteria
     # @return [Hash] the SLO verdict (result PASS or INCONCLUSIVE)
     # @raise [VerificationError] if the verdict is FAIL (HTTP 406)
-    # @raise [Error] if criteria are malformed or SLO tracking is disabled (HTTP 400),
+    # @raise [Error] if SLO tracking is disabled (HTTP 403) or criteria are malformed (HTTP 400),
     #   or on any other failure
     def verify_slo(criteria)
       payload = criteria.respond_to?(:to_h) ? criteria.to_h : criteria
@@ -884,9 +884,12 @@ module MockServer
       if status == 406
         raise VerificationError, (response_body && !response_body.empty? ? response_body : 'SLO verdict: FAIL')
       end
+      if status == 403
+        raise Error, 'SLO tracking is disabled — set sloTrackingEnabled=true ' \
+                     "on the server: #{response_body}"
+      end
       if status == 400
-        raise Error, 'Invalid SLO criteria (or SLO tracking disabled — set ' \
-                     "sloTrackingEnabled=true on the server): #{response_body}"
+        raise Error, "Invalid SLO criteria: #{response_body}"
       end
       if status >= 400
         raise Error, "Failed to verify SLO (status=#{status}): #{response_body}"
@@ -925,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)
     # -------------------------------------------------------------------
@@ -1129,6 +1211,116 @@ module MockServer
       []
     end
 
+    # Send a retrieve request filtered by expectation id.
+    #
+    # An expectation id may be sent in place of a request matcher. For
+    # "ACTIVE_EXPECTATIONS" the server returns only the expectation with that id;
+    # for every other type it returns the entries matching that expectation's
+    # request, exactly as verify by expectation id matches them. An unknown id is
+    # rejected with a 400.
+    #
+    # @param expectation_id [String]
+    # @param query_params [Hash]
+    # @return [Array(Integer, String)] the status and response body
+    # @api private
+    def retrieve_by_id(expectation_id, query_params)
+      do_request(
+        'PUT', '/mockserver/retrieve', JSON.generate({ 'id' => expectation_id }), query_params
+      )
+    end
+    private :retrieve_by_id
+
+    # Retrieve the recorded requests matching the request of the expectation with the given id.
+    # @param expectation_id [String]
+    # @return [Array<HttpRequest>]
+    def retrieve_recorded_requests_by_id(expectation_id)
+      status, response_body = retrieve_by_id(
+        expectation_id, { 'type' => 'REQUESTS', 'format' => 'JSON' }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve recorded requests by id (status=#{status}): #{response_body}"
+      end
+
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed.map { |r| HttpRequest.from_hash(r) } if parsed.is_a?(Array)
+      end
+      []
+    end
+
+    # Retrieve the active expectation with the given id.
+    # @param expectation_id [String]
+    # @return [Array<Expectation>]
+    def retrieve_active_expectations_by_id(expectation_id)
+      status, response_body = retrieve_by_id(
+        expectation_id, { 'type' => 'ACTIVE_EXPECTATIONS', 'format' => 'JSON' }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve active expectations by id (status=#{status}): #{response_body}"
+      end
+
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed.map { |e| Expectation.from_hash(e) } if parsed.is_a?(Array)
+      end
+      []
+    end
+
+    # Retrieve the recorded expectations matching the request of the expectation with the given id.
+    # @param expectation_id [String]
+    # @return [Array<Expectation>]
+    def retrieve_recorded_expectations_by_id(expectation_id)
+      status, response_body = retrieve_by_id(
+        expectation_id, { 'type' => 'RECORDED_EXPECTATIONS', 'format' => 'JSON' }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve recorded expectations by id (status=#{status}): #{response_body}"
+      end
+
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed.map { |e| Expectation.from_hash(e) } if parsed.is_a?(Array)
+      end
+      []
+    end
+
+    # Retrieve the recorded requests and responses matching the request of the expectation with the given id.
+    # @param expectation_id [String]
+    # @return [Array<HttpRequestAndHttpResponse>]
+    def retrieve_recorded_requests_and_responses_by_id(expectation_id)
+      status, response_body = retrieve_by_id(
+        expectation_id, { 'type' => 'REQUEST_RESPONSES', 'format' => 'JSON' }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve request/responses by id (status=#{status}): #{response_body}"
+      end
+
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed.map { |rr| HttpRequestAndHttpResponse.from_hash(rr) } if parsed.is_a?(Array)
+      end
+      []
+    end
+
+    # Retrieve the log messages matching the request of the expectation with the given id.
+    # @param expectation_id [String]
+    # @return [Array<String>]
+    def retrieve_log_messages_by_id(expectation_id)
+      status, response_body = retrieve_by_id(expectation_id, { 'type' => 'LOGS' })
+      if status >= 400
+        raise Error, "Failed to retrieve log messages by id (status=#{status}): #{response_body}"
+      end
+
+      return [] unless response_body && !response_body.empty?
+
+      begin
+        parsed = JSON.parse(response_body)
+        parsed.is_a?(Array) ? parsed : []
+      rescue JSON::ParserError
+        response_body.split("------------------------------------\n")
+      end
+    end
+
     # Retrieve the active expectations as MockServer SDK setup code (the builder
     # code that recreates the expectations) in the requested language.
     # @param format [String] one of "java", "javascript", "python", "go",