railwatch 0.1.0

data/lib/railwatch/secret_safety.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Railwatch
+  # Read-only Git checks used by the installer and doctor. Tokens are never
+  # returned in diagnostics: callers get a path or a short prefix only.
+  module SecretSafety
+    TOKEN_PATTERN = /\blt_[A-Za-z0-9_-]{6,}\b/
+    TOKEN_FILE_GLOBS = [ ".env", ".env.*", ".kamal/secrets", "config/deploy.yml",
+                         "config/initializers/*.rb" ].freeze
+
+    module_function
+
+    def token_preview(token)
+      value = token.to_s
+      return "unset" if value.empty?
+
+      "#{value.byteslice(0, 6)}... (#{value.length} chars)"
+    end
+
+    def git_tracked?(path, root: Dir.pwd)
+      _output, status = git(root, "ls-files", "--error-unmatch", "--", path)
+      status.success?
+    end
+
+    def git_ignored?(path, root: Dir.pwd)
+      _output, status = git(root, "check-ignore", "-q", "--", path)
+      status.success?
+    end
+
+    def tracked_plaintext_token_files(root: Dir.pwd)
+      output, status = git(root, "ls-files", "-z", "--", *TOKEN_FILE_GLOBS)
+      return [] unless status.success?
+
+      output.split("\0").filter_map do |relative|
+        next if relative.empty?
+
+        path = File.join(root.to_s, relative)
+        next unless File.file?(path) && !File.symlink?(path)
+        next unless File.binread(path).match?(TOKEN_PATTERN)
+
+        relative
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    def git(root, *arguments)
+      output, _error, status = Open3.capture3("git", "-C", root.to_s, *arguments)
+      [ output, status ]
+    rescue SystemCallError
+      [ "", NullStatus.new ]
+    end
+    private_class_method :git
+
+    class NullStatus
+      def success? = false
+    end
+    private_constant :NullStatus
+  end
+end

