railwatch 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 072de4fbe3a2b0854d5e00b3b41b033a901d05d9f681f8e6083ae9c6882e4751
-  data.tar.gz: f24164cbf663302b6df3e302aadf59e7328316a4e6d1c86d1b8b5ad49ee6f85f
+  metadata.gz: 954add09993af5d0756ed9ff1875061f25eed72867139116fd020a90b961627c
+  data.tar.gz: 6fbb618b6eb38d867f9ea7648dfce28d7c46003e1ed9499303a3889de06373af
 SHA512:
-  metadata.gz: 9d3907a21539f08dd1e71d4eb83e0305d749673a51e9eb4d8404e4cff2924665d0c0dd28c5f4e8d62b50174ff0618f7e43d41a5984cd52b24a1d6fe63745dae7
-  data.tar.gz: 1bc7449ec96e9c85432d9f75746a28e4f5152ba71b97d3d32e6b7a9ee4b53044abdf34281a78bf4bf546436b0b8168376b51635daf640fe396fd853163cde638
+  metadata.gz: 88f0a50d4769269d565513d59b03567413424f6566da76d1056d08a1e734d7ce244bc609a06c8a25cd7651873ae1519af968a5f6708b225cb984cb764ab77387
+  data.tar.gz: b882ad5f4cb5a5a3ed16975d1cab018fdd04a0e75be8677baa29882dcc61c56b561096568241e023843d687dc950324a16dedc20200dd4035f51f949535b20c5

data/AGENTS.md

@@ -129,6 +129,13 @@ claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
   --header "Authorization: Bearer rwp_your_token_here"
 ```
 
+In development with railwatch-server no token is needed from the same
+machine: `claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp`,
+or `bin/rails generate railwatch:agents` to write `.mcp.json`, a marked
+block in `AGENTS.md`/`CLAUDE.md` and a Claude Code skill. Development
+responses carry `Server-Timing` and `X-Railwatch-Execution-Id` for
+`get_execution`.
+
 `bin/rails railwatch:mcp` prints this and the Claude Desktop, Cursor, VS Code, and
 Zed equivalents for whichever platform the app points at. Call
 `list_applications` first; then `list_issues`, `get_issue` (stack frames,

data/CHANGELOG.md

@@ -6,6 +6,47 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 1.4.0 (2026-10-26)
+
+- In development each recorded request's response carries
+  `Server-Timing` (`total`, `db` with the query count, `view`, `other`) and
+  `X-Railwatch-Execution-Id`, so `curl -i`, the browser's network panel or a
+  coding agent sees what the request cost and which execution to open.
+  `timing_headers` / `RAILWATCH_TIMING_HEADERS` turns it on or off
+  elsewhere; about 4 µs per request when on.
+- `bin/rails generate railwatch:agents` points coding agents at the
+  development Railwatch: `.mcp.json` with the local MCP server, a marked
+  block in `AGENTS.md` and/or `CLAUDE.md` describing the dev loop, and a
+  Claude Code skill. Re-running it changes only its own block and entry.
+- The beacon refuses a body over 256 KiB before Rails parses it.
+  `limit_payload` ran as a before_action, after ActionController had
+  already parsed the params, and a chunked body was read whole to find its
+  length, so an unauthenticated client could make a worker buffer an
+  unbounded body. A middleware in the engine's stack now refuses an
+  oversized Content-Length unread and reads at most one byte past the
+  limit of a chunked body.
+- A plain-HTTP ingest URL that is not allowed is a permanent failure. The
+  result carried no status, which read as retryable, so the reporter kept
+  the batch and walked its whole backoff ladder for a setting that cannot
+  change between attempts.
+- The Kamal post-deploy hook skips an ingest URL that is not https,
+  loopback, or allowed plain HTTP. An upper-case scheme or a bare host fell
+  through the `case` to curl, which sent the token over plain HTTP.
+
+## 1.3.0 (2026-10-25)
+
+- The initial-load visit splits its TTFB into `redirect_ms`,
+  `connect_ms` and `server_ms`, which add up to `ttfb`, plus
+  `redirect_count`. TTFB is measured from navigation start, so it holds
+  every redirect before the page: a 1.2 s TTFB on a route the server
+  answers in 100 ms was a redirect chain, and nothing said so.
+  `redirect_ms` (navigation start to `fetchStart`) is still measured when
+  a hop is cross-origin, where browsers report `redirectCount` 0; the
+  client then leaves `redirect_count` out rather than claim no redirect.
+  The beacon accepts and clamps the four fields. Receivers must store them
+  for them to show anywhere. Apps that copied the client
+  (`app/frontend/lib/railwatch.ts`) need the same change in their copy.
+
 ## 1.2.0 (2026-10-25)
 
 - Executions send only the counters that fired. Every parent record

data/app/controllers/railwatch/beacon_controller.rb

@@ -10,8 +10,10 @@ module Railwatch
     # forged beacon, not a page load, so it is clamped rather than stored.
     MAX_METRIC_MS = 120_000
     MAX_CLS = 100.0
+    # Browsers stop following a redirect chain at 20 (Fetch's limit).
+    MAX_REDIRECTS = 20
 
-    MAX_REQUEST_BYTES = 256 * 1024
+    MAX_REQUEST_BYTES = Middleware::BeaconLimit::MAX_BYTES
     MAX_VISITS = 50
     MAX_ERRORS = 50
     MAX_ERROR_MESSAGE = 1024
@@ -24,7 +26,9 @@ module Railwatch
 
     RATE_LIMIT_WINDOW = 60 # seconds
 
-    before_action :limit_payload, :verify_origin, :throttle, if: -> { Railwatch.config.beacon_enabled }
+    # The body size is enforced before this controller parses anything, by
+    # Middleware::BeaconLimit in the engine's stack.
+    before_action :verify_origin, :throttle, if: -> { Railwatch.config.beacon_enabled }
 
     def create
       return head :no_content unless Railwatch.config.beacon_enabled
@@ -50,6 +54,7 @@ module Railwatch
           cls: cumulative_layout_shift(v["cls"]),
           inp: metric_ms(v["inp"]),
           ttfb: metric_ms(v["ttfb"]),
+          **ttfb_phases(v),
           user: user_id,
           tenant: tenant,
           user_agent: safe_string(request.user_agent, 256))
@@ -140,10 +145,6 @@ module Railwatch
       head :too_many_requests
     end
 
-    def limit_payload
-      head :content_too_large if request.raw_post.bytesize > MAX_REQUEST_BYTES
-    end
-
     # The browser half of release health: one `session` record per beacon
     # flush, never more, whatever the flush carried. The first one the client
     # sends has no duration yet and opens the session; every later flush
@@ -274,9 +275,38 @@ module Railwatch
     # Web vitals only ride along on the initial-load visit, and only from
     # browsers that support the entry type behind them, so every one of these
     # is nil far more often than not.
+    # A value that is not a finite number ("1e309" parses to Infinity, which
+    # #round refuses) is nil, like a missing one: raising here would drop the
+    # whole beacon at the rescue below, every other visit in it included.
     def metric_ms(value)
+      finite_ms(value)&.round&.clamp(0, MAX_METRIC_MS)
+    end
+
+    # The initial load's TTFB split into phases. They add up to ttfb, so if
+    # clamping any of them (or ttfb itself) would break that sum, the split is
+    # dropped rather than stored inconsistent: ttfb stays, the phases are nil.
+    def ttfb_phases(visit)
+      raw = %w[redirect_ms connect_ms server_ms].to_h { |key| [ key, finite_ms(visit[key]) ] }
+      phases = raw.transform_values { |ms| ms&.round&.clamp(0, MAX_METRIC_MS) }
+      total = finite_ms(visit["ttfb"])
+      clamped = raw.any? { |key, ms| ms && ms.round != phases[key] }
+      over = total && total.round > MAX_METRIC_MS
+      phases = phases.transform_values { nil } if clamped || over
+      phases.transform_keys(&:to_sym).merge(redirect_count: redirect_count(visit["redirect_count"]))
+    end
+
+    def finite_ms(value)
+      return nil if value.nil? || value == ""
+      float = safe_float(value)
+      float.finite? ? float : nil
+    end
+
+    # How many redirects the browser SHOWED. It hides them when any hop was
+    # cross-origin, so the client sends nothing then rather than 0, and a
+    # nil here must stay nil: "none" and "hidden" are different answers.
+    def redirect_count(value)
       return nil if value.nil? || value == ""
-      safe_float(value).round.clamp(0, MAX_METRIC_MS)
+      safe_integer(value).clamp(0, MAX_REDIRECTS)
     end
 
     def cumulative_layout_shift(value)

data/docs/ai-and-mcp.md

@@ -16,7 +16,9 @@ The endpoint is `<your ingest host>/mcp`. For the hosted platform that's
 server runs under the app's dashboard path, so the endpoint is the app's own
 host plus `/railwatch/mcp`; see the
 [railwatch-server README](https://github.com/Rebulk/railwatch-server#readme).
-For Railwatch Cloud and a self-hosted server the gem knows which one you're on:
+In development that endpoint needs no token from the same machine (see
+[In development](#in-development) below). For Railwatch Cloud and a
+self-hosted server the gem knows which one you're on:
 
 ```sh
 bin/rails railwatch:mcp
