restless-sdk 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a346b73df699fa4b309117f63c42f284a971d392fff96ac0321510c9b5c06327
-  data.tar.gz: a57d20173e1a974bc5fde6b9c7dd6c20e4239f4f7c70cd572863f97628d9ddfc
+  metadata.gz: f2ab526956a3600f1166a74828a06c9b01b5a0ce2a17808bdba530f6ea344ee9
+  data.tar.gz: 4e5776ac3709c2f1e8b5d0a710d45335927a331eddb0cd9b027a0bd8305c42ee
 SHA512:
-  metadata.gz: 34762d9a43d3294b0448c75a683a158d5ce241d88961177bfbcc215969bf9b4a6f6e0f362cfdb31973e8d05de827a8c56d243ab224132b0f3f3a96c4f7ba0c1b
-  data.tar.gz: bbc49f5ffc1a24e563a4cc609cc6f3a95d43b3f3d4090c78826b83c68cdb4ec5d4aab36cfd7b795ce033ed2e5796d56f0a89c3196d40b49b6227affa0ee13487
+  metadata.gz: ce0a15152665dba1b04f64377e6b6dc2e773f128b48ae6fdcddedc0f35fc34df3c40716470857f16c35b8409793b03af07e2bda387af9a24ba8636bcc419149c
+  data.tar.gz: 395c589c7b35aa121e9612fd0142e32df3c2f0dc75cc3eeb8607912b73d279ef046a3478f4d63e7a548d813ca4a33ae1212a18bef2a7b60f3bdb0ba88d306a55

data/CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 | | |
 |---|---|
-| **Spec version** | 1.0.1 |
+| **Spec version** | 1.1.0 |
 | **Level** | L2 (core + batching, caches, injection, safety) |
 | **Reference** | `restlesshq/node` (`@restlessai/sdk`) |
 | **Driver** | `ruby exe/restless-conformance` |
@@ -31,9 +31,9 @@ node ../node/spec/harness/fuzz.mjs \
   --iterations 8000 --seed 24301
 ```
 
-Current status: **206 vectors, 198 passed, 0 failed, 8 skipped.** Zero
-divergence across 34,918 fuzz comparisons on five seeds (24301, 1, 4242,
-99991, 777).
+Current status: **252 vectors, 244 passed, 0 failed, 8 skipped.** Zero
+divergence across 35,926 fuzz comparisons on five seeds (24301, 1, 4242,
+99991, 777), including the four sampling ops.
 
 The 8 skips are cases outside this implementation's dialect, not gaps:
 
@@ -71,6 +71,11 @@ the reference. They are the reason this SDK is byte-compatible.
 | FP-042 | `project_relative` splits on `/` and scans BACKWARDS from the second-to-last segment, so the LAST project dir wins and a deployment root named `/app` (Docker `WORKDIR`, Heroku) cannot survive into the key. `split("/", -1)`: without the negative limit Ruby drops the trailing empty field, so `/proj/src/` would miss `src` here and match it in JavaScript. |
 | FP-043 | Ruby's `Exception#backtrace` is innermost-FIRST, like v8 and Go and unlike a Python traceback, so the walk goes forwards. Verified empirically in `test/test_stack_frames.rb` rather than assumed. |
 | FP-044 | Frames are `path:line:in \`method'` (`'method'` from Ruby 3.4); both quote styles parse. `block (N levels) in foo` is normalized to `block in foo`, since the nesting count behaves like a line number. Skips are matched by FILE PATH: the SDK's own directory (resolved from `__dir__`), `RbConfig`'s stdlib dirs, `Gem.path`, any `/gems/` segment, and `<internal:` frames. Never by module or class name - a name check would also skip a customer's own Restless-flavoured code and would fail to skip this gem when vendored under another constant. |
