rails_nexus 2.1.0 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3deddaf8307ffc780ab2c69de90a02a6dc4c8baf8c780af2e107b08ff8798337
-  data.tar.gz: 73ab2141acb40a433ca2db21a1dd35b1a2a642ff74a1ad420be2978cfa237821
+  metadata.gz: 78f69603552ed8908670a66523d222bd7e7221fb4202133db0e4967b7676e069
+  data.tar.gz: 8fce257592b3eff5989d41dec5cd6be2a26351b64e98558ed566b889a98400a3
 SHA512:
-  metadata.gz: 7195e03556acf7084d881c264166564a02da3273feff2abbcb6ee56e93b9e5ae2e797309cd82e586ac4310ea083c7fde125e4d492b78268fcefdea19dfac58de
-  data.tar.gz: bb61711dba4e993e79ff6fab0185afe29ef4b20021fcf5c2fdc9ca79b11292bfcb005afe35ebb8fc243760e0f5513cb6a7207cefa7c225a7eb37fc43ef545675
+  metadata.gz: b8cfe97fc4a57e6dbaed6c007da8ae2045a3039ea0aee70e4cd82b654932faa4a5f8419740a494f537c31aa11b4aef837ce4cfc420e88be312e212b880de667b
+  data.tar.gz: 4b3ad524e5e0d44b008cf44e63bb2b6941f580de2a6163daa44f9079054eb69bea0100810b6e6e944da5d3a630805ae6302e89b7708d4c1577595d017f1f0667

