mockserver-client 7.1.0 → 7.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b853b4ba04e3473e6e664a0f1a2f6b4f0a8146f624a2308a19349fe94f536d9e
-  data.tar.gz: 848eedd40df3e43ac6299250c92d4f30ee1b7fbeedb15699cd7254af20fcb6a4
+  metadata.gz: fa28c69e849b63f6fa75a1f57f939a348cf30d3032d6b1dfb040276dbd51eb6b
+  data.tar.gz: 188c6469fc18b0ed51b4099a652d68a3b00b0bbccda233265b282e9d08e5c677
 SHA512:
-  metadata.gz: a2c283e6f9ed9fb935ff296a84298abc7c73768609c0601b8079e20441ebd25ca1029256a7c21a968578ef3f9ea28777b7d07dd20c7d8b4387031298389c4eb8
-  data.tar.gz: 77bc8cf3f5e4e919ba758c4c720cbf9795600094d7bfc41faa66b5571c0ea2b7ee39fa3a4f6871726ffc3a6468f84defb34afce05b33203b734e1cc1ac1c3c53
+  metadata.gz: c4d3d24b31236d09f8684b10bc114e6cb2154f532ff230453f9e3f566ecbd271ef4c770a8d3f6db6a2476bd89efdd529471ba4fb46ca2ebe0e89e8a97f2fc63e
+  data.tar.gz: daef70802e8ee57033d185f74c580c3b61d87eb97fc0c74ab31288f345e9fe86c9823b6ff6f90231d2066c8b9f05a6446d5ba06a7d917bdb61dd1215ef2094ae

data/README.md

@@ -99,6 +99,150 @@ 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.
+
+## A2A Mocking
+
+`MockServer::A2A.a2a_mock` builds the set of expectations needed to emulate an
+A2A (Agent-to-Agent) agent: an agent card served at `/.well-known/agent.json`
+plus JSON-RPC 2.0 `tasks/send`, `tasks/get`, and `tasks/cancel` over `POST
+<path>`. It optionally adds SSE streaming, push-notification config + delivery,
+per-message custom task handlers, and advertised skills.
+
+```ruby
+MockServer::A2A.a2a_mock('/a2a')
+               .with_agent_name('WeatherAgent')
+               .with_agent_description('Forecasts the weather')
+               .with_skill('weather')
+                 .with_name('Weather lookup')
+                 .with_tag('forecast')
+                 .with_example('What is the weather in Paris?')
+               .and_then
+               .with_streaming
+               .with_push_notifications('http://localhost:1234/a2a/callback')
+               .on_task_send
+                 .matching_message('forecast')
+                 .responding_with('Sunny, 25C')
+               .and_then
+               .apply_to(client)
+```
+
+When push notifications are configured, each `tasks/send` both returns the
+JSON-RPC task response to the caller *and* POSTs the completed task to the
+webhook URL. As with MCP mocking, `build` returns the raw expectation Hashes if
+you prefer to register them yourself.
+
+## SRE Control Plane (SLO + Chaos)
+
+Verify service-level objectives and drive scheduled chaos experiments against
+the running MockServer:
+
+```ruby
+# Evaluate SLOs over a window. Returns the verdict Hash on PASS/INCONCLUSIVE;
+# raises MockServer::VerificationError on FAIL (HTTP 406).
+verdict = client.verify_slo(
+  'name' => 'checkout-latency',
+  'window' => 'PT5M',
+  'minimumSampleCount' => 100,
+  'objectives' => [
+    { 'sli' => 'p99_latency_ms', 'comparator' => 'LESS_THAN', 'threshold' => 250 }
+  ]
+)
+
+# Start a scheduled multi-stage chaos experiment (only one may be active).
+client.start_chaos_experiment(
+  'name' => 'payments-brownout',
+  'stages' => [
+    { 'durationMillis' => 60_000, 'profiles' => { 'payments.svc' => 'LATENCY' } }
+  ]
+)
+```
+
+SLO tracking must be enabled on the server (`sloTrackingEnabled=true`) or
+`verify_slo` raises `MockServer::Error` on HTTP 400.
+
 ## 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 +316,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.3.0')
 ```
 
 ### API reference
@@ -203,6 +347,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