restless-sdk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1147b0604f0fdb6ca8b2cdd39ffe03819391d0e5d663b70fa845fbe4b4b72b27
-  data.tar.gz: f1bd487a972936ae678151d03f27edecb476b8c1f7b755ff5a88157f5d015e4e
+  metadata.gz: f2ab526956a3600f1166a74828a06c9b01b5a0ce2a17808bdba530f6ea344ee9
+  data.tar.gz: 4e5776ac3709c2f1e8b5d0a710d45335927a331eddb0cd9b027a0bd8305c42ee
 SHA512:
-  metadata.gz: f7508f1e2f878289a16930cd56db0a0c5e150dc6fd5772a0c221cb97792a703f130f15d6a99e401b81bb713edbceba5adc835da4d994600248911f4d7f86b558
-  data.tar.gz: c6e94661d61836cdb2dc408beefc0e5323afd17ffb3c5ec2e68beb2ec5ab1687af64ae72a6a8726d97e265d4a1343b04dea320687e0b952a7c392f279851e71d
+  metadata.gz: ce0a15152665dba1b04f64377e6b6dc2e773f128b48ae6fdcddedc0f35fc34df3c40716470857f16c35b8409793b03af07e2bda387af9a24ba8636bcc419149c
+  data.tar.gz: 395c589c7b35aa121e9612fd0142e32df3c2f0dc75cc3eeb8607912b73d279ef046a3478f4d63e7a548d813ca4a33ae1212a18bef2a7b60f3bdb0ba88d306a55

data/CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 | | |
 |---|---|
-| **Spec version** | 1.0.0 |
+| **Spec version** | 1.1.0 |
 | **Level** | L2 (core + batching, caches, injection, safety) |
 | **Reference** | `restlesshq/node` (`@restlessai/sdk`) |
 | **Driver** | `ruby exe/restless-conformance` |
@@ -12,7 +12,7 @@ Declared in `lib/restless/version.rb` (META-001).
 ## Verifying
 
 The harness and vectors live in the reference SDK, so the commands below
-assume it is checked out as a sibling (`../node-sdk`), which is how
+assume it is checked out as a sibling (`../node`), which is how
 `setup.sh` in the install repo arranges things. The vectors in `spec/` here
 are a pinned copy, so `ruby -Ilib -Itest test/all.rb` alone works without it.
 
@@ -22,18 +22,18 @@ are a pinned copy, so `ruby -Ilib -Itest test/all.rb` alone works without it.
 ruby -Ilib -Itest test/all.rb
 
 # the shared cross-language harness
-node ../node-sdk/spec/harness/run-vectors.mjs -- ruby exe/restless-conformance
+node ../node/spec/harness/run-vectors.mjs -- ruby exe/restless-conformance
 
 # differential fuzz against the reference implementation
-node ../node-sdk/spec/harness/fuzz.mjs \
-  --ref  "node ../node-sdk/spec/driver/.build/node.js" \
+node ../node/spec/harness/fuzz.mjs \
+  --ref  "node ../node/spec/driver/.build/node.js" \
   --test "ruby exe/restless-conformance" \
   --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/LICENSE

