railwatch 0.1.4 → 0.2.0

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

@@ -8,6 +8,14 @@
 # (https://kamal-deploy.org/docs/hooks/overview/), so it POSTs straight to the
 # ingest host instead of shelling into a container. Never fails a deploy.
 set -e
+
+# Embedded install (transport = :local): the marker is a row in the app's own
+# railwatch database, so record it inside the deployed container and stop.
+if [ "${RAILWATCH_TRANSPORT:-}" = "local" ]; then
+  bin/kamal app exec --primary --reuse "bin/rails railwatch:deploy[$KAMAL_VERSION]" || true
+  exit 0
+fi
+
 [ -z "$RAILWATCH_TOKEN" ] && exit 0
 
 # Optional: .kamal/hooks/post-deploy --sourcemaps, or set

data/lib/puma/plugin/railwatch.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "puma/plugin"
+
+# `plugin :railwatch` in config/puma.rb. In embedded mode, forks one
+# Railwatch::Writer from the Puma process once it has booted, restarts it if
+# it dies, and stops it with Puma. Same shape as Solid Queue's
+# `solid_queue_mode :fork`, in both cluster and single mode: a default Rails
+# 8 app runs Puma in single mode (no WEB_CONCURRENCY), and that app's
+# batches belong off its request threads just as much. The fork happens
+# from the plugin's background thread with the app loaded and Rails'
+# ForkTracker resetting every Railwatch thread in the child, exactly as it
+# does for a Puma cluster worker. A no-op when Railwatch is off or the
+# transport is not :local, so it is safe to leave in place.
+#
+# Nothing in `start` may touch Railwatch: `bundle exec puma` fires plugin
+# starts BEFORE it loads the Rack app, so the constant may not exist yet.
+# Every decision that needs the app is made from the background supervisor,
+# which waits for after_booted.
+Puma::Plugin.create do
+  attr_reader :log_writer, :writer_pid
+
+  POLL = 2
+
+  def start(launcher)
+    @log_writer = launcher.log_writer
+    @puma_pid = $$
+    @launcher = launcher
+    @shutting_down = false
+    @booted = false
+    @warned = false
+
+    # When the app is already loaded (`bin/rails server` loads it before
+    # handing over to Puma), mark a writer expected now: cluster workers fork
+    # from this process after start and inherit the flag, so they retain
+    # batches while the writer is starting instead of writing them in-process.
+    # Under bare `puma` this is false and the workers find the writer on
+    # their transport's next re-check instead (Transport::Socket).
+    ::Railwatch::Writer.expected! if active?
+
+    # in_background blocks are collected at plugin start and started by the
+    # runner once, so this has to be registered here, not from after_booted
+    # (by then they have already been fired and a late block never runs). It
+    # waits for boot itself.
+    in_background { supervise }
+
+    launcher.events.after_booted { booted! }
+    # A phased restart fires before_restart and then, once the new workers
+    # are up, after_booted again. The writer is stopped for the restart and
+    # the supervisor, which is still running, respawns it when @booted flips
+    # back. Only a real stop latches shutdown.
+    launcher.events.before_restart { restart_writer }
+    # after_stopped only latches. It is NOT where the writer is stopped:
+    # Puma's SIGTERM trap fires it BEFORE `stop_blocked` drains in-flight
+    # requests, so stopping here would take the writer away from requests
+    # that are still running. at_exit runs after the whole run loop.
+    launcher.events.after_stopped { @shutting_down = true }
+    at_exit { shutdown_writer if Process.pid == @puma_pid }
+  end
+
+  private
+
+  def booted!
+    @booted = true
+    ::Railwatch::Writer.expected! if active?
+  end
+
+  # Whether this process should run a writer. Answered fresh each time, and
+  # safe before the app is loaded: `defined?(Railwatch)` is true as soon as
+  # the gem's entrypoint has been required (Bundler.require), but a bare
+  # `puma` on an app that has not required it yet sees neither, and must not
+  # raise out of Puma's boot.
+  def active?
+    return false unless defined?(::Railwatch) && ::Railwatch.respond_to?(:enabled?)
+    return false unless ::Railwatch.enabled? && ::Railwatch.config.local?
+
+    path = ::Railwatch.config.writer_socket_path
+    return false if path.nil?
+    return true if ::Railwatch::Writer.usable_path?(path)
+
+    unless @warned
+      @warned = true
+      log "Railwatch writer not started: socket path #{path} is #{path.bytesize} bytes, over the " \
+          "#{::Railwatch::Writer::MAX_SOCKET_PATH}-byte limit; set RAILWATCH_WRITER_SOCKET to a shorter path. " \
+          "Batches are written in-process meanwhile."
+    end
+    false
+  end
+
+  def spawn_writer
+    @writer_pid = ::Railwatch::Writer.fork_writer! do
+      ::Railwatch::Writer.run!(parent: @puma_pid)
+    end
+    log "Railwatch writer started (pid #{@writer_pid})"
+  rescue SystemCallError => e
+    @writer_pid = nil
+    log "Railwatch writer could not be forked (#{e.class}: #{e.message}); retrying"
+  end
+
+  # Puma's cluster reaps every child with wait2(-1), the writer included, so
+  # waitpid on the writer's pid raises ECHILD after it has died. Liveness is
+  # asked with signal 0 instead, which works whoever reaped it.
+  def supervise
+    loop do
+      sleep POLL
+      break if @shutting_down
+      next unless @booted && active?
+      next if writer_alive?
+
+      log "Railwatch writer (pid #{@writer_pid}) is gone; starting" if @writer_pid
+      spawn_writer
+    end
+  end
+
+  def writer_alive?
+    return false unless @writer_pid
+
+    Process.kill(0, @writer_pid)
+    # A zombie the cluster has not reaped yet still answers signal 0.
+    !Process.waitpid(@writer_pid, Process::WNOHANG)
+  rescue Errno::ESRCH
+    false
+  rescue Errno::ECHILD
+    # Already reaped by the cluster: alive iff it still exists for kill 0.
+    begin
+      Process.kill(0, @writer_pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+  end
+
+  # For a restart: stop the writer and mark the cluster as not booted, so the
+  # supervisor spawns a fresh one once after_booted fires again.
+  def restart_writer
+    @booted = false
+    stop_writer
+  end
+
+  # Runs from at_exit, after Puma's run loop has returned and every request
+  # has been served, in both single and cluster mode. Flushes this process's
+  # own reporter (its process and health records, and in single mode the
+  # requests' records) while the writer is still listening, then stops it.
+  def shutdown_writer
+    @shutting_down = true
+    if defined?(::Railwatch) && ::Railwatch.respond_to?(:enabled?) && ::Railwatch.enabled? && ::Railwatch.config.local?
+      ::Railwatch.reporter.shutdown
+    end
+    stop_writer
+  rescue StandardError => e
+    log "Railwatch writer shutdown failed (#{e.class}: #{e.message})"
+  end
+
+  # TERM closes the writer's listener and it drains what it is holding; the
+  # wait also reaps it, so a cluster master never leaves a zombie behind.
+  def stop_writer
+    return unless @writer_pid
+
+    Process.kill(:TERM, @writer_pid)
+    Process.wait(@writer_pid)
+  rescue Errno::ECHILD, Errno::ESRCH
+    nil
+  ensure
+    @writer_pid = nil
+  end
+
+  def log(message)
+    log_writer.log(message)
+  end
+end

data/lib/railwatch/authentication.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Railwatch
+  # `bin/rails railwatch:authentication:configure`: stores the embedded
+  # dashboard's HTTP Basic credentials in the current environment's Rails
+  # credentials, the same way Mission Control Jobs' authentication:configure
+  # does. Asks for a user, generates the password, appends a `railwatch:`
+  # entry to the credentials file the environment reads.
+  module Authentication
+    module_function
+
+    def configure(io: $stdin, out: $stdout)
+      unless credentials_accessible?
+        out.puts "Rails credentials are not configured or the key is not available for `#{Rails.env}`. " \
+                 "Set them up (`bin/rails credentials:help`) or set RAILWATCH_HTTP_BASIC_AUTH_USER and " \
+                 "RAILWATCH_HTTP_BASIC_AUTH_PASSWORD in the environment instead."
+        return false
+      end
+      if configured?
+        out.puts "HTTP Basic authentication is already configured for `#{Rails.env}` (railwatch.http_basic_auth_user); " \
+                 "edit it with `bin/rails credentials:edit#{env_flag}`."
+        return false
+      end
+
+      out.print "Enter username for the Railwatch dashboard (#{Rails.env}): "
+      username = io.gets.to_s.strip
+      if username.empty?
+        out.puts "No username given; nothing written."
+        return false
+      end
+      password = SecureRandom.base58(48)
+      # Merge, never append. A second top-level `railwatch:` mapping would
+      # win in Psych and silently hide whatever the first one held, and a
+      # username with YAML syntax in it would reshape the file; round-tripping
+      # through the parser and to_yaml quotes it correctly.
+      merged = (YAML.safe_load(credentials.read.to_s, permitted_classes: [ Symbol ], aliases: true) || {})
+      unless merged.is_a?(Hash)
+        out.puts "#{credentials.content_path} does not contain a YAML mapping; edit it by hand."
+        return false
+      end
+      merged["railwatch"] = (merged["railwatch"].is_a?(Hash) ? merged["railwatch"] : {})
+        .merge("http_basic_auth_user" => username, "http_basic_auth_password" => password)
+      credentials.write(merged.to_yaml)
+
+      out.puts <<~DONE
+        Stored in #{credentials.content_path.relative_path_from(Rails.root)} under `railwatch:`.
+
+        The dashboard at /railwatch now asks for:
+          user:     #{username}
+          password: #{password}
+
+        Edit later with `bin/rails credentials:edit#{env_flag}`. Restart the app to pick it up.
+      DONE
+      true
+    end
+
+    def credentials_accessible?
+      credentials.read.present?
+    rescue ActiveSupport::EncryptedFile::MissingKeyError, ActiveSupport::MessageEncryptor::InvalidMessage
+      false
+    end
+
+    # Both halves, so a file holding only one of them is repaired rather than
+    # refused (which would leave the dashboard closed with no way forward).
+    def configured?
+      %i[http_basic_auth_user http_basic_auth_password].all? { |key| credentials.dig(:railwatch, key).present? }
+    end
+
+    # The file Rails.application.credentials reads for this environment:
+    # config/credentials/<env>.yml.enc when that environment has one, else
+    # config/credentials.yml.enc.
+    def credentials
+      config = Rails.application.config.credentials
+      Rails.application.encrypted(config.content_path, key_path: config.key_path)
+    end
+
+    def env_flag
+      Rails.root.join("config/credentials/#{Rails.env}.yml.enc").exist? ? " --environment #{Rails.env}" : ""
+    end
+  end
+end

data/lib/railwatch/configuration.rb

@@ -60,7 +60,15 @@ module Railwatch
       Rack::QueryParser::ParameterTypeError
     ].freeze
 
