restless-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1147b0604f0fdb6ca8b2cdd39ffe03819391d0e5d663b70fa845fbe4b4b72b27
+  data.tar.gz: f1bd487a972936ae678151d03f27edecb476b8c1f7b755ff5a88157f5d015e4e
+SHA512:
+  metadata.gz: f7508f1e2f878289a16930cd56db0a0c5e150dc6fd5772a0c221cb97792a703f130f15d6a99e401b81bb713edbceba5adc835da4d994600248911f4d7f86b558
+  data.tar.gz: c6e94661d61836cdb2dc408beefc0e5323afd17ffb3c5ec2e68beb2ec5ab1687af64ae72a6a8726d97e265d4a1343b04dea320687e0b952a7c392f279851e71d

data/CONFORMANCE.md

@@ -0,0 +1,112 @@
+# Conformance
+
+| | |
+|---|---|
+| **Spec version** | 1.0.0 |
+| **Level** | L2 (core + batching, caches, injection, safety) |
+| **Reference** | `restlesshq/node` (`@restlessai/sdk`) |
+| **Driver** | `ruby exe/restless-conformance` |
+
+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
+`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.
+
+
+```sh
+# in-process, no Node and no bundler needed
+ruby -Ilib -Itest test/all.rb
+
+# the shared cross-language harness
+node ../node-sdk/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" \
+  --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).
+
+The 8 skips are cases outside this implementation's dialect, not gaps:
+
+- 7 `fp/stack-*` cases feed a v8-shaped stack into `fingerprint`. FP-044
+  makes frame parsing per-language and FP-046 requires the driver to say so
+  rather than guess. Covered natively in `test/test_stack_frames.rb`. This
+  includes `fp/stack-not-used-for-4xx`, where the stack is never consulted:
+  the driver declares the dialect on the INPUT rather than on whether the
+  strategy happens to fire, which is what the Python and Go drivers do too.
+- 1 `redactBody/lone-surrogate` case. See the exemption below.
+
+## Ruby-specific decisions
+
+Each of these is a place where the obvious Ruby code silently disagrees with
+the reference. They are the reason this SDK is byte-compatible.
+
+| Contract | What Ruby needs |
+|---|---|
+| PRIM-002 | `WS` is enumerated as code points in `text.rb`. Ruby's `\s` is ASCII-only and NARROWER than the contract's set: no NBSP, no Zs category, no LS/PS/ZWNBSP. |
+| PRIM-003 | **Ruby's `\b` is Unicode-aware even though its `\w` is not.** Onigmo defines the boundary against the Unicode word property, so `\b[\w-]*[0-9][\w-]*\b` leaves `éa1` untouched where JavaScript, Go and Python-with-`re.ASCII` all strip the `a1`. `Fingerprint.strip_digit_words` applies that one regex to the UTF-8 BYTES, which restores JavaScript's semantics exactly (every non-ASCII character becomes a run of non-word bytes, which is what a non-`u` JS regex sees in UTF-16 too). The pattern can only match ASCII bytes, so the result is still well-formed UTF-8. |
+| PRIM-005 | `\A...\z` everywhere, never `^...$`. Ruby's `$` also matches before a trailing newline, so a route segment of `"5\n"` would normalize to `:id` here and not in JavaScript. |
+| PRIM-006 | Hex digits validated explicitly against `[0-9a-fA-F]`. `String#to_i(16)` returns 0 for garbage rather than failing, so `%zz` would silently decode as a NUL byte. |
+| PRIM-010 vs PRIM-011 | `String#length` is code points (what REDACT-002 and MASK-006 want) and `String#bytesize` is UTF-8 bytes (what HAR-010 and REDACT-030 want). They are never interchangeable. |
+| PRIM-013 | `Text.to_utf8` scrubs invalid bytes to U+FFFD instead of raising. Rack hands out header and body strings tagged UTF-8 that are not valid UTF-8. It also DECODES a BINARY string rather than transcoding it: `IO#read(n)` always returns ASCII-8BIT and the Rack spec requires `rack.input` to be binary, and Ruby's BINARY-to-UTF-8 transcode has no mapping above `0x7F`, so `encode` turns every byte of every multi-byte character into its own U+FFFD. That corrupted every non-ASCII body the SDK captured and was a second redaction bypass on top of REDACT-010, since a mangled key no longer matches the denylist. |
+| PRIM-020 | `String#downcase` is FULL case mapping and is used unmodified everywhere, including for REDACT-010 names. U+0130 becomes two code points (matching JS and Python, unlike Go's simple mapping) and U+212A KELVIN SIGN becomes `k`. It is not `casefold` and applies no locale tailoring. The one thing it does not do is the Final_Sigma contextual rule that `String.prototype.toLowerCase` applies (word-final Σ to ς rather than σ), and per the PRIM-021 note that is **not required**: nothing in the contract can observe it, because Greek is outside `WORD` so FP-020 step 6 replaces both sigma forms with a space before either reaches a token, and the REDACT-010 denylists are ASCII. An earlier `\p{Cased}` / `\p{Case_Ignorable}` implementation of the rule was removed as untestable. |
+| PRIM-030..032 | Ruby's `JSON.generate` is already compact, insertion-ordered and literal-UTF-8, and does not HTML-escape - so the `<REDACTED:...>` sentinel the dashboard pattern-matches on survives. Verified byte-identical to `JSON.stringify` for control characters, quotes, backslashes and astral characters. |
+| PRIM-040 | Hand-built with `strftime("%Y-%m-%dT%H:%M:%S.%LZ")`. `Time#iso8601` needs `require "time"` plus an explicit fractional-digit count and emits `+00:00` unless the receiver is already UTC. |
+| REDACT-010 | Name normalization uses **full Unicode** lowercase (PRIM-020), not an ASCII fold, and this is a security requirement rather than a cosmetic one. Normalization decides whether a value is redacted, so it must fold more aggressively rather than less: a header `x-api-Key` or a body key `toKen` whose `K` is U+212A KELVIN SIGN lowercases to a denylisted name and must be redacted. A hand-written ASCII-only fold is the easy mistake here, and it ships such values to the dashboard in plaintext. Pinned by `redactHeaders/unicode-fold-kelvin`, `redactBody/unicode-fold-kelvin` and `test_middleware.rb#test_kelvin_sign_does_not_bypass_the_denylist`. |
+| REDACT-016 | An explicit code-point scan, never `^(\S+)(\s+)(\S.*)$`. Ruby's `.` excludes only LF while JavaScript's also excludes CR, LS and PS, so a credential containing a stray CR would take the scheme-preserving branch here and the redact-whole branch there. |
+| REDACT-025 | `split("&", -1)` and `split("/", -1)`. Ruby drops trailing empty fields without the negative limit, so `?a=1&` would come back as `?a=1` and `/users/` would lose its trailing segment. |
+| REDACT-028 | The unreserved set is spelled out. `CGI.escape` turns a space into `+` and escapes `~`; `URI.encode_www_form_component` differs again. |
+| REDACT-029 | `bytes.pack("C*").force_encoding("UTF-8").scrub` is byte-identical to Node's `Buffer#toString("utf8")`, including the maximal-subpart replacement rule. Verified differentially. |
+| FP-020 step 9 | `split(/ /, -1)`, never `split(" ")`. A literal single-space argument triggers Ruby's awk-mode split, which collapses runs and drops leading empties. |
+| FP-030 | Hex classes written as `[0-9a-fA-F]` with no `i` flag. Ruby's case-insensitive matching is Unicode case folding, a wider relation than the ASCII-only canonicalization a non-`u` JavaScript regex performs. |
+| 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. |
+| 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. |
+| CACHE-* | Both caches are Mutex-guarded. Puma, Falcon and threaded Unicorn all serve requests on many threads, so an unsynchronized Hash is a real race. |
+
+## Exemption: PRIM-034 (unpaired surrogates)
+
+This SDK claims the **PRIM-035 exemption**, on stronger grounds than Go's.
+
+A Go string merely *replaces* an unpaired surrogate with U+FFFD while
+decoding. Ruby is more restrictive in both directions:
+
+- `JSON.parse('"\ud83d"')` **raises** `JSON::ParserError: incomplete
+  surrogate pair`. The value never reaches SDK code at all.
+- `"\u{d83d}"` is not a legal Ruby literal - the parser rejects it with
+  `invalid Unicode codepoint`. `[0xd83d].pack("U")` produces the CESU-8
+  bytes `ED A0 BD`, which `String#valid_encoding?` reports as false.
+
+So a Ruby `String` has no representation for the value, and per PRIM-035 the
+SDK never raises on such input and substitutes U+FFFD (`Text.to_utf8`).
+
+The conformance driver reports `unsupported` for any input LINE containing a
+lone surrogate escape, checked on the raw line **before** parsing, because
+the limitation is at the transport layer rather than in redaction - parsing
+first would produce a `JSON::ParserError` that looks like a conformance
+failure. `test/test_vectors.rb` does the same, swapping each such escape for
+an ASCII marker so the vector documents can be read at all, then skipping the
+cases that contained one.
+
+## Residual differences, accepted
+
+**Number rendering in a re-serialized body.** REDACT-020 means a body is only
+re-serialized when it actually contains a denylisted key. For those bodies,
+Ruby preserves int64 exactly where JavaScript silently truncates above 2^53,
+and Ruby's `Float#to_s` uses a different exponent form than JavaScript for
+very large and very small magnitudes. This matches the Python SDK and is the
+behaviour PRIM-033 describes as the *correct* one; the reference is the odd
+one out. It is unreachable from the fuzzer, because `JSON.stringify` has
+already collapsed such values before the input is generated.

data/README.md

@@ -0,0 +1,148 @@
+# restless-sdk
+
+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
+
+```sh
+gem install restless-sdk
+```
+
+or in a `Gemfile`:
+
+```ruby
+gem "restless-sdk"
+```
+
+## Use
+
+```ruby
+require "restless"
+
+CLIENT = Restless.new(ENV["RESTLESS_KEY"])
+
+CLIENT.setup do |request|
+  {
+    api_key: CLIENT.mask(request.header("Authorization")),
+    owner: {
+      # Permanent and immutable. A workspace id or database primary key,
+      # never an API key, email, or anything else that rotates: the
+      # dashboard pins a project's whole log history to this.
+      id: workspace_id_for(request),
+      # Runs once per owner id, then caches for an hour. Put the expensive
+      # lookup here, not in the fields above.
+      enrich: ->(owner_id) {
+        workspace = Workspace.find(owner_id)
+        { label: workspace.name, email: workspace.admin_emails }
+      },
+    },
+  }
+end
+```
+
+Then mount it.
+
+```ruby
+# config.ru (Sinatra, Roda, Hanami, plain Rack)
+use CLIENT.rack
+run App
+
+# config/application.rb (Rails)
+config.middleware.insert_before 0, CLIENT.rack
+```
+
+`CLIENT.rack` returns a middleware factory: anything that calls `.new(app)`
+on it works. Mount it as far **out** as you can, so it sees the real status
+and body your app produced rather than an inner layer's.
+
+## What you get
+
+- **Lazy owner enrichment.** The `enrich` callback runs on the first request
+  from each owner id and then caches, so 100 requests from one workspace do
+  not mean 100 database lookups. The cached value still rides on every
+  upload, so no request lands in the dashboard as unauthenticated.
+- **Safe by default.** `Authorization`, `Cookie`, `password`, `token`, `ssn`
+  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"
+  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
+  site also reports the key it would have grouped under otherwise, so a
+  message you attached before that grouping existed keeps being injected.
+- **Blocking.** Return `{ block: true }` from the setup callback to reject a
+  request before your handler runs, or
+  `{ block: { status: 402, message: "Payment required" } }` to pick the
+  status.
+
+## The setup callback
+
+It receives a small read-only request view and returns a hash:
+
+| field | what |
+|---|---|
+| `api_key` | The **masked** end-user key. Always `CLIENT.mask(raw_header)` - never substitute `"anonymous"`, whose last 4 characters would become the mask tail. |
+| `owner[:id]` | The permanent, immutable workspace/tenant identifier. |
+| `owner[:enrich]` | `->(id) { ... }` returning owner metadata (`label`, `email`, extras). The only channel for owner metadata; anything else inline on `owner` is dropped. |
+| `block` | `true`, or `{ status:, message: }`. |
+| anything else | Carried through onto the log as-is. Keep it cheap - read straight off the request. Anything expensive belongs in `enrich`. |
+
+The request view exposes `header(name)` (case-insensitive),
+`request_method`, `path`, `query_string`, `url`, and the raw Rack `env`.
+
+## Route patterns
+
+The middleware reads the matched route template from the framework so your
+handlers do not have to report it:
+
+| framework | source | reported as |
+|---|---|---|
+| Sinatra | `env["sinatra.route"]` (`GET /pets/:id`) | `/pets/{id}` |
+| Rails | `env["action_dispatch.route_uri_pattern"]` | `/pets/{id}` |
+| anything | `env["restless.route"]`, set by you | as given |
+
+The method prefix is stripped and `:id`-style params are rewritten to
+`{id}`, so the same endpoint produces the same `routePattern` here as it
+does in the Node, Python and Go SDKs. Override the whole thing with a
+lambda:
+
+```ruby
+use CLIENT.rack(route: ->(env) { env["my_router.pattern"] })
+```
+
+## Never breaks your API
+
+Observability must not take down a production request path. Upload failures,
+callback exceptions, unserializable bodies and malformed input are all caught
+and swallowed (surfaced only under `DEBUG=restless`). Uploads happen on a
+background thread and are fire-and-forget. Streaming responses
+(`text/event-stream`) and bodies over 1 MiB are never buffered.
+
+An exception your app raises is captured with its stack - so the error
+fingerprint keys on the method that raised, not on the middleware - and then
+re-raised untouched, leaving your own error handling completely unaffected.
+
+## Environment variables
+
+| variable | purpose |
+|---|---|
+| `RESTLESS_KEY` | Your project API key, if you do not pass one explicitly. |
+| `RESTLESS_BASE_URL` | Override the ingest URL (self-hosted or staging). |
+| `RESTLESS_ENV` / `RACK_ENV` / `RAILS_ENV` | `production` enables batching; anything else flushes every request. `test` disables uploads entirely. |
+| `DEBUG=restless` | Print upload diagnostics to stderr. |
+
+## Conformance
+
+This SDK implements version 1.0.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

data/exe/restless-conformance

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The Ruby conformance driver. See node-sdk/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
+# driver does not exhibit. No customer ever runs it.
+#
+#     bundle exec restless-conformance      # or just: ruby exe/restless-conformance
+#
+# Reads JSON Lines on stdin, writes JSON Lines on stdout, diagnostics on
+# stderr, and exits 0 when stdin closes.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "json"
+require "restless/conformance"
+
+UNSUPPORTED_SURROGATE = <<~MSG.tr("\n", " ").strip
+  unsupported: input line contains an unpaired surrogate escape. Ruby's JSON
+  parser raises on one and a Ruby String has no representation for it, so the
+  value is unreachable before any SDK code runs (PRIM-035).
+MSG
+
+# PRIM-035 / PROTOCOL.md "Skips".
+#
+# Checked on the RAW LINE, because this is a TRANSPORT limit rather than an SDK
+# one: `JSON.parse('"\ud83d"')` raises `JSON::ParserError: incomplete surrogate
+# pair`, and `"\u{d83d}"` is not even a legal Ruby literal. Reporting
+# `unsupported` for the whole line is what the protocol asks for; reporting a
+# parse error would look like a conformance failure, and silently substituting
+# U+FFFD would compare a value the harness never sent.
+def lone_surrogate_escape?(line)
+  hex4 = /\A[0-9a-fA-F]{4}\z/
+  index = 0
+  while (at = line.index("\\u", index))
+    hex = line[at + 2, 4]
+    unless hex && hex4.match?(hex)
+      index = at + 2
+      next
+    end
+
+    code = hex.to_i(16)
+    if code >= 0xD800 && code <= 0xDBFF
+      # A high surrogate is fine only if a low one follows immediately.
+      low_hex = line[at + 8, 4]
+      if line[at + 6, 2] == "\\u" && low_hex && hex4.match?(low_hex)
+        low = low_hex.to_i(16)
+        if low >= 0xDC00 && low <= 0xDFFF
+          index = at + 12
+          next
+        end
+      end
+      return true
+    end
+    return true if code >= 0xDC00 && code <= 0xDFFF
+
+    index = at + 6
+  end
+  false
+end
+
+# Best-effort extraction so the harness can still correlate a response for a
+# line we refuse to fully decode.
+def raw_id_token(line)
+  match = /"id"\s*:\s*("(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?|true|false|null)/.match(line)
+  match ? match[1] : "null"
+end
+
+def emit(line)
+  $stdout.write("#{line}\n")
+  $stdout.flush
+end
+
+$stdout.sync = true
+$stdin.set_encoding(Encoding::UTF_8)
+$stdout.set_encoding(Encoding::UTF_8)
+
+while (line = $stdin.gets)
+  line = line.strip
+  next if line.empty?
+
+  if lone_surrogate_escape?(line)
+    emit(%({"id":#{raw_id_token(line)},"error":#{JSON.generate(UNSUPPORTED_SURROGATE)}}))
+    next
+  end
+
+  begin
+    request = JSON.parse(line, max_nesting: false)
+  rescue StandardError => e
+    emit(JSON.generate({ "id" => nil, "error" => "malformed request: #{e.message}" }))
+    next
+  end
+
+  id = request["id"]
+  begin
+    result = Restless::Conformance.dispatch(request["op"], request["input"])
+    emit(JSON.generate({ "id" => id, "result" => result }))
+  rescue Restless::Conformance::UnknownOp,
+         Restless::Conformance::UnsupportedDialect => e
+    emit(JSON.generate({ "id" => id, "error" => e.message }))
+  rescue StandardError => e
+    emit(JSON.generate({ "id" => id, "error" => "#{e.class}: #{e.message}" }))
+  end
+end
+
+exit 0

data/install.md

@@ -0,0 +1,299 @@
+# install.md: LLM installation reference for restless-sdk (Ruby)
+
+This file is the single source of truth for LLM agents installing or configuring the Restless Ruby SDK. Humans should read `README.md` instead.
+
+The document is ordered so an agent can stop as soon as enough context has been loaded: package basics → setup call → where to mount → redaction → settings file → common mistakes.
+
+---
+
+## 1. What this package is
+
+`restless-sdk` captures HTTP request/response pairs and ships them in batches to the Restless ingest server for dashboard display.
+
+- **Runtime:** Ruby 2.6+. **No dependencies.**
+- **Shape:** one Rack middleware. Rails, Sinatra, Hanami, Grape, Roda and anything else that speaks Rack all use the same one; there are no per-framework adapters.
+- **Install name is not the require name:** you install `restless-sdk` and you `require "restless"`.
+
+## 2. Install
+
+```sh
+gem install restless-sdk
+```
+
+or in a `Gemfile`:
+
+```ruby
+gem "restless-sdk"
+```
+
+No other gems are required.
+
+## 3. The one-line setup
+
+Construct a client, register a per-request callback, mount the middleware:
+
+```ruby
+require "restless"
+
+CLIENT = Restless.new(ENV["RESTLESS_KEY"])
+
+CLIENT.setup do |request|
+  { api_key: CLIENT.mask(request.header("Authorization")),
+    owner: { id: workspace_id_for(request), enrich: method(:load_workspace) } }
+end
+```
+
+The client exposes four things:
+
+| member | purpose |
+|---|---|
+| `setup(&block)` | Register the per-request callback. Takes a block or any callable. |
+| `mask(key)` | Hash an end-user API key for safe logging. |
+| `rack` | The middleware factory to mount. |
+| `flush` | Force-upload the current batch (e.g. before exit). |
+
+`Restless.new` and `Restless::Client.new` are the same thing. `mask` is also available as `Restless.mask` without a client, for scripts and tests.
+
+**Construct the client once**, somewhere loaded at boot - `config/application.rb` under Rails, the top of `config.ru` otherwise. Not per request.
+
+## 4. Where to mount it
+
+`CLIENT.rack` returns a middleware factory: anything that calls `.new(app)` on it works.
+
+```ruby
+# config.ru - Sinatra, Roda, Hanami, Grape, plain Rack
+use CLIENT.rack
+run App
+```
+
+```ruby
+# config/application.rb - Rails
+config.middleware.insert_before 0, CLIENT.rack
+```
+
+```ruby
+# No config.ru at all - wrap where the app is handed to the server
+handler = CLIENT.rack.new(APP)
+```
+
+**Mount as far OUT as you can.** An inner mount sees a different status and body than the client did.
+
+**Rails: `insert_before 0`, not `use`.** `config.middleware.use` appends to the bottom of the stack, below `ActionDispatch::ShowExceptions`. From there the SDK records the rendered error page rather than the real exception, so a 500 loses its raise site and every crash groups by the wording of your error template.
+
+**The mount is not in the file with the routes.** Rails routes live in `config/routes.rb` and the middleware does not go there. This trips up installers coming from frameworks where the two are the same file.
+
+### Route patterns
+
+The middleware reads the matched route template from the framework, so handlers do not have to report it:
+
+| framework | source | reported as |
+|---|---|---|
+| Sinatra | `env["sinatra.route"]` (`GET /pets/:id`) | `/pets/{id}` |
+| Rails | `env["action_dispatch.route_uri_pattern"]` | `/pets/{id}` |
+| Grape | `env["grape.routing_args"]` | as matched |
+| anything | `env["restless.route"]`, set by you | as given |
+
+The method prefix is stripped, Rails' `(.:format)` is dropped and `:id`-style params are rewritten to `{id}`, so one endpoint produces the same `routePattern` here as it does in the Node, Python and Go SDKs. Override wholesale with `CLIENT.rack(route: ->(env) { ... })`.
+
+## 5. The setup callback
+
+The callback receives a read-only `RequestInfo` and returns a hash.
+
+| accessor | what |
+|---|---|
+| `request.header(name)` | One header, case-insensitive. `request["authorization"]` is an alias. |
+| `request.request_method` | `"GET"`, `"POST"`, ... |
+| `request.path` | `SCRIPT_NAME` + `PATH_INFO`. |
+| `request.query_string` | Raw query string, without `?`. |
+| `request.url` | Full URL. |
+| `request.env` | The raw Rack env, for anything the view does not model. |
+
+Use `header`, not `env["HTTP_AUTHORIZATION"]`.
+
+Result fields:
+
+| field | type | required | notes |
+|---|---|---|---|
+| `api_key` | `String` or nil | no | Masked key from `CLIENT.mask`. Never plaintext. |
+| `owner` | `Hash` | yes\* | The workspace / tenant / end-user this request belongs to. |
+| `block` | `true` or `{ status:, message: }` | no | Rejects the request before the handler runs. |
+
+\* Technically optional, but omitting it lands every log in the dashboard as "anonymous".
+
+Extra top-level keys are carried through onto the log.
+
+**The callback runs before your application**, because the middleware is mounted outside everything. `current_user`, Warden, and controller filters have not run yet. Resolve the owner from the credential yourself inside the block.
+
+**A callback that raises is silently ignored.** SAFETY-002 requires that observability never breaks the request path, so an exception is caught and the result discarded. That is correct behaviour, and it means a wrong callback does not crash your app - it just quietly attributes nothing. Verify with §12 rather than assuming.
+
+### 5.1 The `owner` hash
+
+`owner[:id]` is the **permanent, immutable identifier** the dashboard pins a project's entire log history to. Misconfiguring it is the single biggest setup mistake.
+
+| API shape | Use as `id` |
+|---|---|
+| Multi-tenant SaaS (`Account`, `Organization`, `Workspace`) | The tenant's id |
+| Key owned by a project or service (`ApiKey belongs_to :project`) | The project id, not its creator |
+| Per-user API (one key per developer) | The user's id |
+| No identity model | Omit `owner` entirely |
+
+**Never** an API key, email, username, JWT, or a placeholder literal like `"anonymous"` / `"none"` / `"guest"`. Anything that can rotate, or is a dummy string, is wrong.
+
+For requests with no real owner, omit the key. A Ruby hash literal cannot omit a key conditionally, which is why the idiomatic shape builds the hash and then assigns:
+
+```ruby
+CLIENT.setup do |request|
+  result = { api_key: CLIENT.mask(request.header("Authorization")) }
+
+  workspace_id = resolve_workspace(request.header("Authorization"))
+  if workspace_id
+    result[:owner] = { id: workspace_id, enrich: method(:load_workspace) }
+  end
+
+  result
+end
+```
+
+### 5.2 `owner[:enrich]`
+
+The **only** channel for owner metadata. Inline `label` / `email` keys on `owner` are dropped; everything except `id` comes back from `enrich`.
+
+```ruby
+enrich: ->(owner_id) {
+  workspace = Workspace.find(owner_id)
+  { label: workspace.name, email: workspace.admin_emails }   # String or Array
+}
+```
+
+A lambda or a `method(:name)` reference both work.
+
+Behaviour:
+
+- Cached by `owner[:id]`. The first request from each owner runs it; the rest skip it.
+- If an upload comes back with `needsEnrichment`, that owner is invalidated and the next request re-runs it.
+- Exceptions are swallowed; the log still ships with the id.
+- Skipped entirely when the same result also returns `block`, so a banned tenant does not cost a database round-trip per owner id forever.
+- The resolved values ride on every subsequent upload, so each log carries full metadata without re-running the lookup.
+
+## 6. The `mask()` gotcha
+
+`CLIENT.mask(value)` produces `sha512-<base64>?<last4>`. The suffix is the LAST 4 CHARACTERS OF THE INPUT, so substituting a placeholder leaks it.
+
+```ruby
+# CORRECT: nil when the header is missing
+api_key: CLIENT.mask(request.header("Authorization"))
+
+# WRONG: "mous" ends up as the mask tail
+api_key: CLIENT.mask(request.header("Authorization") || "anonymous")
+```
+
+`mask` returns nil on nil input and the SDK handles it.
+
+## 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.
+
+```json
+{
+  "version": 1,
+  "projectId": "<team/workspace uuid>",
+  "apis": [
+    {
+      "id": "<api uuid>",
+      "name": "Public API",
+      "rootDir": ".",
+      "oasFile": ".restless/openapi.yaml",
+      "framework": "rails",
+      "language": "ruby",
+      "baseUrl": "https://api.example.com",
+      "requestIdPrefix": "PUB",
+      "redact": { "headers": ["x-company-auth"], "bodyKeys": ["ssh_private_key"] }
+    }
+  ]
+}
+```
+
+The SDK reads `requestIdPrefix` and `redact` from the matching entry. Pick one when several are defined:
+
+```ruby
+Restless.new(ENV["RESTLESS_KEY"], api: "Public API")
+```
+
+## 8. Redaction (on by default)
+
+Sensitive values are redacted BEFORE anything leaves the process.
+
+- **Headers:** `authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `x-api-key`, `x-auth-token`
+- **Body keys and query params:** `password`, `pass`, `pwd`, `token`, `secret`, `apikey`, `accesstoken`, `refreshtoken`, `idtoken`, `sessionid`, `ssn`, `creditcard`, `ccnumber`, `cvv`, `cvc`
+
+Matching is case-insensitive and ignores `-`/`_`, so `api_key` / `apiKey` / `API-KEY` all match. For `authorization` and `proxy-authorization` the scheme word survives (`Bearer <REDACTED:...>`).
+
+Two additive sources on top of the defaults: `apis[].redact` in the settings file, and the `redact:` option. **The option accepts either casing**, so `body_keys:` and `bodyKeys` both work - snake_case reads better in Ruby, camelCase matches the wire format:
+
+```ruby
+Restless.new(key, redact: { headers: ["x-custom"], body_keys: ["api_secret"] })
+```
+
+Sentinel format, which the dashboard pattern-matches:
+
+```
+<REDACTED:<length>>                 # length < 8
+<REDACTED:<length>:<last-4-chars>>  # length >= 8
+```
+
+Bodies are capped at **256 KiB** (UTF-8 bytes) and truncated with `[...TRUNCATED: original N bytes]`.
+
+## 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.
+
+## 10. Blocking
+
+```ruby
+CLIENT.setup do |request|
+  next { block: true } if banned?(request)                              # 403
+  next { block: { status: 429, message: "slow down" } } if limited?(request)
+
+  { api_key: CLIENT.mask(request.header("Authorization")) }
+end
+```
+
+The handler never runs. The response body is JSON `{"error": "<message>"}`. `enrich` is not called for a blocked request.
+
+## 11. Environment variables and batching
+
+| variable | effect |
+|---|---|
+| `RESTLESS_KEY` | Fallback API key when `Restless.new` is called without one |
+| `README_API_KEY` | Secondary fallback |
+| `RESTLESS_BASE_URL` | Override the ingest URL. **Non-localhost `http://` warns loudly** (plaintext auth). |
+| `DEBUG=restless` | Print upload diagnostics to stderr |
+| `RESTLESS_SETUP_MODE=1` | Upload even under a test runner (see below) |
+
+Batching is fixed: 10 requests per batch, a 5000 ms flush interval, a 1000-entry queue that drops oldest on overflow, and immediate flushing against a localhost base URL. Uploads never block a response, and failures are swallowed unless `DEBUG=restless`.
+
+**Test runs do not upload.** Detected via `RAILS_ENV`/`RACK_ENV` of `test`, or RSpec / Minitest / Test::Unit being loaded. Capture still runs, so your tests exercise the real path.
+
+## 12. Common mistakes (don't do these)
+
+- **Mounting with `config.middleware.use` in Rails.** That appends to the bottom of the stack, below `ShowExceptions`, so the SDK sees a rendered error page instead of the exception. Use `insert_before 0`.
+- **Adding a `before_action` instead of middleware.** It runs far too late and only for requests that reach a controller, so every 404 and every rejected request goes unrecorded.
+- **Editing `config/routes.rb`.** The middleware does not go there.
+- **Reading `current_user` in the callback.** The middleware is outside the stack, so it has not been set yet. Resolve the owner from the credential.
+- **`CLIENT.mask(header || "anonymous")`** - see §6.
+- **Using an API key, email, username or JWT as `owner[:id]`** - see §5.1.
+- **Inline `label` / `email` on `owner`** - dropped. They come back from `enrich`.
+- **Constructing a client per request.** Once, at boot.
+- **Reading `.env`, `config/master.key` or `config/credentials.yml.enc` to "check" the key.** LLMs: never read these.
+- **`gem install restless`** - the gem is `restless-sdk`. `restless` is only the require name.
+- **Looking for `restless/rails` or `restless/sinatra`.** There is one Rack middleware.
+
+## 13. Quick verification after installation
+
+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.