mockserver-client 6.1.0 → 7.1.0

data/lib/mockserver/client.rb

@@ -148,13 +148,126 @@ module MockServer
       close
     end
 
-    # Verify that a request was received.
-    # @param request [HttpRequest]
+    # -------------------------------------------------------------------
+    # Clock Control
+    # -------------------------------------------------------------------
+
+    # Freeze the server clock at the given ISO-8601 instant.
+    # If +instant+ is nil, the clock freezes at the current real time.
+    # @param instant [String, nil] ISO-8601 instant (e.g. "2025-01-15T09:30:00Z")
+    # @return [Hash] response with status, currentInstant, currentEpochMillis
+    def freeze_clock(instant = nil)
+      payload = { 'action' => 'freeze' }
+      payload['instant'] = instant if instant
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/clock', body)
+      if status >= 400
+        raise Error, "Failed to freeze clock (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Advance the frozen clock by +duration_millis+ milliseconds.
+    # @param duration_millis [Integer]
+    # @return [Hash] response with status, currentInstant, currentEpochMillis
+    def advance_clock(duration_millis)
+      body = JSON.generate({ 'action' => 'advance', 'durationMillis' => duration_millis })
+      status, response_body = request('PUT', '/mockserver/clock', body)
+      if status >= 400
+        raise Error, "Failed to advance clock (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Reset the server clock to real wall-clock time.
+    # @return [Hash] response with status, currentInstant, currentEpochMillis
+    def reset_clock
+      body = JSON.generate({ 'action' => 'reset' })
+      status, response_body = request('PUT', '/mockserver/clock', body)
+      if status >= 400
+        raise Error, "Failed to reset clock (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Query the current clock status.
+    # @return [Hash] with currentInstant, currentEpochMillis, frozen
+    def clock_status
+      status, response_body = request('GET', '/mockserver/clock')
+      if status >= 400
+        raise Error, "Failed to get clock status (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(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
+    # matched case-insensitively, ignoring any +:port+.
+    # @param host [String] the upstream host to break
+    # @param chaos [HttpChaosProfile] the chaos profile to apply
+    # @param ttl_millis [Integer, nil] if set, the chaos auto-reverts after this many ms
+    # @return [Hash] response with status and host
+    def set_service_chaos(host, chaos, ttl_millis = nil)
+      payload = { 'host' => host, 'chaos' => chaos.to_h }
+      payload['ttlMillis'] = ttl_millis unless ttl_millis.nil?
+      body = JSON.generate(payload)
+      status, response_body = request('PUT', '/mockserver/serviceChaos', body)
+      if status >= 400
+        raise Error, "Failed to set service chaos (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Remove the service-scoped chaos profile registered for +host+.
+    # @param host [String]
+    # @return [Hash]
+    def remove_service_chaos(host)
+      body = JSON.generate({ 'host' => host, 'remove' => true })
+      status, response_body = request('PUT', '/mockserver/serviceChaos', body)
+      if status >= 400
+        raise Error, "Failed to remove service chaos (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Clear all service-scoped chaos profiles.
+    # @return [Hash]
+    def clear_service_chaos
+      body = JSON.generate({ 'clear' => true })
+      status, response_body = request('PUT', '/mockserver/serviceChaos', body)
+      if status >= 400
+        raise Error, "Failed to clear service chaos (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Query the current service-scoped chaos registrations.
+    # @return [Hash] of the form { "services" => { host => profile, ... } }
+    def service_chaos_status
+      status, response_body = request('GET', '/mockserver/serviceChaos')
+      if status >= 400
+        raise Error, "Failed to get service chaos (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Verify that a request (and optionally a response) was received.
+    # @param request [HttpRequest, nil]
     # @param times [VerificationTimes, nil]
+    # @param response [HttpResponse, nil]
     # @return [nil]
     # @raise [VerificationError] if verification fails (HTTP 406)
-    def verify(request, times: nil)
-      verification = Verification.new(http_request: request, times: times)
+    def verify(request = nil, times: nil, response: nil)
+      verification = Verification.new(http_request: request, http_response: response, times: times)
       body = JSON.generate(verification.to_h)
       status, response_body = do_request('PUT', '/mockserver/verify', body)
       if status == 406
@@ -170,10 +283,14 @@ module MockServer
 
     # Verify that requests were received in sequence.
     # @param requests [Array<HttpRequest>]
+    # @param responses [Array<HttpResponse>, nil] index-aligned response matchers
     # @return [nil]
     # @raise [VerificationError] if verification fails (HTTP 406)
-    def verify_sequence(*requests)
-      verification = VerificationSequence.new(http_requests: requests.to_a)
+    def verify_sequence(*requests, responses: nil)
+      verification = VerificationSequence.new(
+        http_requests: requests.empty? ? nil : requests.to_a,
+        http_responses: responses
+      )
       body = JSON.generate(verification.to_h)
       status, response_body = request('PUT', '/mockserver/verifySequence', body)
       if status == 406