-    attr_accessor :enabled, :token, :ingest_url, :allow_http, :server, :environment,
+    # What the dashboard controllers inherit from unless the host names its
+    # own. Also how `dashboard_gate` tells "they wired their own auth" from
+    # "they left the default".
+    DEFAULT_BASE_CONTROLLER = "ActionController::Base"
+
+    attr_accessor :enabled, :token, :ingest_url, :allow_http, :server, :environment, :transport,
+                  :issue_prefix, :repository_url, :retention_days, :dashboard_user, :writer_socket,
+                  :http_basic_auth_enabled, :http_basic_auth_user, :http_basic_auth_password, :base_controller_class,
+                  :dashboard_open,
                   :sample, :log_level, :capture_request_payload,
                   :capture_exception_source, :capture_exception_locals, :redact_headers, :redact_params,
                   :buffer_size, :buffer_bytes, :execution_buffer_bytes, :batch_bytes,
@@ -69,7 +77,8 @@ module Railwatch
                   :connect_timeout, :timeout, :shutdown_timeout,
                   :slow_query_threshold_ms, :n_plus_one_threshold,
                   :max_view_renders_per_execution, :ignored_cache_key_prefixes,
-                  :beacon_enabled, :beacon_rate_limit, :debug, :capture_default_vendor_commands,
+                  :beacon_enabled, :beacon_rate_limit, :beacon_global_rate_limit, :beacon_allowed_origins,
+                  :debug, :capture_default_vendor_commands,
                   :capture_default_vendor_cache_keys, :on_unrecoverable,
                   :capture_framework_events,
                   :tail_sample_slow_ms, :failure_context, :propagate_traces, :trace_propagation_hosts,