+| SAMPLE-002 | `(r.to_f * 10000 + 0.5).floor`, never `round`. JSON hands over `1` as an Integer and `0.5` as a Float, so the value goes through `to_f` first; a quantized rate is a Float, which is why a rate of 0 serializes as `0.0` (the same JSON number). `true` is not `Numeric` in Ruby, so it needs no special case to be invalid. |
+| SAMPLE-010 | Keys are trimmed of U+0020 only (`sub(/\A +/, "")`), never `strip`, which would also eat a trailing tab or NUL and turn the invalid key `"GET /x\t"` into a valid one. The method is uppercased with `upcase(:ascii)`. |
+| SAMPLE-032 | The decision is the first thing `finish` does. Rack returns status and headers together before the server writes anything, so unlike Node there is no `writeHead` to intercept: none of the SDK's headers exist yet, even for a streaming body or a hijack. A drop returns the app's response triple untouched, body unread. |
+| SAMPLE-040 | The rate token is `format("0.%04d", k)` from the integer step count. `String#sort` compares bytes, which is the order the contract asks for. |
+| Section 14 | `sampling:` accepts symbol or string keys (`default:`, `"routes"`) and symbol modes (`:off`). Neither can come from the settings file or the driver, so the vectors are unaffected. |
 | INJECT-005 | `Text.ws_trim`, not `String#strip`. Ruby's strip removes NUL and leaves NBSP; the contract wants exactly the PRIM-002 set. |
 | BATCH-003 | The environment indicator is `RESTLESS_ENV`, then `RACK_ENV`, then `RAILS_ENV`. Ruby has three spellings in the wild and no single winner. |
 | BATCH-008 | Test detection keys on those same variables being `test`, plus `RSpec::Core`, `Minitest::Test` and `Test::Unit::TestCase` being defined. |

data/README.md

@@ -1,7 +1,9 @@
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/restless-init-dark.svg">
-  <img width="100%" src="docs/restless-init.svg" alt="Restless">
-</picture>
+<a href="https://restless.ai">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/restless-init-dark.svg">
+    <img width="100%" src="docs/restless-init.svg" alt="Restless">
+  </picture>
+</a>
 
 Run in your codebase to get started:
 
@@ -94,6 +96,50 @@ and body your app produced rather than an inner layer's.
   request before your handler runs, or
   `{ block: { status: 402, message: "Payment required" } }` to pick the
   status.
