railwatch 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d212beaade3dc390933ea8a41bd49eb1bbf2c896056071516aac8242b39eb07
-  data.tar.gz: e647976f9634c1e0ba390f6dec52866d190401728363e3dcd1fa93aa2976af3d
+  metadata.gz: 7670085bcbae37c58def37c8e23ffee964be9277a57462869346017016c33a3c
+  data.tar.gz: fb68d72c0863778eb607cfd2bded53714651caaecffefbff20994e25422a1411
 SHA512:
-  metadata.gz: c669c17f558dec72be16f175b06abc5769680591349c2169f6598fc26575191558bd00b903ead0f1f4287bab718c5097b0550ff60e7cfe5fe82fa53940c7a953
-  data.tar.gz: fc9a32a877b22e12e22b7738b4b479c2aa8b9d1dcc5c97f7ed003f5b421ea3e1a95f917221c195c9b01a487ac124d413dc561a22f96e7483e4891bb5db95b685
+  metadata.gz: 429bb5789a56059dce9848403622511df0f5094c2efe4a6ed8c51e5086fb11eaf56b8c762ee9ae68d1ae393a5fae7af65d628df019f01b00466644e207aa6b1d
+  data.tar.gz: 0c38280c362f3529ca2af1e93a6982d77ed15a872351072727dd1152396ea2c3f1a2e634f1132a6cac83bf0ee152f818fda15db76e2251a3f0f1a7a24db5bfb1

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.3.6 (2026-09-20)
+
+- Harden embedded live-stream authorization and telemetry delivery. Bound
+  source-file access and HTTP response reads.
+- Simplify prelaunch interfaces: use prompt, stdin, or environment token input;
+  pass the complete transport delivery metadata; use the current process-version
+  field. Update public install examples and remove obsolete upgrade wording.
+
+## 0.3.5 (2026-09-20)
+
+- Make the embedded telemetry database give disk back. `PruneTelemetryJob`
+  deleted rows past `retention_days` and nothing ever vacuumed, so the freed
+  pages went on SQLite's freelist to be reused and never returned to the
+  filesystem: the file only ever grew. Measured on a copy of a real production
+  database of the same shape (bulk deletes, continuous inserts), deleting
+  40,148 rows left the file at 21M with 5,164 pages on the freelist; a single
+  `PRAGMA incremental_vacuum` took it to 44K.
+
+  Two halves, and neither is worth anything alone. A new telemetry migration,
+  `EnableIncrementalVacuum`, puts the database into `auto_vacuum=incremental`;
+  and the nightly prune now runs `PRAGMA incremental_vacuum` after its deletes,
+  bounded to 2,000 pages a slice and 25 slices (~200MB at SQLite's 4K default)
+  so a backlog drains over successive nights instead of stalling one.
+
+  The mode cannot be declared in `config/database.yml`: Rails applies its own
+  `DEFAULT_PRAGMAS` before any you declare, and `journal_mode = wal` writes the
+  file header, so by the time `auto_vacuum` runs the database is no longer new
+  and SQLite accepts the statement and ignores it. The migration is numbered
+  below `CreateTelemetry` for the same reason -- it has to run while the file
+  still holds nothing.
+
+- Add `bin/rails railwatch:vacuum:status` and `bin/rails railwatch:vacuum`.
+  An **existing** install cannot change mode without a full `VACUUM`, which
+  rewrites the whole file with the write lock held, so nothing does that on its
+  own: the migration leaves an existing database exactly as it found it.
+  `railwatch:vacuum:status` reports the file, its size, its mode and its
+  freelist and changes nothing; `railwatch:vacuum` says what the conversion
+  will cost and then does it. Installs created from this version on need
+  neither.
+
 ## 0.3.4 (2026-09-20)
 
 - Fix the embedded dashboard offering its install steps to an install that is
@@ -644,8 +684,7 @@ First public release.
 - The installer now prefers a hidden prompt, stdin, or `RAILWATCH_TOKEN`, never
   prints token values, and refuses to put a token in a tracked or non-ignored
   `.env`. `railwatch:doctor` also fails when it finds a plaintext `lt_...` token
-  in likely secret-bearing files tracked by Git. The legacy `--token=` option
-  remains compatible but warns about shell-history and process-list exposure.
+  in likely secret-bearing files tracked by Git.
 
 - A forked worker profiles again. `Process._fork` now resets the profiler's
   process-global state in the child: it used to inherit `@running` holding

data/app/channels/railwatch/environment_channel.rb

@@ -2,15 +2,15 @@
 
 module Railwatch
   # Live dashboard updates: Ingest::Batch broadcasts "ingested" on
-  # environment_<id> after each write (throttled to one per 2 s), and the
+  # railwatch: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
+  # request, or dashboard_open explicitly allows public live updates.
+  # A named base controller alone cannot authorize a channel. 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
@@ -19,7 +19,9 @@ module Railwatch
   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}"
