mockserver-client 7.0.0 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97517808097f2af911f727db3decbafcab8454285325b141ad5899a53af70be1
-  data.tar.gz: 60b5bff4ef90906b229064f23b1593bec547dc428b9d93c61b387d29a2615dd0
+  metadata.gz: f1a47589dbc527bf772961f968c2235d9b64ebc13fd8a1f963e143e50319db9f
+  data.tar.gz: 85aa291fefefdce077d8f4eaca22a5fd56d473628ec819c2029fae9f8e91aa4e
 SHA512:
-  metadata.gz: d91bb153b43f523a60812dc4f100fb1e7deb04c6ddc6353266d632f8f074df3683e0292d9cd77efb464034e618d4e4d63fafc3b11b333c009098cc5b48b49684
-  data.tar.gz: 7484d0dfa3e38edb7ad83dd2bb760a2b17dd2c4f474538e5673630f9fd28c056f4f7c2d2389ddbda2aa56f43eb052915cb4b5a432b4f15e7594e4db54cf92c9f
+  metadata.gz: 1b5adcd45c05bc417a62ad3a6fab6e00b42ef1180b7a89cc0084f972bb83aac5d68832d2e02da83d899a7fb511a71fb2ff87576eba4487f51a0bfafc546d5c06
+  data.tar.gz: dd83794b0fd9ad0ffc7439b505bc7ff3c8461e076d6acf209ce8b273b6ca4d233c19638ece936faaacf43e196d39a1a9220206c1a559dbe86dd2154a15b078e8

data/README.md

@@ -99,6 +99,222 @@ 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.
+
+### Register a breakpoint
+
+```ruby
+client = MockServer::Client.new('localhost', 1080)
+
+# REQUEST phase only
+bp_id = client.add_request_breakpoint(
+  MockServer::HttpRequest.new(path: '/api/.*'),
+  ->(request) { request }  # continue unchanged (or return HttpResponse to abort)
+)
+
+# REQUEST + RESPONSE
+bp_id = client.add_request_and_response_breakpoint(
+  MockServer::HttpRequest.new(path: '/api/.*'),
+  ->(request) { request },                      # REQUEST handler
+  ->(request, response) { response }            # RESPONSE handler
+)
+
+# All phases with stream frame handler
+bp_id = client.add_breakpoint(
+  MockServer::HttpRequest.new(path: '/stream/.*'),
+  %w[REQUEST RESPONSE RESPONSE_STREAM INBOUND_STREAM],
+  request_handler: ->(request) { request },
+  response_handler: ->(request, response) { response },
+  stream_frame_handler: ->(frame) { { 'action' => 'CONTINUE' } }
+  # Other actions: MODIFY (with body), DROP, INJECT (with body), CLOSE
+)
+```
+
+### Manage breakpoints
+
+```ruby
+# List all matchers
+matchers = client.list_breakpoint_matchers  # {"matchers" => [...]}
+
+# Remove a specific matcher
+client.remove_breakpoint_matcher(bp_id)
+
+# Clear all matchers
+client.clear_breakpoint_matchers
+```
+
+## Start / Launch MockServer
+
+The Ruby client can download and launch a local MockServer instance directly -- no Java installation and no Docker required. The launcher downloads a self-contained platform bundle (`mockserver-<version>-<os>-<arch>`) from the GitHub Release, verifies its SHA-256, caches it per-user, and starts it.
+
+### Quick start
+
+```ruby
+require 'mockserver-client'
+
+# Download (first run) and start MockServer on port 1080
+handle = MockServer::BinaryLauncher.start(port: 1080)
+puts "MockServer running on port #{handle.port}, PID #{handle.pid}"
+
+# ... use MockServer ...
+
+handle.stop
+```
+
+### Just ensure the binary is present
+
+```ruby
+launcher_path = MockServer::BinaryLauncher.ensure_launcher
+```
+
+### Specify a version
+
+```ruby
+handle = MockServer::BinaryLauncher.start(port: 1080, version: '7.2.0')
+```
+
+### API reference
+
+| Method / Class | Description |
+|---|---|
+| `MockServer::BinaryLauncher.ensure_launcher(version:, log:)` | Download, verify, cache, and return the launcher path. Defaults to `MockServer::VERSION`. |
+| `MockServer::BinaryLauncher.start(port:, version:, extra_args:, log:)` | Ensure the binary and start MockServer. Returns a `ServerHandle`. |
+| `MockServer::BinaryLauncher::ServerHandle` | Handle to the running process. Methods: `stop(timeout:)`, `running?`. Attributes: `pid`, `port`, `launcher`. |
+
+### Supported platforms
+
+| OS | Architecture |
+|---|---|
+| Linux | x86_64, aarch64 |
+| macOS (darwin) | x86_64, aarch64 |
+| Windows | x86_64, aarch64 |
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MOCKSERVER_BINARY_BASE_URL` | Mirror host for the release assets (corporate / air-gapped networks) |
+| `MOCKSERVER_BINARY_CACHE` | Override the cache directory (default: `~/.cache/mockserver/binaries` on Unix) |
+| `MOCKSERVER_SKIP_BINARY_DOWNLOAD` | Fail instead of downloading (use with a pre-seeded cache in CI) |
+
+### Version
+
+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