mockserver-client 9.0.0 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65c675ce8a2644ccefd09d08e036b68676dc481222d4e0e41f8d2a31f5ee4d9e
-  data.tar.gz: 5ce4a28531387f73bef657eac15879122b9bfce161c29b7ac03fe2e609fea74e
+  metadata.gz: 02d995291d2bc1c0c4b875711f568d604c4e6af009952512109b44ff49fa2fed
+  data.tar.gz: 455d49792d3fec33d41dd66eade0ca64e5ee4049306566c411da1008a431b30a
 SHA512:
-  metadata.gz: 5b3e1a67574cfb21096ded9e3d651ef37f0f0963d077f87829d1ea43940c957f2404a6144772b2d8d72230a568073b8869fd81006e7dde367a046faa436cc83a
-  data.tar.gz: '09436cda59e502b5b89444e0ca7aa32aa8fdd0196445aebc99e7d984c5f21b3ce259dc86cc31b1e08b1949c15a06eb80300fd3d6eca84e921a8a5fb1cd73c791'
+  metadata.gz: 71d509505576e64dd73a68b79352bbdd0065519b5775767025340798032832bccffa5806b5bac0cda568286b0202baf7af48f84155a095df301df3c60e6be500
+  data.tar.gz: 5d6c9b72e335529472b51013bfbaad1d521be2784267d95a48284d2a777577a19ccd87b5f68eedae3bab6195e774d80880e4712f4f289993384d84309433cd92

data/README.md

@@ -56,6 +56,15 @@ end
 # Client is automatically closed when the block exits
 ```
 
+## Control-Plane Basic Authentication
+
+When MockServer accepts control-plane Basic authentication, pass `control_plane_basic_auth: [username, password]` with `secure: true` (MockServer refuses Basic credentials without TLS). They are sent on every control-plane request and on the callback and breakpoint WebSockets.
+
+```ruby
+client = MockServer::Client.new('localhost', 1080, secure: true,
+                                control_plane_basic_auth: ['admin', ENV.fetch('MOCKSERVER_PASSWORD')])
+```
+
 ## WebSocket Callbacks
 
 ```ruby
@@ -99,6 +108,7 @@ All 27 domain model classes are available under the `MockServer` module:
 - `Ports`
 - `RequestDefinition` (alias for `HttpRequest`)
 - `Jwt` (JWT / bearer-token request matcher)
+- `DateTimeMatcher` (date-time matcher for header, query, path-parameter and cookie values)
 
 Every model can also be built from the expectation JSON with `from_hash`. Keys
 may be strings (`'httpRequest' => {...}`, as `JSON.parse` returns them) or
@@ -129,6 +139,41 @@ MockServer::HttpRequest.new(
 )
 ```
 
+A header, query parameter, path parameter or cookie value can also be a
+date-time matcher. It compares the request's value as a date-time with
+`before`, `after` or `equal_to_date_time`, where the expected value is `now`,
+`now` with an offset such as `now -1 hours`, or a date-time such as
+`2026-10-21T00:00:00Z`. A plain string such as `'before:2026-01-01'` is still
+matched literally.
+
+```ruby
+MockServer::HttpRequest.new(path: '/orders')
+  .with_header('X-Issued-At', MockServer::DateTimeMatcher.after('now -1 hours'))
+  .with_header('If-Modified-Since',
+               MockServer::DateTimeMatcher.before('2026-10-21T00:00:00Z').with_actual_format('rfc1123'))
+  .with_cookie('seen', MockServer::DateTimeMatcher.equal_to_date_time('now')
+                                                   .with_truncate_expected('startOfDay')
+                                                   .with_truncate_actual('startOfDay')
+                                                   .with_zone('Europe/London'))
+# headers => [{"name"=>"X-Issued-At", "values"=>[{"after"=>"now -1 hours"}]}, ...]
+```
+
+Each `with_*` option (`with_actual_format`, `with_truncate_expected`,
+`with_truncate_actual`, `with_apply_truncation_last`, `with_zone`, `with_not`)
+returns a new matcher. `from_hash` reads an object holding `before`, `after` or
+`equalToDateTime` as a `DateTimeMatcher`.
+
+A JSONPath or XPath body matcher takes a `date_time:` too: the body matches when
+a value the JSONPath selects, or the text of a node the XPath selects, is a
+matching date-time.
+
+```ruby
+MockServer::HttpRequest.new(path: '/orders',
+                            body: MockServer::Body.json_path('$.order.created',
+                                                             date_time: MockServer::DateTimeMatcher.after('now -1 days')))
+# body => {"type"=>"JSON_PATH", "jsonPath"=>"$.order.created", "dateTime"=>{"after"=>"now -1 days"}}
+```
+
 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
@@ -185,6 +230,28 @@ body = MockServer::Body.all_of(
 request = MockServer::HttpRequest.new(method: 'POST', path: '/api').with_body(body)
 ```
 
