solid_stack_web 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85093a248316f7f8921636f68bdc08e2053e496eeb85f17bbbd7cddac57e4ed6
-  data.tar.gz: 3321fa62f08ce3615f733740cfac444d60ed65960b9adc9e4894919416482b46
+  metadata.gz: e7932ddf2c50cc9ae63a884c0dabdc0fe4553c9dfb823870d3e1b15b4dc2a3a6
+  data.tar.gz: 04d6d15b941d21dfae0d1562095e6cdb4cd67a7e1163efa3bc2d33563df2fb92
 SHA512:
-  metadata.gz: 278a4dbde1baa31bb57f58c72d41ea13ef9ddbb83043839228abb4cb0ab06286c4ca954d63ee0c2f2e6914a1b8c24f946731b73afe8db1176ba28a8c157c6b52
-  data.tar.gz: f6b953b896ba256d03e26f802ab594d9e822fbd114ce68f6b7f673d435fceca8009a9ec2c55ea0f45a6dacfcebb34b9b9c23c64564faa212e00a8450292d95c4
+  metadata.gz: 37ac38026dbde5e629d132f18795797f84a7b48b8e19689435b0288f44c57abf73e7dae5aa9e51884021920b4b336160597529b4f87c44cac027e9b88c1293d6
+  data.tar.gz: c233686b589092befdcc5b19ca7bfd09a2f10e9f1d95b894f58afff4fb67475ddcae308bf6b65386f9af5479d670256dde1cd02cf3cf2b5466eadcd00a051a2d

data/README.md

