rails_discord_notifier 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c884f2a318d8b5a1af5e5b3af00ee14b2e886f00ae368dc3ad4ab84e27c2c39e
-  data.tar.gz: '047212981fcd047c7c80c206abf505410f49636d6f1488730de307352817b561'
+  metadata.gz: 1d11c790a2d82647c56a5c2e01a96e9be1d55dc89d5d7042c3b0f06baca195ff
+  data.tar.gz: 56f2cadcc53da57692a4e54ad203d5a818294f790bd3934fa514213df442b667
 SHA512:
-  metadata.gz: 15c983ae8a8288a2b36635184fcc43f9622610195d78aca315fbe27c43d6c48bce1903d0a3566a5cac24bb005d487a41ef44db199fca21801d1256987cdcbfe2
-  data.tar.gz: 4d9480a1e5db5f04eefdf014d7e6c1c5c917ecc6f3e42bf0a1dde5f073e122f4e8f305e503ffc56ee075a63067606ddf0dba2188eeb20574838d30eaa2de705b
+  metadata.gz: d07906322b8103001b7185d6594a55ea09e271fe1aca239cf69e1a93aa0e316a7c0440e4268b40be6476c97432c44861b8bc83bed4d51a8c2318e09bf23ff807
+  data.tar.gz: 6a411b50c842d47a2944c12fd89d1f1e27dab0dd0aa1bf8285e1bdb0a38e3c2651454f2310012a7f2a5d3b4fc8374bb62d4802d6f7d7d02ccc6856a8acad3145

data/CHANGELOG.md

@@ -1,5 +1,95 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-17
+
+This release fixes three defects that could leak credentials or silently drop
+error reports. Upgrading is strongly recommended.
+
+### Security
+
+- **Nested parameters are now redacted.** Filtering previously only inspected
+  top-level keys, so `user[password]` was posted to Discord in cleartext.
+  Filtering is now recursive via `ActiveSupport::ParameterFilter` and always
+  applies a superset of the host application's `config.filter_parameters`.
+- **Query strings are now redacted.** The `URL` field used the raw request URL,
+  so a secret in the query string (`?api_key=...`) was posted verbatim.
+- **Exception messages are scrubbed.** `token=…`, `password="…"` and
+  `Api_Key: …` fragments in an exception or `cause` message are replaced with
+  `[FILTERED]`, so a database connection error no longer posts its password.
+  Best effort only - a message is free text, unlike structured parameters.
+- **Webhook URLs are validated.** Only `https://` URLs on `discord.com` or
+  `discordapp.com` (or their subdomains) are accepted, which prevents a
+  misconfigured or hostile URL from receiving exception reports.
+
+### Fixed
+
+- **Reports are no longer silently dropped.** Payloads are truncated to
+  Discord's documented limits (1024 per field, 256 title, 4096 description,
+  6000 per embed). Oversized messages previously returned HTTP 400 and were
+  discarded, losing the error being reported.
+- **Delivery failures are now visible.** The HTTP response was previously
+  discarded; non-2xx responses are logged, and 429s are logged with `Retry-After`.
+- **Network timeouts are set** (2s open, 5s read, 5s write). Delivery previously
+  had no timeout at all and could hang a request thread indefinitely.
+- `Rails.logger` is no longer assumed to exist; the logger is configurable and
+  falls back to `$stderr`.
+- `require "time"` and `require "rack"` are now explicit, rather than relying on
+  another gem having loaded them.
+- `rails_discord_notifier/middleware` can be required on its own.
+
+### Added
+
+- **Background jobs, rake tasks and runners are now covered** via an
+  `ActiveSupport::ErrorReporter` subscriber (Rails 7.0+). Previously only
+  exceptions raised inside a web request were reported.
+- **Asynchronous delivery** (`config.async`, on by default), so reporting no
+  longer adds a blocking HTTP round-trip to a failing request. In-flight
+  deliveries are waited for at process exit, so reports from rake tasks and
+  runners are not lost when the process ends (`Notifier#flush`).
+- **Throttling** (`config.throttle_period`, 60s by default) collapses repeats of
+  the same error, so an error storm cannot flood the channel or trip Discord's
+  rate limit. The same exception object is never reported twice.
+- **An ignore list** (`config.ignored_exceptions`) pre-populated with routing,
+  `RecordNotFound` and other client-caused noise.
+- **`config.enabled`**, defaulting to off in development and test.
+- **`rails_discord_notifier test`** posts a sample report to your webhook and
+  prints Discord's response. The executable previously did nothing.
+- **Richer reports**: request ID, environment, release, hostname, the exception's
+  `cause`, and arbitrary extra fields via `config.context`.
+- `RailsDiscordNotifier.notify` for reporting an exception by hand.
+- `config.include_params`, `config.filter_parameters`, `config.backtrace_lines`,
+  `config.install_middleware`, `config.install_error_subscriber`.
+- RBS signatures for the public API.
+
+### Changed
+
+- **`configure` no longer raises** when `webhook_url` is missing. A missing
+  environment variable logs a warning and leaves the notifier disabled instead
+  of taking down application boot.
+- Configuration moved to a `Configuration` object. The previous flat accessors
+  (`RailsDiscordNotifier.webhook_url = ...`) still work.
+- Depends on `actionpack`, `activesupport`, `railties`, `rack` and `logger`
+  rather than the whole `rails` meta-gem. Minimum Rails is now 6.1.
+- The timestamp uses Discord's native embed `timestamp` instead of a field.
+- Backtraces default to 10 lines (was 5), trimmed to fit Discord's field limit.
+
+## [0.1.2] - 2025-06-10
+
+- Add `frozen_string_literal` comments throughout
+- Require MFA for RubyGems pushes
+- Move development dependencies out of the gemspec and into the Gemfile
+
+## [0.1.1] - 2025-06-03
+
+- Fix security and stability issues in the middleware
+
 ## [0.1.0] - 2025-05-28
 
 - Initial release

