mockserver-client 7.1.0 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b853b4ba04e3473e6e664a0f1a2f6b4f0a8146f624a2308a19349fe94f536d9e
-  data.tar.gz: 848eedd40df3e43ac6299250c92d4f30ee1b7fbeedb15699cd7254af20fcb6a4
+  metadata.gz: f1a47589dbc527bf772961f968c2235d9b64ebc13fd8a1f963e143e50319db9f
+  data.tar.gz: 85aa291fefefdce077d8f4eaca22a5fd56d473628ec819c2029fae9f8e91aa4e
 SHA512:
-  metadata.gz: a2c283e6f9ed9fb935ff296a84298abc7c73768609c0601b8079e20441ebd25ca1029256a7c21a968578ef3f9ea28777b7d07dd20c7d8b4387031298389c4eb8
-  data.tar.gz: 77bc8cf3f5e4e919ba758c4c720cbf9795600094d7bfc41faa66b5571c0ea2b7ee39fa3a4f6871726ffc3a6468f84defb34afce05b33203b734e1cc1ac1c3c53
+  metadata.gz: 1b5adcd45c05bc417a62ad3a6fab6e00b42ef1180b7a89cc0084f972bb83aac5d68832d2e02da83d899a7fb511a71fb2ff87576eba4487f51a0bfafc546d5c06
+  data.tar.gz: dd83794b0fd9ad0ffc7439b505bc7ff3c8461e076d6acf209ce8b273b6ca4d233c19638ece936faaacf43e196d39a1a9220206c1a559dbe86dd2154a15b078e8

data/README.md

@@ -99,6 +99,90 @@ All 25 domain model classes are available under the `MockServer` module:
 - `Ports`
 - `RequestDefinition` (alias for `HttpRequest`)
 
+## LLM Mocking
+
+Fluent builders under `MockServer::LLM` mock LLM provider endpoints. They produce
+expectations whose action is carried in the `httpLlmResponse` field; MockServer
+re-encodes the provider-agnostic completion into the configured provider's wire
+shape (OpenAI / Anthropic / Gemini / Bedrock / ...) when serving the request.
+
+```ruby
+require 'mockserver-client'
+
+client = MockServer::Client.new('localhost', 1080)
+
+# A single completion mock
+MockServer::LLM.llm_mock('/v1/chat/completions')
+               .with_provider(MockServer::LLM::Provider::OPENAI)
+               .with_model('gpt-4o')
+               .responding_with(
+                 MockServer::LLM.completion
+                                .with_text('Hello!')
+                                .with_usage(MockServer::LLM.usage.with_input_tokens(10).with_output_tokens(5))
+               )
+               .apply_to(client)
+```
+
+Multi-turn **conversations** use MockServer scenario-state advancement so each
+turn is served once, in order. Add per-turn predicates with `when_*` methods and
+optionally isolate per session with `isolate_by`:
+
+```ruby
+MockServer::LLM.conversation
+               .with_path('/v1/chat/completions')
+               .with_provider(MockServer::LLM::Provider::OPENAI)
+               .isolate_by(MockServer::LLM.header('x-session-id'))
+               .turn.when_latest_message_contains('weather')
+                    .responding_with(MockServer::LLM.completion.with_text('It is sunny.'))
+               .turn.responding_with(MockServer::LLM.completion.with_text('Anything else?'))
+               .apply_to(client)
+```
+
+**Failover** scenarios script N upstream failures (consecutive identical failures
+are coalesced) followed by a success; default JSON error bodies are generated per
+status code unless a custom body is supplied:
+
+```ruby
+MockServer::LLM.llm_failover
+               .with_path('/v1/chat/completions')
+               .with_provider(MockServer::LLM::Provider::OPENAI)
+               .fail_with(429, 2)          # two rate-limit failures
+               .fail_with(503)             # then one service-unavailable
+               .then_respond_with(MockServer::LLM.completion.with_text('Recovered'))
+               .apply_to(client)
+```
+
+Each builder also exposes `build` to obtain the raw expectation Hash(es) without
+registering them.
+
+## MCP Mocking
+
+`MockServer::MCP.mcp_mock` builds the set of expectations needed to emulate a
+Streamable-HTTP MCP (Model Context Protocol) server speaking JSON-RPC 2.0. It
+generates `initialize`, `ping`, `notifications/initialized`, and per-capability
+`tools`, `resources`, and `prompts` handlers.
+
+```ruby
+MockServer::MCP.mcp_mock('/mcp')
+               .with_server_name('MyServer')
+               .with_tool('get_weather')
+                 .with_description('Get the weather for a city')
+                 .with_input_schema('{"type":"object","properties":{"city":{"type":"string"}}}')
+                 .responding_with('72F and sunny')
+               .and_then
+               .with_resource('file:///config.json')
+                 .with_name('config')
+                 .with_content('{"debug":true}')
+               .and_then
+               .with_prompt('greet')
+                 .with_argument('name', 'who to greet', true)
+                 .responding_with('user', 'Hello there')
+               .and_then
+               .apply_to(client)
+```
+
+`build` returns the raw expectation Hashes if you prefer to register them yourself.
+
 ## Interactive Breakpoints
 
 The client supports matcher-driven interactive breakpoints over the callback WebSocket. Register a breakpoint matcher to pause forwarded/proxied exchanges at specific phases and inspect/modify/continue them via callback handlers.
