solid_stack_web 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a146449291d2d1e6bc46612021b6abf939a08f969fda923afceeb863323bf672
-  data.tar.gz: 6499cd93a4db8268bbf637bfb5934e3777ec124eea3f44ccea877188c7c83ed1
+  metadata.gz: 85093a248316f7f8921636f68bdc08e2053e496eeb85f17bbbd7cddac57e4ed6
+  data.tar.gz: 3321fa62f08ce3615f733740cfac444d60ed65960b9adc9e4894919416482b46
 SHA512:
-  metadata.gz: be0e30ea4fa72ef666e82cefddd3936a99196bd43f809e546fa37bb59bfed39ed267b07b42268479baed8210303762d0629c49bb15c9cbb3661090b295bad91e
-  data.tar.gz: 7bc30e8a5a62929ed893bc1189f3b141c52add6489f423f39076a7565219d419a9a60568f5faae9b7dbfb503c8f74144bab1a91f6d7db065b654c9ed2d2e29d7
+  metadata.gz: 278a4dbde1baa31bb57f58c72d41ea13ef9ddbb83043839228abb4cb0ab06286c4ca954d63ee0c2f2e6914a1b8c24f946731b73afe8db1176ba28a8c157c6b52
+  data.tar.gz: f6b953b896ba256d03e26f802ab594d9e822fbd114ce68f6b7f673d435fceca8009a9ec2c55ea0f45a6dacfcebb34b9b9c23c64564faa212e00a8450292d95c4

data/README.md

@@ -29,6 +29,75 @@ mount SolidStackWeb::Engine, at: "/solid_stack"
 
 The dashboard will be available at `/solid_stack` (or whatever path you choose).
 
+### Install generator
+
+Run the install generator to create a documented initializer and wire up the mount point in one step:
+
+```bash
+rails generate solid_stack_web:install
+```
+
+This creates `config/initializers/solid_stack_web.rb` with every configuration option commented inline, and injects `mount SolidStackWeb::Engine, at: "/solid_stack"` into `config/routes.rb`.
+
+---
+
+## Metrics endpoint
+
+`GET /metrics` (relative to your mount path) returns a JSON payload suitable for external monitoring tools, uptime checkers, or custom alerting:
+
+```json
+{
+  "queue": {
+    "ready": 4,
+    "scheduled": 1,
+    "claimed": 2,
+    "blocked": 0,
+    "failed": 3,
+    "done_1h": 45,
+    "done_24h": 312,
+    "processes_healthy": 2,
+    "processes_stale": 0,
+    "slow_jobs": 7
+  },
+  "cache": { "entries": 1024, "byte_size": 2097152, "oldest_entry": "2026-05-20T10:00:00Z" },
+  "cable": { "messages": 50, "channels": 3, "messages_per_hour": 12, "oldest_message": "2026-05-20T10:00:00Z", "top_channels": { "ActionCable::Channel::Base": 30, "ChatChannel": 15, "NotificationsChannel": 5 } },
+  "generated_at": "2026-05-26T10:00:00Z"
+}
+```
+
+`slow_jobs` is only present when `slow_job_threshold` is configured. The endpoint is protected by the same authentication as the rest of the dashboard.
+
+---
+
+## General configuration
+
+Create an initializer at `config/initializers/solid_stack_web.rb`:
+
+```ruby
+SolidStackWeb.configure do |config|
+  # Number of items per paginated page (default: 25)
+  config.page_size = 50
+
+  # Authentication — block runs in controller context.
+  # Return a truthy value to allow access; falsy falls back to HTTP Basic.
+  config.authenticate do
+    current_user&.admin?
+  end
+end
+```
+
+### Authentication
+
+The `authenticate` block is evaluated in the context of each request's controller instance, so any helper method available to controllers (e.g. `current_user` from Devise) works directly. If the block returns `false` or `nil`, the engine falls back to HTTP Basic authentication. If no `authenticate` block is configured, the dashboard is open.
+
+### Linking to the dashboard
+
+`SolidStackWeb.mount_path` returns the path at which the engine is mounted, derived automatically from your routes. Use it to link to the dashboard from your application layout without hardcoding the path:
+
+```ruby
+link_to "Queue Dashboard", SolidStackWeb.mount_path
+```
+
 ---
 
 ## Solid Queue