@@ -364,6 +481,120 @@ module MockServer
       ForwardChainExpectation.new(self, expectation)
     end
 
+    # -------------------------------------------------------------------
+    # Breakpoint matcher management
+    # -------------------------------------------------------------------
+
+    # Register a breakpoint matcher with callback handlers.
+    # The callback WebSocket is opened lazily and reused.
+    #
+    # @param matcher [HttpRequest] the request definition to match
+    # @param phases [Array<String>] e.g. ["REQUEST", "RESPONSE"]
+    # @param request_handler [Proc, nil] handler for REQUEST phase
+    # @param response_handler [Proc, nil] handler for RESPONSE phase
+    # @param stream_frame_handler [Proc, nil] handler for streaming phases
+    # @return [String] the server-assigned breakpoint matcher id
+    def add_breakpoint(matcher, phases,
+                       request_handler: nil, response_handler: nil,
+                       stream_frame_handler: nil)
+      raise ArgumentError, 'add_breakpoint requires a non-nil matcher' if matcher.nil?
+      raise ArgumentError, 'add_breakpoint requires a non-empty phases array' if phases.nil? || phases.empty?
+
+      ws_client = ensure_breakpoint_websocket
+      client_id = ws_client.client_id
+
+      body = JSON.generate({
+        'httpRequest' => matcher.to_h,
+        'phases' => phases,
+        'clientId' => client_id
+      })
+      status, response_body = request('PUT', '/mockserver/breakpoint/matcher', body)
+      if status >= 400
+        raise Error, "Failed to register breakpoint matcher (status=#{status}): #{response_body}"
+      end
+
+      parsed = response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+      breakpoint_id = parsed['id']
+      raise Error, 'Server did not return a breakpoint id' unless breakpoint_id
+
+      # Install per-breakpoint-id handlers
+      ws_client.set_breakpoint_request_handler(breakpoint_id, request_handler) if request_handler
+      ws_client.set_breakpoint_response_handler(breakpoint_id, response_handler) if response_handler
+      ws_client.set_breakpoint_stream_frame_handler(breakpoint_id, stream_frame_handler) if stream_frame_handler
+
+      breakpoint_id
+    end
+
+    # Convenience: register a REQUEST-only breakpoint.
+    # @param matcher [HttpRequest]
+    # @param request_handler [Proc]
+    # @return [String]
+    def add_request_breakpoint(matcher, request_handler)
+      add_breakpoint(matcher, ['REQUEST'], request_handler: request_handler)
+    end
+
+    # Convenience: register a REQUEST+RESPONSE breakpoint.
+    # @param matcher [HttpRequest]
+    # @param request_handler [Proc]
+    # @param response_handler [Proc]
+    # @return [String]
+    def add_request_and_response_breakpoint(matcher, request_handler, response_handler)
+      add_breakpoint(matcher, %w[REQUEST RESPONSE],
+                     request_handler: request_handler,
+                     response_handler: response_handler)
+    end
+
+    # List all registered breakpoint matchers.
+    # @return [Hash] e.g. {"matchers" => [{...}, ...]}
+    def list_breakpoint_matchers
+      status, response_body = request('GET', '/mockserver/breakpoint/matchers')
+      if status >= 400
+        raise Error, "Failed to list breakpoint matchers (status=#{status}): #{response_body}"
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Remove a breakpoint matcher by id.
+    # @param breakpoint_id [String]
+    # @return [Hash]
+    def remove_breakpoint_matcher(breakpoint_id)
+      raise ArgumentError, 'remove_breakpoint_matcher requires a non-empty id' if breakpoint_id.nil? || breakpoint_id.empty?
+
+      body = JSON.generate({ 'id' => breakpoint_id })
+      status, response_body = request('PUT', '/mockserver/breakpoint/matcher/remove', body)
+      if status >= 400
+        raise Error, "Failed to remove breakpoint matcher (status=#{status}): #{response_body}"
+      end
+
+      # Remove client-side handlers
+      @websocket_mutex.synchronize do
+        @websocket_clients.each do |ws|
+          ws.remove_breakpoint_handlers(breakpoint_id) if ws.respond_to?(:remove_breakpoint_handlers)
+        end
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
+    # Clear all registered breakpoint matchers.
+    # @return [Hash]
+    def clear_breakpoint_matchers
+      status, response_body = request('PUT', '/mockserver/breakpoint/matcher/clear')
+      if status >= 400
+        raise Error, "Failed to clear breakpoint matchers (status=#{status}): #{response_body}"
+      end
+
+      # Clear client-side handlers
+      @websocket_mutex.synchronize do
+        @websocket_clients.each do |ws|
+          ws.clear_breakpoint_handlers if ws.respond_to?(:clear_breakpoint_handlers)
+        end
+      end
+
+      response_body && !response_body.empty? ? JSON.parse(response_body) : {}
+    end
+
     # -------------------------------------------------------------------
     # Callback methods
     # -------------------------------------------------------------------
