bard-exception_notification 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a24301e4be9951e47b9c36677feddb1e821b1f2ce800c9981267cea23c3b62a7
+  data.tar.gz: 6ba33cc979646e6291832a1d7e00e78db3006773bda7dfcb25bd88d864eba420
+SHA512:
+  metadata.gz: 86e2d68724422b51e9851d22c940fb9a57b59539f70815eb200e3f0776bbdf91b1ceda1dfa8899e4433b07942ac4d6ef838c9aaca1b3ebfb185dcbccc000d814
+  data.tar.gz: bd446d6a565fba957c8f82b4dadf318c78304c0ee56e1f182f672e07b252ba2172b96e92ba826bfc20910db6d5b26e70d6d175d1278d6d4756848e24fc8bb39b

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CLAUDE.md

@@ -0,0 +1,30 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A Rails engine gem that gives every BARD-managed Rails app the same exception_notification setup: email notifications for web requests, ActiveJob, rake tasks and `ActionController::Live`, plus `rake exception_notification:test` to verify delivery end to end in a deployed app.
+
+## Commands
+
+- Full suite (fast, under a second): `bundle exec rspec` (also `bundle exec rake`)
+- Single file / example: `bundle exec rspec spec/bard/exception_notification_spec.rb:42`
+- Rails matrix (as CI runs it, Ruby 3.2–4.0 × Rails 7.2/8.0/8.1): `bundle exec appraisal install`, then `bundle exec appraisal rails-7.2 rspec`
+
+## Architecture
+
+- `lib/bard/exception_notification.rb` holds the shared pieces: `email_options` (recipient, sender, `[<app dir name>]` subject prefix, SMTP from `credentials.exception_notification_smtp_settings`, and `sections` that deliberately omit `session`), `notify_job_failure`, and two prepend modules (`LiveErrorNotification`, `UnknownTaskNotification`).
+- `lib/bard/exception_notification/engine.rb` wires it into the host app:
+  - The defaults initializer runs `before: :load_config_initializers`, so a host app's own `ExceptionNotification.configure` can add to (`+=`) or override the defaults. Preserve that ordering.
+  - It adds `filter_parameters` for cookie/auth/session env keys so they show as `[FILTERED]` in emails, and ignores everything outside `Rails.env.production?`.
+  - Job failures come from a `perform.active_job` notification subscriber, which fires only once retries are exhausted and never for discarded jobs.
+  - The test route is prepended with a constraint on `Test::ENV_KEY`, an env key set only in-process, so it can't be reached over HTTP.
+- `lib/bard/exception_notification/test.rb` + `lib/tasks/exception_notification.rake` implement the end-to-end check. `Test.web` drives `Rails.application.call` with a mock request and inspects `exception_notifier.delivered`. It sets `ExceptionNotifier.testing_mode = true` so delivery failures raise instead of being only logged. The `test` task runs `web`, then `job`, then `rake`; `rake` goes last because it aborts by raising.
+- `app/` holds the engine's `TestsController` and `TestJob` (which inherits the host's `::ApplicationJob`).
+
+## Specs
+
+- `spec/spec_helper.rb` defines an inline `Dummy::Application` (root `spec/dummy`), the `/boom` and `/login` routes, and the `request`/`deliveries` helpers. It stubs `Rails.env` to `production` before every example, so notifications fire by default. Tests that need "not production" re-stub it.
+- `spec/dummy/config/initializers/exception_notification.rb` acts as a host app's initializer and switches the email notifier to `delivery_method: :test`.
+- `module Bard::Rake` is defined in the spec helper on purpose: in real apps, bard-rake makes `Rake` inside `module Bard` resolve to `Bard::Rake`, which is why the engine uses `::Rake`. Keep top-level constants (`::Rails`, `::Rake`, `::ExceptionNotification`) fully qualified inside `module Bard`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Micah Geisel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# bard-exception_notification
+
+Shared [exception_notification](https://rubygems.org/gems/exception_notification) setup for BARD-managed Rails apps. Add the gem and every production app emails its exceptions the same way, from:
+
+- web requests
+- ActiveJob jobs, once retries are exhausted (discarded jobs send nothing)
+- rake tasks, including unknown task names
+- `ActionController::Live` actions that raise after the response has started streaming
+
+It also adds `rake exception_notification:test` to check that notifications actually arrive from a deployed app.
+
+## Installation
+
+```ruby
+gem "bard-exception_notification"
+```
+
+Requires Ruby 3.2+, Rails 7.2+ and exception_notification 5.0+.
+
+Add SMTP settings to the app's credentials:
+
+```yaml
+exception_notification_smtp_settings:
+  address: smtp.example.com
+  port: 587
+  user_name: ...
+  password: ...
+```
+
+## What it configures
+
+- Emails go to `micah@botandrose.com` from `errors@bardtracker.com`, with the app's directory name as the subject prefix, e.g. `[myapp] `.
+- Notifications are sent only in production.
+- Common noise is ignored: `ActionController::InvalidAuthenticityToken`, `ActionView::MissingTemplate`, `ActionController::BadRequest`, `ActionDispatch::Http::Parameters::ParseError`, `Mime::Type::InvalidMimeType`, `URI::InvalidComponentError` and `Addressable::URI::InvalidURIError`.
+- Cookies, the `Authorization` header and the session are kept out of emails. They are added to `filter_parameters`, and the session section is left out.
+
+## Customizing
+
+The defaults are applied before the app's own initializers, so an initializer can add to them or override them:
+
+```ruby
+# config/initializers/exception_notification.rb
+ExceptionNotification.configure do |config|
+  config.ignored_exceptions += %w[MyApp::ExpectedError]
+  config.add_notifier :email, Bard::ExceptionNotification.email_options.merge(exception_recipients: "team@example.com")
+end
+```
+
+## Testing a deployed app
+
+```sh
+bin/rake exception_notification:test
+```
+
+This runs three checks in order:
+
+- `exception_notification:test:web` sends a request through the app's middleware stack to a test page that raises, then fails unless a notification was delivered. The page is reachable only from this task, never over HTTP. The request uses the host from `Rails.application.default_url_options`, so that host must be allowed by `config.hosts`.
+- `exception_notification:test:job` enqueues a job that raises. Its notification is sent once a worker runs the job and any retries configured by `ApplicationJob` are exhausted.
+- `exception_notification:test:rake` raises from the task itself, so the task exits with a failure after sending its notification.
+
+The web and rake checks raise if the notification can't be delivered, instead of only logging the failure.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec appraisal install && bundle exec appraisal rspec   # every supported Rails version
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/bard/exception_notification/tests_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bard
+  module ExceptionNotification
+    class TestsController < ActionController::Base
+      def show
+        raise TestError, Test.message("web")
+      end
+    end
+  end
+end

data/app/jobs/bard/exception_notification/test_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bard
+  module ExceptionNotification
+    class TestJob < ::ApplicationJob
+      def perform(message)
+        raise TestError, message
+      end
+    end
+  end
+end

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "appraisal"
+gem "rails", "~> 7.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "appraisal"
+gem "rails", "~> 8.0.0"
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "appraisal"
+gem "rails", "~> 8.1.0"
+
+gemspec path: "../"

data/lib/bard/exception_notification/engine.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Bard
+  module ExceptionNotification
+    class Engine < ::Rails::Engine
+      # Before the app's own initializers, so they can adjust any of this with ExceptionNotification.configure.
+      initializer "bard-exception_notification.defaults", before: :load_config_initializers do |app|
+        app.config.filter_parameters += [
+          /\AHTTP_COOKIE\z/,
+          /\AHTTP_AUTHORIZATION\z/,
+          /\Arack\.request\.cookie_(hash|string)\z/,
+          /\Arack\.session\z/,
+          /\Aaction_dispatch\.request\.unsigned_session_cookie\z/,
+        ]
+
+        ::ExceptionNotification.configure do |config|
+          config.ignored_exceptions += %w[
+            ActionController::InvalidAuthenticityToken
+            ActionView::MissingTemplate
+            ActionController::BadRequest
+            ActionDispatch::Http::Parameters::ParseError
+            Mime::Type::InvalidMimeType
+            URI::InvalidComponentError
+            Addressable::URI::InvalidURIError
+          ]
+
+          config.ignore_if do |exception, options|
+            !::Rails.env.production?
+          end
+
+          config.add_notifier :email, ExceptionNotification.email_options
+        end
+      end
+
+      initializer "bard-exception_notification.active_job" do
+        ActiveSupport::Notifications.subscribe("perform.active_job") do |event|
+          exception = event.payload[:exception_object]
+          ExceptionNotification.notify_job_failure(exception, event.payload[:job]) if exception
+        end
+      end
+
+      initializer "bard-exception_notification.live" do
+        ActiveSupport.on_load(:action_controller_base) do
+          ActionController::Live.prepend LiveErrorNotification
+        end
+      end
+
+      initializer "bard-exception_notification.test_route" do |app|
+        app.routes.prepend do
+          get "/exception_notification/test",
+            to: "bard/exception_notification/tests#show",
+            as: nil,
+            constraints: ->(request) { request.env[Test::ENV_KEY] }
+        end
+      end
+
+      rake_tasks do
+        ::Rake::Application.prepend UnknownTaskNotification
+      end
+    end
+  end
+end

data/lib/bard/exception_notification/test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Bard
+  module ExceptionNotification
+    class TestError < StandardError; end
+
+    module Test
+      # Set only in-process, so no HTTP request can reach the test page.
+      ENV_KEY = "bard.exception_notification.test"
+
+      extend self
+
+      def web
+        surface_delivery_failures!
+        env = ::Rack::MockRequest.env_for("https://#{host}/exception_notification/test", "HTTP_HOST" => host, ENV_KEY => true)
+        status, _headers, body = ::Rails.application.call(env)
+        body.close if body.respond_to?(:close)
+
+        raise "Expected the test page to raise #{TestError}, but it responded #{status}" unless env["action_controller.instance"].is_a?(TestsController)
+
+        exception = env["action_dispatch.exception"]
+        raise exception if exception && !exception.is_a?(TestError)
+        raise "#{TestError} from the test page was not sent; check ExceptionNotification's ignore rules" unless env["exception_notifier.delivered"]
+        puts "web: sent a #{TestError} notification from #{TestsController}"
+      end
+
+      def job
+        TestJob.perform_later(message("job"))
+        puts "job: enqueued #{TestJob}; its notification is sent once the job fails for good, after any retries ApplicationJob configures"
+      end
+
+      def rake
+        surface_delivery_failures!
+        raise TestError, message("rake")
+      end
+
+      def message(context)
+        "Exception notification test from #{context} at #{Time.now.utc.iso8601}"
+      end
+
+      private
+
+      # Otherwise ExceptionNotifier only logs a failed delivery, and the test looks like it passed.
+      def surface_delivery_failures!
+        ExceptionNotifier.testing_mode = true
+      end
+
+      def host
+        ::Rails.application.default_url_options.fetch(:host, "localhost")
+      end
+    end
+  end
+end

data/lib/bard/exception_notification/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Bard
+  module ExceptionNotification
+    VERSION = "0.1.0"
+  end
+end

data/lib/bard/exception_notification.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "exception_notification"
+require "exception_notification/rails"
+require "bard/exception_notification/version"
+require "bard/exception_notification/test"
+require "bard/exception_notification/engine"
+
+module Bard
+  module ExceptionNotification
+    def self.email_options
+      {
+        email_prefix: "[#{::Rails.root.basename}] ",
+        exception_recipients: "micah@botandrose.com",
+        sender_address: "errors@bardtracker.com",
+        sections: %w[request environment backtrace], # not session, which can hold a login's persistence token
+        smtp_settings: ::Rails.application.credentials.exception_notification_smtp_settings,
+      }
+    end
+
+    def self.notify_job_failure(exception, job)
+      ExceptionNotifier.notify_exception(exception, data: {
+        job_class: job.class.name,
+        job_id: job.job_id,
+        arguments: job.arguments,
+        queue_name: job.queue_name,
+        executions: job.executions,
+      })
+    end
+
+    module LiveErrorNotification
+      def log_error(exception)
+        ExceptionNotifier.notify_exception(exception, env: request.env)
+        super
+      end
+    end
+
+    module UnknownTaskNotification
+      def invoke_task(task_string)
+        super
+      rescue RuntimeError => exception
+        ExceptionNotifier.notify_exception(exception) if exception.message.start_with?("Don't know how to build task")
+        raise
+      end
+    end
+  end
+end

data/lib/bard-exception_notification.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bard/exception_notification"

data/lib/tasks/exception_notification.rake

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+namespace :exception_notification do
+  desc "Send a test exception notification from a web request, a job and a rake task"
+  task test: %w[test:web test:job test:rake]
+
+  namespace :test do
+    desc "Send a test exception notification from a web request"
+    task web: :environment do
+      Bard::ExceptionNotification::Test.web
+    end
+
+    desc "Enqueue a job that fails, to send a test exception notification from a job"
+    task job: :environment do
+      Bard::ExceptionNotification::Test.job
+    end
+
+    desc "Send a test exception notification from a rake task"
+    task rake: :environment do
+      Bard::ExceptionNotification::Test.rake
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: bard-exception_notification
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah Geisel
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: exception_notification
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: Configures exception_notification for web requests, ActiveJob, rake and
+  ActionController::Live, and adds rake exception_notification:test to check it end
+  to end
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Appraisals
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/bard/exception_notification/tests_controller.rb
+- app/jobs/bard/exception_notification/test_job.rb
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/bard-exception_notification.rb
+- lib/bard/exception_notification.rb
+- lib/bard/exception_notification/engine.rb
+- lib/bard/exception_notification/test.rb
+- lib/bard/exception_notification/version.rb
+- lib/tasks/exception_notification.rake
+homepage: https://github.com/botandrose/bard-exception_notification
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/bard-exception_notification
+  source_code_uri: https://github.com/botandrose/bard-exception_notification
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Shared exception_notification setup for BARD-managed Rails projects
+test_files: []