@@ -88,6 +97,39 @@ module Railwatch
     def initialize
       @enabled = env_bool("RAILWATCH_ENABLED", true)
       @token = ENV["RAILWATCH_TOKEN"]
+      @transport = ENV.fetch("RAILWATCH_TRANSPORT", "http").to_sym
+      # Embedded dashboard settings; ignored when transport is :http.
+      @issue_prefix = ENV["RAILWATCH_ISSUE_PREFIX"]
+      @repository_url = ENV["RAILWATCH_REPOSITORY_URL"]
+      @retention_days = env_int("RAILWATCH_RETENTION_DAYS", 7)
+      @dashboard_user = nil
+      # Dashboard access, the way Mission Control Jobs does it: HTTP Basic
+      # authentication is on and CLOSED by default. With no user and password
+      # configured every dashboard request is 401, so an install that forgot
+      # to set anything up is never a public page. Credentials come from
+      # Rails credentials (railwatch.http_basic_auth_user/_password, written
+      # by `bin/rails railwatch:authentication:configure`), from these env
+      # vars, or by assignment here. A host with its own admin auth turns
+      # Basic off and names a base controller, or wraps the mount in a
+      # routes constraint.
+      @http_basic_auth_enabled = env_bool("RAILWATCH_HTTP_BASIC_AUTH_ENABLED", true)
+      @http_basic_auth_user = ENV["RAILWATCH_HTTP_BASIC_AUTH_USER"]
+      @http_basic_auth_password = ENV["RAILWATCH_HTTP_BASIC_AUTH_PASSWORD"]
+      # Only consulted when HTTP Basic is off: the host saying, in as many
+      # words, "I accept that anyone who can reach this URL can read it".
+      # A private network or a VPN is a real answer; this is how you say so,
+      # and it is what silences the boot warning and opens the live channel.
+      @dashboard_open = env_bool("RAILWATCH_DASHBOARD_OPEN", false)
+      # The dashboard controllers inherit from this class, so a host's own
+      # before_actions (require an admin, redirect to sign-in) run in front of
+      # every page. Default is the engine's own base, which authenticates
+      # nothing itself beyond HTTP Basic above.
+      @base_controller_class = ENV.fetch("RAILWATCH_BASE_CONTROLLER_CLASS", DEFAULT_BASE_CONTROLLER)
+      # Embedded mode's writer process (lib/railwatch/writer.rb): the Unix
+      # socket the Puma workers hand their batches to. Relative paths are
+      # under Rails.root. nil disables the writer and every process writes
+      # its own batches, as before.
+      @writer_socket = ENV.fetch("RAILWATCH_WRITER_SOCKET", "tmp/sockets/railwatch-writer.sock")
       @ingest_url = ENV.fetch("RAILWATCH_INGEST_URL", "https://railwatch.rebulk.com")
       @allow_http = env_bool("RAILWATCH_ALLOW_HTTP", false)
       @project_root = defined?(Rails) ? Rails.root : Dir.pwd
