mockserver-client 9.1.0 → 9.2.0

data/lib/mockserver/models.rb

@@ -13,6 +13,7 @@ module MockServer
     'reason_phrase'                  => 'reasonPhrase',
     'keep_alive'                     => 'keepAlive',
     'respond_before_body'            => 'respondBeforeBody',
+    'client_ip'                      => 'clientIp',
     'query_string_parameters'        => 'queryStringParameters',
     'path_parameters'                => 'pathParameters',
     'socket_address'                 => 'socketAddress',
@@ -32,6 +33,7 @@ module MockServer
     'drop_connection'                => 'dropConnection',
     'response_bytes'                 => 'responseBytes',
     'stream_error'                   => 'streamError',
+    'reset_connection'               => 'resetConnection',
     'http_request'                   => 'httpRequest',
     'http_response'                  => 'httpResponse',
     'http_response_template'         => 'httpResponseTemplate',
@@ -48,6 +50,7 @@ module MockServer
     'template_type'                  => 'templateType',
     'template_file'                  => 'templateFile',
     'file_path'                      => 'filePath',
+    'templated_file_path'            => 'templatedFilePath',
     'base64_bytes'                   => 'base64Bytes',
     'not_body'                       => 'not',
     'content_type'                   => 'contentType',
@@ -85,6 +88,7 @@ module MockServer
     'degradation_ramp_millis'        => 'degradationRampMillis',
     'http_class_callback'            => 'httpClassCallback',
     'http_object_callback'           => 'httpObjectCallback',
+    'http_request_template'          => 'httpRequestTemplate',
     'failure_policy'                 => 'failurePolicy',
     'http_responses'                 => 'httpResponses',
     'response_mode'                  => 'responseMode',
@@ -242,7 +246,7 @@ module MockServer
   def self.serialize_key_multi_values(items, key_match_style = nil)
     if key_match_style
       map = { 'keyMatchStyle' => key_match_style }
-      (items || []).each { |item| (map[item.name] ||= []).concat(Array(item.values)) }
+      (items || []).each { |item| (map[item.name] ||= []).concat(serialize_matcher_values(Array(item.values))) }
       return map
     end
     return nil if items.nil?
@@ -251,10 +255,11 @@ module MockServer
   end
 
   # @api private
-  # An httpRequest holding if is a conditional matcher, one naming an OpenAPI
-  # spec (specUrlOrPayload) is an OpenAPI matcher; anything else is an HTTP (or
-  # DNS) request matcher.
+  # An httpRequest holding anyOf is an anyOf matcher, one holding if a
+  # conditional matcher, one naming an OpenAPI spec (specUrlOrPayload) an
+  # OpenAPI matcher; anything else is an HTTP (or DNS) request matcher.
   def self.deserialize_request_definition(data)
+    return AnyOfRequestDefinition.from_hash(data) if data.is_a?(Hash) && data.key?('anyOf')
     return ConditionalRequestDefinition.from_hash(data) if data.is_a?(Hash) && data.key?('if')
     return OpenAPIDefinition.from_hash(data) if data.is_a?(Hash) && data.key?('specUrlOrPayload')
 
@@ -289,10 +294,43 @@ module MockServer
       next item unless item.is_a?(Hash)
 
       item = stringify_keys(item)
-      KeyToMultiValue.new(name: item.fetch('name', ''), values: item.key?('value') ? [item['value']] : item.fetch('values', []))
+      values = item.key?('value') ? [item['value']] : item.fetch('values', [])
+      KeyToMultiValue.new(name: item.fetch('name', ''), values: deserialize_matcher_values(values))
     end
   end
 
+  # @api private
+  # A header, query, path-parameter or cookie value is a plain String, the
+  # nottable / schema object form (kept as a Hash) or a DateTimeMatcher. Only a
+  # Hash holding exactly one date-time operator and nothing but date-time keys
+  # becomes a DateTimeMatcher, so any other object form round-trips unchanged.
+  def self.date_time_matcher_hash?(value)
+    return false unless value.is_a?(Hash)
+
+    keys = value.keys.map(&:to_s)
+    (keys & DateTimeMatcher::OPERATOR_FIELDS).length == 1 && (keys - DateTimeMatcher::FIELDS).empty?
+  end
+
+  # @api private
+  def self.deserialize_matcher_value(value)
+    date_time_matcher_hash?(value) ? DateTimeMatcher.from_hash(stringify_keys(value)) : value
+  end
+
+  # @api private
+  def self.deserialize_matcher_values(values)
+    values.is_a?(Array) ? values.map { |v| deserialize_matcher_value(v) } : deserialize_matcher_value(values)
+  end
+
+  # @api private
+  def self.serialize_matcher_value(value)
+    value.is_a?(DateTimeMatcher) ? value.to_h : value
+  end
+
+  # @api private
+  def self.serialize_matcher_values(values)
+    values.is_a?(Array) ? values.map { |v| serialize_matcher_value(v) } : serialize_matcher_value(values)
+  end
+
   # @api private
   # Serialise a keyToMultiValue collection in the { name => [values] } object form
   # (rather than the [{name, values}] array form). MockServer accepts both wire