+## Client IP matcher
+
+Match requests by the client IP address or CIDR range, IPv4 or IPv6. The client address is the TCP peer of the connection, not `X-Forwarded-For`; prefix with `!` to match every other address.
+
+```ruby
+MockServer::HttpRequest.new(path: '/internal').with_client_ip('10.0.0.0/8')
+# or MockServer::HttpRequest.new(path: '/internal', client_ip: '!10.0.0.0/8')
+```
+
+## Any-of (logical OR) matcher
+
+`MockServer::AnyOfRequestDefinition` matches a request when any one of its request matchers does, tried in order. Entries may be `HttpRequest`, `OpenAPIDefinition`, `ConditionalRequestDefinition` or a nested `AnyOfRequestDefinition`; `not_any_of: true` matches requests that match none of them. `ExplainedExpectation#any_of` says which entry came closest when none matches.
+
+```ruby
+client.when(
+  MockServer::AnyOfRequestDefinition.new(
+    any_of: [MockServer::HttpRequest.new(method: 'GET', path: '/pets'),
+             MockServer::HttpRequest.new(method: 'GET', path: '/animals')]
+  )
+).respond(MockServer::HttpResponse.new(body: 'pets or animals'))
+```
+
 ## LLM Mocking
 
 Fluent builders under `MockServer::LLM` mock LLM provider endpoints. They produce
@@ -300,6 +367,40 @@ JSON-RPC task response to the caller *and* POSTs the completed task to the
 webhook URL. As with MCP mocking, `build` returns the raw expectation Hashes if
 you prefer to register them yourself.
 
+## Expectation Metadata
+
+Label expectations with `metadata` (String keys, any JSON value), then retrieve or clear them by
+metadata, find the ones that never matched a request, and page large lists:
+
+```ruby
+client.when(MockServer::HttpRequest.new(path: '/checkout'))
+      .with_metadata('owner' => 'team-a', 'ticket' => 4211, 'tags' => ['smoke'])
+      .respond(MockServer::HttpResponse.new(status_code: 200))
+
+client.retrieve_active_expectations_by_metadata('owner', 'team-a')
+client.retrieve_active_expectations_by_metadata_key('ticket')
+client.retrieve_unmatched_expectations
+client.retrieve_active_expectations(
+  filter: MockServer::ExpectationFilter.new.with_metadata_json_path("$.tags[?(@ == 'smoke')]").with_limit(10)
+)
+client.retrieve_recorded_expectations(offset: 0, limit: 50)
+# replay changing responses in order, keep only some request headers, move large bodies into files
+client.retrieve_recorded_expectations(
+  options: MockServer::RecordedExpectationsOptions.new.with_repeats_as_scenarios
+                                                    .with_capture_headers('X-Tenant')
+                                                    .with_extract_bodies_larger_than(1024)
+)
+
+client.clear_by_metadata('owner', 'team-a')
+client.clear_by_metadata_key('ticket')
+client.clear_unmatched_expectations
+```
+
+A String value is matched as text; any other value (`42`, `true`, an Array or Hash) is matched as
+JSON, and `MockServer::ExpectationFilter::JSON_NULL` selects a stored JSON null. A blank key or
+JSONPath, a `nil` value, negative paging, paging on clear, or a clear with no selection raises
+`ArgumentError` before anything is sent, so a mistake can never clear every expectation.
+
 ## SRE Control Plane (SLO + Chaos)
 
 Verify service-level objectives and drive scheduled chaos experiments against
