oopsie_exceptions 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064c67e6e15924cf8a33314dfc3b4f174e749a5eef347b3e7620afb3785de58a
-  data.tar.gz: 9fe2be17be0fb8c3d171b302c0552b90f73277fea962f324de14ed84b0d5c487
+  metadata.gz: a3c1bf7176b541c4c19f09ca56724e8c873e1bae149ac9ff9963a4f4fb4f1156
+  data.tar.gz: 692fd55d89e3235279b1ba98764f1fbeaeab5e11204c3733674f7a8958956262
 SHA512:
-  metadata.gz: d75e1e6e3fc2b6b743414c7fb83ee0beb92ee54f41dd9cc7cd16e87d8036c545d5484e66930b3b50a63953d232c79c4043c6281b1c701d133ed4606b5c44c0ac
-  data.tar.gz: c29d4e4a013d41504193009688520ae0afdc55f9d3d6a4281c57d0e203f083314f919c7385bd4ae59de2f56055540ad98d5cc45d1f4fd009103836a6b871fe6d
+  metadata.gz: 0c8a3bfd9907819f35ecd979d114e9784daf71ff7c5b2264246782458463c15271a71319208fe5798de1c11178c7bf643e8bcda693124ed74e7f2a50cc25ef17
+  data.tar.gz: 9d4f5168d31b516127abc0afa2e894ec02c28cdf076e82f96d555f81c1e38fb3884d3fbca46307572ce2f9749798cf1ace9c4e2fa6d98a6263908c4a695a14a1

data/README.md

@@ -2,7 +2,7 @@
 
 Lightweight exception capture and webhook delivery for Rails. Like Sentry/Rollbar, but self-hosted and webhook-driven.
 
-Captures unhandled exceptions from web requests and background jobs, enriches them with request/user/server context, and delivers structured JSON payloads to configurable webhook endpoints.
+Captures unhandled exceptions from web requests and background jobs, enriches them with request/user/server context, and POSTs structured JSON payloads to one or more webhook endpoints.
 
 ## Installation
 
@@ -18,49 +18,99 @@ Then run the install generator:
 bin/rails generate oopsie_exceptions:install
 ```
 
-This creates:
-- `config/initializers/oopsie_exceptions.rb` — configuration
-- `app/jobs/oopsie_exceptions/delivery_job.rb` — async webhook delivery
+That creates a single file: `config/initializers/oopsie_exceptions.rb`. No code lands in `app/` — the Rack middleware, Rails error subscriber, ActiveJob hook, and webhook delivery job all live inside the gem.
 
 ## Configuration
 
-Edit `config/initializers/oopsie_exceptions.rb`:
+The most common pattern is to configure a different webhook per environment, with the URL and auth token coming from environment variables. Here's a real-world initializer:
 
 ```ruby
+# config/initializers/oopsie_exceptions.rb
 OopsieExceptions.configure do |config|
-  config.add_webhook "https://your-endpoint.com/webhooks/exceptions",
-    headers: { "Authorization" => "Bearer #{ENV['OOPSIE_WEBHOOK_TOKEN']}" }
+  if Rails.env.development?
+    config.add_webhook(
+      "http://localhost:3099/api/v1/exceptions",
+      headers: { "Authorization" => "Bearer #{ENV['OOPSIE_DEV_TOKEN']}" },
+      name: "oopsie-local"
+    )
+    config.async_delivery = false
+  end
+
+  if Rails.env.production?
+    config.add_webhook(
+      "https://oopsie.example.com/api/v1/exceptions",
+      headers: { "Authorization" => "Bearer #{ENV['OOPSIE_PROD_TOKEN']}" },
+      name: "oopsie-prod"
+    )
+    config.async_delivery = true
+  end
 
   config.app_name = "MyApp"
   config.environment = Rails.env