@@ -302,7 +340,7 @@ module MockServer
   def self.serialize_key_multi_values_object(items)
     return nil if items.nil?
 
-    items.each_with_object({}) { |item, map| map[item.name] = item.values }
+    items.each_with_object({}) { |item, map| map[item.name] = serialize_matcher_values(item.values) }
   end
 
   # @api private
@@ -311,7 +349,7 @@ module MockServer
 
     if data.is_a?(Hash)
       return data.reject { |k, _v| k == 'keyMatchStyle' }
-                 .map { |k, v| KeyToMultiValue.new(name: k, values: v.is_a?(Array) ? v : [v]) }
+                 .map { |k, v| KeyToMultiValue.new(name: k, values: deserialize_matcher_values(v.is_a?(Array) ? v : [v])) }
     end
 
     data.map do |item|
@@ -332,7 +370,7 @@ module MockServer
     return nil if items.nil?
 
     items.each_with_object({}) do |item, map|
-      map[item.name] = item.values.is_a?(Array) ? item.values.first : item.values
+      map[item.name] = serialize_matcher_value(item.values.is_a?(Array) ? item.values.first : item.values)
     end
   end
 
@@ -341,7 +379,7 @@ module MockServer
     return nil if data.nil?
 
     if data.is_a?(Hash)
-      return data.map { |k, v| KeyToMultiValue.new(name: k, values: v.is_a?(Array) ? v : [v]) }
+      return data.map { |k, v| KeyToMultiValue.new(name: k, values: deserialize_matcher_values(v.is_a?(Array) ? v : [v])) }
     end
 
     # tolerate the legacy array form on read
@@ -515,7 +553,7 @@ module MockServer
     def to_h
       {
         'name'   => @name,
-        'values' => @values
+        'values' => MockServer.serialize_matcher_values(@values)
       }
     end
 
@@ -524,11 +562,136 @@ module MockServer
 
       new(
         name:   data.fetch('name', ''),
-        values: data.fetch('values', [])
+        values: MockServer.deserialize_matcher_values(data.fetch('values', []))
       )
     end
   end
 
+  # A date-time matcher for a header, query-string parameter, path parameter or
+  # cookie value, written on the wire as an object such as
+  # { "after": "now -1 hours", "actualFormat": "rfc1123" }. Instances are frozen;
+  # every with_* method returns a new matcher.
+  #
+  #   request.with_header('X-Issued-At', MockServer::DateTimeMatcher.after('now -1 hours'))
+  class DateTimeMatcher
+    OPERATOR_FIELDS = %w[before after equalToDateTime].freeze
+    FIELDS = (%w[not] + OPERATOR_FIELDS +
+              %w[actualFormat truncateExpected truncateActual applyTruncationLast zone]).freeze
+
+    # +operator+ is the wire field name: 'before', 'after' or 'equalToDateTime'.
+    attr_reader :operator, :expected, :actual_format, :truncate_expected, :truncate_actual,
+                :apply_truncation_last, :zone, :not_matcher
+
+    def initialize(operator:, expected:, actual_format: nil, truncate_expected: nil, truncate_actual: nil,
+                   apply_truncation_last: nil, zone: nil, not_matcher: nil)
+      unless operator.nil? || OPERATOR_FIELDS.include?(operator)
+        raise ArgumentError, "Unknown date-time operator #{operator.inspect}; expected one of #{OPERATOR_FIELDS.join(', ')}"
+      end
+
+      @operator = operator
+      @expected = expected
+      @actual_format = actual_format
+      @truncate_expected = truncate_expected
+      @truncate_actual = truncate_actual
+      @apply_truncation_last = apply_truncation_last
+      @zone = zone
+      @not_matcher = not_matcher
+      freeze
+    end
+
+    def self.before(expected)
+      new(operator: 'before', expected: expected)
+    end
+
+    def self.after(expected)
+      new(operator: 'after', expected: expected)
+    end
+
+    def self.equal_to_date_time(expected)
+      new(operator: 'equalToDateTime', expected: expected)
+    end
+
+    def with_actual_format(actual_format)
+      copy(actual_format: actual_format)
+    end
+
+    def with_truncate_expected(truncate_expected)
+      copy(truncate_expected: truncate_expected)
+    end
+
+    def with_truncate_actual(truncate_actual)
+      copy(truncate_actual: truncate_actual)
+    end
+
+    def with_apply_truncation_last(apply_truncation_last)
+      copy(apply_truncation_last: apply_truncation_last)
+    end
+
+    def with_zone(zone)
+      copy(zone: zone)
+    end
+
+    def with_not(not_matcher)
+      copy(not_matcher: not_matcher)
+    end
+
+    # Field order and omission follow the server: not only when true, every
+    # other optional field only when set.
+    def to_h
+      result = {}
+      result['not'] = true if @not_matcher == true
+      result[@operator] = @expected unless @operator.nil?
+      result['actualFormat'] = @actual_format unless @actual_format.nil?
+      result['truncateExpected'] = @truncate_expected unless @truncate_expected.nil?
+      result['truncateActual'] = @truncate_actual unless @truncate_actual.nil?
+      result['applyTruncationLast'] = @apply_truncation_last unless @apply_truncation_last.nil?
+      result['zone'] = @zone unless @zone.nil?
+      result
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def ==(other)
+      other.is_a?(DateTimeMatcher) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      operators = OPERATOR_FIELDS.select { |field| data.key?(field) }
+      if operators.length > 1
+        raise ArgumentError, "A date-time matcher takes one of #{OPERATOR_FIELDS.join(', ')}, got #{operators.join(', ')}"
+      end
+
+      new(
+        operator:              operators.first,
+        expected:              operators.first && data[operators.first],
+        actual_format:         data['actualFormat'],
+        truncate_expected:     data['truncateExpected'],
+        truncate_actual:       data['truncateActual'],
+        apply_truncation_last: data['applyTruncationLast'],
+        zone:                  data['zone'],
+        not_matcher:           data['not']
+      )
+    end
+
+    private
+
+    def copy(**changes)
+      fields = { operator: @operator, expected: @expected, actual_format: @actual_format,
+                 truncate_expected: @truncate_expected, truncate_actual: @truncate_actual,
+                 apply_truncation_last: @apply_truncation_last, zone: @zone, not_matcher: @not_matcher }
+      self.class.new(**fields.merge(changes))
+    end
+  end
+
   class Body
     # sub_string / match_type / match_numbers_as_strings / json_schema /
     # parameter_styles / xml_schema / parameters / module_name / optional are the