@@ -147,6 +189,19 @@ module Railwatch
       # from a shell. Per client IP per minute; 0 turns the limit off, and a
       # negative value is normalized to 0 rather than left to mean anything.
       @beacon_rate_limit = [ env_int("RAILWATCH_BEACON_RATE_LIMIT", 120), 0 ].max
+      # The same three defences a hosted product puts in front of a public
+      # browser-ingest endpoint (Sentry's are allowed domains, per-key rate
+      # limits and spike protection): a per-IP limit above, a ceiling on the
+      # whole endpoint so one busy minute cannot fill the telemetry database,
+      # and an origin allowlist. None is authentication -- a public endpoint
+      # cannot have any, since the credential would be in the page -- they
+      # bound abuse. 0 disables a limit; beacon_enabled = false removes the
+      # endpoint's work entirely.
+      @beacon_global_rate_limit = [ env_int("RAILWATCH_BEACON_GLOBAL_RATE_LIMIT", 6_000), 0 ].max
+      # Extra origins allowed to beacon, beyond the app's own. Same meaning
+      # as Sentry's allowed domains: "https://app.example.com", or a host on
+      # its own. Empty means same-origin only.
+      @beacon_allowed_origins = ENV["RAILWATCH_BEACON_ALLOWED_ORIGINS"]&.split(",")&.map(&:strip)&.reject(&:empty?) || []
       @debug = env_bool("RAILWATCH_DEBUG", false)
       # Tail-based sampling: a head-sampled-out execution is still kept when
       # it ran at least this long, raised, or Railwatch.keep! was called. nil = off.
