faultline-rails 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c846154434391fa5b6aff599c9c6f70dfd2d90690d5ce2050be6d284cd2d5c39
-  data.tar.gz: 3191607d7ef2b2f0694d0a10e0a54899ddd4569dd007adba6d9f4e4bc09c50f2
+  metadata.gz: 870d33f7e1f9311ee4e932c60c0b430f91a5bf3f5e2e5c446bf69753647f8eda
+  data.tar.gz: 36a4dfce3b186ad20c60f849cc0d7a220579014bf44aa630dab6843d4bd68efa
 SHA512:
-  metadata.gz: 89a84d8d6ff2955fa71be82b7deef6100e10953548ef381cde60b2e0df57bd3fa07403899900d8ce85bb1ee11ca66ee316472062e77baedceccde538812cf65b
-  data.tar.gz: d63e16bf9eba501733ef42b694fb1315da801fa544579d2c5db999ee547841d2c7879247573f374303283e7aec100cbef436d4e9e5a608074270efebdda0567d
+  metadata.gz: f9311ba143ef33928040c5fcbe360fcd71fd2741d1f03f7793eac409545c988b9c3043c019f64217a0d907a7dde4d593cc5c9e0fffdd8aae9d4d0e334a0b3de2
+  data.tar.gz: 7cdae081decc10a6c3d8c406486aec7887fd89ee0d388c7da2da26ea8c7597fb62d34b56912feb7e20263fbb5d745409c36dd2aae57066a648d379e8caf10219

data/README.md

@@ -1,14 +1,31 @@
 # Faultline Rails
 