@@ -540,16 +703,19 @@ module MockServer
     # from +string+: the legacy Body.xml(...) factory populates +string+ (pinned by a
     # test), whereas a server-produced XML body serialises its content under +xml+.
     attr_accessor :type, :string, :xml, :json, :regex, :json_path, :xpath, :base64_bytes,
-                  :not_body, :content_type, :charset, :file_path, :template_type, :body_all_of,
+                  :not_body, :content_type, :charset, :file_path, :template_type, :templated_file_path, :body_all_of,
                   :sub_string, :match_type, :match_numbers_as_strings, :json_schema,
-                  :parameter_styles, :xml_schema, :parameters, :module_name, :optional
+                  :parameter_styles, :xml_schema, :parameters, :module_name, :optional, :date_time
 
+    # +date_time+ (a DateTimeMatcher) applies to a JSON_PATH or XPATH body: it then
+    # matches only when a value the JSONPath selects, or the text of a node the
+    # XPath selects, is a date-time satisfying it.
     def initialize(type: nil, string: nil, xml: nil, json: nil, regex: nil, json_path: nil, xpath: nil,
                    base64_bytes: nil, not_body: nil, content_type: nil, charset: nil,
-                   file_path: nil, template_type: nil, body_all_of: nil,
+                   file_path: nil, template_type: nil, templated_file_path: nil, body_all_of: nil,
                    sub_string: nil, match_type: nil, match_numbers_as_strings: nil,
                    json_schema: nil, parameter_styles: nil, xml_schema: nil,
-                   parameters: nil, module_name: nil, optional: nil)
+                   parameters: nil, module_name: nil, optional: nil, date_time: nil)
       @type = type
       @string = string
       @xml = xml
@@ -563,6 +729,7 @@ module MockServer
       @charset = charset
       @file_path = file_path
       @template_type = template_type
+      @templated_file_path = templated_file_path
       @body_all_of = body_all_of
       @sub_string = sub_string
       @match_type = match_type
@@ -573,6 +740,7 @@ module MockServer
       @parameters = parameters
       @module_name = module_name
       @optional = optional
+      @date_time = date_time
     end
 
     def to_h
@@ -584,12 +752,15 @@ module MockServer
       result['regex']        = @regex         unless @regex.nil?
       result['jsonPath']     = @json_path     unless @json_path.nil?
       result['xpath']        = @xpath         unless @xpath.nil?
+      result['dateTime']     = MockServer.serialize_matcher_value(@date_time) unless @date_time.nil?
       result['base64Bytes']  = @base64_bytes  unless @base64_bytes.nil?
       result['not']          = @not_body      unless @not_body.nil?
       result['contentType']  = @content_type  unless @content_type.nil?
       result['charset']      = @charset       unless @charset.nil?
       result['filePath']     = @file_path     unless @file_path.nil?
       result['templateType'] = @template_type unless @template_type.nil?
+      # FILE body: render filePath as a template; omitted unless true.
+      result['templatedFilePath'] = true if @templated_file_path == true
       result['subString']    = @sub_string    unless @sub_string.nil?
       result['matchType']    = @match_type    unless @match_type.nil?
       result['matchNumbersAsStrings'] = @match_numbers_as_strings unless @match_numbers_as_strings.nil?
@@ -623,6 +794,7 @@ module MockServer
         charset:       data['charset'],
         file_path:     data['filePath'],
         template_type: data['templateType'],
+        templated_file_path:      data['templatedFilePath'],
         sub_string:               data['subString'],
         match_type:               data['matchType'],
         match_numbers_as_strings: data['matchNumbersAsStrings'],
@@ -632,6 +804,7 @@ module MockServer
         parameters:               data['parameters'],
         module_name:              data['moduleName'],
         optional:                 data['optional'],