@@ -128,57 +197,6 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
 
 ---
 
-## Metrics endpoint
-
-`GET /metrics` (relative to your mount path) returns a JSON payload suitable for external monitoring tools, uptime checkers, or custom alerting:
-
-```json
-{
-  "queue": {
-    "ready": 4,
-    "scheduled": 1,
-    "claimed": 2,
-    "blocked": 0,
-    "failed": 3,
-    "done_1h": 45,
-    "done_24h": 312,
-    "processes_healthy": 2,
-    "processes_stale": 0,
-    "slow_jobs": 7
-  },
-  "cache": { "entries": 1024, "byte_size": 2097152, "oldest_entry": "2026-05-20T10:00:00Z" },
-  "cable": { "messages": 50, "channels": 3, "messages_per_hour": 12, "oldest_message": "2026-05-20T10:00:00Z", "top_channels": { "ActionCable::Channel::Base": 30, "ChatChannel": 15, "NotificationsChannel": 5 } },
-  "generated_at": "2026-05-26T10:00:00Z"
-}
-```
-
-`slow_jobs` is only present when `slow_job_threshold` is configured. The endpoint is protected by the same authentication as the rest of the dashboard.
-
----
-
-## General configuration
-
-Create an initializer at `config/initializers/solid_stack_web.rb`:
-
-```ruby
-SolidStackWeb.configure do |config|
-  # Number of items per paginated page (default: 25)
-  config.page_size = 50
-
-  # Authentication — block runs in controller context.
-  # Return a truthy value to allow access; falsy falls back to HTTP Basic.
-  config.authenticate do
-    current_user&.admin?
-  end
-end
-```
-
-### Authentication
-
-The `authenticate` block is evaluated in the context of each request's controller instance, so any helper method available to controllers (e.g. `current_user` from Devise) works directly. If the block returns `false` or `nil`, the engine falls back to HTTP Basic authentication. If no `authenticate` block is configured, the dashboard is open.
-
----
-
 ## Requirements
 
 - Ruby >= 3.3

data/app/assets/stylesheets/solid_stack_web/_01_base.css