+- **Sampling.** Send less for noisy endpoints without losing your counts.
+  See below.
+
+## Sampling
+
+Each endpoint is `"on"` (the default), `"off"`, `"errors"` (only status
+>= 400), or a rate such as `0.1`: that fraction of successful requests is
+logged in full and the rest without bodies, so counts, latency and
+per-customer usage stay exact. Errors are never sampled.
+
+```ruby
+CLIENT = Restless.new(ENV["RESTLESS_KEY"], sampling: {
+  default: "on",
+  routes: {
+    "GET /health" => "off",
+    "GET /status" => "errors",
+    "GET /pets" => 0.1,
+    "* /pets/{id}" => 0.5,
+  },
+})
+```
+
+| mode | successes (< 400) | errors (>= 400) |
+|---|---|---|
+| `"on"` (default) | full log | full log |
+| a rate `0` to `1` | that fraction in full, the rest without bodies | full log |
+| `"errors"` | nothing sent | full log |
+| `"off"` | nothing sent | nothing sent |
+
+Keys are a method (or `*` for any) and the route pattern your framework
+matched (see [Route patterns](#route-patterns)); `{id}` and `:id` are the
+same, and `HEAD` does not fall back to `GET`. A request with no route
+pattern uses `default`. Symbols work for the modes (`:off`, `:errors`).
+
+The same `sampling` block can live under an API entry in
+`.restless/settings.json`, and the option in code wins per route. A request
+that sends nothing (an `"off"` route, or a success on an `"errors"` route)
+also gets no `x-request-id` header and no debug headers, since there is no
+log for them to point at. An invalid value never raises: it falls back to
+`"on"` and says so under `DEBUG=restless`.
+
+With sampling configured, the SDK tells Restless the configuration once, on
+the first request it serves (never at boot), so the dashboard can show an
+`"off"` endpoint as off rather than as idle.
 
 ## The setup callback
 
@@ -153,7 +199,7 @@ re-raised untouched, leaving your own error handling completely unaffected.
 
 ## Conformance
 
-This SDK implements version 1.0.0 of the Restless SDK Contract at level L2,
+This SDK implements version 1.1.0 of the Restless SDK Contract at level L2,
 and is verified against the shared cross-language conformance vectors and a
 differential fuzzer run against the reference implementation. See
 [CONFORMANCE.md](./CONFORMANCE.md).

data/install.md

@@ -196,24 +196,25 @@ Read at startup, walking up from the working directory. Created and owned by the
 ```json
 {
   "version": 1,
-  "projectId": "<team/workspace uuid>",
   "apis": [
     {
       "id": "<api uuid>",
       "name": "Public API",
       "rootDir": ".",
+      "projectId": "<restless project uuid>",
       "oasFile": ".restless/openapi.yaml",
       "framework": "rails",
       "language": "ruby",
       "baseUrl": "https://api.example.com",
       "requestIdPrefix": "PUB",
-      "redact": { "headers": ["x-company-auth"], "bodyKeys": ["ssh_private_key"] }
+      "redact": { "headers": ["x-company-auth"], "bodyKeys": ["ssh_private_key"] },
+      "sampling": { "default": "on", "routes": { "GET /health": "off", "GET /pets": 0.1 } }
     }
   ]
 }
 ```
 
-The SDK reads `requestIdPrefix` and `redact` from the matching entry. Pick one when several are defined:
+The SDK reads `requestIdPrefix`, `redact` and `sampling` (§8a, merged with the `sampling:` option, code winning per route) from the matching entry. The rest, `projectId` included - which is per-API and never top-level - belongs to the CLI, not the runtime. Pick one when several are defined:
 
 ```ruby
 Restless.new(ENV["RESTLESS_KEY"], api: "Public API")
@@ -243,11 +244,35 @@ Sentinel format, which the dashboard pattern-matches:
 
 Bodies are capped at **256 KiB** (UTF-8 bytes) and truncated with `[...TRUNCATED: original N bytes]`.
 
+## 8a. Sampling (off by default)
+
+Without a `sampling` block every request is logged in full. With one, each endpoint gets a mode:
+
+| mode | successes (< 400) | errors (>= 400) |
+|---|---|---|
+| `"on"` (default) | full log | full log |
+| a rate `0` to `1` | that fraction in full, the rest without bodies | full log |
+| `"errors"` | nothing sent | full log |
+| `"off"` | nothing sent | nothing sent |
+
+```ruby
+Restless.new(ENV["RESTLESS_KEY"], sampling: {
+  routes: { "GET /health" => "off", "GET /pets" => 0.1, "* /internal/{job}" => "errors" },
+})
+```
+
+Rules an installer should know:
+
+- Keys are `"<METHOD> <route pattern>"`, with `*` for any method. Use the pattern the framework matched (`/pets/{id}` or `/pets/:id`, both work; §4 "Route patterns"), never a concrete URL like `/pets/42`. `HEAD` does not fall back to `GET`. A request with no route pattern uses `default`.
+- Modes are the strings `"on"`, `"off"`, `"errors"` (symbols work in code), or a number from 0 to 1. Anything else falls back to `"on"`; it never raises.
+- Only suggest `"off"` or `"errors"` for endpoints the user agrees are noise (health checks, readiness probes, polling). Never sample auth or payment endpoints without asking.
+- A request that sends nothing also gets no `x-request-id` header, so do not use an `"off"` route to verify the install (§13).
+
 ## 9. Request IDs and response injection
 
 - Request IDs are v4 UUIDs, never time-based, so they leak no ordering.
-- Every response gets `x-restless-id`. `x-request-id` is set only if the caller did not send one, and an incoming value is never reused as ours.
-- On **every** status the SDK adds `x-log-url` and `x-debug` headers; on status **>= 400** it also merges a `debug` key into a JSON body. There is no user-configurable hook for this.
+- The SDK sets exactly one id header, always its own: `x-request-id` by default, or `x-restless-id` when the incoming request already carried an `x-request-id` (we never stomp or reuse an existing chain). With no key resolved the value is the literal `missing-key`.
+- On **every** status the SDK adds `x-log-url` and `x-debug` headers; on status **>= 400** it also merges a `debug` key into a JSON body. There is no user-configurable hook for this. The one exception is a request that sampling drops (§8a): it gets no id header and nothing injected.
 - `x-log-url` points at your project's public docs host, which the server tells the SDK on each upload. Until the first upload round-trips it is omitted rather than guessed: a URL that 404s is worse than no URL. The ingest host is never used for it.
 
 ## 10. Blocking
@@ -261,7 +286,7 @@ CLIENT.setup do |request|
 end
 ```
 
-The handler never runs. The response body is JSON `{"error": "<message>"}`. `enrich` is not called for a blocked request.
+The handler never runs. The response body is JSON `{"error": "<message>"}`. `enrich` is not called for a blocked request. Sampling (§8a) treats a blocked request like any other response with its status: a 403 or 429 is logged in full, except on an `"off"` route, where it is not logged and gets no id header.
 
 ## 11. Environment variables and batching
 
@@ -297,4 +322,4 @@ Batching is fixed: 10 requests per batch, a 5000 ms flush interval, a 1000-entry
 2. `CLIENT.rack` is mounted in `config.ru` or `config/application.rb`, as far out as possible.
 3. A `CLIENT.setup` block exists and reads its header via `request.header(...)`.
 4. `.restless/settings.json` exists (created by `npx restless init`).
-5. Starting the server and curling any endpoint returns an `x-restless-id` response header.
+5. Starting the server and curling any endpoint returns an `x-request-id` response header carrying a fresh id - `<prefix>-<uuid>` when the API has a `requestIdPrefix` in `.restless/settings.json` (the CLI sets one on every project), otherwise a bare UUID. If your curl sends its own `x-request-id`, look for `x-restless-id` instead. Plenty of stacks set `x-request-id` themselves, so the unambiguous proof it came through our SDK is the `x-debug` header, which rides every captured response. A value of `missing-key` means the server is up but never loaded `RESTLESS_KEY`; restart it.

data/lib/restless/capture.rb

@@ -5,6 +5,7 @@ require "json"
 require_relative "caches"
 require_relative "fingerprint"
 require_relative "redact"
+require_relative "sampling"
 require_relative "uploader"
 
 module Restless
@@ -20,9 +21,19 @@ module Restless
 
     attr_reader :uploader, :enrich_cache, :recovery_cache
 
+    # `sampling` is a Sampling::Config, already merged and validated. Nil, or
+    # the default config, means no sampling at all.
     def initialize(api_key:, base_url:, request_id_prefix: nil, redact: nil,
-                   transport: nil)
+                   sampling: nil, transport: nil)
       @redact = redact || {}
+      # Only kept for a non-default config (SAMPLE-041). Without one, `sample`
+      # is a constant :full and nothing about sampling touches the wire.
+      @sampling = sampling && !sampling.default? ? sampling : nil
+      @sampling_hash = @sampling && Sampling.digest(@sampling)
+      @sampling_report = :unsent
+      @sampling_mutex = Mutex.new
+      # Test hook: anything responding to `call` with a Float in [0, 1).
+      @random = -> { Random.rand }
       @enrich_cache = EnrichCache.new
       @recovery_cache = RecoveryCache.new
       @portal_url = nil
@@ -33,10 +44,31 @@ module Restless
         base_url: base_url,
         request_id_prefix: request_id_prefix,
         transport: transport,
+        sampling_hash: @sampling_hash,
         on_response: method(:handle_server_response)
       )
     end
 