@@ -5,7 +5,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://www.ruby-lang.org)
 [![codecov](https://codecov.io/gh/eclectic-coding/solid_stack_web/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/solid_stack_web)
 
-A mountable Rails engine that provides a unified web dashboard for the full [Solid Stack](https://github.com/rails/solid_queue) — **Solid Queue**, **Solid Cache**, and **Solid Cable** — in a single interface with no asset pipeline dependency and no JavaScript runtime requirement.
+A production-ready operations dashboard for the full Rails Solid Stack. Mount one engine to get deep visibility into **Solid Queue** (job browser, failed job retry, queue controls, recurring tasks, performance stats), **Solid Cache** (entry browser, size distribution, write timeline), and **Solid Cable** (channel browser, message list, purge controls) — with dark mode, CSV export, alert webhooks, and a JSON metrics endpoint, all with no asset pipeline dependency.
 
 ## Installation
 
@@ -41,6 +41,12 @@ This creates `config/initializers/solid_stack_web.rb` with every configuration o
 
 ---
 
+## Screenshots
+
+![SolidStackWeb dashboard](docs/screenshots/demo.gif)
+
+---
+
 ## Metrics endpoint
 
 `GET /metrics` (relative to your mount path) returns a JSON payload suitable for external monitoring tools, uptime checkers, or custom alerting:
@@ -83,6 +89,10 @@ SolidStackWeb.configure do |config|
   config.authenticate do
     current_user&.admin?
   end
+
+  # Multi-database — pass a connects_to hash when Solid Queue / Cache / Cable
+  # live on a separate database from your primary (default: nil, uses primary).
+  config.connects_to = { database: { writing: :queue, reading: :queue } }
 end
 ```
 
@@ -100,6 +110,44 @@ link_to "Queue Dashboard", SolidStackWeb.mount_path
 
 ---
 
+## Security
+
+### Authentication
+
+**The dashboard is open to all visitors by default.** Any production deployment must configure an `authenticate` block or the dashboard will be publicly accessible.
+
+```ruby
+SolidStackWeb.configure do |config|
+  # Devise
+  config.authenticate { current_user&.admin? }
+
+  # HTTP Basic fallback (used when no authenticate block is set, or when
+  # the block returns false/nil and you want a browser credential prompt)
+  # Configure via HTTP_BASIC_AUTH_NAME / HTTP_BASIC_AUTH_PASSWORD env vars
+  # in your host app, or use a reverse proxy.
+end
+```
+
+If the `authenticate` block returns `false` or `nil`, the engine falls back to HTTP Basic authentication. If no block is configured at all, the dashboard is open.
+
+### Sensitive cache values
+
+`allow_value_preview` is `false` by default. Enabling it renders the raw serialised cache value on the entry detail page. Do not enable this if your cache stores session tokens, PII, or other sensitive data.
+
+### CSRF protection
+
+All state-mutating actions (job discard, retry, queue pause/resume, cache flush) use form POST requests. Turbo handles CSRF tokens automatically for any standard Rails app with `protect_from_forgery`.
+
+### Rate limiting and network exposure
+
+The dashboard is designed to be mounted behind your application's existing authentication. For additional hardening, consider:
+
+- Mounting at a non-guessable path (e.g. `at: "/ops/#{Rails.application.credentials.dashboard_token}"`)
+- Restricting access by IP at the reverse-proxy level
+- Applying [Rack::Attack](https://github.com/rack/rack-attack) rules to the mount path
+
+---
+
 ## Solid Queue
 
 ### Features
@@ -207,6 +255,36 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
 - [turbo-rails](https://github.com/hotwired/turbo-rails) >= 2.0
 - [importmap-rails](https://github.com/rails/importmap-rails) >= 1.2
 
+## Versioning
+
+SolidStackWeb follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+### Public API
+
+The following are considered stable public API from v1.0.0 onwards — breaking changes to any of these require a major version bump:
+
+- The `SolidStackWeb.configure` block and all documented configuration keys
+- The `SolidStackWeb.mount_path` helper
+- The `authenticate` block interface
+- The `GET /metrics` JSON payload shape
+- The `SolidStackWeb::Engine` class and its mount interface
+- The `rails generate solid_stack_web:install` generator
+
+### Not part of the public API
+
+The following are internal and may change in any release without notice:
+
+- Internal service classes (`CacheStats`, `QueueStats`, etc.)
+- View templates, partial names, and CSS class names
+- Controller and helper internals
+- Private methods on any class
+
+### Deprecation policy
+
+When a public API item is renamed or removed, the old interface is deprecated in a **minor** release — it continues to work but issues an `ActiveSupport::Deprecation` warning pointing to the replacement. The old interface is removed in the next **major** release. The [UPGRADING.md](UPGRADING.md) file documents every breaking change and the migration steps.
+
+---
+
 ## Contributing
 
 1. Fork the repository

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

@@ -70,20 +70,9 @@
   overflow-y: auto;
 }
 
-.sqw-detail {
-  display: grid;
-  grid-template-columns: auto 1fr;
-  gap: 0.5rem 1.5rem;
-  font-size: 13px;
-  margin-bottom: 1.5rem;
-}
-.sqw-detail__row {
-  display: contents;
-}
-.sqw-detail__row dt { color: var(--muted); white-space: nowrap; align-self: start; padding-top: 0.15rem; }
-.sqw-detail__row dd { word-break: break-all; }
-
-.sqw-value-preview { margin-top: 1rem; }
+.sqw-detail-card--mt,
+.sqw-detail-card + .sqw-detail-card,
+.sqw-detail-grid + .sqw-detail-card { margin-top: 1.5rem; }
 
 .sqw-value-preview__header {
   display: flex;
@@ -93,20 +82,6 @@
 }
 .sqw-value-preview__header .sqw-section-title { margin-bottom: 0; }
 
-.sqw-value-pre {
-  font-family: ui-monospace, "SFMono-Regular", Menlo, monospace;
-  font-size: 12px;
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  padding: 0.75rem;
-  overflow-x: auto;
-  white-space: pre-wrap;
-  word-break: break-word;
-  max-height: 500px;
-  overflow-y: auto;
-}
-
 .sqw-value-truncated { font-size: 12px; margin-top: 0.5rem; }
 
 .sqw-link { color: var(--primary); text-decoration: none; }

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

@@ -10,33 +10,30 @@
   </div>
 </div>
 
-<dl class="sqw-detail">
-  <div class="sqw-detail__row">
+<div class="sqw-detail-card sqw-detail-section">
+  <h2 class="sqw-section-title">Details</h2>
+  <dl class="sqw-dl">
     <dt>Key</dt>
     <dd class="sqw-monospace"><%= @entry.key %></dd>
-  </div>
-  <div class="sqw-detail__row">
     <dt>Size</dt>
     <dd><%= number_to_human_size(@entry.byte_size) %></dd>
-  </div>
-  <div class="sqw-detail__row">
     <dt>Created</dt>
     <dd class="sqw-muted"><%= local_time(@entry.created_at, format: :long) %></dd>
-  </div>
-</dl>
+  </dl>
+</div>
 
-<section class="sqw-value-preview">
+<div class="sqw-detail-card sqw-detail-section">
+  <% formatted = SolidStackWeb.allow_value_preview ? format_cache_value(@entry.value) : nil %>
   <div class="sqw-value-preview__header">
     <h2 class="sqw-section-title">Value</h2>
-    <% if SolidStackWeb.allow_value_preview %>
-      <% formatted = format_cache_value(@entry.value) %>
+    <% if formatted %>
       <span class="sqw-badge sqw-badge--queue"><%= formatted[:label] %></span>
     <% end %>
   </div>
-  <% if SolidStackWeb.allow_value_preview %>
+  <% if formatted %>
     <% content = formatted[:content] %>
     <% truncated = content.length > 4096 %>
-    <pre class="sqw-value-pre"><%= truncated ? content[0, 4096] : content %></pre>
+    <pre class="sqw-code-block"><%= truncated ? content[0, 4096] : content %></pre>
     <% if truncated %>
       <p class="sqw-muted sqw-value-truncated">Showing first 4 KB of <%= number_to_human_size(@entry.byte_size) %> total.</p>
     <% end %>
@@ -45,4 +42,4 @@
       <p>Value preview is disabled. Set <code>config.allow_value_preview = true</code> in your initializer to enable.</p>
     </div>
   <% end %>
-</section>
+</div>

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

@@ -45,7 +45,7 @@
   </div>
 </div>
 
-<div class="sqw-detail-card sqw-detail-section" style="margin-top: 1.5rem;">
+<div class="sqw-detail-card sqw-detail-section sqw-detail-card--mt">
   <h2 class="sqw-section-title">Arguments</h2>
   <%= form_with url: failed_job_arguments_path(@execution), method: :patch do |f| %>
     <%= f.text_area :arguments, value: @arguments, rows: 12,

data/lib/solid_stack_web/engine.rb

@@ -25,6 +25,10 @@ module SolidStackWeb
       end
     end
 
+    initializer "solid_stack_web.deprecator" do |app|
+      app.deprecators[:solid_stack_web] = SolidStackWeb.deprecator
+    end
+
     initializer "solid_stack_web.pagy" do |app|
       app.config.after_initialize do
         Pagy::OPTIONS[:limit] = SolidStackWeb.page_size

data/lib/solid_stack_web/version.rb

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

data/lib/solid_stack_web.rb

@@ -74,5 +74,27 @@ module SolidStackWeb
       @authenticate = block if block_given?
       @authenticate
     end
+
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0", "SolidStackWeb")
+    end
+
+    private
+
+    # Define a deprecated writer for a renamed config key.
+    # The old writer issues a deprecation warning and forwards to the new key.
+    #
+    # Usage (add entries here as keys are renamed before 1.0):
+    #   deprecated_config :old_key, :new_key
+    def deprecated_config(old_key, new_key)
+      singleton_class.define_method(:"#{old_key}=") do |value|
+        deprecator.warn(
+          "config.#{old_key}= is deprecated and will be removed in SolidStackWeb 1.0. " \
+          "Use config.#{new_key}= instead.",
+          caller_locations
+        )
+        public_send(:"#{new_key}=", value)
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_stack_web
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -121,9 +121,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Mount SolidStackWeb in any Rails app using the Solid Stack to get a single
-  dashboard covering Solid Queue job monitoring, Solid Cache statistics, and Solid
-  Cable connection observability — all without leaving your app.
+description: SolidStackWeb is a mountable Rails engine that provides a production-ready
+  operations dashboard for the full Solid Stack. It covers Solid Queue (job browser,
+  failed job retry with inline argument editing, queue pause/resume, recurring tasks,
+  performance stats, CSV export, and alert webhooks), Solid Cache (entry browser,
+  size distribution, 24-hour write timeline, and optional value preview), and Solid
+  Cable (channel browser, per-channel message list, and purge controls). Ships with
+  dark mode, Turbo Stream responses, a JSON metrics endpoint, and no asset pipeline
+  dependency.
 email:
 - eclectic-coding@users.noreply.github.com
 executables: []
@@ -212,6 +217,7 @@ files:
 - app/views/solid_stack_web/stats/index.html.erb
 - config/importmap.rb
 - config/routes.rb
+- docs/screenshots/demo.gif
 - lib/generators/solid_stack_web/install/install_generator.rb
 - lib/generators/solid_stack_web/install/templates/initializer.rb
 - lib/solid_stack_web.rb