data/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to RailsNexus will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.1] - 2026-08-23
+
+### Added
+- **Security controls** — Global fail-closed dashboard authorization, webhook destination policy controls, safe source browsing, and recursive sensitive-parameter filtering.
+- **Database compatibility CI** — SQLite, PostgreSQL, and MySQL/MariaDB coverage plus Ruby 3.2–4.0 and Rails 8.0–8.1 test matrices.
+- **Release security** — Private vulnerability reporting guidance, dependency updates, static analysis, dependency auditing, and MFA release metadata.
+- **Advanced exception filtering** — Ransack filters now cover exception type, source, message/class/source search, platform, priority, workflow status, assignee, time range, and minimum occurrence count.
+- **Sortable exception table** — Exception, platform, source, message, occurrence count, workflow priority, and last-seen columns can be sorted without leaving the Turbo Frame.
+
+### Changed
+- **Exception boundary** — New installations capture `StandardError` while fatal process and VM exceptions retain normal Ruby/Rails behavior.
+- **Frontend distribution** — RailsNexus now ships a fingerprintable prebuilt bundle and no longer requires or modifies Importmap.
+- **Portable analytics** — Time grouping is bounded and isolated for SQLite, PostgreSQL, and MySQL/MariaDB.
+- **Pagy pagination** — Replaced WillPaginate with Pagy for exception and cron-job pagination.
+- **Compact exception table** — The message column is constrained and ellipsized with the complete message available as a tooltip; source, fingerprint, workflow, assignment, and occurrence metadata are presented in a denser layout.
+- **Occurrence performance** — The exception table uses each fingerprint's stored `occurrence_count`, removing the per-row count query.
+
+### Fixed
+- **Backup process safety** — External backup tools receive validated argument arrays and secrets through protected environment/configuration channels.
+- **Webhook request safety** — Webhook delivery validates schemes, DNS results, network ranges, redirects, and host policy before connecting.
+- **Source viewer safety** — Canonical path containment and non-shell Git execution prevent path and command injection.
+- **Legacy namespace boot compatibility** — Applications that still include `RailsOps::ExceptionLoggable` can boot while migrating to `RailsNexus::ExceptionLoggable`.
+- **Unified exception query** — Legacy and Ransack filters now compose in one relation, platform filtering works independently of source filtering, and filtered bulk deletion deletes the same result set shown in the table.
+- **Filter pills** — Removing a Ransack filter pill now correctly removes its nested `q` parameter.
+- **Zero-config engine assets** — The engine registers its prebuilt JavaScript and CSS assets without depending on the host's application entry point or assets.
+- **Local Hotwire assets** — Turbo and Stimulus are served from their Rails gems instead of third-party CDN URLs, improving CSP compatibility and offline deployment.
+- **Host entry-point isolation** — RailsNexus no longer adds pins or imports to the host application's JavaScript setup.
+
+## [1.1.0] - 2026-08-22
+
+### Added
+- **Exception cause chains** — Automatically captures the full exception chain (`exception.cause`) up to 10 levels deep. New "Cause Chain" tab in the detail view shows each exception with its message and backtrace snippet.
+- **Breadcrumbs (activity trail)** — Subscribes to ActiveSupport::Notifications to capture SQL queries, controller actions, cache reads/writes, job executions, mailer deliveries, and partial renders before a crash. Thread-local ring buffer (50 entries) flushed on exception. Enable with `config.breadcrumbs_enabled = true`.
+- **Storm protection (circuit breaker)** — Prevents error floods from crashing the app with DB writes. Per-process threshold (default: 50 errors/sec), auto-opens circuit when exceeded, sheds 90% of errors, auto-resets after cooldown. Enable with `config.storm_protection_enabled = true`.
+- **User impact scoring** — Tracks `user_id` on each exception and ranks errors by unique users affected (not occurrence count). User Impact table on the dashboard shows top 5 errors. Enable with `config.user_impact_tracking = true`.
+- **System health snapshots** — Captures GC stats, memory (RSS/VSZ), thread count, DB connection pool utilization, and Ruby version at the moment of each exception. New "System Health" tab in detail view.
+- **Exception fingerprinting** — Generates SHA256 fingerprints for grouping similar exceptions. Duplicate exceptions increment an `occurrence_count` instead of creating new rows.
+- **Database health summary** — Live database stats on the Statistics page: adapter, version, ping latency, active connections, pool size, uptime, and per-table row counts.
+- **Backup status detection** — Detects the `backup` gem and shows config path, model files, backup directory stats, last backup time, storage destination, database adapters, notifiers, and crontab scheduling.
+- **Server statistics dashboard** — New `/rails_nexus/stats` page with memory, CPU, disk, Ruby/Rails info, Sidekiq stats, process info, and exception trend charts.
+- **Cron job monitoring** — New `RailsNexus::CronJob` model and `/rails_nexus/cron_jobs` page to track scheduled task runs with status, duration, hostname, and error details. Rake tasks: `rails_nexus:wrap_cron`, `rails_nexus:cron_stats`, `rails_nexus:cron_cleanup`.
+- **Webhook configuration UI** — New `/rails_nexus/settings` page to view configured webhooks, send test payloads, and see delivery history with status codes and timing.
+- **Webhook delivery logging** — Every webhook attempt (success or failure) logged to `RailsNexus::WebhookDelivery` with request/response body, status code, duration, and error message.
+- **New migration templates** — `migration_cron_jobs.rb`, `migration_webhook_deliveries.rb`, and `migration_advanced_features.rb` for the new columns and tables.
+- **New configuration options** — `breadcrumbs_enabled`, `storm_protection_enabled`, `storm_threshold_per_second`, `storm_cooldown_seconds`, `user_impact_tracking`, `show_server_stats`, `cron_job_tracking`, `log_webhook_deliveries`, and more.
+
+### Changed
+- **Sidebar navigation** — Added Statistics, Cron Jobs, and Settings links to the dashboard sidebar.
+- **Exception detail view** — New tabs for Cause Chain, Breadcrumbs, and System Health alongside existing Overview, Backtrace, Request, Environment, and User Info tabs.
+- **Exception index view** — User Impact ranking table displayed above filters when data is available.
+- **Stats controller** — Now collects system, Ruby, Sidekiq, database, backup, and storm protection stats.
+
+## [1.0.1] - 2026-08-22
+
+### Added
+- **Tailwind-like utility classes** — Embedded utility CSS (display, flexbox, spacing, typography, colors, animations, responsive breakpoints) so the dashboard works with or without Tailwind CSS.
+- **Standard Stimulus controller locations** — Moved controllers to `app/javascript/controllers/` (Stimulus's default scan path) so `bin/rails stimulus:manifest:update` registers them automatically without extra configuration.
+- **Dark mode auto-detection** — Theme controller now respects `prefers-color-scheme` media query for the `auto` theme setting, in addition to localStorage persistence.
+- **Generator template updates** — `rails_nexus:customize` now generates sidebar and theme controller templates in the standard Stimulus location with localStorage-backed theme persistence.
+
+### Fixed
+- **Theme controller localStorage persistence** — The engine's theme controller previously ignored the user's saved preference and always overwrote localStorage with the server-side default on every page load. Now it checks localStorage first, falls back to the server config, and respects system color-scheme preference.
+
+### Changed
+- **Version bumped to 1.0.1** — Indicates the Tailwind/Hotwire modernization milestone.
+- **Removed legacy Sprockets JS** — Deleted `app/assets/javascripts/rails_nexus/application.js` (the old vanilla Stimulus registration shim) since controllers now live in the standard importmap/esbuild path.
+- **Removed unused legacy image directory** — Cleaned up an unused image placeholder.
+- **Removed old `rails_nexus/controllers/` directory** — Sidebar and theme controllers moved from `app/javascript/rails_nexus/controllers/` to `app/javascript/controllers/`.
+- **Customize generator updated** — Output paths and post-install instructions reflect the new controller locations.
+- **CSS file restructured** — Utility classes are now at the top of the stylesheet above the legacy `rn-*` component styles for clearer layering.
+
+## [0.2.0] - 2026-08-21
+
+### Added
+- **Install generator** — `bin/rails generate rails_nexus:install` sets up routes, migration, and initializer in one command.
+- **Configuration DSL** — `RailsNexus.configure` block for auth, app name, per-page, and exception data.
+- **Auth by default** — `auth_block` configuration prevents unauthenticated access. Dashboard returns 403 when no auth is configured.
+- **Self-contained CSS** — Dashboard works without Tailwind CSS. Custom stylesheets are engine-provided.
+- **Database indexes** — Added indexes on `created_at`, `exception_class`, and `[controller_name, action_name]` for faster queries.
+- **Backward compatibility** — Legacy `ExceptionLoggable` class attributes still work alongside the new configuration DSL.
+
+### Fixed
+- **Message formatting** — Exception messages are no longer nil when no extra data is attached.
+- **Removed stray `.gem` files** from the repository.
+
+### Changed
+- Views use engine-scoped CSS classes instead of Tailwind utility classes.
+- Layout no longer depends on host application assets.
+
+## [0.1.1] - 2026-08-20
+
+### Added
+- `rails_nexus:tailwind:sources` rake task for Tailwind v4 source discovery.
+
+## [0.1.0] - 2024-03-30
+
+### Added
+- Initial release.
+- Exception logging via `RailsNexus::ExceptionLoggable`.
+- Dashboard with filtering, search, pagination.
+- Turbo Frames and Streams for SPA-like UX.
+- RSS feed.
+- Turbo Stream-based delete operations.

data/README.md

@@ -33,13 +33,6 @@ RailsNexus is an extensible operations and administration console for Rails appl
 - **Execution Times** — Monitor job duration and detect slow jobs
 - **Cleanup** — Automatic old job record removal
 
-### 💾 Backup Management
-- **Backup Dashboard** — Health status, model listing, recent backups
-- **File Browser** — View all backup files with size, age, and format
-- **Trigger from UI** — Run backups directly from the dashboard
-- **Settings Editor** — Configure paths, thresholds, and notifications
-- **Health Monitoring** — Alerts when backups are stale or missing
-- **Cron Schedule** — View and manage backup schedules
 
 ### 🖥️ Server Statistics
 - **Memory Usage** — RAM and swap monitoring
@@ -85,7 +78,7 @@ RailsNexus is an extensible operations and administration console for Rails appl
 
 - Ruby 3.2 or newer
 - Rails 8.0 or newer
-- A database supported by Active Record
+- SQLite 3, PostgreSQL, or MySQL/MariaDB
 
 ## Installation
 
@@ -108,10 +101,20 @@ This will:
 1. Copy the database migration with proper indexes.
 2. Create a configuration initializer at `config/initializers/rails_nexus.rb`.
 3. Mount the engine in your routes.
-4. Add `rescue_from Exception, with: :log_exception_handler` to `ApplicationController`.
+4. Add `rescue_from StandardError, with: :log_exception_handler` to `ApplicationController`.
 
 The dashboard is now available at `/rails_nexus`.
 
+Backup management is provided separately by
+[backup_nexus](https://github.com/tamiru/backup_nexus). Add it when your
+application needs the backup dashboard and runner:
+
+```ruby
+gem "backup_nexus"
+```
+
+Then run bin/rails generate backup_nexus:install.
+
 ### Optional UI customization
 
 The mounted dashboard already includes its CSS, Turbo, and Stimulus controllers.
@@ -151,6 +154,10 @@ class Api::V1::BaseController < ActionController::API
 end
 ```
 
+Older applications using `RailsOps::ExceptionLoggable` remain supported for
+boot compatibility. Update them to `RailsNexus::ExceptionLoggable` when
+convenient.
+
 ### Background jobs (Sidekiq)
 
 RailsNexus automatically logs Sidekiq job exceptions when the middleware is configured:
@@ -168,7 +175,10 @@ end
 
 The dashboard contains sensitive information. **Do not expose it to unauthenticated users.**
 
-By default, the dashboard returns `403 Forbidden` for all requests. Configure authentication:
+Authentication is applied globally by `RailsNexus::ApplicationController`,
+including workflow mutations and source-code viewing. If `auth_block` is
+missing, returns `false`/`nil`, or raises an error, every dashboard request
+returns `403 Forbidden`. Configure authentication:
 
 ```ruby
 # config/initializers/rails_nexus.rb
@@ -294,8 +304,18 @@ config.webhooks = [
 ]
 config.webhook_timeout = 5
 config.webhook_headers = { "Authorization" => "Bearer token" }
+config.webhook_allowed_hosts = ["hooks.slack.com", "*.example.com"] # optional
+config.webhook_denied_hosts = ["blocked.example.com"]
+# HTTP is only available in development, and only with this explicit opt-in:
+config.webhook_allow_http_in_development = false
 ```
 
+Webhook destinations must use HTTPS, cannot contain URL credentials, and are
+resolved and pinned to a validated public IP before connecting. Private,
+loopback, link-local, metadata, multicast, unspecified, reserved, and redirect
+destinations are rejected. Logged delivery URLs redact their path and query so
+provider tokens are not persisted.
+
 POST JSON to each URL on every new exception:
 ```json
 {
@@ -347,7 +367,7 @@ rake rails_nexus:test_webhook     # Test webhook configuration
 
 ### Hotwire (default)
 
-RailsNexus includes `importmap-rails`, `turbo-rails`, and `stimulus-rails` as dependencies. Its namespaced importmap is automatically composed into the host application, so no frontend installation step is needed.
+RailsNexus ships a prebuilt JavaScript asset containing Turbo and its namespaced Stimulus controllers. It does not require `importmap-rails`, does not modify the host JavaScript entry point, and works in hosts using Importmap, jsbundling/esbuild/Bun, or no JavaScript bundler. The bundle reuses a host Stimulus application exposed as `window.Stimulus`; otherwise it starts one engine-scoped application and reuses it across repeated loads.
 
 ### Styling
 
@@ -365,7 +385,7 @@ If your app uses Tailwind, add the gem's views as a source:
 
 #### Asset pipelines
 
-The engine registers its JavaScript path and precompile assets automatically. Both Propshaft and Sprockets hosts can mount RailsNexus without changing the host asset manifest.
+The engine registers and precompiles its fingerprintable JavaScript and CSS assets automatically. Both Propshaft and Sprockets hosts can mount RailsNexus without changing the host asset manifest.
 
 The entry point is `rails_nexus/application`; it does not replace or depend on the host app's `application` entry point. Turbo and Stimulus are served locally from their Rails gems rather than from a CDN.
 
@@ -384,7 +404,14 @@ Four controllers are included and registered by the engine's entry point:
 
 The engine creates a `rails_nexus_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.
+RailsNexus applies Rails' configured parameter filters plus built-in password, token, authorization, cookie, session, and secret filters before persistence. Application-provided free-form messages can still contain sensitive data, so apply your normal database encryption, retention, backup, and access-control policies.
+
+Analytics time grouping works on SQLite, PostgreSQL, and MySQL/MariaDB. Row counts work on all three; physical table-size and server uptime/connection metrics are displayed only where the adapter exposes them safely, and otherwise show as unavailable.
+
+
+## Security
+
+The dashboard denies every request unless `auth_block` returns a truthy value. Webhooks use HTTPS by default, resolve and pin public destinations, reject redirects and private/reserved networks, and support explicit host allow/deny lists. See [SECURITY.md](SECURITY.md) for private vulnerability reporting.
 
 ## Generators
 
@@ -414,6 +441,34 @@ gem build rails_nexus.gemspec
 
 The repository includes a Rails dummy application under `test/dummy` for engine integration testing.
 
+## CI/CD
+
+GitHub Actions runs the test matrix, database compatibility checks, asset builds,
+and security checks on pushes and pull requests. Releases are published to
+RubyGems when a version tag is pushed.
+
+Before the first release, configure a RubyGems [Trusted Publisher](https://guides.rubygems.org/trusted-publishing/)
+for:
+
+- Owner: `tamiru`
+- Repository: `rails_nexus`
+- Workflow: `release.yml`
+- GitHub environment: `release`
+
+Create the `release` environment in GitHub and add required reviewers if you
+want a manual approval before publishing. No RubyGems API key is needed.
+
+To release a version, update `lib/rails_nexus/version.rb` and `CHANGELOG.md`,
+merge the changes to `main`, then push a matching tag:
+
+```bash
+git tag v2.1.2
+git push origin v2.1.2
+```
+
+The workflow verifies that the tag matches the gem version, runs the tests,
+builds and validates the gem, then publishes it and creates the GitHub release.
+
 ## Support
 
 If you find RailsNexus useful, consider supporting the project:

data/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released RailsNexus minor version. Users should upgrade to the newest patch release before reporting an issue.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Use GitHub's private security advisory form at `https://github.com/tamiru/rails_nexus/security/advisories/new`, or email `tamiruhailu@gmail.com` if the form is unavailable.
+
+Include the affected version, impact, reproduction steps, and any suggested mitigation. You can expect an acknowledgement within seven days. Details will remain private until a fix and coordinated disclosure are ready.

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-Party Notices
+
+The prebuilt `rails_nexus/application.js` asset contains Turbo and Stimulus.
+
+- Turbo: Copyright (c) 2020 Basecamp
+- Stimulus: Copyright (c) 2021 Basecamp
+
+Both are distributed under the MIT License:
+
+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/app/assets/config/rails_nexus_manifest.js

@@ -1,2 +1,2 @@
 //= link_directory ../stylesheets/rails_nexus .css
-//= link_directory ../javascripts/rails_nexus .js
+//= link rails_nexus/application.js