+        date_time:                MockServer.deserialize_matcher_value(data['dateTime']),
         body_all_of:   all_of&.map { |b| MockServer.deserialize_body(b) }
       )
     end
@@ -664,12 +837,12 @@ module MockServer
       new(type: 'ALL_OF', body_all_of: bodies.flatten)
     end
 
-    def self.json_path(value)
-      new(type: 'JSON_PATH', json_path: value)
+    def self.json_path(value, date_time: nil)
+      new(type: 'JSON_PATH', json_path: value, date_time: date_time)
     end
 
-    def self.xpath(value)
-      new(type: 'XPATH', xpath: value)
+    def self.xpath(value, date_time: nil)
+      new(type: 'XPATH', xpath: value, date_time: date_time)
     end
 
     # A JSON_SCHEMA body matcher. +parameter_styles+ is an optional
@@ -700,8 +873,11 @@ module MockServer
       new(type: 'WASM', module_name: module_name)
     end
 
-    def self.file(file_path, content_type: nil, template_type: nil)
-      new(type: 'FILE', file_path: file_path, content_type: content_type, template_type: template_type)
+    # A FILE body. +templated_file_path: true+ (with a +template_type+) also renders
+    # +file_path+ as a template against the request before the file is read.
+    def self.file(file_path, content_type: nil, template_type: nil, templated_file_path: nil)
+      new(type: 'FILE', file_path: file_path, content_type: content_type, template_type: template_type,
+          templated_file_path: templated_file_path)
     end
 
     def self.json_rpc(method_name, params_schema: nil)
@@ -716,6 +892,11 @@ module MockServer
       @template_type = template_type
       self
     end
+
+    def with_templated_file_path(templated_file_path = true)
+      @templated_file_path = templated_file_path
+      self
+    end
   end
 
   class JsonRpcBody
@@ -891,7 +1072,7 @@ module MockServer
     attr_accessor :method, :path, :body, :secure, :protocol, :keep_alive, :respond_before_body,
                   :socket_address, :jwt, :dns_name, :dns_type, :dns_class,
                   :headers_key_match_style, :query_string_parameters_key_match_style,
-                  :path_parameters_key_match_style
+                  :path_parameters_key_match_style, :client_ip
     attr_reader :query_string_parameters, :headers, :cookies, :path_parameters
 
     def initialize(method: nil, path: nil, query_string_parameters: nil, headers: nil,
@@ -899,7 +1080,7 @@ module MockServer
                    respond_before_body: nil, path_parameters: nil, socket_address: nil,
                    jwt: nil, dns_name: nil, dns_type: nil, dns_class: nil,
                    headers_key_match_style: nil, query_string_parameters_key_match_style: nil,
-                   path_parameters_key_match_style: nil)
+                   path_parameters_key_match_style: nil, client_ip: nil)
       @method = method
       @path = path
       self.query_string_parameters = query_string_parameters
@@ -916,6 +1097,7 @@ module MockServer
       @dns_name = dns_name
       @dns_type = dns_type
       @dns_class = dns_class
+      @client_ip = client_ip
       @headers_key_match_style = headers_key_match_style if headers_key_match_style
       @query_string_parameters_key_match_style = query_string_parameters_key_match_style if query_string_parameters_key_match_style
       @path_parameters_key_match_style = path_parameters_key_match_style if path_parameters_key_match_style
@@ -961,6 +1143,7 @@ module MockServer
         'protocol'              => @protocol,
         'keepAlive'             => @keep_alive,
         'respondBeforeBody'     => @respond_before_body,
+        'clientIp'              => @client_ip,
         'pathParameters'        => path_parameters,
         'socketAddress'         => @socket_address&.to_h,
         'jwt'                   => @jwt&.to_h,
@@ -984,6 +1167,7 @@ module MockServer
         protocol:                data['protocol'],
         keep_alive:              data['keepAlive'],
         respond_before_body:     data['respondBeforeBody'],
+        client_ip:               data['clientIp'],
         path_parameters:         MockServer.deserialize_key_multi_values(data['pathParameters']),
         socket_address:          SocketAddress.from_hash(data['socketAddress']),
         jwt:                     Jwt.from_hash(data['jwt']),
@@ -1057,6 +1241,13 @@ module MockServer
       @respond_before_body = respond_before_body
       self
     end
+
+    # Match only requests from this client IP address or CIDR range (e.g. '10.0.0.0/8'); prefix with '!'
+    # to match any other address. It is the TCP peer address, not X-Forwarded-For.
+    def with_client_ip(client_ip)
+      @client_ip = client_ip
+      self
+    end
   end
 
   class ConnectionOptions
@@ -1322,11 +1513,12 @@ module MockServer
   class HttpTemplate
     # response_override (an {HttpResponse}) is applied over the rendered output;
     # response_modifier is the server's responseModifier object, as a Hash.
+    # parameters is a Hash of values the template reads as parameters (parameters.greeting), kept exactly.
     attr_accessor :template_type, :template, :template_file, :delay, :primary,