+    attr_writer :random
+
+    # The sampling outcome for one request (CONTRACT.md SAMPLE-030): :full,
+    # :stub or :drop. The middleware calls this exactly once per request, when
+    # the status is final and before any SDK header is added (SAMPLE-032),
+    # and acts on the answer.
+    #
+    # Never raises. Anything unexpected sends the request in full
+    # (SAMPLE-035): sampling may only ever remove data, never break capture.
+    def sample(method, route_pattern, status)
+      return :full if @sampling.nil?
+
+      report_sampling(false)
+      mode = Sampling.resolve_mode(@sampling, method, route_pattern)
+      Sampling.decide(mode, status.to_i, @random.call)
+    rescue StandardError => e
+      Env.debug_log("sampling failed, sending in full: #{e.class}: #{e.message}")
+      :full
+    end
+
     def callback=(callback)
       @callback = callback
     end
@@ -56,6 +88,9 @@ module Restless
 
     # WIRE-020..023, CACHE-006, CACHE-011..013.
     def handle_server_response(body, batch_fingerprints)
+      # WIRE-025, SAMPLE-053.
+      report_sampling(true) if body["needsSamplingConfig"] == true
+
       needs = body["needsEnrichment"]
       if needs.is_a?(Array)
         needs.each { |key| @enrich_cache.invalidate(key) if key.is_a?(String) }
@@ -212,6 +247,13 @@ module Restless
     def record(captured, stack_frame: nil)
       request = captured["request"] || {}
       response = captured["response"] || {}
+      if captured["sampled"]
+        # A stub ships as if no body had been captured (SAMPLE-034). Dropping
+        # them here, before redaction, skips the parse work for exactly the
+        # requests the customer asked to send less of.
+        request = request.merge("body" => nil)
+        response = response.merge("body" => nil)
+      end
       request_headers = request["headers"] || {}
       response_headers = response["headers"] || {}
 
@@ -251,6 +293,40 @@ module Restless
 
     private
 
