oopsie_exceptions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38724bd4e7e3113063179a4306f5207544e2c8933491ab429433d5294c00f04a
+  data.tar.gz: c42960e5299dfce450d2cd7992cc3fe5acf1c92ab667c41c555a2c8b90a258a5
+SHA512:
+  metadata.gz: aa0c4ed76d142a98fc0b1097ad6956a637296eaa0da494762d839c2b94aecd4eabd061cc5d18e6c22113652ab401e2d74d6767ac86bccaed9c77ea620b990e7e
+  data.tar.gz: 39de699f9980f8151a55098257c75b50b000300718031baea8b9b8322cd96d8cb49f766a41dfddec615338d3835ece207b0192438f2730146df69d67a8427c48

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Troy
+
+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,108 @@
+# OopsieExceptions
+
+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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "oopsie_exceptions"
+```
+
+Then run the install generator:
+
+```bash
+bin/rails generate oopsie_exceptions:install
+```
+
+This creates:
+- `config/initializers/oopsie_exceptions.rb` — configuration
+- `app/jobs/oopsie_exceptions/delivery_job.rb` — async webhook delivery
+
+## Configuration
+
+Edit `config/initializers/oopsie_exceptions.rb`:
+
+```ruby
+OopsieExceptions.configure do |config|
+  config.add_webhook "https://your-endpoint.com/webhooks/exceptions",
+    headers: { "Authorization" => "Bearer #{ENV['OOPSIE_WEBHOOK_TOKEN']}" }
+
+  config.app_name = "MyApp"
+  config.environment = Rails.env
+  config.enabled = Rails.env.production?
+end
+```
+
+## What happens automatically
+
+- **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
+
+## Adding user context
+
+In your `ApplicationController`:
+
+```ruby
+before_action :set_oopsie_context
+
+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}"
+  )
+end
+```
+
+## Manual reporting
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  OopsieExceptions.report(e, context: { order_id: 123 }, handled: true)
+end
+```
+
+## Multiple webhooks
+
+```ruby
+config.add_webhook "https://your-api.com/exceptions"
+config.add_webhook "https://hooks.slack.com/services/..."
+config.add_webhook "https://discord.com/api/webhooks/..."
+```
+
+Each endpoint receives every exception.
+
+## Payload format
+
+Each webhook receives a JSON payload with:
+
+- **exception** — class, message, backtrace, cause chain
+- **request** — URL, method, IP, params, headers, user agent
+- **context** — user info and custom data you set
+- **server** — hostname, PID, Ruby/Rails versions
+- **app** — name, environment
+- **timestamp** — UTC ISO8601
+
+## Filtering
+
+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.
+
+Customize in your initializer:
+
+```ruby
+config.ignored_exceptions += ["MyApp::IgnorableError"]
+config.filter_parameters += [:credit_card]
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/generators/oopsie_exceptions/install_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OopsieExceptions initializer and delivery job"
+
+      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"
+      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 ""
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+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

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

@@ -0,0 +1,30 @@
+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"
+
+  # config.add_webhook "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
+  # config.add_webhook "https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK"
+
+  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?
+
+  # 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/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  class Configuration
+    attr_accessor :webhook_urls, :app_name, :environment,
+                  :ignored_exceptions, :filter_parameters,
+                  :filter_headers, :capture_request_body,
+                  :async_delivery, :timeout, :open_timeout,
+                  :backtrace_cleaner, :before_notify,
+                  :enabled
+
+    def initialize
+      @webhook_urls = []
+      @app_name = defined?(Rails) ? (Rails.application.class.module_parent_name rescue "App") : "App"
+      @environment = defined?(Rails) ? (Rails.env rescue "development") : "development"
+      @ignored_exceptions = default_ignored_exceptions
+      @filter_parameters = %w[password password_confirmation secret token api_key]
+      @filter_headers = %w[Authorization Cookie Set-Cookie]
+      @capture_request_body = false
+      @async_delivery = true
+      @timeout = 10
+      @open_timeout = 5
+      @backtrace_cleaner = nil
+      @before_notify = nil
+      @enabled = true
+    end
+
+    def add_webhook(url, headers: {}, name: nil)
+      @webhook_urls << Webhook.new(url: url, headers: headers, name: name || url)
+    end
+
+    def ignore_exception(*class_names)
+      @ignored_exceptions.concat(class_names.map(&:to_s))
+    end
+
+    def ignored?(exception)
+      @ignored_exceptions.include?(exception.class.name)
+    end
+
+    private
+
+    def default_ignored_exceptions
+      %w[
+        ActionController::RoutingError
+        ActionController::UnknownFormat
+        ActionController::BadRequest
+        ActionDispatch::Http::MimeNegotiation::InvalidType
+        AbstractController::ActionNotFound
+        ActiveRecord::RecordNotFound
+        ActionController::UnknownHttpMethod
+      ]
+    end
+
+    Webhook = Data.define(:url, :headers, :name)
+  end
+end

data/lib/oopsie_exceptions/context.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  module Context
+    THREAD_KEY = :oopsie_exceptions_context
+
+    class << self
+      def current
+        Thread.current[THREAD_KEY] ||= {}
+      end
+
+      def merge(hash)
+        current.merge!(hash)
+      end
+
+      def replace(hash)
+        Thread.current[THREAD_KEY] = hash
+      end
+
+      def clear
+        Thread.current[THREAD_KEY] = nil
+      end
+
+      def from_rack_env(env)
+        request = ActionDispatch::Request.new(env)
+        config = OopsieExceptions.configuration
+
+        ctx = {
+          request: {
+            url: request.original_url,
+            method: request.method,
+            ip: request.remote_ip,
+            user_agent: request.user_agent,
+            referer: request.referer,
+            request_id: request.request_id,
+            params: sanitize_params(request.filtered_parameters),
+            headers: extract_headers(env, config)
+          }
+        }
+
+        if config.capture_request_body && request.content_type&.include?("application/json")
+          body = request.body.read
+          request.body.rewind
+          ctx[:request][:body] = body.truncate(10_000) if body.present?
+        end
+
+        ctx
+      end
+
+      private
+
+      def sanitize_params(params)
+        params.except("controller", "action").to_h
+      rescue
+        {}
+      end
+
+      def extract_headers(env, config)
+        headers = {}
+        env.each do |key, value|
+          next unless key.start_with?("HTTP_")
+          header_name = key.sub("HTTP_", "").split("_").map(&:capitalize).join("-")
+          next if config.filter_headers.any? { |h| h.casecmp(header_name) == 0 }
+          headers[header_name] = value
+        end
+        headers
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions/error_subscriber.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  class ErrorSubscriber
+    def report(error, handled:, severity:, context: {}, source: nil)
+      return if severity == :warning
+
+      merged_context = context.merge(
+        rails_error_reporter: true,
+        severity: severity.to_s,
+        source: source
+      ).compact
+
+      OopsieExceptions.report(error, context: merged_context, handled: handled)
+    end
+  end
+end

data/lib/oopsie_exceptions/middleware.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Context.clear
+
+      begin
+        request_context = Context.from_rack_env(env)
+        Context.merge(request_context)
+
+        response = @app.call(env)
+
+        if response[0].to_i >= 500
+          Context.merge(response_status: response[0].to_i)
+        end
+
+        response
+      rescue Exception => exception
+        Context.merge(response_status: 500)
+        OopsieExceptions.report(exception, handled: false)
+        raise
+      ensure
+        Context.clear
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions/payload.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  class Payload
+    MAX_CAUSE_DEPTH = 10
+
+    class << self
+      def build(exception, context: {}, handled: true)
+        config = OopsieExceptions.configuration
+        backtrace = clean_backtrace(exception, config)
+
+        {
+          notifier: "OopsieExceptions",
+          version: VERSION,
+          timestamp: Time.now.utc.iso8601(3),
+          app: {
+            name: config.app_name,
+            environment: config.environment
+          },
+          error: {
+            class_name: exception.class.name,
+            message: exception.message.to_s[0, 10_000],
+            backtrace: backtrace,
+            first_line: parse_backtrace_line(backtrace&.first),
+            causes: collect_causes(exception),
+            handled: handled
+          },
+          context: Context.current.merge(context),
+          server: server_info
+        }
+      end
+
+      private
+
+      def server_info
+        info = {
+          hostname: Socket.gethostname,
+          pid: Process.pid,
+          ruby_version: RUBY_VERSION
+        }
+        info[:rails_version] = Rails::VERSION::STRING if defined?(Rails::VERSION)
+        info
+      end
+
+      def clean_backtrace(exception, config)
+        bt = exception.backtrace || []
+        cleaner = config.backtrace_cleaner || default_cleaner
+        cleaner ? cleaner.clean(bt) : bt
+      end
+
+      def default_cleaner
+        Rails.backtrace_cleaner if defined?(Rails)
+      rescue
+        nil
+      end
+
+      def collect_causes(exception)
+        causes = []
+        current = exception.cause
+        depth = 0
+
+        while current && depth < MAX_CAUSE_DEPTH
+          causes << {
+            class_name: current.class.name,
+            message: current.message.to_s[0, 1_000],
+            first_line: parse_backtrace_line(current.backtrace&.first)
+          }
+          current = current.cause
+          depth += 1
+        end
+
+        causes
+      end
+
+      def parse_backtrace_line(line)
+        return nil unless line
+        match = line.match(/\A(.+):(\d+):in [`'](.+)'\z/)
+        return { raw: line } unless match
+
+        {
+          file: match[1],
+          line: match[2].to_i,
+          method: match[3]
+        }
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OopsieExceptions
+  class Railtie < Rails::Railtie
+    initializer "oopsie_exceptions.middleware" do |app|
+      app.middleware.insert_after ActionDispatch::DebugExceptions, OopsieExceptions::Middleware
+    end
+
+    initializer "oopsie_exceptions.error_subscriber", after: :load_config_initializers do
+      if Rails.respond_to?(:error) && OopsieExceptions.configuration.enabled
+        Rails.error.subscribe(OopsieExceptions::ErrorSubscriber.new)
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions/version.rb

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