data/README.md

@@ -1,94 +1,175 @@
 # RailsDiscordNotifier
 
-**Send Rails exceptions to Discord via an incoming webhook**
+Send Rails exceptions to a Discord channel via an incoming webhook.
 
-RailsDiscordNotifier is a lightweight gem that captures unhandled exceptions in your Rails application and delivers detailed error reports directly to a Discord channel via a configurable webhook. You own the codebase and can customize the format, embed fields, and delivery settings to suit your needs.
-
-## Features
-
-- Middleware-based interception of all uncaught exceptions
-- Rich embed messages with exception class, message, backtrace, request method & URL, and timestamp
-- Configurable via environment variables and initializer
-- Safe error handling: notification failures are logged but don’t interrupt your app
+- Catches unhandled exceptions from **web requests** (Rack middleware) and from
+  **background jobs, rake tasks and runners** (`Rails.error` subscriber, Rails 7.0+)
+- **Redacts secrets** from params and query strings, using your app's own
+  `config.filter_parameters` plus a built-in list
+- **Never slows down or breaks your app**: delivery happens off the request
+  thread, with short timeouts, and every failure is logged rather than raised
+- **Never floods your channel**: repeats of the same error are collapsed, and
+  routing/404-style noise is ignored by default
 
 ## Installation
 
-Add the gem directly from RubyGems.org by including it in your Gemfile:
-
 ```ruby
-gem "rails_discord_notifier", "~> 0.1.0"
+gem "rails_discord_notifier", "~> 0.2"
 ```
 
-Then install:
-
 ```bash
 bundle install
+rails generate rails_discord_notifier:install
 ```
 
-Or use Bundler:
+Then set your webhook (Server Settings → Integrations → Webhooks → Copy URL):
 
 ```bash
-bundle add rails_discord_notifier
+export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…/…"
 ```
 
