mockserver-client 7.6.0 → 9.0.0

data/lib/mockserver/models.rb

@@ -131,6 +131,44 @@ module MockServer
     hash.reject { |_k, v| v.nil? }
   end
 
+  # @api private
+  def self.symbol_keys?(value)
+    case value
+    when Hash then value.any? { |k, v| k.is_a?(Symbol) || symbol_keys?(v) }
+    when Array then value.any? { |v| symbol_keys?(v) }
+    else false
+    end
+  end
+
+  # @api private
+  # Returns a copy of +value+ with every Symbol hash key, at any depth, turned
+  # into a String; values and other keys are unchanged.
+  def self.stringify_keys(value)
+    case value
+    when Hash then value.each_with_object({}) { |(k, v), h| h[k.is_a?(Symbol) ? k.to_s : k] = stringify_keys(v) }
+    when Array then value.map { |v| stringify_keys(v) }
+    else value
+    end
+  end
+
+  # @api private
+  # Prepended to every model's from_hash. A hash literal written with JSON-style
+  # keys ({ "httpRequest": {...} }) has Symbol keys in Ruby, while the models read
+  # the String keys JSON.parse produces, so normalise before reading. Only the
+  # outermost call scans: nested calls receive parts of the normalised hash.
+  module SymbolKeyTolerantFromHash
+    def from_hash(data)
+      return super if Thread.current[:mockserver_from_hash_normalised]
+
+      Thread.current[:mockserver_from_hash_normalised] = true
+      begin
+        super(MockServer.symbol_keys?(data) ? MockServer.stringify_keys(data) : data)
+      ensure
+        Thread.current[:mockserver_from_hash_normalised] = false
+      end
+    end
+  end
+
   # @api private
   # Coerce a class-callback value into an {HttpClassCallback}. Accepts:
   #   * +nil+              -> +nil+
@@ -199,12 +237,62 @@ module MockServer
   end
 
   # @api private
-  def self.serialize_key_multi_values(items)
+  # With a key_match_style (MATCHING_KEY or SUB_SET) the collection is written in
+  # the object form, the only form that carries keyMatchStyle.
+  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)) }
+      return map
+    end
     return nil if items.nil?
 
     items.map(&:to_h)
   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.
+  def self.deserialize_request_definition(data)
+    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')
+
+    HttpRequest.from_hash(data)
+  end
+
+  # @api private
+  def self.key_match_style(data)
+    data['keyMatchStyle'] || data[:keyMatchStyle] if data.is_a?(Hash)
+  end
+
+  # @api private
+  # Accept a keyToMultiValue collection as the server's JSON does, so headers,
+  # query parameters and trailers can be given as { name => values }, as
+  # [{ name:, values: }] or as KeyToMultiValue objects.
+  def self.coerce_key_multi_values(value)
+    return value if value.nil?
+    return deserialize_key_multi_values(stringify_keys(value)) if value.is_a?(Hash)
+    raise TypeError, "Expected a Hash or an Array of KeyToMultiValue, got #{value.class.name}" unless value.is_a?(Array)
+
+    value.map { |item| item.is_a?(Hash) ? KeyToMultiValue.from_hash(stringify_keys(item)) : item }
+  end
+
+  # @api private
+  # Cookies as { name => value }, [{ name:, value: }] or KeyToMultiValue objects.
+  def self.coerce_cookies(value)
+    return value if value.nil?
+    return deserialize_cookies(stringify_keys(value)) if value.is_a?(Hash)
+    raise TypeError, "Expected a Hash or an Array of KeyToMultiValue, got #{value.class.name}" unless value.is_a?(Array)
+
+    value.map do |item|
+      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', []))
+    end
+  end
+
   # @api private
   # Serialise a keyToMultiValue collection in the { name => [values] } object form
   # (rather than the [{name, values}] array form). MockServer accepts both wire
@@ -222,7 +310,8 @@ 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.reject { |k, _v| k == 'keyMatchStyle' }
+                 .map { |k, v| KeyToMultiValue.new(name: k, values: v.is_a?(Array) ? v : [v]) }
     end
 
     data.map do |item|
@@ -304,19 +393,25 @@ module MockServer
   end
 
   class Delay
-    attr_accessor :time_unit, :value, :distribution
+    # template is rendered against the request and read as milliseconds (falling
+    # back to time_unit/value); template_type is VELOCITY or MUSTACHE.
+    attr_accessor :time_unit, :value, :distribution, :template, :template_type
 
-    def initialize(time_unit: 'MILLISECONDS', value: 0, distribution: nil)
+    def initialize(time_unit: 'MILLISECONDS', value: 0, distribution: nil, template: nil, template_type: nil)
       @time_unit = time_unit
       @value = value
       @distribution = distribution
+      @template = template
+      @template_type = template_type
     end
 
     def to_h
       MockServer.strip_none({
         'timeUnit'     => @time_unit,
         'value'        => @value,
-        'distribution' => @distribution&.to_h
+        'distribution' => @distribution&.to_h,
+        'template'     => @template,
+        'templateType' => @template_type
       })
     end
 
@@ -325,9 +420,11 @@ module MockServer
 
       dist_data = data['distribution']
       new(
-        time_unit:    data.fetch('timeUnit', 'MILLISECONDS'),
-        value:        data.fetch('value', 0),
-        distribution: dist_data ? DelayDistribution.from_hash(dist_data) : nil
+        time_unit:     data.fetch('timeUnit', 'MILLISECONDS'),
+        value:         data.fetch('value', 0),
+        distribution:  dist_data ? DelayDistribution.from_hash(dist_data) : nil,
+        template:      data['template'],
+        template_type: data['templateType']
       )
     end
   end
@@ -786,46 +883,85 @@ module MockServer
     # protocol pins the transport the matcher requires
     # (org.mockserver.model.Protocol: HTTP_1_1 / HTTP_2 / HTTP_3 / SOCKS / ...),
     # round-tripping the httpRequest +protocol+ wire key.