@@ -24,6 +26,28 @@ bin/rails railwatch:mcp
 
 prints every block below with your platform's host already filled in.
 
+### In development
+
+With `railwatch-server`, the app's own `bin/dev` serves MCP at
+`http://localhost:3000/railwatch/mcp`, and the proxy signs agent requests
+for you, so no token is needed:
+
+```sh
+bin/rails generate railwatch:agents   # .mcp.json, AGENTS.md/CLAUDE.md block, Claude Code skill
+# or by hand:
+claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp
+```
+
+That holds only in development, for a request from the same machine to a
+`localhost`/`127.0.0.1`/`::1` host name, so anyone who can reach the dev
+server's port from this machine can read and comment on its development
+data, as they can already open its dashboard. Other environments need a
+token unless the app sets `Railwatch::Server.config.agent_access = true`.
+Each recorded development response also carries `Server-Timing` and
+`X-Railwatch-Execution-Id` (`timing_headers` in
+[`configuration.md`](configuration.md)), so an agent can `curl -i` a page and
+pass the id to `get_execution`.
+
 ## 1. Get a token
 
 MCP tokens are **per person**, not per application: sign in to the platform,
@@ -146,19 +170,24 @@ they're configured.
 
 Every tool returns JSON as the text body of a single content block. **All
 durations are milliseconds.** Every `window` argument takes `1h`, `6h`,
-`24h`, `7d`, or `30d`, and defaults to `24h`.
+`24h`, `7d`, or `30d`, and defaults to `24h`. `application_slug` and
+`environment` may be left out when the token sees one application, or the
+application has one environment. A result over 60 KB comes back as
+`{"truncated": {…, "hint"}, "result": …}`, still valid JSON, with a hint on how
+to narrow the call. Rows carry a dashboard `url` for the human.
 
 | Tool | Arguments | Returns |
 |---|---|---|
 | `list_applications` | — | applications, their account, and their environments. Start here — everything else takes the `application_slug` and `environment` this returns (plus `account_slug`/`application_id` when two accounts share a slug). |