-Faultline is a production-friendly exception dashboard for Rails 8. It records unhandled application exceptions and gives your team a fast, searchable view of messages, requests, environments, and backtraces.
+[![Gem Version](https://badge.fury.io/rb/faultline-rails.svg)](https://rubygems.org/gems/faultline-rails)
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa)](https://github.com/sponsors/tamiru)
 
-The dashboard is server-rendered and progressively enhanced with:
+Faultline is a production-friendly exception dashboard for Rails 8. It records unhandled application exceptions and gives your team a fast, searchable view of messages, requests, environments, and backtraces.
 
-- **Tailwind CSS** layout that works with or without Tailwind installed.
-- **Ransack** for advanced search and sortable columns.
-- Turbo Frames for filtering and opening exception details without full-page navigation.
-- Turbo Streams for deleting one, many, or all exceptions.
-- Stimulus for loading state and small interaction behavior.
+The dashboard features a polished dark/light theme, keyboard shortcuts, tabbed detail view, stats overview, and webhook notifications.
+
+## Features
+
+- **Dark / Light theme** — Toggle with the sun/moon button or press `t`. Remembers preference in localStorage.
+- **Keyboard shortcuts** — Press `?` to see all shortcuts. Navigate with `j`/`k`, focus search with `/`, open details with `Enter`.
+- **Stats overview** — Total, weekly, today, and unique class counts at a glance.
+- **Advanced filters** — Exception type, controller, time range, and full-text search with debounced input.
+- **Tabbed detail view** — Overview, Backtrace, Request, Environment, and User Info tabs.
+- **Prev/Next navigation** — Navigate between exceptions without returning to the list.
+- **Copy to clipboard** — One-click copy for exception ID, message, and backtrace.
+- **Collapsible backtrace** — Long traces collapse automatically; expand on demand.
+- **Metadata grid** — Structured detail cards for exception class, controller, action, time, IP, and user agent.
+- **Page size selector** — Choose 25, 50, or 100 results per page.
+- **Active filter pills** — See and dismiss active filters with one click.
+- **RSS feed** — Subscribe to `/faultline/logged_exceptions/feed.rss`.
+- **Webhook notifications** — POST to Slack, Discord, or custom endpoints on each new exception.
+- **Telegram notifications** — Built-in notifier with rate limiting.
+- **Sidekiq middleware** — Automatically logs background job exceptions.
+- **Cleanup / Retention** — Auto-delete old exceptions via rake tasks.
+- **Structured logging** — JSON log output with request context and metadata.
 
 ## Requirements
 
@@ -25,7 +42,7 @@ Add Faultline to your application:
 gem "faultline-rails"
 ```
 
-Run the install generator to set up everything in one step:
+Run the install generator:
 
 ```bash
 bundle install
@@ -37,53 +54,74 @@ This will:
 1. Copy the database migration with proper indexes.
 2. Create a configuration initializer at `config/initializers/faultline.rb`.
 3. Mount the engine in your routes.
-4. Add `rescue_from Exception, with: :log_exception_handler` to your `ApplicationController` for Rails 8 compatibility.
+4. Add `rescue_from Exception, with: :log_exception_handler` to `ApplicationController`.
 
 The dashboard is now available at `/faultline`.
 
-> **Note:** The generator mounts the engine at `/faultline` by default. You can change the mount path by editing `config/routes.rb`.
+### Modern UI setup
+
+Generate the polished dark/light theme with keyboard shortcuts:
+
+```bash
+bin/rails generate faultline:customize
+bin/rails stimulus:manifest:update
+```
+
+This generates:
+- Self-contained layout with sidebar, topbar, and theme toggle
+- Tabbed detail view with metadata grid
+- Keyboard shortcuts dialog
+- Stimulus controllers for theme, sidebar, and interactions
+
+Options: `--layout-only`, `--views-only`, `--stimulus-only`, `--initializer-only`
 
 ## Start logging exceptions
 
 Include `Faultline::ExceptionLoggable` in your application controller:
 
 ```ruby
-# app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
   include Faultline::ExceptionLoggable
 end
 ```
 
-Faultline logs the exception and then re-raises it so Rails keeps its normal error handling, status codes, and error pages.
+Faultline logs the exception and then re-raises it so Rails keeps its normal error handling.
 
-### Rails 8+ compatibility
+### API controllers
 
-Faultline's initializer automatically adds `rescue_from Exception, with: :log_exception_handler` to your `ApplicationController`. This ensures exceptions are logged even when Rails' built-in `rescue_action` pattern is no longer used.
+For `ActionController::API` subclasses (e.g., API namespaces):
 
-If you need to handle this manually:
+```ruby
+class Api::V1::BaseController < ActionController::API
+  include Faultline::ExceptionLoggable
+end
+```
+
+### Background jobs (Sidekiq)
+
+Faultline automatically logs Sidekiq job exceptions when the middleware is configured:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  rescue_from Exception, with: :log_exception_handler
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add FaultlineSidekiqMiddleware
+  end
 end
 ```
 
 ## Protect the dashboard
 
-The dashboard contains sensitive information, including request parameters, environment variables, and source paths. **Do not expose it to unauthenticated public users.**
+The dashboard contains sensitive information. **Do not expose it to unauthenticated users.**
 
-By default, the dashboard returns `403 Forbidden` for all requests. Configure authentication in your initializer:
+By default, the dashboard returns `403 Forbidden` for all requests. Configure authentication:
 
 ```ruby
 # config/initializers/faultline.rb
 Rails.application.config.to_prepare do
   Faultline.configure do |config|
     config.auth_block = lambda do |controller|
-      # Return true if the user is authorized to view the dashboard.
-      # Examples:
-      controller.authenticate_user!  # Devise
-      # controller.current_user&.admin?  # Custom auth
-      # false  # Block everyone (default)
+      controller.current_user&.admin?
     end
   end
 end
@@ -91,171 +129,255 @@ end
 
 ## Configuration
 
-Configure Faultline through the block-style DSL in your initializer:
-
 ```ruby
 # config/initializers/faultline.rb
 Rails.application.config.to_prepare do
   Faultline.configure do |config|
-    # Dashboard title
-    config.application_name = "Acme"
-
-    # Items per page (default: 30)
-    config.per_page = 50
+    # ─── General ─────────────────────────────────────────────
+    config.application_name = "My App"       # Dashboard title
+    config.per_page = 50                     # Items per page (default: 30)
 
-    # Authentication block (see "Protect the dashboard" above)
+    # ─── Authentication ──────────────────────────────────────
     config.auth_block = lambda do |controller|
       controller.current_user&.admin?
     end
-  end
-end
-```
 
-You can also attach additional application data to each recorded exception:
+    # ─── Exception Data ──────────────────────────────────────
+    config.exception_data = lambda do |controller|
+      {
+        user_id: controller.current_user&.id,
+        request_id: controller.request.request_id,
+        environment: Rails.env
+      }
+    end
 
-```ruby
-config.exception_data = lambda do |controller|
-  {
-    request_id: controller.request.request_id,
-    user_id: controller.current_user&.id,
-    user_email: controller.current_user&.email,
-    environment: Rails.env
-  }
+    # ─── Notifications ───────────────────────────────────────
+    config.after_create = lambda do |exception|
+      MyNotifier.alert(exception)
+    end
+
+    config.webhooks = ["https://hooks.slack.com/services/xxx"]
+    config.webhook_timeout = 5
+    config.webhook_headers = { "Authorization" => "Bearer token" }
+
+    # ─── Cleanup ─────────────────────────────────────────────
+    config.retention_days = 90               # Auto-delete after N days
+
+    # ─── Appearance ──────────────────────────────────────────
+    config.theme = "auto"                    # "light", "dark", or "auto"
+    config.body_class = ""                   # Custom body CSS class
+    config.use_host_layout = false           # Use host app's layout
+
+    # ─── Advanced UI ─────────────────────────────────────────
+    config.show_stats = true                 # Stats overview cards
+    config.keyboard_shortcuts = true         # Keyboard shortcuts
+    config.enable_navigation = true          # Prev/next in detail view
+    config.backtrace_limit = 30              # Frames before collapse
+    config.show_metadata = true              # Metadata grid
+    config.show_environment = false          # Environment tab
+    config.show_request = true               # Request params tab
+    config.page_size_options = [25, 50, 100] # Page size selector
+
+    # ─── Sidebar Links ───────────────────────────────────────
+    config.sidebar_links = [
+      { label: "GitHub", url: "https://github.com/myorg/myapp" },
+      { label: "Docs", url: "/docs" }
+    ]
+
+    # ─── Logging ─────────────────────────────────────────────
+    config.logging_enabled = true
+    config.log_level = :info                 # :debug, :info, :warn, :error, :fatal
+    config.log_file = "log/faultline.log"    # JSON log file (nil = none)
+    config.log_backtrace = true
+    config.log_params = true
+    config.log_user_info = true
+    config.log_backtrace_limit = 20
+    config.deduplication_enabled = false
+    config.deduplication_window = 300        # Seconds
+  end
 end
 ```
 
-Exclude trusted private networks from the dashboard's local-request handling:
+## Keyboard shortcuts
 
-```ruby
-class ApplicationController < ActionController::Base
-  include Faultline::ExceptionLoggable
+Press `?` in the dashboard to see all shortcuts:
 
-  consider_local "10.0.0.0/8", "192.168.0.0/16"
-end
-```
+| Key | Action |
+|---|---|
+| `/` | Focus search |
+| `j` or `↓` | Navigate down |
+| `k` or `↑` | Navigate up |
+| `Enter` | Open selected exception |
+| `p` or `←` | Previous exception |
+| `n` or `→` | Next exception |
+| `t` | Toggle dark/light theme |
+| `1`-`5` | Switch tabs |
+| `Esc` | Close panel / Clear |
+| `?` | Show shortcuts dialog |
 
-Rails' `filter_parameters` configuration is respected before request parameters are stored.
+## Search & Filter
 
-## Search & Filter (Ransack)
+- **Exception Type** — Select dropdown, auto-submits on change
+- **Controller** — Select dropdown, auto-submits on change
+- **Time Range** — Today, 3 days, 7 days, 30 days
+- **Search** — Full-text search with 400ms debounce
+- **Active Filters** — Pills with one-click dismiss
 
-Faultline includes [Ransack](https://github.com/activerecord-hackery/ransack) for advanced search and filtering. The dashboard provides:
+All filters work with Ransack for advanced search, or fall back to built-in scopes.
 
-- **Search form** — Search by exception class, controller name, and message text.
-- **Sortable columns** — Click column headers to sort by exception class, controller, action, or date.
-- **Sidebar filters** — Quick filter by exception class, controller/action, and time range (today, 3 days, 7 days, 30 days).
+## Notifications
 
-If your app doesn't include Ransack, Faultline falls back to the built-in sidebar filters automatically.
+### Webhooks
 
-### Searching
+```ruby
+config.webhooks = [
+  "https://hooks.slack.com/services/T00/B00/xxx",
+  "https://discord.com/api/webhooks/xxx"
+]
+config.webhook_timeout = 5
+config.webhook_headers = { "Authorization" => "Bearer token" }
+```
 
-Type in the search form fields and click "Search" to filter exceptions:
+POST JSON to each URL on every new exception:
+```json
+{
+  "exception_class": "RuntimeError",
+  "controller_name": "users",
+  "action_name": "show",
+  "message": "Something went wrong",
+  "created_at": "2026-08-22T12:00:00Z",
+  "dashboard_url": "http://localhost:3000/faultline/logged_exceptions/42"
+}
+```
 
-- **Exception Class** — Search by exception type (e.g., `RuntimeError`, `ActiveRecord::RecordNotFound`)
-- **Controller** — Search by controller name (e.g., `users`, `posts`)
-- **Message** — Full-text search across exception messages
+### Telegram
 
-### Sorting
+Set `TELEGRAM_TOKEN` and `TELEGRAM_CHAT_ID` environment variables:
 
-Click any column header in the exceptions table to sort:
+```bash
+export TELEGRAM_TOKEN="your-bot-token"
+export TELEGRAM_CHAT_ID="your-chat-id"
+```
 
-- **Exception** — Sort alphabetically by exception class
-- **Controller** — Sort by controller name
-- **Action** — Sort by action name
-- **Date** — Sort by creation date (newest/oldest first)
+Configure the notifier:
 
-## Frontend setup
+```ruby
+config.after_create = lambda do |exception|
+  Faultline::TelegramNotifier.new.notify(exception)
+end
+```
 
-### Hotwire (default)
+Rate limiting: 10-minute cooldown per exception class + controller combination.
 
-Faultline includes `turbo-rails` and `stimulus-rails` as dependencies. If your Rails app already has Hotwire installed (the default for Rails 8), no extra setup is needed.
+## Cleanup / Retention
 
-If you need to install Hotwire:
+```ruby
+config.retention_days = 90  # Auto-delete after 90 days
+```
+
+Rake tasks:
 
 ```bash
-bin/rails turbo:install
-bin/rails stimulus:install
+rake faultline:cleanup          # Delete exceptions older than retention_days
+rake faultline:stats            # Show exception statistics
+rake faultline:tail             # Tail JSON logs in real-time
+rake faultline:export           # Export exceptions to JSON
+rake faultline:test_webhook     # Test webhook configuration
 ```
 
-### Styling
+## Frontend setup
 
-Faultline ships with its own built-in CSS stylesheet that works out of the box. No Tailwind configuration is required.
+### Hotwire (default)
 
-#### Tailwind CSS
+Faultline includes `turbo-rails` and `stimulus-rails` as dependencies. For Rails 8, no extra setup is needed.
 
-If your application uses Tailwind CSS, Faultline's views are already Tailwind-styled and will automatically use your Tailwind theme.
+### Styling
 
-If you want to configure the gem's view directory as a Tailwind source, use the absolute path returned by Bundler:
+Faultline ships with its own CSS (`faultline/dashboard.css`) that works out of the box with dark/light themes.
 
-```bash
-bundle show faultline-rails
-```
+#### Tailwind CSS
 
-For Tailwind CSS v4, add a source entry:
+If your app uses Tailwind, add the gem's views as a source:
 
 ```css
+/* Tailwind v4 */
 @import "tailwindcss";
-@source "/absolute/path/to/faultline-rails/app/views";
+@source "/path/to/faultline-rails/app/views";
 ```
 
-For Tailwind CSS v3, add the gem path to `content` in `tailwind.config.js`:
+#### Esbuild / Propshaft
 
-```javascript
-const faultlinePath = "/absolute/path/to/faultline-rails"
+The layout automatically detects your asset pipeline and loads `application.js`:
 
-module.exports = {
-  content: [
-    "./app/views/**/*.{erb,html}",
-    `${faultlinePath}/app/views/**/*.html.erb`
-  ]
-}
+```erb
+<% if defined?(Propshaft) || Rails.application.assets&.find_asset("application.js") %>
+  <%= javascript_include_tag "application", "data-turbo-track": "reload", type: "module" %>
+<% elsif respond_to?(:javascript_importmap_tags) %>
+  <%= javascript_importmap_tags %>
+<% end %>
 ```
 
-#### Non-importmap projects
-
-Faultline works with **importmap**, **sprockets**, **propshaft**, or **no JS pipeline** at all. The layout adapts to your asset pipeline:
+#### Importmap
 
-- If `javascript_importmap_tags` is available, it uses importmap.
-- If `turbo_refreshes_with` is available, it enables Turbo morph scrolling.
-- If neither is available, the dashboard works without JavaScript.
+Works automatically. Run `stimulus:manifest:update` to register the faultline controllers.
 
-### Bootstrap / Other CSS frameworks
+### Stimulus controllers
 
-Faultline's views use Tailwind CSS utility classes. To use Bootstrap or another framework:
+Three controllers are included:
 
-1. Override the views by copying them to your app:
-   ```bash
-   cp -r $(bundle show faultline-rails)/app/views/faultline app/views/faultline
-   ```
-2. Rewrite the Tailwind classes with your framework's classes.
-3. The built-in CSS in `faultline/application.css` provides fallback styles.
+| Controller | Registered as | Purpose |
+|---|---|---|
+| `faultline_controller.js` | `faultline` | Keyboard nav, search, tabs, copy, backtrace expand |
+| `faultline_sidebar_controller.js` | `faultline-sidebar` | Mobile drawer toggle |
+| `faultline_theme_controller.js` | `faultline-theme` | Dark/light/auto theme toggle |
 
-## Dashboard features
-
-- **Search** — Full-text search across exception messages, classes, and controllers.
-- **Sortable columns** — Sort by exception class, controller, action, or date.
-- **Filter** — Filter by exception class, controller/action, or age.
-- **Exception details** — Open full exception details in a Turbo Frame.
-- **Delete** — Delete individual exceptions without leaving the page.
-- **Bulk delete** — Delete the currently visible result set.
-- **Clear history** — Clear the complete exception history.
-- **RSS feed** — Subscribe to `/faultline/logged_exceptions/feed.rss`.
+Run `bin/rails stimulus:manifest:update` after installing to auto-register them.
 
 ## Data storage
 
-The engine creates a `faultline_logged_exceptions` table containing the exception class, controller/action, message, backtrace, request, environment, user information, user agent, remote IP, and timestamps.
+The engine creates a `faultline_logged_exceptions` table with columns for exception class, controller/action, message, backtrace, request, environment, user information, user agent, remote IP, and timestamps.
 
 Exception records can contain secrets. Apply your normal database encryption, retention, backup, and access-control policies.
 
+## Generators
+
+| Generator | Description |
+|---|---|
+| `rails generate faultline:install` | Full setup (migration, initializer, routes) |
+| `rails generate faultline:install --modern` | Install + generate all customizations |
+| `rails generate faultline:customize` | Generate customizable views, layout, and JS |
+| `rails generate faultline:customize --layout-only` | Only the layout |
+| `rails generate faultline:customize --views-only` | Only the views |
+| `rails generate faultline:customize --stimulus-only` | Only the Stimulus controller |
+
 ## Development
 
-Run the test suite with:
+Run the test suite:
 
 ```bash
-bin/rails test
+cd /path/to/faultline-rails
+RAILS_ENV=test bundle exec rails test
+```
+
+Build the gem:
+
+```bash
+gem build faultline-rails.gemspec
 ```
 
 The repository includes a Rails dummy application under `test/dummy` for engine integration testing.
 
+## Support
+
+If you find Faultline useful, consider supporting the project:
+
+- ⭐ **Star the repo** — Help others discover Faultline
+- 🐛 **Report issues** — Help improve the gem
+- 💡 **Contribute** — Submit pull requests
+- 💰 **Sponsor** — [GitHub Sponsors](https://github.com/sponsors/tamiru)
+
+Your support helps maintain and improve Faultline for the Rails community.
+
 ## License
 
 Faultline Rails is released under the [MIT License](MIT-LICENSE).