mockserver-client 7.1.0 → 7.3.0

data/lib/mockserver/client.rb

@@ -204,6 +204,319 @@ module MockServer
       response_body && !response_body.empty? ? JSON.parse(response_body) : {}
     end
 
+    # -------------------------------------------------------------------
+    # Metrics
+    # -------------------------------------------------------------------
+
+    # Retrieve the JSON metric counter snapshot
+    # (PUT /mockserver/retrieve?type=METRICS).
+    #
+    # Returns a Hash mapping each metric name to its long value. When metrics
+    # are disabled on the server the snapshot is an empty Hash.
+    #
+    # @return [Hash] metric name => value
+    def retrieve_metrics
+      status, response_body = do_request(
+        'PUT', '/mockserver/retrieve', '', { 'type' => 'METRICS' }
+      )
+      if status >= 400
+        raise Error, "Failed to retrieve metrics (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Scrape the Prometheus exposition text (GET /mockserver/metrics).
+    #
+    # Returns the raw Prometheus/OpenMetrics exposition text. When metrics are
+    # disabled on the server this endpoint returns 404 and an {Error} is raised.
+    #
+    # @return [String] the Prometheus exposition text
+    def scrape_metrics
+      status, response_body = request('GET', '/mockserver/metrics')
+      if status == 404
+        raise Error, 'Failed to scrape metrics (status=404): metrics are disabled ' \
+                     '(set metricsEnabled=true on the server to enable them)'
+      end
+      if status >= 400
+        raise Error, "Failed to scrape metrics (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # -------------------------------------------------------------------
+    # Configuration
+    # -------------------------------------------------------------------
+
+    # Read the effective live configuration (GET /mockserver/configuration).
+    #
+    # @return [String] the serialized configuration JSON
+    def retrieve_configuration
+      status, response_body = request('GET', '/mockserver/configuration')
+      if status >= 400
+        raise Error, "Failed to retrieve configuration (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # Update the live configuration (PUT /mockserver/configuration).
+    #
+    # +config_json+ is a ConfigurationDTO JSON document; only the fields present
+    # are applied (partial update). A nil value is sent as an empty body.
+    #
+    # @param config_json [String, nil] the ConfigurationDTO JSON
+    # @return [String] the serialized updated configuration JSON
+    def update_configuration(config_json)
+      body = config_json.nil? ? '' : config_json.to_s
+      status, response_body = request('PUT', '/mockserver/configuration', body)
+      if status >= 400
+        raise Error, "Failed to update configuration (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # -------------------------------------------------------------------
+    # Pact (import / export / verify)
+    # -------------------------------------------------------------------
+
+    # Import a Pact v3 contract as expectations (PUT /mockserver/pact/import).
+    #
+    # @param json [String] the Pact v3 contract JSON (must not be blank)
+    # @return [String] the JSON array of upserted expectations
+    # @raise [ArgumentError] if +json+ is nil or blank
+    def pact_import(json)
+      if json.nil? || json.to_s.strip.empty?
+        raise ArgumentError, 'pact JSON must not be empty'
+      end
+
+      status, response_body = request('PUT', '/mockserver/pact/import', json.to_s)
+      if status >= 400
+        raise Error, "Failed to import pact (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # Export the active expectations as a Pact v3 contract
+    # (PUT /mockserver/pact?consumer=&provider=).
+    #
+    # A query param is only added when its value is non-blank; otherwise the
+    # server defaults are used.
+    #
+    # @param consumer [String, nil] the Pact consumer name
+    # @param provider [String, nil] the Pact provider name
+    # @return [String] the generated Pact v3 contract JSON
+    def pact_export(consumer: nil, provider: nil)
+      query_params = {}
+      query_params['consumer'] = consumer if consumer && !consumer.to_s.empty?
+      query_params['provider'] = provider if provider && !provider.to_s.empty?
+      status, response_body = do_request(
+        'PUT', '/mockserver/pact', nil, query_params.empty? ? nil : query_params
+      )
+      if status >= 400
+        raise Error, "Failed to export pact (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # Verify a Pact v3 contract against the active expectations
+    # (PUT /mockserver/pact/verify).
+    #
+    # The server encodes the verdict in the HTTP status: 202 when every
+    # interaction matches (PASS), 406 when verification fails (FAIL). Both
+    # carry the verification report JSON, which is returned verbatim in both
+    # cases (a FAIL does not raise) so callers can inspect the report.
+    #
+    # @param json [String] the Pact v3 contract JSON to verify (must not be blank)
+    # @return [String] the verification report JSON
+    # @raise [ArgumentError] if +json+ is nil or blank
+    def pact_verify(json)
+      if json.nil? || json.to_s.strip.empty?
+        raise ArgumentError, 'pact JSON must not be empty'
+      end
+
+      status, response_body = request('PUT', '/mockserver/pact/verify', json.to_s)
+      if status == 202 || status == 406
+        return response_body || ''
+      end
+      if status >= 400
+        raise Error, "Failed to verify pact (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # -------------------------------------------------------------------
+    # File store (store / retrieve / list / delete)
+    # -------------------------------------------------------------------
+
+    # Store a file in the in-memory file store (PUT /mockserver/files/store).
+    #
+    # @param name [String] the file name/key
+    # @param content [String] the UTF-8 file content
+    # @return [Hash] response of the form { "name" => ..., "size" => ... }
+    def store_file(name, content)
+      body = JSON.generate({ 'name' => name, 'content' => content })
+      status, response_body = request('PUT', '/mockserver/files/store', body)
+      if status >= 400
+        raise Error, "Failed to store file (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Retrieve a file's raw content (PUT /mockserver/files/retrieve).
+    #
+    # Returns the raw 200 body verbatim. An unknown file yields a 404 which
+    # raises an {Error} (there is no null-on-404 fallback).
+    #
+    # @param name [String] the file name/key
+    # @return [String] the raw file content
+    def retrieve_file(name)
+      body = JSON.generate({ 'name' => name })
+      status, response_body = request('PUT', '/mockserver/files/retrieve', body)
+      if status == 404
+        raise Error, "File not found (status=404): #{name}"
+      end
+      if status >= 400
+        raise Error, "Failed to retrieve file (status=#{status}): #{response_body}"
+      end
+
+      response_body || ''
+    end
+
+    # List the names of all stored files (PUT /mockserver/files/list).
+    #
+    # @return [Array<String>] the file names
+    def list_files
+      status, response_body = request('PUT', '/mockserver/files/list')
+      if status >= 400
+        raise Error, "Failed to list files (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
+
+    # Delete a stored file (PUT /mockserver/files/delete).
+    #
+    # An unknown file yields a 404 which raises an {Error}.
+    #
+    # @param name [String] the file name/key
+    # @return [nil]
+    def delete_file(name)
+      body = JSON.generate({ 'name' => name })
+      status, response_body = request('PUT', '/mockserver/files/delete', body)
+      if status == 404
+        raise Error, "File not found (status=404): #{name}"
+      end
+      if status >= 400
+        raise Error, "Failed to delete file (status=#{status}): #{response_body}"
+      end
+
+      nil
+    end
+
+    # -------------------------------------------------------------------
+    # Import (HAR / Postman)
+    # -------------------------------------------------------------------
+
+    # Import a HAR document as expectations (PUT /mockserver/import?format=har).
+    #
+    # @param har_json [String] the HAR JSON document (must not be blank)
+    # @return [Array<Expectation>] the upserted expectations
+    # @raise [ArgumentError] if +har_json+ is nil or blank
+    def import_har(har_json)
+      import_document(har_json, 'har')
+    end
+
+    # Import a Postman collection as expectations
+    # (PUT /mockserver/import?format=postman).
+    #
+    # @param collection_json [String] the Postman collection JSON (must not be blank)
+    # @return [Array<Expectation>] the upserted expectations
+    # @raise [ArgumentError] if +collection_json+ is nil or blank
+    def import_postman_collection(collection_json)
+      import_document(collection_json, 'postman')
+    end
+
+    # -------------------------------------------------------------------
+    # Operating mode (SIMULATE / SPY / CAPTURE)
+    # -------------------------------------------------------------------
+
+    # Valid operating modes (parallels +org.mockserver.mock.MockMode+).
+    MODE_SIMULATE = 'SIMULATE'
+    MODE_SPY = 'SPY'
+    MODE_CAPTURE = 'CAPTURE'
+
+    # Set the high-level operating mode (PUT /mockserver/mode?mode=<MODE>).
+    #
+    # +mode+ may be a Symbol or String (case-insensitive), one of
+    # +:simulate+/+:spy+/+:capture+ (or the {MODE_SIMULATE}, {MODE_SPY},
+    # {MODE_CAPTURE} constants). Setting the mode also flips the
+    # proxy-on-no-match behaviour on the server.
+    #
+    # @param mode [String, Symbol] the operating mode
+    # @return [Hash] response of the form
+    #   { "mode" => ..., "proxyUnmatchedRequests" => ... }
+    def set_mode(mode)
+      mode_value = mode.to_s.upcase
+      status, response_body = do_request(
+        'PUT', '/mockserver/mode', nil, { 'mode' => mode_value }
+      )
+      if status >= 400
+        raise Error, "Failed to set mode (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Read the current operating mode (GET /mockserver/mode).
+    #
+    # @return [Hash] response of the form
+    #   { "mode" => ..., "proxyUnmatchedRequests" => ... }
+    def retrieve_mode
+      status, response_body = request('GET', '/mockserver/mode')
+      if status >= 400
+        raise Error, "Failed to retrieve mode (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # -------------------------------------------------------------------
+    # WSDL -> expectations
+    # -------------------------------------------------------------------
+
+    # Generate expectations from a WSDL document (PUT /mockserver/wsdl).
+    #
+    # The WSDL XML is sent as the raw request body with an XML content type.
+    #
+    # @param wsdl [String] the WSDL document (XML, must not be blank)
+    # @return [Array<Expectation>] the generated (upserted) expectations
+    # @raise [ArgumentError] if +wsdl+ is nil or blank
+    def wsdl_expectation(wsdl)
+      if wsdl.nil? || wsdl.to_s.strip.empty?
+        raise ArgumentError, 'WSDL must not be empty'
+      end
+
+      status, response_body = request(
+        'PUT', '/mockserver/wsdl', wsdl.to_s, content_type: 'application/xml'
+      )
+      if status >= 400
+        raise Error, "Failed to generate WSDL expectations (status=#{status}): #{response_body}"
+      end
+
+      expectations_from_response(response_body)
+    end
+
     # Register a service-scoped HTTP chaos profile for an upstream host. The profile
     # is applied to every matched forward expectation to that host that does not
     # define its own chaos (an expectation's own chaos always wins). The host is
