railwatch-server 0.1.0-x86_64-linux

data/lib/railwatch/server/relay.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Server
+    # Sockets the proxy has taken from Puma, moved by one thread per app
+    # process with IO.select instead of a Puma thread (or two threads) per
+    # connection. Two kinds:
+    #
+    # - live: the live channel (the dashboard's websocket, one per open tab),
+    #   spliced both ways until either side closes (#add).
+    # - proxied: every other dashboard request (#proxy). The request, which
+    #   Puma has read in full, is written to the server; the response is
+    #   written back to the browser as it arrives, byte for byte except its
+    #   head (Connection: close, the app's own Set-Cookie added: ProxyHandoff), and then
+    #   both sockets close. A slow page waits here, not on a Puma thread.
+    #
+    # Each kind has its own cap (Configuration#max_live_connections,
+    # #max_proxied_requests). Each direction buffers at most MAX_BUFFER bytes
+    # for a slow reader before its source stops being read.
+    #
+    # A proxied request the server has not started answering within
+    # first_byte_timeout gets a 504, one it stops answering before sending a
+    # byte a 502, both written here; one that goes quiet for idle_timeout
+    # after its first byte is cut off.
+    class Relay
+      CHUNK = 16 * 1024
+      MAX_BUFFER = 1024 * 1024
+      MAX_HEAD = 64 * 1024
+      HOP_BY_HOP = %w[connection keep-alive proxy-connection].freeze
+      # The server's own HSTS (sent behind a trusted proxy with an https
+      # url): the host is the app's, and so is its policy (ProxyHandoff
+      # passes the app's on).
+      APP_OWNED = %w[strict-transport-security].freeze
+      REASONS = { 502 => "Bad Gateway", 504 => "Gateway Timeout" }.freeze
+
+      # input: what this side's peer is sent instead of what is read from io
+      # (a proxied request's body, from Puma's tempfile).
+      Side = Struct.new(:io, :peer, :pending, :eof, :input, :pair)
+      # head: the proxied response's head while it arrives; nil once it has
+      # been passed on (or the relay answered instead).
+      Pair = Struct.new(:kind, :left, :right, :started_at, :active_at, :head, :extra_headers)
+
+      class << self
+        # One per process: a forked Puma worker starts its own.
+        def current
+          @mutex ||= Mutex.new
+          @mutex.synchronize do
+            @current = nil unless @pid == ::Process.pid
+            @pid = ::Process.pid
+            config = Railwatch::Server.config
+            @current ||= new(max_live: config.max_live_connections, max_proxied: config.max_proxied_requests,
+                             first_byte_timeout: config.proxy_first_byte_timeout, idle_timeout: config.proxy_idle_timeout)
+          end
+        end
+      end
+
+      def initialize(max_live: 64, max_proxied: 64, first_byte_timeout: 120, idle_timeout: 60)
+        @max = { live: max_live, proxied: max_proxied }
+        @first_byte_timeout = first_byte_timeout
+        @idle_timeout = idle_timeout
+        @sides = {}
+        @pairs = []
+        @mutex = Mutex.new
+        @wake_r, @wake_w = IO.pipe
+        @thread = nil
+      end
+
+      def max(kind = :live) = @max.fetch(kind)
+
+      def size(kind = :live) = @mutex.synchronize { @pairs.count { _1.kind == kind } }
+
+      def full?(kind) = size(kind) >= @max.fetch(kind)
+
+      # Splices `a` and `b` until either closes. False when the live cap is
+      # reached; the caller still owns both sockets then.
+      def add(a, b)
+        @mutex.synchronize do
+          return false if @pairs.count { _1.kind == :live } >= @max[:live]
+
+          register(:live, a, b)
+        end
+        wake
+        true
+      end
+
+      # One proxied request: `request` (its head, and its body when small) and
+      # then `body` (an IO, read to its end) go to the server on `upstream`;
+      # the server's response goes to `client` with `headers` ([name, value]
+      # pairs: the app's Set-Cookie) added to its head; then all three close. The relay owns them
+      # from here. Never refuses: the proxy checks #full? first, so the cap
+      # can be passed by as many requests as are checked at the same moment.
+      def proxy(client, upstream, request:, body: nil, headers: [])
+        @mutex.synchronize do
+          pair = register(:proxied, client, upstream)
+          pair.head = +"".b
+          pair.extra_headers = headers
+          pair.right.pending << request.b
+          pair.left.eof = body.nil?
+          if body
+            pair.left.input = body
+            @sides[body] = pair.left
+          end
+        end
+        wake
+        true
+      end
+
+      private
+
+      def register(kind, a, b)
+        left = Side.new(a, nil, +"".b, false)
+        right = Side.new(b, left, +"".b, false)
+        left.peer = right
+        now = monotonic
+        pair = Pair.new(kind, left, right, now, now)
+        left.pair = right.pair = pair
+        @sides[a] = left
+        @sides[b] = right
+        @pairs << pair
+        start_thread
+        pair
+      end
+
+      def start_thread
+        return if @thread&.alive?
+
+        @thread = Thread.new { run }
+        @thread.name = "railwatch-server-relay"
+        @thread.report_on_exception = false
+      end
+
+      def wake
+        @wake_w.write_nonblock(".", exception: false)
+      end
+
+      def run
+        loop do
+          readers, writers, timed = @mutex.synchronize do
+            sides = @pairs.flat_map { [ _1.left, _1.right ] }
+            [ sides.select { |s| !s.eof && s.peer.pending.bytesize < MAX_BUFFER }.map { |s| s.input || s.io },
+              sides.reject { |s| s.pending.empty? }.map(&:io),
+              @pairs.any? { _1.kind == :proxied } ]
+          end
+          readable, writable, = IO.select(readers + [ @wake_r ], writers, nil, timed ? 0.5 : 30)
+          if readable
+            @wake_r.read_nonblock(1024, exception: false) if readable.delete(@wake_r)
+            writable.each { |io| flush(io) }
+            readable.each { |io| pull(io) }
+          end
+          expire if timed
+        end
+      rescue StandardError => e
+        warn("[railwatch-server] relay stopped: #{e.class}: #{e.message}")
+        @mutex.synchronize do
+          @sides.each_key { |io| io.close rescue nil }.clear
+          @pairs.clear
+        end
+      end
+
+      def pull(io)
+        side = @mutex.synchronize { @sides[io] }
+        return unless side
+
+        pair = side.pair
+        data = io.read_nonblock(CHUNK, exception: false)
+        case data
+        when :wait_readable, :wait_writable then nil
+        when nil
+          side.eof = true
+          if side.input
+            @mutex.synchronize { @sides.delete(io) }
+            io.close
+            side.input = nil
+          end
+          return fail_pair(pair, 502, "closed the connection without answering") if side.equal?(pair.right) && pair.head
+
+          close_if_done(side)
+        else
+          pair.active_at = monotonic
+          if side.equal?(pair.right) && pair.head
+            pair.head << data
+            split = pair.head.index("\r\n\r\n")
+            unless split
+              fail_pair(pair, 502, "sent a response head over #{MAX_HEAD} bytes") if pair.head.bytesize > MAX_HEAD
+              return
+            end
+            data = response_head(pair.head.byteslice(0, split), pair.extra_headers) + pair.head.byteslice((split + 4)..)
+            pair.head = nil
+          end
+          side.peer.pending << data
+          flush(side.peer.io)
+        end
+      rescue IOError, SystemCallError => e
+        side.equal?(pair.right) ? fail_pair(pair, 502, "dropped the connection (#{e.class})") : close_pair(pair)
+      end
+
+      def flush(io)
+        side = @mutex.synchronize { @sides[io] }
+        return unless side
+        return if side.pending.empty?
+
+        written = io.write_nonblock(side.pending, exception: false)
+        if written.is_a?(Integer)
+          side.pending = side.pending.byteslice(written..)
+          side.pair.active_at = monotonic
+        end
+        close_if_done(side)
+      rescue IOError, SystemCallError => e
+        side.equal?(side.pair.right) ? fail_pair(side.pair, 502, "dropped the connection (#{e.class})") : close_pair(side.pair)
+      end
+
+      # Live: one side closed, what it sent is delivered to the other, then
+      # both go (a websocket's close frame is data, so nothing is cut short).
+      # Proxied: the server has finished its response and the browser has all
+      # of it.
+      def close_if_done(side)
+        pair = side.pair
+        done = if pair.kind == :live
+                 (side.eof && side.peer.pending.empty?) || (side.peer.eof && side.pending.empty?)
+               else
+                 pair.right.eof && pair.left.pending.empty?
+               end
+        close_pair(pair) if done
+      end
+
+      # The server's response head, for a connection that closes after it:
+      # the body is passed on as sent (its Content-Length or chunked framing
+      # included), so only the connection headers change.
+      def response_head(head, extra)
+        status, *fields = head.split("\r\n")
+        fields.reject! { |field| (HOP_BY_HOP + APP_OWNED).include?(field[/\A[^:]*/].strip.downcase) }
+        fields.concat(extra.map { |name, value| "#{name}: #{value}" })
+        "#{status}\r\n#{fields.map { "#{_1}\r\n" }.join}connection: close\r\n\r\n".b
+      end
+
+      # A proxied request the server failed: before the response started, the
+      # browser gets `status` with why, then the connection closes; after, it
+      # is cut short (a browser sees a truncated body as a failed load).
+      def fail_pair(pair, status, why)
+        return close_pair(pair) unless pair.kind == :proxied && pair.head && @mutex.synchronize { @pairs.include?(pair) }
+
+        message = "The Railwatch server #{why}. Its log is in the app's storage/railwatch/<env>/server.log.\n"
+        warn("[railwatch-server] dashboard request: #{status}: the server #{why}")
+        pair.head = nil
+        pair.active_at = monotonic
+        pair.right.eof = true
+        pair.right.pending.clear
+        pair.left.eof = true
+        if (input = pair.left.input)
+          @mutex.synchronize { @sides.delete(input) }
+          input.close rescue nil
+          pair.left.input = nil
+        end
+        pair.left.pending << "HTTP/1.1 #{status} #{REASONS[status]}\r\nContent-Type: text/plain; charset=utf-8\r\n" \
+                             "Content-Length: #{message.bytesize}\r\nConnection: close\r\n\r\n#{message}"
+        flush(pair.left.io)
+      end
+
+      def expire
+        now = monotonic
+        @mutex.synchronize { @pairs.select { _1.kind == :proxied } }.each do |pair|
+          if pair.head && now - pair.started_at > @first_byte_timeout
+            fail_pair(pair, 504, "did not answer within #{@first_byte_timeout} s (proxy_first_byte_timeout)")
+          elsif !pair.head && now - pair.active_at > @idle_timeout
+            warn("[railwatch-server] dashboard request: nothing moved for #{@idle_timeout} s (proxy_idle_timeout); closing it")
+            close_pair(pair)
+          end
+        end
+      end
+
+      def close_pair(pair)
+        @mutex.synchronize do
+          @pairs.delete(pair)
+          [ pair.left, pair.right ].each do |side|
+            [ side.io, side.input ].compact.each do |io|
+              @sides.delete(io)
+              io.close rescue nil
+            end
+          end
+        end
+      end
+
+      def monotonic = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/railwatch/server/settings.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Railwatch
+  module Server
+    # The server's own settings that come from the app: SMTP for alert and
+    # digest email, S3 backups, Google sign-in, retention, whether alerts are
+    # sent. Written to `<data dir>/server.env` (0600, replaced atomically on
+    # every start) and handed to the server as RAILWATCH_ENV_FILE, so secrets
+    # are neither on the server's command line nor in its environment, and
+    # never in a log: only the names of what was set are logged.
+    #
+    # Each comes from Railwatch::Server.config first, then from the app:
+    #
+    #   smtp      config.action_mailer.smtp_settings, when delivery_method is :smtp
+    #   mail_from ActionMailer::Base.default[:from]
+    #   backup    credentials.railwatch_server.backup
+    #   google    credentials.railwatch_server.google
+    #
+    # Anything the server reads that has no setting here goes in
+    # config.server_env ("RAILWATCH_..." => value). The server's own process
+    # environment still wins over this file (its rule for env files).
+    class Settings
+      Invalid = Class.new(StandardError)
+
+      def initialize(config, rails: (defined?(::Rails) && ::Rails.respond_to?(:application) ? ::Rails.application : nil))
+        @config = config
+        @rails = rails
+      end
+
+      # { "RAILWATCH_SMTP_ADDRESS" => "smtp.example.com", ... }, and which
+      # groups were set, for the log.
+      def env
+        out = {}
+        if (smtp = smtp_settings)
+          out.merge!(smtp_env(smtp))
+        end
+        if (from = mail_from)
+          out["RAILWATCH_SMTP_FROM"] = from
+        end
+        if (backup = backup_settings)
+          out.merge!(backup_env(backup))
+        end
+        if (google = google_settings)
+          out.merge!(google_env(google))
+        end
+        if (r = given(@config.retention))
+          out["RAILWATCH_DETAIL_RETENTION_DAYS"] = r[:detail_days] if r[:detail_days]
+          out["RAILWATCH_CORE_RETENTION_DAYS_MAX"] = r[:core_days_max] if r[:core_days_max]
+        end
+        out["RAILWATCH_ALERT_DELIVERY"] = @config.alert_delivery ? "on" : "off" unless @config.alert_delivery.nil?
+        out.merge!(@config.server_env.to_h.transform_keys(&:to_s))
+        out.transform_values { |v| v.to_s }.reject { |_, v| v.empty? }
+      end
+
+      def groups(env = self.env)
+        {
+          "smtp" => env.key?("RAILWATCH_SMTP_ADDRESS"),
+          "backup" => env.key?("RAILWATCH_BACKUP_S3_BUCKET"),
+          "google" => env.key?("RAILWATCH_GOOGLE_CLIENT_ID"),
+          "retention" => env.keys.any? { _1.include?("RETENTION") },
+          "alert_delivery" => env.key?("RAILWATCH_ALERT_DELIVERY")
+        }.select { |_, v| v }.keys + (@config.server_env.to_h.keys.map(&:to_s) - KNOWN)
+      end
+
+      # Writes the file the server reads; returns its path.
+      def write!(path)
+        body = +"# Written by railwatch-server on every start from the app's settings. Do not edit.\n"
+        env.each do |key, value|
+          raise Invalid, "#{key}: not a variable name" unless key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+          raise Invalid, "#{key}: a value cannot contain a line break" if value.match?(/[\r\n]/)
+
+          # The server strips one pair of matching quotes and keeps the rest
+          # verbatim (no escapes), so quoting keeps edge spaces and '#'.
+          body << "#{key}=\"#{value}\"\n"
+        end
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        tmp = "#{path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(body) }
+        File.chmod(0o600, tmp)
+        File.rename(tmp, path)
+        path
+      end
+
+      private
+
+      KNOWN = %w[
+        RAILWATCH_SMTP_ADDRESS RAILWATCH_SMTP_PORT RAILWATCH_SMTP_SECURITY RAILWATCH_SMTP_USERNAME RAILWATCH_SMTP_PASSWORD
+        RAILWATCH_SMTP_FROM RAILWATCH_BACKUP_S3_ENDPOINT RAILWATCH_BACKUP_S3_BUCKET RAILWATCH_BACKUP_S3_ACCESS_KEY_ID
+        RAILWATCH_BACKUP_S3_SECRET_ACCESS_KEY RAILWATCH_BACKUP_S3_REGION RAILWATCH_BACKUP_S3_PREFIX
+        RAILWATCH_BACKUP_INTERVAL_SECONDS RAILWATCH_GOOGLE_CLIENT_ID RAILWATCH_GOOGLE_CLIENT_SECRET
+        RAILWATCH_DETAIL_RETENTION_DAYS RAILWATCH_CORE_RETENTION_DAYS_MAX RAILWATCH_ALERT_DELIVERY
+      ].freeze
+
+      # nil: from the app. false or {}: off. A hash: that.
+      def given(value) = value.nil? ? nil : (value.respond_to?(:to_h) && value.to_h.any? ? symbolize(value) : false)
+
+      def smtp_settings
+        return given(@config.smtp) || nil unless @config.smtp.nil?
+        return unless @rails && defined?(::ActionMailer::Base)
+        return unless ::ActionMailer::Base.delivery_method == :smtp
+
+        settings = symbolize(::ActionMailer::Base.smtp_settings)
+        settings[:address] ? settings : nil
+      end
+
+      def mail_from
+        return @config.mail_from if @config.mail_from
+        return unless @rails && defined?(::ActionMailer::Base)
+
+        from = ::ActionMailer::Base.default[:from]
+        from.is_a?(String) ? from : nil
+      end
+
+      def backup_settings
+        @config.backup.nil? ? credential(:backup) : given(@config.backup) || nil
+      end
+
+      def google_settings
+        @config.google.nil? ? credential(:google) : given(@config.google) || nil
+      end
+
+      def credential(name)
+        value = @rails&.credentials&.dig(:railwatch_server, name)
+        value ? symbolize(value) : nil
+      rescue StandardError
+        # Unreadable credentials (no master key on this machine) are the app's
+        # problem to report; the server runs without these settings.
+        nil
+      end
+
+      # Action Mailer's names, as the mail gem reads them.
+      def smtp_env(s)
+        security = if s[:tls] || s[:ssl]
+          "tls"
+        elsif s[:enable_starttls] == false && s[:enable_starttls_auto] == false
+          "none"
+        else
+          "starttls"
+        end
+        {
+          "RAILWATCH_SMTP_ADDRESS" => s[:address],
+          "RAILWATCH_SMTP_PORT" => s[:port] || 25,
+          "RAILWATCH_SMTP_SECURITY" => security,
+          "RAILWATCH_SMTP_USERNAME" => s[:user_name],
+          "RAILWATCH_SMTP_PASSWORD" => s[:password]
+        }.compact
+      end
+
+      def backup_env(b)
+        missing = %i[endpoint bucket access_key_id secret_access_key].reject { b[_1] }
+        raise Invalid, "backup needs #{missing.join(', ')} (Railwatch::Server.config.backup or credentials.railwatch_server.backup)" if missing.any?
+
+        {
+          "RAILWATCH_BACKUP_S3_ENDPOINT" => b[:endpoint],
+          "RAILWATCH_BACKUP_S3_BUCKET" => b[:bucket],
+          "RAILWATCH_BACKUP_S3_ACCESS_KEY_ID" => b[:access_key_id],
+          "RAILWATCH_BACKUP_S3_SECRET_ACCESS_KEY" => b[:secret_access_key],
+          "RAILWATCH_BACKUP_S3_REGION" => b[:region],
+          "RAILWATCH_BACKUP_S3_PREFIX" => b[:prefix],
+          "RAILWATCH_BACKUP_INTERVAL_SECONDS" => b[:interval_seconds]
+        }.compact
+      end
+
+      def google_env(g)
+        raise Invalid, "google needs client_id and client_secret" unless g[:client_id] && g[:client_secret]
+
+        { "RAILWATCH_GOOGLE_CLIENT_ID" => g[:client_id], "RAILWATCH_GOOGLE_CLIENT_SECRET" => g[:client_secret] }
+      end
+
+      def symbolize(hash) = hash.to_h.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/railwatch/server/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Server
+    VERSION = "0.1.0"
+    # The published railwatch-rs commit the bundled binaries are built from
+    # (README, "The server side"); the Corresponding Source under AGPL-3.0.
+    RAILWATCH_RS = "d4c842c2f02e1cd56aeedb1e9ad1403313f0aed8"
+  end
+end