-  config.enabled = Rails.env.production?
+  config.filter_parameters = %w[password password_confirmation secret token api_key]
+  config.enabled = Rails.env.development? || Rails.env.production?
+
+  # Attach the current user and controller#action to every exception.
+  # `env` is the Rack env — runs once per request.
+  config.context_builder = ->(env) {
+    warden = env["warden"]
+    user = warden&.user
+    params = env["action_dispatch.request.path_parameters"]
+    {
+      user: user ? { id: user.id, email: user.email } : nil,
+      action: params ? "#{params[:controller]}##{params[:action]}" : nil
+    }.compact
+  }
 end
 ```
 
-## What happens automatically
+### Configuration options
 
-- **Rack middleware** inserted after `DebugExceptions` catches unhandled exceptions
-- **Rails.error subscriber** captures framework-reported errors
-- Request context (URL, IP, params, headers) is collected automatically
-- Webhooks are delivered async via ActiveJob
+| Option | Default | Description |
+| --- | --- | --- |
+| `add_webhook(url, headers:, name:)` | — | Register a webhook. Call multiple times for fan-out. |
+| `app_name` | Rails app module name | Identifier sent in every payload. |
+| `environment` | `Rails.env` | Environment label sent in every payload. |
+| `enabled` | `true` | Master kill switch. Set false in test/dev. |
+| `async_delivery` | `true` | Deliver via ActiveJob. Set false to POST inline. |
+| `filter_parameters` | `password, secret, token, api_key, ...` | Param names to redact in payloads. |
+| `filter_headers` | `Authorization, Cookie, Set-Cookie` | Headers to strip from payloads. |
+| `capture_request_body` | `false` | Include first 10KB of JSON request bodies. |
+| `ignored_exceptions` | 404s, routing errors, etc. | Exception class names to silently drop. |
+| `ignore_exception(*names)` | — | Append to `ignored_exceptions`. |
+| `context_builder` | `nil` | `->(env) { Hash }` — extra context per request. |
+| `before_notify` | `nil` | `->(payload) { payload }` — mutate or drop payloads. |
+| `timeout` / `open_timeout` | `10` / `5` | HTTP timeouts (seconds). |
 
-## Adding user context
+## What gets captured automatically
 
-In your `ApplicationController`:
+- **Web requests** — A Rack middleware inserted after `ActionDispatch::DebugExceptions` catches unhandled exceptions and 5xx responses.
+- **Background jobs** — `ActiveJob::Base.execute` is wrapped at the class level (the same approach Appsignal uses), so every queue adapter (Solid Queue, Sidekiq, Async, etc.) is covered. Catches `DeserializationError` and missing job classes too.
+- **`Rails.error` reports** — Subscribed via `Rails.error.subscribe`, so anything reported through the framework error reporter (`Rails.error.report` / `Rails.error.handle`) flows through.
+
+Each captured exception is enriched with request URL/method/IP/params/headers, the current user (via `context_builder` or `set_context`), server hostname/PID/Ruby version, and a UTC timestamp.
+
+## Adding context per-request
+
+If you don't want to use `context_builder`, you can set context from a controller:
 
 ```ruby
-before_action :set_oopsie_context
+class ApplicationController < ActionController::Base
+  before_action :set_oopsie_context
 
-private
+  private
 
-def set_oopsie_context
-  OopsieExceptions.set_context(
-    user: current_user ? { id: current_user.id, email: current_user.email } : nil,
-    action: "#{self.class.name}##{action_name}"
-  )
+  def set_oopsie_context
+    OopsieExceptions.set_context(
+      user: current_user ? { id: current_user.id, email: current_user.email } : nil,
+      action: "#{self.class.name}##{action_name}"
+    )
+  end
 end
 ```
 
+`context_builder` is preferred — it runs in the middleware before the request hits any controller, so it captures context even on errors raised before `before_action` runs.
+
 ## Manual reporting
 
 ```ruby
@@ -71,38 +121,89 @@ rescue => e
 end
 ```
 
+Or scope context to a block:
+
+```ruby
+OopsieExceptions.with_context(tenant_id: 42) do
+  do_work
+end
+```
+
 ## Multiple webhooks
 
 ```ruby
