solid_queue_lite 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8794ace8f2ebf4cfcaf14e887c2a166f660ee6a91e6cb381052efa29d6bb913f
+  data.tar.gz: 7d0b0b3fbe10136b7ef29f75686c05943a8db655d5025795f54c7ea92273a09e
+SHA512:
+  metadata.gz: e0ce386dc14caf232ef48431d826029d9bd17cfd6dda08840e28c7779015230589f9c503a8773287ed0b59feaafa26c8489cb9569ad340234c45122e4456da59
+  data.tar.gz: 26962200de4d9e6d126dbac23eb84d6ea6c92cda64e0c4993daea15aedf498b5e7c32836467fdde96caf6137a80150511ba1d92a6f9e6bdb246dfd69cfae0b54

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public release of Solid Queue Lite.
+- Added a mockup-aligned dashboard experience for pulse, jobs, processes, and recurring tasks.
+- Added queue discovery from Solid Queue worker configuration and process metadata.
+- Added exact queue and telemetry counts for fresh installs.
+- Added recurring task monitoring with last-run and next-run visibility.
+- Added queue control actions, job drill-downs, retry/discard operations, and telemetry sampling support.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright nanda suhendra
+
+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/README.md

@@ -0,0 +1,142 @@
+# Solid Queue Lite
+
+A minimal, zero-build web interface for [Solid Queue](https://github.com/rails/solid_queue).
+
+[![Gem Version](https://badge.fury.io/rb/solid_queue_lite.svg)](https://rubygems.org/gems/solid_queue_lite)
+
+The official `mission_control-jobs` engine is great, but it brings along Turbo, Stimulus, and expects a standard Rails asset pipeline. If you run an API-only app, use a modern JS framework, or just want to avoid frontend dependencies in your infrastructure tooling, Solid Queue Lite provides the same operational visibility without the build-step baggage.
+
+## Installation
+
+Add the engine to your host application's Gemfile:
+
+```ruby
+gem "solid_queue_lite"
+```
+
+Install dependencies, then run the engine migration:
+
+```bash
+bundle install
+bin/rails solid_queue_lite:install
+```
+
+The installer copies the engine migration into the host app and creates `config/initializers/solid_queue_lite.rb` if it does not already exist.
+
+Run the migration separately, or let the installer do it for you:
+
+```bash
+bin/rails db:migrate
+# or
+bin/rails solid_queue_lite:install MIGRATE=1
+```
+
+Mount the engine behind your application's own authentication boundary:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(user) { user.admin? } do
+	mount SolidQueueLite::Engine => "/ops/jobs"
+end
+```
+
+The engine root renders the dashboard at `/ops/jobs`, and the jobs index is available at `/ops/jobs/jobs`.
+
+## Requirements
+
+- Ruby 3.1+
+- Rails 7.1+
+- Solid Queue 1.x
+
+## Host Configuration
+
+Use the configuration block to scope all dashboard reads in multi-tenant deployments:
+
+```ruby
+# config/initializers/solid_queue_lite.rb
+SolidQueueLite.configure do |config|
+	config.tenant_scope = lambda do |relation|
+		relation.where(queue_name: Current.account.solid_queue_prefix)
+	end
+end
+```
+
+The lambda receives the Active Record relation before it is queried.
+
+## Telemetry Sampling
+
+The engine ships with `SolidQueueLite::TelemetrySamplerJob`, which writes aggregate queue snapshots into `solid_queue_lite_stats` and prunes samples older than 7 days.
+
+If you use Solid Queue recurring tasks, schedule the sampler in your host application's recurring configuration:
+
+```yml
+# config/recurring.yml
+production:
+	solid_queue_lite_telemetry:
+		class: SolidQueueLite::TelemetrySamplerJob
+		schedule: every 5 minutes
+		queue: default
+```
+
+Without a scheduler process, the dashboard still renders, but the historical charts stay empty until samples are written.
+
+## Console And Tasks
+
+The reusable logic now lives under `lib/solid_queue_lite`, so you can call the same APIs from a Rails console:
+
+```ruby
+SolidQueueLite::Telemetry.sample!
+SolidQueueLite::Telemetry.backfill!
+SolidQueueLite::Telemetry.dashboard_data(range_key: "24h")
+
+SolidQueueLite::Jobs.list(state_key: "failed", page: 1, per_page: 50)
+SolidQueueLite::Jobs.find(123)
+
+SolidQueueLite::Processes.index_data
+SolidQueueLite::Processes.pause_queue!("background")
+```
+
+To force an immediate current telemetry snapshot after upgrading, run:
+
+```bash
+bin/rake solid_queue_lite:telemetry:backfill
+```
+
+The historical `scheduled_count` and `success_count` series cannot be reconstructed exactly for old rows because Solid Queue does not retain that event history. The backfill task writes or refreshes a current snapshot immediately so upgraded installs do not need to wait for the next scheduled sample.
+
+### Core Design Decisions
+
+- **Zero Asset Pipeline:** The UI is built with raw HTML, Pico.css, and Alpine.js loaded via CDN. It adds nothing to your app's frontend build.
+- **Database Safe:** Standard job dashboards often kill primary databases with naive `COUNT(*)` queries on massive tables. This engine strictly uses database metadata (e.g., `pg_class` in Postgres) for approximate counting to prevent sequential scans and lock contention.
+- **Built-in Telemetry:** Solid Queue doesn't store historical data. This engine includes a lightweight, self-pruning background job that snapshots queue sizes, latency, and error rates, giving you 24-hour trends without needing an external APM.
+- **Multi-tenant Support:** Exposes a simple configuration block to scope the dashboard's database queries, allowing you to isolate job visibility per tenant.
+
+### Features
+
+- Monitor active Supervisors, Workers, and Dispatchers.
+- Filter and inspect Ready, In-Progress, Scheduled, and Failed jobs.
+- View job arguments (JSON), full stack traces, and execute individual or bulk retries/discards.
+- Configurable auto-refresh that automatically pauses when you interact with the UI to prevent state loss.
+- Monitor recurring task schedule, last run time, next run time, and latest status from a dedicated dashboard tab.
+
+## Releasing
+
+Build the gem locally before publishing:
+
+```bash
+gem build solid_queue_lite.gemspec
+```
+
+Publish to RubyGems:
+
+```bash
+gem push solid_queue_lite-0.1.0.gem
+```
+
+Typical release flow:
+
+1. Update `lib/solid_queue_lite/version.rb`.
+2. Update `CHANGELOG.md`.
+3. Commit and tag the release.
+4. Build with `gem build solid_queue_lite.gemspec`.
+5. Push with `gem push <built-gem-file>`.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/soliq_queue_lite/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/concerns/solid_queue_lite/approximate_countable.rb

@@ -0,0 +1,10 @@
+module SolidQueueLite
+  module ApproximateCountable
+    extend ActiveSupport::Concern
+
+    private
+      def approximate_count(relation)
+        SolidQueueLite::ApproximateCounter.count(relation)
+      end
+  end
+end

data/app/controllers/solid_queue_lite/application_controller.rb

@@ -0,0 +1,4 @@
+module SolidQueueLite
+  class ApplicationController < ::ActionController::Base
+  end
+end

data/app/controllers/solid_queue_lite/dashboards_controller.rb

@@ -0,0 +1,61 @@
+module SolidQueueLite
+  class DashboardsController < ApplicationController
+    DASHBOARD_TABS = %w[pulse jobs processes recurring].freeze
+    DASHBOARD_PER_PAGE = 25
+
+    def show
+      telemetry_data = SolidQueueLite::Telemetry.dashboard_data(range_key: params.fetch(:range, "24h"))
+      process_data = SolidQueueLite::Processes.index_data
+
+      @active_tab = requested_tab
+      @selected_range = telemetry_data[:selected_range]
+      @stats = telemetry_data[:stats]
+      @latest_stat = telemetry_data[:latest_stat]
+      @current_ready_count = telemetry_data[:current_ready_count]
+      @current_scheduled_count = telemetry_data[:current_scheduled_count]
+      @current_failed_count = telemetry_data[:current_failed_count]
+      @worker_count = telemetry_data[:worker_count]
+      @dispatcher_count = telemetry_data[:dispatcher_count]
+      @stale_process_count = telemetry_data[:stale_process_count]
+      @recurring_tasks = telemetry_data[:recurring_tasks]
+      @chart_payload = telemetry_data[:chart_payload]
+
+      @processes = process_data[:processes]
+      @heartbeat = process_data[:heartbeat]
+      @queues = process_data[:queues]
+
+      @selected_queue_name = params[:queue_name].presence
+      @selected_queue_metrics = @queues.find { |queue| queue[:name] == @selected_queue_name }
+      @jobs_selected_state = params.fetch(:state, "failed")
+      @jobs_per_page = SolidQueueLite::Jobs.normalize_per_page(params.fetch(:per_page, DASHBOARD_PER_PAGE))
+      @jobs_page = SolidQueueLite::Jobs.normalize_page(params.fetch(:page, 1))
+
+      if @selected_queue_name.present?
+        jobs_data = SolidQueueLite::Jobs.list(
+          state_key: @jobs_selected_state,
+          page: @jobs_page,
+          per_page: @jobs_per_page,
+          queue_name: @selected_queue_name,
+          include_details: true
+        )
+
+        @jobs = jobs_data[:jobs]
+        @jobs_pagination = jobs_data[:pagination]
+      else
+        @jobs = []
+        @jobs_pagination = {
+          page: @jobs_page,
+          per_page: @jobs_per_page,
+          total_pages: 1,
+          approximate_total_count: 0
+        }
+      end
+    end
+
+    private
+      def requested_tab
+        requested_value = params[:tab].presence || "pulse"
+        DASHBOARD_TABS.include?(requested_value) ? requested_value : "pulse"
+      end
+  end
+end

data/app/controllers/solid_queue_lite/jobs_controller.rb

@@ -0,0 +1,129 @@
+module SolidQueueLite
+  class JobsController < ApplicationController
+    rescue_from ::ActiveRecord::RecordNotFound, with: :render_not_found
+
+    def index
+      state_key = requested_state_key
+      data = SolidQueueLite::Jobs.list(
+        state_key: state_key,
+        page: requested_page,
+        per_page: requested_per_page,
+        queue_name: params[:queue_name],
+        include_details: true
+      )
+
+      @jobs = data[:jobs]
+      @selected_state = data[:selected_state]
+      @state_options = data[:state_options]
+      @selected_queue_name = data[:selected_queue_name]
+      @pagination = data[:pagination]
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            jobs: @jobs,
+            pagination: @pagination,
+            filters: {
+              state: state_key
+            }
+          }
+        end
+      end
+    end
+
+    def show
+      @job = SolidQueueLite::Jobs.find(params[:id])
+
+      respond_to do |format|
+        format.json { render json: SolidQueueLite::Jobs.serialize(@job) }
+      end
+    end
+
+    def bulk_retry
+      retried_count = SolidQueueLite::Jobs.bulk_retry!(job_ids: params[:job_ids], state_key: params.fetch(:state, "failed"))
+
+      respond_to do |format|
+        format.json { render json: { retried: retried_count } }
+      end
+    end
+
+    def bulk_discard
+      discarded_count = SolidQueueLite::Jobs.bulk_discard!(job_ids: params[:job_ids], state_key: params.fetch(:state, requested_state_key))
+
+      respond_to do |format|
+        format.json { render json: { discarded: discarded_count } }
+      end
+    rescue ::SolidQueue::Execution::UndiscardableError => error
+      render_unprocessable_entity(error)
+    end
+
+    def retry
+      job = SolidQueueLite::Jobs.retry!(params[:id])
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            id: job.id,
+            retried: true,
+            state: "ready"
+          }
+        end
+      end
+    end
+
+    def discard
+      job, previous_state = SolidQueueLite::Jobs.discard!(params[:id])
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            id: job.id,
+            discarded: true,
+            previous_state: previous_state
+          }
+        end
+      end
+    rescue ::SolidQueue::Execution::UndiscardableError => error
+      render_unprocessable_entity(error)
+    end
+
+    private
+      def requested_page
+        SolidQueueLite::Jobs.normalize_page(params.fetch(:page, 1))
+      end
+
+      def requested_per_page
+        SolidQueueLite::Jobs.normalize_per_page(params.fetch(:per_page, SolidQueueLite::Jobs::DEFAULT_PER_PAGE))
+      end
+
+      def requested_state_key
+        params.fetch(:state, "ready")
+      end
+
+      def requested_state(state_key = requested_state_key)
+        SolidQueueLite::Jobs.resolve_state(state_key)
+      end
+
+      def jobs_redirect_params(default_state: "failed")
+        SolidQueueLite::Jobs.jobs_redirect_params(params, default_state: default_state)
+      end
+
+      def redirect_target(default_state: "failed")
+        return params[:return_to] if params[:return_to].to_s.start_with?("/")
+
+        jobs_path(jobs_redirect_params(default_state: default_state))
+      end
+
+      def render_not_found
+        respond_to do |format|
+          format.json { render json: { error: "Not found" }, status: :not_found }
+        end
+      end
+
+      def render_unprocessable_entity(error)
+        respond_to do |format|
+          format.json { render json: { error: error.message }, status: :unprocessable_entity }
+        end
+      end
+  end
+end

data/app/controllers/solid_queue_lite/processes_controller.rb

@@ -0,0 +1,39 @@
+module SolidQueueLite
+  class ProcessesController < ApplicationController
+    def index
+      data = SolidQueueLite::Processes.index_data
+      @processes = data[:processes]
+      @heartbeat = data[:heartbeat]
+      @queues = data[:queues]
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            processes: @processes,
+            heartbeat: @heartbeat
+          }
+        end
+      end
+    end
+
+    def prune
+      prunable_before = SolidQueueLite::Processes.prune!
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            pruned: true,
+            approximate_pruned_count: prunable_before
+          }
+        end
+      end
+    end
+
+    private
+      def redirect_target
+        return params[:return_to] if params[:return_to].to_s.start_with?("/")
+
+        processes_path
+      end
+  end
+end

data/app/controllers/solid_queue_lite/queues_controller.rb

@@ -0,0 +1,31 @@
+module SolidQueueLite
+  class QueuesController < ApplicationController
+    def index
+      redirect_to processes_path
+    end
+
+    def pause
+      SolidQueueLite::Processes.pause_queue!(params.fetch(:queue_name))
+      redirect_to redirect_target, notice: "Paused queue #{params[:queue_name]}"
+    end
+
+    def resume
+      SolidQueueLite::Processes.resume_queue!(params.fetch(:queue_name))
+      redirect_to redirect_target, notice: "Resumed queue #{params[:queue_name]}"
+    end
+
+    def clear
+      SolidQueueLite::Processes.clear_queue!(params.fetch(:queue_name))
+      redirect_to redirect_target, notice: "Cleared ready jobs from queue #{params[:queue_name]}"
+    rescue ::SolidQueue::Execution::UndiscardableError => error
+      redirect_to redirect_target, alert: error.message
+    end
+
+    private
+      def redirect_target
+        return params[:return_to] if params[:return_to].to_s.start_with?("/")
+
+        processes_path
+      end
+  end
+end

data/app/helpers/solid_queue_lite/application_helper.rb

@@ -0,0 +1,27 @@
+module SolidQueueLite
+  module ApplicationHelper
+    def dashboard_route_params(overrides = {})
+      {
+        tab: params[:tab].presence || "pulse",
+        range: params[:range].presence || "24h",
+        queue_name: params[:queue_name].presence,
+        state: params[:state].presence || "failed",
+        page: params[:page].presence,
+        per_page: params[:per_page].presence
+      }.merge(overrides).compact
+    end
+
+    def dashboard_return_to(overrides = {})
+      root_path(dashboard_route_params(overrides))
+    end
+
+    def dashboard_relative_time(timestamp)
+      return "n/a" unless timestamp
+      return "Just now" if timestamp >= 1.minute.ago
+
+      I18n.with_locale(:en) do
+        "#{time_ago_in_words(timestamp)} ago"
+      end
+    end
+  end
+end

data/app/jobs/solid_queue_lite/application_job.rb

@@ -0,0 +1,4 @@
+module SolidQueueLite
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/solid_queue_lite/telemetry_sampler_job.rb

@@ -0,0 +1,11 @@
+require "json"
+
+module SolidQueueLite
+  class TelemetrySamplerJob < ApplicationJob
+    queue_as :default
+
+    def perform(timestamp: Time.current)
+      SolidQueueLite::Telemetry.sample!(timestamp: timestamp)
+    end
+  end
+end

data/app/models/solid_queue_lite/application_record.rb

@@ -0,0 +1,5 @@
+module SolidQueueLite
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/solid_queue_lite/stat.rb

@@ -0,0 +1,7 @@
+module SolidQueueLite
+  class Stat < ApplicationRecord
+    self.table_name = "solid_queue_lite_stats"
+
+    validates :timestamp, :queue_name, presence: true
+  end
+end