-                  :response_override, :response_modifier
+                  :response_override, :response_modifier, :parameters
 
     def initialize(template_type: 'JAVASCRIPT', template: nil, template_file: nil, delay: nil, primary: nil,
-                   response_override: nil, response_modifier: nil)
+                   response_override: nil, response_modifier: nil, parameters: nil)
       @template_type = template_type
       @template = template
       @template_file = template_file
@@ -1334,6 +1526,7 @@ module MockServer
       @primary = primary
       @response_override = response_override
       @response_modifier = response_modifier
+      @parameters = parameters
     end
 
     def to_h
@@ -1344,7 +1537,8 @@ module MockServer
         'delay'            => @delay&.to_h,
         'primary'          => @primary,
         'responseOverride' => @response_override&.to_h,
-        'responseModifier' => @response_modifier
+        'responseModifier' => @response_modifier,
+        'parameters'       => (@parameters.nil? || @parameters.empty? ? nil : @parameters)
       })
     end
 
@@ -1358,7 +1552,8 @@ module MockServer
         delay:         Delay.from_hash(data['delay']),
         primary:       data['primary'],
         response_override: HttpResponse.from_hash(data['responseOverride']),
-        response_modifier: data['responseModifier']
+        response_modifier: data['responseModifier'],
+        parameters: data['parameters']
       )
     end
 
@@ -1380,6 +1575,12 @@ module MockServer
       @response_modifier = response_modifier
       self
     end
+
+    # Adds a value the template reads as parameters.<name>.
+    def with_parameter(name, value)
+      @parameters = (@parameters || {}).merge(name.to_s => value)
+      self
+    end
   end
 
   class HttpClassCallback
@@ -1449,10 +1650,14 @@ module MockServer
     # stream_error: reset the matched request stream with this error code (HTTP/2 RST_STREAM /
     # HTTP/3 RESET_STREAM) instead of returning a response; HTTP/1.1 has no stream concept so this
     # falls back to dropping the connection. Takes precedence over drop_connection when both are set.
-    attr_accessor :drop_connection, :response_bytes, :stream_error, :delay, :primary
+    # reset_connection: reset the connection with a TCP RST so the client sees "connection reset by
+    # peer". Takes precedence over stream_error and drop_connection.
+    attr_accessor :drop_connection, :reset_connection, :response_bytes, :stream_error, :delay, :primary
 
-    def initialize(drop_connection: nil, response_bytes: nil, stream_error: nil, delay: nil, primary: nil)
+    def initialize(drop_connection: nil, response_bytes: nil, stream_error: nil, delay: nil, primary: nil,
+                   reset_connection: nil)
       @drop_connection = drop_connection
+      @reset_connection = reset_connection
       @response_bytes = response_bytes
       @stream_error = stream_error
       @delay = delay
@@ -1462,6 +1667,7 @@ module MockServer
     def to_h
       MockServer.strip_none({
         'dropConnection' => @drop_connection,
+        'resetConnection' => @reset_connection,
         'responseBytes'  => @response_bytes,
         'streamError'    => @stream_error,
         'delay'          => @delay&.to_h,
@@ -1474,6 +1680,7 @@ module MockServer
 
       new(
         drop_connection: data['dropConnection'],
+        reset_connection: data['resetConnection'],
         response_bytes:  data['responseBytes'],
         stream_error:    data['streamError'],
         delay:           Delay.from_hash(data['delay']),
@@ -2254,13 +2461,16 @@ module MockServer
   end
 
   class AfterAction
-    # blocking, timeout and failure_policy are only meaningful for before-actions
+    # blocking, timeout and failure_policy are only meaningful for before-actions.
+    # http_request_template (an {HttpTemplate}) renders the webhook request from the triggering
+    # request; escape request values in it and keep them out of its destination.
     attr_accessor :http_request, :http_class_callback, :http_object_callback, :delay,
-                  :blocking, :timeout, :failure_policy
+                  :blocking, :timeout, :failure_policy, :http_request_template
 
     def initialize(http_request: nil, http_class_callback: nil, http_object_callback: nil, delay: nil,
-                   blocking: nil, timeout: nil, failure_policy: nil)
+                   blocking: nil, timeout: nil, failure_policy: nil, http_request_template: nil)
       @http_request = http_request
+      @http_request_template = http_request_template
       @http_class_callback = http_class_callback
       @http_object_callback = http_object_callback
       @delay = delay
@@ -2271,9 +2481,10 @@ module MockServer
 
     def to_h
       MockServer.strip_none({
-        'httpRequest'        => @http_request&.to_h,
-        'httpClassCallback'  => @http_class_callback&.to_h,
-        'httpObjectCallback' => @http_object_callback&.to_h,
+        'httpRequest'         => @http_request&.to_h,
+        'httpRequestTemplate' => @http_request_template&.to_h,
+        'httpClassCallback'   => @http_class_callback&.to_h,
+        'httpObjectCallback'  => @http_object_callback&.to_h,
         'delay'              => @delay&.to_h,
         'blocking'           => @blocking,
         'timeout'            => @timeout&.to_h,
@@ -2291,7 +2502,8 @@ module MockServer
         delay:               Delay.from_hash(data['delay']),
         blocking:            data['blocking'],
         timeout:             Delay.from_hash(data['timeout']),
-        failure_policy:      data['failurePolicy']
+        failure_policy:      data['failurePolicy'],
+        http_request_template: HttpTemplate.from_hash(data['httpRequestTemplate'])
       )
     end
   end
@@ -2710,6 +2922,7 @@ module MockServer
                   :http_responses, :response_mode, :response_weights, :switch_after,
                   :cross_protocol_scenarios, :steps, :capture, :namespace,
                   :scenario_name, :scenario_state, :new_scenario_state, :timestamp
+    attr_reader :metadata
 
     def initialize(id: nil, priority: nil, percentage: nil, http_request: nil, http_response: nil,
                    http_response_template: nil, http_response_class_callback: nil,
@@ -2726,7 +2939,7 @@ module MockServer
                    switch_after: nil, cross_protocol_scenarios: nil, steps: nil,
                    capture: nil, namespace: nil,
                    scenario_name: nil, scenario_state: nil, new_scenario_state: nil,
-                   timestamp: nil)
+                   timestamp: nil, metadata: nil)
       @id = id
       @priority = priority
       @percentage = percentage
@@ -2771,6 +2984,18 @@ module MockServer
       @scenario_state = scenario_state
       @new_scenario_state = new_scenario_state
       @timestamp = timestamp
+      self.metadata = metadata
+    end
+
+    # Free-form labels (owner, ticket, tags, ...) used to retrieve or clear
+    # expectations by metadata. Keys are stored as Strings (Symbol keys are
+    # converted, at any depth); values may be any JSON value, including nil.
+    def metadata=(value)
+      unless value.nil? || value.is_a?(Hash)
+        raise ArgumentError, "metadata must be a Hash, got #{value.class}"
+      end
+
+      @metadata = value.nil? ? nil : MockServer.stringify_keys(value)
     end
 
     # Set the response class-callback action. Accepts either a fully-qualified
@@ -2845,7 +3070,8 @@ module MockServer
         'scenarioName'                 => @scenario_name,
         'scenarioState'                => @scenario_state,
         'newScenarioState'             => @new_scenario_state,
-        'timestamp'                    => @timestamp
+        'timestamp'                    => @timestamp,
+        'metadata'                     => @metadata.nil? || @metadata.empty? ? nil : @metadata
       })
     end
 
