mockserver-client 7.2.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
@@ -416,6 +729,169 @@ module MockServer
       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)
     # -------------------------------------------------------------------
@@ -1018,6 +1494,34 @@ module MockServer
       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
     def build_http(uri)
       http = Net::HTTP.new(uri.host, uri.port)