data/lib/oopsie_exceptions/webhook_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module OopsieExceptions
+  class WebhookClient
+    class << self
+      def post(webhook, payload)
+        uri = URI.parse(webhook.url)
+        config = OopsieExceptions.configuration
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = config.open_timeout
+        http.read_timeout = config.timeout
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "OopsieExceptions/#{VERSION}"
+
+        webhook.headers.each { |k, v| request[k] = v }
+
+        request.body = payload.is_a?(String) ? payload : payload.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          log_warn("Webhook #{webhook.name} responded #{response.code}: #{response.body.to_s[0, 500]}")
+        end
+
+        response
+      rescue => e
+        log_error("Failed to deliver to #{webhook.name}: #{e.message}")
+        nil
+      end
+
+      private
+
+      def log_warn(message)
+        if defined?(Rails.logger) && Rails.logger
+          Rails.logger.warn("[OopsieExceptions] #{message}")
+        else
+          warn("[OopsieExceptions] #{message}")
+        end
+      end
+
+      def log_error(message)
+        if defined?(Rails.logger) && Rails.logger
+          Rails.logger.error("[OopsieExceptions] #{message}")
+        else
+          warn("[OopsieExceptions] ERROR: #{message}")
+        end
+      end
+    end
+  end
+end

data/lib/oopsie_exceptions.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "oopsie_exceptions/version"
+require_relative "oopsie_exceptions/configuration"
+require_relative "oopsie_exceptions/context"
+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/railtie" if defined?(Rails::Railtie)
+
+module OopsieExceptions
+  REPORTED_MARKER = :@__oopsie_reported
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def report(exception, context: {}, handled: true)
+      return unless configuration.enabled
+      return if configuration.ignored?(exception)
+      return if exception.instance_variable_get(REPORTED_MARKER)
+
+      exception.instance_variable_set(REPORTED_MARKER, true)
+
+      payload = Payload.build(exception, context: context, handled: handled)
+
+      if configuration.before_notify
+        payload = configuration.before_notify.call(payload)
+        return if payload.nil?
+      end
+
+      deliver(payload)
+    end
+
+    def set_context(hash)
+      Context.merge(hash)
+    end
+
+    def clear_context
+      Context.clear
+    end
+
+    def with_context(hash)
+      previous = Context.current.dup
+      Context.merge(hash)
+      yield
+    ensure
+      Context.replace(previous)
+    end
+
+    private
+
+    def deliver(payload)
+      configuration.webhook_urls.each do |webhook|
+        if configuration.async_delivery && defined?(OopsieExceptions::DeliveryJob)
+          DeliveryJob.perform_later(
+            payload.to_json,
+            webhook.url,
+            webhook.headers.to_json
+          )
+        else
+          WebhookClient.post(webhook, payload)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: oopsie_exceptions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Troy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 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.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+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/configuration.rb
+- lib/oopsie_exceptions/context.rb
+- lib/oopsie_exceptions/error_subscriber.rb
+- lib/oopsie_exceptions/middleware.rb
+- lib/oopsie_exceptions/payload.rb
+- lib/oopsie_exceptions/railtie.rb
+- lib/oopsie_exceptions/version.rb
+- lib/oopsie_exceptions/webhook_client.rb
+homepage: https://github.com/theinventor/oopsie_exceptions
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/theinventor/oopsie_exceptions
+  changelog_uri: https://github.com/theinventor/oopsie_exceptions/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Lightweight exception capture and webhook delivery for Rails
+test_files: []