rails_error_dashboard 0.14.4 → 0.16.0

data/lib/rails_error_dashboard/services/telegram_delivery.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RailsErrorDashboard
+  module Services
+    # One sendMessage call to the Telegram Bot API.
+    #
+    # WHY ONE PLACE: four senders post to Telegram (per-error notifications,
+    # storm and burst-summary messages, baseline alerts). The bot token is part
+    # of the URL -- https://api.telegram.org/bot<token>/sendMessage -- so any
+    # log line that quotes the URL, or an exception message that carries it,
+    # would leak the credential. Building the URL and redacting it live here
+    # so no caller has to remember either.
+    #
+    # Transport errors propagate, as in WebhookDelivery: every caller already
+    # rescues around its send and logs in its own words. Callers pass the
+    # message through .redact before logging it. A non-2xx answer from
+    # Telegram is not an exception; it is logged here with Telegram's own
+    # description ("Bad Request: chat not found"), which is the line an
+    # operator needs when the chat id is wrong.
+    class TelegramDelivery
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 10
+      USER_AGENT = "RailsErrorDashboard/1.0"
+      REDACTED = "[FILTERED]"
+
+      class << self
+        # Enabled and credentialled: the condition under which a dispatcher
+        # fires this channel.
+        def configured?(config = RailsErrorDashboard.configuration)
+          config.enable_telegram_notifications && credentials?(config)
+        end
+
+        # Token and chat id both present. The jobs check this rather than
+        # configured?, like the Discord job checks its URL and not the flag:
+        # the dispatcher decided to enqueue; the job only needs the means.
+        def credentials?(config = RailsErrorDashboard.configuration)
+          config.telegram_bot_token.present? && config.telegram_chat_id.present?
+        end
+
+        # POST a prepared sendMessage payload ({ text:, parse_mode:, ... }).
+        # chat_id is configuration, not content, so it is merged here rather
+        # than built into every payload.
+        #
+        # @return [HTTParty::Response, Net::HTTPResponse, nil] nil when there
+        #   are no credentials to send with
+        def post(payload, config: RailsErrorDashboard.configuration)
+          return nil unless credentials?(config)
+
+          body = payload.merge(chat_id: config.telegram_chat_id).to_json
+          headers = { "Content-Type" => "application/json", "User-Agent" => USER_AGENT }
+          url = send_message_url(config)
+
+          response =
+            if defined?(HTTParty)
+              HTTParty.post(url, body: body, headers: headers, timeout: READ_TIMEOUT)
+            else
+              uri = URI(url)
+              http = Net::HTTP.new(uri.host, uri.port)
+              http.use_ssl = uri.scheme == "https"
+              http.open_timeout = OPEN_TIMEOUT
+              http.read_timeout = READ_TIMEOUT
+              request = Net::HTTP::Post.new(uri.request_uri, headers)
+              request.body = body
+              http.request(request)
+            end
+
+          log_rejection(response)
+          response
+        end
+
+        # A plain or HTML-formatted message with nothing else to it (storm and
+        # burst summaries). parse_mode: nil sends the text verbatim, which is
+        # right for a sentence that may contain a "<" from an app name.
+        def send_message(text, parse_mode: nil, config: RailsErrorDashboard.configuration)
+          payload = { text: text, disable_web_page_preview: true }
+          payload[:parse_mode] = parse_mode if parse_mode
+
+          post(payload, config: config)
+        end
+
+        # The bot token replaced wherever it appears in +string+ (an exception
+        # message that quotes the URL, a response body that echoes it).
+        def redact(string, config: RailsErrorDashboard.configuration)
+          token = config.telegram_bot_token.to_s
+          text = string.to_s
+          return text if token.empty?
+
+          text.gsub(token, REDACTED)
+        end
+
+        # The URL with the token replaced, for log lines that need to say
+        # where the POST went.
+        def redacted_url(config = RailsErrorDashboard.configuration)
+          redact(send_message_url(config), config: config)
+        end
+
+        private
+
+        def send_message_url(config)
+          base = config.telegram_api_base_url.to_s.strip
+          base = "https://api.telegram.org" if base.empty?
+
+          "#{base.chomp('/')}/bot#{config.telegram_bot_token}/sendMessage"
+        end
+
+        # Telegram answers 4xx with {"ok":false,"error_code":400,"description":"..."}.
+        # The description names the real problem (chat not found, bot was
+        # blocked, can't parse entities), so it goes in the log verbatim; the
+        # body never contains the token, but it is redacted anyway.
+        def log_rejection(response)
+          code = response.code.to_i
+          return if (200..299).cover?(code)
+
+          description = begin
+            JSON.parse(response.body.to_s)["description"]
+          rescue JSON::ParserError, TypeError
+            nil
+          end
+
+          Rails.logger.error(
+            "[RailsErrorDashboard] Telegram API rejected the message (HTTP #{code}): " \
+            "#{redact(description || response.body.to_s[0, 200])}"
+          )
+        rescue => e
+          Rails.logger.error("[RailsErrorDashboard] Telegram API response could not be read: #{e.class}")
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/telegram_payload_builder.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "erb"
+
+module RailsErrorDashboard
+  module Services
+    # Pure algorithm: build the Telegram sendMessage payload for an error.
+    #
+    # No HTTP calls. Returns { text:, parse_mode:, disable_web_page_preview: };
+    # TelegramDelivery adds the chat id, which is configuration, not content.
+    #
+    # WHY HTML AND NOT MARKDOWNV2: MarkdownV2 reserves eighteen characters,
+    # every one of which must be escaped in every value, and a single
+    # unescaped "_" in a class name like Net::OpenTimeout_Retry fails the
+    # whole message with "can't parse entities". HTML mode needs only <, >
+    # and & escaped, which ERB::Util.html_escape does. Telegram allows <b>,
+    # <i>, <code>, <pre> and <a href>; nothing else is used here.
+    #
+    # @example
+    #   TelegramPayloadBuilder.call(error_log)
+    #   # => { text: "<b>🚨 Error Alert</b>\n...", parse_mode: "HTML", ... }
+    class TelegramPayloadBuilder
+      # Telegram rejects a text longer than this. The fields below are all
+      # bounded (message 500, location 100, the rest short), so a message
+      # built here is a few hundred characters; the fallback exists for the
+      # one pathological row and sends the same content unformatted rather
+      # than losing the notification to a parse error from a cut tag.
+      MAX_TEXT_LENGTH = 4096
+      MESSAGE_LENGTH = 500
+
+      # @param error_log [ErrorLog]
+      # @param locale [String] resolved by the enqueueing thread (P4-T1)
+      # @return [Hash] sendMessage payload without chat_id
+      def self.call(error_log, locale: I18nStore::DEFAULT_LOCALE)
+        unknown = NotificationHelpers.unknown(locale)
+        not_available = NotificationHelpers.not_available(locale)
+
+        lines = [
+          bold(NotificationHelpers.t("red.notifications.error_alert.heading", locale)),
+          # error_type is an exception class name -- verbatim, escaped.
+          bold(error_log.error_type),
+          code(NotificationHelpers.truncate_message(error_log.message, MESSAGE_LENGTH)),
+          "",
+          field(:application, NotificationHelpers.app_name(error_log), locale),
+          *environment_line(error_log, locale),
+          field(:platform, error_log.platform || unknown, locale),
+          field(:occurrences, error_log.occurrence_count.to_s, locale),
+          field(:controller, error_log.controller_name || not_available, locale),
+          field(:action, error_log.action_name || not_available, locale),
+          field(:first_seen, NotificationHelpers.format_datetime_or_na(error_log.first_seen_at, locale), locale),
+          # Backtrace content is diagnostic output -- never translated.
+          field(:location, NotificationHelpers.extract_first_backtrace_line(error_log.backtrace, locale: locale), locale, code: true),
+          "",
+          link(NotificationHelpers.dashboard_url(error_log),
+               NotificationHelpers.t("red.notifications.error_alert.view_in_dashboard", locale))
+        ]
+
+        html_payload(lines.join("\n"))
+      end
+
+      # "<b>Label:</b> value". The colon and the bold are Telegram markup, not
+      # language, so they stay here rather than in each translation (same
+      # reasoning as NotificationHelpers.field for Slack).
+      def self.field(label, value, locale, code: false)
+        rendered = code ? code(value) : escape(value)
+        "#{bold("#{NotificationHelpers.label(label, locale)}:")} #{rendered}"
+      end
+
+      def self.environment_line(error_log, locale)
+        return [] unless error_log.respond_to?(:environment) && error_log.environment.present?
+
+        [ field(:environment, error_log.environment, locale) ]
+      end
+
+      def self.bold(text)
+        "<b>#{escape(text)}</b>"
+      end
+
+      def self.code(text)
+        "<code>#{escape(text)}</code>"
+      end
+
+      def self.link(url, text)
+        %(<a href="#{escape(url)}">#{escape(text)}</a>)
+      end
+
+      # Plain String, not a SafeBuffer: these go into JSON, not a view.
+      def self.escape(value)
+        ERB::Util.html_escape(value.to_s).to_str
+      end
+
+      # The payload for an already-formatted HTML text, degrading to plain
+      # text when it would not fit.
+      def self.html_payload(text)
+        if text.length > MAX_TEXT_LENGTH
+          plain = CGI.unescapeHTML(text.gsub(/<[^>]+>/, ""))
+          return { text: plain[0, MAX_TEXT_LENGTH], disable_web_page_preview: true }
+        end
+
+        { text: text, parse_mode: "HTML", disable_web_page_preview: true }
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/webhook_delivery.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module RailsErrorDashboard
+  module Services
+    # One POST to a custom webhook URL (config.webhook_urls), signed when
+    # config.webhook_signing_secret is set.
+    #
+    # WHY ONE PLACE: three jobs post to webhook_urls (per-error notifications,
+    # storm/burst-summary messages, baseline alerts) and each carried its own
+    # copy of the HTTP code. The signature must be computed over the exact
+    # bytes on the wire, so the body is serialised once here and the same
+    # string is both signed and sent. Slack, Discord and PagerDuty keep their
+    # own senders: their payloads are not ours to sign.
+    #
+    # Errors propagate. Every caller already rescues around its send and logs
+    # in its own words (the specs pin those messages), so swallowing here would
+    # only hide the failure from them.
+    class WebhookDelivery
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 10
+      USER_AGENT = "RailsErrorDashboard/1.0"
+
+      class << self
+        # @param url [String]
+        # @param payload [Hash] serialised with #to_json
+        # @param headers [Hash{String => String}] merged over the defaults
+        # @return [HTTParty::Response, Net::HTTPResponse]
+        def post(url, payload, headers: {})
+          body = payload.to_json
+          all_headers = { "Content-Type" => "application/json", "User-Agent" => USER_AGENT }
+            .merge(headers)
+            .merge(signature_headers(body))
+
+          if defined?(HTTParty)
+            HTTParty.post(url, body: body, headers: all_headers, timeout: READ_TIMEOUT)
+          else
+            uri = URI(url)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            http.open_timeout = OPEN_TIMEOUT
+            http.read_timeout = READ_TIMEOUT
+            # request_uri, not path: a webhook URL that carries a query string
+            # (a token, a channel id) used to lose it on this branch.
+            request = Net::HTTP::Post.new(uri.request_uri, all_headers)
+            request.body = body
+            http.request(request)
+          end
+        end
+
+        # Signature headers for +body+, or {} when no secret is configured.
+        def signature_headers(body)
+          secret = RailsErrorDashboard.configuration.webhook_signing_secret
+          return {} if secret.blank?
+
+          WebhookSigner.headers_for(body, secret: secret)
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/webhook_signer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module RailsErrorDashboard
+  module Services
+    # HMAC-SHA256 signatures for OUTBOUND webhooks (the ones RED sends to
+    # config.webhook_urls). Inbound verification for GitHub/GitLab/Codeberg/
+    # Linear lives in WebhooksController and is unrelated.
+    #
+    # Scheme, chosen to match what Stripe, Svix and GitHub receivers already
+    # know how to check:
+    #
+    #   X-Error-Dashboard-Timestamp:     1718000000            (Unix seconds)
+    #   X-Error-Dashboard-Signature-256: sha256=<hex>
+    #
+    #   hex = HMAC_SHA256(secret, "#{timestamp}.#{raw_body}")
+    #
+    # The timestamp is part of the signed string, not just a header, so a
+    # captured request cannot be replayed later with a fresh timestamp. The
+    # receiver verifies the digest over the RAW body it received (before
+    # parsing JSON) and rejects timestamps outside its tolerance window.
+    #
+    # Pure functions, no I/O, nothing here can raise on well-typed input.
+    class WebhookSigner
+      TIMESTAMP_HEADER = "X-Error-Dashboard-Timestamp"
+      SIGNATURE_HEADER = "X-Error-Dashboard-Signature-256"
+      PREFIX = "sha256="
+
+      # Default replay window for verifiers, in seconds. Five minutes is the
+      # value Stripe and Svix document; it absorbs clock skew without leaving
+      # a captured request useful for long.
+      DEFAULT_TOLERANCE = 300
+
+      class << self
+        # Headers to merge into the outbound request.
+        #
+        # @param body [String] the exact bytes being sent
+        # @param secret [String]
+        # @param timestamp [Integer] Unix seconds; defaults to now
+        # @return [Hash{String => String}]
+        def headers_for(body, secret:, timestamp: Time.now.to_i)
+          ts = timestamp.to_i
+          {
+            TIMESTAMP_HEADER => ts.to_s,
+            SIGNATURE_HEADER => PREFIX + digest(body, secret: secret, timestamp: ts)
+          }
+        end
+
+        # @return [String] lowercase hex HMAC over "#{timestamp}.#{body}"
+        def digest(body, secret:, timestamp:)
+          OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp.to_i}.#{body}")
+        end
+
+        # Receiver-side check, offered so a Ruby receiver (and this gem's own
+        # specs and docs) need not re-derive the scheme.
+        #
+        # @param body [String] raw request body
+        # @param timestamp [String, Integer] value of X-Error-Dashboard-Timestamp
+        # @param signature [String] value of X-Error-Dashboard-Signature-256
+        # @param secret [String]
+        # @param tolerance [Integer, nil] max age in seconds; nil skips the window check
+        # @param now [Integer] injectable clock for tests
+        # @return [Boolean]
+        def valid?(body, timestamp:, signature:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now.to_i)
+          return false if secret.to_s.empty? || signature.to_s.empty?
+
+          ts = Integer(timestamp.to_s, 10)
+          return false if tolerance && (now - ts).abs > tolerance
+
+          expected = PREFIX + digest(body, secret: secret, timestamp: ts)
+          ActiveSupport::SecurityUtils.secure_compare(expected, signature.to_s)
+        rescue ArgumentError, TypeError
+          # A timestamp that is not an integer is a bad signature, not an error.
+          false
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/value_objects/occurrence_snapshot.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module ValueObjects
+    # The error as it looked at one occurrence: a read-only copy of the error
+    # row whose breadcrumbs, system health and variables are that occurrence's
+    # stored context. Every other field keeps the row's latest value.
+    #
+    # A real ErrorLog rather than a delegator, so every way a card reads a
+    # piece sees the occurrence's value: the instance-variables card goes
+    # through read_attribute and error.class.column_names, because
+    # Object#instance_variables shadows the attribute reader.
+    module OccurrenceSnapshot
+      # @param error [ErrorLog] the error the context belongs to
+      # @param context [ErrorOccurrenceContext] one of its occurrences' contexts
+      # @return [ErrorLog] read-only; a piece the occurrence did not capture is nil
+      def self.build(error, context)
+        pieces = Commands::RecordOccurrenceContext::PIECES.to_h { |piece| [ piece.to_s, context.read_attribute(piece) ] }
+        error.class.instantiate(error.attributes_before_type_cast.merge(pieces)).tap(&:readonly!)
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/version.rb