-    attr_accessor :method, :path, :query_string_parameters, :headers,
-                  :cookies, :body, :secure, :protocol, :keep_alive, :respond_before_body,
-                  :path_parameters, :socket_address, :jwt,
-                  :dns_name, :dns_type, :dns_class
+    # headers, query_string_parameters, path_parameters and cookies also accept a
+    # Hash ({ name => values }) or an Array of Hashes, as in the server's JSON.
+    # *_key_match_style is SUB_SET (the server's default: one value of a key
+    # must match) or MATCHING_KEY (every value must); a Hash with a
+    # 'keyMatchStyle' key sets it too.
+    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
+    attr_reader :query_string_parameters, :headers, :cookies, :path_parameters
 
     def initialize(method: nil, path: nil, query_string_parameters: nil, headers: nil,
                    cookies: nil, body: nil, secure: nil, protocol: nil, keep_alive: nil,
                    respond_before_body: nil, path_parameters: nil, socket_address: nil,
-                   jwt: nil, dns_name: nil, dns_type: nil, dns_class: 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)
       @method = method
       @path = path
-      @query_string_parameters = query_string_parameters
-      @headers = headers
-      @cookies = cookies
+      self.query_string_parameters = query_string_parameters
+      self.headers = headers
+      self.cookies = cookies
       @body = body
       @secure = secure
       @protocol = protocol
       @keep_alive = keep_alive
       @respond_before_body = respond_before_body
-      @path_parameters = path_parameters
+      self.path_parameters = path_parameters
       @socket_address = socket_address
       @jwt = jwt
       @dns_name = dns_name
       @dns_type = dns_type
       @dns_class = dns_class
+      @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
+    end
+
+    def headers=(value)
+      style = MockServer.key_match_style(value)
+      @headers_key_match_style = style if style
+      @headers = MockServer.coerce_key_multi_values(value)
+    end
+
+    def query_string_parameters=(value)
+      style = MockServer.key_match_style(value)
+      @query_string_parameters_key_match_style = style if style
+      @query_string_parameters = MockServer.coerce_key_multi_values(value)
+    end
+
+    def path_parameters=(value)
+      style = MockServer.key_match_style(value)
+      @path_parameters_key_match_style = style if style
+      @path_parameters = MockServer.coerce_key_multi_values(value)
+    end
+
+    def cookies=(value)
+      @cookies = MockServer.coerce_cookies(value)
     end
 
     def to_h
+      path_parameters = if @path_parameters_key_match_style
+                          MockServer.serialize_key_multi_values(@path_parameters, @path_parameters_key_match_style)
+                        else
+                          MockServer.serialize_key_multi_values_object(@path_parameters)
+                        end
       MockServer.strip_none({
         'method'                => @method,
         'path'                  => @path,
-        'queryStringParameters' => MockServer.serialize_key_multi_values(@query_string_parameters),
-        'headers'               => MockServer.serialize_key_multi_values(@headers),
+        'queryStringParameters' => MockServer.serialize_key_multi_values(@query_string_parameters,
+                                                                         @query_string_parameters_key_match_style),
+        'headers'               => MockServer.serialize_key_multi_values(@headers, @headers_key_match_style),
         'cookies'               => MockServer.serialize_cookies(@cookies),
         'body'                  => MockServer.serialize_body(@body),
         'secure'                => @secure,
         'protocol'              => @protocol,
         'keepAlive'             => @keep_alive,
         'respondBeforeBody'     => @respond_before_body,
-        'pathParameters'        => MockServer.serialize_key_multi_values_object(@path_parameters),
+        'pathParameters'        => path_parameters,
         'socketAddress'         => @socket_address&.to_h,
         'jwt'                   => @jwt&.to_h,
         'dnsName'               => @dns_name,
@@ -853,7 +989,10 @@ module MockServer
         jwt:                     Jwt.from_hash(data['jwt']),
         dns_name:                data['dnsName'],
         dns_type:                data['dnsType'],
-        dns_class:               data['dnsClass']
+        dns_class:               data['dnsClass'],
+        headers_key_match_style: MockServer.key_match_style(data['headers']),
+        query_string_parameters_key_match_style: MockServer.key_match_style(data['queryStringParameters']),
+        path_parameters_key_match_style: MockServer.key_match_style(data['pathParameters'])
       )
     end
 
@@ -968,23 +1107,74 @@ module MockServer
     end
   end
 
+  # Serves +fail_response+ for the first +fail_times+ matches, then the real
+  # response; +idempotency_header+ keys an independent window per header value.
+  class RecoverAfter
+    attr_accessor :fail_times, :fail_response, :idempotency_header
+
+    def initialize(fail_times: nil, fail_response: nil, idempotency_header: nil)
+      @fail_times = fail_times
+      @fail_response = fail_response
+      @idempotency_header = idempotency_header
+    end
+
+    def to_h
+      MockServer.strip_none({
+        'failTimes'         => @fail_times,
+        'failResponse'      => @fail_response&.to_h,
+        'idempotencyHeader' => @idempotency_header
+      })
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        fail_times:         data['failTimes'],
+        fail_response:      HttpResponse.from_hash(data['failResponse']),
+        idempotency_header: data['idempotencyHeader']
+      )
+    end
+  end
+
   class HttpResponse
     # trailers carries HTTP trailing headers (org.mockserver.model.Headers on the
     # response's +trailers+ slot), a keyToMultiValue collection like +headers+.
