railwatch 0.1.4 → 0.2.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b78b98999447f64098f912cdfdcbb6202c9331ac4e07988fb350080d084f79c
-  data.tar.gz: e230f37a0a728c381fc4b84849bc0db762ad14e2b9c37aa5802850b97cba7271
+  metadata.gz: 9500835353b9f428ff09ae908f9cbc360c44f0ea01740139738ec8c06ce73eb2
+  data.tar.gz: 7b4e2b48a881ef09243af6d2f51865609bd5615e55d27d9fca784f3e2740de7b
 SHA512:
-  metadata.gz: 27c7659440a7e1592b99d10ad2a409c711a2b5a44cafee9a4707ff8672e0952fcf6819ad5b98c96f4e9d25ae6e1c5b86193ebb70a74b52904f8aee808977c72d
-  data.tar.gz: c1101b7933f5703f4dfd7469b07bf9ac3f39cfaee7bd2a9d451e30126921c33a0326c5976d8605e7dce39f13b10b8d65fd8052007051775bc9e46f0b5cbb6368
+  metadata.gz: 0d38ab1fced44ae3168de8f7864b858732ad07a26a4a9a96d82b74891d3b20144b9cc19a703743a127a2d270552ba422e9d51c1c9f8e768077c5a12364f613c8
+  data.tar.gz: 0e4ad6b17f76856cc2f160c64c992ed8405e50ba9485563c6e3b40495fdb11c1da756d8aa0317adec1d78b93f4b3dc6783de196c33c42d58dbbc606e3491310f

data/CHANGELOG.md

@@ -1,5 +1,210 @@
 # Changelog
 