@@ -1,3 +1,3 @@
 module RailsErrorDashboard
-  VERSION = "0.14.4"
+  VERSION = "0.16.0"
 end

data/lib/rails_error_dashboard.rb

@@ -23,6 +23,7 @@ begin; require "turbo-rails"; rescue LoadError; end
 # Core library files
 require "rails_error_dashboard/value_objects/error_context"
 require "rails_error_dashboard/value_objects/llm_call_event"
+require "rails_error_dashboard/value_objects/occurrence_snapshot"
 require "rails_error_dashboard/integrations/o_tel"
 require "rails_error_dashboard/integrations/tracer"
 require "rails_error_dashboard/integrations/llm_span_processor"
@@ -44,6 +45,7 @@ require "rails_error_dashboard/services/localized_time_formatter"
 require "rails_error_dashboard/services/notification_helpers"
 require "rails_error_dashboard/services/slack_payload_builder"
 require "rails_error_dashboard/services/discord_payload_builder"
+require "rails_error_dashboard/services/telegram_payload_builder"
 require "rails_error_dashboard/services/pagerduty_payload_builder"
 require "rails_error_dashboard/services/webhook_payload_builder"
 require "rails_error_dashboard/services/baseline_alert_payload_builder"
@@ -58,6 +60,7 @@ require "rails_error_dashboard/services/source_code_reader"
 require "rails_error_dashboard/services/git_blame_reader"
 require "rails_error_dashboard/services/git_head_reader"
 require "rails_error_dashboard/services/solid_queue_config_check"