@@ -2907,11 +3133,232 @@ module MockServer
         scenario_name:                   data['scenarioName'],
         scenario_state:                  data['scenarioState'],
         new_scenario_state:              data['newScenarioState'],
-        timestamp:                       data['timestamp']
+        timestamp:                       data['timestamp'],
+        metadata:                        data['metadata']
       )
     end
   end
 
+  # Selects expectations to retrieve or clear by metadata, by whether they have
+  # ever matched a request, and pages a retrieved list. Sent as query parameters
+  # on +PUT /mockserver/retrieve+ and +PUT /mockserver/clear+; every selection
+  # that is set must hold. Invalid arguments raise ArgumentError immediately, so
+  # a broken filter can never be sent as "no filter" (which, on clear, clears
+  # every expectation).
+  #
+  #   MockServer::ExpectationFilter.new.with_metadata('owner', 'team-a').with_limit(10)
+  class ExpectationFilter
+    # Pass as the value to {#with_metadata} to select a stored JSON null; Ruby
+    # +nil+ is rejected so it can never read as "any value".
+    JSON_NULL = Object.new.tap do |null|
+      def null.inspect
+        'MockServer::ExpectationFilter::JSON_NULL'
+      end
+    end.freeze
+
+    attr_reader :metadata_key, :metadata_value, :metadata_json_path, :unmatched, :offset, :limit
+
+    def initialize
+      @metadata_key = nil
+      @metadata_value = nil
+      @metadata_json_path = nil
+      @unmatched = false
+      @offset = nil
+      @limit = nil
+    end
+
+    # Select expectations whose metadata has +key+ with a value equal to
+    # +value+. A String is sent as text; any other value (number, boolean,
+    # Array, Hash, {JSON_NULL}) is sent as its compact JSON.
+    # @raise [ArgumentError] if +key+ is blank or +value+ is nil
+    def with_metadata(key, value)
+      if value.nil?
+        raise ArgumentError, 'the metadata value must not be nil; use with_metadata_key(key) to select any value, ' \
+                             'or ExpectationFilter::JSON_NULL to select a JSON null'
+      end
+
+      @metadata_key = ExpectationFilter.require_not_blank(key, 'metadata key')
+      @metadata_value = ExpectationFilter.encode_value(value)
+      self
+    end
+
+    # Select expectations whose metadata has +key+, with any value.
+    # @raise [ArgumentError] if +key+ is blank
+    def with_metadata_key(key)
+      @metadata_key = ExpectationFilter.require_not_blank(key, 'metadata key')
+      @metadata_value = nil
+      self
+    end
+
+    # Select expectations whose metadata object the JSONPath selects at least
+    # one value from, e.g. <tt>$[?(@.owner == 'team-a')]</tt>.
+    # @raise [ArgumentError] if +json_path+ is blank
+    def with_metadata_json_path(json_path)
+      @metadata_json_path = ExpectationFilter.require_not_blank(json_path, 'metadata JSONPath')
+      self
+    end
+
+    # Select only expectations that have not matched any request.
+    def with_unmatched(unmatched = true)
+      unless [true, false].include?(unmatched)
+        raise ArgumentError, "unmatched must be true or false, got #{unmatched.inspect}"
+      end
+
+      @unmatched = unmatched
+      self
+    end
+
+    # Skip this many results (retrieve only).
+    def with_offset(offset)
+      @offset = ExpectationFilter.require_non_negative(offset, 'offset')
+      self
+    end
+
+    # Return at most this many results (retrieve only).
+    def with_limit(limit)
+      @limit = ExpectationFilter.require_non_negative(limit, 'limit')
+      self
+    end
+
+    # @return [Boolean] true when a metadata or unmatched selection is set
+    def selection?
+      !@metadata_key.nil? || !@metadata_json_path.nil? || @unmatched
+    end
+
+    # @return [Boolean] true when offset or limit is set
+    def paging?
+      !@offset.nil? || !@limit.nil?
+    end
+
+    # The query parameters for this filter, names and values exactly as sent.
+    # @return [Hash{String => String}]
+    def to_query_params
+      params = {}
+      unless @metadata_key.nil?
+        params['metadataKey'] = @metadata_key
+        params['metadataValue'] = @metadata_value unless @metadata_value.nil?
+      end
+      params['metadataJsonPath'] = @metadata_json_path unless @metadata_json_path.nil?
+      params['unmatched'] = 'true' if @unmatched
+      params['offset'] = @offset.to_s unless @offset.nil?
+      params['limit'] = @limit.to_s unless @limit.nil?
+      params
+    end
+
+    # @api private
+    def self.require_not_blank(value, description)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError, "the #{description} must be a String, got #{value.inspect}"
+      end
+      raise ArgumentError, "the #{description} must not be blank" if value.to_s.strip.empty?
+
+      value.to_s
+    end
+
+    # @api private
+    def self.require_non_negative(value, description)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "#{description} must be an Integer of zero or more, got #{value.inspect}"
+      end
+
+      value
+    end
+
+    # @api private
+    def self.encode_value(value)
+      return 'null' if value.equal?(JSON_NULL)
+      return value if value.is_a?(String)
+
+      JSON.generate(MockServer.stringify_keys(value))
+    rescue JSON::GeneratorError => e
+      raise ArgumentError, "the metadata value #{value.inspect} cannot be sent as JSON: #{e.message}"
+    end
+  end
+
+  # Options that shape the expectations returned by
+  # {Client#retrieve_recorded_expectations}. Sent as query parameters on
+  # +PUT /mockserver/retrieve?type=RECORDED_EXPECTATIONS+; each option is off
+  # unless set. Invalid arguments raise ArgumentError immediately, so nothing
+  # is sent.
+  #
+  #   MockServer::RecordedExpectationsOptions.new
+  #     .with_repeats_as_scenarios(true)
+  #     .with_capture_headers('X-Tenant')
+  #     .with_extract_bodies_larger_than(1024)
+  class RecordedExpectationsOptions
+    attr_reader :consolidate, :parameterize, :repeats_as_scenarios, :capture_headers, :extract_bodies_larger_than
+
+    def initialize
+      @consolidate = nil
+      @parameterize = nil
+      @repeats_as_scenarios = nil
+      @capture_headers = nil
+      @extract_bodies_larger_than = nil
+    end
+
+    # Collapse recorded exchanges that share a request shape into one
+    # reusable, unlimited-times expectation.
+    def with_consolidate(consolidate = true)
+      @consolidate = RecordedExpectationsOptions.require_boolean(consolidate, 'consolidate')
+      self
+    end
+
+    # Also generalise volatile path, query, header and body values into
+    # matchers (implies consolidate).
+    def with_parameterize(parameterize = true)
+      @parameterize = RecordedExpectationsOptions.require_boolean(parameterize, 'parameterize')
+      self
+    end
+
+    # Replay a request recorded several times with different responses in the
+    # recorded order, then keep returning the last one.
+    def with_repeats_as_scenarios(repeats_as_scenarios = true)
+      @repeats_as_scenarios = RecordedExpectationsOptions.require_boolean(repeats_as_scenarios, 'repeats_as_scenarios')
+      self
+    end
+
+    # Keep only these request headers (case-insensitive) in each recorded
+    # matcher; no names keeps none.
+    # @raise [ArgumentError] if a name is blank or contains a comma
+    def with_capture_headers(*header_names)
+      header_names.each do |name|
+        unless name.is_a?(String) && !name.strip.empty? && !name.include?(',')
+          raise ArgumentError,
+                "each capture header must be a non-blank header name without a comma, got #{name.inspect}"
+        end
+      end
+      @capture_headers = header_names
+      self
+    end
+
+    # Write each response body larger than this many bytes to the server's
+    # +recordedBodyFilesDirectory+ and return a FILE body that points at it.
+    # @raise [ArgumentError] unless an Integer of zero or more
+    def with_extract_bodies_larger_than(threshold_bytes)
+      @extract_bodies_larger_than = ExpectationFilter.require_non_negative(threshold_bytes, 'extract_bodies_larger_than')
+      self
+    end
+
+    # The query parameters for these options, names and values exactly as sent.
+    # @return [Hash{String => String}]
+    def to_query_params
+      params = {}
+      params['consolidate'] = 'true' if @consolidate
+      params['parameterize'] = 'true' if @parameterize
+      params['repeatsAsScenarios'] = 'true' if @repeats_as_scenarios
+      params['captureHeaders'] = @capture_headers.join(',') unless @capture_headers.nil?
+      params['extractBodiesLargerThan'] = @extract_bodies_larger_than.to_s unless @extract_bodies_larger_than.nil?
+      params
+    end
+
+    # @api private
+    def self.require_boolean(value, description)
+      raise ArgumentError, "#{description} must be true or false, got #{value.inspect}" unless [true, false].include?(value)
+
+      value
+    end
+  end
+
   # An OpenAPI request matcher: as an expectation's or verification's
   # httpRequest it matches the requests an OpenAPI operation accepts.
   class OpenAPIDefinition
