rails_discord_notifier 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bca289e9c14290633d82aff1222693bf779c7bfca2da23a8688d5fc4dc713077
-  data.tar.gz: 5c7e2a1b13f6fa5b028b95ce4ad9614a367b32cb3e13de98010ecb3d5a99ad6b
+  metadata.gz: 6527e49521148326dc463e191ed0fe51097c0625e7a09b89074615eb6b21f431
+  data.tar.gz: 3502ab8e704d8e0d995cdd17fb8d06fc36d9c6bae13122455cb33b013c9eff3c
 SHA512:
-  metadata.gz: 6669af0bcaa175df2396c6e0ea557db4f58db4aca8d794a450d822737b734187454a4bd09f507b585905a328d236d5ace2d03ed2717d33c4548c70628e8f2554
-  data.tar.gz: 87486bd08b6cbb223abebab6bf39d12b54dd4399fcf9ec37cae7d3f75eb889a12e45b32c18cc6df31635c39bee9a93785a29d7a9609073dad224e8ed27e8b7ff
+  metadata.gz: 2933ce5afd5ee5ae228d589c4c556fdde5dee1def8146a07204fc2230b80ccdbe89dbcbd055786af2389653518d8518e3de564d1dc3147851a8236a50f48ac5f
+  data.tar.gz: 01a951280d579cac677a76e6e2120b9fb30b4c8c94fd584459423a0b4e1b7d65e8ab178584ef4e9b41178a216a3b010d2a0d34950d481e0ef341d28050609bc5

data/CHANGELOG.md

@@ -1,5 +1,144 @@
+# 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.3.0] - 2026-10-28
+
+### Added
+
+- **Google Chat support.** Set `webhook_url` to a Google Chat incoming webhook
+  (`https://chat.googleapis.com/v1/spaces/…`) and reports are sent as a Google
+  Chat text message instead of a Discord embed. They are redacted and size-limited
+  the same way, and fit within Google Chat's 32,000 byte limit. `username` and
+  `avatar_url` don't apply to Google Chat.
+- `rails_discord_notifier test` also reads `GOOGLE_CHAT_WEBHOOK_URL`.
+
+### Security
+
+- **Chat markup in reports is defused for Google Chat.** Attacker-influenced
+  text (exception message, path, User-Agent) can no longer produce an
+  `<users/all>` mention or a `<url|text>` masked link.
+- **The CLI no longer echoes a rejected webhook URL.** The URL is a credential
+  and the output may land in CI logs.
+- **Message scrubbing can no longer stall the process.** On Ruby 3.1 the scrubber
+  regex took cubic time, so a request that put about 4 KB of text into an
+  exception message held the interpreter lock for about 13 seconds. Matching is
+  now linear on every supported Ruby.
+- **The scrubber catches more credential shapes:** `Authorization` values with
+  the `Bearer`, `Basic`, `Token`, `Digest` or `Negotiate` scheme, JSON and
+  `inspect`-style quoted keys (`"password":"x"`, `"password" => "x"`), and
+  passwords in URLs (`redis://:pw@host`, `postgres://user:pw@host`).
+- **`Rails.error` context and `config.context` are now filtered** with the same
+  parameter filter as request params, including nested values and
+  `ActionController::Parameters`. They were previously sent verbatim. If the
+  filter itself raises, the context is left out and a warning is logged.
+- **Delivery threads are capped at 10 in flight.** Before, an error storm
+  against a slow webhook started one thread per report without limit. Reports
+  beyond the cap are dropped and logged.
+
+### Fixed
+
+- **Text that isn't valid UTF-8 no longer drops the report.** A binary header
+  value (which Rack passes through) or a stray byte in an exception message made
+  JSON encoding fail. Invalid bytes are now replaced with `�`, and text in other
+  encodings (e.g. Windows-1252) is converted.
+
+### Changed
+
+- **Repeats are recognised by route, not path.** The throttle fingerprint uses
+  controller and action instead of the raw request path, so `/users/1`,
+  `/users/2` and `/users/1.json` hitting the same bug count as one error.
+- Delivery log lines no longer name Discord ("webhook rejected the message",
+  "rate limited by the webhook"). Update any log alerts that match the old text.
+
+## [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,222 @@
 # RailsDiscordNotifier
 
-**Send Rails exceptions to Discord via an incoming webhook**
+Send Rails exceptions to a Discord channel or a Google Chat space via an
+incoming webhook.
+
+- 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
 
-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.
+## Installation
 
-## Features
+```ruby
+gem "rails_discord_notifier", "~> 0.3"
+```
 
-- 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
+```bash
+bundle install
+rails generate rails_discord_notifier:install
+```
 
-## Installation
+Then set your webhook. The gem works out which service it is from the URL.
 
-Add the gem directly from RubyGems.org by including it in your Gemfile:
+**Discord:** Server Settings → Integrations → Webhooks → Copy URL.
 
-```ruby
-gem "rails_discord_notifier", "~> 0.1.0"
+```bash
+export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…/…"
 ```
 
-Then install:
+**Google Chat:** open the space → Apps & integrations → Webhooks → Add webhook,
+then copy the URL. Your Workspace admin must allow incoming webhooks.
 
 ```bash
-bundle install
+export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/…/messages?key=…&token=…"
 ```
 
-Or use Bundler:
+The generated initializer reads `DISCORD_WEBHOOK_URL`, then
+`GOOGLE_CHAT_WEBHOOK_URL`. Treat either URL as a password: anyone holding it
+can post to your channel.
+
+## Verify it works
 
 ```bash