+## Unreleased
+
+- Embedded mode: `bin/rails generate railwatch:install --local` keeps
+  every record in two SQLite databases the app owns (`railwatch` for
+  issues, comments, saved views, thresholds and deploys;
+  `railwatch_telemetry` for what the app reports) and serves the whole
+  Railwatch dashboard at `/railwatch`, from a bundle shipped inside the
+  gem. No token, no Node, no asset pipeline. `c.transport = :local`
+  (`RAILWATCH_TRANSPORT=local`) switches the reporter to write batches
+  in-process; everything else about sampling, redaction and buffering is
+  unchanged. The installer adds the databases (migrated from the gem's own
+  migration history, so a gem update is followed by `db:prepare` and
+  nothing else) and an
+  initializer with `issue_prefix`, `repository_url`, `retention_days`
+  and a `dashboard_user` resolver. `railwatch:doctor`, `railwatch:status`
+  and `railwatch:deploy` understand the mode. See docs/embedded.md.
+- Embedded mode needs no job worker. Exceptions are grouped into issues
+  as each batch lands, and release health, threshold and anomaly scans,
+  missed scheduled tasks, auto-resolve and pruning run from
+  `Railwatch::Maintenance`, a clocked thread in every web and worker
+  process (one process per server runs each task, leased through the new
+  `railwatch_maintenance_tasks` table). Nothing goes through Active Job,
+  so the gem never writes the host's queue adapter, and a dead worker
+  cannot hide its own missed runs. The installer no longer edits
+  `config/recurring.yml`; remove any `Railwatch::*` entries a pre-release
+  added there.
+- Embedded ingest folds each batch into the hourly rollups as it lands
+  (`Ingest::RollupAbsorber`), so the dashboard's counts and percentiles
+  move with every batch; the hosted platform's per-batch RollupJob
+  recompute is not enqueued in embedded mode and the minute-long
+  aggregate cache is bypassed there.
+- Embedded mode gets a writer process. `plugin :railwatch` in
+  `config/puma.rb` (added by `--local`) forks one `Railwatch::Writer`
+  from the Puma master, the way Solid Queue's in-Puma mode does. Web
+  workers hand their batches to it over a Unix socket
+  (`Transport::Socket`) instead of writing SQLite on their own reporter
+  thread, so mapping, the write lock, rollups, issue grouping and the
+  maintenance clock all run in a process whose interpreter no request
+  shares. The writer is restarted by Puma if it dies and stops with it;
+  a process with no writer (a runner, a Solid Queue worker, a server
+  without the plugin) writes in-process from its first miss. The doctor
+  reports whether the writer is listening. Measured
+  on a two-worker Puma host under five minutes of open-loop load with
+  every record sampled: all-paths p95 817 ms with the writer against
+  938 ms writing on the worker threads and 716 ms with Railwatch off, and
+  each worker's reporter thread fell from 7 s of CPU per minute of load
+  to 2 s over the whole run.
+- Hardening from an adversarial review of the writer: a batch's
+  exceptions are counted onto an issue exactly once however many times
+  its follow-ups run (a `railwatch_followup_receipts` row per batch and
+  group, committed with the count); the wedge guard tracks each write by
+  invocation so a retry of the same batch cannot hide a stuck original;
+  the writer reads and writes under deadlines, bounds inflation and the
+  accept queue, binds inside a 0700 directory as a 0600 socket, and
+  refuses to take over a socket another writer is answering on; Puma
+  phased restarts restart the writer rather than losing it; workers
+  under the plugin retain batches while the writer is away, and any
+  other process falls back to in-process writing on the first miss
+  (including a stale socket file); a maintenance lease is released only
+  by the token that claimed it and a failed task is retried next tick;
+  maintenance failures report through `on_unrecoverable`, never
+  `Rails.error`; pruning is bounded per run. The plugin is cluster-mode
+  only.
+- Embedded ingest keeps a delivery ledger. The reporter's batch id is
+  stored on the `ingest_batches` row inside the batch's own transaction,
+  so a batch the reporter retries after a failure is written once, and
+  a write that fails is now retried with the same backoff the HTTP
+  transport gets instead of being dropped. The exception grouping a
+  batch owes is recorded on that row as well and cleared when done; a
+  process that dies in between leaves it for `Railwatch::Maintenance` to
+  finish on its next tick, so an exception can no longer be stored
+  without ever becoming an issue.
+- A missed scheduled task says why, when Solid Queue is the adapter:
+  the scheduler never enqueued the run, it was enqueued but no worker
+  is running, or it is enqueued and waiting behind a backlog. Read from
+  Solid Queue's own `recurring_executions` and `processes` tables.
+- `rails runner script/x.rb` is a deployed script even when the whole
+  application is checked out under a scratch directory such as `/tmp`;
+  only a scratch path inside the app still counts as interactive.
+- `RollupJob` no longer overwrites a rollup that a batch folded into
+  between its read and its write: a stored count higher than the
+  recomputed one is kept, and the next run picks the group up.
+- `PruneTelemetryJob` takes `checkpoint:`; the embedded clock prunes with
+  a PASSIVE WAL checkpoint so it never blocks the app's own readers.
+- The affected-user count on an issue is recomputed at most once every
+  five minutes per issue (and always for a new one) instead of on every
+  batch that touched the group.
+- The gem now depends on `inertia_rails` and `tdigest` for the dashboard.
+- Embedded install is one command and boots in production. `bin/rails
+  generate railwatch:install --local` now creates and migrates both
+  databases itself (no separate `db:prepare`), fills in the production
+  `database:` paths Rails 8.1's template leaves commented out. The two
+  entries name `adapter: sqlite3` themselves instead of inheriting the
+  app's default, so embedded mode works on a PostgreSQL or MySQL app (the
+  generator adds `gem "sqlite3"` there and asks for a `bundle install`
+  first) and needs no `&default` anchor to exist. The gem
+  depends on `json < 3` for now: Rails 8.1 cannot decode with json 3
+  (rails/rails#58784), which broke this gem's own SQLite migrations on a
+  fresh Ruby 3.4.10, and a dependency is what makes `bundle add
+  railwatch` resolve past it. The engine loads Active Job itself
+  and treats Action Cable as optional, so an app from `rails new
+  --minimal` boots with it.
+- The engine's models never fall back to the host's primary database. Both
+  abstract bases rescue a missing `database.yml` entry so a cloud-transport
+  app still boots and eager-loads them, but using one then raises
+  `Railwatch::DatabaseNotConfigured` instead of inheriting
+  `ActiveRecord::Base`'s connection -- where the unprefixed telemetry
+  tables (`sessions`, `visits`, `people`, `notifications`) are the
+  application's own.
+- The in-process fallback is provisional: a process that found no writer
+  re-checks the socket every 30 seconds instead of writing its own batches
+  for the rest of its life, and a process that expects a writer stops
+  retaining and writes its own after a minute without one, rather than
+  holding batches until the retry cap drops them. A batch abandoned after the retry cap is now
+  reported through `on_unrecoverable` rather than only under
+  `RAILWATCH_DEBUG`, and `railwatch:doctor` no longer calls a configured
+  but absent writer a pass.
+- The generated Puma line is `plugin :railwatch`, unconditional:
+  `bundle exec puma` evaluates `config/puma.rb` before it loads the app,
+  so the old `if defined?(Railwatch)` guard meant a writer was never
+  started there. The plugin itself now decides whether to run after boot.
+- Embedded mode is verified on PostgreSQL and MySQL hosts, not only
+  SQLite ones. The telemetry databases are SQLite files whatever the
+  application runs on, so the install is `generate`, `bundle install`
+  (for the sqlite3 gem the generator adds), then `db:prepare`. On both,
+  the app's own databases keep every table they had and the server gains
+  no Railwatch table at all.
+- Releasing is gated on the thing that silently breaks it. `gem build`
+  globs its file list, so a missing or half-built dashboard produces a
+  gem that installs cleanly and serves a blank page; `rake
+  package:assert_dashboard` refuses to publish one, and the release
+  workflow runs it between building the bundle and building the gem. The
+  publish job also installs the bundle it was already calling `bundle
+  exec` against, which it had never done. Built `.gem` files are no
+  longer tracked in git.
+- The browser beacon is bounded the way a hosted product bounds a public
+  ingest endpoint, since one cannot hold a credential the page does not
+  already give away: an origin allowlist (`beacon_allowed_origins`,
+  same-origin by default, the analogue of Sentry's allowed domains), the
+  per-client rate limit, and a new ceiling for the endpoint as a whole
+  (`beacon_global_rate_limit`, 6,000/minute) so a rotating address cannot
+  multiply past the first. Both limits fail closed on a cache store that
+  cannot count, where the limiter used to fail open.
+- How the dashboard is gated is now something the app states rather than
+  something the gem guesses. `Configuration#dashboard_gate` names it:
+  HTTP Basic, a `base_controller_class`, a `dashboard_user` resolver that
+  can refuse, or `dashboard_open = true` for a dashboard that is public on
+  purpose (a private network, a VPN, a routes constraint the gem cannot
+  see). With Basic off and none of them set the gate is undeclared: the
+  dashboard still serves, because a constraint is a legitimate answer, but
+  the app logs a warning at every boot outside development, the doctor
+  reports it, and live updates are refused. The live channel follows the
+  declared gate, which matters because Action Cable runs on the host's own
+  `/cable` endpoint that no routes constraint around the mount covers.
+- Railwatch no longer pins `json` for the host. The Rails 8.1 and json 3
+  incompatibility (rails/rails#58784) is the application's own, and a
+  gemspec dependency would constrain every bundle for it. The gem detects
+  the pair by asking it to decode rather than by comparing version
+  numbers, so a patched Rails or a backport is judged correctly and the
+  warning goes quiet by itself when Rails ships the fix. The installer
+  offers the pin in the app's Gemfile, the doctor reports it, and the app
+  logs it once at boot.
+- Both database bases also survive an entry whose adapter gem is not in
+  the bundle yet (a `LoadError` rather than `AdapterNotSpecified`), which
+  is the state a PostgreSQL app is in between the installer adding
+  `gem "sqlite3"` and the `bundle install` that follows.
+- The embedded dashboard authenticates the way Mission Control Jobs
+  does: HTTP Basic is on and closed by default, so with no credentials
+  every dashboard page answers 401 (with a note saying what to run), the
+  live channel refuses the subscription, and the doctor reports it. The
+  beacon endpoint and the dashboard's own static assets stay public, as
+  they must be. `bin/rails
+  railwatch:authentication:configure` writes
+  `railwatch.http_basic_auth_user/_password` to the environment's Rails
+  credentials; `RAILWATCH_HTTP_BASIC_AUTH_USER/_PASSWORD` or the
+  initializer do the same. A host with its own admin auth sets
+  `c.http_basic_auth_enabled = false` and either
+  `c.base_controller_class` (the dashboard controllers inherit from it)
+  or a routes constraint around the mount. Before this a production
+  install served every query and log line to anyone who found the URL.
+- The Puma plugin forks the writer in single mode too (the default for a
+  Rails 8 app). It stops the writer from `at_exit`, after Puma's run loop
+  has returned: Puma's SIGTERM trap fires `after_stopped` BEFORE it drains
+  in-flight requests, so stopping there took the writer away from requests
+  that were still running and lost their records. The live-update
+  broadcast after a batch rescues a `LoadError` as well: a host whose
+  production `cable.yml` names redis without the gem (Rails 8.1's
+  non-Docker template) used to take the writer down on every batch.
+- Puma workers under the plugin actually use the writer. The socket
+  transport captured "is a writer expected" when it was built, and
+  `rails server` builds the reporter (app boot) before Puma evaluates
+  `config/puma.rb` (where the plugin sets the flag), so every worker
+  inherited a transport that expected no writer, missed the socket once
+  during the writer's startup, and wrote its own batches in-process for
+  the rest of its life. The flag is now read at delivery time. On the
+  dogfood host this is the difference between a reporter thread at 3.6 ms
+  of CPU per request in each worker and one at 0.2 ms, with the writer
+  process doing the 2.8 ms.
+- The per-record memory estimate on the request thread
+  (`Record.buffered_bytes`, run once for every query, cache event and log
+  line an execution buffers) walks a record in one loop instead of one
+  method call per value: 6.2 to 2.7 us for a query record, about 120 us
+  off a 20-query request. Same numbers for every record shape, including
+  at the depth bound and on a self-referential one.
+
 ## 0.1.4 (2026-09-15)
 
 - `llm_call` records what the call carried and how it was configured, not

data/README.md

@@ -15,6 +15,14 @@ bin/rails generate railwatch:install --prompt-token  # 2. hidden token input plu
 bin/rails railwatch:doctor                    # 3. check every piece is wired up after restart
 ```
 
+Or keep everything inside your app, with the full dashboard at
+`/railwatch` and no token ([Embedded mode](docs/embedded.md)):
+
+```sh
+bundle add railwatch
+bin/rails generate railwatch:install --local
+```
+
 Getting the token, the generator's flags, and deploying with Kamal,
 Docker, Heroku, or Render are covered in
 [Getting started](docs/getting-started.md). For a self-hosted deployment
@@ -76,6 +84,8 @@ expect { get "/widgets" }.not_to have_railwatch_n_plus_one
   option by option and call site by call site.
 - [Coming from Laravel Nightwatch](docs/replacing-nightwatch.md) — the
   record-type mapping and the sampling model, for Laravel people.
+- [Embedded mode](docs/embedded.md) — the whole dashboard inside your
+  app, telemetry in your own SQLite files, no cloud.
 - [Self-hosting](docs/self-hosting.md) — pointing the gem at your own
   Railwatch Cloud.
 - [Troubleshooting](docs/troubleshooting.md) — every failure mode, paired

data/app/channels/railwatch/environment_channel.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Live dashboard updates: Ingest::Batch broadcasts "ingested" on
+  # environment_<id> after each write (throttled to one per 2 s), and the
+  # page reloads its props. Under HTTP Basic the browser sends the same
+  # Authorization header on the WebSocket handshake, so the channel checks
+  # the same credentials as the pages.
+  #
+  # With Basic off, Configuration#dashboard_channel_allowed? asks whichever
+  # gate the host declared: a dashboard_user resolver can refuse this
+  # request, a named base controller or an explicit dashboard_open is taken
+  # at its word, and an undeclared gate refuses. That last case matters
+  # because Action Cable runs on the host's own /cable endpoint: a routes
+  # constraint around the engine's mount does not cover it and a base
+  # controller cannot reach it, so "something in front of /railwatch" is not
+  # evidence about this. What a subscriber would see is the ingest ping (a
+  # timestamp and per-type counts), never telemetry records.
+  class EnvironmentChannel < ActionCable::Channel::Base
+    def subscribed
+      if params[:id].to_i == Environment::ID && Railwatch.config.dashboard_channel_allowed?(connection.request)
+        stream_from "environment_#{Environment::ID}"
+      else
+        reject
+      end
+    end
+  end
+end

data/app/controllers/concerns/railwatch/telemetry_identity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Builds identity props from the current environment's telemetry database.
+# Callers must already be inside `telemetry { }`; this keeps Person lookups
+# batched and prevents a reference from ever being resolved in another
+# environment's tenant database.
+module Railwatch
+  module TelemetryIdentity
+    private
+
+    def origin_people(rows)
+      refs = rows.filter_map(&:user_ref).uniq
+      refs.empty? ? {} : Telemetry::Person.where(ref: refs).index_by(&:ref)
+    end
+
+    def origin_identity(record, people)
+      person = people[record.user_ref]
+      {
+        user_ref: record.user_ref,
+        tenant: record.app_tenant,
+        person: person && { ref: person.ref, name: person.display_name }
+      }
+    end
+  end
+end

data/app/controllers/railwatch/alerts_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Fired-alert history. Reachable two ways: account-wide at /alerts (every
+# environment) and, nested under an environment, scoped to that
+# environment's issues. AlertRule (and so Alert) belongs to an application
+# rather than an environment, so the env-scoped view filters through the
+# alert's issue instead -- app-level alerts with no issue (e.g. quota) only
+# show up in the account-wide view.
+module Railwatch
+    class AlertsController < DashboardController
+    # One environment in an embedded install, so the account-wide and the
+    # environment-scoped listing are the same page; the base class already
+    # set the environment and shares its props.
+
+    def index
+      scope = account_alerts
+      scope = scope.joins(:issue).where(railwatch_issues: { environment_id: environment.id }) if params[:environment_id]
+      fields = FilterQuery.parse(params[:q]).fetch(:fields)
+      scope = scope.where(event: fields["event"]) if AlertRule::EVENTS.include?(fields["event"].to_s)
+      scope = scope.where(status: fields["status"]) if Alert::STATUSES.include?(fields["status"].to_s)
+      alerts = scope.order(created_at: :desc).limit(200)
+      render inertia: { alerts: alerts.map { |a| row(a) }, q: params[:q].to_s, statuses: Alert::STATUSES }
+    end
+
+    def retry
+      alert = account_alerts.find(params[:id])
+      if alert.retry_delivery!
+        redirect_back fallback_location: alerts_path, notice: "Retrying alert"
+      else
+        redirect_back fallback_location: alerts_path, alert: "Only failed alerts can be retried"
+      end
+    end
+
+    private
+
+    # Scoped through the integration rather than the rule's application: a
+    # "Send test" alert has no rule, and its destination is what owns it.
+    def account_alerts
+      Alert.all
+    end
+
+    def row(a)
+      { id: a.id, event: a.event, status: a.status, sent_at: a.sent_at, error: a.error, payload: a.payload, created_at: a.created_at,
+        integration: { kind: a.integration.kind, name: a.integration.name },
+        issue: a.issue && { id: a.issue.id, key: a.issue.key, title: a.issue.title } }
+    end
+    end
+end

data/app/controllers/railwatch/anomaly_rules_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Railwatch
+    class AnomalyRulesController < DashboardController
+    def create
+      rule = environment.anomaly_rules.new(anomaly_rule_params)
+      if rule.save
+        redirect_to application_environment_thresholds_path(application, environment), notice: "Anomaly rule added"
+      else
+        redirect_to application_environment_thresholds_path(application, environment), inertia: { errors: rule.errors }
+      end
+    end
+
+    def update
+      rule = environment.anomaly_rules.find(params[:id])
+      rule.update(anomaly_rule_params)
+      redirect_to application_environment_thresholds_path(application, environment), notice: "Anomaly rule updated"
+    end
+
+    def destroy
+      environment.anomaly_rules.find(params[:id]).destroy
+      redirect_to application_environment_thresholds_path(application, environment), notice: "Anomaly rule removed"
+    end
+
+    private
+
+    def anomaly_rule_params
+      params.permit(:target_kind, :target, :metric, :deviation, :window_minutes, :baseline_days, :enabled)
+    end
+    end
+end

data/app/controllers/railwatch/attachments_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Serves the bytes an app attached to an execution or exception. The row
+# only exists in its own environment's telemetry database, so an id from
+# another environment 404s here.
+module Railwatch
+    class AttachmentsController < DashboardController
+    def show
+      attachment = telemetry { Telemetry::Attachment.find(params[:id]) }
+      # Rendered as text/plain even for text/html or SVG: these bytes came
+      # from a monitored app and must never execute on our origin.
+      if params[:view] == "1" && attachment.viewable?
+        send_data attachment.body, type: "text/plain; charset=utf-8", disposition: "inline"
+      else
+        send_data attachment.body, type: attachment.content_type.presence || "application/octet-stream",
+          filename: attachment.name, disposition: "attachment"
+      end
+    rescue Telemetry::BoundedGzip::Error
+      head :unprocessable_content
+    end
+    end
+end

data/app/controllers/railwatch/beacon_controller.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module Railwatch
   # Receives Inertia visit timings and JavaScript errors from the browser
   # client (app/frontend/lib/railwatch.ts). Mounted at /railwatch/beacon.
@@ -22,7 +24,7 @@ module Railwatch
 
     RATE_LIMIT_WINDOW = 60 # seconds
 
-    before_action :limit_payload, :throttle, if: -> { Railwatch.config.beacon_enabled }
+    before_action :limit_payload, :verify_origin, :throttle, if: -> { Railwatch.config.beacon_enabled }
 
     def create
       return head :no_content unless Railwatch.config.beacon_enabled
@@ -65,17 +67,75 @@ module Railwatch
     # The beacon takes no credential and keeps every browser error it is
     # sent, so a client that is not the page -- a script, a bored visitor
     # with curl -- could otherwise fill the app's quota with junk issues.
-    # Same shape as Rails' rate_limit (a counter per client IP in the app's
-    # cache store), read from config at request time so an initializer can
-    # raise or disable it. A store that cannot count (NullStore) fails open:
-    # the beacon keeps working, just unthrottled.
+    # Two ceilings, both counters in the app's cache store in the shape of
+    # Rails' own rate_limit: one per client IP, and one for the endpoint as a
+    # whole so a rotating address cannot multiply its way past the first.
+    # Read from config per request, so an initializer can raise or remove
+    # either one.
+    # Same idea as Sentry's allowed domains: a public ingest endpoint cannot
+    # authenticate its caller (the credential would be in the page), so it
+    # refuses anything that says it came from somewhere else. Not a security
+    # boundary -- an Origin header is trivially forged outside a browser --
+    # but it stops another site's page from spending this app's quota.
+    # Missing Origin and Referer pass, which is how Rails' own forgery origin
+    # check behaves.
+    def verify_origin
+      origin = request.origin || referer_origin
+      return if origin.nil? || origin == request.base_url
+      return if Railwatch.config.beacon_allowed_origins.any? { |allowed| origin_matches?(origin, allowed) }
+
+      Railwatch.debug { "refused a beacon from #{origin} (this app is #{request.base_url})" }
+      head :forbidden
+    end
+
+    def referer_origin
+      referer = request.referer.presence or return nil
+      uri = URI.parse(referer)
+      return nil unless uri.scheme && uri.host
+
+      port = ":#{uri.port}" if uri.port && uri.port != uri.default_port
+      "#{uri.scheme}://#{uri.host}#{port}"
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # An entry is either a full origin ("https://app.example.com") or a bare
+    # host, which matches either scheme.
+    def origin_matches?(origin, allowed)
+      return true if origin == allowed
+
+      allowed.include?("://") ? false : [ "https://#{allowed}", "http://#{allowed}" ].include?(origin)
+    end
+
     def throttle
       limit = Railwatch.config.beacon_rate_limit.to_i
+      global = Railwatch.config.beacon_global_rate_limit.to_i
+      return refuse_beacon if global.positive? && over?("railwatch:beacon:all", global)
       return unless limit.positive?
 
-      count = cache_store.increment("railwatch:beacon:#{request.remote_ip}", 1, expires_in: RATE_LIMIT_WINDOW)
-      return unless count && count > limit
+      # A store that cannot count (NullStore, a cache that is down, one whose
+      # increment is unsupported) returns nil. Refuse the beacon then rather
+      # than serving an unauthenticated, unlimited write endpoint: the
+      # browser client retries on the next flush, and an app that genuinely
+      # wants no limit sets beacon_rate_limit to 0.
+      refuse_beacon if over?("railwatch:beacon:#{request.remote_ip}", limit)
+    end
+
+    # True when this key has passed its ceiling for the window, and also when
+    # the store cannot count at all: a store that returns nil (NullStore, a
+    # cache that is down, one without increment) would otherwise leave an
+    # unauthenticated endpoint with no ceiling on it. An app that genuinely
+    # wants no limit sets the limit to 0, or turns the beacon off.
+    def over?(key, limit)
+      count = cache_store.increment(key, 1, expires_in: RATE_LIMIT_WINDOW)
+      if count.nil?
+        Railwatch.debug { "beacon rate limiting is unavailable (#{cache_store.class}); refusing the beacon" }
+        return true
+      end
+      count > limit
+    end
 
+    def refuse_beacon
       response.set_header("Retry-After", RATE_LIMIT_WINDOW.to_s)
       head :too_many_requests
     end

data/app/controllers/railwatch/broadcasts_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Railwatch
+    class BroadcastsController < DashboardController
+    def index
+      from, to = window_range
+      streams = telemetry do
+        Telemetry::Broadcast.between(from, to).group(:group_hash, :kind).pluck(:group_hash, :kind, Arel.sql("MAX(COALESCE(stream, channel))"), Arel.sql("COUNT(*)"), Arel.sql("SUM(bytes)"), Arel.sql("AVG(duration)"))
+          .map { |g, k, name, c, b, d| { group_hash: g, kind: k, name: name, count: c, bytes: b.to_i, avg: (d.to_f / 1000.0).round(3) } }.sort_by { |r| -r[:count] }.first(200)
+      end
+      recent = telemetry { Telemetry::Broadcast.between(from, to).recent.limit(100).map { |b| { id: b.id, kind: b.kind, stream: b.stream, channel: b.channel, action: b.action, bytes: b.bytes, failed: b.failed, duration: b.duration_ms.round(3), occurred_at: b.occurred_at, execution_id: b.execution_id, execution_preview: b.execution_preview } } }
+      render inertia: { streams: streams, recent: recent }
+    end
+    end
+end

data/app/controllers/railwatch/cache_events_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Railwatch
+    class CacheEventsController < DashboardController
+    def index
+      from, to = window_range
+      fields = FilterQuery.parse(params[:q]).fetch(:fields)
+      keys = telemetry do
+        scope = Telemetry::Rollup.for_type("cache_event").between(from, to)
+        if fields["store"].present?
+          # Rollup rows have no store column; find the matching group_hashes
+          # from the raw cache_events for this window and filter by those.
+          hashes = Telemetry::CacheEvent.between(from, to).where(store: fields["store"]).distinct.pluck(:group_hash)
+          scope = scope.where(group_hash: hashes)
+        end
+        rows = scope.to_a
+        rows.group_by(&:group_hash).map do |group_hash, group_rows|
+          count = group_rows.sum(&:count)
+          hits = group_rows.sum { |r| r.extra["hits"].to_i }
+          misses = group_rows.sum { |r| r.extra["misses"].to_i }
+          duration_sum = group_rows.sum(&:duration_sum)
+          { group_hash: group_hash, key: group_rows.max_by(&:bucket).name, count: count, hits: hits, misses: misses,
+           hit_rate: (hits + misses).zero? ? nil : (hits * 100.0 / (hits + misses)).round(1),
+           avg: count.zero? ? 0 : (duration_sum / count / 1000.0).round(3), sparkline: Telemetry::Aggregations.sparkline(group_rows, from, to) }
+        end.sort_by { |r| -r[:count] }.first(200)
+      end
+      render inertia: { keys: keys, series: series("cache_event"), q: params[:q].to_s }
+    end
+    end
+end

data/app/controllers/railwatch/commands_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Railwatch
+    class CommandsController < DashboardController
+    def index
+      rows = telemetry { Telemetry::Execution.commands.between(*window_range).recent.limit(200).to_a }
+      render inertia: { commands: grouped("command", limit: 100),
+                        runs: rows.map { |r| { execution_id: r.execution_id, name: r.name, exit_code: r.status, duration: r.duration_ms.round(1), occurred_at: r.occurred_at, server: r.server, exception_preview: r.exception_preview } } }
+    end
+
+    def show
+      exe = telemetry { Telemetry::Execution.find_by!(execution_id: params[:id]) }
+      render inertia: "executions/show", props: ExecutionPresenter.new(exe, environment).props
+    end
+    end
+end

data/app/controllers/railwatch/comments_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Railwatch
+    class CommentsController < DashboardController
+    def create
+      issue = Issue.all.find(params[:issue_id])
+      issue.comments.create!(user: Viewer.user, body: params.require(:body))
+      redirect_to issue_path(issue), notice: "Comment added"
+    end
+    end
+end

data/app/controllers/railwatch/dashboard_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Base for every dashboard page: the prebuilt Inertia bundle, the shared
+  # props its layouts read, and per-controller Inertia config so a host that
+  # also uses Inertia keeps its own.
+  #
+  # Inherits from Railwatch.config.base_controller_class (default
+  # ActionController::Base) so a host can put its own admin gate in front of
+  # every page the way Mission Control Jobs allows: point it at a controller
+  # whose before_action requires an admin, and turn HTTP Basic off.
+  class DashboardController < Railwatch.config.base_controller_class.constantize
+    include Railwatch::AssetsHelper
+    helper Railwatch::AssetsHelper
+    include Railwatch::EnvironmentScoped
+
+    layout "railwatch/dashboard"
+    # The bundle's pages are named after the platform's controllers
+    # (overview/show, requests/index); strip the engine namespace so
+    # default_render finds them.
+    inertia_config version: -> { Railwatch::AssetsHelper.digest }, layout: "railwatch/dashboard",
+                   use_script_element_for_initial_page: true, always_include_errors_hash: true, default_render: true,
+                   component_path_resolver: ->(path:, action:) { "#{path.delete_prefix('railwatch/')}/#{action}" }
+    rescue_from Telemetry::CursorPage::InvalidCursor do |exception|
+      render plain: exception.message, status: :unprocessable_content
+    end
+
+    # HTTP Basic, on and closed by default (Configuration#http_basic_auth_*).
+    # Runs before anything reads telemetry; a host that authenticates in its
+    # base controller or a routes constraint turns it off.
+    before_action :authenticate_by_http_basic
+    before_action { Viewer.user = Railwatch.config.resolve_dashboard_user(request) }
+
+    inertia_share auth: -> { { user: Viewer.user.as_json, session: { id: "embedded", recently_authenticated: true } } },
+                  account: -> { Railwatch::Embedded::Account.as_json },
+                  accounts: -> { [ { id: 1, name: Railwatch::Embedded::Account.name } ] },
+                  applications: -> { [ { id: 1, name: Application.current.name, slug: Application.current.slug,
+                                       issue_prefix: Application.current.issue_prefix,
+                                       environments: [ { id: 1, name: Environment.current.name, slug: Environment.current.slug,
+                                                       last_seen_at: Environment.current.last_seen_at, paused: false } ] } ] },
+                  flash: -> { { alert: flash.alert, warning: flash[:warning], notice: flash.notice } },
+                  google_oauth: false,
+                  embedded: true
+
+    private
+
+    def authenticate_by_http_basic
+      config = Railwatch.config
+      return unless config.http_basic_auth_enabled
+
+      if config.http_basic_auth_configured?
+        http_basic_authenticate_or_request_with(name: config.http_basic_auth_user, password: config.http_basic_auth_password,
+                                                realm: "Railwatch")
+      else
+        # Closed, not open: same as Mission Control with no credentials. The
+        # challenge header is still sent so a client or a monitor sees the
+        # scheme, and the body says what to do, since a bare 401 looks like a
+        # broken install rather than an unconfigured one.
+        response.set_header("WWW-Authenticate", %(Basic realm="Railwatch"))
+        render plain: "Railwatch: HTTP Basic authentication is on and no credentials are configured, so the " \
+                      "dashboard is closed. Run `bin/rails railwatch:authentication:configure` (writes " \
+                      "railwatch.http_basic_auth_user/_password to Rails credentials), or set " \
+                      "RAILWATCH_HTTP_BASIC_AUTH_USER and _PASSWORD, or turn Basic off " \
+                      "(c.http_basic_auth_enabled = false) once your own auth gates the mount. See docs/embedded.md.",
+               status: :unauthorized
+      end
+    end
+  end
+end