@@ -417,7 +518,7 @@ launcher_path = MockServer::BinaryLauncher.ensure_launcher
 ### Specify a version
 
 ```ruby
-handle = MockServer::BinaryLauncher.start(port: 1080, version: '9.0.0')
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '9.2.0')
 ```
 
 ### API reference

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/client.rb

@@ -4,6 +4,7 @@ require 'net/http'
 require 'uri'
 require 'json'
 require 'openssl'
+require 'base64'
 
 module MockServer
   # Synchronous MockServer client.
@@ -28,14 +29,28 @@ module MockServer
   class Client
     HTTP_TIMEOUT = 60 # seconds, matching Python client
 
+    # Default for clear's +filter:+ so an explicit nil filter is rejected
+    # instead of silently clearing everything.
+    NO_FILTER = Object.new.freeze
+    private_constant :NO_FILTER
+
     # @param host [String]
     # @param port [Integer]
     # @param context_path [String]
     # @param secure [Boolean]
     # @param ca_cert_path [String, nil]
     # @param tls_verify [Boolean]
+    # @param control_plane_basic_auth [Array(String, String), nil] control-plane HTTP Basic
+    #   +[username, password]+, sent on every control-plane request and on the callback and
+    #   breakpoint WebSockets; MockServer refuses Basic credentials without TLS, so use +secure: true+
     def initialize(host, port, context_path: '', secure: false,
-                   ca_cert_path: nil, tls_verify: true)
+                   ca_cert_path: nil, tls_verify: true, control_plane_basic_auth: nil)
+      @control_plane_authorization = basic_authorization(control_plane_basic_auth)
+      if @control_plane_authorization && !secure
+        warn 'MockServer::Client: control-plane Basic credentials are configured without secure: true, so the password ' \
+             'can be read on the network, and MockServer refuses them unless controlPlaneBasicAuthenticationAllowInsecure ' \
+             'is set (tests only)'
+      end
       @host = host
       @port = port
       @context_path = context_path
@@ -100,10 +115,19 @@ module MockServer
     end
 
     # Clear expectations and/or logs.
+    #
+    # With +filter:+ only the expectations matching both +request+ (when
+    # given) and the filter's metadata / unmatched selection are cleared; the
+    # event log is left untouched. A filter must select something and must not
+    # page, otherwise ArgumentError is raised and nothing is sent.
+    #
     # @param request [HttpRequest, nil]
     # @param type [String, nil] "EXPECTATIONS", "LOG", or "ALL"
+    # @param filter [ExpectationFilter] selection of expectations to clear
     # @return [nil]
-    def clear(request = nil, type: nil)
+    def clear(request = nil, type: nil, filter: NO_FILTER)
+      return clear_with_filter(request, type, filter) unless filter.equal?(NO_FILTER)
+
       query_params = {}
       query_params['type'] = type if type
       body = request ? JSON.generate(request.to_h) : ''
@@ -117,6 +141,25 @@ module MockServer
       nil
     end
 
+    # Clear the expectations whose metadata has +key+ with a value equal to
+    # +value+ (see {ExpectationFilter#with_metadata}).
+    # @return [nil]
+    def clear_by_metadata(key, value)
+      clear(filter: ExpectationFilter.new.with_metadata(key, value))
+    end
+
+    # Clear the expectations whose metadata has +key+, with any value.
+    # @return [nil]
+    def clear_by_metadata_key(key)
+      clear(filter: ExpectationFilter.new.with_metadata_key(key))
+    end
+
+    # Clear the expectations that have not matched any request.
+    # @return [nil]
+    def clear_unmatched_expectations
+      clear(filter: ExpectationFilter.new.with_unmatched(true))
+    end
+
     # Clear by expectation ID.
     # @param expectation_id [String]
     # @param type [String, nil]