@@ -2983,6 +3430,37 @@ module MockServer
     end
   end
 
+  # A logical OR of request matchers, written as an httpRequest holding an
+  # anyOf array. It matches a request when any branch matches it, trying them
+  # in order. Each branch is an HttpRequest, an OpenAPIDefinition, a
+  # ConditionalRequestDefinition or another AnyOfRequestDefinition.
+  class AnyOfRequestDefinition
+    # not_any_of inverts the match (the server's +not+ field): it then matches
+    # when no branch does.
+    attr_accessor :any_of, :not_any_of
+
+    def initialize(any_of: [], not_any_of: nil)
+      @any_of = any_of
+      @not_any_of = not_any_of
+    end
+
+    def to_h
+      MockServer.strip_none({
+        'not'   => @not_any_of,
+        'anyOf' => (@any_of || []).map(&:to_h)
+      })
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        any_of:     (data['anyOf'] || []).map { |branch| MockServer.deserialize_request_definition(branch) },
+        not_any_of: data['not']
+      )
+    end
+  end
+
   class OpenAPIExpectation
     attr_accessor :spec_url_or_payload, :operations_and_responses
 
@@ -3680,20 +4158,40 @@ module MockServer
     end
   end
 
+  # For an anyOf request matcher that does not match the request, which branch
+  # came closest (+closest_branch+, 0-based, the earlier on a tie) and how each
+  # differed: each of +branches+ has branch, matches, differingFieldCount and
+  # differingFields.
+  class AnyOfBranchComparison
+    attr_reader :closest_branch, :branches
+
+    def initialize(closest_branch: nil, branches: [])
+      @closest_branch = closest_branch
+      @branches = branches
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(closest_branch: data['closestBranch'], branches: data['branches'] || [])
+    end
+  end
+
   # One expectation as explain, debug_mismatch or explain_unmatched evaluated
   # it. The matched expectation has no +reason+; a skipped or shadowed one has
   # a +reason+ (NAMESPACE, INACTIVE, FIELDS_DIFFER, NOT_OPERATOR, CONVERSATION,
   # SCENARIO_STATE, PERCENTAGE or LOWER_PRIORITY) and an +explanation+.
