solid_observer 0.1.1 → 0.4.0

data/app/views/solid_observer/jobs/show.html.erb

@@ -0,0 +1,71 @@
+<% content_for :title, "Job ##{@execution.id}" %>
+
+<div class="so-content__header">
+  <h1>Job #<%= @execution.id %></h1>
+</div>
+
+<div class="so-back-link">
+  <%= link_to "← Back to Jobs", jobs_path(status: @status), class: "so-btn" %>
+</div>
+
+<div class="so-card so-card--spaced">
+  <table class="so-table so-details">
+    <tbody>
+      <tr>
+        <td>Job Class</td>
+        <td><code><%= @job&.class_name || "N/A" %></code></td>
+      </tr>
+      <tr>
+        <td>Job ID</td>
+        <td><%= @job&.id || "N/A" %></td>
+      </tr>
+      <tr>
+        <td>Status</td>
+        <td><%= status_badge(@status) %></td>
+      </tr>
+      <tr>
+        <td>Queue</td>
+        <td><%= @presenter.queue_name || "N/A" %></td>
+      </tr>
+      <tr>
+        <td>Priority</td>
+        <td><%= @presenter.priority || "N/A" %></td>
+      </tr>
+      <tr>
+        <td>Created At</td>
+        <td><%= @execution.created_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></td>
+      </tr>
+      <% if @execution.respond_to?(:scheduled_at) && @execution.scheduled_at %>
+        <tr>
+          <td>Scheduled At</td>
+          <td><%= @execution.scheduled_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<% if @execution.is_a?(SolidQueue::FailedExecution) && @execution.error %>
+  <div class="so-card so-card--accent-danger">
+    <div class="so-card__label so-card__label--danger">Error Details</div>
+    <table class="so-table so-details so-table--card">
+      <tbody>
+        <tr>
+          <td>Error Class</td>
+          <td><code><%= @execution.error["exception_class"] %></code></td>
+        </tr>
+        <tr>
+          <td>Message</td>
+          <td><%= @execution.error["message"] %></td>
+        </tr>
+      </tbody>
+    </table>
+    <div class="so-card__label">Backtrace</div>
+    <pre class="so-pre so-pre--error"><code><%= @execution.error["backtrace"]&.first(20)&.join("\n") || "No backtrace available" %></code></pre>
+  </div>
+
+  <div class="so-actions">
+    <%= button_to "Retry Job", retry_job_path(@execution.id), method: :post, class: "so-btn so-btn--primary", data: { confirm: "Retry job #{@execution.id}?" } %>
+    <%= button_to "Discard Job", discard_job_path(@execution.id), method: :post, class: "so-btn so-btn--danger", data: { confirm: "Discard job #{@execution.id}? This cannot be undone." } %>
+  </div>
+<% end %>

data/app/views/solid_observer/shared/_empty_state.html.erb

@@ -0,0 +1,5 @@
+<% local_assigns[:message] ||= "No data available" %>
+<div class="so-empty">
+  <div class="so-empty__icon">📭</div>
+  <div class="so-empty__message"><%= message %></div>
+</div>

data/app/views/solid_observer/shared/_pagination.html.erb

@@ -0,0 +1,17 @@
+<% if total_pages > 1 %>
+  <div class="so-pagination">
+    <% if page > 1 %>
+      <%= link_to "Previous", url_for(request.query_parameters.merge(page: page - 1)), class: "so-btn" %>
+    <% else %>
+      <span class="so-btn so-btn--disabled" aria-disabled="true">Previous</span>
+    <% end %>
+
+    <span class="so-btn so-btn--static so-pagination__status">Page <%= page %> of <%= total_pages %></span>
+
+    <% if page < total_pages %>
+      <%= link_to "Next", url_for(request.query_parameters.merge(page: page + 1)), class: "so-btn" %>
+    <% else %>
+      <span class="so-btn so-btn--disabled" aria-disabled="true">Next</span>
+    <% end %>
+  </div>
+<% end %>

data/app/views/solid_observer/shared/_stat_card.html.erb

@@ -0,0 +1,9 @@
+<% subtitle = local_assigns[:subtitle] %>
+<% data_key = local_assigns[:data_key] %>
+<div class="so-card">
+  <div class="so-card__label"><%= label %></div>
+  <% if subtitle.present? %>
+    <div class="so-card__subtitle"><%= subtitle %></div>
+  <% end %>
+  <div class="so-card__value"<%= data_key ? " data-so-card-value=\"#{data_key}\"".html_safe : "".html_safe %>><%= value || 0 %></div>
+</div>