-| `list_issues` | `application_slug?`, `environment?`, `status?` (`open`/`resolved`/`ignored`, default `open`), `limit?` | issues with key, title, kind, status, priority, occurrence and affected-user counts, culprit, first/last seen. |
-| `get_issue` | `key` or `issue_id` | one issue. For an exception, the sample and latest occurrences with stored stack frames, cause, locals, parsed context, browser breadcrumbs, and the execution it happened inside. For a performance or anomaly issue, the metric, limit or baseline, representative records, trend, and deploy comparison. |
+| `list_issues` | `application_slug?`, `environment?`, `status?` (`open`/`resolved`/`ignored`, default `open`), `sort?` (`impact`), `limit?` | issues with key, title, kind, status, priority, occurrence and affected-user counts, culprit, first/last seen and the dashboard `url`. Newest first by default; `sort: impact` ranks by occurrences discounted by days since last seen. |
+| `get_issue` | `key` or `issue_id`, `frames?` (`all`) | one issue and its dashboard `url`. For an exception, the sample occurrence with stored stack frames (runs of framework and gem frames collapsed to a count unless `frames: "all"`), cause, locals, parsed context, browser breadcrumbs, and the execution it happened inside; the latest occurrence is shown only when it differs from the sample. For a performance or anomaly issue, the metric, limit or baseline, representative records, trend, and deploy comparison. |
 | `update_issue` | `key`, `status?`, `priority?`, `assignee_email?`, `agent?` | the updated issue. Writes an activity entry attributed to your user and `agent`. |
 | `add_comment` | `key`, `body`, `agent?` | the created comment, attributed the same way. |
-| `list_slow_routes` | `application_slug`, `environment`, `window?` | the 20 slowest routes by p95, each with `group_hash`, count, errors, `p95_ms`. |
+| `list_slow_routes` | `application_slug?`, `environment?`, `window?`, `sort?` (`total`/`avg`/`p95`) | the 20 routes that cost the most request time (count × average) by default, each with `group_hash`, count, errors, `total_ms`, `avg_ms`, `p95_ms` and `url`. `sort: p95` ranks by per-request latency. |
 | `get_route` | `application_slug`, `environment`, `route` or `group_hash`, `window?` | one route's count/errors, p50/p95/p99/max, its slowest individual requests, the slowest queries those requests ran, and each N+1 with a concrete Active Record fix. |
 | `search_requests` | `application_slug`, `environment`, `q?`, `window?`, `limit?` | individual requests. `q` is the dashboard's filter grammar: `method:GET`, `route:/checkout`, `status:500` or `status:5xx`, `deploy:…`, `tenant:…`, `user:…`, `min_ms:250`; bare words match the route name. |
-| `get_execution` | `application_slug`, `environment`, `execution_id` | one execution and its full child timeline — every query, cache read, log line, outgoing request, view render, and exception, each offset in ms from the start. |
+| `get_execution` | `application_slug?`, `environment?`, `execution_id`, `timeline_offset?`, `timeline_limit?`, `timeline_type?` | why one execution took as long as it did. `summary` first: time split by sql, transactions, view, external, cache and untracked; the repeated queries and N+1s with their `source` (`file:line`) and an Active Record fix; the slowest records; notes on what to look at. Then one page of the timeline (25 rows by default, `timeline_offset` for more). |
+| `last_execution` | `application_slug?`, `environment?`, `path?`, `kind?` (`request`/`job`), `timeline_offset?`, `timeline_limit?`, `timeline_type?` | the newest request or job in `get_execution`'s shape: the dev loop. `path` matches the request path, route pattern or execution name. With no executions yet, it says why records may be missing. |
 | `explain_query` | `application_slug`, `environment`, `group_hash`, `window?` | the stored query plan for a query group, with the SQL and the sample's duration. `explain` is null unless the app sets `RAILWATCH_CAPTURE_QUERY_EXPLAIN`. `sql` is the normalized shape unless the app also sets `RAILWATCH_CAPTURE_SQL_VALUES`. |
 | `get_profile` | `application_slug`, `environment`, `profile_id?`, `execution_id?`, `limit?` | the hottest frames of a stack profile — self and total samples, each with a percentage. |
 | `search_logs` | `application_slug`, `environment`, `q`, `level?`, `limit?` | matching log lines, each with the `execution_id` to expand with `get_execution`. |
@@ -224,6 +253,15 @@ working *in a Rails app that uses Railwatch*:
 
 Copy either into your own app's repo to give its agent the same context.
 