-## Usage
-
-Generate the default initializer in your Rails app:
+## Verify it works
 
 ```bash
-rails generate rails_discord_notifier:install
+bundle exec rails_discord_notifier test
 ```
 
-In `config/initializers/rails_discord_notifier.rb`, configure your webhook and options:
+This posts a real sample report to your webhook and prints what Discord said,
+so you find out now rather than during your next incident.
+
+## What a report looks like
+
+An embed titled with the failing request, followed by the details you need to
+find the error:
+
+```
+Exception in POST /orders
+ActiveRecord::RecordInvalid: Validation failed: Email can't be blank
+Caused by ArgumentError: missing email
+
+URL          https://shop.example.com/orders?utm_source=newsletter
+Controller   orders          Action   create
+Environment  production      Release  a1b2c3d
+Request ID   8f3c…           Host     web-01
+Params       { "order": { "email": "", "card_token": "[FILTERED]" } }
+Backtrace    `app/controllers/orders_controller.rb:42:in 'create'` …
+```
+
+## Configuration
+
+Everything is optional except `webhook_url`.
+
+| Option | Default | Description |
+|---|---|---|
+| `webhook_url` | `nil` | **Required.** Must be `https://` on `discord.com` or `discordapp.com`. Anything else leaves the notifier disabled. |
+| `enabled` | `false` in development and test, `true` elsewhere | Master switch. |
+| `username` | `"Error Bot"` | Bot display name in Discord. |
+| `avatar_url` | `nil` | Bot avatar image. |
+| `async` | `true` | Deliver on a separate thread so a failing request is not slowed down. |
+| `throttle_period` | `60` | Seconds to collapse repeats of the same error. `0` disables. |
+| `ignored_exceptions` | routing/404-style noise (see below) | Exception class names, matched including subclasses. |
+| `include_params` | `true` | Include filtered request parameters. |
+| `filter_parameters` | `[]` | Extra redaction matchers, unioned with your app's `config.filter_parameters` and the gem's built-in list. |
+| `backtrace_lines` | `10` | Backtrace lines to send, trimmed to fit Discord's field limit. |
+| `open_timeout` / `read_timeout` / `write_timeout` | `2` / `5` / `5` | Seconds. |
+| `environment` | `Rails.env`, else `RAILS_ENV`/`RACK_ENV` | Shown as a field, and decides the `enabled` default. |
+| `release` | `nil` | Shown as a field; handy for matching an error to a deploy. |
+| `context` | `nil` | Callable receiving the Rack env (`nil` outside a request), returning a hash of extra fields. |
+| `logger` | `Rails.logger`, else `$stderr` | Where delivery problems are logged. |
+| `install_middleware` | `true` | Install the Rack middleware. |
+| `install_error_subscriber` | `true` | Subscribe to `Rails.error` (Rails 7.0+). |
 
 ```ruby
 RailsDiscordNotifier.configure do |config|
-  # Discord webhook URL (required)
-  config.webhook_url = ENV.fetch("DISCORD_WEBHOOK_URL")
+  config.webhook_url = ENV.fetch("DISCORD_WEBHOOK_URL", nil)
+  config.release     = ENV.fetch("GIT_COMMIT_SHA", nil)
 
-  # Bot username (optional, defaults to ENV["ERROR_BOT_NAME"] or "Error Bot")
-  config.username    = ENV.fetch("ERROR_BOT_NAME", "Error Bot")
+  config.ignored_exceptions += %w[MyApp::HarmlessError]
 
-  # Bot avatar URL (optional)
-  # config.avatar_url = ENV.fetch("ERROR_BOT_AVATAR_URL", nil)
+  config.context = ->(env) { { "User" => env&.dig("warden")&.user&.id } }
 end
 ```
 