data/app/views/solid_observer/storages/show.html.erb

@@ -0,0 +1,71 @@
+<% content_for :title, "Storage" %>
+
+<div class="so-dashboard">
+  <div class="so-content__header">
+    <h1>Storage</h1>
+  </div>
+
+  <% if @storage_components.any? %>
+    <section class="so-dashboard-section" aria-labelledby="component-health-title">
+      <header class="so-dashboard-section__header">
+        <h2 id="component-health-title" class="so-dashboard-section__title">Component health</h2>
+      </header>
+
+      <div class="so-stat-cards">
+        <% @storage_components.each do |component| %>
+        <% status_class = component[:available] ? "so-badge--success" : "so-badge--warning" %>
+        <% size_value = component[:available] && component[:db_size_bytes] ? number_to_human_size(component[:db_size_bytes], precision: 1, significant: false, strip_insignificant_zeros: false) : "—" %>
+        <% records_value = component[:available] && !component[:event_count].nil? ? number_with_delimiter(component[:event_count]) : "—" %>
+
+          <article class="so-card">
+            <div class="so-card__label"><%= component[:label] %></div>
+            <div class="so-card__subtitle">
+              <span class="so-badge so-badge--pill <%= status_class %>">
+                <svg class="so-badge__dot" viewBox="0 0 6 6" aria-hidden="true"><circle r="3" cx="3" cy="3"/></svg>
+                <%= component[:available] ? "Available" : "Unavailable" %>
+              </span>
+            </div>
+            <div class="so-card__value"><%= size_value %></div>
+            <div class="so-card__subtitle">
+              <% if component[:available] %>
+                <%= records_value %> <%= component[:record_label] %>
+              <% else %>
+                <%= component[:unavailable_reason] %>
+              <% end %>
+            </div>
+          </article>
+        <% end %>
+      </div>
+    </section>
+
+    <% if @storage_history.any? %>
+      <div class="so-card so-card--section">
+        <div class="so-card__label">Recent Snapshots</div>
+        <table class="so-table so-table--card">
+          <caption class="sr-only">Recent storage snapshots by component</caption>
+          <thead>
+            <tr>
+              <th>Time</th>
+              <th>Component</th>
+              <th>Size</th>
+              <th>Records</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @storage_history.each do |snapshot| %>
+              <% record_label = snapshot.component == "solid_cache" ? "cache rows" : "observer events" %>
+              <tr>
+                <td><%= snapshot.recorded_at.strftime("%Y-%m-%d %H:%M") %></td>
+                <td><%= snapshot.component.humanize %></td>
+                <td><%= number_to_human_size(snapshot.db_size_bytes, precision: 1, significant: false, strip_insignificant_zeros: false) %></td>
+                <td><%= number_with_delimiter(snapshot.event_count) %> <%= record_label %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  <% else %>
+    <%= render "solid_observer/shared/empty_state", message: "No storage information available" %>
+  <% end %>
+</div>

data/bin/quality_gate

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# SolidObserver Quality Gate Suite
+# Runs all non-negotiable gates in sequence.
+# Usage: bin/quality_gate [--skip-appraisal]
+#
+# Individual gates can be run via:
+#   bin/quality_gate rspec
+#   bin/quality_gate standardrb
+#   bin/quality_gate reek
+#   bin/quality_gate appraisal
+#   bin/quality_gate audit
+
+SKIP_APPRAISAL=false
+SINGLE_GATE=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --skip-appraisal) SKIP_APPRAISAL=true ;;
+    rspec|standardrb|reek|appraisal|audit) SINGLE_GATE="$arg" ;;
+  esac
+done
+
+red()   { printf '\033[31m%s\033[0m\n' "$*" >&2; }
+green() { printf '\033[32m%s\033[0m\n' "$*"; }
+dim()   { printf '\033[2m%s\033[0m\n' "$*"; }
+
+run_gate() {
+  local label="$1"; shift
+  dim "⏳ ${label}..."
+  if "$@" > /dev/null 2>&1; then
+    green "✅ ${label}"
+    return 0
+  else
+    red "❌ ${label} FAILED — check output above"
+    return 1
+  fi
+}
+
+gate_rspec() {
+  run_gate "RSpec" bundle exec rspec
+}
+
+gate_standardrb() {
+  run_gate "StandardRB" bundle exec standardrb
+}
+
+gate_reek() {
+  run_gate "Reek" bundle exec reek lib/ app/
+}
+
+gate_appraisal() {
+  run_gate "Rails 8.0 appraisal" bundle exec appraisal rails-8.0 rspec \
+    && run_gate "Rails 8.1 appraisal" bundle exec appraisal rails-8.1 rspec
+}
+
+gate_audit() {
+  dim "⏳ bundler-audit: updating advisory DB..."
+  bundle exec bundler-audit update > /dev/null 2>&1 || true
+  run_gate "bundler-audit" bundle exec bundler-audit check
+}
+
+run_all() {
+  local failed=0
+
+  gate_rspec      || failed=$((failed + 1))
+  gate_standardrb || failed=$((failed + 1))
+  gate_reek       || failed=$((failed + 1))
+
+  if [ "$SKIP_APPRAISAL" = false ]; then
+    gate_appraisal || failed=$((failed + 1))
+  else
+    dim "⏭️  Skipping appraisal (--skip-appraisal)"
+  fi
+
+  gate_audit      || failed=$((failed + 1))
+
+  echo ""
+  if [ "$failed" -eq 0 ]; then
+    green "All quality gates passed"
+  else
+    red "${failed} gate(s) failed"
+    return 1
+  fi
+}
+
+case "$SINGLE_GATE" in
+  rspec)      gate_rspec ;;
+  standardrb) gate_standardrb ;;
+  reek)       gate_reek ;;
+  appraisal)  gate_appraisal ;;
+  audit)      gate_audit ;;
+  "")         run_all ;;
+esac