-    attr_accessor :status_code, :reason_phrase, :headers, :cookies,
-                  :body, :delay, :connection_options, :trailers, :primary
+    # status_code_range serves a status from a range such as "2xx";
+    # generate_from_schema is a JSON schema the body is generated from.
+    # headers, trailers and cookies also accept a Hash or an Array of Hashes,
+    # as in the server's JSON (see HttpRequest).
+    attr_accessor :status_code, :reason_phrase, :body, :delay, :connection_options, :primary,
+                  :status_code_range, :generate_from_schema, :recover_after
+    attr_reader :headers, :cookies, :trailers
 
     def initialize(status_code: nil, reason_phrase: nil, headers: nil, cookies: nil,
-                   body: nil, delay: nil, connection_options: nil, trailers: nil, primary: nil)
+                   body: nil, delay: nil, connection_options: nil, trailers: nil, primary: nil,
+                   status_code_range: nil, generate_from_schema: nil, recover_after: nil)
       @status_code = status_code
       @reason_phrase = reason_phrase
-      @headers = headers
-      @cookies = cookies
+      self.headers = headers
+      self.cookies = cookies
       @body = body
       @delay = delay
       @connection_options = connection_options
-      @trailers = trailers
+      self.trailers = trailers
       @primary = primary
+      @status_code_range = status_code_range
+      @generate_from_schema = generate_from_schema
+      @recover_after = recover_after
+    end
+
+    def headers=(value)
+      @headers = MockServer.coerce_key_multi_values(value)
+    end
+
+    def trailers=(value)
+      @trailers = MockServer.coerce_key_multi_values(value)
+    end
+
+    def cookies=(value)
+      @cookies = MockServer.coerce_cookies(value)
     end
 
     def to_h
@@ -997,7 +1187,10 @@ module MockServer
         'delay'            => @delay&.to_h,
         'connectionOptions' => @connection_options&.to_h,
         'trailers'         => MockServer.serialize_key_multi_values(@trailers),
-        'primary'          => @primary
+        'primary'          => @primary,
+        'statusCodeRange'  => @status_code_range,
+        'generateFromSchema' => @generate_from_schema,
+        'recoverAfter'     => @recover_after&.to_h
       })
     end
 
@@ -1013,7 +1206,10 @@ module MockServer
         delay:             Delay.from_hash(data['delay']),
         connection_options: ConnectionOptions.from_hash(data['connectionOptions']),
         trailers:          MockServer.deserialize_key_multi_values(data['trailers']),
-        primary:           data['primary']
+        primary:           data['primary'],
+        status_code_range: data['statusCodeRange'],
+        generate_from_schema: data['generateFromSchema'],
+        recover_after:     RecoverAfter.from_hash(data['recoverAfter'])
       )
     end
 
@@ -1068,6 +1264,21 @@ module MockServer
       @reason_phrase = reason_phrase
       self
     end
+
+    def with_status_code_range(status_code_range)
+      @status_code_range = status_code_range
+      self
+    end
+
+    def with_generate_from_schema(schema)
+      @generate_from_schema = schema
+      self
+    end
+
+    def with_recover_after(recover_after)
+      @recover_after = recover_after
+      self
+    end
   end
 
   class HttpForward
@@ -1109,23 +1320,31 @@ module MockServer
   end
 
   class HttpTemplate
-    attr_accessor :template_type, :template, :template_file, :delay, :primary
+    # response_override (an {HttpResponse}) is applied over the rendered output;
+    # response_modifier is the server's responseModifier object, as a Hash.
+    attr_accessor :template_type, :template, :template_file, :delay, :primary,
+                  :response_override, :response_modifier
 
-    def initialize(template_type: 'JAVASCRIPT', template: nil, template_file: nil, delay: nil, primary: nil)
+    def initialize(template_type: 'JAVASCRIPT', template: nil, template_file: nil, delay: nil, primary: nil,
+                   response_override: nil, response_modifier: nil)
       @template_type = template_type
       @template = template
       @template_file = template_file
       @delay = delay
       @primary = primary
+      @response_override = response_override
+      @response_modifier = response_modifier
     end
 
     def to_h
       MockServer.strip_none({
-        'templateType' => @template_type,
-        'template'     => @template,
-        'templateFile' => @template_file,
-        'delay'        => @delay&.to_h,
-        'primary'      => @primary
+        'templateType'     => @template_type,
+        'template'         => @template,
+        'templateFile'     => @template_file,
+        'delay'            => @delay&.to_h,
+        'primary'          => @primary,
+        'responseOverride' => @response_override&.to_h,
+        'responseModifier' => @response_modifier
       })
     end
 
@@ -1137,7 +1356,9 @@ module MockServer
         template:      data['template'],
         template_file: data['templateFile'],
         delay:         Delay.from_hash(data['delay']),
-        primary:       data['primary']
+        primary:       data['primary'],
+        response_override: HttpResponse.from_hash(data['responseOverride']),
+        response_modifier: data['responseModifier']
       )
     end
 
@@ -1149,6 +1370,16 @@ module MockServer
       @template_file = template_file
       self
     end
+
+    def with_response_override(response_override)
+      @response_override = response_override
+      self
+    end
+
+    def with_response_modifier(response_modifier)
+      @response_modifier = response_modifier
+      self
+    end
   end
 
   class HttpClassCallback
@@ -1256,16 +1487,27 @@ module MockServer
   end
 
   class HttpOverrideForwardedRequest
+    # request_override (an {HttpRequest}) is merged over the forwarded request and
+    # response_override (an {HttpResponse}) over the response; response_template
+    # (an {HttpTemplate}) renders the response from the request and the forwarded
+    # response. http_request / http_response are the older names of the overrides;
+    # the server accepts either set, not both.
     attr_accessor :http_request, :http_response, :delay,
-                  :request_modifier, :response_modifier, :primary
+                  :request_override, :request_modifier,
+                  :response_override, :response_modifier, :response_template, :primary
 
     def initialize(http_request: nil, http_response: nil, delay: nil,
-                   request_modifier: nil, response_modifier: nil, primary: nil)
+                   request_override: nil, request_modifier: nil,
+                   response_override: nil, response_modifier: nil, response_template: nil,
+                   primary: nil)
       @http_request = http_request
       @http_response = http_response
       @delay = delay