@@ -265,6 +308,9 @@ module MockServer
     #
     # +config_json+ is a ConfigurationDTO JSON document; only the fields present
     # are applied (partial update). A nil value is sent as an empty body.
+    # Properties fixed at startup, such as forwardProxyBlockPrivateNetworks,
+    # forwardProxyAllowedHosts and forwardProxyDeniedHosts, are ignored and the
+    # server logs a warning.
     #
     # @param config_json [String, nil] the ConfigurationDTO JSON
     # @return [String] the serialized updated configuration JSON
@@ -912,14 +958,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}"
@@ -1173,13 +1220,17 @@ module MockServer
 
     # Retrieve active expectations.
     # @param request [HttpRequest, nil]
+    # @param filter [ExpectationFilter, nil] metadata / unmatched selection and paging
     # @return [Array<Expectation>]
-    def retrieve_active_expectations(request: nil)
+    def retrieve_active_expectations(request: nil, filter: nil)
+      unless filter.nil? || filter.is_a?(ExpectationFilter)
+        raise ArgumentError, "filter must be a MockServer::ExpectationFilter, got #{filter.class}"
+      end
+
       body = request ? JSON.generate(request.to_h) : ''
-      status, response_body = do_request(
-        'PUT', '/mockserver/retrieve', body,
-        { 'type' => 'ACTIVE_EXPECTATIONS', 'format' => 'JSON' }
-      )
+      query_params = { 'type' => 'ACTIVE_EXPECTATIONS', 'format' => 'JSON' }
+      query_params.merge!(filter.to_query_params) if filter
+      status, response_body = do_request('PUT', '/mockserver/retrieve', body, query_params)
       if status >= 400
         raise Error, "Failed to retrieve active expectations (status=#{status}): #{response_body}"
       end
@@ -1191,14 +1242,47 @@ module MockServer
       []
     end
 
-    # Retrieve recorded expectations.
+    # Retrieve active expectations whose metadata has +key+ with a value
+    # equal to +value+ (see {ExpectationFilter#with_metadata}).
+    # @return [Array<Expectation>]
+    def retrieve_active_expectations_by_metadata(key, value)
+      retrieve_active_expectations(filter: ExpectationFilter.new.with_metadata(key, value))
+    end
+
+    # Retrieve active expectations whose metadata has +key+, with any value.
+    # @return [Array<Expectation>]
+    def retrieve_active_expectations_by_metadata_key(key)
+      retrieve_active_expectations(filter: ExpectationFilter.new.with_metadata_key(key))
+    end
+
+    # Retrieve the active expectations that have not matched any request.
+    # @return [Array<Expectation>]
+    def retrieve_unmatched_expectations
+      retrieve_active_expectations(filter: ExpectationFilter.new.with_unmatched(true))
+    end
+
+    # Retrieve recorded expectations, optionally one page of them in the
+    # order the requests were received.
     # @param request [HttpRequest, nil]
+    # @param offset [Integer, nil] number to skip, zero or more
+    # @param limit [Integer, nil] maximum number to return, zero or more
+    # @param options [RecordedExpectationsOptions, nil] shapes the returned
+    #   expectations, for example replaying a request recorded with different
+    #   responses in order
     # @return [Array<Expectation>]
-    def retrieve_recorded_expectations(request: nil)
+    def retrieve_recorded_expectations(request: nil, offset: nil, limit: nil, options: nil)
+      unless options.nil? || options.is_a?(RecordedExpectationsOptions)
+        raise ArgumentError, "options must be a RecordedExpectationsOptions, got #{options.inspect}"
+      end
+
+      paging = ExpectationFilter.new
+      paging.with_offset(offset) unless offset.nil?
+      paging.with_limit(limit) unless limit.nil?
       body = request ? JSON.generate(request.to_h) : ''