@@ -31,3 +31,15 @@ a:hover { text-decoration: underline; }
 .sqw-monospace { font-family: ui-monospace, "SFMono-Regular", Menlo, monospace; font-size: 13px; }
 .sqw-muted     { color: var(--muted); }
 .sqw-truncate  { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+.sqw-sr-only {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0;
+}
+
+.sqw-skip-link {
+  position: absolute; top: -100%; left: 0; z-index: 9999;
+  padding: 0.5rem 1rem; background: var(--accent); color: #fff;
+  font-weight: 600; text-decoration: none; border-radius: 0 0 4px 0;
+}
+.sqw-skip-link:focus { top: 0; }

data/app/controllers/solid_stack_web/application_controller.rb

@@ -9,6 +9,13 @@ module SolidStackWeb
     before_action :authenticate!
     around_action :with_database_connection
 
+    rescue_from StandardError do |exception|
+      raise exception if Rails.application.config.consider_all_requests_local
+      render_internal_server_error
+    end
+
+    rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+
     helper_method :current_section
 
     private
@@ -43,5 +50,13 @@ module SolidStackWeb
     def request_basic_auth
       request_http_basic_authentication("Solid Stack Dashboard")
     end
+
+    def render_not_found
+      render "solid_stack_web/errors/not_found", status: :not_found
+    end
+
+    def render_internal_server_error
+      render "solid_stack_web/errors/internal_server_error", status: :internal_server_error
+    end
   end
 end

data/app/controllers/solid_stack_web/jobs_controller.rb

@@ -5,8 +5,11 @@ module SolidStackWeb
     before_action :require_discardable, only: [:destroy]
 
     def index
-      @queue_options    = Job::EXECUTION_MODELS[@status].joins(:job).distinct.pluck("solid_queue_jobs.queue_name").sort
-      @priority_options = Job::EXECUTION_MODELS[@status].joins(:job).distinct.pluck("solid_queue_jobs.priority").sort
+      pairs = Job::EXECUTION_MODELS[@status].joins(:job)
+                .distinct
+                .pluck("solid_queue_jobs.queue_name", "solid_queue_jobs.priority")
+      @queue_options    = pairs.map(&:first).uniq.sort
+      @priority_options = pairs.map(&:last).uniq.sort
 
       respond_to do |format|
         format.html { @pagy, @executions = pagy(filtered_scope) }

data/app/controllers/solid_stack_web/queues_controller.rb

@@ -1,16 +1,11 @@
 module SolidStackWeb
   class QueuesController < ApplicationController
     def index
-      queue_names = ::SolidQueue::ReadyExecution.distinct.pluck(:queue_name)
-      paused      = ::SolidQueue::Pause.pluck(:queue_name).to_set
+      counts = ::SolidQueue::ReadyExecution.group(:queue_name).count
+      paused = ::SolidQueue::Pause.pluck(:queue_name).to_set
 
-      @queues = queue_names.sort.map do |name|
-        {
-          name:   name,
-          size:   ::SolidQueue::ReadyExecution.where(queue_name: name).count,
-          paused: paused.include?(name)
-        }
-      end
+      @queues = counts.map { |name, size| { name:, size:, paused: paused.include?(name) } }
+                      .sort_by { |q| q[:name] }
 
       @sparklines = @queues.each_with_object({}) do |queue, h|
         h[queue[:name]] = QueueDepthSparkline.new(queue[:name])

data/app/models/solid_stack_web/cache_size_stats.rb

@@ -18,16 +18,20 @@ module SolidStackWeb
     end
 
     def buckets
-      @buckets ||= BUCKETS.map do |b|
-        scope = ::SolidCache::Entry.all
-        scope = scope.where("byte_size >= ?", b[:min]) if b[:min] > 0
-        scope = scope.where("byte_size < ?",  b[:max]) if b[:max]
-        { label: b[:label], count: scope.count }
+      @buckets ||= begin
+        row = ::SolidCache::Entry.pluck(
+          Arel.sql("COALESCE(SUM(CASE WHEN byte_size < 1024 THEN 1 ELSE 0 END), 0)"),
+          Arel.sql("COALESCE(SUM(CASE WHEN byte_size >= 1024 AND byte_size < 10240 THEN 1 ELSE 0 END), 0)"),
+          Arel.sql("COALESCE(SUM(CASE WHEN byte_size >= 10240 AND byte_size < 102400 THEN 1 ELSE 0 END), 0)"),
+          Arel.sql("COALESCE(SUM(CASE WHEN byte_size >= 102400 AND byte_size < 1048576 THEN 1 ELSE 0 END), 0)"),
+          Arel.sql("COALESCE(SUM(CASE WHEN byte_size >= 1048576 THEN 1 ELSE 0 END), 0)")
+        ).first || Array.new(5, 0)
+        BUCKETS.zip(row).map { |b, count| { label: b[:label], count: count.to_i } }
       end
     end
 
     def total
-      @total ||= ::SolidCache::Entry.count
+      @total ||= buckets.sum { |b| b[:count] }
     end
   end
 end

data/app/views/layouts/solid_stack_web/application.html.erb

@@ -11,10 +11,11 @@
   <%= javascript_importmap_tags "solid_stack_web" %>
 </head>
 <body data-controller="theme">
+  <a href="#main-content" class="sqw-skip-link">Skip to main content</a>
   <header class="sqw-header">
     <div class="sqw-header__inner">
       <%= link_to "Solid Stack", root_path, class: "sqw-header__logo" %>
-      <nav class="sqw-nav">
+      <nav class="sqw-nav" aria-label="Main navigation">
         <%= link_to "Queue", jobs_path,
               class: "sqw-nav__link#{" sqw-nav__link--active" if current_section == :queue}" %>
         <%= link_to "Cache", cache_path,
@@ -28,7 +29,7 @@
   </header>
 
   <% if current_section == :cache %>
-    <nav class="sqw-subnav">
+    <nav class="sqw-subnav" aria-label="Cache section">
       <div class="sqw-subnav__inner">
         <%= link_to "Overview", cache_path,
               class: "sqw-subnav__link#{" sqw-subnav__link--active" if controller_name == "cache"}" %>
@@ -39,7 +40,7 @@
   <% end %>
 
   <% if current_section == :cable %>
-    <nav class="sqw-subnav">
+    <nav class="sqw-subnav" aria-label="Cable section">
       <div class="sqw-subnav__inner">
         <%= link_to "Overview", cable_path,
               class: "sqw-subnav__link#{" sqw-subnav__link--active" if controller_name == "cable"}" %>
@@ -48,7 +49,7 @@
   <% end %>
 
   <% if current_section == :queue %>
-    <nav class="sqw-subnav">
+    <nav class="sqw-subnav" aria-label="Queue section">
       <div class="sqw-subnav__inner">
         <%= link_to "Jobs", jobs_path,
               class: "sqw-subnav__link#{" sqw-subnav__link--active" if controller_name == "jobs"}" %>
@@ -68,7 +69,7 @@
     </nav>
   <% end %>
 
-  <main class="sqw-main">
+  <main id="main-content" class="sqw-main">
     <div id="sqw-flash-container">
       <% flash.each do |type, message| %>
         <div class="sqw-flash sqw-flash--<%= type %>"><%= message %></div>

data/app/views/solid_stack_web/cable/index.html.erb

@@ -50,9 +50,9 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>Channel</th>
-        <th>Messages</th>
-        <th>Last Message</th>
+        <th scope="col">Channel</th>
+        <th scope="col">Messages</th>
+        <th scope="col">Last Message</th>
       </tr>
     </thead>
     <tbody>

data/app/views/solid_stack_web/cable_messages/index.html.erb

@@ -23,9 +23,9 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>ID</th>
-        <th>Payload</th>
-        <th>Sent</th>
+        <th scope="col">ID</th>
+        <th scope="col">Payload</th>
+        <th scope="col">Sent</th>
       </tr>
     </thead>
     <tbody>
@@ -42,7 +42,7 @@
       <% end %>
     </tbody>
   </table>
-  <%== @pagy.series_nav if @pagy.pages > 1 %>
+  <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
 <% else %>
   <div class="sqw-empty">
     <% if @search.present? %>

data/app/views/solid_stack_web/cache/index.html.erb

@@ -20,9 +20,9 @@
       <table class="sqw-table">
         <thead>
           <tr>
-            <th>Range</th>
-            <th>Entries</th>
-            <th></th>
+            <th scope="col">Range</th>
+            <th scope="col">Entries</th>
+            <th scope="col"><span class="sqw-sr-only">Distribution</span></th>
           </tr>
         </thead>
         <tbody>
@@ -48,8 +48,8 @@
       <table class="sqw-table">
         <thead>
           <tr>
-            <th>Key</th>
-            <th>Size</th>
+            <th scope="col">Key</th>
+            <th scope="col">Size</th>
           </tr>
         </thead>
         <tbody>

data/app/views/solid_stack_web/cache_entries/index.html.erb

@@ -26,7 +26,7 @@
     <thead>
       <tr>
         <% [["key", "Key"], ["byte_size", "Size"], ["created_at", "Created"]].each do |col, label| %>
-          <th>
+          <th scope="col">
             <% next_dir = (@sort["column"] == col && @sort["direction"] == "desc") ? "asc" : "desc" %>
             <%= link_to cache_entries_path(q: @search, column: col, direction: next_dir) do %>
               <%= label %>
@@ -36,7 +36,7 @@
             <% end %>
           </th>
         <% end %>
-        <th></th>
+        <th scope="col"><span class="sqw-sr-only">Actions</span></th>
       </tr>
     </thead>
     <tbody>
@@ -58,7 +58,7 @@
       <% end %>
     </tbody>
   </table>
-  <%== @pagy.series_nav if @pagy.pages > 1 %>
+  <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
 <% else %>
   <div class="sqw-empty">
     <% if @search.present? %>

data/app/views/solid_stack_web/errors/internal_server_error.html.erb

@@ -0,0 +1,8 @@
+<div class="sqw-page-header">
+  <h1 class="sqw-page-title">Something Went Wrong</h1>
+</div>
+
+<div class="sqw-empty">
+  <p class="sqw-empty__title">500 &mdash; An unexpected error occurred.</p>
+  <p class="sqw-empty__hint"><%= link_to "Back to Dashboard", root_path, class: "sqw-btn sqw-btn--secondary" %></p>
+</div>

data/app/views/solid_stack_web/errors/not_found.html.erb

@@ -0,0 +1,8 @@
+<div class="sqw-page-header">
+  <h1 class="sqw-page-title">Not Found</h1>
+</div>
+
+<div class="sqw-empty">
+  <p class="sqw-empty__title">404 &mdash; The record you&rsquo;re looking for doesn&rsquo;t exist or has been removed.</p>
+  <p class="sqw-empty__hint"><%= link_to "Back to Dashboard", root_path, class: "sqw-btn sqw-btn--secondary" %></p>
+</div>

data/app/views/solid_stack_web/failed_jobs/index.html.erb

@@ -29,14 +29,14 @@
       <table class="sqw-table">
         <thead>
           <tr>
-            <th><input type="checkbox" class="sqw-checkbox" aria-label="Select all"
+            <th scope="col"><input type="checkbox" class="sqw-checkbox" aria-label="Select all"
                        data-selection-target="selectAll"
                        data-action="change->selection#selectAll"></th>
-            <th>Job Class</th>
-            <th>Queue</th>
-            <th>Error</th>
-            <th>Failed At</th>
-            <th></th>
+            <th scope="col">Job Class</th>
+            <th scope="col">Queue</th>
+            <th scope="col">Error</th>
+            <th scope="col">Failed At</th>
+            <th scope="col"><span class="sqw-sr-only">Actions</span></th>
           </tr>
         </thead>
         <tbody>
@@ -62,7 +62,7 @@
           <% end %>
         </tbody>
       </table>
-      <%== @pagy.series_nav if @pagy.pages > 1 %>
+      <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
     </div>
   <% else %>
     <div class="sqw-empty">

data/app/views/solid_stack_web/history/index.html.erb

@@ -45,10 +45,10 @@
     <table class="sqw-table">
       <thead>
         <tr>
-          <th>Job Class</th>
-          <th>Queue</th>
-          <th>Duration</th>
-          <th>Finished At</th>
+          <th scope="col">Job Class</th>
+          <th scope="col">Queue</th>
+          <th scope="col">Duration</th>
+          <th scope="col">Finished At</th>
         </tr>
       </thead>
       <tbody>
@@ -66,7 +66,7 @@
         <% end %>
       </tbody>
     </table>
-    <%== @pagy.series_nav if @pagy.pages > 1 %>
+    <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
   </div>
 <% else %>
   <div class="sqw-empty">

data/app/views/solid_stack_web/jobs/index.html.erb

@@ -96,16 +96,16 @@
         <thead>
           <tr>
             <% if SolidStackWeb::Job::DISCARDABLE.include?(@status) %>
-              <th><input type="checkbox" class="sqw-checkbox" aria-label="Select all"
+              <th scope="col"><input type="checkbox" class="sqw-checkbox" aria-label="Select all"
                          data-selection-target="selectAll"
                          data-action="change->selection#selectAll"></th>
             <% end %>
-            <th>Job Class</th>
-            <th>Queue</th>
-            <th>Priority</th>
-            <th>Enqueued At</th>
-            <% if @status == "scheduled" %><th>Scheduled At</th><% end %>
-            <th></th>
+            <th scope="col">Job Class</th>
+            <th scope="col">Queue</th>
+            <th scope="col">Priority</th>
+            <th scope="col">Enqueued At</th>
+            <% if @status == "scheduled" %><th scope="col">Scheduled At</th><% end %>
+            <th scope="col"><span class="sqw-sr-only">Actions</span></th>
           </tr>
         </thead>
         <tbody>
@@ -149,7 +149,7 @@
           <% end %>
         </tbody>
       </table>
-      <%== @pagy.series_nav if @pagy.pages > 1 %>
+      <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
     </div>
   <% else %>
     <%= render "empty" %>

data/app/views/solid_stack_web/processes/index.html.erb

@@ -8,11 +8,11 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>Kind</th>
-        <th>Name</th>
-        <th>PID</th>
-        <th>Host</th>
-        <th>Last Heartbeat</th>
+        <th scope="col">Kind</th>
+        <th scope="col">Name</th>
+        <th scope="col">PID</th>
+        <th scope="col">Host</th>
+        <th scope="col">Last Heartbeat</th>
       </tr>
     </thead>
     <tbody>

data/app/views/solid_stack_web/queues/index.html.erb

@@ -6,11 +6,11 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Size</th>
-        <th>Depth (12h)</th>
-        <th>Status</th>
-        <th></th>
+        <th scope="col">Name</th>
+        <th scope="col">Size</th>
+        <th scope="col">Depth (12h)</th>
+        <th scope="col">Status</th>
+        <th scope="col"><span class="sqw-sr-only">Actions</span></th>
       </tr>
     </thead>
     <tbody>

data/app/views/solid_stack_web/queues/show.html.erb

@@ -35,10 +35,10 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>Job Class</th>
-        <th>Priority</th>
-        <th>Enqueued At</th>
-        <th></th>
+        <th scope="col">Job Class</th>
+        <th scope="col">Priority</th>
+        <th scope="col">Enqueued At</th>
+        <th scope="col"><span class="sqw-sr-only">Actions</span></th>
       </tr>
     </thead>
     <tbody>
@@ -59,7 +59,7 @@
       <% end %>
     </tbody>
   </table>
-  <%== @pagy.series_nav if @pagy.pages > 1 %>
+  <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
 <% else %>
   <div class="sqw-empty">
     <p>No ready jobs in <strong><%= @queue_name %></strong>.</p>

data/app/views/solid_stack_web/recurring_tasks/index.html.erb

@@ -6,14 +6,14 @@
   <table class="sqw-table">
     <thead>
       <tr>
-        <th>Key</th>
-        <th>Schedule</th>
-        <th>Job / Command</th>
-        <th>Queue</th>
-        <th>Next Run</th>
-        <th>Last Run</th>
-        <th>Type</th>
-        <th></th>
+        <th scope="col">Key</th>
+        <th scope="col">Schedule</th>
+        <th scope="col">Job / Command</th>
+        <th scope="col">Queue</th>
+        <th scope="col">Next Run</th>
+        <th scope="col">Last Run</th>
+        <th scope="col">Type</th>
+        <th scope="col"><span class="sqw-sr-only">Actions</span></th>
       </tr>
     </thead>
     <tbody>

data/app/views/solid_stack_web/stats/index.html.erb

@@ -15,7 +15,7 @@
           ["min",        "Min"],
           ["max",        "Max"]
         ].each do |col, label| %>