+      @request_override = request_override
       @request_modifier = request_modifier
+      @response_override = response_override
       @response_modifier = response_modifier
+      @response_template = response_template
       @primary = primary
     end
 
@@ -1274,8 +1516,11 @@ module MockServer
         'httpRequest'      => @http_request&.to_h,
         'httpResponse'     => @http_response&.to_h,
         'delay'            => @delay&.to_h,
+        'requestOverride'  => @request_override&.to_h,
         'requestModifier'  => @request_modifier,
+        'responseOverride' => @response_override&.to_h,
         'responseModifier' => @response_modifier,
+        'responseTemplate' => @response_template&.to_h,
         'primary'          => @primary
       })
     end
@@ -1287,8 +1532,11 @@ module MockServer
         http_request:      HttpRequest.from_hash(data['httpRequest']),
         http_response:     HttpResponse.from_hash(data['httpResponse']),
         delay:             Delay.from_hash(data['delay']),
+        request_override:  HttpRequest.from_hash(data['requestOverride']),
         request_modifier:  data['requestModifier'],
+        response_override: HttpResponse.from_hash(data['responseOverride']),
         response_modifier: data['responseModifier'],
+        response_template: HttpTemplate.from_hash(data['responseTemplate']),
         primary:           data['primary']
       )
     end
@@ -1296,6 +1544,21 @@ module MockServer
     def self.forward_overridden_request(request: nil)
       new(http_request: request)
     end
+
+    def with_request_override(request_override)
+      @request_override = request_override
+      self
+    end
+
+    def with_response_override(response_override)
+      @response_override = response_override
+      self
+    end
+
+    def with_response_template(response_template)
+      @response_template = response_template
+      self
+    end
   end
 
   class HttpRequestAndHttpResponse
@@ -1376,15 +1639,18 @@ module MockServer
   end
 
   class HttpSseResponse
-    attr_accessor :status_code, :headers, :events, :close_connection, :delay, :primary
+    # template_type renders each event with that engine (VELOCITY / JAVASCRIPT / MUSTACHE).
+    attr_accessor :status_code, :headers, :events, :close_connection, :delay, :primary, :template_type
 
-    def initialize(status_code: nil, headers: nil, events: nil, close_connection: nil, delay: nil, primary: nil)
+    def initialize(status_code: nil, headers: nil, events: nil, close_connection: nil, delay: nil, primary: nil,
+                   template_type: nil)
       @status_code = status_code
       @headers = headers
       @events = events
       @close_connection = close_connection
       @delay = delay
       @primary = primary
+      @template_type = template_type
     end
 
     def to_h
@@ -1395,6 +1661,7 @@ module MockServer
       result['closeConnection'] = @close_connection unless @close_connection.nil?
       result['delay'] = @delay.to_h if @delay
       result['primary'] = @primary unless @primary.nil?
+      result['templateType'] = @template_type unless @template_type.nil?
       result
     end
 
@@ -1409,7 +1676,8 @@ module MockServer
         events:           events,
         close_connection: data['closeConnection'],
         delay:            Delay.from_hash(data['delay']),
-        primary:          data['primary']
+        primary:          data['primary'],
+        template_type:    data['templateType']
       )
     end
   end
@@ -1478,18 +1746,63 @@ module MockServer
     end
   end
 
+  # Matches a graphql-transport-ws subscribe message against this GraphQL query.
+  # +type+ is an optional body-type discriminator; only "GRAPHQL" is meaningful.
+  class GraphQLSubscriptionFilter
+    attr_accessor :query, :operation_name, :variables_schema, :selection_set_match_type, :fields, :type
+
+    def initialize(query: nil, operation_name: nil, variables_schema: nil, selection_set_match_type: nil,
+                   fields: nil, type: nil)
+      @query = query
+      @operation_name = operation_name
+      @variables_schema = variables_schema
+      @selection_set_match_type = selection_set_match_type
+      @fields = fields
+      @type = type
+    end
+
+    def to_h
+      MockServer.strip_none({
+        'type'                  => @type,
+        'query'                 => @query,
+        'operationName'         => @operation_name,
+        'variablesSchema'       => @variables_schema,
+        'selectionSetMatchType' => @selection_set_match_type,
+        'fields'                => @fields
+      })
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        query:                    data['query'],
+        operation_name:           data['operationName'],
+        variables_schema:         data['variablesSchema'],
+        selection_set_match_type: data['selectionSetMatchType'],
+        fields:                   data['fields'],
+        type:                     data['type']
+      )
+    end
+  end
+
   class HttpWebSocketResponse
     # matchers carries per-incoming-frame response rules (server
     # HttpWebSocketResponseDTO.matchers); each is a {WebSocketFrameMatcher}.
-    attr_accessor :subprotocol, :messages, :matchers, :close_connection, :delay, :primary
+    # template_type renders each message with that engine.
+    attr_accessor :subprotocol, :messages, :matchers, :close_connection, :delay, :primary,
+                  :template_type, :graphql_subscription_filter
 
-    def initialize(subprotocol: nil, messages: nil, matchers: nil, close_connection: nil, delay: nil, primary: nil)
+    def initialize(subprotocol: nil, messages: nil, matchers: nil, close_connection: nil, delay: nil, primary: nil,
+                   template_type: nil, graphql_subscription_filter: nil)
       @subprotocol = subprotocol
       @messages = messages
       @matchers = matchers
       @close_connection = close_connection
       @delay = delay
       @primary = primary
+      @template_type = template_type
+      @graphql_subscription_filter = graphql_subscription_filter
     end
 
     def to_h
@@ -1500,6 +1813,8 @@ module MockServer
       result['closeConnection'] = @close_connection unless @close_connection.nil?
       result['delay'] = @delay.to_h if @delay
       result['primary'] = @primary unless @primary.nil?