+        stream_from "railwatch:environment:#{Environment::ID}", coder: ActiveSupport::JSON do |message|
+          transmit_authorized(message)
+        end
       else
         reject
       end
@@ -27,6 +29,17 @@ module Railwatch
 
     private
 
+    # A host's resolver can revoke an operator while their socket is open.
+    def transmit_authorized(message)
+      if Railwatch.config.dashboard_channel_allowed?(connection_request)
+        transmit message
+      else
+        stop_all_streams
+        reject
+        reject_subscription
+      end
+    end
+
     # Built from the connection's env rather than asking it for its request:
     # ActionCable::Connection::Base#request is private (Rails documents it for
     # use inside a Connection subclass, not from a channel), so the obvious

data/app/jobs/railwatch/prune_telemetry_job.rb

@@ -20,6 +20,21 @@ module Railwatch
     # writer that long hold would look like a wedge and end the process.
     MAX_BATCHES_PER_TABLE = 40
 
+    # Reclaim, bounded the same way the deletes are. Deleting rows only moves
+    # their pages to the freelist; PRAGMA incremental_vacuum is what hands
+    # them back to the filesystem, and it is only possible at all on a
+    # database in auto_vacuum=incremental (EnableIncrementalVacuum, or
+    # `bin/rails railwatch:vacuum` for a database that predates it).
+    # Measured at 80k-190k pages/s warm, so a full run is well under a second
+    # there; the slicing is for the cold, large file, where each slice takes
+    # and releases the write lock instead of holding it throughout.
+    VACUUM_PAGES_PER_SLICE = 2_000
+    # 50k pages, ~200MB at SQLite's 4KB default. A few thousand pages a night
+    # would never keep up with a night's deletes on a busy app, and the file
+    # would go on growing with the freelist; a backlog past this one still
+    # drains over successive nightly runs.
+    VACUUM_SLICES = 25
+
     RAW = [ Telemetry::Execution, Telemetry::Query, Telemetry::Exception, Telemetry::CacheEvent, Telemetry::Mail,
             Telemetry::Broadcast, Telemetry::Notification, Telemetry::OutgoingRequest, Telemetry::StorageOp,
             Telemetry::ViewRender, Telemetry::Log, Telemetry::EnqueuedJob, Telemetry::Transaction,
@@ -50,7 +65,11 @@ module Railwatch
         Telemetry::IngestBatch.where(received_at: ...cutoff).delete_all
         Telemetry::Process.where(booted_at: ...cutoff).delete_all
         Telemetry::HealthSample.where(sampled_at: ...cutoff).delete_all
-        TelemetryRecord.connection.execute("PRAGMA wal_checkpoint(#{checkpoint})") if TelemetryRecord.connection.adapter_name =~ /sqlite/i
+        # Before the checkpoint, not after: incremental_vacuum truncates the
+        # database file, and in WAL mode that truncation only reaches the file
+        # on disk once it is checkpointed.
+        TelemetryRecord.reclaim_freelist!(slice: VACUUM_PAGES_PER_SLICE, slices: VACUUM_SLICES)
+        TelemetryRecord.connection.execute("PRAGMA wal_checkpoint(#{checkpoint})") if TelemetryRecord.sqlite?
       end
     end
 

data/app/models/railwatch/ingest/batch.rb

@@ -340,7 +340,7 @@ module Railwatch
         return if last && now - last < THROTTLE_WINDOW
 
         LAST_BROADCAST_AT[@environment.id] = now
-        ActionCable.server.broadcast("environment_#{@environment.id}", { event: "ingested", at: now.iso8601, counts: @counts })
+        ActionCable.server.broadcast("railwatch:environment:#{@environment.id}", { event: "ingested", at: now.iso8601, counts: @counts })
       rescue StandardError, LoadError => e
         # A live refresh ping is not worth failing a written batch over.
         # LoadError too: a host whose production cable adapter is redis with

data/app/models/railwatch/ingest/mapper.rb

@@ -417,9 +417,7 @@ module Railwatch
         [ Telemetry::Process, {
           booted_at: timestamp_string(rec["timestamp"]), pid: rec["pid"], role: rec["role"], server: rec["server"],
           deploy: rec["deploy"], ruby_version: rec["ruby_version"], rails_version: rec["rails_version"],
-          # Gems older than 0.1.3 send lantern_version; processes recorded
-          # by one are still readable.
-          railwatch_version: rec["railwatch_version"] || rec["lantern_version"], boot_seconds: rec["boot_seconds"],
+          railwatch_version: rec["railwatch_version"], boot_seconds: rec["boot_seconds"],
           detail: rec.slice("app", "environment", "database_adapter", "queue_adapter", "cache_store")
         } ]
       end

data/app/models/railwatch/telemetry_record.rb

@@ -31,6 +31,54 @@ module Railwatch
       end
     end
 
+    # SQLite's auto_vacuum modes. Deleted pages only leave the file in
+    # :incremental, and only when PRAGMA incremental_vacuum asks for them;
+    # :none (the default, and what every database created before
+    # EnableIncrementalVacuum is in) keeps them on the freelist forever.
+    AUTO_VACUUM_MODES = { 0 => :none, 1 => :full, 2 => :incremental }.freeze
+
+    # Everything below reads and writes THIS database, never the host's. The
+    # pragmas are per-database and there is no Active Record wrapper for them,
+    # so they go through this class's own connection on purpose: through
+    # ActiveRecord::Base they would report on, and vacuum, the application's
+    # primary database instead.
+    def self.sqlite? = connection.adapter_name.match?(/sqlite/i)
+
+    def self.auto_vacuum_mode = sqlite? ? AUTO_VACUUM_MODES.fetch(connection.select_value("PRAGMA auto_vacuum").to_i, :unknown) : nil
+
+    def self.freelist_pages = sqlite? ? connection.select_value("PRAGMA freelist_count").to_i : 0
+
+    def self.page_size = sqlite? ? connection.select_value("PRAGMA page_size").to_i : 0
+
+    # Hands freelist pages back to the filesystem, a slice at a time. Each
+    # PRAGMA is its own implicit transaction, so the write lock is taken and
+    # released once per slice rather than held for the whole reclaim -- the
+    # same reason PruneTelemetryJob deletes in bounded batches instead of one
+    # statement. Returns the pages actually reclaimed, which is 0 on a
+    # database that is not in incremental mode: there the pragma is accepted
+    # and does nothing, and calling it would look like work that happened.
+    def self.reclaim_freelist!(slice:, slices:)
+      return 0 unless sqlite? && auto_vacuum_mode == :incremental
+
+      before = freelist_pages
+      slices.times do
+        break if freelist_pages.zero?
+
+        incremental_vacuum(slice.to_i)
+      end
+      before - freelist_pages
+    end
+
+    # Through the raw connection on purpose. incremental_vacuum frees one page
+    # per sqlite3_step, and Active Record's execute steps a statement with no
+    # result columns exactly once -- so through it this pragma frees a single
+    # page whatever count it is handed, which is the kind of no-op that reads
+    # as work done. The sqlite3 gem's own execute steps to completion. Same
+    # raw_connection route Ingest::Writer already takes for its inserts.
+    def self.incremental_vacuum(pages = nil)
+      connection.raw_connection.execute("PRAGMA incremental_vacuum#{"(#{pages})" if pages}")
+    end
+
     # Records arrive as the gem's wire hashes; this is the shared envelope.
     def self.envelope_columns(t)
       t.datetime :occurred_at, null: false, precision: 6

data/db/railwatch_telemetry_migrate/20260903000000_enable_incremental_vacuum.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Puts the telemetry database into incremental auto-vacuum mode, which is what
+# lets PruneTelemetryJob hand the pages it frees back to the filesystem
+# instead of parking them on the freelist forever. Without it the file only
+# ever grows: deleting a day of telemetry frees pages for SQLite to reuse and
+# returns not one byte to the disk.
+#
+# Why a migration, and why this version number. SQLite only lets a database
+# leave auto_vacuum=none for free while it still holds no pages; after that
+# the only way in is a full VACUUM, which rewrites the entire file with the
+# write lock held. Declaring the pragma in config/database.yml cannot do it
+# either: Rails applies its own DEFAULT_PRAGMAS before any declared ones, and
+# `journal_mode = wal` writes the file header, so by the time
+# `auto_vacuum = incremental` runs the database is no longer new and the
+# statement is a silent no-op (measured: the mode comes out `none`).
+#
+# A migration is the one hook that runs both on a new install's db:prepare and
+# on an existing install's upgrade, and this one is numbered below
+# CreateTelemetry so that on a new database it runs while the file holds
+# nothing but schema_migrations and ar_internal_metadata -- a few kilobytes,
+# where the VACUUM that commits the mode is instant. Rails runs a pending
+# migration whatever its version, so an existing install gets it too; there it
+# does nothing at all, because converting a file that may be tens of gigabytes
+# is not a decision a deploy gets to make. That one is `bin/rails
+# railwatch:vacuum`, run deliberately, which says what it will cost first.
+class EnableIncrementalVacuum < ActiveRecord::Migration[8.1]
+  # VACUUM cannot run inside a transaction.
+  disable_ddl_transaction!
+
+  # Rails' own bookkeeping, which is present before the first migration runs
+  # and so does not make a database "existing".
+  BOOKKEEPING = %w[schema_migrations ar_internal_metadata].freeze
+
+  def up
+    return say("not SQLite (#{connection.adapter_name}); auto_vacuum does not apply") unless sqlite?
+    return say("auto_vacuum is already incremental") if mode == "incremental"
+
+    populated = connection.tables - BOOKKEEPING
+    if populated.any?
+      return say("#{populated.size} tables already here: left in auto_vacuum=#{mode}. Run " \
+                 "`bin/rails railwatch:vacuum` to convert this database when you can spare the lock.")
+    end
+
+    connection.execute("PRAGMA auto_vacuum = incremental")
+    connection.execute("VACUUM")
+    say("auto_vacuum = #{mode}")
+  end
+
+  # Irreversible in the useful sense: going back to `none` is another whole
+  # VACUUM, and nothing about the schema depends on the mode. Rolling back
+  # leaves it where it is rather than spending that on an undo nobody asked
+  # for.
+  def down
+    say("auto_vacuum left as #{sqlite? ? mode : connection.adapter_name}; use `PRAGMA auto_vacuum = none; VACUUM;` to undo it by hand")
+  end
+
+  private
+    def sqlite? = connection.adapter_name.match?(/sqlite/i)
+
+    def mode = { 0 => "none", 1 => "full", 2 => "incremental" }[connection.select_value("PRAGMA auto_vacuum").to_i]
+end

data/docs/embedded.md

@@ -165,7 +165,11 @@ c.base_controller_class = "AdminController"   # requires an admin, or redirects
 ```
 
 Your controller's code runs inside the engine, whose route helpers take
-precedence; reach your app's with `main_app.root_path`.
+precedence; reach your app's with `main_app.root_path`. The controller does
+not run for Action Cable subscriptions: live updates stay closed unless
+`dashboard_user` also authorizes the connection (as below). Return `nil` or
+`false` for unauthorized users. The resolver names the operator on pages;
+keep the controller or mount constraint as the page authorization gate.
 
 Or a routes constraint, which keeps the engine out of it entirely (for
 example with the sessions Rails' authentication generator creates):
@@ -183,7 +187,11 @@ purpose:
 
 ```ruby
 c.http_basic_auth_enabled = false
-c.dashboard_open = true   # "something in front of the mount gates this"
+# The mount constraint does not cover /cable. Authorize live updates too:
+c.dashboard_user = ->(request) {
+  user = Session.find_by(id: request.cookie_jar.signed[:session_id])&.user
+  { id: user.id, name: user.name } if user&.admin?
+}
 ```
 
 ### Deliberately public
@@ -201,7 +209,8 @@ With Basic off and none of `base_controller_class`, `dashboard_user` or
 forgotten one. It serves the dashboard (a routes constraint it cannot see
 is a legitimate answer) but logs a warning at every boot outside
 development, `railwatch:doctor` reports the gate as undeclared, and live
-updates are refused. Declaring any of the three settles it.
+updates are refused. A custom base controller declares the page gate only;
+live updates still require their own authorization as described below.
 
 ### Live updates and `/cable`
 
@@ -209,9 +218,11 @@ Action Cable runs on your application's own `/cable` endpoint, not under
 the engine's mount, so a routes constraint around `/railwatch` does not
 cover it and a base controller cannot reach it. The live-update channel
 therefore follows what you declared: HTTP Basic credentials are checked
-on the WebSocket handshake, a `dashboard_user` resolver is consulted,
-`dashboard_open` and `base_controller_class` are taken at their word, and
-an undeclared gate is refused. The channel carries an ingest ping (a
+from the WebSocket handshake, a `dashboard_user` resolver is consulted,
+or `dashboard_open` explicitly permits public live updates. A custom
+`base_controller_class` authorizes pages only and never permits a Cable
+subscription by itself. The gate is rechecked before each live update;
+revocation removes the subscription and notifies the client. The channel carries an ingest ping (a
 timestamp and per-type counts) and never telemetry records.
 
 ### Naming the operator, and what an id may be
@@ -322,7 +333,7 @@ The work that keeps the dashboard current happens in two places:
 | anomaly scan | every 5 minutes | Anomaly rules, when any are enabled |
 | scheduled tasks | every 10 minutes | Missed and late scheduled tasks |
 | auto-resolve | daily | Resolves issues quiet for 14 days |
-| prune | daily | Deletes telemetry older than `retention_days`, then `ANALYZE` |
+| prune | daily | Deletes telemetry older than `retention_days`, returns the freed pages to the filesystem when incremental auto-vacuum is on (see below), then `ANALYZE` |
 
 Because the clock lives in the web process, it keeps running when the
 job worker is down, which is exactly when "scheduled task X missed its
@@ -375,6 +386,52 @@ telemetry database grows with traffic and sampling and is pruned to
 SQLite files in `storage/`, so Litestream or a volume snapshot covers
 them.
 
+### Giving the disk back
+
+Deleting rows does not shrink a SQLite file on its own. The pages go on
+the database's freelist, where later inserts reuse them, and the file
+stays whatever size it reached. So pruning alone keeps the *contents*
+bounded and lets the *file* grow forever.
+
+Railwatch creates its telemetry database in SQLite's
+`auto_vacuum=incremental` mode, and the nightly prune runs `PRAGMA
+incremental_vacuum` after its deletes, which hands those pages back to
+the filesystem. It is bounded -- 2,000 pages a slice, 25 slices, about
+200MB a night at SQLite's 4K default page size -- so a large backlog
+drains over successive nights rather than holding the write lock through
+one enormous reclaim. Nothing to configure.
+
+```
+$ bin/rails railwatch:vacuum:status
+Railwatch telemetry database
+  file    /rails/storage/production_railwatch_telemetry.sqlite3
+  size    1.42 GB
+  mode    auto_vacuum=incremental
+  free    312 pages (1.22 MB) on the freelist
+
+The nightly prune returns up to 195 MB a night on its own.
+`bin/rails railwatch:vacuum` returns all 1.22 MB now.
+```
+
+**Installs created before 0.3.5 report `auto_vacuum=none`, and pruning
+cannot return their space.** SQLite can only set the mode on a database
+that is still empty; on one that has data the only route is a full
+`VACUUM`, which rewrites the entire file with the write lock held.
+Railwatch will not do that to a running application behind your back, so
+upgrading leaves the mode alone and the conversion is a task you run
+when you can spare the lock:
+
+```
+$ bin/rails railwatch:vacuum
+```
+
+It prints the file, its size and its freelist first, then says how long
+the `VACUUM` should take and that it needs about the file's own size in
+free disk for the temporary copy. Telemetry written while it runs waits
+for it and the dashboard is frozen for the duration, so pick a quiet
+moment. Once converted, the nightly prune keeps up on its own and you
+never need to run it again.
+
 ## Switching to the cloud later
 
 Set a token and drop `c.transport = :local` (or set

data/docs/getting-started.md

@@ -36,8 +36,6 @@ bin/rails generate railwatch:install \
 
 - `--prompt-token` reads without echo. `--token-stdin` is available for a
   secret-manager pipe; an already exported `RAILWATCH_TOKEN` is also detected.
-  The legacy `--token=` flag warns because command arguments can be visible in
-  shell history and process listings.
 - A token is written to `.env` only when Git confirms that `.env` is ignored.
   A tracked or non-ignored dotenv file is refused; use Rails credentials, a
   deployment secret manager, or add `.env` to `.gitignore` first. Token values

data/docs/source-maps.md

@@ -48,9 +48,7 @@ New default browser issue fingerprints use the resolved original location
 when a map is already available. Custom fingerprints are preserved. Late
 uploads improve existing stack displays, Copy for AI, API issue details and
 MCP `get_issue`, while existing occurrences keep their original grouping.
-Missing maps or columns fall back to the raw stack. Upgrade the gem for
-new browser occurrences to include columns; older gem versions discarded
-them and cannot resolve minified locations accurately.
+Missing maps or columns fall back to the raw stack.
 
 For a custom release uploader, POST the raw `.map` bytes to
 `/ingest/sourcemaps` with `Content-Type: application/octet-stream`,

data/lib/generators/railwatch/install/install_generator.rb

@@ -13,8 +13,6 @@ module Railwatch
 
       class_option :local, type: :boolean, default: false,
                            desc: "Keep telemetry in this app and serve the dashboard at /railwatch: no token, no cloud."
-      class_option :token, type: :string,
-                           desc: "Deprecated: token in process arguments. Prefer --prompt-token, --token-stdin, or RAILWATCH_TOKEN."
       class_option :prompt_token, type: :boolean, default: false,
                                   desc: "Prompt for the ingest token without echoing it."
       class_option :token_stdin, type: :boolean, default: false,
@@ -167,10 +165,6 @@ module Railwatch
         return if options[:local]
 
         token = resolved_token
-        if options[:token]
-          say("--token exposes #{Railwatch::SecretSafety.token_preview(options[:token])} in process arguments; " \
-              "use --prompt-token or --token-stdin next time.", :yellow)
-        end
         vars = { TOKEN_VAR => token, URL_VAR => options[:url] }.compact
         return if vars.empty?
         return say(env_instructions(vars), :yellow) unless dotenv_app?
@@ -463,8 +457,6 @@ module Railwatch
             ask("Railwatch ingest token (input hidden):", echo: false)
           elsif options[:token_stdin]
             $stdin.gets
-          elsif options[:token]
-            options[:token]
           elsif !ENV[TOKEN_VAR].to_s.empty?
             ENV[TOKEN_VAR]
           end

data/lib/railwatch/backtrace.rb

@@ -145,9 +145,19 @@ module Railwatch
       url.start_with?("#{origin}/")
     end
 
+    MAX_SOURCE_BYTES = 1024 * 1024
+
     def source_snippet(path, line, context: 5)
-      return nil unless path && File.readable?(path)
-      lines = File.readlines(path, chomp: true)
+      return nil unless path
+      # String backtraces can be assigned by libraries. A lexical Rails.root
+      # prefix alone allows ../ and symlinks to disclose files outside it.
+      root = File.realpath(app_root) + File::SEPARATOR
+      source = File.realpath(path)
+      return nil unless source.start_with?(root) && File.file?(source)
+
+      data = File.binread(source, MAX_SOURCE_BYTES + 1)
+      return nil if data.bytesize > MAX_SOURCE_BYTES
+      lines = data.force_encoding(Encoding::UTF_8).scrub.lines(chomp: true)
       from = [ line - context - 1, 0 ].max
       to = [ line + context - 1, lines.size - 1 ].min
       (from..to).to_h { |i| [ i + 1, lines[i].to_s[0, 200] ] }

data/lib/railwatch/configuration.rb

@@ -407,12 +407,13 @@ module Railwatch
     # engine's mount does not cover and a base controller cannot reach, so an
     # undeclared gate refuses rather than assuming.
     def dashboard_channel_allowed?(request)
-      case dashboard_gate
-      when :basic then http_basic_auth_ok?(request)
-      when :resolver then !(dashboard_user.respond_to?(:call) ? dashboard_user.call(request) : dashboard_user).nil?
-      when :open, :controller then true
-      else false
+      return http_basic_auth_ok?(request) if http_basic_auth_enabled
+      if dashboard_user
+        return !!(dashboard_user.respond_to?(:call) ? dashboard_user.call(request) : dashboard_user)
       end
+
+      # A controller name is not evidence of authorization on /cable.
+      !!dashboard_open
     end
 
     def resolve_dashboard_user(request)

data/lib/railwatch/engine.rb

@@ -105,8 +105,8 @@ module Railwatch
           Rails.logger.warn(
             "[railwatch] the dashboard at the engine's mount has no gate this gem can see: HTTP Basic is off and " \
             "no base_controller_class, dashboard_user or dashboard_open is set. If a routes constraint or your " \
-            "network already gates it, set `c.dashboard_open = true` to say so (it also enables live updates); " \
-            "otherwise anyone who can reach the URL can read every query, log line and exception this app records."
+            "network already gates it, authorize /cable separately with `c.dashboard_user`, or set `c.dashboard_open = true` " \
+            "only when the network protects both endpoints. Otherwise anyone who can reach the dashboard can read every query, log line and exception this app records."
           )
         end
       end

data/lib/railwatch/export/client.rb

@@ -22,7 +22,14 @@ module Railwatch
       # Not `send`: shadowing Object#send on a class makes it impossible to
       # reach the real one, and reads as a coincidence rather than a verb.
       def deliver(claim, producer_id:)
-        result = transport_for(claim).deliver_encoded(
+        # Snapshot once, then verify and use those exact bytes. Configuration
+        # can change after Outbox#claim! checked the destination binding.
+        token = @config.resolved_export_token.to_s.dup.freeze
+        unless Digest::SHA256.hexdigest(token) == claim.token_digest
+          return Outcome.new(disposition: :deferred, status: 401, reason: "export credential changed after claim")
+        end
+
+        result = transport_for(claim, token: token).deliver_encoded(
           body: claim.body, expected_count: claim.record_count, batch_id: claim.delivery_id,
           dropped: claim.metadata.fetch("dropped", 0).to_i,
           dropped_bytes: claim.metadata.fetch("dropped_bytes", 0).to_i,
@@ -54,11 +61,11 @@ module Railwatch
       # otherwise post bytes admitted for one receiver to another one -- and,
       # if they belong to different tenants, hand a customer's telemetry to
       # somebody else while marking it delivered.
-      def transport_for(claim)
+      def transport_for(claim, token:)
         key = [ claim.url, claim.token_digest ]
         @transports[key] ||= begin
           credentialed = @config.dup
-          credentialed.token = @config.resolved_export_token
+          credentialed.token = token
           Transport::Http.new(credentialed, endpoint: claim.url)
         end
       end

data/lib/railwatch/reporter.rb

@@ -481,19 +481,9 @@ module Railwatch
                         dropped_bytes: batch.dropped_bytes + dropped_bytes, prepared: true)
     end
 
-    # Third-party/test transports written before batch idempotency only accept
-    # `dropped:`. Keep those working while the HTTP transport receives the
-    # stable identity required to replay a request safely.
     def deliver(batch)
-      parameters = @transport.method(:deliver).parameters
-      accepts_batch_id = parameters.any? { |kind, name| kind == :keyrest || name == :batch_id }
-      accepts_dropped_bytes = parameters.any? { |kind, name| kind == :keyrest || name == :dropped_bytes }
-      accepts_backpressure = parameters.any? { |kind, name| kind == :keyrest || name == :backpressure_factor }
-      keywords = { dropped: batch.dropped }
-      keywords[:batch_id] = batch.id if accepts_batch_id
-      keywords[:dropped_bytes] = batch.dropped_bytes if accepts_dropped_bytes
-      keywords[:backpressure_factor] = @backpressure_factor if accepts_backpressure
-      @transport.deliver(batch.records, **keywords)
+      @transport.deliver(batch.records, dropped: batch.dropped, batch_id: batch.id,
+                         dropped_bytes: batch.dropped_bytes, backpressure_factor: @backpressure_factor)
     end
 
     def update_backpressure

data/lib/railwatch/source_maps.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "uri"
 require "pathname"
 require "json"
@@ -10,6 +11,7 @@ module Railwatch
   # during release preparation; it never follows map URLs or HTTP redirects.
   class SourceMaps
     MAX_BYTES = 10 * 1024 * 1024
+    MAX_RESPONSE_BYTES = 64 * 1024
 
     def initialize(config)
       @config = config
@@ -46,7 +48,17 @@ module Railwatch
       request["X-Railwatch-Deploy"] = @config.deploy
       request["X-Railwatch-Filename"] = filename
       request.body = data
-      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 30, write_timeout: 30) { |http| http.request(request) }
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", verify_mode: OpenSSL::SSL::VERIFY_PEER,
+                                 open_timeout: 5, read_timeout: 30, write_timeout: 30) do |http|
+        http.request(request) do |result|
+          body = String.new(encoding: Encoding::BINARY)
+          result.read_body do |chunk|
+            raise "Source map response exceeds 64 KiB" if body.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+            body << chunk
+          end
+          result.body = body
+        end
+      end
       unless response.is_a?(Net::HTTPSuccess)
         raise "Source map upload failed (HTTP #{response.code}) for #{filename}"
       end

data/lib/railwatch/spec_helper.rb

@@ -15,7 +15,7 @@ module Railwatch
     class MemoryTransport
       attr_reader :batches
       def initialize = @batches = []
-      def deliver(records, dropped: 0, batch_id: nil)
+      def deliver(records, dropped: 0, batch_id: nil, **)
         @batches << records
         Transport::Http::Result.new(ok: true, status: 200, accepted: records.size, rejected: 0)
       end

data/lib/railwatch/transport/http.rb

@@ -174,12 +174,22 @@ module Railwatch
         # explicitly so a Ruby default change cannot silently weaken ingest.
         options[:verify_mode] = OpenSSL::SSL::VERIFY_PEER if options[:use_ssl]
         Net::HTTP.start(@uri.host, @uri.port, **options) do |http|
-          http.request(req)
+          http.request(req) do |response|
+            body = String.new(encoding: Encoding::BINARY)
+            response.read_body do |chunk|
+              if body.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+                raise ResponseTooLarge, "ingest response is larger than #{MAX_RESPONSE_BYTES} bytes"
+              end
+              body << chunk
+            end
+            response.body = body
+          end
         end
       end
 
-      # A receiver in trouble can answer with something enormous -- a proxy
-      # error page, a stack trace. Only ever look at the first slice of it.
+      # Enforced while streaming, before Net::HTTP can buffer an unbounded
+      # proxy error page or decompressed response inside the monitored app.
+      class ResponseTooLarge < StandardError; end
       MAX_RESPONSE_BYTES = 64 * 1024
       # The longest delay we will take from a receiver, in either spelling.
       MAX_RETRY_AFTER = 86_400
@@ -193,8 +203,7 @@ module Railwatch
         end
       end
 
-      # Bounds what we keep and log, not what Net::HTTP already read off the
-      # socket -- it buffers the whole response before we ever see it.
+      # Keep diagnostics smaller still than the bounded response body.
       def summarize(body) = body.to_s.byteslice(0, 200).to_s.scrub
 
       # Seconds, or an HTTP date. Anything else is not a delay we can trust,