-bundle add rails_discord_notifier
+bundle exec rails_discord_notifier test
 ```
 
-## Usage
+This posts a real sample report to your webhook and prints what the service
+said, so you find out now rather than during your next incident. It reads
+`DISCORD_WEBHOOK_URL`, then `GOOGLE_CHAT_WEBHOOK_URL`, or takes `--webhook URL`
+(which ends up in your shell history, so prefer the environment variable).
 
-Generate the default initializer in your Rails app:
+## What a report looks like
 
-```bash
-rails generate rails_discord_notifier:install
+In Discord, 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'` …
 ```
 
-In `config/initializers/rails_discord_notifier.rb`, configure your webhook and options:
+In Google Chat, the same details as a single text message, with the params and
+backtrace in code blocks. Chat has no per-message sender name or avatar: those
+come from the name and avatar you gave the webhook when you created it.
+
+## Configuration
+
+Everything is optional except `webhook_url`.
+
+| Option | Default | Description |
+|---|---|---|
+| `webhook_url` | `nil` | **Required.** Must be `https://` on `discord.com`, `discordapp.com` or `chat.googleapis.com`. Anything else leaves the notifier disabled. |
+| `enabled` | `false` in development and test, `true` elsewhere | Master switch. |
+| `username` | `"Error Bot"` | Bot display name. Discord only. |
+| `avatar_url` | `nil` | Bot avatar image. Discord only. |
+| `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 the message size 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:
+
+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`).
 
-Any uncaught exception in your controllers or middleware stack will now send an embed to Discord before re-raising.
+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`. The same filter applies to extra fields from
+`config.context` and from `Rails.error` context.
 
-## Configuration Options
+Exception messages are free text rather than structured parameters, so they get
+a best-effort scrub instead: `token=abc`, `password="x"`, `Api_Key: abc`,
+`"password":"x"`, `Authorization: Bearer abc` and `redis://:password@host` 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.
 
-| 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        |
+Path segments are sent as they are. If a route puts a secret in the path (for
+example `/password_resets/:token`), move it to the query string or the body,
+where it is filtered.
+
+Request bodies, headers and cookies are never sent.
+
+In Google Chat, text like `<users/all>` or `<https://…|click here>` would become
+an @all mention or a disguised link. Since anyone who can make your app raise
+controls part of the report (the path, the User-Agent, often the exception
+message), the gem defuses these with an invisible zero-width space after each
+`<`. The report looks the same but can't ping the space or hide a link. The
+space is still there if you copy text out of the report (for example
+``in `<main>'`` from a backtrace), so retype the `<` if a search comes up empty.
+
+## Google Chat rate limits
+
+Google Chat accepts about one message per second per space, shared with
+anything else posting there. Repeats of the same error are already collapsed
+(`throttle_period`), but a burst of *different* errors beyond that rate is
+rejected by Google with HTTP 429. Those rejections are logged, not retried.
+
+## 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.
+
+"The same error" means the same exception class, raised from the same line, on
+the same controller action. So `/orders/1` and `/orders/2` failing the same way
+count as one error for `throttle_period`. At most 10 reports are delivered at
+once; during a storm, anything beyond that is dropped with a log line rather
+than starting more threads.
+
+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,50 @@
+# 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. A Discord (https://discord.com/api/webhooks/...) or Google Chat
+  # (https://chat.googleapis.com/v1/spaces/...) webhook URL. The message format
+  # follows the URL. If it is missing or malformed the notifier stays disabled and
+  # logs a warning rather than breaking boot. Keep it out of source control.
+  config.webhook_url = ENV.fetch("DISCORD_WEBHOOK_URL", nil).presence || ENV.fetch("GOOGLE_CHAT_WEBHOOK_URL", nil)
+
+  # Appearance of the bot in Discord. Google Chat uses the name and avatar set on
+  # the webhook itself.
+  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 webhook 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,106 @@
+# frozen_string_literal: true
+
+module RailsDiscordNotifier
+  # `rails_discord_notifier test` posts a real message to your webhook and prints
+  # what the service 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 or Google Chat webhook
+        version    Print the gem version
+        help       Show this message
+
+      Options:
+        --webhook URL   Webhook to use (defaults to $DISCORD_WEBHOOK_URL,
+                        then $GOOGLE_CHAT_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 your webhook…")
+      deliver(config)
+    end
+
+    def deliver(config)
+      if Client.new(config).post(sample_payload(config))
+        @out.puts("Sent. Check your channel.")
+        0
+      else
+        @out.puts("The webhook 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.build(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]
+
+      # Blank counts as unset: deploy templates often export unused variables as "".
+      @env.values_at("DISCORD_WEBHOOK_URL", "GOOGLE_CHAT_WEBHOOK_URL").find { |url| !url.to_s.strip.empty? }
+    end
+
+    # Never echoes the URL: it is a credential and this may be a CI log.
+    def webhook_help
+      if webhook_url.to_s.strip.empty?
+        "No webhook configured. Set DISCORD_WEBHOOK_URL or GOOGLE_CHAT_WEBHOOK_URL, or pass --webhook URL."
+      else
+        "Invalid webhook: expected an https://discord.com/api/webhooks/... " \
+          "or https://chat.googleapis.com/v1/spaces/... URL"
+      end
+    end
+
+    def print_version
+      @out.puts(VERSION)
+      0
+    end
+
+    def usage(status)
+      @out.puts(USAGE)
+      status
+    end
+  end
+end