@@ -172,7 +256,7 @@ launcher_path = MockServer::BinaryLauncher.ensure_launcher
 ### Specify a version
 
 ```ruby
-handle = MockServer::BinaryLauncher.start(port: 1080, version: '7.1.0')
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '7.2.0')
 ```
 
 ### API reference
@@ -203,6 +287,34 @@ handle = MockServer::BinaryLauncher.start(port: 1080, version: '7.1.0')
 
 By default the launcher downloads the MockServer version matching this client gem (currently `MockServer::VERSION` from `lib/mockserver/version.rb`). Pass an explicit `version:` keyword to override.
 
+## Using in tests (RSpec)
+
+Require `mockserver/rspec` to get a shared context that provides a fresh
+`MockServer::Client` per example and resets the server before and after each
+example, so recorded requests, expectations and logs never leak between
+examples:
+
+```ruby
+# spec_helper.rb
+require 'mockserver/rspec'
+
+# any spec tagged :mockserver gets a reset `mockserver` client
+RSpec.describe 'my integration', :mockserver do
+  it 'records the request' do
+    # `mockserver` is the shared, reset client
+    mockserver.when(
+      MockServer::HttpRequest.request(path: '/hello')
+    ).respond(
+      MockServer::HttpResponse.response(body: 'world', status_code: 200)
+    )
+  end
+end
+```
+
+Host and port default to `127.0.0.1:1080` and can be overridden with the
+`MOCKSERVER_HOST` / `MOCKSERVER_PORT` environment variables, or by defining a
+`mockserver_host` / `mockserver_port` `let` in your example group.
+
 ## License
 
 Apache-2.0

data/lib/mockserver/binary_launcher.rb

@@ -32,6 +32,11 @@ module MockServer
   # @example Just ensure the binary is present
   #   path = MockServer::BinaryLauncher.ensure_launcher
   class BinaryLauncher
+    # Raised internally when a download returns HTTP 404, so the caller can
+    # distinguish "no bundle published for this version" from other transport
+    # errors and emit actionable guidance.
+    class NotFoundError < StandardError; end
+
     REPO = 'mock-server/mockserver-monorepo'
 
     # CDN base URL used for SNAPSHOT version downloads.
@@ -171,7 +176,14 @@ module MockServer
           # Download to a temp file
           url = asset_url(version, archive_file)
           log.info("Downloading #{url}")
-          download_file(url, partial)
+          begin
+            download_file(url, partial)
+          rescue NotFoundError
+            # A 404 means the release tag exists but ships no bundle for this
+            # version (or the tag does not exist). Emit actionable guidance
+            # instead of an opaque HTTP error.
+            raise Error, no_bundle_message(version)
+          end
 
           # Verify SHA-256 (fail-closed — always required, no bypass)
           sha_url = asset_url(version, "#{archive_file}.sha256")