data/lib/railwatch/server.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "railwatch"
+require_relative "server/version"
+require_relative "server/configuration"
+require_relative "server/binary"
+require_relative "server/proxy_auth"
+require_relative "server/data_dir"
+require_relative "server/settings"
+require_relative "server/process"
+require_relative "server/relay"
+require_relative "server/proxy_handoff"
+
+module Railwatch
+  # The Railwatch server (the AGPL Rust binary, bundled) run next to this
+  # app: started by Puma's master (`plugin :railwatch_server`) or
+  # `bin/rails railwatch_server:start`, never inside a Puma worker; the
+  # dashboard proxied at /railwatch behind the app's own gate; the railwatch
+  # agent pointed at it.
+  module Server
+    class Error < StandardError; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+
+      def data_dir
+        DataDir.new(config.data_path)
+      end
+
+      def enabled?
+        config.enabled
+      end
+
+      # Whether the app reports somewhere of its own choosing, in which case
+      # the agent is left alone: a token set (RAILWATCH_TOKEN or the
+      # initializer), or the embedded store (`transport = :local`).
+      def agent_configured_elsewhere?
+        return true if Railwatch.config.local?
+        return false if Railwatch.config.ingest_url == config.local_url
+
+        Railwatch.config.token.to_s.strip != ""
+      end
+
+      # Whether this process starts the server, the only kind that may create
+      # the data dir: Puma with `plugin :railwatch_server` (its master and
+      # workers; under a bare `puma` the plugin is loaded before the app),
+      # `bin/rails server` (which loads the app before Puma reads its config),
+      # and `bin/rails railwatch_server:start`. Every other process (a job
+      # worker, a console, `assets:precompile` in a Dockerfile) only reads
+      # what the server's process wrote: provisioning in an asset build put
+      # the token and the dashboard's HMAC key in the image, shared by every
+      # volume made from it.
+      def serving?
+        return true if defined?(::Rails::Server)
+        return true if $LOADED_FEATURES.any? { _1.end_with?("/puma/plugin/railwatch_server.rb") }
+
+        rake_tasks.include?("railwatch_server:start")
+      end
+
+      # An image build (`SECRET_KEY_BASE_DUMMY=1 bin/rails assets:precompile`),
+      # or the database step a container runs before its server (Rails'
+      # docker-entrypoint: `bin/rails db:prepare`, then `rails server`, which
+      # provisions), where an unprovisioned data dir is expected and not
+      # worth a warning: on a fresh volume it was logged right before the
+      # server's process provisioned it.
+      def building?
+        ENV["SECRET_KEY_BASE_DUMMY"].to_s.strip != "" || rake_tasks.any? { _1.start_with?("assets:", "db:") }
+      end
+
+      def rake_tasks
+        defined?(::Rake.application) ? ::Rake.application.top_level_tasks : []
+      end
+
+      # Why this process could not provision the data dir (the dashboard
+      # says so), or nil.
+      attr_reader :provision_error
+
+      # Once per data dir, before the first server starts: `railwatch setup`
+      # and the proxy secret. Cheap after the first time (two files exist).
+      # Only from a process that starts the server (serving?).
+      #
+      # Tried once per process: under `bin/rails server` the Railtie and then
+      # the Puma plugin both get here before Puma listens, and a setup that
+      # failed or hit setup_timeout must not hold up the boot twice. The next
+      # start tries again.
+      def provision!(log: ->(m) { warn("[railwatch-server] #{m}") })
+        dir = data_dir
+        return dir if dir.provisioned?
+        raise @provision_error if @provision_error
+
+        app = defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : "App"
+        env = config.environment
+        # setup needs none of the app's settings (server.env is written at
+        # the first start, after this).
+        server_env = Process.new(config: config, data_dir: dir, binary: Binary.path, log: log).env.merge("RAILWATCH_ENV_FILE" => File::NULL)
+        done = dir.provision!(binary: Binary.path, env: server_env, app_name: app, env_name: env, timeout: config.setup_timeout)
+        log.call("provisioned #{dir.path}: #{done.join(', ')}") if done.any?
+        dir
+      rescue Error => e
+        @provision_error = e
+        raise
+      end
+
+      # The railwatch agent's settings for the bundled server. Called from
+      # the Railtie after the app's initializers have run.
+      def wire_agent!
+        return :disabled unless enabled? && config.wire_agent
+        return :configured_elsewhere if agent_configured_elsewhere?
+
+        dir = serving? ? provision! : data_dir
+        return building? ? :building : :not_provisioned unless dir.provisioned?
+
+        held = dir.environment
+        if held && held != config.environment
+          raise Error, "#{dir.path} holds the #{held} environment, and this is #{config.environment}: the agent is not wired, " \
+                       "so #{config.environment}'s telemetry does not land in #{held}'s. One data dir per environment: " \
+                       "unset RAILWATCH_SERVER_DATA_DIR (the default is storage/railwatch/<env>) or point it elsewhere"
+        end
+        token = dir.token
+        Railwatch.config.token = token
+        Railwatch.config.ingest_url = config.local_url
+        :wired
+      end
+
+      # The foreground supervisor for setups without Puma (Procfile,
+      # systemd, a container's second process): runs until TERM/INT.
+      def run!(log: ->(m) { $stdout.puts("[railwatch-server] #{m}"); $stdout.flush })
+        provision!(log: log)
+        server = Process.new(config: config, data_dir: data_dir, binary: Binary.path, log: log)
+        stopping = false
+        %w[TERM INT].each { |sig| trap(sig) { stopping = true } }
+        begin
+          loop do
+            sleep 0.5
+            # Checked after the sleep: a TERM during it must not start a
+            # server on the way out.
+            break if stopping
+
+            server.ensure_running
+          end
+        ensure
+          server.stop
+        end
+      end
+    end
+  end
+end
+
+require_relative "server/engine" if defined?(Rails::Engine)

