railwatch 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8904a8f775771bd894a52f80b7d5ecf4d8a40d0dee09aaf16697e68685c5e106
-  data.tar.gz: de27dad2204510d9e8f3d1bb3ada89901ccd467486c94fde9f0b85ff83ab50ca
+  metadata.gz: 56eb44eab9d0988d36c517995ad2ec8d42971ed9af60e3cf4c419c5df926007f
+  data.tar.gz: 20f9bfed5d8044797a1e43b523668846b2b888756ff9fef59a1f54dc136d64c1
 SHA512:
-  metadata.gz: 5fe5b808c60a3aac92302f8669b82c539634cb655d7317e98279143c5e920f9178d15920a1e75145c9c153ad5d3bfc41ade5004c1df9f1e7c8de29ab2fc20b76
-  data.tar.gz: 251237b9c8ee2a3d252c61eef492d89a532e3c7fef856bde91e19d4d3baa5c831ebc34a0bbbd24b2ced390f76f0ef8106c43cee2d68d6fbf25725f01b074298f
+  metadata.gz: 8bbd22e4636c6c3ba58dfff0242d3553db415af9b90041b524634ae7b95e65a0ff52f6584c7d6c4c61aee12274e177b308d06040508db41ee8db0af81ff1ab0d
+  data.tar.gz: 398eea6fd06b824600b834f5da026f68b70fba6a5bcc1ec97c73995933ca9a8e569cca0d5135f27ee413563281bd91a941eb19ccb954f0b731cd25b2446ba86c

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.3.7 (2026-09-20)
+
+- Stop a rake task or `rails runner` waiting on the network as it finishes.
+  The command patches called `Railwatch.flush` when the execution closed --
+  on the application's own thread, with no time limit. The engine's `at_exit`
+  already calls `Reporter#shutdown`, which wakes the reporter thread and joins
+  it for `shutdown_timeout`, so the same records were already being delivered,
+  already bounded, and a failed task's exception already went with them. The
+  flush was a second, unbounded way to do it.
+
+  Against a receiver that accepts connections and never answers, that second
+  way cost a full timeout ladder per process -- measured at ~6s, and ~12s when
+  it queued behind a delivery the reporter thread was already stuck in. An app
+  whose container entrypoint boots Rails eleven times before starting Puma
+  spent that on every boot and lost the deploy to its proxy's timeout. With
+  the call removed the task returns immediately and the process still leaves
+  within `shutdown_timeout`, carrying the same records.
+
+  Only short-lived processes were affected: web and worker processes flush on
+  the reporter's own thread and never blocked. `Railwatch.flush` is unchanged
+  and still public, for a caller who wants to wait on purpose.
+
+- Add a process-level regression that runs a failing rake task against a
+  socket that accepts and never answers, and asserts the task returns without
+  waiting on it and the process exits inside the shutdown bound. In-process
+  examples cannot see this: the cost lives in a socket read and the bound in
+  an `at_exit` join.
+
+## 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`
@@ -676,8 +712,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/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/docs/configuration.md

@@ -431,9 +431,14 @@ affects one probabilistic decision. Set `backpressure` false to keep the
 factor at 1. The current value is sent as
 `X-Railwatch-Backpressure-Factor` whenever it is greater than 1.
 
-`Railwatch.flush` forces an immediate flush. The `command` patches also
-call it after a rake task/runner invocation finishes, so short-lived
-processes don't lose their last batch to the flush interval. An unhandled
+`Railwatch.flush` forces an immediate flush, on the calling thread and
+without a time limit, so it is yours to call when you know you want to
+wait. Nothing in the gem calls it for you: a short-lived process keeps its
+last batch because the engine's `at_exit` runs `Reporter#shutdown`, which
+wakes the reporter thread and joins it for `shutdown_timeout`. That is a
+bounded wait, which is what a rake task, a runner or a cron job needs --
+a receiver that accepts connections and never answers then costs
+`shutdown_timeout`, not a timeout ladder per process. An unhandled
 exception goes through `Railwatch.record_now` → `Reporter#write_now`,
 which enqueues the record and asks for an urgent flush. It never performs
 network I/O or a timeout cycle on the application thread. Urgent means

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

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/patches/rake_task.rb

@@ -72,7 +72,16 @@ module Railwatch
             name: name,
             command: "rake #{name}#{command_suffix}",
             exit_code: exit_code.to_i.clamp(0, 255))
-          Railwatch.flush
+          # Deliberately no flush. The engine's at_exit calls Reporter#shutdown,
+          # which wakes the reporter thread and joins it for shutdown_timeout --
+          # already a bounded last delivery, and already the one that ships a
+          # failed task's exception. Flushing here as well delivered the same
+          # records a second way, on the application's own thread, with no
+          # bound: against a receiver that accepts connections and never
+          # answers it cost a full timeout ladder per process, measured at ~6s,
+          # and ~12s when it queued behind a delivery the reporter thread was
+          # already stuck in. An app whose entrypoint boots Rails eleven times
+          # spent that eleven times over and lost the deploy.
         end
       end
 

data/lib/railwatch/patches/runner_command.rb

@@ -91,7 +91,9 @@ module Railwatch
           }
           fields[:interactive] = true if interactive
           Railwatch.finish_execution(:command, **fields)
-          Railwatch.flush
+          # No flush here either; see the note in patches/rake_task.rb. The
+          # at_exit shutdown is the bounded delivery, and it runs for a runner
+          # exactly as it does for a task.
         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,

data/lib/railwatch/version.rb

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