-Ensure the middleware is loaded (added automatically by the Railtie).
+A missing or malformed `webhook_url` logs a warning and disables the notifier.
+It will never take down application boot.
+
+### Ignored by default
+
+`ActionController::RoutingError`, `ActiveRecord::RecordNotFound`,
+`ActionController::InvalidAuthenticityToken`, `ActionController::UnknownFormat`,
+`ActionController::BadRequest`, `Rack::QueryParser::ParameterTypeError` and
+similar client-caused errors. See `Configuration::DEFAULT_IGNORED_EXCEPTIONS`
+for the full list. Replace it wholesale with `config.ignored_exceptions = [...]`
+or extend it with `+=`.
+
+## Secret redaction
+
+Parameters and query strings are filtered recursively with
+`ActiveSupport::ParameterFilter`, using the union of:
 
-Any uncaught exception in your controllers or middleware stack will now send an embed to Discord before re-raising.
+1. your application's `config.filter_parameters`,
+2. anything you add via `config.filter_parameters`, and
+3. the gem's built-in list (`passw`, `secret`, `token`, `_key`, `crypt`, `salt`,
+   `certificate`, `otp`, `ssn`, `signature`, `authorization`, `cookie`,
+   `session`, `credential`).
 
-## Configuration Options
+Because it is a union, enabling this gem can never redact less than your
+application already does. To send no parameters at all, set
+`config.include_params = false`.
 
-| Option        | Type   | Default                              | Description                        |
-|---------------|--------|--------------------------------------|------------------------------------|
-| `webhook_url` | String | **Required**                         | Discord incoming webhook URL       |
-| `username`    | String | fetched from ENV `ERROR_BOT_NAME` (defaults to `"Error Bot"`) | Bot display name                   |
-| `avatar_url`  | String | fetched from ENV `ERROR_BOT_AVATAR_URL` (defaults to `nil`)  | URL of the bot avatar image        |
+Exception messages are free text rather than structured parameters, so they get
+a best-effort scrub instead: `token=abc`, `password="x"` and `Api_Key: abc` style
+fragments are replaced with `[FILTERED]`. This catches the usual culprits (a
+database connection error carrying a password, an HTTP error carrying a URL with
+a token) but cannot be exhaustive the way parameter filtering is.
+
+Request bodies, headers and cookies are never sent.
+
+## Reporting an exception yourself
+
+```ruby
+rescue SomeError => e
+  RailsDiscordNotifier.notify(e, context: { "Tenant" => tenant.id })
+end
+```
+
+## How it gets your exceptions
+
+| Source | Mechanism | Requires |
+|---|---|---|
+| Controllers, routing, Rack apps | `RailsDiscordNotifier::Middleware` | any supported Rails |
+| Active Job, rake tasks, runners, `Rails.error.handle/record` | `RailsDiscordNotifier::ErrorSubscriber` | Rails 7.0+ |
+| Anything else | `RailsDiscordNotifier.notify` | — |
+
+The middleware observes and re-raises, so it never changes how your application
+handles errors. When both entry points see the same exception, it is reported once.
+
+Asynchronous deliveries still in flight are waited for at process exit, so a
+report from a rake task or `rails runner` is not lost when the process ends. Call
+`RailsDiscordNotifier.notifier.flush` to wait for them explicitly.
+
+## Compatibility
+
+Ruby 3.1+, Rails 6.1+. Every supported combination is exercised in CI.
 
 ## Development
 
-1. Checkout the repo
-2. Run `bin/setup` to install dependencies
-3. Run `bundle exec rspec` to execute the test suite
-4. Build and install locally:
-   ```bash
-   gem build rails_discord_notifier.gemspec
-   gem install ./rails_discord_notifier-#{RailsDiscordNotifier::VERSION}.gem
-   ```
-5. To release (public gem) update `lib/rails_discord_notifier/version.rb` and run:
-   ```bash
-   bundle exec rake release
-   ```
+```bash
+bin/setup                 # install dependencies
+bundle exec rspec         # run the test suite
+bundle exec rubocop       # lint
+bundle exec appraisal install && bundle exec appraisal rspec   # all Rails versions
+```
 