data/lib/railwatch/sessions.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Server-side sessions, the fallback half of release health. Every request
+  # that resolves a user or carries the browser client's session id updates
+  # one in-memory entry per session key; a background thread ships each entry
+  # as a `session` record every config.session_flush_interval and retires the
+  # ones idle for longer than config.session_timeout.
+  #
+  # Same thread shape as Railwatch::Health -- one thread per process, parked on
+  # a ConditionVariable, re-armed in every forked child -- and started from
+  # the same engine initializer.
+  #
+  # The browser client emits `session` records of its own through the beacon
+  # carrying the same id (it sets the cookie this reads), so a session seen
+  # from both ends dedupes on the platform instead of counting twice.
+  module Sessions
+    # Only a request creates a session, so a worker/console/rake process has
+    # nothing to flush and does not start a thread.
+    ROLES = %w[web].freeze
+    # A process that keeps meeting new keys -- an app that sets no cookie
+    # being crawled, say -- must not grow without bound. Oldest first, and
+    # counted so the drop is visible rather than silent.
+    MAX_KEYS = 10_000
+    # The cookie the browser client sets (railwatch.ts), so every request from
+    # a tab carries the id its beacons already use.
+    COOKIE = /(?:\A|;\s*)railwatch_session=([^;]+)/
+    KEY_LIMIT = 64
+
+    @mutex = Mutex.new
+    @wakeup = ConditionVariable.new
+    @sessions = {}
+    @dropped = 0
+    @thread = nil
+    @pid = nil
+    @stopping = false
+
+    module_function
+
+    # Session keys dropped because the process was already tracking MAX_KEYS.
+    def dropped
+      @dropped
+    end
+
+    # Records one finished request against its session. A request that is
+    # neither authenticated nor carrying a session id is not a session, and
+    # returns here having touched nothing.
+    def touch(exe, env, status)
+      key = key_for(exe, env) or return nil
+      exe.session_key = key
+      now = Clock.now
+      @mutex.synchronize do
+        entry = @sessions[key] ||= begin
+          drop_oldest if @sessions.size >= MAX_KEYS
+          { started_at: now, last_seen_at: now, requests: 0, errors: 0, crashed: false, user: exe.user_id }
+        end
+        entry[:last_seen_at] = now
+        entry[:requests] += 1
+        entry[:errors] += 1 if status.to_i >= 500 || exe.counters[:exceptions].positive?
+        entry[:crashed] = true if exe.session_crashed
+        entry[:user] ||= exe.user_id
+      end
+    end
+
+    # Ships one record per tracked session. Keys idle for longer than
+    # config.session_timeout ship with `ended` and are dropped; the rest stay
+    # and are shipped again next interval, so a long session is one row per
+    # interval that the platform dedupes by id.
+    def flush
+      now = Clock.now
+      timeout = Railwatch.config.session_timeout
+      due = @mutex.synchronize do
+        rows = @sessions.map { |key, entry| [ key, entry, now - entry[:last_seen_at] > timeout ] }
+        rows.each { |key, _entry, ended| @sessions.delete(key) if ended }
+        rows
+      end
+      due.each { |key, entry, ended| emit(key, entry, ended) }
+    end
+
+    # The browser client's id when the request carries one -- so the two
+    # halves of the same session share a key -- else the resolved user.
+    def key_for(exe, env)
+      id = env["HTTP_X_RAILWATCH_SESSION"] || COOKIE.match(env["HTTP_COOKIE"])&.[](1)
+      return id[0, KEY_LIMIT] unless id.nil? || id.empty?
+
+      user = exe.user_id
+      user && "user:#{user}"[0, KEY_LIMIT]
+    end
+
+    def emit(key, entry, ended)
+      Railwatch.record(:session, group: Record.group_hash(key),
+        id: key, source: "server", status: status_of(entry),
+        started_at: entry[:started_at], duration: ((entry[:last_seen_at] - entry[:started_at]) * 1_000_000).round,
+        requests: entry[:requests], errors: entry[:errors], ended: ended, user: entry[:user])
+    rescue StandardError => e
+      Railwatch.debug { "session flush failed: #{e.class}: #{e.message}" }
+      nil
+    end
+
+    def status_of(entry)
+      return "crashed" if entry[:crashed]
+      entry[:errors].positive? ? "errored" : "ok"
+    end
+
+    def drop_oldest
+      @sessions.shift
+      @dropped += 1
+    end
+
+    # --- background thread (mirrors Railwatch::Health) ------------------------
+
+    def start!
+      return unless Railwatch.enabled? && Railwatch.config.track_sessions
+      return if defined?(Rails) && Rails.env.test?
+      return unless ROLES.include?(Subscribers::ProcessInfo.role)
+      return if @thread&.alive? && @pid == Process.pid
+
+      @mutex.synchronize do
+        return if @thread&.alive? && @pid == Process.pid
+
+        @pid = Process.pid
+        @stopping = false
+        @thread = Thread.new { run }
+        @thread.name = "railwatch-sessions"
+        @thread.abort_on_exception = false
+        @thread.report_on_exception = false
+      end
+    end
+
+    # A forked child inherits a dead thread, the parent's pid, and the
+    # parent's half-finished session map; both are replaced here.
+    def restart_after_fork!
+      @mutex = Mutex.new
+      @wakeup = ConditionVariable.new
+      @thread = nil
+      @pid = nil
+      @stopping = false
+      @sessions = {}
+      @dropped = 0
+      start!
+    end
+
+    def stop!
+      return unless @thread
+
+      @stopping = true
+      @mutex.synchronize { @wakeup.signal }
+      @thread.join(1)
+      @thread = nil
+      # Shutting down without this would throw away every session opened
+      # since the last interval, on every deploy.
+      flush
+    end
+
+    def run
+      until @stopping
+        @mutex.synchronize { @wakeup.wait(@mutex, Railwatch.config.session_flush_interval) unless @stopping }
+        flush unless @stopping
+      end
+    end
+  end
+end