+    # Tell the ingest which config produced this process's uploads, so an
+    # "off" endpoint does not read as a dead one (SAMPLE-050..053). Once per
+    # process, on the first decision; again only when the server asks, and
+    # never while a report is already in flight.
+    def report_sampling(resend)
+      return if @sampling.nil?
+
+      send_now = @sampling_mutex.synchronize do
+        if @sampling_report == :inflight || (@sampling_report == :sent && !resend)
+          false
+        else
+          @sampling_report = :inflight
+          true
+        end
+      end
+      return unless send_now
+
+      report = {
+        "hash" => @sampling_hash,
+        "default" => @sampling.default,
+        "routes" => Sampling.sorted_routes(@sampling),
+        "creator" => { "name" => SDK_NAME, "version" => VERSION }
+      }
+      # Fire and forget on a background thread, and a failure is not retried
+      # (SAMPLE-051): the `x-restless-sampling` header on the next upload is
+      # how the server asks again if it never got this.
+      @uploader.send_sampling_report_async(report) do
+        @sampling_mutex.synchronize { @sampling_report = :sent }
+      end
+    rescue StandardError => e
+      @sampling_mutex.synchronize { @sampling_report = :sent }
+      Env.debug_log("sampling report failed: #{e.class}: #{e.message}")
+    end
+
     # Accept both `:api_key`/`"apiKey"` spellings so the callback reads
     # naturally in Ruby without losing the documented wire names (SETUP-001).
     def normalize_setup(raw)

data/lib/restless/client.rb

@@ -4,6 +4,7 @@ require_relative "capture"
 require_relative "env"
 require_relative "mask"
 require_relative "request_id"
+require_relative "sampling"
 require_relative "settings"
 require_relative "version"
 
@@ -22,10 +23,25 @@ module Restless
     # them (REDACT-014). Both the settings file and this option are additive
     # on top of the defaults (REDACT-015).
     #
+    # `sampling` sends less for high-traffic endpoints (CONTRACT.md section
+    # 12.1). Each endpoint is "on" (the default), "off", "errors" (only
+    # status >= 400) or a rate in [0, 1]: that fraction of successful
+    # requests in full and the rest without bodies. Errors are never sampled.
+    #
+    #     sampling: {
+    #       default: "on",
+    #       routes: { "GET /health" => "off", "GET /pets" => 0.1, "* /pets/{id}" => "errors" }
+    #     }
+    #
+    # Symbols work too (`default: :off`). Merged with `sampling` in
+    # `.restless/settings.json`, this option winning per route (SAMPLE-014).
+    # An invalid value never raises: it falls back to "on" and says so under
+    # DEBUG=restless.
+    #
     # `transport` is an internal test hook -- anything responding to
     # `call(url, headers, body) -> [status, body]` -- and is not public API.
     def initialize(api_key = nil, base_url: nil, api: nil, redact: nil,
-                   transport: nil)
+                   sampling: nil, transport: nil)
       resolved_key = Env.resolve_api_key(api_key)
 
       # CONFIG-002. Construction still succeeds and capture still runs; only
@@ -41,11 +57,23 @@ module Restless
       entry = Settings.resolve_api(Settings.load, api)
       settings_redact = entry && entry[:redact]
 
+      sampling_config = begin
+        config, warnings = Sampling.normalize(entry && entry[:sampling], sampling)
+        warnings.each { |w| Env.debug_log(w) }
+        config
+      rescue StandardError => e
+        # SAMPLE-003: a bad config never raises. Without one, every request
+        # is sent in full.
+        Env.debug_log("sampling config ignored: #{e.class}: #{e.message}")
+        nil
+      end
+
       @engine = CaptureEngine.new(
         api_key: resolved_key,
         base_url: Env.resolve_base_url(base_url),
         request_id_prefix: entry && entry[:request_id_prefix],
         redact: merge_redact(settings_redact, redact),
+        sampling: sampling_config,
         transport: transport
       )
     end

data/lib/restless/conformance.rb

@@ -7,6 +7,7 @@ require_relative "stack_frames"
 require_relative "har"
 require_relative "request_id"
 require_relative "injection"
+require_relative "sampling"
 
 module Restless
   # The shared operation table behind the conformance driver.
@@ -86,6 +87,24 @@ module Restless
       when "harEntry"
         Har.to_har_entry(hash(input["captured"]))
 