+      result['templateType'] = @template_type unless @template_type.nil?
+      result['graphqlSubscriptionFilter'] = @graphql_subscription_filter.to_h if @graphql_subscription_filter
       result
     end
 
@@ -1516,7 +1831,9 @@ module MockServer
         matchers:         matchers,
         close_connection: data['closeConnection'],
         delay:            Delay.from_hash(data['delay']),
-        primary:          data['primary']
+        primary:          data['primary'],
+        template_type:    data['templateType'],
+        graphql_subscription_filter: GraphQLSubscriptionFilter.from_hash(data['graphqlSubscriptionFilter'])
       )
     end
   end
@@ -1672,13 +1989,23 @@ module MockServer
     end
   end
 
+  # Values for BinaryResponse#upstream: what happens upstream to a message a binary
+  # expectation matches on a relayed connection (matchBinaryExpectationsWhenProxying).
+  # ANSWER_ONLY is the server's default; the other two need binaryMessageFraming POSTGRESQL.
+  module BinaryUpstream
+    ANSWER_ONLY         = 'ANSWER_ONLY'
+    ANSWER_AND_FORWARD  = 'ANSWER_AND_FORWARD'
+    FORWARD_AND_REPLACE = 'FORWARD_AND_REPLACE'
+  end
+
   class BinaryResponse
-    attr_accessor :binary_data, :delay, :primary
+    attr_accessor :binary_data, :delay, :primary, :upstream
 
-    def initialize(binary_data: nil, delay: nil, primary: nil)
+    def initialize(binary_data: nil, delay: nil, primary: nil, upstream: nil)
       @binary_data = binary_data
       @delay = delay
       @primary = primary
+      @upstream = upstream
     end
 
     def to_h
@@ -1686,6 +2013,7 @@ module MockServer
       result['binaryData'] = @binary_data unless @binary_data.nil?
       result['delay'] = @delay.to_h if @delay
       result['primary'] = @primary unless @primary.nil?
+      result['upstream'] = @upstream unless @upstream.nil?
       result
     end
 
@@ -1695,7 +2023,8 @@ module MockServer
       new(
         binary_data: data['binaryData'],
         delay:       Delay.from_hash(data['delay']),
-        primary:     data['primary']
+        primary:     data['primary'],
+        upstream:    data['upstream']
       )
     end
   end
@@ -2541,7 +2870,7 @@ module MockServer
         id:                              data['id'],
         priority:                        data['priority'],
         percentage:                      data['percentage'],
-        http_request:                    HttpRequest.from_hash(data['httpRequest']),
+        http_request:                    MockServer.deserialize_request_definition(data['httpRequest']),
         http_response:                   HttpResponse.from_hash(data['httpResponse']),
         http_response_template:          HttpTemplate.from_hash(data['httpResponseTemplate']),
         http_response_class_callback:    HttpClassCallback.from_hash(data['httpResponseClassCallback']),
@@ -2583,18 +2912,25 @@ module MockServer
     end
   end
 
+  # An OpenAPI request matcher: as an expectation's or verification's
+  # httpRequest it matches the requests an OpenAPI operation accepts.
   class OpenAPIDefinition
-    attr_accessor :spec_url_or_payload, :operation_id
+    # not_operation inverts the match (the server's +not+ field).
+    attr_accessor :spec_url_or_payload, :operation_id, :context_path_prefix, :not_operation
 
-    def initialize(spec_url_or_payload: nil, operation_id: nil)
+    def initialize(spec_url_or_payload: nil, operation_id: nil, context_path_prefix: nil, not_operation: nil)
       @spec_url_or_payload = spec_url_or_payload
       @operation_id = operation_id
+      @context_path_prefix = context_path_prefix
+      @not_operation = not_operation
     end
 
     def to_h
       MockServer.strip_none({
-        'specUrlOrPayload' => @spec_url_or_payload,
-        'operationId'      => @operation_id
+        'not'               => @not_operation,
+        'specUrlOrPayload'  => @spec_url_or_payload,
+        'operationId'       => @operation_id,
+        'contextPathPrefix' => @context_path_prefix
       })
     end
 
@@ -2603,7 +2939,46 @@ module MockServer
 
       new(
         spec_url_or_payload: data['specUrlOrPayload'],
-        operation_id:        data['operationId']
+        operation_id:        data['operationId'],
+        context_path_prefix: data['contextPathPrefix'],
+        not_operation:       data['not']
+      )
+    end
+  end
+
+  # A conditional (if/then/else) request matcher, written as an httpRequest
+  # holding if, then and else. When +if_request+ matches, +then_request+ must
+  # match too; otherwise +else_request+ must (with none, the matcher matches
+  # whenever +if_request+ does not). Each branch is an HttpRequest, an
+  # OpenAPIDefinition or another ConditionalRequestDefinition.
+  class ConditionalRequestDefinition
+    # not_condition inverts the match (the server's +not+ field).
+    attr_accessor :if_request, :then_request, :else_request, :not_condition
+
+    def initialize(if_request: nil, then_request: nil, else_request: nil, not_condition: nil)
+      @if_request = if_request
+      @then_request = then_request
+      @else_request = else_request
+      @not_condition = not_condition
+    end
+
+    def to_h
+      MockServer.strip_none({
+        'not'  => @not_condition,
+        'if'   => @if_request&.to_h,
+        'then' => @then_request&.to_h,
+        'else' => @else_request&.to_h
+      })
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        if_request:    MockServer.deserialize_request_definition(data['if']),
+        then_request:  MockServer.deserialize_request_definition(data['then']),
+        else_request:  MockServer.deserialize_request_definition(data['else']),
+        not_condition: data['not']
       )
     end
   end