data/lib/railwatch/source_maps.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "pathname"
+require "json"
+
+module Railwatch
+  # Upload locally built source maps to private telemetry storage. This runs
+  # during release preparation; it never follows map URLs or HTTP redirects.
+  class SourceMaps
+    MAX_BYTES = 10 * 1024 * 1024
+
+    def initialize(config)
+      @config = config
+    end
+
+    def upload(directory: "public", delete: false)
+      raise ArgumentError, "RAILWATCH_TOKEN is not set" if @config.token.to_s.empty?
+      raise ArgumentError, "RAILWATCH_DEPLOY (or KAMAL_VERSION) is not set" if @config.deploy.to_s.empty?
+      raise ArgumentError, "plain HTTP ingest is disabled; use HTTPS or set RAILWATCH_ALLOW_HTTP=true" unless @config.ingest_url_allowed?
+      root = Pathname.new(directory).realpath
+      files = Dir[root.join("**/*.map").to_s].sort.select { |path| File.file?(path) }
+      raise ArgumentError, "no .map files found in #{root}" if files.empty?
+      files.each do |path|
+        file = Pathname.new(path)
+        unless file.realpath.to_s.start_with?(root.to_s + File::SEPARATOR) && !file.symlink?
+          raise ArgumentError, "source map must be a regular file within the upload directory"
+        end
+        data = File.binread(file, MAX_BYTES + 1)
+        raise ArgumentError, "source map exceeds 10 MiB: #{file.basename}" if data.bytesize > MAX_BYTES
+        filename = file.relative_path_from(root).to_s.delete_suffix(".map")
+        upload_file(filename, data)
+        File.delete(file) if delete
+      end
+      files.size
+    end
+
+    private
+
+    def upload_file(filename, data)
+      uri = URI.join(@config.ingest_url, "/ingest/sourcemaps")
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{@config.token}"
+      request["Content-Type"] = "application/octet-stream"
+      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) }
+      unless response.is_a?(Net::HTTPSuccess)
+        raise "Source map upload failed (HTTP #{response.code}) for #{filename}"
+      end
+      result = JSON.parse(response.body)
+      unless result["ok"] == true && result["filename"] == filename && result["bytes"] == data.bytesize
+        raise "Source map upload was not acknowledged for #{filename}"
+      end
+    end
+  end
+end