data/lib/tasks/railwatch_server.rake

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+namespace :railwatch_server do
+  desc "Run the bundled Railwatch server in the foreground (for a Procfile or a supervisor; Puma users add `plugin :railwatch_server`)"
+  task start: :environment do
+    Railwatch::Server.run!
+  end
+
+  desc "Whether the bundled Railwatch server is running and the agent reports to it"
+  task status: :environment do
+    config = Railwatch::Server.config
+    dir = Railwatch::Server.data_dir
+    up = begin
+      Net::HTTP.get_response(URI("#{config.local_url}/up")).is_a?(Net::HTTPSuccess)
+    rescue SystemCallError, IOError
+      false
+    end
+    pid = dir.path.join("server.pid")
+    binary = begin
+      Railwatch::Server::Binary.path
+    rescue Railwatch::Server::Binary::NotFound => e
+      "MISSING: #{e.message.lines.first.strip}"
+    end
+    puts "binary       #{binary}"
+    puts "data dir     #{dir.path}#{' (not provisioned)' unless dir.provisioned?}"
+    puts "server       #{up ? 'UP' : 'DOWN'} on #{config.local_url}#{" (pid #{pid.read.split.first})" if pid.exist?}"
+    puts "dashboard    #{config.normalized_mount_path}"
+    puts "agent        " + (Railwatch::Server.agent_configured_elsewhere? ? "configured elsewhere (#{Railwatch.config.local? ? 'transport :local' : Railwatch.config.ingest_url})" :
+                             "reports to #{Railwatch.config.ingest_url}")
+    puts "log          #{dir.log_file}"
+    exit(up ? 0 : 1)
+  end
+end