mockserver-client 7.0.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97517808097f2af911f727db3decbafcab8454285325b141ad5899a53af70be1
-  data.tar.gz: 60b5bff4ef90906b229064f23b1593bec547dc428b9d93c61b387d29a2615dd0
+  metadata.gz: b853b4ba04e3473e6e664a0f1a2f6b4f0a8146f624a2308a19349fe94f536d9e
+  data.tar.gz: 848eedd40df3e43ac6299250c92d4f30ee1b7fbeedb15699cd7254af20fcb6a4
 SHA512:
-  metadata.gz: d91bb153b43f523a60812dc4f100fb1e7deb04c6ddc6353266d632f8f074df3683e0292d9cd77efb464034e618d4e4d63fafc3b11b333c009098cc5b48b49684
-  data.tar.gz: 7484d0dfa3e38edb7ad83dd2bb760a2b17dd2c4f474538e5673630f9fd28c056f4f7c2d2389ddbda2aa56f43eb052915cb4b5a432b4f15e7594e4db54cf92c9f
+  metadata.gz: a2c283e6f9ed9fb935ff296a84298abc7c73768609c0601b8079e20441ebd25ca1029256a7c21a968578ef3f9ea28777b7d07dd20c7d8b4387031298389c4eb8
+  data.tar.gz: 77bc8cf3f5e4e919ba758c4c720cbf9795600094d7bfc41faa66b5571c0ea2b7ee39fa3a4f6871726ffc3a6468f84defb34afce05b33203b734e1cc1ac1c3c53

data/README.md

@@ -99,6 +99,110 @@ All 25 domain model classes are available under the `MockServer` module:
 - `Ports`
 - `RequestDefinition` (alias for `HttpRequest`)
 
+## 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.1.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.
+
 ## License
 
 Apache-2.0