@@ -0,0 +1,18 @@
+Copyright © 2026 Restless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,3 +1,18 @@
+<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:
+
+```sh
+npx restless init
+```
+
+This scans your project, figures out your framework, generates an OpenAPI spec, and automatically wires the SDK into your server.
+
 # restless-sdk
 
 Capture your API traffic and send it to [Restless](https://restless.ai).
@@ -5,7 +20,9 @@ Capture your API traffic and send it to [Restless](https://restless.ai).
 One Rack middleware covers **Rails**, **Sinatra**, **Hanami**, **Grape**,
 **Roda** and anything else that speaks Rack. Ruby 2.6+. No dependencies.
 
-## Install
+## Manual installation
+
+If you'd rather wire it up by hand:
 
 ```sh
 gem install restless-sdk
@@ -68,8 +85,8 @@ and body your app produced rather than an inner layer's.
   and friends are redacted before anything leaves your process. Bodies with
   nothing to redact are passed through byte for byte, so your payloads are
   never re-serialized on the way out.
-- **Error triage.** 4xx/5xx responses get `x-log-url` and `x-debug` headers
-  and a `debug` block in the JSON body. If someone attaches a "next steps"
+- **Error triage.** Every response gets `x-log-url` and `x-debug` headers,
+  and 4xx/5xx responses also get a `debug` block in the JSON body. If someone attaches a "next steps"
   message to an error in the dashboard, the SDK injects it as
   `debug.recovery` - read synchronously from an in-process cache, never
   blocking the response on a network call. A 5xx that groups by its throw
@@ -79,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
 
@@ -138,11 +199,10 @@ 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).
 
 ## License
-
-ISC
+MIT

data/exe/restless-conformance

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# The Ruby conformance driver. See node-sdk/spec/driver/PROTOCOL.md.
+# The Ruby conformance driver. See sdk/node/spec/driver/PROTOCOL.md.
 #
 # Dev-only: it is a thin shell over Restless::Conformance, which
 # test/test_vectors.rb also uses, so the vectors cannot describe behaviour the

data/install.md

@@ -191,29 +191,30 @@ api_key: CLIENT.mask(request.header("Authorization") || "anonymous")
 
 ## 7. `.restless/settings.json`
 
-Read at startup, walking up from the working directory. Created and owned by the `api` CLI (`npx api setup`). Every Restless SDK reads the same file with the same camelCase keys, so a polyglot repo needs only one.
+Read at startup, walking up from the working directory. Created and owned by the `restless` CLI (`npx restless init`). Every Restless SDK reads the same file with the same camelCase keys, so a polyglot repo needs only one.
 
 ```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,36 @@ 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 status **>= 400** the SDK adds `x-log-url` and `x-debug` headers, and 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
 
@@ -260,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
 
@@ -295,5 +321,5 @@ Batching is fixed: 10 requests per batch, a 5000 ms flush interval, a 1000-entry
 1. `restless-sdk` appears in the `Gemfile`, and `bundle list` finds it.
 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 api setup`).
-5. Starting the server and curling any endpoint returns an `x-restless-id` response header.
+4. `.restless/settings.json` exists (created by `npx restless init`).
+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,12 +21,22 @@ 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
-      @docs_url = nil
+      @portal_url = nil
       @docs_mutex = Mutex.new
       @callback = nil
       @uploader = Uploader.new(
@@ -33,18 +44,42 @@ 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
 
     # INJECT-006. The latest server-resolved docs origin, or nil when no batch
     # has round-tripped yet.
-    def docs_url
-      @docs_mutex.synchronize { @docs_url }
+    # INJECT-006. The server-published portal origin every injected URL is
+    # built on. Nil before the first upload round-trip, and then nothing is
+    # emitted rather than a guess.
+    def portal_url
+      @docs_mutex.synchronize { @portal_url }
     end
 
     def flush
@@ -53,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) }
@@ -61,7 +99,9 @@ module Restless
       docs = body["docsUrl"]
       if docs.is_a?(String) && !docs.empty?
         # Origin only; strip trailing slashes so the server can be lax.
-        @docs_mutex.synchronize { @docs_url = docs.sub(%r{/+\z}, "") }
+        # The wire key stays `docsUrl`: every already-deployed SDK reads it,
+        # so renaming would strand them all with no portal origin (WIRE-023).
+        @docs_mutex.synchronize { @portal_url = docs.sub(%r{/+\z}, "") }
       end
 
       messages = body["recoveryMessages"].is_a?(Hash) ? body["recoveryMessages"] : {}
@@ -207,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"] || {}
 
@@ -246,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.
@@ -16,7 +17,7 @@ module Restless
   # through this one file, so it is impossible for the vectors to describe
   # behaviour the driver does not exhibit.
   #
-  # See node-sdk/spec/driver/PROTOCOL.md. Internal: never part of the public
+  # See sdk/node/spec/driver/PROTOCOL.md. Internal: never part of the public
   # API, never shipped behaviour a customer depends on.
   module Conformance
     # An input this implementation's language cannot represent or parse. The
@@ -79,16 +80,57 @@ module Restless
       # --- injection (section 10) ---
       when "recoverySlug"
         Injection.recovery_slug(str_or_nil(input["method"]), str_or_nil(input["path"]))
+      when "debugInjection"
+        debug_injection(input)
 
       # --- HAR (section 7) ---
       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
     end
 
+    # The observable surface only: the headers, and the `debug` object the
+    # adapter would merge (nil when there is nothing to merge).
+    def debug_injection(input)
+      built = Injection.build(
+        status: input["status"].to_i,
+        request_id: str(input["requestId"]),
+        prefix: str_or_nil(input["prefix"]),
+        recovery: str_or_nil(input["recovery"]),
+        method: str_or_nil(input["method"]),
+        path: str_or_nil(input["path"]),
+        portal_url: str_or_nil(input["portalUrl"])
+      )
+      { "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/injection.rb

@@ -31,19 +31,37 @@ module Restless
       flat.empty? ? m : "#{m}-#{flat}"
     end
 
+    # INJECT-002. The debug response headers, which ship on every status.
+    #
+    # `x-log-url` is omitted with no portal origin; `x-debug` carries no URL,
+    # so it always ships.
+    def headers(request_id:, prefix: nil, portal_url: nil)
+      display = RequestId.format_request_id(request_id, prefix)
+      out = { "x-debug" => "npx api debug #{display}" }
+      out["x-log-url"] = "#{portal_url}/logs/#{request_id}" unless portal_url.nil? || portal_url.empty?
+      out
+    end
+
     # INJECT-001..004, INJECT-006. Returns the headers to set plus the `debug`
-    # object to merge into a JSON body, or nil when nothing should be injected.
-    def build(status:, request_id:, base_url:, prefix: nil, recovery: nil,
-              method: nil, path: nil, docs_url: nil)
-      return nil if status < 400 # INJECT-001
+    # object to merge into a JSON body (nil when there is nothing to merge).
+    #
+    # `portal_url` is the project's public portal origin, published by the
+    # server. It is NOT the ingest base URL, which serves `/v1/*` and would
+    # 404 both paths, and there is deliberately no fallback to it: with no
+    # portal origin we emit `x-debug` alone. A caller cannot tell a broken URL
+    # from a missing one, and one fetched 404 teaches an agent to stop
+    # following the link.
+    def build(status:, request_id:, prefix: nil, recovery: nil,
+              method: nil, path: nil, portal_url: nil)
+      hdrs = headers(request_id: request_id, prefix: prefix, portal_url: portal_url)
 
-      display = RequestId.format_request_id(request_id, prefix)
-      # INJECT-006: the server-supplied docsUrl when one has been learned,
-      # else the configured base URL. One batch of staleness after a
-      # docs-domain change is accepted.
-      log_host = docs_url.nil? || docs_url.empty? ? base_url : docs_url
-      log_url = "#{log_host}/logs/#{request_id}"
-      debug_cmd = "npx api debug #{display}"
+      # INJECT-001. The body object is 4xx/5xx only: a successful body is the
+      # caller's data, not ours to reshape. With no portal origin there is no
+      # URL to put in one either (INJECT-006).
+      return { headers: hdrs, debug: nil } if status < 400 || portal_url.nil? || portal_url.empty?
+
+      log_url = hdrs["x-log-url"]
+      debug_cmd = hdrs["x-debug"]
 
       # Per-request "dig-in" URL the calling agent (often an AI) can fetch for
       # concrete next steps. Deliberately LEGIBLE: it ends in `<slug>.md` so it
@@ -52,7 +70,7 @@ module Restless
       # can correlate the follow-up without any new tracking token.
       slug = recovery_slug(method, path)
       dig_in = "For the accepted parameters and next steps, " \
-               "fetch #{log_host}/p/#{request_id}/#{slug}.md"
+               "fetch #{portal_url}/p/#{request_id}/#{slug}.md"
       # INJECT-004: a cached recovery message precedes the dig-in line,
       # separated by a blank line.
       recovery_text =
@@ -63,10 +81,7 @@ module Restless
         end
 
       {
-        headers: {
-          "x-log-url" => log_url, # INJECT-002
-          "x-debug" => debug_cmd
-        },
+        headers: hdrs,
         debug: {
           "log" => log_url,
           "cli" => debug_cmd,