exceptify 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbf40071354c10947e6fa90ef8c512db08003e84322f1ade20637107db09deb5
+  data.tar.gz: 28a5b5cfe05a3012a4f5b88d9adda06b1fe7f6257beacd4a294c630b5a360f06
+SHA512:
+  metadata.gz: 3f7077257beead584f587c93f989c30908deb06264e5c254f8013bb84841a78dab7ed6eb4964fb04e3e48fab0debb7060851801c3cb55c333961dfbe30c641f1
+  data.tar.gz: de6d0cfb74a7be063254a5c7316e7b3ad3678754582648ef93bf05754065f78320d4357a623961cf247065f0f2e7c4fb11936df913efc6a9c74446c00c16a09d

data/CHANGELOG.rdoc

@@ -0,0 +1,16 @@
+== 1.0.0
+
+First maintained release line under <tt>lukin-io/exceptify</tt>.
+
+* Rename the gem, require paths, namespace, generator, templates, and documentation to <tt>exceptify</tt>.
+* Require Ruby 3.4.4 or newer.
+* Target Rails 8.0.2 or newer for development and verification, below Rails 9.
+* Keep the supported notifier set focused on Email, Slack, Microsoft Teams, Amazon SNS, Datadog, Webhook, and custom notifiers.
+* Remove unsupported notifier integrations and stale documentation.
+* Add PORO configuration, notifier registry, dispatcher, notification, and request-context objects to keep core behavior testable.
+* Add deterministic setup validation for network notifier options.
+* Add dependency injection support for notifier clients/transports.
+* Keep Rack middleware options isolated per middleware instance.
+* Guard Rails runner hook installation from duplicate callbacks.
+* Add Solid Queue support for reporting unhandled Active Job failures.
+* Expand specs for success, failure, and edge/null/boundary behavior across the refactored core and supported notifiers.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 1.2.0](http://contributor-covenant.org/version/1/2/0/).

data/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# How to contribute
+
+Pull requests welcome! Please try to make them as complete and clear as possible, with reproduction steps and good tests.
+
+
+## Issues
+
+Issues are monitored and responded to, but pull requests are much more likely to be merged.
+
+Make sure the issue includes version information, reproduction steps, and any other relevant information.
+
+You can use the `examples/sample_app.rb` to help reproduce the issue.
+
+
+## Pull Requests
+
+All PRs with changes will be reviewed and merged if possible. Thank you for taking the time to contribute.
+
+Changes must include tests. Please include a description of the problem and why the change is needed. Same with issues, reproduction steps are helpful.
+
+
+### Running the tests
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+And running the linting with [standard](https://github.com/standardrb/standard):
+
+```bash
+bundle exec standardrb
+```

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2011-2016 Sebastian Martinez
+Copyright (c) 2005-2010 Jamis Buck
+
+The MIT License (MIT)
+
+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,534 @@
+# Exceptify
+
+[![Gem Version](https://badge.fury.io/rb/exceptify.svg)](https://badge.fury.io/rb/exceptify)
+[![Build Status](https://github.com/lukin-io/exceptify/actions/workflows/ci.yml/badge.svg)](https://github.com/lukin-io/exceptify/actions/workflows/ci.yml)
+
+Exceptify sends exception reports from Rails and Rack applications to the channels your team already watches: email, chat, webhooks, and monitoring tools.
+
+This repository is maintained by [@lukin-io](https://github.com/lukin-io) as `lukin-io/exceptify` with the `exceptify` gem name and `Exceptify` API. Version `1.0.0` starts the maintained Exceptify release line.
+
+## Quick Start
+
+Add the gem to your Rails application's `Gemfile`:
+
+```ruby
+gem "exceptify"
+```
+
+Install it and generate the initializer:
+
+```bash
+bundle install
+bundle exec rails generate exceptify:install
+```
+
+Configure at least one notifier:
+
+```ruby
+# config/initializers/exceptify.rb
+require "exceptify/rails"
+require "exceptify/rake"
+
+Exceptify.configure do |config|
+  config.add_notifier :email, {
+    email_prefix: "[#{Rails.env.upcase}] ",
+    sender_address: %("Exceptify" <notifier@example.com>),
+    exception_recipients: %w[exceptions@example.com]
+  }
+
+  config.ignore_if do |_exception, _options|
+    Rails.env.local?
+  end
+end
+```
+
+Email delivery uses your application's ActionMailer configuration. See [ActionMailer configuration](docs/notifiers/email.md#actionmailer-configuration) if emails do not send.
+
+## How To Test It
+
+After configuring a notifier, trigger a real exception in a non-production environment.
+
+```ruby
+# config/routes.rb
+get "/exceptify_test", to: proc {
+  raise "Exceptify test"
+}
+```
+
+Start Rails, visit `/exceptify_test`, and confirm the notification arrives. Remove the route after testing.
+
+## Contents
+
+* [Quick Start](#quick-start)
+* [How To Test It](#how-to-test-it)
+* [What It Does](#what-it-does)
+* [Compatibility](#compatibility)
+* [Installation](#installation)
+* [Rails Setup](#rails-setup)
+* [Common Workflows](#common-workflows)
+* [Notifiers](#notifiers)
+* [Noise Control](#noise-control)
+* [Production Checklist](#production-checklist)
+* [Background Jobs](#background-jobs)
+* [Rack and Sinatra](#rack-and-sinatra)
+* [Maintenance](#maintenance)
+* [Development](#development)
+* [License](#license)
+
+## What It Does
+
+Exceptify installs a Rack middleware that watches for unhandled exceptions during web requests and sends a notification with request, session, environment, backtrace, and optional application data.
+
+Use it when you want a small, self-hosted notification layer for exceptions without adopting a hosted error tracker.
+
+It supports:
+
+* Rails integration through a generator and initializer.
+* Rack middleware configuration for Rails, Sinatra, and other Rack apps.
+* Built-in notifiers for email, Slack, Teams, Amazon SNS, Datadog, and webhooks.
+* Manual reporting for rescued exceptions, background jobs, scripts, rake tasks, and runners.
+* Ignore rules, crawler filtering, per-notifier filtering, and repeated-error grouping.
+
+## Compatibility
+
+* Exceptify 1.0.0 or newer.
+* Ruby 3.4.4 or newer.
+* Rails 8.0.2 or newer, below Rails 9.
+* Rack applications, including Sinatra.
+
+The changelog starts at `1.0.0` for the maintained `exceptify` release line.
+
+## Installation
+
+Add the gem to your application's `Gemfile`:
+
+```ruby
+gem "exceptify"
+```
+
+Install it:
+
+```bash
+bundle install
+```
+
+To use this maintained repository directly from Git:
+
+```ruby
+gem "exceptify", git: "https://github.com/lukin-io/exceptify.git"
+```
+
+For local gem development, point a test application at your checkout:
+
+```ruby
+gem "exceptify", path: "../exceptify"
+```
+
+If the application should keep a Git source in its `Gemfile` while Bundler uses a local checkout, configure a local override from that application:
+
+```bash
+bundle config set local.exceptify ../exceptify
+bundle install
+```
+
+## Rails Setup
+
+Generate the Rails initializer:
+
+```bash
+bundle exec rails generate exceptify:install
+```
+
+The generated file is written to `config/initializers/exceptify.rb`.
+
+Keep the gem available to every environment that loads the initializer. If you want notifications only in production, keep the gem outside a `production`-only bundle group and add an ignore rule for local environments.
+
+### Initializer Notes
+
+The generated initializer should load the Rails and Rake integrations, then register one or more notifiers. The email example in [Quick Start](#quick-start) is enough for a first setup; add other notifiers from [Notifiers](#notifiers) as needed.
+
+### Rails Runner Support
+
+If you want `rails runner` commands to report exceptions, load the Rails integration from `config/application.rb` below `Bundler.require`:
+
+```ruby
+# config/application.rb
+require "exceptify/rails"
+```
+
+The initializer is too late for runner callbacks. You can still keep notifier configuration in `config/initializers/exceptify.rb`.
+The runner hook is guarded, so loading the integration more than once does not install duplicate `at_exit` callbacks.
+
+## Common Workflows
+
+### Send to Email and Slack
+
+Slack notifications require the `slack-notifier` gem:
+
+```ruby
+gem "slack-notifier"
+```
+
+Then register both notifiers:
+
+```ruby
+Exceptify.configure do |config|
+  config.add_notifier :email, {
+    email_prefix: "[#{Rails.env.upcase}] ",
+    sender_address: %("Exceptify" <notifier@example.com>),
+    exception_recipients: %w[exceptions@example.com]
+  }
+
+  if (webhook_url = Rails.application.credentials.dig(:slack, :exceptions_webhook_url))
+    config.add_notifier :slack, {
+      webhook_url: webhook_url,
+      channel: "#exceptions",
+      additional_parameters: {
+        mrkdwn: true
+      }
+    }
+  end
+end
+```
+
+### Attach Request Context
+
+Store application data in the request environment before an exception is raised:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :prepare_exceptify_notification
+
+  private
+
+  def prepare_exceptify_notification
+    request.env["exceptify.exception_data"] = {
+      current_user_id: current_user&.id,
+      account_id: current_account&.id,
+      request_id: request.request_id
+    }
+  end
+end
+```
+
+That data is included in supported notifier payloads and email sections.
+
+### Report a Handled Controller Error
+
+Middleware only sees exceptions that continue up the Rack stack. If a controller rescues an error, notify manually:
+
+```ruby
+class OrdersController < ApplicationController
+  rescue_from PaymentGateway::Timeout, with: :payment_gateway_timeout
+
+  private
+
+  def payment_gateway_timeout(exception)
+    Exceptify.notify_exception(
+      exception,
+      env: request.env,
+      data: {
+        order_id: params[:id],
+        request_id: request.request_id
+      }
+    )
+
+    render json: {error: "payment_gateway_timeout"}, status: :bad_gateway
+  end
+end
+```
+
+### Report from Plain Ruby Code
+
+```ruby
+begin
+  ImportCustomers.call(file_path)
+rescue => exception
+  Exceptify.notify_exception(
+    exception,
+    data: {
+      job: "ImportCustomers",
+      file_path: file_path
+    }
+  )
+
+  raise
+end
+```
+
+### Filter Sensitive Parameters
+
+Exception emails can include request parameters. Use Rails parameter filtering for secrets:
+
+```ruby
+# config/application.rb
+config.filter_parameters += [
+  :password,
+  :password_confirmation,
+  :credit_card_number,
+  :secret_details
+]
+```
+
+## Notifiers
+
+Built-in notifier docs and support status:
+
+| Notifier | Status | Docs |
+| --- | --- | --- |
+| Email | Supported | [Email](docs/notifiers/email.md) |
+| Slack | Supported | [Slack](docs/notifiers/slack.md) |
+| Teams | Supported | [Teams](docs/notifiers/teams.md) |
+| Amazon SNS | Supported | [Amazon SNS](docs/notifiers/sns.md) |
+| Datadog | Supported | [Datadog](docs/notifiers/datadog.md) |
+| WebHook | Supported | [WebHook](docs/notifiers/webhook.md) |
+| Custom notifiers | Supported extension point | [Custom notifiers](docs/notifiers/custom.md) |
+
+### Notifier Setup Rules
+
+Network notifiers validate required options during setup. Missing `webhook_url`, `url`, or AWS credentials raise `ArgumentError` instead of silently disabling notifications.
+
+For tests, custom transports, or apps that already wrap provider clients, pass an injected client:
+
+```ruby
+Exceptify.configure do |config|
+  config.add_notifier :webhook, {
+    url: "https://example.com/exception-webhook",
+    http_client: MyHTTPClient
+  }
+
+  config.add_notifier :sns, {
+    topic_arn: "arn:aws:sns:us-east-1:123456789012:exceptions",
+    client: Aws::SNS::Client.new(region: "us-east-1")
+  }
+end
+```
+
+Slack accepts `notifier:` for a prebuilt Slack client. Use `fail_silently: true` only as a temporary compatibility option while migrating old silent configurations.
+
+You can also register any object that responds to `#call(exception, options)`:
+
+```ruby
+Exceptify.configure do |config|
+  config.add_notifier :logger, lambda { |exception, options|
+    Rails.logger.error(
+      "[exceptify] #{exception.class}: #{exception.message} #{options[:data].inspect}"
+    )
+  }
+end
+```
+
+## Noise Control
+
+### Ignore Known Exceptions
+
+```ruby
+Exceptify.configure do |config|
+  config.ignored_exceptions += %w[
+    ActionView::TemplateError
+    MyApp::ExpectedError
+  ]
+end
+```
+
+The default ignored exceptions include common routing, record-not-found, and invalid-parameter errors.
+
+### Ignore Crawlers
+
+```ruby
+Exceptify.configure do |config|
+  config.ignore_crawlers %w[Googlebot bingbot]
+end
+```
+
+### Ignore by Condition
+
+```ruby
+Exceptify.configure do |config|
+  config.ignore_if do |exception, options|
+    path = options.dig(:env, "PATH_INFO")
+
+    Rails.env.local? ||
+      path == "/health" ||
+      exception.message.match?(/Couldn't find Page with ID=/)
+  end
+end
+```
+
+### Ignore Only One Notifier
+
+Use per-notifier filtering when email should still send but chat should stay quiet, or the reverse:
+
+```ruby
+Exceptify.configure do |config|
+  config.ignore_notifier_if(:slack) do |exception, _options|
+    exception.is_a?(ActionController::RoutingError)
+  end
+end
+```
+
+### Group Repeated Errors
+
+Error grouping prevents notification floods for the same exception. With the default trigger, notifications are sent at counts 1, 2, 4, 8, 16, and so on.
+
+```ruby
+Exceptify.configure do |config|
+  config.error_grouping = true
+  config.error_grouping_cache = Rails.cache
+  config.error_grouping_period = 5.minutes
+
+  config.notification_trigger = lambda { |_exception, count|
+    count == 1 || (count % 10).zero?
+  }
+end
+```
+
+## Production Checklist
+
+Before relying on exception notifications in production:
+
+* Configure at least one notifier.
+* Verify delivery with a real test exception in staging.
+* Confirm ActionMailer delivery settings if using email.
+* Filter secrets with `config.filter_parameters`.
+* Ignore local and test environments.
+* Add crawler or health-check ignores if they create noise.
+* Enable error grouping for high-traffic applications.
+* Make sure background jobs are covered separately from web requests.
+
+## Background Jobs
+
+The Rack middleware only catches exceptions during web requests. For jobs and command-line work, use one of the integrations below.
+
+### Rake Tasks
+
+The generated initializer includes:
+
+```ruby
+require "exceptify/rake"
+```
+
+That reports unhandled exceptions from rake tasks.
+
+### Rails Runner
+
+For `rails runner`, require the Rails integration from `config/application.rb` as shown in [Rails Runner Support](#rails-runner-support).
+
+### Sidekiq, Resque, and Solid Queue
+
+Generate an initializer with the integration you need:
+
+```bash
+bundle exec rails generate exceptify:install --sidekiq
+```
+
+or:
+
+```bash
+bundle exec rails generate exceptify:install --resque
+```
+
+or:
+
+```bash
+bundle exec rails generate exceptify:install --solid-queue
+```
+
+The Solid Queue integration hooks into Active Job failure notifications and reports unhandled exceptions for jobs using the `solid_queue` adapter. It preserves Active Job failure behavior, so failed jobs still end up in Solid Queue's failed executions table and `retry_on` or `discard_on` handlers still run normally.
+
+### Manual Job Reporting
+
+If a job system is not integrated, report exceptions directly:
+
+```ruby
+class RebuildSearchIndexJob
+  def perform(account_id)
+    RebuildSearchIndex.call(account_id)
+  rescue => exception
+    Exceptify.notify_exception(
+      exception,
+      data: {
+        job: self.class.name,
+        account_id: account_id
+      }
+    )
+
+    raise
+  end
+end
+```
+
+## Rack and Sinatra
+
+Use the Rack middleware directly when you are not using the Rails generator, or when you need Rack-only options such as `ignore_cascade_pass`.
+
+```ruby
+require "exceptify"
+
+use Exceptify::Rack,
+  email: {
+    email_prefix: "[RACK ERROR] ",
+    sender_address: %("Exceptify" <notifier@example.com>),
+    exception_recipients: %w[exceptions@example.com]
+  },
+  ignore_exceptions: ["Sinatra::NotFound"],
+  ignore_cascade_pass: true
+```
+
+Options passed directly to `Exceptify::Rack` are local to that middleware instance. To use one application-wide configuration, configure `Exceptify` once and mount the middleware without notifier options:
+
+```ruby
+require "exceptify"
+
+Exceptify.configure do |config|
+  config.add_notifier :email, {
+    sender_address: %("Exceptify" <notifier@example.com>),
+    exception_recipients: %w[exceptions@example.com]
+  }
+end
+
+use Exceptify::Rack
+```
+
+Sinatra users can also review the [example application](examples/sinatra).
+
+## Maintenance
+
+This repository is the current home for the `exceptify` gem. Maintenance focuses on modern Ruby and Rails support, clear documentation, and practical bug fixes around the `Exceptify` API.
+
+Issues and pull requests are welcome when they include enough context to reproduce the behavior.
+The current refactoring direction is tracked in [REFACTORING.md](REFACTORING.md).
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+Open a console with the gem loaded:
+
+```bash
+bundle exec rake console
+```
+
+Build the gem locally:
+
+```bash
+bundle exec rake build
+```
+
+Pull requests and issues are welcome. Please read the [Contributing Guide](CONTRIBUTING.md) and follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Released under the [MIT license](MIT-LICENSE).
+
+Maintainer: [@lukin-io](https://github.com/lukin-io)

data/RELEASING.md

@@ -0,0 +1,51 @@
+# Releasing Exceptify
+
+## First RubyGems.org Publish
+
+The `exceptify` gem is built from `exceptify.gemspec`. RubyGems.org receives the
+built `.gem` file, not the Git repository.
+
+Run the first publish manually:
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec standardrb
+gem build --strict exceptify.gemspec
+gem signin
+gem push exceptify-1.0.0.gem
+```
+
+RubyGems.org versions are immutable. If a pushed gem needs any code or metadata
+change, bump `Exceptify::VERSION` and publish a new version.
+
+## Trusted Publishing Setup
+
+After the first publish, configure RubyGems.org Trusted Publishing for automated
+tag releases:
+
+- Gem name: `exceptify`
+- GitHub repository owner: `lukin-io`
+- GitHub repository name: `exceptify`
+- Workflow filename: `gem-push.yml`
+- Environment: `release`
+
+The workflow publishes tagged releases to both GitHub Packages and RubyGems.org.
+RubyGems.org publishing uses GitHub OIDC through `rubygems/release-gem@v1`, so no
+long-lived `RUBYGEMS_AUTH_TOKEN` secret is needed.
+
+## Release Flow
+
+1. Update `Exceptify::VERSION` in `lib/exceptify/version.rb`.
+2. Update `CHANGELOG.rdoc`.
+3. Commit the changes.
+4. Create a matching tag:
+
+   ```sh
+   git tag v1.0.0
+   git push origin main
+   git push origin v1.0.0
+   ```
+
+The CI workflow verifies that the tag name matches the gem version before
+publishing.