@@ -238,7 +293,83 @@ module Railwatch
     end
 
     def enabled?
-      @enabled && token.present?
+      @enabled && (local? || token.present?)
+    end
+
+    # :local writes telemetry into the engine's own database in-process;
+    # anything else ships it to ingest_url over HTTPS.
+    def local? = transport.to_s == "local"
+
+    # Absolute path of the writer socket, or nil when the writer is off.
+    def writer_socket_path
+      path = writer_socket.to_s
+      return nil if path.empty?
+
+      root = defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd
+      File.expand_path(path, root)
+    end
+
+    # Who the embedded dashboard shows as the signed-in operator. A host
+    # passes a lambda taking the request (cookies, warden, whatever it uses)
+    # and returning a User, {id:, name:, email:} or nil. Authentication and
+    # authorisation stay the host's job: put the mount behind its own
+    # constraint. This only names the person for comments and saved views.
+    # Both halves present. Read late (not at boot) so credentials set from an
+    # initializer, an env var or the configure task all count.
+    def http_basic_auth_configured?
+      http_basic_auth_user.to_s.strip != "" && http_basic_auth_password.to_s.strip != ""
+    end
+
+    # Whether the request carries the configured HTTP Basic credentials.
+    # False when Basic is on and nothing is configured (closed), true when
+    # Basic is off (the host's base controller or routes constraint is the
+    # gate then). Shared by the dashboard controller and the live channel.
+    def http_basic_auth_ok?(request)
+      return true unless http_basic_auth_enabled
+      return false unless http_basic_auth_configured?
+
+      ActionController::HttpAuthentication::Basic.authenticate(request) do |user, password|
+        ActiveSupport::SecurityUtils.secure_compare(user, http_basic_auth_user.to_s) &
+          ActiveSupport::SecurityUtils.secure_compare(password, http_basic_auth_password.to_s)
+      end == true
+    end
+
+    # Which gate is in force, for the doctor, the boot warning and the live
+    # channel. :basic when HTTP Basic is on (closed until credentials exist),
+    # :controller when the host named its own base controller, :resolver when
+    # it gave a dashboard_user that can refuse, :open when it said the
+    # dashboard is deliberately public, and :undeclared when Basic is off and
+    # none of those is true -- which usually means a routes constraint the
+    # gem cannot see, and might mean nothing at all.
+    def dashboard_gate
+      return :basic if http_basic_auth_enabled
+      return :controller unless base_controller_class == DEFAULT_BASE_CONTROLLER
+      return :resolver if dashboard_user
+      return :open if dashboard_open
+
+      :undeclared
+    end
+
+    # Whether a live-update subscription is allowed. Action Cable runs on the
+    # host's own /cable endpoint, which a routes constraint around the
+    # 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
+      end
+    end
+
+    def resolve_dashboard_user(request)
+      resolved = dashboard_user.respond_to?(:call) ? dashboard_user.call(request) : dashboard_user
+      case resolved
+      when User then resolved
+      when Hash then User.new(id: resolved[:id] || User::ID, name: resolved[:name].to_s.presence || "Operator", email: resolved[:email])
+      else User.default
+      end
     end
 
     def ingest_url_allowed?

