mockserver-client 9.1.0 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b414bb7cc138b2e2a46b674e67743d1145bc004bc7a62be5d25e75fab95409f
-  data.tar.gz: 8d11ed79c2d777ab576c4181e9cb2c6b2730c352afc532d5df4070e9accddaf6
+  metadata.gz: 02d995291d2bc1c0c4b875711f568d604c4e6af009952512109b44ff49fa2fed
+  data.tar.gz: 455d49792d3fec33d41dd66eade0ca64e5ee4049306566c411da1008a431b30a
 SHA512:
-  metadata.gz: f0b346b83cbc825456b2dc85b6b1462e1fa3610f779f9037e77ba2f40f4a780e9c64a793d80df95dbceb0b7d67b57805cce281d75fa8ba36114edb7e35851892
-  data.tar.gz: 5bde30af6fe4e94208ac4a275e52309d77e1d78a94d74ce152c993a656e8db00d98adc88f9556c21f2c1d3939b180e2f7ac9588195a4462a9a99ab035883eaac
+  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.1.0')
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '9.2.0')
 ```
 
 ### API reference

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
@@ -1174,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
@@ -1192,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}"
@@ -1656,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
@@ -1673,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
@@ -1688,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,
@@ -1785,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]