-config.add_webhook "https://your-api.com/exceptions"
+config.add_webhook "https://your-api.com/exceptions",
+  headers: { "Authorization" => "Bearer #{ENV['PRIMARY_TOKEN']}" }
+
 config.add_webhook "https://hooks.slack.com/services/..."
 config.add_webhook "https://discord.com/api/webhooks/..."
 ```
 
-Each endpoint receives every exception.
+Each endpoint receives every exception. Failures on one webhook don't affect the others.
 
 ## Payload format
 
-Each webhook receives a JSON payload with:
+Each webhook receives a JSON POST with:
 
 - **exception** — class, message, backtrace, cause chain
 - **request** — URL, method, IP, params, headers, user agent
-- **context** — user info and custom data you set
+- **context** — `user`, `action`, `job`, plus anything you set via `context_builder` / `set_context`
 - **server** — hostname, PID, Ruby/Rails versions
-- **app** — name, environment
+- **app** — `app_name`, `environment`
 - **timestamp** — UTC ISO8601
+- **handled** — `true` for `OopsieExceptions.report(..., handled: true)`, `false` for unhandled
+
+## Filtering noise
+
+By default these are dropped:
+
+```
+ActionController::RoutingError
+ActionController::UnknownFormat
+ActionController::BadRequest
+ActionDispatch::Http::MimeNegotiation::InvalidType
+AbstractController::ActionNotFound
+ActiveRecord::RecordNotFound
+ActionController::UnknownHttpMethod
+```
 
-## Filtering
+Add your own:
 
-By default, common noise exceptions are ignored (404s, routing errors, `ActionController::BadRequest`, etc.). Sensitive parameters (`password`, `token`, `secret`, `api_key`) and headers (`Authorization`, `Cookie`) are automatically filtered from payloads.
+```ruby
+config.ignore_exception "MyApp::IgnorableError", "ThirdParty::Timeout"
+```
 
-Customize in your initializer:
+Sensitive params (`password`, `token`, `secret`, `api_key`) and headers (`Authorization`, `Cookie`, `Set-Cookie`) are redacted from payloads automatically.
+
+## Mutating or dropping payloads
 
 ```ruby