@@ -2705,7 +3080,7 @@ module MockServer
       return nil if data.nil?
 
       new(
-        http_request:    HttpRequest.from_hash(data['httpRequest']),
+        http_request:    MockServer.deserialize_request_definition(data['httpRequest']),
         http_response:   HttpResponse.from_hash(data['httpResponse']),
         expectation_id:  ExpectationId.from_hash(data['expectationId']),
         times:           VerificationTimes.from_hash(data['times']),
@@ -2738,7 +3113,7 @@ module MockServer
       http_responses_data = data['httpResponses']
       expectation_ids_data = data['expectationIds']
       new(
-        http_requests:   http_requests_data&.map { |r| HttpRequest.from_hash(r) },
+        http_requests:   http_requests_data&.map { |r| MockServer.deserialize_request_definition(r) },
         http_responses:  http_responses_data&.map { |r| HttpResponse.from_hash(r) },
         expectation_ids: expectation_ids_data&.map { |e| ExpectationId.from_hash(e) }
       )
@@ -3116,20 +3491,61 @@ module MockServer
     end
   end
 
+  # A per-step response assertion for a load scenario: reads a value from the
+  # step's response (+source+ +STATUS+, +HEADER+ with +header_name+, or
+  # +BODY_JSONPATH+ with +json_path+) and compares it with +value+ using
+  # +comparator+ (+EQUALS+, +NOT_EQUALS+, +CONTAINS+, +MATCHES+, +GT+, +LT+,
+  # +GTE+ or +LTE+). A failing check never fails the request; failures feed the
+  # +CHECK_FAILURE_RATE+ threshold.
+  class LoadCheck
+    attr_accessor :source, :header_name, :json_path, :comparator, :value
+
+    def initialize(source:, comparator:, header_name: nil, json_path: nil, value: nil)
+      @source = source
+      @comparator = comparator
+      @header_name = header_name
+      @json_path = json_path
+      @value = value
+    end
+
+    def to_h
+      MockServer.strip_none({
+        'source'     => @source,
+        'headerName' => @header_name,
+        'jsonPath'   => @json_path,
+        'comparator' => @comparator,
+        'value'      => @value
+      })
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        source:      data['source'],
+        header_name: data['headerName'],
+        json_path:   data['jsonPath'],
+        comparator:  data['comparator'],
+        value:       data['value']
+      )
+    end
+  end
+
   # A single step within a load scenario. Each step fires +request+ (an HttpRequest)
   # against the target, optionally pausing for +think_time+ (a Delay) afterwards.
   # +captures+ binds values from this step's response for later steps in the same
-  # iteration; +weight+ is the relative selection weight when the scenario's
-  # +step_selection+ is +WEIGHTED+.
+  # iteration; +checks+ (LoadCheck) assert on that response; +weight+ is the
+  # relative selection weight when the scenario's +step_selection+ is +WEIGHTED+.
   class LoadStep
-    attr_accessor :name, :labels, :think_time, :request, :captures, :weight
+    attr_accessor :name, :labels, :think_time, :request, :captures, :checks, :weight
 
-    def initialize(request:, name: nil, labels: nil, think_time: nil, captures: nil, weight: nil)
+    def initialize(request:, name: nil, labels: nil, think_time: nil, captures: nil, checks: nil, weight: nil)
       @request = request
       @name = name
       @labels = labels
       @think_time = think_time
       @captures = captures
+      @checks = checks
       @weight = weight
     end
 
@@ -3140,6 +3556,7 @@ module MockServer
         'thinkTime' => @think_time&.to_h,
         'request'   => @request&.to_h,
         'captures'  => @captures.nil? ? nil : @captures.map(&:to_h),
+        'checks'    => @checks.nil? ? nil : @checks.map(&:to_h),
         'weight'    => @weight
       })
     end
@@ -3148,12 +3565,14 @@ module MockServer
       return nil if data.nil?
 
       captures_data = data['captures']
+      checks_data = data['checks']
       new(
         name:       data['name'],
         labels:     data['labels'],
         think_time: Delay.from_hash(data['thinkTime']),
         request:    HttpRequest.from_hash(data['request']),
         captures:   captures_data ? captures_data.map { |c| LoadCapture.from_hash(c) } : nil,
+        checks:     checks_data ? checks_data.map { |c| LoadCheck.from_hash(c) } : nil,
         weight:     data['weight']
       )
     end
@@ -3230,6 +3649,384 @@ module MockServer
     end
   end
 