-## Contributing
+To release: update `lib/rails_discord_notifier/version.rb` and `CHANGELOG.md`,
+then `bundle exec rake release`.
 
-Bug reports and pull requests are welcome on GitHub:
-[https://github.com/gettinDrikkieWithIt/rails_discord_notifier](https://github.com/gettinDrikkieWithIt/rails_discord_notifier)
+## Contributing
 
-Please follow the project’s Code of Conduct.
+Bug reports and pull requests are welcome at
+<https://github.com/gettinDrikkieWithIt/rails_discord_notifier>.
+Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-This gem is available as open source under the terms of the MIT License.  
-See [LICENSE.txt](LICENSE.txt) for details.
+MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/rails_discord_notifier

@@ -1,3 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "rails_discord_notifier"
+
+exit RailsDiscordNotifier::CLI.new(ARGV).run

data/lib/generators/rails_discord_notifier/install_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators"
 
 module RailsDiscordNotifier

data/lib/generators/rails_discord_notifier/templates/rails_discord_notifier.rb

@@ -1,5 +1,48 @@
+# frozen_string_literal: true
+
 RailsDiscordNotifier.configure do |config|
-  config.webhook_url = ENV.fetch("DISCORD_WEBHOOK_URL")
-  config.username    = ENV.fetch("ERROR_BOT_NAME", "Error Bot")
-  # config.avatar_url = "https://example.com/avatar.png"
+  # Required. Must be an https://discord.com/api/webhooks/... URL.
+  # If it is missing or malformed the notifier stays disabled and logs a warning
+  # rather than breaking boot.
+  config.webhook_url = ENV.fetch("DISCORD_WEBHOOK_URL", nil)
+
+  # Appearance of the bot in Discord.
+  config.username = ENV.fetch("ERROR_BOT_NAME", "Error Bot")
+  # config.avatar_url = ENV.fetch("ERROR_BOT_AVATAR_URL", nil)
+
+  # Reporting is off in development and test by default.
+  # config.enabled = Rails.env.production?
+
+  # Deliver off the request thread. Set to false only if you need delivery to be
+  # synchronous (for example inside a test).
+  # config.async = true
+
+  # Collapse repeats of the same error for this many seconds. 0 disables it.
+  # config.throttle_period = 60
+
+  # Network timeouts, in seconds. Kept short so a slow Discord never slows you down.
+  # config.open_timeout  = 2
+  # config.read_timeout  = 5
+  # config.write_timeout = 5
+
+  # Client-caused noise that is ignored by default. Append your own:
+  # config.ignored_exceptions += %w[MyApp::HarmlessError]
+
+  # Request parameters are included, filtered with your app's
+  # config.filter_parameters plus the gem's own list. Turn them off entirely with:
+  # config.include_params = false
+  # config.filter_parameters += %w[national_id]
+
+  # Extra fields on every report. Receives the Rack env (nil outside a request).
+  # config.context = lambda do |env|
+  #   { "User" => env&.dig("warden")&.user&.id }
+  # end
+
+  # Shown as a field, handy for matching an error to a deploy.
+  # config.release = ENV.fetch("GIT_COMMIT_SHA", nil)
+
+  # Entry points. Middleware catches web requests; the Rails.error subscriber
+  # catches jobs, rake tasks and runners (Rails 7.0+).
+  # config.install_middleware = true
+  # config.install_error_subscriber = true
 end

data/lib/rails_discord_notifier/cli.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RailsDiscordNotifier
+  # `rails_discord_notifier test` posts a real message to your webhook and prints
+  # what Discord said. It answers the first question every user of this gem has:
+  # "is my webhook actually wired up?"
+  class CLI
+    USAGE = <<~TEXT
+      Usage: rails_discord_notifier <command> [options]
+
+      Commands:
+        test       Send a sample exception report to your Discord webhook
+        version    Print the gem version
+        help       Show this message
+
+      Options:
+        --webhook URL   Webhook to use (defaults to $DISCORD_WEBHOOK_URL)
+    TEXT
+
+    def initialize(argv, out: $stdout, env: ENV)
+      @argv = Array(argv)
+      @out  = out
+      @env  = env
+    end
+
+    # Returns a process exit status.
+    def run
+      case @argv.first
+      when "test"    then run_test
+      when "version" then print_version
+      when "help", nil then usage(0)
+      else usage(1)
+      end
+    end
+
+    private
+
+    def run_test
+      config = test_config
+      unless config.valid_webhook_url?
+        @out.puts(webhook_help)
+        return 1
+      end
+
+      @out.puts("Posting a sample exception report to Discord…")
+      deliver(config)
+    end
+
+    def deliver(config)
+      if Client.new(config).post(sample_payload(config))
+        @out.puts("Sent. Check your Discord channel.")
+        0
+      else
+        @out.puts("Discord did not accept the message. See the logged response above.")
+        1
+      end
+    end
+
+    def sample_payload(config)
+      exception = begin
+        raise "RailsDiscordNotifier test message - everything is wired up correctly"
+      rescue StandardError => e
+        e
+      end
+      Payload.new(exception, config: config).to_h
+    end
+
+    def test_config
+      Configuration.new.tap do |config|
+        config.webhook_url = webhook_url
+        config.enabled     = true
+        config.async       = false
+        config.logger      = Logger.new(@out)
+      end
+    end
+
+    def webhook_url
+      index = @argv.index("--webhook")
+      return @argv[index + 1] if index && @argv[index + 1]
+
+      @env["DISCORD_WEBHOOK_URL"]
+    end
+
+    def webhook_help
+      if webhook_url.to_s.strip.empty?
+        "No webhook configured. Set DISCORD_WEBHOOK_URL or pass --webhook URL."
+      else
+        "Invalid webhook: expected an https://discord.com/api/webhooks/... URL, got #{webhook_url}"
+      end
+    end
+
+    def print_version
+      @out.puts(VERSION)
+      0
+    end
+
+    def usage(status)
+      @out.puts(USAGE)
+      status
+    end
+  end
+end

data/lib/rails_discord_notifier/client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RailsDiscordNotifier
+  # Posts a prepared payload to the Discord webhook.
+  #
+  # Never raises: a notifier that breaks the request it is reporting on is worse
+  # than no notifier. Every failure is logged and swallowed.
+  class Client
+    SUCCESS = (200..299)
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Returns true when Discord accepted the message.
+    def post(payload)
+      uri = target_uri
+      return false if uri.nil?
+
+      accepted?(http(uri).request(build_request(uri, payload)))
+    rescue StandardError => e
+      config.logger.error("[RailsDiscordNotifier] delivery failed: #{e.class}: #{e.message}")
+      false
+    end
+
+    private
+
+    attr_reader :config
+
+    def target_uri
+      return nil unless config.valid_webhook_url?
+
+      URI.parse(config.webhook_url.to_s.strip)
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def http(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.use_ssl       = uri.scheme == "https"
+        http.open_timeout  = config.open_timeout
+        http.read_timeout  = config.read_timeout
+        http.write_timeout = config.write_timeout
+      end
+    end
+
+    def build_request(uri, payload)
+      Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json").tap do |request|
+        request.body = JSON.generate(payload)
+      end
+    end
+
+    # Logs whatever Discord said, and answers whether the message got through.
+    def accepted?(response)
+      return true if SUCCESS.cover?(response.code.to_i)
+
+      if response.code.to_i == 429
+        config.logger.warn(
+          "[RailsDiscordNotifier] rate limited by Discord, retry after #{response["Retry-After"] || "unknown"}s"
+        )
+      else
+        config.logger.error(
+          "[RailsDiscordNotifier] Discord rejected the message: HTTP #{response.code} #{response.body}"
+        )
+      end
+      false
+    end
+  end
+end