data/config/routes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+SolidObserver::Engine.routes.draw do
+  root "dashboard#index"
+  get "queue", to: "dashboard#index", defaults: {component: "queue"}, as: :queue_dashboard
+  get "cache", to: "cache_dashboard#index", as: :cache_dashboard
+  get "cache/controls", to: "cache_operations#index", as: :cache_operations
+  post "cache/controls/prune", to: "cache_operations#prune", as: :prune_cache_operations
+  post "cache/controls/clear", to: "cache_operations#clear", as: :clear_cache_operations
+  get "poll_data", to: "dashboard#poll_data", as: :poll_data
+  get "live_poll.js", to: "dashboard#live_poll", as: :live_poll_script
+
+  resources :jobs, only: %i[index show] do
+    member do
+      post :retry
+      post :discard
+    end
+  end
+
+  resource :storage, only: %i[show]
+  resources :events, only: %i[index show]
+end

data/db/migrate/20260424000001_add_composite_indexes_to_queue_events.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class AddCompositeIndexesToQueueEvents < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    options = concurrent_supported? ? {algorithm: :concurrently} : {}
+
+    add_index :solid_observer_queue_events,
+      %i[job_class recorded_at],
+      order: {recorded_at: :desc},
+      if_not_exists: true,
+      **options
+
+    add_index :solid_observer_queue_events,
+      %i[queue_name recorded_at],
+      order: {recorded_at: :desc},
+      if_not_exists: true,
+      **options
+
+    remove_index :solid_observer_queue_events, :job_class, if_exists: true, **options
+    remove_index :solid_observer_queue_events, :queue_name, if_exists: true, **options
+  end
+
+  private
+
+  def concurrent_supported?
+    connection.adapter_name.match?(/postgres/i)
+  end
+end

data/db/migrate/20260601000001_create_solid_observer_cache_events.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateSolidObserverCacheEvents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :solid_observer_cache_events do |t|
+      t.string :event_type, null: false, limit: 64
+      t.string :key_digest, null: false, limit: 64
+      t.boolean :hit
+      t.float :duration
+      t.string :error_class, limit: 255
+      t.text :error_message
+      t.text :metadata
+      t.datetime :recorded_at, null: false
+
+      t.index :recorded_at
+      t.index :event_type
+      t.index :key_digest
+      t.index :hit
+      t.index :error_class
+    end
+  end
+end

data/db/migrate/20260601000002_create_solid_observer_cache_metrics.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateSolidObserverCacheMetrics < ActiveRecord::Migration[8.0]
+  def change
+    create_table :solid_observer_cache_metrics do |t|
+      t.string :event_type, null: false, limit: 64
+      t.datetime :period_start, null: false
+      t.bigint :operations_count, null: false, default: 0
+      t.bigint :hits_count, null: false, default: 0
+      t.bigint :misses_count, null: false, default: 0
+      t.bigint :errors_count, null: false, default: 0
+      t.float :duration_total, null: false, default: 0.0
+
+      t.index [:event_type, :period_start], unique: true, name: "idx_solid_observer_cache_metrics_unique"
+      t.index :period_start
+    end
+  end
+end