-          <th>
+          <th scope="col" <%= "aria-sort=\"#{@direction == 'asc' ? 'ascending' : 'descending'}\"".html_safe if @sort == col %>>
             <% next_dir = (@sort == col && @direction == "desc") ? "asc" : "desc" %>
             <%= link_to stats_path(sort: col, direction: next_dir) do %>
               <%= label %>

data/lib/generators/solid_stack_web/install/install_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators/base"
+
+module SolidStackWeb
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a SolidStackWeb initializer and mounts the engine in routes.rb"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/solid_stack_web.rb"
+      end
+
+      def mount_engine
+        route 'mount SolidStackWeb::Engine, at: "/solid_stack"'
+      end
+    end
+  end
+end

data/lib/generators/solid_stack_web/install/templates/initializer.rb

@@ -0,0 +1,51 @@
+SolidStackWeb.configure do |config|
+  # Authentication — block runs in controller context.
+  # Return a truthy value to allow access; falsy falls back to HTTP Basic auth.
+  # If omitted entirely, the dashboard is open to anyone.
+  #
+  #   config.authenticate do
+  #     current_user&.admin?
+  #   end
+
+  # Number of records shown per paginated page (default: 25).
+  # config.page_size = 25
+
+  # Database connection — pass a connects_to hash when Solid Queue / Cache / Cable
+  # live on a separate database from your primary.
+  #
+  #   config.connects_to = { database: { writing: :queue, reading: :queue } }
+
+  # Slow-job threshold in seconds (default: nil — stat hidden).
+  # When set, the dashboard shows a "Slow (24h)" count on the overview card
+  # for finished jobs whose wall time exceeded this value.
+  # config.slow_job_threshold = 30
+
+  # Auto-refresh intervals in milliseconds.
+  # config.dashboard_refresh_interval = 5_000   # overview dashboard
+  # config.default_refresh_interval   = 10_000  # jobs, processes, history
+
+  # Maximum number of results returned by the search feature (default: 25).
+  # config.search_results_limit = 25
+
+  # Show the raw serialised value on the cache entry detail page (default: false).
+  # Disable for stores that contain sensitive data.
+  # config.allow_value_preview = false
+
+  # Link to the dashboard from anywhere in your app without hardcoding the path:
+  #
+  #   link_to "Queue Dashboard", SolidStackWeb.mount_path
+  #
+  # SolidStackWeb.mount_path is derived automatically from your routes — no
+  # configuration needed.
+
+  # Alert webhook — POST to this URL when a threshold is breached.
+  # Delivery failures are silently swallowed; configure a cooldown to avoid storms.
+  #
+  # config.alert_webhook_url       = "https://hooks.example.com/my-alert"
+  # config.alert_failure_threshold = 10      # fire when failed jobs >= this
+  # config.alert_queue_thresholds  = {       # fire when a queue's ready depth >= value
+  #   "critical" => 50,
+  #   "default"  => 500
+  # }
+  # config.alert_webhook_cooldown  = 3600   # seconds between repeat alerts
+end