@@ -317,6 +329,22 @@ module MockServer
 
       private
 
+      # Build a clear, actionable error message for a missing release bundle.
+      #
+      # Explains that no downloadable bundle exists for +version+ and lists the
+      # concrete alternatives. The wording is kept consistent across all client
+      # languages.
+      #
+      # @param version [String]
+      # @return [String]
+      def no_bundle_message(version)
+        "no MockServer release bundle is published for version #{version} " \
+          "(no downloadable asset at the GitHub release tag 'mockserver-#{version}'). " \
+          'Use a MockServer version that ships self-contained bundles, ' \
+          "or run MockServer via Docker (docker run mockserver/mockserver:mockserver-#{version}), " \
+          "or use the Maven Central jar (org.mock-server:mockserver-netty:#{version})."
+      end
+
       # Validate the version string against the strict pattern (H1).
       #
       # @param version [String]
@@ -567,6 +595,8 @@ module MockServer
             response.read_body
             location = response['location']
             fetch_with_redirects(URI.parse(location), dest, max_redirects - 1)
+          when Net::HTTPNotFound
+            raise NotFoundError, "download #{uri} failed: HTTP 404"
           else
             raise Error, "download #{uri} failed: HTTP #{response.code}"
           end

data/lib/mockserver/client.rb

@@ -260,6 +260,256 @@ module MockServer
       response_body && !response_body.empty? ? JSON.parse(response_body) : {}
     end
 
