Merge pull request #85 from eclectic-coding/feat/custom-dashboard-cards

feat: custom dashboard cards and nav links

Author: eclectic-coding

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - i18n support
+- Custom dashboard cards — `config.dashboard_cards` accepts an array of `{ title:, stats:, link: }` hashes; each card is rendered after the built-in queue stat cards on the dashboard; `stats:` is a lambda returning a `{ label => value }` hash evaluated at render time; `link:` is an optional `{ label:, url: }` header link
+- Custom nav links — `config.nav_links` accepts an array of `{ label:, url: }` hashes appended to the main navigation bar after the built-in links
 
 ### Changed
 

Gemfile.lock

@@ -342,7 +342,6 @@ CHECKSUMS
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
-  bundler (4.0.13) sha256=19f08be7f27022cf0b89f27da0b044ae075e8270a9ef44ad248a932614e1ca3b
   bundler-audit (0.9.3) sha256=81c8766c71e47d0d28a0f98c7eed028539f21a6ea3cd8f685eb6f42333c9b4e9
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a

README.md

@@ -35,6 +35,9 @@ A monitoring and management dashboard for [Solid Queue](https://github.com/rails
 - [Read replica support](#read-replica-support)
 - [i18n](#i18n)
   - [Adding a custom locale](#adding-a-custom-locale)
+- [Extensibility](#extensibility)
+  - [Custom dashboard cards](#custom-dashboard-cards)
+  - [Custom nav links](#custom-nav-links)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
 - [License](#license)
@@ -102,6 +105,8 @@ SolidQueueWeb surfaces all of this in a browser UI available at any route you ch
 - **Error frequency report** — `GET /jobs/failed_jobs/errors` groups all failed jobs by error class and message prefix, shows a count per group, and surfaces a sample backtrace in an expandable row; sorted by count descending so the most common errors appear first; accessible via the "Error Summary" button on the Failed Jobs page
 - **Metrics / health endpoint** — `GET /jobs/metrics.json` returns a machine-readable JSON document with job counts, throughput, per-queue depth and pause state, and process health summary; suitable for Prometheus scraping, uptime monitors, or external dashboards; `slow_jobs` count included when `slow_job_threshold` is configured
 - **i18n** — all UI strings (page titles, table headers, buttons, empty states, flash messages) are backed by `config/locales/en.yml`; locale switching via `?locale=` param or session; add a custom locale by supplying a YAML file in your host app and registering it with `config.available_locales`
+- **Custom dashboard cards** — `config.dashboard_cards` accepts an array of `{ title:, stats:, link: }` hashes rendered after the built-in queue stat cards; `stats:` is a lambda returning a `{ label => value }` hash evaluated at render time; `link:` is an optional header link
+- **Custom nav links** — `config.nav_links` accepts an array of `{ label:, url: }` hashes appended to the main navigation bar after the built-in links
 
 [↑ Back to top](#table-of-contents)
 
@@ -174,6 +179,8 @@ SolidQueueWeb.configure do |config|
   config.connects_to                = { reading: :reading, writing: :writing } # read replica (default: nil)
   config.time_zone                  = "America/New_York" # display timezone for all timestamps (default: nil = UTC)
   config.available_locales          = [:en, :fr]         # locales available for switching (default: [:en])
+  config.nav_links                  = [{ label: "Admin", url: "/admin" }] # extra nav links (default: [])
+  config.dashboard_cards            = [{ title: "My App", stats: -> { { "Users" => User.count } } }] # custom stat cards (default: [])
 end
 
 SolidQueueWeb.authenticate do
@@ -451,6 +458,51 @@ Rails will pick up the file automatically via its standard `config.i18n.load_pat
 
 ---
 
+## Extensibility
+
+### Custom dashboard cards
+
+`config.dashboard_cards` adds custom stat cards to the dashboard after the built-in queue cards. Each card accepts three keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `title` | String | Card heading (required) |
+| `link` | `{ label:, url: }` | Optional header link rendered top-right |
+| `stats` | Lambda | Optional — called at render time; must return a `{ label => value }` hash |
+
+```ruby
+SolidQueueWeb.configure do |config|
+  config.dashboard_cards = [
+    {
+      title: "My App",
+      link:  { label: "View Admin", url: "/admin" },
+      stats: -> { { "Users" => User.count, "Premium" => User.premium.count } }
+    }
+  ]
+end
+```
+
+The `stats` lambda runs on every dashboard render, so keep it fast. Defaults to `[]` — no custom cards appear when unconfigured.
+
+### Custom nav links
+
+`config.nav_links` appends extra links to the main navigation bar after the built-in links. Use it to link back to your host application's admin pages or related tools.
+
+```ruby
+SolidQueueWeb.configure do |config|
+  config.nav_links = [
+    { label: "Back to App", url: "/" },
+    { label: "Admin",       url: "/admin" }
+  ]
+end
+```
+
+Defaults to `[]` — no extra links appear when unconfigured.
+
+[↑ Back to top](#table-of-contents)
+
+---
+
 ## Roadmap
 
 See [ROADMAP.md](ROADMAP.md) for the full post-1.0 feature plan, organized by release milestone.

ROADMAP.md

@@ -6,11 +6,4 @@ Pull requests for any of these are welcome. See [Contributing](README.md#contrib
 
 ---
 
-## v1.6 — Extensibility
-
-*Breaking changes or large architectural additions — planned only if community demand warrants it.*
-
-| Feature | Notes |
-|---|---|
-| **Custom dashboard cards** | Registration hook so host apps can add their own stat cards alongside queue stats. |
-| **Custom nav links** | `config.nav_links = [{ label: "Admin", url: "/admin" }]` to integrate the dashboard into the host app's navigation. |
+No items currently planned. Open an issue to suggest a feature.

app/assets/stylesheets/solid_queue_web/_04_table.css

@@ -19,6 +19,34 @@
   font-weight: 600;
 }
 
+.sqd-card__body {
+  padding: 0.75rem 1rem;
+  display: flex;
+  flex-direction: column;
+}
+
+.sqd-custom-stat {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  font-size: 13px;
+  padding: 0.375rem 0;
+  border-bottom: 1px solid var(--border);
+}
+
+.sqd-custom-stat:last-child {
+  border-bottom: none;
+}
+
+.sqd-custom-stat__label {
+  color: var(--muted);
+}
+
+.sqd-custom-stat__value {
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
 table {
   width: 100%;
   border-collapse: collapse;

app/views/layouts/solid_queue_web/application.html.erb

@@ -27,6 +27,9 @@
           <li><%= link_to t("solid_queue_web.layout.nav.processes"),  processes_path,       class: current_page?(processes_path) ? "active" : "",       aria: { current: current_page?(processes_path) ? "page" : nil } %></li>
           <li><%= link_to t("solid_queue_web.layout.nav.search"),     search_path,          class: current_page?(search_path) ? "active" : "",          aria: { current: current_page?(search_path) ? "page" : nil } %></li>
           <li><%= link_to t("solid_queue_web.layout.nav.audit"),      audit_path,           class: current_page?(audit_path) ? "active" : "",           aria: { current: current_page?(audit_path) ? "page" : nil } %></li>
+          <% SolidQueueWeb.nav_links.each do |link| %>
+            <li><%= link_to link[:label], link[:url] %></li>
+          <% end %>
         </ul>
       </nav>
     </div>

app/views/solid_queue_web/dashboard/index.html.erb

@@ -196,5 +196,26 @@
       </div>
     </div>
   <% end %>
+
+  <% SolidQueueWeb.dashboard_cards.each do |card| %>
+    <div class="sqd-card">
+      <div class="sqd-card__header">
+        <span class="sqd-card__title"><%= card[:title] %></span>
+        <% if card[:link] %>
+          <%= link_to card[:link][:label], card[:link][:url], class: "sqd-btn sqd-btn--muted sqd-btn--sm" %>
+        <% end %>
+      </div>
+      <% if card[:stats] %>
+        <div class="sqd-card__body">
+          <% card[:stats].call.each do |label, value| %>
+            <div class="sqd-custom-stat">
+              <span class="sqd-custom-stat__label"><%= label %></span>
+              <span class="sqd-custom-stat__value"><%= value %></span>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
 </div>
 <% end %>

lib/solid_queue_web.rb

@@ -7,7 +7,7 @@ class << self
     attr_writer :page_size, :dashboard_refresh_interval, :default_refresh_interval, :search_results_limit,
                 :slow_job_threshold, :alert_webhook_url, :alert_failure_threshold, :alert_webhook_cooldown,
                 :alert_queue_thresholds, :alert_slow_job_count_threshold, :alert_stale_process_threshold,
-                :connects_to, :time_zone, :available_locales
+                :connects_to, :time_zone, :available_locales, :nav_links, :dashboard_cards
 
     def page_size
       @page_size || 25
@@ -65,6 +65,14 @@ def available_locales
       @available_locales || %i[en]
     end
 
+    def nav_links
+      @nav_links || []
+    end
+
+    def dashboard_cards
+      @dashboard_cards || []
+    end
+
     def configure
       yield self
     end

spec/controllers/solid_queue_web/application_controller_spec.rb

@@ -46,6 +46,35 @@ def index
     end
   end
 
+  describe "#record_audit" do
+    controller(SolidQueueWeb::ApplicationController) do
+      skip_before_action :authenticate!
+
+      def create
+        record_audit("test_action")
+        render plain: "ok"
+      end
+    end
+
+    it "logs an error and does not raise when AuditEvent.create! fails" do
+      allow(SolidQueueWeb::AuditEvent).to receive(:create!).and_raise(ActiveRecord::RecordInvalid)
+      expect(Rails.logger).to receive(:error).with(/Audit log failed/)
+      post :create
+      expect(response).to have_http_status(:ok)
+    end
+  end
+
+  describe "#resolve_current_actor" do
+    after { SolidQueueWeb.instance_variable_set(:@current_actor, nil) }
+
+    it "logs an error and returns nil when the current_actor block raises" do
+      SolidQueueWeb.current_actor { raise "identity error" }
+      expect(Rails.logger).to receive(:error).with(/current_actor block failed/)
+      result = controller.send(:resolve_current_actor)
+      expect(result).to be_nil
+    end
+  end
+
   describe "#replica_configured?" do
     it "returns false when only role is configured" do
       expect(controller.send(:replica_configured?, { role: :writing })).to be false

spec/generators/solid_queue_web/migrations_generator_spec.rb

@@ -0,0 +1,30 @@
+require "rails_helper"
+require "rails/generators"
+require "rails/generators/testing/assertions"
+require "rails/generators/testing/setup_and_teardown"
+require "rails/generators/testing/behavior"
+require "generators/solid_queue_web/install/migrations_generator"
+
+RSpec.describe SolidQueueWeb::Install::MigrationsGenerator do
+  include Rails::Generators::Testing::Behavior
+  include Rails::Generators::Testing::Assertions
+  include FileUtils
+
+  tests SolidQueueWeb::Install::MigrationsGenerator
+  destination File.expand_path("../../../tmp/generator_test", __dir__)
+
+  before { prepare_destination }
+
+  describe "#create_migration_file" do
+    before { run_generator }
+
+    it "creates the audit events migration file" do
+      assert_migration "db/migrate/create_solid_queue_web_audit_events.rb"
+    end
+
+    it "defines the solid_queue_web_audit_events table in the migration" do
+      assert_migration "db/migrate/create_solid_queue_web_audit_events.rb",
+                       /create_table :solid_queue_web_audit_events/
+    end
+  end
+end