+For the development loop, `bin/rails generate railwatch:agents` writes into
+the app: `.mcp.json` with the local MCP server (Claude Code's
+[project scope](https://code.claude.com/docs/en/mcp)), a block between
+`<!-- BEGIN railwatch ... -->` and `<!-- END railwatch -->` in `AGENTS.md`
+and/or `CLAUDE.md` (whichever exist; `AGENTS.md` when neither does), and a
+[Claude Code skill](https://code.claude.com/docs/en/skills) at
+`.claude/skills/railwatch/SKILL.md` (`--no-skill` skips it). Re-running it
+replaces only its own block and entry; `--url` points it at another port.
+
 ## See also
 
 - [`getting-started.md`](getting-started.md) — install, the token,

data/docs/configuration.md

@@ -20,6 +20,7 @@ values set in the initializer always win over the env var.
 | `server` | `RAILWATCH_SERVER` | `KAMAL_HOST`, else `Socket.gethostname` | Host stamped on every record. Under Kamal the container hostname carries a per-deploy container id, so the Kamal host wins; it is what the post-deploy hook registers as an expected server, which is what silent-host detection compares against. |
 | `environment` | — | resolved lazily from `Rails.env` | Set `c.environment = "staging"` to report under a name other than the actual Rails env. |
 | `ignored_request_paths` | `RAILWATCH_IGNORED_REQUEST_PATHS` (comma-separated) | `/up,/railwatch/beacon` | Exact request paths that bypass Railwatch's request execution entirely. In Ruby configuration, `Regexp` entries are also supported. Setting the env var replaces the defaults; append with `c.ignored_request_paths += ["/healthz"]` to keep them. |
+| `timing_headers` | `RAILWATCH_TIMING_HEADERS` | on in development, off elsewhere | Adds `Server-Timing` (`total`, `db` with the query count in `desc`, `view`, `other`) and `X-Railwatch-Execution-Id` to every recorded request's response, so `curl -i`, the browser's network panel, or a coding agent sees the cost and the execution to pass to `get_execution`. The id is left out when the request was sampled out. An existing `Server-Timing` (Rails' `config.server_timing`) is appended to. Off outside development by default because it tells every visitor how the app spends its time. Costs about 4 µs per request when on. |
 | `beacon_allowed_origins` | `RAILWATCH_BEACON_ALLOWED_ORIGINS` | `[]` | Extra origins allowed to post to the beacon beyond the app's own, comma-separated: a full origin (`https://app.example.com`) or a bare host. Like Sentry's allowed domains this bounds abuse rather than authenticating, since an endpoint a browser posts to cannot hold a secret. |
 | `beacon_global_rate_limit` | `RAILWATCH_BEACON_GLOBAL_RATE_LIMIT` | `6000` | Beacons accepted per minute across every client, so a rotating address cannot multiply past the per-client limit. 0 disables it. |
 | `beacon_rate_limit` | `RAILWATCH_BEACON_RATE_LIMIT` | `120` | Beacon POSTs accepted per client IP per minute before `POST /railwatch/beacon` answers 429. The beacon is unauthenticated and keeps every browser error it is sent, so this is what stops a script from spending the app's event quota. Counted in the app's cache store; `0` turns it off. |

data/docs/records.md

@@ -768,7 +768,11 @@ entirely if `config.beacon_enabled` is off.
 | `lcp` | Largest Contentful Paint, integer ms, clamped to 0–120000. Initial load only. |
 | `cls` | Cumulative Layout Shift — the largest session window, float rounded to 4 decimals, clamped to 0–100. Initial load only. |
 | `inp` | Interaction to Next Paint, integer ms, clamped to 0–120000. The slowest interaction, not the spec's high percentile. Initial load only. |
-| `ttfb` | Time to First Byte from navigation timing's `responseStart`, integer ms, clamped to 0–120000. Initial load only. |
+| `ttfb` | Time to First Byte from navigation timing's `responseStart`, integer ms, clamped to 0–120000. Initial load only. Includes every redirect before the page. |
+| `redirect_ms` | The part of `ttfb` before the final request started: navigation start to `fetchStart` (`workerStart` when a service worker started first). Every redirect hop, plus a few ms of the browser's own work. Still measured when a hop is cross-origin, when the browser hides the count. Integer ms, clamped to 0–120000. Initial load only. |
+| `redirect_count` | Redirects the browser **showed** (`redirectCount`), clamped to 0–20. Nil when it showed none, which is either no redirect or a cross-origin hop it hid: never read nil as "no redirect", read `redirect_ms`. Initial load only. |
+| `connect_ms` | `ttfb` from the final request's start to `requestStart`: service worker startup, HTTP cache, DNS, TCP and TLS. Integer ms, clamped to 0–120000. Initial load only. |
+| `server_ms` | `ttfb` from `requestStart` to `responseStart`: the network round trip plus the server's time. Integer ms, clamped to 0–120000. Initial load only. |
 | `user` | Resolved server-side from the beacon request's session/cookies, same resolver as every other record. |
 | `tenant` | Current tenant context. |
 | `user_agent` | Truncated to 256 chars. |
@@ -781,7 +785,11 @@ never routed it. It has `method` `"GET"`, `status` `"success"`, and
 four Core Web Vitals. It is held back until the page is first hidden, on
 `visibilitychange`/`pagehide`, so those numbers are final when it ships.
 Every vital is nil on a browser that doesn't support the
-`PerformanceObserver` entry type behind it.
+`PerformanceObserver` entry type behind it. `redirect_ms`, `connect_ms`
+and `server_ms` add up to `ttfb` exactly (the boundaries are rounded
+before subtracting); all three are nil when the browser's timestamps are
+missing or out of order, and when clamping `ttfb` or any phase to the
+120,000 ms cap would leave a split that no longer adds up.
 
 ### `session`
 

data/lib/generators/railwatch/agents/agents_generator.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "rails/generators"
+
+module Railwatch
+  module Generators
+    # Points the coding agents working on this app at its development
+    # Railwatch: the MCP server the railwatch-server gem serves at
+    # <mount>/mcp (no token needed from this machine in development), and a
+    # short note on the dev loop. Every file it touches is either its own or
+    # changed only between its markers, so it can be re-run after an upgrade.
+    class AgentsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Writes .mcp.json (Claude Code's project MCP servers) with this app's development Railwatch, " \
+           "a marked Railwatch block in AGENTS.md and/or CLAUDE.md, and a Claude Code skill. Safe to re-run."
+
+      class_option :url, type: :string,
+                         desc: "The MCP endpoint. Default: http://localhost:<PORT or 3000><mount>/mcp."
+      class_option :skill, type: :boolean, default: true,
+                           desc: "Write .claude/skills/railwatch/SKILL.md."
+
+      SERVER_NAME = "railwatch"
+      BEGIN_MARKER = "<!-- BEGIN railwatch (bin/rails generate railwatch:agents) -->"
+      END_MARKER = "<!-- END railwatch -->"
+      AGENT_FILES = %w[AGENTS.md CLAUDE.md].freeze
+
+      # Claude Code's project scope: { "mcpServers": { name: { "type": "http",
+      # "url": ... } } } in .mcp.json at the root
+      # (https://code.claude.com/docs/en/mcp, "Project scope"). Only the
+      # railwatch entry is written; other servers and keys are kept.
+      def write_mcp_json
+        path = File.join(destination_root, ".mcp.json")
+        config = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        return say("Not touching .mcp.json: its top level is not a JSON object.", :red) unless config.is_a?(Hash)
+
+        servers = config["mcpServers"] ||= {}
+        return say("Not touching .mcp.json: its mcpServers is not a JSON object.", :red) unless servers.is_a?(Hash)
+
+        entry = { "type" => "http", "url" => mcp_url }
+        return say_status(:identical, ".mcp.json", :blue) if servers[SERVER_NAME] == entry
+
+        servers[SERVER_NAME] = entry
+        create_file ".mcp.json", "#{JSON.pretty_generate(config)}\n", force: true
+      rescue JSON::ParserError => e
+        say("Not touching .mcp.json: it is not valid JSON (#{e.message.lines.first.strip}). Add this under mcpServers yourself: " \
+            "#{JSON.generate(SERVER_NAME => { "type" => "http", "url" => mcp_url })}", :red)
+      end
+
+      # The block goes into whichever of AGENTS.md and CLAUDE.md exist, and
+      # AGENTS.md is created when neither does. Between its markers it is
+      # replaced on every run; nothing outside them is changed.
+      def write_agent_instructions
+        existing = AGENT_FILES.select { |name| File.exist?(File.join(destination_root, name)) }
+        (existing.empty? ? [ "AGENTS.md" ] : existing).each { |name| write_block(name, block) }
+      end
+
+      # A Claude Code project skill (https://code.claude.com/docs/en/skills):
+      # .claude/skills/<name>/SKILL.md, frontmatter `name` and `description`.
+      # The whole file is this generator's, rewritten on every run.
+      def write_skill
+        return unless options[:skill]
+
+        template "SKILL.md", ".claude/skills/railwatch/SKILL.md", force: true
+      end
+
+      def show_next_steps
+        say <<~STEPS, :green
+
+          Railwatch MCP for this app (development): #{mcp_url}
+            Claude Code reads .mcp.json and asks once before it uses a project server.
+            Other clients: add the same URL as a streamable HTTP MCP server.
+            No token is needed from this machine in development (railwatch-server).
+            Anywhere else, send one: Authorization: Bearer rwp_... (Settings -> Profile).
+        STEPS
+      end
+
+      # `contents` with the marked block replaced by `block`, or with it
+      # appended (after a blank line) when there is none. The block replaced
+      # is the first BEGIN whose END comes before any other BEGIN, so a BEGIN
+      # left without its END is never paired with a later block's END (which
+      # would delete everything between them): it stays as it is, and the
+      # block is appended once and then found on every re-run.
+      def self.with_block(contents, block)
+        return block if contents.nil? || contents.strip.empty?
+
+        start = finish = nil
+        at = 0
+        while (candidate = contents.index(BEGIN_MARKER, at))
+          after = candidate + BEGIN_MARKER.length
+          close = contents.index(END_MARKER, after)
+          reopen = contents.index(BEGIN_MARKER, after)
+          if close && (reopen.nil? || close < reopen)
+            start, finish = candidate, close
+            break
+          end
+          at = after
+        end
+        if finish
+          tail = contents[(finish + END_MARKER.length)..].sub(/\A\n/, "")
+          "#{contents[0...start]}#{block}#{tail}"
+        else
+          "#{contents.sub(/\n*\z/, "\n")}\n#{block}"
+        end
+      end
+
+      private
+
+      def mcp_url
+        options[:url].presence || "http://localhost:#{ENV.fetch("PORT", "3000")}#{mount_path}/mcp"
+      end
+
+      def dashboard_url
+        mcp_url.delete_suffix("/mcp")
+      end
+
+      # The app itself, for the curl in the instructions.
+      def app_url
+        dashboard_url.delete_suffix(mount_path)
+      end
+
+      # The slug railwatch-server gives the app it provisions: the app's
+      # module name, parameterized.
+      def app_slug
+        name = defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : File.basename(destination_root)
+        name.to_s.parameterize
+      end
+
+      def mount_path
+        path = defined?(Railwatch::Server) && Railwatch::Server.respond_to?(:config) ? Railwatch::Server.config.normalized_mount_path : "/railwatch"
+        path.to_s.empty? ? "/railwatch" : path
+      end
+
+      def block
+        content = ERB.new(File.read(File.join(self.class.source_root, "agents_block.md.tt")), trim_mode: "-").result(binding).strip
+        "#{BEGIN_MARKER}\n#{content}\n#{END_MARKER}\n"
+      end
+
+      def write_block(name, text)
+        path = File.join(destination_root, name)
+        current = File.exist?(path) ? File.read(path) : nil
+        updated = self.class.with_block(current, text)
+        return say_status(:identical, name, :blue) if updated == current
+
+        create_file name, updated, force: true
+      end
+    end
+  end
+end

data/lib/generators/railwatch/agents/templates/SKILL.md.tt

@@ -0,0 +1,32 @@
+---
+name: railwatch
+description: Find out why a page or job in this Rails app is slow or failing in development, using Railwatch (SQL with file:line, N+1s, views, logs, exceptions per request). Use after changing code that touches the database or views, when a request is slow, or to check a performance fix.
+---
+
+# Railwatch in development
+
+The `railwatch` MCP server (<%= mcp_url %>, in `.mcp.json`) reads what
+this app recorded while it ran under `bin/dev`. No token is needed from this
+machine. Arguments: `application_slug: "<%= app_slug %>"`, `environment: "development"`.
+
+1. Make the request and read its cost from the response headers:
+
+   ```sh
+   curl -si <%= app_url %>/path | grep -i -e server-timing -e x-railwatch
+   ```
+
+   `Server-Timing: total;dur=…, db;dur=…;desc="N queries", view;dur=…, other;dur=…`
+   and `X-Railwatch-Execution-Id: <id>`. A request with a session needs its
+   cookie (`-b`), or use the id from the browser's network panel.
+2. `get_execution(execution_id: <id>)`, or `last_execution(path: "/path")`
+   without the id: `summary` first (where the time went, the repeated
+   queries and N+1s with their `source` `file:line` and a fix), then a page
+   of the timeline (`timeline_offset` for more).
+3. `get_route(route: "GET /path")`: the route's N+1s with the line and the
+   `includes` that fixes each, and its slowest queries. `explain_query` for a
+   query's plan.
+4. Change the code, repeat 1-2, and report the before and after query count
+   and db time.
+
+For a person, link the dashboard: <%= dashboard_url %>. Errors:
+`list_issues`, then `get_issue(key:)`.

data/lib/generators/railwatch/agents/templates/agents_block.md.tt

@@ -0,0 +1,26 @@
+## Railwatch (performance and errors, in development)
+
+Every request, job and command this app runs in development is recorded by
+the `railwatch` gem into the server `railwatch-server` runs beside it: SQL
+(with the `file:line` that ran it), N+1s, views, logs and exceptions, all
+linked to one execution.
+
+- MCP server `<%= SERVER_NAME %>` at <%= mcp_url %> (in `.mcp.json`). No token from
+  this machine in development. Tools take `application_slug: "<%= app_slug %>"`
+  and `environment: "development"`; `list_applications` lists them.
+- Dashboard, for the human: <%= dashboard_url %>
+
+The loop after a change:
+
+1. Hit the page: `curl -si <%= app_url %>/path | grep -i -e server-timing -e x-railwatch`.
+   `Server-Timing` has total, db (with the query count), view and other;
+   `X-Railwatch-Execution-Id` names the execution.
+2. `get_execution` with that id, or `last_execution` (optionally with a
+   `path`): a summary of where the time went, the repeated queries and N+1s
+   with their `source` (`file:line`), then a page of the timeline.
+3. `get_route` for the route: its N+1s, each with the source line and an
+   `includes` to add, and its slowest queries.
+4. Fix, hit the page again, compare the query count and db time.
+
+`search_requests`, `list_slow_routes`, `list_issues` and `get_issue` cover the
+rest.

data/lib/generators/railwatch/install/templates/post-deploy

@@ -37,6 +37,12 @@ case "$INGEST" in
       exit 0
     fi
     ;;
+  *)
+    # An upper-case scheme or a bare host: curl would send the token over
+    # plain HTTP, which none of the branches above allowed.
+    echo "Railwatch deploy marker skipped: unsupported ingest URL (use https://)" >&2
+    exit 0
+    ;;
 esac
 
 post() {

data/lib/generators/railwatch/install/templates/railwatch.ts

@@ -1,7 +1,8 @@
 // Railwatch browser client for Inertia. Reports each visit's duration,
 // component, and prop payload size to /railwatch/beacon so the platform can
-// show real page-load timing, plus Core Web Vitals (LCP, CLS, INP, TTFB)
-// for the initial page load, plus every JavaScript error the page throws
+// show real page-load timing, plus Core Web Vitals (LCP, CLS, INP, TTFB,
+// with TTFB split into redirect / connection / server time) for the
+// initial page load, plus every JavaScript error the page throws
 // with the breadcrumb trail that led to it.
 // No dependencies -- every metric comes from PerformanceObserver or the
 // navigation timing entry, and every API is feature-detected, so browsers
@@ -23,6 +24,11 @@ interface Visit {
   cls?: number
   inp?: number
   ttfb?: number
+  // TTFB split into phases (initial load only; see ttfbPhases).
+  redirect_ms?: number
+  redirect_count?: number
+  connect_ms?: number
+  server_ms?: number
 }
 
 // The tab's session, for release health. sessionStorage scopes it to the
@@ -679,6 +685,58 @@ function pageComponent(): string | undefined {
   }
 }
 
+// Where the initial load's TTFB went, in three phases that add up to it:
+//
+//   redirect_ms  navigation start -> the final request's start: every
+//                redirect hop, plus the browser's own few ms (so never
+//                quite 0).
+//   connect_ms   -> requestStart: service worker startup, HTTP cache, DNS,
+//                TCP and TLS for the final request.
+//   server_ms    -> responseStart: the network round trip and the server's
+//                time.
+//
+// The final request starts at fetchStart, or at workerStart when a service
+// worker had to start first (the web-vitals library cuts there too).
+//
+// redirect_ms stays honest when a hop is cross-origin. The browser then
+// zeroes redirectCount, redirectStart and redirectEnd (Navigation Timing 2),
+// but fetchStart is still the final request's start (Fetch's "post-redirect
+// start time"), so the hidden hops' time is still in it.
+//
+// redirect_count is sent only when the browser shows the redirects. A 0
+// means "no redirect" or "hidden", and a hidden redirect must never be
+// reported as no redirect.
+//
+// The boundaries are rounded before subtracting, so the three phases add up
+// to the reported ttfb exactly. A browser whose timestamps are missing or
+// out of order sends no phases rather than a wrong split.
+function ttfbPhases(nav: PerformanceNavigationTiming): Partial<Visit> {
+  const fetchStart =
+    nav.workerStart > 0 && nav.workerStart < nav.fetchStart
+      ? nav.workerStart
+      : nav.fetchStart
+  // Order is judged on the raw timestamps: rounding first would let a
+  // requestStart a hair before fetchStart through as a 0 ms phase.
+  const ordered =
+    nav.responseStart > 0 &&
+    fetchStart >= nav.startTime &&
+    nav.requestStart >= fetchStart &&
+    nav.responseStart >= nav.requestStart
+  if (!ordered) return {}
+  const [start, fetched, requested, responded] = [
+    nav.startTime,
+    fetchStart,
+    nav.requestStart,
+    nav.responseStart,
+  ].map(Math.round)
+  return {
+    redirect_ms: fetched - start,
+    redirect_count: nav.redirectCount > 0 ? nav.redirectCount : undefined,
+    connect_ms: requested - fetched,
+    server_ms: responded - requested,
+  }
+}
+
 // The first page load is a visit too -- it just wasn't routed by Inertia, so
 // the component name comes off the root element's serialized page object.
 function initialVisit(): Visit | null {
@@ -696,6 +754,7 @@ function initialVisit(): Visit | null {
     component,
     duration_ms: duration,
     status: "success",
+    ...ttfbPhases(nav),
   }
 }
 

data/lib/railwatch/configuration.rb

@@ -86,7 +86,7 @@ module Railwatch
                   :capture_job_arguments, :capture_job_retry_errors, :capture_response_body_on_error, :max_attachment_bytes,
                   :track_sessions, :session_flush_interval, :session_timeout,
                   :capture_console, :interactive_runner_paths, :ignored_request_paths,
-                  :capture_llm_content
+                  :capture_llm_content, :timing_headers
 
     attr_reader :deploy, :deploy_source, :detect_deploy, :user_resolver, :beacon_user_resolver,
                 :fingerprint_resolver, :redactors, :rejectors, :before_ingest, :backpressure_high_water
@@ -238,6 +238,13 @@ module Railwatch
         DEFAULT_INTERACTIVE_RUNNER_PATHS.dup
       @ignored_request_paths = ENV["RAILWATCH_IGNORED_REQUEST_PATHS"]&.split(",")&.map(&:strip)&.reject(&:empty?) ||
         DEFAULT_IGNORED_REQUEST_PATHS.dup
+      # Server-Timing (total, db with the query count, view, other) and
+      # X-Railwatch-Execution-Id on each recorded request's response, for
+      # `curl -i`, the browser's network panel, and an agent that wants the
+      # execution it just caused. nil: on in development only
+      # (#timing_headers?), since elsewhere they tell every visitor how the
+      # app spends its time.
+      @timing_headers = env_bool("RAILWATCH_TIMING_HEADERS", nil)
       @user_resolver = nil
       @beacon_user_resolver = nil
       @fingerprint_resolver = nil
@@ -364,6 +371,11 @@ module Railwatch
       @environment || (defined?(Rails) ? Rails.env.to_s : "production")
     end
 
+    # Whether the request middleware adds its timing headers (#timing_headers).
+    def timing_headers?
+      @timing_headers.nil? ? defined?(Rails) && Rails.env.development? : @timing_headers
+    end
+
     # Matches Railwatch.reject_cache_keys entries and DEFAULT_VENDOR_CACHE_KEYS
     # against a cache key. A Regexp is used as-is. A String starting with "^"
     # or containing another regex metacharacter is compiled as a Regexp; a

data/lib/railwatch/engine.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require "railwatch/middleware/beacon_limit"
+
 module Railwatch
   # Mounted for the browser beacon (POST <mount>/beacon), its only route.
   class Engine < ::Rails::Engine
     isolate_namespace Railwatch
 
+    config.middleware.use Railwatch::Middleware::BeaconLimit
+
     # The request middleware goes first so wall time includes every other
     # middleware, exactly like Nightwatch's GlobalMiddleware.
     initializer "railwatch.middleware", before: :load_config_initializers do |app|

data/lib/railwatch/middleware/beacon_limit.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Middleware
+    # Refuses an oversized beacon body before Rails parses it. The check
+    # cannot live in BeaconController: ActionController parses the params
+    # (ParamsWrapper, parameter filtering for the log line) before any
+    # before_action, and Request#content_length on a chunked body reads it
+    # whole. In the engine's own stack, so it sees only the beacon route.
+    class BeaconLimit
+      MAX_BYTES = 256 * 1024
+
+      def initialize(app, limit = MAX_BYTES)
+        @app = app
+        @limit = limit
+      end
+
+      def call(env)
+        return too_large if env["CONTENT_LENGTH"].to_i > @limit
+        return @app.call(env) if env["CONTENT_LENGTH"] || !(input = env["rack.input"])
+
+        # Chunked: no length up front, so read at most one byte past the
+        # limit and hand the rest of the stack a body it can read again.
+        body = read_bounded(input)
+        return too_large if body.bytesize > @limit
+
+        env["rack.input"] = StringIO.new(body)
+        env["CONTENT_LENGTH"] = body.bytesize.to_s
+        env.delete("HTTP_TRANSFER_ENCODING")
+        @app.call(env)
+      end
+
+      private
+
+      # Rack lets read(n) return fewer than n bytes before the end, so keep
+      # reading until the end or one byte past the limit, never further.
+      def read_bounded(input)
+        body = +"".b
+        while body.bytesize <= @limit
+          chunk = input.read(@limit + 1 - body.bytesize) or break
+          break if chunk.empty?
+
+          body << chunk
+        end
+        body
+      end
+
+      def too_large
+        [ 413, { "content-type" => "text/plain" }, [] ]
+      end
+    end
+  end
+end

data/lib/railwatch/middleware/request.rb

@@ -20,6 +20,10 @@ module Railwatch
       # CONTENT_TYPE test Subscribers::Requests uses before its params walk.
       MULTIPART = "multipart/form-data"
       NO_FILES = [].freeze
+      # Response headers written with config.timing_headers. Lower case, as
+      # Rack 3 requires; Rack::Headers matches any case.
+      SERVER_TIMING = "server-timing"
+      EXECUTION_ID = "x-railwatch-execution-id"
 
       # Returns [trace_id, parent_id, sampled] from an inbound traceparent,
       # or nil when the header is absent or malformed.
@@ -55,21 +59,58 @@ module Railwatch
         exe.keep! if upstream_sampled
         exe.enter_stage(:middleware_before)
         env["railwatch.execution"] = exe
-        status = headers = body = nil
+        status = headers = body = parent = nil
+        timing = Railwatch.config.timing_headers?
         begin
           status, headers, body = @app.call(env)
+          server_timing(env, exe, headers) if timing && headers
         rescue Exception => e # rubocop:disable Lint/RescueException
           Subscribers::Exceptions.capture(e, handled: false, severity: :error, source: "railwatch.middleware")
           raise
         ensure
           exe.enter_stage(:middleware_after) unless exe.stage == :middleware_after
-          finish(env, exe, status, headers)
+          parent = finish(env, exe, status, headers)
         end
+        execution_id(exe, headers) if timing && headers && parent
         [ status, headers, body ]
       end
 
       private
 
+      # config.timing_headers (development by default): what this request
+      # cost, on the response, so `curl -i` or the browser's network panel
+      # shows it without opening the dashboard. Everything here is already
+      # known: the counters, and the runtimes the process_action subscriber
+      # put in env. Appended to a Server-Timing the app (Rails' own, with
+      # config.server_timing) already set, whether one string or several.
+      def server_timing(env, exe, headers)
+        total = exe.duration / 1000.0
+        db = env["railwatch.db_runtime"]
+        view = env["railwatch.view_runtime"]
+        queries = exe.counters[:queries]
+        cached = exe.counters[:cached_queries]
+        desc = cached.positive? ? "#{queries} queries, #{cached} cached" : "#{queries} #{queries == 1 ? "query" : "queries"}"
+        metrics = [ format("total;dur=%.1f", total), db ? format("db;dur=%.1f;desc=\"%s\"", db, desc) : "db;desc=\"#{desc}\"" ]
+        metrics << format("view;dur=%.1f", view) if view
+        metrics << format("other;dur=%.1f;desc=\"not db or view\"", [ total - db.to_f - view.to_f, 0 ].max) if db || view
+        # A plain Hash may hold it title-cased; Rack::Headers finds either.
+        existing = Array(headers[SERVER_TIMING] || headers.delete("Server-Timing")).join(", ")
+        headers[SERVER_TIMING] = existing.empty? ? metrics.join(", ") : "#{existing}, #{metrics.join(", ")}"
+      rescue StandardError => e
+        # A frozen header hash (a Rack app that returns a constant): the
+        # response is the app's, unchanged.
+        Railwatch.debug { "timing headers skipped: #{e.class}: #{e.message}" }
+      end
+
+      # The execution an agent passes to get_execution. Only once the
+      # request record has shipped (head-sampled in, kept, or rescued by the
+      # tail decision): any other id is one the server never has.
+      def execution_id(exe, headers)
+        headers[EXECUTION_ID] = exe.id
+      rescue StandardError => e
+        Railwatch.debug { "execution id header skipped: #{e.class}: #{e.message}" }
+      end
+
       def ignored_request?(env)
         path = env["PATH_INFO"].to_s
         Railwatch.config.ignored_request_paths.any? do |pattern|
@@ -111,13 +152,16 @@ module Railwatch
         # The block is only called when the request record is going to ship;
         # a head-sampled-out request nothing rescued skips the
         # ActionDispatch::Request and the header walk entirely.
-        Railwatch.finish_execution(:request) { parent_fields(env, exe, status, headers) }
+        parent = Railwatch.finish_execution(:request) { parent_fields(env, exe, status, headers) }
         # A request with no user and no session cookie has no session, and
         # Sessions.touch returns without writing anything.
         Sessions.touch(exe, env, status) if Railwatch.config.track_sessions
+        # The request record, when one shipped.
+        parent
       rescue StandardError => e
         Railwatch.debug { "request finish failed: #{e.class}: #{e.message}" }
         Railwatch.finish_execution
+        nil
       end
 
       def parent_fields(env, exe, status, headers)

data/lib/railwatch/transport/http.rb

@@ -69,9 +69,9 @@ module Railwatch
       end
 
       def deliver(records, dropped: 0, dropped_bytes: 0, backpressure_factor: 1.0, batch_id: SecureRandom.uuid)
-        unless destination_allowed?
-          return Result.new(ok: false, error: "plain HTTP ingest is disabled; use HTTPS or set RAILWATCH_ALLOW_HTTP=true")
-        end
+        # Permanent: it cannot change between attempts, and with no status
+        # the result would read as retryable and walk the backoff ladder.
+        return permanent("plain HTTP ingest is disabled; use HTTPS or set RAILWATCH_ALLOW_HTTP=true") unless destination_allowed?
         return Result.new(ok: false, status: UNAUTHORIZED_STATUS, error: "unauthorized, flushing stopped") if @unauthorized
 
         encoded = @encoder.encode(records)

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/railwatch/wire_fixtures.json

@@ -605,6 +605,10 @@
     "cls": null,
     "inp": null,
     "ttfb": null,
+    "redirect_ms": null,
+    "redirect_count": null,
+    "connect_ms": null,
+    "server_ms": null,
     "user": null,
     "tenant": null,
     "user_agent": ""

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Cole Robertson
@@ -70,6 +70,9 @@ files:
 - docs/source-maps.md
 - docs/testing.md
 - docs/troubleshooting.md
+- lib/generators/railwatch/agents/agents_generator.rb
+- lib/generators/railwatch/agents/templates/SKILL.md.tt
+- lib/generators/railwatch/agents/templates/agents_block.md.tt
 - lib/generators/railwatch/install/install_generator.rb
 - lib/generators/railwatch/install/templates/initializer.rb.tt
 - lib/generators/railwatch/install/templates/post-deploy
@@ -91,6 +94,7 @@ files:
 - lib/railwatch/health.rb
 - lib/railwatch/job_tracing.rb
 - lib/railwatch/json_compat.rb
+- lib/railwatch/middleware/beacon_limit.rb
 - lib/railwatch/middleware/request.rb
 - lib/railwatch/minitest.rb
 - lib/railwatch/patches.rb