+      query_params = { 'type' => 'RECORDED_EXPECTATIONS', 'format' => 'JSON' }
+      query_params.merge!(options.to_query_params) unless options.nil?
       status, response_body = do_request(
-        'PUT', '/mockserver/retrieve', body,
-        { 'type' => 'RECORDED_EXPECTATIONS', 'format' => 'JSON' }
+        'PUT', '/mockserver/retrieve', body, query_params.merge(paging.to_query_params)
       )
       if status >= 400
         raise Error, "Failed to retrieve recorded expectations (status=#{status}): #{response_body}"
@@ -1655,7 +1739,8 @@ module MockServer
           context_path: @context_path,
           secure: @secure,
           ca_cert_path: @ca_cert_path,
-          tls_verify: @tls_verify
+          tls_verify: @tls_verify,
+          authorization: @control_plane_authorization
         )
         ws_client.instance_variable_set(:@is_breakpoint_ws, true)
         ws_client.listen
@@ -1672,7 +1757,8 @@ module MockServer
         context_path: @context_path,
         secure: @secure,
         ca_cert_path: @ca_cert_path,
-        tls_verify: @tls_verify
+        tls_verify: @tls_verify,
+        authorization: @control_plane_authorization
       )
 
       case callback_type
@@ -1687,6 +1773,26 @@ module MockServer
       ws_client.client_id
     end
 
+    # @api private
+    def clear_with_filter(request, type, filter)
+      unless filter.is_a?(ExpectationFilter) && filter.selection?
+        raise ArgumentError, 'clear with a filter requires a metadata or unmatched selection; ' \
+                             'use clear(request) to clear without one'
+      end
+      raise ArgumentError, 'offset and limit are not supported for clear' if filter.paging?
+      unless type.nil? || type.to_s.casecmp?('expectations')
+        raise ArgumentError, "clear with a filter only clears expectations, not type #{type.inspect}"
+      end
+
+      body = request ? JSON.generate(request.to_h) : ''
+      status, response_body = do_request(
+        'PUT', '/mockserver/clear', body, { 'type' => 'expectations' }.merge(filter.to_query_params)
+      )
+      raise Error, "Failed to clear (status=#{status}): #{response_body}" if status >= 400
+
+      nil
+    end
+
     # Perform an HTTP request with optional query parameters.
     # @api private
     def do_request(method, path, body = nil, query_params = nil,
@@ -1784,10 +1890,23 @@ module MockServer
         req = Net::HTTP::Put.new(request_path)
       end
       req['Content-Type'] = content_type
+      req['Authorization'] = @control_plane_authorization if @control_plane_authorization
       req.body = body if body
       req
     end
 
+    # @api private
+    def basic_authorization(credentials)
+      return nil if credentials.nil?
+
+      username, password = credentials
+      if username.nil? || username.to_s.empty? || username.to_s.include?(':') || password.nil?
+        raise ArgumentError, 'control_plane_basic_auth needs [username, password] with a username without ":"'
+      end
+
+      "Basic #{Base64.strict_encode64("#{username}:#{password}".encode('UTF-8'))}"
+    end
+
     # @api private
     def execute_request(http, req)
       # Use the block form of #start so the underlying TCP/TLS connection is

data/lib/mockserver/forward_chain_expectation.rb

@@ -37,6 +37,14 @@ module MockServer
       self
     end
 
+    # Set the expectation metadata, used to retrieve or clear it by metadata.
+    # @param metadata [Hash] String (or Symbol) keys to any JSON value
+    # @return [self]
+    def with_metadata(metadata)
+      @expectation.metadata = metadata
+      self
+    end
+
     # Set the response action. Accepts an HttpResponse, HttpTemplate, or
     # a Proc/lambda callback.
     # @param response_or_callback [HttpResponse, HttpTemplate, Proc]

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.