data/lib/railwatch/spec_helper.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Test helpers for apps using Railwatch. Add to spec/rails_helper.rb:
+#   require "railwatch/spec_helper"
+#   config.include Railwatch::SpecHelper
+#
+# `require "railwatch/rspec"` does both of those and adds the block matchers;
+# `require "railwatch/minitest"` is the Minitest equivalent.
+module Railwatch
+  module SpecHelper
+    # Raised instead of silently reporting zero records, which would turn a
+    # CI performance gate into a no-op that always passes.
+    class Disabled < StandardError; end
+
+    class MemoryTransport
+      attr_reader :batches
+      def initialize = @batches = []
+      def deliver(records, dropped: 0, batch_id: nil)
+        @batches << records
+        Transport::Http::Result.new(ok: true, status: 200, accepted: records.size, rejected: 0)
+      end
+      def ping = true
+    end
+
+    def railwatch_records(type = nil)
+      Railwatch.flush
+      all = railwatch_transport.batches.flatten
+      type ? all.select { |r| r[:t] == type.to_s } : all
+    end
+
+    def railwatch_transport
+      @railwatch_transport ||= begin
+        transport = MemoryTransport.new
+        Railwatch.instance_variable_set(:@reporter, Railwatch::Reporter.new(Railwatch.config, transport: transport))
+        transport
+      end
+    end
+
+    # Runs the block and returns only the records it produced. Backs every
+    # matcher in railwatch/rspec and every assertion in railwatch/minitest.
+    #
+    # Child records sit on their execution until it finishes, so there are
+    # three cases. A block that opens and closes its own execution (a request
+    # spec's `get "/widgets"`) needs no help — its records reach the transport
+    # by the time the block returns. A block with nothing executing (a model or
+    # service spec) is wrapped in an execution here. A block running *inside*
+    # an already-open execution has its records read straight off that
+    # execution's buffer, since nothing will flush them until it ends.
+    def railwatch_capture
+      unless Railwatch.enabled?
+        raise Disabled, "Railwatch is disabled (config.enabled is false or config.token is blank), " \
+                        "so this block would always look empty. Set RAILWATCH_TOKEN in your test environment."
+      end
+
+      Railwatch.flush
+      batch_offset = railwatch_transport.batches.size
+      buffered = with_railwatch_execution { yield }
+      Railwatch.flush
+      railwatch_transport.batches[batch_offset..].flatten + buffered
+    end
+
+    private
+
+    # Returns the records buffered on a pre-existing execution by the block
+    # (empty when this opened its own, since finishing it ships them).
+    def with_railwatch_execution
+      exe = Railwatch.execution
+      if exe
+        offset = exe.records.size
+        yield
+        exe.records[offset..] || []
+      else
+        # :command is the closest of Execution::SOURCES to a test body.
+        # Sampling is forced on so a fractional sample rate in the app's test
+        # config can't quietly turn an assertion into one that never fires.
+        Railwatch.start_execution(source: :command, sample_kind: :requests).sampled = true
+        begin
+          yield
+        ensure
+          # No parent type: the wrapper itself must not add a `command` record.
+          Railwatch.finish_execution
+        end
+        []
+      end
+    end
+
+    # --- shared by railwatch/rspec and railwatch/minitest -------------------------
+
+    SQL_PREVIEW_CHARS = 120
+
+    class << self
+      # Exactly one of exactly:/at_most:/at_least: describes the bound.
+      def count_satisfied?(count, exactly: nil, at_most: nil, at_least: nil)
+        bound = check_bound(exactly: exactly, at_most: at_most, at_least: at_least)
+        case bound.first
+        when :exactly then count == bound.last
+        when :at_most then count <= bound.last
+        else count >= bound.last
+        end
+      end
+
+      def bound_description(exactly: nil, at_most: nil, at_least: nil)
+        kind, value = check_bound(exactly: exactly, at_most: at_most, at_least: at_least)
+        "#{kind.to_s.tr('_', ' ')} #{value}"
+      end
+
+      # Every failure message ends in the offending records, so CI output says
+      # which queries to go and fix rather than just "expected 5, got 9".
+      def sql_lines(records)
+        lines(records) { |r| truncate(r[:sql]) }
+      end
+
+      def n_plus_one_lines(records)
+        lines(records) { |r| "#{r[:count]}x #{truncate(r[:sql])}#{" at #{r[:source]}" if r[:source]}" }
+      end
+
+      def outgoing_lines(records)
+        lines(records) { |r| "#{r[:method]} #{truncate(r[:url])}" }
+      end
+
+      def exception_lines(records)
+        lines(records) { |r| "#{r[:class]}: #{truncate(r[:message])}" }
+      end
+
+      def record_names(records, key)
+        records.map { |r| r[key].to_s }
+      end
+
+      def truncate(value)
+        value.to_s.gsub(/\s+/, " ").strip[0, SQL_PREVIEW_CHARS]
+      end
+
+      private
+
+      def lines(records)
+        return " (none)" if records.empty?
+        records.each_with_index.map { |r, i| "\n  #{i + 1}. #{yield(r)}" }.join
+      end
+
+      def check_bound(exactly:, at_most:, at_least:)
+        given = { exactly: exactly, at_most: at_most, at_least: at_least }.compact
+        raise ArgumentError, "pass exactly one of exactly:, at_most:, at_least:" unless given.size == 1
+        given.first
+      end
+    end
+  end
+end