+    # -------------------------------------------------------------------
+    # Load scenario registry (load injection)
+    # -------------------------------------------------------------------
+    #
+    # The load scenario registry decouples *registering* a scenario from
+    # *running* it:
+    #
+    #   * registering (load_scenario) only stores the definition keyed by its
+    #     unique +name+ and is allowed even when +loadGenerationEnabled+ is off;
+    #   * starting (start_load_scenarios) is what actually drives traffic and
+    #     requires +loadGenerationEnabled+ on the server (otherwise a 403).
+    #
+    # Scenario states are: LOADED, PENDING, RUNNING, COMPLETED, STOPPED.
+
+    # Register (load) a scenario into the registry without running it.
+    #
+    # +scenario+ may be a {LoadScenario} model (which responds to +to_h+) or a
+    # plain Hash already shaped to the +LoadScenario+ JSON contract. It must
+    # carry a unique +name+. Registering is permitted even when load generation
+    # is disabled on the server.
+    #
+    # @param scenario [LoadScenario, Hash] the scenario to register
+    # @return [Hash] parsed response of the form { "name" => ..., "state" => ... }
+    def load_scenario(scenario)
+      payload = scenario.respond_to?(:to_h) ? scenario.to_h : scenario
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/loadScenario', body)
+      if status >= 400
+        raise Error, "Failed to register load scenario (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # List all registered load scenarios.
+    #
+    # @return [Hash] parsed response of the form
+    #   { "scenarios" => [ { "name" => ..., "state" => ..., "definition" => ..., "status" => ... }, ... ] }
+    def load_scenarios
+      status, response_body = request('GET', '/mockserver/loadScenario')
+      if status >= 400
+        raise Error, "Failed to list load scenarios (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Fetch a single registered load scenario by name.
+    #
+    # @param name [String] the unique scenario name
+    # @return [Hash] parsed scenario entry { "name" => ..., "state" => ..., "definition" => ..., "status" => ... }
+    # @raise [Error] if the scenario does not exist (404) or another failure occurs
+    def get_load_scenario(name)
+      status, response_body = request('GET', "/mockserver/loadScenario/#{encode_path_segment(name)}")
+      if status == 404
+        raise Error, "Load scenario not found (status=404): #{name}"
+      end
+      if status >= 400
+        raise Error, "Failed to get load scenario (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Remove a single registered load scenario by name.
+    #
+    # @param name [String] the unique scenario name
+    # @return [Hash] parsed response (may be empty)
+    def delete_load_scenario(name)
+      status, response_body = request('DELETE', "/mockserver/loadScenario/#{encode_path_segment(name)}")
+      if status >= 400
+        raise Error, "Failed to delete load scenario (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Clear all registered load scenarios.
+    #
+    # @return [Hash] parsed response (may be empty)
+    def clear_load_scenarios
+      status, response_body = request('DELETE', '/mockserver/loadScenario')
+      if status >= 400
+        raise Error, "Failed to clear load scenarios (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Start one or more registered scenarios.
+    #
+    # +names+ may be a single scenario name (String) or an Array of names; it is
+    # always sent as { "names" => [...] }. Honours each scenario's
+    # +startDelayMillis+. Requires +loadGenerationEnabled+ on the server; a 403
+    # response raises a clear error explaining the feature is disabled.
+    #
+    # @param names [String, Array<String>] scenario name(s) to start
+    # @return [Hash] parsed response of the form
+    #   { "started" => [ { "name" => ..., "state" => ... }, ... ], "status" => ... }
+    def start_load_scenarios(names)
+      payload = { 'names' => Array(names) }
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/loadScenario/start', body)
+      if status == 403
+        raise Error, 'Load scenario start rejected (status=403): load generation is disabled ' \
+                     '(set loadGenerationEnabled=true on the server to enable it)'
+      end
+      if status == 404
+        raise Error, "Load scenario not found (status=404): #{response_body}"
+      end
+      if status >= 400
+        raise Error, "Failed to start load scenarios (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Stop running scenarios.
+    #
+    # +names+ may be:
+    #   * a single scenario name (String) -> { "names" => ["a"] }
+    #   * an Array of names                -> { "names" => ["a", "b"] }
+    #   * nil (the default)                -> empty body, which stops all running scenarios
+    #
+    # @param names [String, Array<String>, nil] scenario name(s) to stop, or nil for all
+    # @return [Hash] parsed response of the form
+    #   { "stopped" => [ ... ], "status" => ... }
+    def stop_load_scenarios(names = nil)
+      body = names.nil? ? nil : JSON.generate({ 'names' => Array(names) })
+      status, response_body = request('PUT', '/mockserver/loadScenario/stop', body)
+      if status >= 400
+        raise Error, "Failed to stop load scenarios (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Convenience: register a scenario then immediately start it.
+    #
+    # Equivalent to calling {#load_scenario} followed by {#start_load_scenarios}
+    # for the scenario's name. Requires +loadGenerationEnabled+ on the server for
+    # the start step.
+    #
+    # @param scenario [LoadScenario, Hash] the scenario to register and run
+    # @return [Hash] parsed response from the start call
+    def run_load_scenario(scenario)
+      payload = scenario.respond_to?(:to_h) ? scenario.to_h : scenario
+      name = payload.respond_to?(:[]) ? (payload['name'] || payload[:name]) : nil
+      if name.nil? || name.to_s.empty?
+        raise ArgumentError, 'scenario must carry a non-empty name to run'
+      end
+
+      load_scenario(payload)
+      start_load_scenarios(name)
+    end
+
+    # -------------------------------------------------------------------
+    # Stateful scenarios (state machine control plane)
+    # -------------------------------------------------------------------
+
+    # Return a handle to the named stateful scenario, wrapping the
+    # +/mockserver/scenario/{name}+ control-plane endpoints.
+    #
+    # @param name [String] the scenario (state-machine) name
+    # @return [ScenarioHandle]
+    def scenario(name)
+      ScenarioHandle.new(self, name)
+    end
+
+    # List every known scenario and its current state.
+    #
+    # @return [Array<ScenarioState>] each with +scenario_name+ and +current_state+
+    def scenarios
+      result = scenario_request('GET', '/mockserver/scenario')
+      list = result.is_a?(Hash) ? (result['scenarios'] || []) : []
+      list.map { |s| ScenarioState.from_hash(s) }
+    end
+
+    # @api private
+    # Issue a control-plane scenario request, parsing the JSON response and
+    # raising {Error} on any >= 400 status. Reuses the same transport
+    # (+request+) as the other +/mockserver/...+ control endpoints.
+    def scenario_request(method, path, body = nil)
+      status, response_body = request(method, path, body)
+      if status >= 400
+        raise Error, "Scenario request failed (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # -------------------------------------------------------------------
+    # gRPC descriptor management
+    # -------------------------------------------------------------------
+
+    # Upload a compiled protobuf descriptor set so gRPC requests can be matched.
+    #
+    # +descriptor_bytes+ must be the raw bytes of a +FileDescriptorSet+ (e.g. the
+    # output of +protoc --descriptor_set_out=... --include_imports+). The bytes are
+    # sent verbatim as +application/octet-stream+ (NOT base64-encoded).
+    #
+    # @param descriptor_bytes [String] raw descriptor set bytes (binary string)
+    # @return [nil]
+    def upload_grpc_descriptor(descriptor_bytes)
+      if descriptor_bytes.nil? || descriptor_bytes.empty?
+        raise ArgumentError, 'descriptor bytes must not be empty'
+      end
+
+      status, response_body = request(
+        'PUT', '/mockserver/grpc/descriptors', descriptor_bytes,
+        content_type: 'application/octet-stream'
+      )
+      if status >= 400
+        raise Error, "Failed to upload gRPC descriptor (status=#{status}): #{response_body}"
+      end
+
+      nil
+    end
+
+    # Retrieve the gRPC services registered from uploaded descriptor sets.
+    #
+    # Returns an array of service hashes, each with a +"name"+ and a list of
+    # +"methods"+ (+"name"+, +"inputType"+, +"outputType"+, +"clientStreaming"+,
+    # +"serverStreaming"+).
+    #
+    # @return [Array<Hash>]
+    def retrieve_grpc_services
+      status, response_body = request('PUT', '/mockserver/grpc/services')
+      if status >= 400
+        raise Error, "Failed to retrieve gRPC services (status=#{status}): #{response_body}"
+      end
+
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed if parsed.is_a?(Array)
+      end
+      []
+    end
+
+    # Clear all uploaded gRPC descriptor sets and registered services.
+    # @return [nil]
+    def clear_grpc_descriptors
+      status, response_body = request('PUT', '/mockserver/grpc/clear')
+      if status >= 400
+        raise Error, "Failed to clear gRPC descriptors (status=#{status}): #{response_body}"
+      end
+
+      nil
+    end
+
     # Verify that a request (and optionally a response) was received.
     # @param request [HttpRequest, nil]
     # @param times [VerificationTimes, nil]