data/lib/solid_stack_web/version.rb

@@ -1,3 +1,3 @@
 module SolidStackWeb
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/solid_stack_web.rb

@@ -53,6 +53,19 @@ module SolidStackWeb
       @allow_value_preview || false
     end
 
+    # Returns the path at which the engine is mounted in the host application,
+    # derived automatically from the host's routes. Host apps can use this to
+    # build links to the dashboard without hardcoding the mount path.
+    #
+    #   link_to "Dashboard", SolidStackWeb.mount_path
+    #
+    def mount_path
+      route = Rails.application.routes.routes.find do |r|
+        r.app.respond_to?(:app) && r.app.app == SolidStackWeb::Engine
+      end
+      route&.path&.spec&.to_s&.sub(%r{\(.*\)\z}, "") || "/"
+    end
+
     def configure
       yield self
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_stack_web
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -193,6 +193,8 @@ files:
 - app/views/solid_stack_web/cache_entries/index.html.erb
 - app/views/solid_stack_web/cache_entries/show.html.erb
 - app/views/solid_stack_web/dashboard/index.html.erb
+- app/views/solid_stack_web/errors/internal_server_error.html.erb
+- app/views/solid_stack_web/errors/not_found.html.erb
 - app/views/solid_stack_web/failed_jobs/destroy.turbo_stream.erb
 - app/views/solid_stack_web/failed_jobs/index.html.erb
 - app/views/solid_stack_web/failed_jobs/show.html.erb
@@ -210,6 +212,8 @@ files:
 - app/views/solid_stack_web/stats/index.html.erb
 - config/importmap.rb
 - config/routes.rb
+- lib/generators/solid_stack_web/install/install_generator.rb
+- lib/generators/solid_stack_web/install/templates/initializer.rb
 - lib/solid_stack_web.rb
 - lib/solid_stack_web/engine.rb
 - lib/solid_stack_web/version.rb