data/db/migrate/20260602000001_add_component_to_solid_observer_storage_infos.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddComponentToSolidObserverStorageInfos < ActiveRecord::Migration[8.0]
+  def change
+    add_column :solid_observer_storage_info, :component, :string, null: false, default: "queue_observer"
+    add_index :solid_observer_storage_info, :component
+  end
+end

data/lib/generators/solid_observer/install_generator.rb

@@ -24,6 +24,10 @@ module SolidObserver
         end
       end
 
+      def add_engine_mount
+        route 'mount SolidObserver::Engine, at: "/solid_observer"'
+      end
+
       def show_instructions
         say "\n"
         print_banner
@@ -34,38 +38,21 @@ module SolidObserver
         say "  3. Create database: bin/rails db:create"
         say "  4. Run migrations: bin/rails db:migrate"
         say "  5. Restart your Rails server"
+        say "  6. Visit /solid_observer to access the web dashboard"
         say "\n"
-        say "Documentation: https://solid.observer", :cyan
-        say "GitHub: https://github.com/bart-oz/solid_observer", :cyan
+        say "Documentation: https://solid.observer", :red
+        say "GitHub: https://github.com/bart-oz/solid_observer", :red
         say "\n"
       end
 
       private
 
       def print_banner
-        banner = <<~BANNER
-
-          ███████╗ ██████╗ ██╗     ██╗██████╗
-          ██╔════╝██╔═══██╗██║     ██║██╔══██╗
-          ███████╗██║   ██║██║     ██║██║  ██║
-          ╚════██║██║   ██║██║     ██║██║  ██║
-          ███████║╚██████╔╝███████╗██║██████╔╝
-          ╚══════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝
-
-           ██████╗ ██████╗ ███████╗███████╗██████╗ ██╗   ██╗███████╗██████╗
-          ██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██╔════╝██╔══██╗
-          ██║   ██║██████╔╝███████╗█████╗  ██████╔╝██║   ██║█████╗  ██████╔╝
-          ██║   ██║██╔══██╗╚════██║██╔══╝  ██╔══██╗╚██╗ ██╔╝██╔══╝  ██╔══██╗
-          ╚██████╔╝██████╔╝███████║███████╗██║  ██║ ╚████╔╝ ███████╗██║  ██║
-           ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚══════╝╚═╝  ╚═╝
-
-                 Observe your Solid Stack like a pro! 🔭
-                                v#{SolidObserver::VERSION}
-
-        BANNER
-
-        banner.each_line { |line| say line.chomp, :cyan }
-        say "  ✓ SolidObserver installed successfully!", :green
+        say "         ┌─   ─┐", :red
+        say "            ◉     solid_observer", :red
+        say "         └─   ─┘", :red
+        say ""
+        say "   ✓ SolidObserver installed successfully!", :green
       end
     end
   end

data/lib/generators/solid_observer/templates/initializer.rb.tt

@@ -9,10 +9,9 @@ SolidObserver.configure do |config|
   # Recommended: false in production, true in development/staging
   config.ui_enabled = !Rails.env.production?
 
-  # Authentication for UI (when ui_enabled = true)
-  # config.http_basic_auth_enabled = true
-  # config.http_basic_auth_user = "admin"
-  # config.http_basic_auth_password = "secret"
+  # Authentication for web UI — set a username to enable HTTP Basic Auth
+  # config.ui_username = "admin"
+  # config.ui_password = "secret"
 
   # Base controller for UI (customize authorization)
   # config.ui_base_controller = "ApplicationController"
@@ -20,11 +19,12 @@ SolidObserver.configure do |config|
   # === Queue Observability (v0.1.0) ===
   config.observe_queue = true
 
-  # === Cache Observability (Coming in v0.2.0+) ===
+  # === Cache Observability (v0.4.0) ===
+  # Enable SolidCache event capture and operational clear/prune controls
   # config.observe_cache = true
   # config.cache_sampling_rate = 0.1  # Sample 10% of cache operations
 
-  # === Cable Observability (Coming in v0.2.0+) ===
+  # === Cable Observability (Coming in v0.5.0+) ===
   # config.observe_cable = true
 
   # Data Retention

data/lib/solid_observer/base_metric.rb

@@ -3,7 +3,7 @@
 module SolidObserver
   # BaseMetric provides the foundation for time-series metrics storage.
   #
-  # NOTE: Metrics functionality is planned for v0.2.0. The database connection
+  # NOTE: Metrics functionality is planned for a future release. The database connection
   # will be configured by the Engine (similar to BaseEvent) when metrics are
   # fully implemented.
   #