data/lib/railwatch/dashboard_assets.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rack/files"
+
+module Railwatch
+  # Serves the prebuilt dashboard bundle the gem ships under public/railwatch.
+  # Vite wrote every asset URL with base /railwatch/assets/, so a request for
+  # /railwatch/assets/assets/app-abc123.js maps to public/railwatch/assets/
+  # app-abc123.js. Files are content-hashed, so they are immutable. The
+  # favicon is the one unhashed file, served with a short cache instead.
+  class DashboardAssets
+    PREFIX = "/railwatch/assets/"
+    ICONS = { "/railwatch/icon.svg" => "/icon.svg", "/railwatch/icon.png" => "/icon.png" }.freeze
+
+    # Put this middleware in the host's stack. Before ActionDispatch::Static
+    # when the host has it, which is what keeps a same-named file in the
+    # app's own public/ from shadowing the dashboard's. An app that serves
+    # static files from nginx, a CDN or Thruster sets
+    # `config.public_file_server.enabled = false` and has no such middleware:
+    # inserting relative to it would raise and take the whole application
+    # down at boot, so go to the front instead, which is the same position
+    # relative to everything that remains.
+    def self.install!(app, root:)
+      if app.config.public_file_server.enabled
+        app.middleware.insert_before ActionDispatch::Static, self, root: root
+      else
+        app.middleware.insert 0, self, root: root
+      end
+    end
+
+    def initialize(app, root:)
+      @app = app
+      @files = Rack::Files.new(root, { "cache-control" => "public, max-age=31536000, immutable" })
+      @icons = Rack::Files.new(root, { "cache-control" => "public, max-age=86400" })
+    end
+
+    def call(env)
+      path = env["PATH_INFO"]
+      return @icons.call(env.merge("PATH_INFO" => ICONS[path])) if ICONS.key?(path)
+      return @app.call(env) unless path.start_with?(PREFIX) && !path.include?("..")
+
+      @files.call(env.merge("PATH_INFO" => path.delete_prefix("/railwatch/assets")))
+    end
+  end
+end

data/lib/railwatch/embedded.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Process-local state for the embedded (in-process) mode and the stand-ins
+  # the platform's code expects from its account layer.
+  module Embedded
+    # Relation-shaped empty set for platform associations an embedded install
+    # does not have (Linear links, integrations). Every scope returns itself.
+    NONE = Class.new do
+      def method_missing(*) = self
+      def respond_to_missing?(*) = true
+      def to_a = []
+      def each(&) = [].each(&)
+      def first = nil
+      def map(&) = []
+      def count = 0
+      def any? = false
+      def none? = true
+      def exists?(*) = false
+      def empty? = true
+      def limit(*) = self
+      def where(*) = self
+      def find_each(&) = nil
+    end.new.freeze
+
+    # The platform scopes everything by account (plan, quota, retention,
+    # members). One embedded install is one account with none of that.
+    module Account
+      module_function
+
+      def id = 1
+      def name = Rails.application.class.module_parent_name
+      def slug = name.parameterize
+      def plan = "embedded"
+      def retention_days = Railwatch.config.retention_days
+      def auto_resolve_after_days = 14
+      # Whoever the host's resolver named for this request, not the anonymous
+      # placeholder: an embedded install has no member list, so the account's
+      # one "member" is the person looking at it.
+      def users = [ User.current || User.default ]
+      def members = users
+      def memberships = NONE
+      def integrations = NONE
+      def applications = [ Application.current ]
+      def environments = [ Environment.current ]
+      def quota_exhausted? = false
+      def as_json(*) = { id: id, name: name, slug: slug, plan: plan }
+    end
+
+    class << self
+      attr_accessor :last_seen_at
+    end
+  end
+end

data/lib/railwatch/engine.rb

@@ -1,11 +1,56 @@
 # frozen_string_literal: true
 
+# The dashboard controllers are Inertia controllers; a host that does not use
+# Inertia itself never requires the gem, so the engine does.
+require "inertia_rails"
+# The engine's jobs (grouping, rollups, scans) are Active Job classes even
+# though embedded mode calls their perform directly, so a host built with
+# `rails new --minimal` (no Active Job) still needs the framework loaded.
+# Part of the rails gem this one depends on, so nothing new is pulled in.
+require "active_job/railtie"
+
 module Railwatch
+  # isolate_namespace would give every model a railwatch_ prefix. Only the
+  # engine's own records (issues, comments, deploys: Railwatch::ApplicationRecord)
+  # carry it; the telemetry tables are the hosted platform's schema and stay
+  # unprefixed. Defined before isolate_namespace runs, which only adds a
+  # prefix when none is set.
+  def self.table_name_prefix = ""
+
   class Engine < ::Rails::Engine
     isolate_namespace Railwatch
 
     config.railwatch = ActiveSupport::OrderedOptions.new
 