+      # --- sampling (section 12.1) ---
+      # Routes come back as sorted [key, mode] pairs so the comparison pins
+      # the normalized keys without depending on hash order. Warnings are
+      # debug output, not contract surface, so they are not emitted.
+      when "samplingConfig"
+        config = sampling_config(input)
+        { "default" => config.default, "routes" => config.routes.sort_by { |key, _| key } }
+      when "samplingMode"
+        Sampling.resolve_mode(sampling_config(input), str(input["method"]),
+                              str_or_nil(input["route"]))
+      when "samplingDecide"
+        status = input["status"].is_a?(Numeric) ? input["status"] : 0
+        u = input["u"].is_a?(Numeric) ? input["u"] : 0
+        Sampling.decide(input["mode"], status, u).to_s
+      when "samplingHash"
+        config = sampling_config(input)
+        { "canonical" => Sampling.canonical(config), "hash" => Sampling.digest(config) }
+
       else
         raise UnknownOp, "unknown op: #{op}"
       end
@@ -106,6 +125,12 @@ module Restless
       { "headers" => built[:headers], "debug" => built[:debug] }
     end
 
+    # `settings` and `code` are passed verbatim, possibly invalid, and every
+    # op that takes them merges and normalizes them first (SAMPLE-014).
+    def sampling_config(input)
+      Sampling.normalize(input["settings"], input["code"]).first
+    end
+
     def fingerprint(input)
       stack = stack_text(input["stackTrace"])
       if !stack.empty? && v8_dialect?(stack)

data/lib/restless/rack.rb

@@ -210,21 +210,45 @@ module Restless
     def finish(env, setup, our_id, started_at, clock, response,
                request_body:, stack_frame:, inject: true)
       status, headers, body = response
-      headers = normalize_headers(headers)
+      route = route_pattern(env)
+
+      # SAMPLE-032. One decision per request, here: Rack hands over the status
+      # and headers together, before the server has written a byte, so the
+      # status is final and none of our headers exist yet. That holds for a
+      # streaming body and for a hijack too.
+      outcome = @engine.sample(env["REQUEST_METHOD"], route, status.to_i)
+
+      # SAMPLE-033. Dropped: no log, so no id header, no injected headers and
+      # no `debug` object pointing at one. The response goes back exactly as
+      # the app returned it, body unread.
+      return response if outcome == :drop
 
-      body_text, body = read_response_body(body, headers)
+      # SAMPLE-034. A stub never ships a body, and is always a success, so
+      # there is nothing to inject into it either: leave the body unread.
+      stub = outcome == :stub
+
+      headers = normalize_headers(headers)
+      # Rack's partial hijack hands the server a callable in the headers. It
+      # is not a header: keep it out of the capture and give it back intact.
+      hijack = headers.delete("rack.hijack")
+
+      body_text, body = if stub || hijack
+                          [nil, body]
+                        else
+                          read_response_body(body, headers)
+                        end
       duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - clock) * 1000).round
 
       captured = {
         "requestId" => our_id,
         "startedAt" => Text.iso8601_millis(started_at),
         "duration" => duration,
-        "routePattern" => route_pattern(env),
+        "routePattern" => route,
         "request" => {
           "method" => env["REQUEST_METHOD"],
           "url" => Middleware.full_url(env),
           "headers" => request_headers(env),
-          "body" => request_body
+          "body" => stub ? nil : request_body
         },
         "response" => {
           "status" => status.to_i,
@@ -234,6 +258,7 @@ module Restless
         "user" => setup
       }
       captured.delete("routePattern") if captured["routePattern"].nil?
+      captured["sampled"] = true if stub # WIRE-030
 
       options = @engine.uploader.options
       # REQID-010, REQID-011.
@@ -293,6 +318,8 @@ module Restless
 
       safely(nil) { @engine.record(captured, stack_frame: stack_frame) }
 
+      # After `record`, which copies the headers it keeps.
+      headers["rack.hijack"] = hijack if hijack
       [status, headers, body]
     rescue StandardError => e
       Env.debug_log("middleware finish failed: #{e.class}: #{e.message}")
@@ -305,7 +332,14 @@ module Restless
     def normalize_headers(headers)
       out = {}
       (headers || {}).each do |name, value|
-        out[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s
+        name = name.to_s.downcase
+        out[name] = if name == "rack.hijack"
+                      value # a callable, not a header value
+                    elsif value.is_a?(Array)
+                      value.join(", ")
+                    else
+                      value.to_s
+                    end
       end
       out
     end