@@ -260,6 +573,419 @@ 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
+
+    # Fetch the end-of-run summary report for a load scenario run.
+    #
+    # Returns the report derived from the run's status snapshot (live while
+    # running, or the retained terminal snapshot once finished). With no +format+
+    # (or any value other than +"junit"+) the JSON report is parsed and returned
+    # as a Hash carrying counts, latency percentiles, the threshold verdict and
+    # per-threshold results. With +format: "junit"+ the raw JUnit-XML
+    # +<testsuite>+ document is returned as a String so a load run becomes a
+    # first-class CI test artifact.
+    #
+    # @param name [String] the unique scenario name
+    # @param format [String, nil] +"junit"+ for the JUnit-XML report, otherwise JSON
+    # @return [Hash, String] parsed JSON report (default) or the raw JUnit-XML String
+    # @raise [Error] if the scenario never ran (404) or another failure occurs
+    def get_load_scenario_report(name, format = nil)
+      query_params = {}
+      query_params['format'] = format if format
+      status, response_body = do_request(
+        'GET', "/mockserver/loadScenario/#{encode_path_segment(name)}/report", nil,
+        query_params.empty? ? nil : query_params
+      )
+      if status == 404
+        raise Error, "Load scenario report not found (status=404): #{name}"
+      end
+      if status >= 400
+        raise Error, "Failed to get load scenario report (status=#{status}): #{response_body}"
+      end
+
+      return response_body if format == 'junit'
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Generate (and register) a load scenario from an OpenAPI specification.
+    #
+    # Produces an editable scenario - one step per OpenAPI operation - and loads
+    # it into the registry under +name+ in the LOADED state; it generates no
+    # traffic and is allowed even when load generation is disabled.
+    #
+    # @param name [String] the generated scenario name (the unique registry key)
+    # @param spec_url_or_payload [String] OpenAPI spec as inline JSON/YAML, a URL,
+    #   or a file/classpath reference
+    # @param target [Hash, nil] explicit network target for every generated step
+    #   (e.g. { "host" => ..., "port" => ..., "scheme" => "http" })
+    # @param profile [LoadProfile, Hash, nil] optional traffic profile (a
+    #   conservative default is applied when omitted)
+    # @return [Hash] parsed response of the form
+    #   { "status" => "loaded", "name" => ..., "state" => ..., "scenario" => {...} }
+    def generate_load_scenario_from_openapi(name, spec_url_or_payload, target: nil, profile: nil)
+      payload = { 'name' => name, 'specUrlOrPayload' => spec_url_or_payload }
+      payload['target'] = target if target
+      payload['profile'] = profile.respond_to?(:to_h) ? profile.to_h : profile if profile
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/loadScenario/generateFromOpenAPI', body)
+      if status >= 400
+        raise Error, "Failed to generate load scenario from OpenAPI (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Generate (and register) a load scenario from recorded proxy traffic.
+    #
+    # Converts requests previously recorded by MockServer in proxy/recording mode
+    # into an editable scenario and loads it into the registry under +name+ in the
+    # LOADED state; it generates no traffic and is allowed even when load
+    # generation is disabled.
+    #
+    # @param name [String] the generated scenario name (the unique registry key)
+    # @param mode [String, nil] +VERBATIM+ (default) or +TEMPLATIZED+
+    # @param request_filter [HttpRequest, Hash, nil] optional matcher selecting
+    #   which recorded requests to include (absent means all)
+    # @param target [Hash, nil] explicit network target applied to every step
+    # @param max_steps [Integer, nil] optional cap on the number of VERBATIM steps
+    # @return [Hash] parsed response of the form
+    #   { "status" => "loaded", "name" => ..., "state" => ..., "scenario" => {...} }
+    def generate_load_scenario_from_recording(name, mode: nil, request_filter: nil,
+                                              target: nil, max_steps: nil)
+      payload = { 'name' => name }
+      payload['mode'] = mode if mode
+      payload['requestFilter'] = request_filter.respond_to?(:to_h) ? request_filter.to_h : request_filter if request_filter
+      payload['target'] = target if target
+      payload['maxSteps'] = max_steps if max_steps
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/loadScenario/generateFromRecording', body)
+      if status >= 400
+        raise Error, "Failed to generate load scenario from recording (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # -------------------------------------------------------------------
+    # SRE control plane: SLO verification + chaos experiments
+    # -------------------------------------------------------------------
+
+    # Evaluate a set of service-level objectives (SLOs) over a window
+    # (PUT /mockserver/verifySLO).
+    #
+    # The server encodes the verdict in the HTTP status: 200 for PASS or
+    # INCONCLUSIVE, 406 for FAIL, 400 for malformed criteria or when SLO tracking
+    # is disabled (+sloTrackingEnabled=false+). The decoded verdict Hash carries
+    # the overall +result+ and the per-objective +objectiveResults+ so callers can
+    # inspect why an SLO failed.
+    #
+    # +criteria+ may be any Hash already shaped to the +SloCriteria+ JSON contract
+    # (+name+, +window+, +minimumSampleCount+, +upstreamHosts+,
+    # +objectives+[{+sli+, +comparator+, +threshold+, +scope+}]) or an object that
+    # responds to +to_h+.
+    #
+    # @param criteria [Hash, #to_h] the SLO criteria
+    # @return [Hash] the SLO verdict (result PASS or INCONCLUSIVE)
+    # @raise [VerificationError] if the verdict is FAIL (HTTP 406)
+    # @raise [Error] if criteria are malformed or SLO tracking is disabled (HTTP 400),
+    #   or on any other failure
+    def verify_slo(criteria)
+      payload = criteria.respond_to?(:to_h) ? criteria.to_h : criteria
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/verifySLO', body)
+      if status == 406
+        raise VerificationError, (response_body && !response_body.empty? ? response_body : 'SLO verdict: FAIL')
+      end
+      if status == 400
+        raise Error, 'Invalid SLO criteria (or SLO tracking disabled — set ' \
+                     "sloTrackingEnabled=true on the server): #{response_body}"
+      end
+      if status >= 400
+        raise Error, "Failed to verify SLO (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Start a scheduled multi-stage chaos experiment
+    # (PUT /mockserver/chaosExperiment).
+    #
+    # The experiment is an ordered sequence of stages, each applying
+    # service-scoped chaos profiles to one or more hosts for a duration; stages
+    # progress automatically. Only one experiment may be active at a time;
+    # starting a new one stops the previous one.
+    #
+    # +experiment+ may be any Hash already shaped to the +ChaosExperiment+ JSON
+    # contract (+name+, +loop+, +stages+[{+durationMillis+, +profiles+{host:
+    # profile}}]) or an object that responds to +to_h+.
+    #
+    # @param experiment [Hash, #to_h] the experiment definition
+    # @return [Hash] the started status, e.g. { "status" => "started", "name" => ... }
+    # @raise [Error] if the experiment definition is invalid or chaos is disabled
+    #   (HTTP 400/403), or on any other failure
+    def start_chaos_experiment(experiment)
+      payload = experiment.respond_to?(:to_h) ? experiment.to_h : experiment
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/chaosExperiment', body)
+      if status == 403
+        raise Error, 'Chaos experiment rejected (status=403): chaos is disabled on the server'
+      end
+      if status >= 400
+        raise Error, "Failed to start chaos experiment (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    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 +1096,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 +1464,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 +1474,52 @@ 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
+    # Import a document (HAR/Postman/Pact) via PUT /mockserver/import?format=<format>
+    # and return the upserted expectations.
+    def import_document(json, format)
+      if json.nil? || json.to_s.strip.empty?
+        raise ArgumentError, "import #{format} document must not be empty"
+      end
+
+      status, response_body = do_request(
+        'PUT', '/mockserver/import', json.to_s, { 'format' => format }
+      )
+      if status >= 400
+        raise Error, "Failed to import #{format} (status=#{status}): #{response_body}"
+      end
+
+      expectations_from_response(response_body)
+    end
+
+    # @api private
+    # Parse a JSON array of expectations from a control-plane response body.
+    def expectations_from_response(response_body)
+      if response_body && !response_body.empty?
+        parsed = JSON.parse(response_body)
+        return parsed.map { |e| Expectation.from_hash(e) } if parsed.is_a?(Array)
+      end
+      []
     end
 
     # @api private
@@ -741,7 +1544,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 +1558,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}"