+require "rails_error_dashboard/services/repository_url"
 require "rails_error_dashboard/services/github_link_generator"
 require "rails_error_dashboard/services/cause_chain_extractor"
 require "rails_error_dashboard/services/environment_snapshot"
@@ -88,6 +91,13 @@ require "rails_error_dashboard/services/variable_serializer"
 require "rails_error_dashboard/services/local_variable_capturer"
 require "rails_error_dashboard/services/swallowed_exception_tracker"
 require "rails_error_dashboard/services/rack_attack_tracker"
+require "rails_error_dashboard/services/webhook_signer"
+require "rails_error_dashboard/services/webhook_delivery"
+require "rails_error_dashboard/services/telegram_delivery"
+require "rails_error_dashboard/services/resolution_callbacks"
+require "rails_error_dashboard/services/missing_translation_tracker"
+require "rails_error_dashboard/services/missing_translation_handler"
+require "rails_error_dashboard/services/active_storage_probe"
 require "rails_error_dashboard/services/ai_agent_classifier"
 require "rails_error_dashboard/services/crash_capture"
 require "rails_error_dashboard/services/diagnostic_dump_generator"
@@ -108,6 +118,7 @@ require "rails_error_dashboard/queries/error_cascades"
 require "rails_error_dashboard/queries/baseline_stats"
 require "rails_error_dashboard/queries/platform_comparison"
 require "rails_error_dashboard/queries/error_correlation"