-  # +suggested_fix+ is set only by explain_unmatched with +suggest_fixes+.
+  # +suggested_fix+ is set only by explain_unmatched with +suggest_fixes+;
+  # +any_of+ only for an anyOf request matcher that does not match.
   class ExplainedExpectation
     attr_reader :expectation_id, :expectation_method, :expectation_path, :position, :priority,
                 :reason, :explanation, :matches, :matched_field_count, :total_field_count,
-                :differing_field_count, :differences, :remediation, :suggested_fix
+                :differing_field_count, :differences, :remediation, :suggested_fix, :any_of
 
     def initialize(expectation_id: nil, expectation_method: nil, expectation_path: nil, position: nil,
                    priority: nil, reason: nil, explanation: nil, matches: nil, matched_field_count: nil,
                    total_field_count: nil, differing_field_count: nil, differences: {}, remediation: {},
-                   suggested_fix: nil)
+                   suggested_fix: nil, any_of: nil)
       @expectation_id = expectation_id
       @expectation_method = expectation_method
       @expectation_path = expectation_path
@@ -3708,6 +4206,7 @@ module MockServer
       @differences = differences
       @remediation = remediation
       @suggested_fix = suggested_fix
+      @any_of = any_of
     end
 
     def self.from_hash(data)
@@ -3727,7 +4226,8 @@ module MockServer
         differing_field_count: data['differingFieldCount'],
         differences:           data['differences'] || {},
         remediation:           data['remediation'] || {},
-        suggested_fix:         SuggestedFix.from_hash(data['suggestedFix'])
+        suggested_fix:         SuggestedFix.from_hash(data['suggestedFix']),
+        any_of:                AnyOfBranchComparison.from_hash(data['anyOf'])
       )
     end