+  # -------------------------------------------------------------------
+  # Diagnostics: explain, debug_mismatch and explain_unmatched results.
+  # They follow the RequestExplanation and ExplainedExpectation OpenAPI
+  # schemas; an enum value a newer server sends is kept as its String.
+  # -------------------------------------------------------------------
+
+  # A JSON patch (RFC 6902) of an expectation that would make it match the
+  # request; nothing is applied. +unpatched_fields+ lists each field that
+  # could not be patched, with a +reason+.
+  class SuggestedFix
+    attr_reader :patch, :patched_fields, :unpatched_fields, :matches_after_patch
+
+    def initialize(patch: [], patched_fields: [], unpatched_fields: [], matches_after_patch: false)
+      @patch = patch
+      @patched_fields = patched_fields
+      @unpatched_fields = unpatched_fields
+      @matches_after_patch = matches_after_patch
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        patch:               data['patch'] || [],
+        patched_fields:      data['patchedFields'] || [],
+        unpatched_fields:    data['unpatchedFields'] || [],
+        matches_after_patch: data['matchesAfterPatch'] == true
+      )
+    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+.
+  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
+
+    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)
+      @expectation_id = expectation_id
+      @expectation_method = expectation_method
+      @expectation_path = expectation_path
+      @position = position
+      @priority = priority
+      @reason = reason
+      @explanation = explanation
+      @matches = matches
+      @matched_field_count = matched_field_count
+      @total_field_count = total_field_count
+      @differing_field_count = differing_field_count
+      @differences = differences
+      @remediation = remediation
+      @suggested_fix = suggested_fix
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        expectation_id:        data['expectationId'],
+        expectation_method:    data['expectationMethod'],
+        expectation_path:      data['expectationPath'],
+        position:              data['position'],
+        priority:              data['priority'],
+        reason:                data['reason'],
+        explanation:           data['explanation'],
+        matches:               data['matches'],
+        matched_field_count:   data['matchedFieldCount'],
+        total_field_count:     data['totalFieldCount'],
+        differing_field_count: data['differingFieldCount'],
+        differences:           data['differences'] || {},
+        remediation:           data['remediation'] || {},
+        suggested_fix:         SuggestedFix.from_hash(data['suggestedFix'])
+      )
+    end
+
+    # @api private
+    def self.list(items)
+      (items || []).map { |item| from_hash(item) }
+    end
+  end
+
+  # The recorded request that explain re-checked.
+  class ExplainedRequest
+    attr_reader :timestamp, :method, :path, :body_truncated, :body_truncated_note
+
+    def initialize(timestamp: nil, method: nil, path: nil, body_truncated: false, body_truncated_note: nil)
+      @timestamp = timestamp
+      @method = method
+      @path = path
+      @body_truncated = body_truncated
+      @body_truncated_note = body_truncated_note
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        timestamp:           data['timestamp'],
+        method:              data['method'],
+        path:                data['path'],
+        body_truncated:      data['bodyTruncated'] == true,
+        body_truncated_note: data['bodyTruncatedNote']
+      )
+    end
+  end
+
+  # How a request was handled when it arrived: +outcome+ is MATCHED, NO_MATCH,
+  # FORWARDED_WITHOUT_EXPECTATION, RESPONDED_WITHOUT_EXPECTATION or UNKNOWN;
+  # the expectation fields are set for MATCHED only.
+  # +forward_failure+ is set only when the request was forwarded and the
+  # forward failed.
+  class Arrival
+    attr_reader :outcome, :expectation_id, :expectation_still_stored, :forward_failure
+
+    def initialize(outcome: nil, expectation_id: nil, expectation_still_stored: nil, forward_failure: nil)
+      @outcome = outcome
+      @expectation_id = expectation_id
+      @expectation_still_stored = expectation_still_stored
+      @forward_failure = forward_failure
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        outcome:                  data['outcome'],
+        expectation_id:           data['expectationId'],
+        expectation_still_stored: data['expectationStillStored'],
+        forward_failure:          ArrivalForwardFailure.from_hash(data['forwardFailure'])
+      )
+    end
+  end
+
+  # Why a request's forward failed, so MockServer answered 502: the same
+  # facts the explain_forward_failure MCP tool gives. +reason+ is redacted as
+  # the event log is and capped at 2048 characters (+reason_truncated+); when
+  # +cause_named+ is false the reason is the raw error and +hint+ says what to
+  # look at next.
+  class ArrivalForwardFailure
+    attr_reader :status_code, :reason, :reason_truncated, :cause_named, :forward_loop_suspected, :hint
+
+    def initialize(status_code: nil, reason: nil, reason_truncated: false, cause_named: nil,
+                   forward_loop_suspected: nil, hint: nil)
+      @status_code = status_code
+      @reason = reason
+      @reason_truncated = reason_truncated
+      @cause_named = cause_named
+      @forward_loop_suspected = forward_loop_suspected
+      @hint = hint
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        status_code:            data['statusCode'],
+        reason:                 data['reason'],
+        reason_truncated:       data['reasonTruncated'] == true,
+        cause_named:            data['causeNamed'],
+        forward_loop_suspected: data['forwardLoopSuspected'],
+        hint:                   data['hint']
+      )
+    end
+  end
+
+  # Set only when narration was asked for: a plain-language summary the
+  # configured LLM backend wrote, or why none is available (+reason+). It is
+  # AI-generated and can be wrong; the other fields are the facts.
+  class ExplanationNarration
+    attr_reader :available, :ai_generated, :label, :provider, :model, :text, :reason
+
+    def initialize(available: nil, ai_generated: nil, label: nil, provider: nil, model: nil, text: nil,
+                   reason: nil)
+      @available = available
+      @ai_generated = ai_generated
+      @label = label
+      @provider = provider
+      @model = model
+      @text = text
+      @reason = reason
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        available:    data['available'],
+        ai_generated: data['aiGenerated'],
+        label:        data['label'],
+        provider:     data['provider'],
+        model:        data['model'],
+        text:         data['text'],
+        reason:       data['reason']
+      )
+    end
+  end
+
+  # Which expectation would serve a recorded request now, why each one
+  # evaluated ahead of it was passed over, which lower-priority ones it
+  # shadows, and how the request was handled when it arrived. Recomputed when
+  # asked for, against the current expectations, scenario states and Times.
+  class RequestExplanation
+    attr_reader :correlation_id, :timestamp, :recomputed, :note, :request, :at_arrival,
+                :same_outcome_as_at_arrival, :expectations_changed_since, :expectations_last_changed,
+                :matched_expectation, :closest_expectation_id, :skipped_expectations,
+                :shadowed_expectations, :total_expectations, :evaluated_expectations, :truncated,
+                :max_expectations_evaluated, :narration
+
+    def initialize(correlation_id: nil, timestamp: nil, recomputed: nil, note: nil, request: nil,
+                   at_arrival: nil, same_outcome_as_at_arrival: nil, expectations_changed_since: false,
+                   expectations_last_changed: nil, matched_expectation: nil, closest_expectation_id: nil,
+                   skipped_expectations: [], shadowed_expectations: [], total_expectations: 0,
+                   evaluated_expectations: 0, truncated: false, max_expectations_evaluated: nil,
+                   narration: nil)
+      @correlation_id = correlation_id
+      @timestamp = timestamp
+      @recomputed = recomputed
+      @note = note
+      @request = request
+      @at_arrival = at_arrival
+      @same_outcome_as_at_arrival = same_outcome_as_at_arrival
+      @expectations_changed_since = expectations_changed_since
+      @expectations_last_changed = expectations_last_changed
+      @matched_expectation = matched_expectation
+      @closest_expectation_id = closest_expectation_id
+      @skipped_expectations = skipped_expectations
+      @shadowed_expectations = shadowed_expectations
+      @total_expectations = total_expectations
+      @evaluated_expectations = evaluated_expectations
+      @truncated = truncated
+      @max_expectations_evaluated = max_expectations_evaluated
+      @narration = narration
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        correlation_id:             data['correlationId'],
+        timestamp:                  data['timestamp'],
+        recomputed:                 data['recomputed'],
+        note:                       data['note'],
+        request:                    ExplainedRequest.from_hash(data['request']),
+        at_arrival:                 Arrival.from_hash(data['atArrival']),
+        same_outcome_as_at_arrival: data['sameOutcomeAsAtArrival'],
+        expectations_changed_since: data['expectationsChangedSince'] == true,
+        expectations_last_changed:  data['expectationsLastChanged'],
+        matched_expectation:        ExplainedExpectation.from_hash(data['matchedExpectation']),
+        closest_expectation_id:     data['closestExpectationId'],
+        skipped_expectations:       ExplainedExpectation.list(data['skippedExpectations']),
+        shadowed_expectations:      ExplainedExpectation.list(data['shadowedExpectations']),
+        total_expectations:         data['totalExpectations'] || 0,
+        evaluated_expectations:     data['evaluatedExpectations'] || 0,
+        truncated:                  data['truncated'] == true,
+        max_expectations_evaluated: data['maxExpectationsEvaluated'],
+        narration:                  ExplanationNarration.from_hash(data['narration'])
+      )
+    end
+  end
+
+  # The expectation debug_mismatch found with the fewest differing fields.
+  class ClosestMatch
+    attr_reader :expectation_id, :matched_fields, :total_fields
+
+    def initialize(expectation_id: nil, matched_fields: nil, total_fields: nil)
+      @expectation_id = expectation_id
+      @matched_fields = matched_fields
+      @total_fields = total_fields
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(expectation_id: data['expectationId'], matched_fields: data['matchedFields'],
+          total_fields: data['totalFields'])
+    end
+  end
+
+  # The result of debug_mismatch: each active expectation compared with the
+  # request, and the closest match (nil when every expectation matches).
+  class DebugMismatchResult
+    attr_reader :correlation_id, :timestamp, :total_expectations, :evaluated_expectations,
+                :truncated, :max_expectations_evaluated, :closest_match, :results
+
+    def initialize(correlation_id: nil, timestamp: nil, total_expectations: 0, evaluated_expectations: 0,
+                   truncated: false, max_expectations_evaluated: nil, closest_match: nil, results: [])
+      @correlation_id = correlation_id
+      @timestamp = timestamp
+      @total_expectations = total_expectations
+      @evaluated_expectations = evaluated_expectations
+      @truncated = truncated
+      @max_expectations_evaluated = max_expectations_evaluated
+      @closest_match = closest_match
+      @results = results
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        correlation_id:             data['correlationId'],
+        timestamp:                  data['timestamp'],
+        total_expectations:         data['totalExpectations'] || 0,
+        evaluated_expectations:     data['evaluatedExpectations'] || 0,
+        truncated:                  data['truncated'] == true,
+        max_expectations_evaluated: data['maxExpectationsEvaluated'],
+        closest_match:              ClosestMatch.from_hash(data['closestMatch']),
+        results:                    ExplainedExpectation.list(data['results'])
+      )
+    end
+  end
+
+  # One recent unmatched request and its closest expectations, closest first.
+  class UnmatchedRequest
+    attr_reader :timestamp, :method, :path, :closest_expectations, :total_expectations_evaluated
+
+    def initialize(timestamp: nil, method: nil, path: nil, closest_expectations: [],
+                   total_expectations_evaluated: 0)
+      @timestamp = timestamp
+      @method = method
+      @path = path
+      @closest_expectations = closest_expectations
+      @total_expectations_evaluated = total_expectations_evaluated
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        timestamp:                    data['timestamp'],
+        method:                       data['method'],
+        path:                         data['path'],
+        closest_expectations:         ExplainedExpectation.list(data['closestExpectations']),
+        total_expectations_evaluated: data['totalExpectationsEvaluated'] || 0
+      )
+    end
+  end
+
+  # The result of explain_unmatched.
+  class ExplainUnmatchedResult
+    attr_reader :correlation_id, :timestamp, :unmatched_request_count, :truncated, :unmatched_requests,
+                :narration
+
+    def initialize(correlation_id: nil, timestamp: nil, unmatched_request_count: 0, truncated: false,
+                   unmatched_requests: [], narration: nil)
+      @correlation_id = correlation_id
+      @timestamp = timestamp
+      @unmatched_request_count = unmatched_request_count
+      @truncated = truncated
+      @unmatched_requests = unmatched_requests
+      @narration = narration
+    end
+
+    def self.from_hash(data)
+      return nil if data.nil?
+
+      new(
+        correlation_id:          data['correlationId'],
+        timestamp:               data['timestamp'],
+        unmatched_request_count: data['unmatchedRequestCount'] || 0,
+        truncated:               data['truncated'] == true,
+        unmatched_requests:      (data['unmatchedRequests'] || []).map { |r| UnmatchedRequest.from_hash(r) },
+        narration:               ExplanationNarration.from_hash(data['narration'])
+      )
+    end
+  end
+
   # Alias matching the Python client
   RequestDefinition = HttpRequest
+
+  constants.map { |name| const_get(name) }.each do |model|
+    model.singleton_class.prepend(SymbolKeyTolerantFromHash) if model.is_a?(Class) && model.respond_to?(:from_hash)
+  end
 end