+require "rails_error_dashboard/commands/record_occurrence_context"
 require "rails_error_dashboard/commands/log_error"
 require "rails_error_dashboard/commands/resolve_error"
 require "rails_error_dashboard/commands/create_issue"
@@ -136,6 +147,7 @@ require "rails_error_dashboard/commands/upsert_cascade_pattern"
 require "rails_error_dashboard/commands/upsert_baseline"
 require "rails_error_dashboard/commands/flush_swallowed_exceptions"
 require "rails_error_dashboard/commands/flush_rack_attack_events"
+require "rails_error_dashboard/commands/flush_missing_translations"
 require "rails_error_dashboard/commands/scrub_invalid_encoding"
 require "rails_error_dashboard/commands/backfill_resolved_at"
 require "rails_error_dashboard/queries/uninstall_plan"
@@ -158,6 +170,9 @@ require "rails_error_dashboard/queries/job_health_summary"
 require "rails_error_dashboard/queries/database_health_summary"
 require "rails_error_dashboard/queries/swallowed_exception_summary"
 require "rails_error_dashboard/queries/rack_attack_summary"
+require "rails_error_dashboard/queries/health_status"
+require "rails_error_dashboard/queries/missing_translation_summary"
+require "rails_error_dashboard/queries/boot_errors"
 require "rails_error_dashboard/queries/llm_health_summary"
 require "rails_error_dashboard/queries/release_timeline"
 require "rails_error_dashboard/error_reporter"