@@ -370,6 +620,44 @@ module MockServer
       []
     end
 
+    # Retrieve the active expectations as MockServer SDK setup code (the builder
+    # code that recreates the expectations) in the requested language.
+    # @param format [String] one of "java", "javascript", "python", "go",
+    #   "csharp", "ruby", "rust" or "php" (case-insensitive)
+    # @param request [HttpRequest, nil]
+    # @return [String] the generated code
+    def retrieve_expectations_as_code(format: 'java', request: nil)
+      body = request ? JSON.generate(request.to_h) : ''
+      status, response_body = do_request(
+        'PUT', '/mockserver/retrieve', body,
+        { 'type' => 'ACTIVE_EXPECTATIONS', 'format' => format.to_s.upcase }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve expectations as code (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # Retrieve the recorded (proxied) request/response pairs as MockServer SDK
+    # setup code in the requested language.
+    # @param format [String] one of "java", "javascript", "python", "go",
+    #   "csharp", "ruby", "rust" or "php" (case-insensitive)
+    # @param request [HttpRequest, nil]
+    # @return [String] the generated code
+    def retrieve_recorded_expectations_as_code(format: 'java', request: nil)
+      body = request ? JSON.generate(request.to_h) : ''
+      status, response_body = do_request(
+        'PUT', '/mockserver/retrieve', body,
+        { 'type' => 'RECORDED_EXPECTATIONS', 'format' => format.to_s.upcase }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve recorded expectations as code (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
     # Retrieve recorded requests and responses.
     # @param request [HttpRequest, nil]
     # @return [Array<HttpRequestAndHttpResponse>]
@@ -700,7 +988,8 @@ module MockServer
 
     # Perform an HTTP request with optional query parameters.
     # @api private
-    def do_request(method, path, body = nil, query_params = nil)
+    def do_request(method, path, body = nil, query_params = nil,
+                   content_type: 'application/json; charset=utf-8')
       url = "#{@base_url}#{path}"
       if query_params && !query_params.empty?
         url = "#{url}?#{URI.encode_www_form(query_params)}"
@@ -709,14 +998,24 @@ module MockServer
       uri = URI.parse(url)
       http = build_http(uri)
 
-      req = build_request(method, uri, body)
+      req = build_request(method, uri, body, content_type)
       execute_request(http, req)
     end
 
     # Perform an HTTP request (no query params).
     # @api private
-    def request(method, path, body = nil)
-      do_request(method, path, body, nil)
+    def request(method, path, body = nil,
+                content_type: 'application/json; charset=utf-8')
+      do_request(method, path, body, nil, content_type: content_type)
+    end
+
+    # @api private
+    # Percent-encode a single URL path segment (e.g. a scenario name) so that
+    # spaces, slashes, and other reserved characters are transmitted safely.
+    def encode_path_segment(value)
+      raise ArgumentError, 'name must not be nil or empty' if value.nil? || value.to_s.empty?
+
+      URI.encode_www_form_component(value.to_s).gsub('+', '%20')
     end
 
     # @api private
@@ -741,7 +1040,7 @@ module MockServer
     end
 
     # @api private
-    def build_request(method, uri, body)
+    def build_request(method, uri, body, content_type = 'application/json; charset=utf-8')
       request_path = uri.request_uri
       case method.upcase
       when 'PUT'
@@ -755,14 +1054,19 @@ module MockServer
       else
         req = Net::HTTP::Put.new(request_path)
       end
-      req['Content-Type'] = 'application/json; charset=utf-8'
+      req['Content-Type'] = content_type
       req.body = body if body
       req
     end
 
     # @api private
     def execute_request(http, req)
-      response = http.request(req)
+      # Use the block form of #start so the underlying TCP/TLS connection is
+      # always closed (#finish) when the request completes, rather than being
+      # left open until garbage collection. All connection options (use_ssl,
+      # ca_file, verify_mode, read_timeout, open_timeout) configured on +http+
+      # by #build_http are preserved because #start operates on this instance.
+      response = http.start { |conn| conn.request(req) }
       [response.code.to_i, response.body || '']
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       raise ConnectionError, "Request to MockServer at #{@base_url} timed out: #{e.message}"

data/lib/mockserver/forward_chain_expectation.rb

@@ -182,14 +182,24 @@ module MockServer
       @client.upsert(@expectation)
     end
 
-    # Set a forward class callback action.
-    # @param class_callback [HttpClassCallback]
+    # Set a response class-callback action: the server invokes a server-side
+    # class implementing the response callback interface. Accepts either a
+    # fully-qualified class-name String (e.g. "com.example.MyResponseCallback")
+    # or a pre-built {HttpClassCallback} (carrying an optional +delay+ /
+    # +primary+).
+    # @param class_callback [String, HttpClassCallback]
+    # @return [Array<Expectation>]
+    def respond_with_class_callback(class_callback)
+      @expectation.http_response_class_callback = class_callback
+      @client.upsert(@expectation)
+    end
+
+    # Set a forward class-callback action: the server invokes a server-side
+    # class implementing the forward callback interface. Accepts either a
+    # fully-qualified class-name String or a pre-built {HttpClassCallback}.
+    # @param class_callback [String, HttpClassCallback]
     # @return [Array<Expectation>]
     def forward_with_class_callback(class_callback)
-      unless class_callback.is_a?(HttpClassCallback)
-        raise TypeError,
-              "Expected HttpClassCallback, got #{class_callback.class.name}"
-      end
       @expectation.http_forward_class_callback = class_callback
       @client.upsert(@expectation)
     end