+    # The dashboard bundle is built into the gem at release time; serve it
+    # from here so a host app needs no asset pipeline integration at all.
+    # Where it goes in the stack is DashboardAssets.install!'s decision.
+    initializer "railwatch.dashboard_assets" do |app|
+      Railwatch::DashboardAssets.install!(app, root: root.join("public/railwatch").to_s)
+    end
+
+    # Action Cable is optional: live dashboard updates need it, nothing else
+    # does. A host without it (`rails new --minimal`, --skip-action-cable)
+    # must not eager-load the engine's channel, which inherits from a class
+    # that does not exist there.
+    initializer "railwatch.channels", before: :setup_main_autoloader do
+      Rails.autoloaders.main.ignore(root.join("app/channels")) unless defined?(::ActionCable)
+    end
+
+    # The dashboard bundle subscribes to "EnvironmentChannel" by name; Action
+    # Cable constantizes that, so the engine's channel needs the bare name.
+    # Only defined when the host has not got one of its own.
+    initializer "railwatch.live_channel" do
+      next unless defined?(::ActionCable)
+
+      # Action Cable constantizes the subscription's channel name at
+      # subscribe time; the alias only has to exist by then, and it must
+      # not clobber a host channel of the same name.
+      config.to_prepare do
+        Object.const_set(:EnvironmentChannel, Railwatch::EnvironmentChannel) unless Object.const_defined?(:EnvironmentChannel)
+      end
+    end
+
     # The request middleware goes first so wall time includes every other
     # middleware, exactly like Nightwatch's GlobalMiddleware.
     initializer "railwatch.middleware", before: :load_config_initializers do |app|
@@ -18,8 +63,39 @@ module Railwatch
       Railwatch::Console.silence!
     end
 
+    # Same source Mission Control Jobs reads: railwatch.http_basic_auth_user
+    # and _password in Rails credentials, which `bin/rails
+    # railwatch:authentication:configure` writes. An initializer or env var
+    # that already set them wins.
+    initializer "railwatch.http_basic_auth", after: :load_config_initializers do |app|
+      config = Railwatch.config
+      config.http_basic_auth_user ||= app.credentials.dig(:railwatch, :http_basic_auth_user)
+      config.http_basic_auth_password ||= app.credentials.dig(:railwatch, :http_basic_auth_password)
+    end
+
+    # Two things worth one line in the log at boot, because both are
+    # invisible until something is already wrong: a Rails/json pair that
+    # cannot decode, and an embedded dashboard with nothing declared in
+    # front of it.
+    initializer "railwatch.warnings", after: :load_config_initializers do
+      config.after_initialize do
+        next unless Railwatch.enabled?
+
+        Rails.logger.warn("[railwatch] #{Railwatch::JsonCompat.advice}") if Railwatch::JsonCompat.broken?
+
+        if Railwatch.config.local? && Railwatch.config.dashboard_gate == :undeclared && !Rails.env.local?
+          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."
+          )
+        end
+      end
+    end
+
     initializer "railwatch.transport_security", after: :load_config_initializers do
-      next if Railwatch.config.ingest_url_allowed?
+      next if Railwatch.config.local? || Railwatch.config.ingest_url_allowed?
 
       Rails.logger.warn(
         "Railwatch will not send telemetry to #{Railwatch.config.ingest_url}: plain HTTP is allowed only for loopback " \
@@ -129,6 +205,17 @@ module Railwatch
       at_exit { Railwatch::Sessions.stop! }
     end
 
+    # The embedded install's maintenance clock (release health, scans,
+    # pruning). Same shape and ordering rationale as "railwatch.health":
+    # stopped before the reporter's final flush. Maintenance.start! is a
+    # no-op unless the transport is local.
+    initializer "railwatch.maintenance" do
+      next unless Railwatch.enabled?
+
+      Railwatch::Maintenance.start!
+      at_exit { Railwatch::Maintenance.stop! }
+    end
+
     # lib/tasks/railwatch_tasks.rake is picked up by Rails::Engine's default
     # lib/tasks convention; the rake_tasks block above only installs the
     # Rake::Task patch.
@@ -138,6 +225,7 @@ end
 require "railwatch/console"
 require "railwatch/health"
 require "railwatch/sessions"
+require "railwatch/maintenance"
 require "railwatch/middleware/request"
 require "railwatch/job_tracing"
 require "railwatch/controller_helpers"

data/lib/railwatch/ingest_request_body_limit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# The hosted platform bounds ingest request bodies with Rack middleware. In
+# an embedded install nothing arrives over HTTP, but Ingest::Payload and
+# Telemetry::Attachment still size their limits from this constant.
+module Railwatch
+  module IngestRequestBodyLimit
+    MAX_BYTES = 32 * 1024 * 1024
+  end
+end