data/lib/solid_observer/cache_event_buffer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module SolidObserver
+  class CacheEventBuffer
+    include Singleton
+
+    def initialize
+      @mutex = Mutex.new
+      @buffer = []
+    end
+
+    def push(event_data)
+      config = SolidObserver.config
+      return unless config.persistence_mode?
+
+      should_flush = buffer_ready_to_flush?(event_data, config.buffer_size)
+      flush! if should_flush
+    end
+
+    def flush!
+      events = @mutex.synchronize do
+        buffered_events = @buffer.dup
+        @buffer.clear
+        buffered_events
+      end
+      return if events.empty?
+
+      Services::FlushCacheEventBuffer.call(events)
+    rescue => error
+      @mutex.synchronize { @buffer = events + @buffer }
+      Rails.logger&.error("[SolidObserver] Cache buffer flush failed: #{error.message}") if defined?(Rails)
+    end
+
+    def size
+      @mutex.synchronize { @buffer.size }
+    end
+
+    def clear
+      @mutex.synchronize { @buffer.clear }
+    end
+
+    private
+
+    def buffer_ready_to_flush?(event_data, buffer_size)
+      @mutex.synchronize do
+        @buffer << event_data
+        @buffer.size >= buffer_size
+      end
+    end
+  end
+end

data/lib/solid_observer/cache_subscriber.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class CacheSubscriber
+    EVENTS = %w[
+      cache_read.active_support
+      cache_write.active_support
+      cache_delete.active_support
+      cache_exist?.active_support
+      cache_read_multi.active_support
+      cache_write_multi.active_support
+      cache_delete_multi.active_support
+    ].freeze
+
+    class << self
+      def subscribe!
+        return unless subscription_allowed?
+
+        @subscriptions = EVENTS.map { |event_name| subscribe_to(event_name) }
+      end
+
+      def unsubscribe!
+        return unless @subscriptions
+
+        @subscriptions.each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+        @subscriptions = []
+      end
+
+      def subscribed?
+        !!@subscriptions&.any?
+      end
+
+      private
+
+      def subscription_allowed?
+        SolidObserver.config.solid_cache_enabled? && !subscribed? && defined?(ActiveSupport::Notifications)
+      end
+
+      def subscribe_to(event_name)
+        ActiveSupport::Notifications.subscribe(event_name) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          Services::RecordCacheEvent.call(event: event, buffer: CacheEventBuffer.instance)
+        end
+      end
+    end
+  end
+end

data/lib/solid_observer/chart_buffer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  class ChartBuffer
+    INSTANCE_MUTEX = Mutex.new
+
+    class << self
+      def append(value, at: Time.now)
+        instance.append(value, at: at)
+      end
+
+      def recent(window_seconds)
+        instance.recent(window_seconds)
+      end
+
+      def clear
+        instance.clear
+      end
+
+      private
+
+      def instance
+        INSTANCE_MUTEX.synchronize { @instance ||= new }
+      end
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      @samples = []
+      @cap = nil
+    end
+
+    def append(value, at: Time.now)
+      sample = {t: at.to_i, v: value.to_i}
+
+      @mutex.synchronize { store_sample(sample) }
+
+      sample
+    end
+
+    def recent(window_seconds)
+      cutoff = Time.now.to_i - window_seconds.to_i
+
+      @mutex.synchronize do
+        @samples.select { |sample| sample[:t] >= cutoff }.map(&:dup)
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @samples.clear
+        @cap = nil
+      end
+    end
+
+    private
+
+    def store_sample(sample)
+      @cap ||= compute_cap
+      replace_or_append(sample)
+      trim_to_cap
+    end
+
+    def replace_or_append(sample)
+      latest_sample = @samples.last
+
+      if latest_sample && latest_sample[:t] == sample[:t]
+        @samples[-1] = sample
+      else
+        @samples << sample
+      end
+    end
+
+    def trim_to_cap
+      overflow = @samples.length - @cap
+      @samples.shift(overflow) if overflow.positive?
+    end
+
+    def compute_cap
+      (3600 / 5).to_i # 720 samples — 1h at the 5s cadence
+    end
+  end
+end

data/lib/solid_observer/cli/base.rb

@@ -39,8 +39,8 @@ module SolidObserver
 
         widths = calculate_column_widths(headers, rows)
 
-        output(format_table_row(headers, widths), color: :cyan)
-        output(separator_line(widths), color: :cyan)
+        output(format_table_row(headers, widths), color: :red)
+        output(separator_line(widths), color: :red)
 
         rows.each do |row|
           output(format_table_row(row, widths))