@@ -418,6 +649,32 @@ module MockServer
 
     private
 
+    # @api private
+    # Ensure a callback WS is connected for breakpoint use, returning it.
+    def ensure_breakpoint_websocket
+      # Hold the mutex for the whole check-create-append so two concurrent
+      # add_breakpoint calls cannot both create a breakpoint WS (TOCTOU).
+      # Breakpoint WS creation is rare, so blocking on connect under the lock
+      # is acceptable.
+      @websocket_mutex.synchronize do
+        existing = @websocket_clients.find { |ws| ws.instance_variable_get(:@is_breakpoint_ws) }
+        return existing if existing
+
+        ws_client = WebSocketClient.new
+        ws_client.connect(
+          @host, @port,
+          context_path: @context_path,
+          secure: @secure,
+          ca_cert_path: @ca_cert_path,
+          tls_verify: @tls_verify
+        )
+        ws_client.instance_variable_set(:@is_breakpoint_ws, true)
+        ws_client.listen
+        @websocket_clients << ws_client
+        ws_client
+      end
+    end
+
     # @api private
     def register_websocket_callback(callback_type, callback_fn, forward_response_fn = nil)
       ws_client = WebSocketClient.new

data/lib/mockserver/forward_chain_expectation.rb

@@ -29,6 +29,14 @@ module MockServer
       self
     end
 
+    # Set a declarative HTTP chaos/fault injection profile.
+    # @param chaos [HttpChaosProfile]
+    # @return [self]
+    def with_chaos(chaos)
+      @expectation.chaos = chaos
+      self
+    end
+
     # Set the response action. Accepts an HttpResponse, HttpTemplate, or
     # a Proc/lambda callback.
     # @param response_or_callback [HttpResponse, HttpTemplate, Proc]
@@ -113,5 +121,92 @@ module MockServer
       @expectation.http_websocket_response = websocket_response
       @client.upsert(@expectation)
     end
+
+    # Set a gRPC stream response action.
+    # @param grpc_stream_response [GrpcStreamResponse]
+    # @return [Array<Expectation>]
+    def respond_with_grpc_stream(grpc_stream_response)
+      unless grpc_stream_response.is_a?(GrpcStreamResponse)
+        raise TypeError,
+              "Expected GrpcStreamResponse, got #{grpc_stream_response.class.name}"
+      end
+      @expectation.grpc_stream_response = grpc_stream_response
+      @client.upsert(@expectation)
+    end
+
+    # Set a gRPC bidi streaming response action.
+    # @param grpc_bidi_response [GrpcBidiResponse]
+    # @return [Array<Expectation>]
+    def respond_with_grpc_bidi(grpc_bidi_response)
+      unless grpc_bidi_response.is_a?(GrpcBidiResponse)
+        raise TypeError,
+              "Expected GrpcBidiResponse, got #{grpc_bidi_response.class.name}"
+      end
+      @expectation.grpc_bidi_response = grpc_bidi_response
+      @client.upsert(@expectation)
+    end
+
+    # Set a binary response action.
+    # @param binary_response [BinaryResponse]
+    # @return [Array<Expectation>]
+    def respond_with_binary(binary_response)
+      unless binary_response.is_a?(BinaryResponse)
+        raise TypeError,
+              "Expected BinaryResponse, got #{binary_response.class.name}"
+      end
+      @expectation.binary_response = binary_response
+      @client.upsert(@expectation)
+    end
+
+    # Set a DNS response action.
+    # @param dns_response [DnsResponse]
+    # @return [Array<Expectation>]
+    def respond_with_dns(dns_response)
+      unless dns_response.is_a?(DnsResponse)
+        raise TypeError,
+              "Expected DnsResponse, got #{dns_response.class.name}"
+      end
+      @expectation.dns_response = dns_response
+      @client.upsert(@expectation)
+    end
+
+    # Set a forward template action.
+    # @param template [HttpTemplate]
+    # @return [Array<Expectation>]
+    def forward_with_template(template)
+      unless template.is_a?(HttpTemplate)
+        raise TypeError,
+              "Expected HttpTemplate, got #{template.class.name}"
+      end
+      @expectation.http_forward_template = template
+      @client.upsert(@expectation)
+    end
+
+    # Set a forward class callback action.
+    # @param class_callback [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
+
+    # Set an ordered multi-action pipeline of steps.
+    #
+    # Exactly one step must have +responder: true+; that step produces the
+    # HTTP response. All other steps are side-effects executed in order.
+    # @param steps [Array<ExpectationStep>]
+    # @return [Array<Expectation>]
+    def with_steps(steps)
+      unless steps.is_a?(Array) && steps.all? { |s| s.is_a?(ExpectationStep) }
+        raise TypeError, 'Expected an Array of ExpectationStep objects'
+      end
+
+      @expectation.steps = steps
+      @client.upsert(@expectation)
+    end
   end
 end