-config.ignored_exceptions += ["MyApp::IgnorableError"]
-config.filter_parameters += [:credit_card]
+config.before_notify = ->(payload) {
+  payload[:context][:deploy_sha] = ENV["GIT_SHA"]
+  return nil if payload[:exception][:message].include?("known noise")
+  payload
+}
 ```
 
+Return `nil` to drop the notification entirely.
+
+## Upgrading from earlier versions
+
+If you're coming from an older version of the gem that generated `app/jobs/oopsie_exceptions/delivery_job.rb` in your app, **delete that file**. The gem now ships its own `OopsieExceptions::WebhookJob` and the host-app file is obsolete.
+
+```bash
+rm app/jobs/oopsie_exceptions/delivery_job.rb
+rmdir app/jobs/oopsie_exceptions  # if empty
+```
+
+Or just re-run the install generator and it will detect and remove the legacy file for you:
+
+```bash
+bin/rails generate oopsie_exceptions:install
+```
+
+No initializer changes are required.
+
 ## License
 
 MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/generators/oopsie_exceptions/install_generator.rb

@@ -5,32 +5,27 @@ module OopsieExceptions
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      desc "Creates an OopsieExceptions initializer and delivery job"
+      desc "Creates an OopsieExceptions initializer"
 
       def create_initializer
         template "initializer.rb", "config/initializers/oopsie_exceptions.rb"
       end
 
-      def create_delivery_job
-        template "delivery_job.rb", "app/jobs/oopsie_exceptions/delivery_job.rb"
+      def remove_legacy_delivery_job
+        legacy_path = "app/jobs/oopsie_exceptions/delivery_job.rb"
+        return unless File.exist?(File.join(destination_root, legacy_path))
+
+        say ""
+        say "Found legacy #{legacy_path} from a previous version.", :yellow
+        say "The gem now ships its own webhook job — this file is no longer used."
+        remove_file legacy_path
       end
 
       def show_post_install
         say ""
         say "OopsieExceptions installed!", :green
         say ""
-        say "Next steps:"
-        say "  1. Edit config/initializers/oopsie_exceptions.rb to add your webhook URLs"
-        say "  2. Optionally add user context in ApplicationController:"
-        say ""
-        say "     before_action :set_oopsie_context"
-        say ""
-        say "     def set_oopsie_context"
-        say "       OopsieExceptions.set_context("
-        say "         user: current_user ? { id: current_user.id, email: current_user.email } : nil,"
-        say "         action: \"\#{self.class.name}#\#{action_name}\""
-        say "       )"
-        say "     end"
+        say "Next step: edit config/initializers/oopsie_exceptions.rb and add your webhook URLs."
         say ""
       end
     end

data/lib/generators/oopsie_exceptions/templates/initializer.rb

@@ -1,8 +1,23 @@
 OopsieExceptions.configure do |config|
-  # Add webhook endpoints — exceptions get POSTed here as JSON
-  # config.add_webhook "https://your-endpoint.com/webhooks/exceptions",
-  #   headers: { "Authorization" => "Bearer #{ENV['OOPSIE_WEBHOOK_TOKEN']}" },
-  #   name: "primary"
+  # Webhook endpoints — exceptions get POSTed as JSON.
+  # Configure per-environment so dev errors don't hit your prod tracker.
+  if Rails.env.development?
+    config.add_webhook(
+      "http://localhost:3099/api/v1/exceptions",
+      headers: { "Authorization" => "Bearer #{ENV['OOPSIE_DEV_TOKEN']}" },
+      name: "oopsie-local"
+    )
+    config.async_delivery = false
+  end
+
+  if Rails.env.production?
+    config.add_webhook(
+      "https://oopsie.example.com/api/v1/exceptions",
+      headers: { "Authorization" => "Bearer #{ENV['OOPSIE_PROD_TOKEN']}" },
+      name: "oopsie-prod"
+    )
+    config.async_delivery = true
+  end
 
   # config.add_webhook "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
   # config.add_webhook "https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK"
@@ -10,32 +25,30 @@ OopsieExceptions.configure do |config|
   config.app_name = Rails.application.class.module_parent_name
   config.environment = Rails.env
 
-  # Deliver webhooks async via ActiveJob (set false for sync delivery)
-  config.async_delivery = true
-
-  # Exceptions that won't be reported (404s, bot garbage, etc.)
-  # config.ignore_exception "ActionController::RoutingError"
-
   # Filter sensitive params from payloads (inherits from Rails by default)
   config.filter_parameters = Rails.application.config.filter_parameters.map(&:to_s)
 
-  # Set false to disable in dev/test
-  config.enabled = Rails.env.production? || Rails.env.staging?
+  # Master kill switch — leave off in test
+  config.enabled = Rails.env.development? || Rails.env.production?
 
-  # Optional: modify or drop payloads before sending
-  # config.before_notify = ->(payload) {
-  #   payload[:context][:deploy_sha] = ENV["GIT_SHA"]
-  #   payload  # return nil to skip this notification
-  # }
+  # Exceptions that won't be reported (404s, bot garbage, etc.)
+  # config.ignore_exception "MyApp::IgnorableError"
 
-  # Add custom context to every exception from the Rack env.
-  # This runs on every request — use it to attach the current user, feature flags, etc.
+  # Attach the current user and controller#action to every exception.
+  # `env` is the Rack env — runs once per request, before any controller code.
   # config.context_builder = ->(env) {
   #   warden = env["warden"]
   #   user = warden&.user
+  #   params = env["action_dispatch.request.path_parameters"]
   #   {
   #     user: user ? { id: user.id, email: user.email } : nil,
-  #     action: env["action_dispatch.request.path_parameters"]&.slice(:controller, :action)&.values&.join("#")
-  #   }
+  #     action: params ? "#{params[:controller]}##{params[:action]}" : nil
+  #   }.compact
+  # }
+
+  # Optional: modify or drop payloads before sending
+  # config.before_notify = ->(payload) {
+  #   payload[:context][:deploy_sha] = ENV["GIT_SHA"]
+  #   payload  # return nil to skip this notification
   # }
 end

data/lib/oopsie_exceptions/active_job_extension.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  # Class-level extension for ActiveJob::Base. Wraps `execute(job_data)`, the
+  # entry point queue adapters call, so we capture every unhandled exception
+  # — including ones that fire before `perform` runs (e.g. DeserializationError,
+  # or a missing job class).
+  #
+  # This mirrors how Appsignal hooks ActiveJob (lib/appsignal/hooks/active_job.rb).
+  module ActiveJobExtension
+    def execute(job_data)
+      job_context = {
+        job: {
+          class: job_data["job_class"],
+          job_id: job_data["job_id"],
+          queue: job_data["queue_name"],
+          arguments: job_data["arguments"],
+          executions: job_data["executions"],
+          provider_job_id: job_data["provider_job_id"]
+        }.compact
+      }
+
+      OopsieExceptions.with_context(job_context) do
+        super
+      rescue Exception => exception
+        OopsieExceptions.report(
+          exception,
+          context: { namespace: "background_job" },
+          handled: false
+        )
+        raise
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions/railtie.rb

@@ -8,21 +8,8 @@ module OopsieExceptions
 
     initializer "oopsie_exceptions.active_job" do
       ActiveSupport.on_load(:active_job) do
-        around_perform do |job, block|
-          OopsieExceptions.with_context(
-            job: {
-              class: job.class.name,
-              job_id: job.job_id,
-              queue: job.queue_name,
-              arguments: job.arguments.map(&:to_s)
-            }
-          ) do
-            block.call
-          end
-        rescue Exception => e
-          OopsieExceptions.report(e, context: { namespace: "background_job" }, handled: false)
-          raise
-        end
+        ::ActiveJob::Base.extend(OopsieExceptions::ActiveJobExtension)
+        require "oopsie_exceptions/webhook_job"
       end
     end
 

data/lib/oopsie_exceptions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OopsieExceptions
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/oopsie_exceptions/webhook_job.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Webhook delivery job. Loaded from the Railtie inside on_load(:active_job),
+# so it's only defined when the host app has ActiveJob available.
+#
+# Inherits from ActiveJob::Base directly (not ApplicationJob) so the gem has
+# zero hard dependencies on host-app code.
+module OopsieExceptions
+  class WebhookJob < ActiveJob::Base
+    queue_as :default
+
+    discard_on StandardError do |_job, error|
+      logger = OopsieExceptions.configuration.logger
+      logger&.error("[OopsieExceptions] WebhookJob discarded permanently: #{error.message}")
+    end
+
+    retry_on Net::OpenTimeout, Net::ReadTimeout, wait: 5.seconds, attempts: 3
+
+    def perform(payload_json, webhook_url, headers_json)
+      webhook = OopsieExceptions::Configuration::Webhook.new(
+        url: webhook_url,
+        headers: JSON.parse(headers_json),
+        name: webhook_url
+      )
+
+      OopsieExceptions::WebhookClient.post(webhook, payload_json)
+    end
+  end
+end

data/lib/oopsie_exceptions.rb

@@ -7,6 +7,7 @@ require_relative "oopsie_exceptions/payload"
 require_relative "oopsie_exceptions/webhook_client"
 require_relative "oopsie_exceptions/middleware"
 require_relative "oopsie_exceptions/error_subscriber"
+require_relative "oopsie_exceptions/active_job_extension"
 require_relative "oopsie_exceptions/railtie" if defined?(Rails::Railtie)
 
 module OopsieExceptions
@@ -58,8 +59,8 @@ module OopsieExceptions
 
     def deliver(payload)
       configuration.webhook_urls.each do |webhook|
-        if configuration.async_delivery && defined?(OopsieExceptions::DeliveryJob)
-          DeliveryJob.perform_later(
+        if configuration.async_delivery && defined?(OopsieExceptions::WebhookJob)
+          WebhookJob.perform_later(
             payload.to_json,
             webhook.url,
             webhook.headers.to_json

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oopsie_exceptions
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Troy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -36,9 +36,9 @@ files:
 - LICENSE.txt
 - README.md
 - lib/generators/oopsie_exceptions/install_generator.rb
-- lib/generators/oopsie_exceptions/templates/delivery_job.rb
 - lib/generators/oopsie_exceptions/templates/initializer.rb
 - lib/oopsie_exceptions.rb
+- lib/oopsie_exceptions/active_job_extension.rb
 - lib/oopsie_exceptions/configuration.rb
 - lib/oopsie_exceptions/context.rb
 - lib/oopsie_exceptions/error_subscriber.rb
@@ -47,6 +47,7 @@ files:
 - lib/oopsie_exceptions/railtie.rb
 - lib/oopsie_exceptions/version.rb
 - lib/oopsie_exceptions/webhook_client.rb
+- lib/oopsie_exceptions/webhook_job.rb
 homepage: https://github.com/theinventor/oopsie_exceptions
 licenses:
 - MIT
@@ -69,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Lightweight exception capture and webhook delivery for Ruby (framework-agnostic)

data/lib/generators/oopsie_exceptions/templates/delivery_job.rb

@@ -1,21 +0,0 @@
-module OopsieExceptions
-  class DeliveryJob < ApplicationJob
-    queue_as :default
-
-    discard_on StandardError do |job, error|
-      Rails.logger.error("[OopsieExceptions] DeliveryJob failed permanently: #{error.message}")
-    end
-
-    retry_on Net::OpenTimeout, Net::ReadTimeout, wait: 5.seconds, attempts: 3
-
-    def perform(payload_json, webhook_url, headers_json)
-      webhook = OopsieExceptions::Configuration::Webhook.new(
-        url: webhook_url,
-        headers: JSON.parse(headers_json),
-        name: webhook_url
-      )
-
-      OopsieExceptions::WebhookClient.post(webhook, payload_json)
-    end
-  end
-end