@@ -214,6 +229,19 @@ module RailsErrorDashboard
     remove_instance_variable(:@detected_git_sha) if defined?(@detected_git_sha)
   end
 
+  # The name errors are filed under: config.application_name, then the
+  # APPLICATION_NAME variable, then the Rails app's module name. Capture, the
+  # storm and event flushers, and the backfill all use this one chain, or the
+  # same app's rows end up under two Applications, or under none.
+  #
+  # @return [String]
+  def self.resolved_application_name
+    configuration.application_name.presence ||
+      ENV["APPLICATION_NAME"].presence ||
+      (defined?(Rails) && Rails.application&.class&.module_parent_name) ||
+      "Rails Application"
+  end
+
   # Register a plugin
   # @param plugin [Plugin] The plugin instance to register
   # @return [Boolean] True if registered successfully, false otherwise

data/lib/tasks/error_dashboard.rake

@@ -335,9 +335,8 @@ namespace :error_dashboard do
 
   desc "Backfill application_id for existing errors"
   task backfill_application: :environment do
-    app_name = ENV["APP_NAME"] || ENV["APPLICATION_NAME"] ||
-               (defined?(Rails) && Rails.application.class.module_parent_name) ||
-               "Legacy Application"
+    # APP_NAME overrides; otherwise the name capture files new errors under
+    app_name = ENV["APP_NAME"].presence || RailsErrorDashboard.resolved_application_name
 
     puts "\n" + "=" * 80
     puts "RAILS ERROR DASHBOARD - BACKFILL APPLICATION"