job_board 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9383d573ca40430673ec3e2ad7436edec021a856b72ebfcd45c3e557b8b4ac7
+  data.tar.gz: 6d0849f4f83e665364ea8769483adbbc53f9189ff8ddd50de6fb957d1adc76ae
+SHA512:
+  metadata.gz: 544bcb5aa2cbddefa3d4ee47f708398e7fcda871addfbf95ac7184d5c5e48b332da2a34aec62ebb60158461c62c637d664df3ee0177336afa51b8d8cd93a1f39
+  data.tar.gz: 28f552a8ed1840b90b7984806dc2794674819ea442d9e1b6da439bc0fd4cbf465c6900544e39a3f9fe5b5ebc65dbf6771b4207f06f0f2807f25763f0ba2de0c4

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Queues overview with per-queue ready count, latency, failed count, and pause/resume.
+- Latency-SLA aware: `within_*` queue names (e.g. `within_5_minutes`) set their own
+  warning threshold and sort order; configurable per queue or globally.
+- Jobs browsing by status (ready, scheduled, in progress, blocked, failed, finished)
+  with queue/class filters, keyset pagination, and a job detail page.
+- Failed job management: retry/discard individually or in bulk.
+- Workers page: supervisor tree, heartbeat freshness, stale detection, orphaned-job warning.
+- Recurring tasks page with last/next run times.
+- Zero-dependency UI served by the engine itself, with polling auto-refresh.
+- Optional HTTP Basic auth via `JobBoard.configure`.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Mike
+
+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,129 @@
+# Job Board
+
+A mountable Rails engine that gives you a dashboard for [Solid Queue](https://github.com/rails/solid_queue):
+queue latency at a glance, jobs by status, failed-job management, worker health, and recurring tasks.
+
+## Features
+
+- **Queues** — every queue with its ready-job count, **current latency** (how long the oldest
+  ready job has been waiting), and pause/resume controls.
+- **Jobs** — browse by status (ready, scheduled, in progress, blocked, failed, finished) with
+  queue and class filters, keyset pagination that stays fast on huge tables, and a detail page
+  showing arguments, timestamps, and the full error with backtrace.
+- **Failed job management** — retry or discard individual jobs, or all failed jobs matching the
+  current filters (batched, safe for large sets).
+- **Workers** — the supervisor → worker/dispatcher/scheduler tree with heartbeat freshness,
+  stale-process badges, per-worker in-progress jobs, and a warning when claimed jobs have been
+  orphaned by a dead process.
+- **Recurring tasks** — each task's cron schedule, last run, and next run.
+- **Zero dependencies** — the engine serves its own CSS and ~40 lines of vanilla JS. No
+  importmap, sprockets, propshaft, or Node requirement. Pages auto-refresh every few seconds.
+
+## Installation
+
+Add the gem:
+
+```ruby
+gem "job_board"
+```
+
+Mount the engine:
+
+```ruby
+# config/routes.rb
+mount JobBoard::Engine => "/job_board"
+```
+
+That's it — visit `/job_board`.
+
+## Authentication
+
+The dashboard ships with no forced authentication. Two options:
+
+**Constraint-based mounting** (recommended when you have app auth, e.g. Devise):
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount JobBoard::Engine => "/job_board"
+end
+```
+
+**Built-in HTTP Basic auth:**
+
+```ruby
+# config/initializers/job_board.rb
+JobBoard.configure do |config|
+  config.http_basic_auth = {
+    name: Rails.application.credentials.dig(:job_board, :user),
+    password: Rails.application.credentials.dig(:job_board, :password)
+  }
+end
+```
+
+## Configuration
+
+```ruby
+JobBoard.configure do |config|
+  config.poll_interval = 5              # seconds between auto-refreshes; nil or 0 disables
+  config.per_page = 25                  # rows per page on job lists
+  config.stale_process_threshold = nil  # heartbeat age before a process is flagged stale;
+                                        # nil uses SolidQueue.process_alive_threshold (5 min)
+  config.http_basic_auth = nil          # see Authentication above
+
+  # Latency (seconds) above which a queue is highlighted as breaching:
+  config.latency_warning_threshold = 60                      # global default
+  config.latency_warning_thresholds = { "critical" => 10 }   # per-queue overrides
+end
+```
+
+### Latency-SLA queue names
+
+If you name queues after their latency target — the `within_*` convention from
+[Gusto's Sidekiq scaling write-up](https://engineering.gusto.com/scaling-sidekiq-at-gusto-3f9e3279e63) —
+Job Board parses the threshold straight from the name, no configuration needed:
+
+| Queue | Highlighted red when latency exceeds |
+|---|---|
+| `within_30_seconds` | 30 seconds |
+| `within_5_minutes` | 5 minutes |
+| `within_1_hour` | 1 hour |
+| `within_24_hours` | 24 hours |
+
+Explicit `latency_warning_thresholds` entries still win over the naming convention.
+
+The queues page also sorts by SLA: queues with a detectable latency target come first
+(strictest at the top), and everything else follows alphabetically.
+
+## Notes
+
+- **Separate queue database**: works automatically. Job Board reads and writes exclusively
+  through the `SolidQueue::*` models, which connect to whatever database
+  `config.solid_queue.connects_to` points at.
+- **Latency** is computed the same way Solid Queue itself defines it: seconds since the oldest
+  ready execution in the queue was enqueued (0 for an empty queue). Scheduled and failed jobs
+  don't count against latency.
+- **`preserve_finished_jobs = false`** hosts will see an explanatory empty state on the
+  Finished tab, since finished jobs are deleted immediately.
+- **Discarding is permanent** — Solid Queue deletes the job row entirely; there is no trash.
+  In-progress jobs can't be discarded.
+- Queue names containing `/` can't be paused through the UI (route limitation).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+
+# Run the demo app with seeded data:
+cd test/dummy
+bin/rails db:prepare db:seed
+bin/rails server
+# open http://localhost:3000/job_board
+
+# Optionally start real workers against the seeded jobs:
+bin/rails solid_queue:start
+```
+
+## License
+
+MIT.

data/app/controllers/job_board/application_controller.rb

@@ -0,0 +1,24 @@
+module JobBoard
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    before_action :authenticate
+
+    layout "job_board/application"
+
+    private
+      def authenticate
+        credentials = JobBoard.config.http_basic_auth
+        return unless credentials
+
+        authenticate_or_request_with_http_basic("JobBoard") do |name, password|
+          ActiveSupport::SecurityUtils.secure_compare(name, credentials[:name].to_s) &
+            ActiveSupport::SecurityUtils.secure_compare(password, credentials[:password].to_s)
+        end
+      end
+
+      def stale_threshold
+        JobBoard.config.stale_process_threshold || SolidQueue.process_alive_threshold
+      end
+  end
+end

data/app/controllers/job_board/assets_controller.rb

@@ -0,0 +1,19 @@
+module JobBoard
+  class AssetsController < ApplicationController
+    skip_forgery_protection
+
+    ASSETS = {
+      "application.css" => "text/css",
+      "application.js" => "text/javascript"
+    }.freeze
+
+    def show
+      name = params[:name]
+      content_type = ASSETS[name] or return head(:not_found)
+
+      expires_in 1.year, public: true
+      send_file JobBoard::Engine.root.join("lib/job_board/assets", name),
+        type: content_type, disposition: :inline
+    end
+  end
+end

data/app/controllers/job_board/jobs_controller.rb

@@ -0,0 +1,88 @@
+module JobBoard
+  class JobsController < ApplicationController
+    before_action :set_query, only: [:index, :retry_all, :discard_all]
+
+    def index
+      @page = @query.page(before: params[:before], limit: JobBoard.config.per_page)
+      @counts = @query.counts
+      @queues = LatencySla.sort(SolidQueue::Queue.all)
+    end
+
+    def show
+      @job = JobPresenter.new(find_job)
+    end
+
+    def retry
+      job = find_job
+      if job.failed_execution.present?
+        job.retry
+        redirect_back_or_to jobs_path(status: "failed"), notice: "Job ##{job.id} queued for retry."
+      else
+        redirect_back_or_to jobs_path, alert: "Job ##{job.id} is not failed, so it can't be retried."
+      end
+    end
+
+    def discard
+      job = find_job
+      if job.status == :claimed
+        redirect_back_or_to jobs_path, alert: "Job ##{job.id} is in progress and can't be discarded."
+      elsif job.finished?
+        redirect_back_or_to jobs_path, alert: "Job ##{job.id} is already finished."
+      else
+        job.discard
+        redirect_to jobs_path(status: params[:status] || "failed"), notice: "Job ##{job.id} discarded."
+      end
+    end
+
+    def retry_all
+      count = 0
+      failed_jobs_in_batches do |batch|
+        SolidQueue::FailedExecution.retry_all(batch)
+        count += batch.size
+      end
+      redirect_to failed_jobs_path, notice: "#{count} #{"job".pluralize(count)} queued for retry."
+    end
+
+    def discard_all
+      count = 0
+      failed_jobs_in_batches do |batch|
+        SolidQueue::FailedExecution.discard_all_from_jobs(batch)
+        count += batch.size
+      end
+      redirect_to failed_jobs_path, notice: "#{count} #{"job".pluralize(count)} discarded."
+    end
+
+    private
+      def set_query
+        status = params[:status].presence || "ready"
+        head :not_found and return unless JobsQuery::STATUSES.include?(status)
+
+        @query = JobsQuery.new(
+          status: status,
+          queue_name: params[:queue_name].presence,
+          class_name: params[:class_name].presence
+        )
+      end
+
+      def find_job
+        SolidQueue::Job
+          .includes(:ready_execution, :scheduled_execution, :claimed_execution,
+                    :blocked_execution, :failed_execution)
+          .find(params[:id])
+      end
+
+      def failed_jobs_in_batches(&block)
+        query = JobsQuery.new(
+          status: "failed",
+          queue_name: params[:queue_name].presence,
+          class_name: params[:class_name].presence
+        )
+        query.failed_jobs_relation.find_in_batches(batch_size: 500, &block)
+      end
+
+      def failed_jobs_path
+        jobs_path(status: "failed", queue_name: params[:queue_name].presence,
+                  class_name: params[:class_name].presence)
+      end
+  end
+end

data/app/controllers/job_board/processes_controller.rb

@@ -0,0 +1,7 @@
+module JobBoard
+  class ProcessesController < ApplicationController
+    def index
+      @tree = ProcessTree.build(stale_threshold: stale_threshold)
+    end
+  end
+end

data/app/controllers/job_board/queues/pauses_controller.rb

@@ -0,0 +1,15 @@
+module JobBoard
+  module Queues
+    class PausesController < ApplicationController
+      def create
+        SolidQueue::Queue.find_by_name(params[:queue_name]).pause
+        redirect_to queues_path, notice: "Queue \"#{params[:queue_name]}\" paused."
+      end
+
+      def destroy
+        SolidQueue::Queue.find_by_name(params[:queue_name]).resume
+        redirect_to queues_path, notice: "Queue \"#{params[:queue_name]}\" resumed."
+      end
+    end
+  end
+end

data/app/controllers/job_board/queues_controller.rb

@@ -0,0 +1,9 @@
+module JobBoard
+  class QueuesController < ApplicationController
+    def index
+      @queues = LatencySla.sort(SolidQueue::Queue.all)
+      @failed_counts = SolidQueue::FailedExecution.joins(:job)
+        .group("solid_queue_jobs.queue_name").count
+    end
+  end
+end

data/app/controllers/job_board/recurring_tasks_controller.rb

@@ -0,0 +1,7 @@
+module JobBoard
+  class RecurringTasksController < ApplicationController
+    def index
+      @tasks = SolidQueue::RecurringTask.order(:key)
+    end
+  end
+end

data/app/helpers/job_board/application_helper.rb

@@ -0,0 +1,40 @@
+module JobBoard
+  module ApplicationHelper
+    def status_badge(status)
+      tag.span(status.to_s.humanize, class: "badge badge--#{status}")
+    end
+
+    def time_ago(time)
+      return tag.span("–", class: "muted") if time.blank?
+
+      time = Time.zone.parse(time) if time.is_a?(String)
+      tag.time("#{duration((Time.current - time).abs)} #{time.future? ? "from now" : "ago"}",
+        title: time.iso8601, datetime: time.iso8601)
+    end
+
+    def duration(seconds)
+      seconds = seconds.to_i
+      return "0s" if seconds <= 0
+
+      parts = { "d" => 86400, "h" => 3600, "m" => 60, "s" => 1 }.filter_map do |unit, size|
+        value, seconds = seconds.divmod(size)
+        "#{value}#{unit}" if value.positive?
+      end
+      parts.first(2).join(" ")
+    end
+
+    # Latency (seconds) above which a queue counts as breaching. Resolution order:
+    # explicit per-queue config, a threshold parsed from a within_* style name,
+    # then the global default.
+    def latency_threshold_for(queue_name)
+      LatencySla.threshold_for(queue_name)
+    end
+
+    def format_json(value)
+      value = JSON.parse(value) if value.is_a?(String)
+      JSON.pretty_generate(value)
+    rescue JSON::ParserError, JSON::GeneratorError
+      value.to_s
+    end
+  end
+end

data/app/models/job_board/job_presenter.rb

@@ -0,0 +1,37 @@
+module JobBoard
+  # Detail-page wrapper around a SolidQueue::Job loaded with all five
+  # has_one execution associations preloaded.
+  class JobPresenter
+    attr_reader :job
+
+    delegate :id, :queue_name, :class_name, :priority, :active_job_id,
+             :concurrency_key, :created_at, :finished_at, :finished?,
+             :failed_execution, :status, to: :job
+
+    def initialize(job)
+      @job = job
+    end
+
+    # The serialized ActiveJob payload (Job#arguments is JSON-coded by SolidQueue).
+    def payload
+      @payload ||= job.arguments || {}
+    rescue StandardError
+      @payload = {}
+    end
+
+    def arguments = payload["arguments"]
+    def executions_count = payload["executions"]
+    def exception_executions = payload["exception_executions"]
+    def enqueued_at = payload["enqueued_at"]
+
+    def scheduled_at
+      job.scheduled_execution&.scheduled_at || job.scheduled_at
+    end
+
+    def error = failed_execution
+
+    def process
+      job.claimed_execution&.process
+    end
+  end
+end

data/app/models/job_board/job_row.rb

@@ -0,0 +1,48 @@
+module JobBoard
+  # Uniform row facade so the jobs table doesn't care whether a row came from
+  # an execution record or a finished job.
+  class JobRow
+    attr_reader :job, :status, :execution
+
+    def self.from_execution(execution, status:)
+      new(job: execution.job, status: status, execution: execution)
+    end
+
+    def self.from_job(job, status: :finished)
+      new(job: job, status: status)
+    end
+
+    def initialize(job:, status:, execution: nil)
+      @job = job
+      @status = status.to_sym
+      @execution = execution
+    end
+
+    def id = job.id
+    def queue_name = job.queue_name
+    def class_name = job.class_name
+    def priority = job.priority
+    def enqueued_at = job.created_at
+    def finished_at = job.finished_at
+
+    def scheduled_at
+      status == :scheduled ? execution.scheduled_at : job.scheduled_at
+    end
+
+    def process
+      execution.process if status == :claimed && execution
+    end
+
+    def concurrency_key
+      execution.concurrency_key if status == :blocked && execution
+    end
+
+    def error_class
+      execution.exception_class if status == :failed && execution
+    end
+
+    def error_message
+      execution.message if status == :failed && execution
+    end
+  end
+end

data/app/models/job_board/jobs_query.rb

@@ -0,0 +1,86 @@
+module JobBoard
+  # Status-scoped job finder. Each status is driven by its execution table so a
+  # row's status is known without calling Job#status (which needs 5 preloads).
+  class JobsQuery
+    STATUSES = %w[ready scheduled in_progress blocked failed finished].freeze
+
+    ROW_STATUS = {
+      "ready" => :ready, "scheduled" => :scheduled, "in_progress" => :claimed,
+      "blocked" => :blocked, "failed" => :failed, "finished" => :finished
+    }.freeze
+
+    attr_reader :status, :queue_name, :class_name
+
+    def initialize(status:, queue_name: nil, class_name: nil)
+      @status = status.to_s
+      @queue_name = queue_name
+      @class_name = class_name
+    end
+
+    def page(before: nil, limit: 25)
+      row_status = ROW_STATUS.fetch(status)
+      builder =
+        if status == "finished"
+          ->(job) { JobRow.from_job(job) }
+        else
+          ->(execution) { JobRow.from_execution(execution, status: row_status) }
+        end
+      Page.new(relation.order(id: :desc), before: before, limit: limit, &builder)
+    end
+
+    # One COUNT per status, with the current filters applied — for tab badges.
+    def counts
+      STATUSES.index_with do |s|
+        self.class.new(status: s, queue_name: queue_name, class_name: class_name).count
+      end
+    end
+
+    def count
+      relation.count(:all)
+    end
+
+    # Job relation backing bulk retry/discard. Only meaningful for the failed set,
+    # so it is always scoped to jobs with a failed execution.
+    def failed_jobs_relation
+      scope = SolidQueue::Job.joins(:failed_execution)
+      scope = scope.where(queue_name: queue_name) if queue_name
+      scope = scope.where(class_name: class_name) if class_name
+      scope
+    end
+
+    private
+      def relation
+        case status
+        when "ready"
+          filtered(SolidQueue::ReadyExecution.includes(:job), own_queue_column: true)
+        when "scheduled"
+          filtered(SolidQueue::ScheduledExecution.includes(:job), own_queue_column: true)
+        when "in_progress"
+          filtered(SolidQueue::ClaimedExecution.includes(:process, :job), own_queue_column: false)
+        when "blocked"
+          filtered(SolidQueue::BlockedExecution.includes(:job), own_queue_column: true)
+        when "failed"
+          filtered(SolidQueue::FailedExecution.includes(:job), own_queue_column: false)
+        when "finished"
+          filtered_jobs(SolidQueue::Job.finished)
+        else
+          raise ArgumentError, "unknown status #{status.inspect}"
+        end
+      end
+
+      def filtered(scope, own_queue_column:)
+        if queue_name
+          scope = own_queue_column ? scope.where(queue_name: queue_name)
+                                   : scope.joins(:job).where(solid_queue_jobs: { queue_name: queue_name })
+        end
+        scope = scope.joins(:job).where(solid_queue_jobs: { class_name: class_name }) if class_name
+        scope
+      end
+
+      def filtered_jobs(scope)
+        scope = scope.where(queue_name: queue_name) if queue_name
+        scope = scope.where(class_name: class_name) if class_name
+        scope
+      end
+  end
+end

data/app/models/job_board/latency_sla.rb

@@ -0,0 +1,31 @@
+module JobBoard
+  # Detects a queue's latency SLA from explicit configuration or from the
+  # within_* naming convention (e.g. "within_5_minutes" => 300).
+  module LatencySla
+    UNITS = { "second" => 1, "minute" => 60, "hour" => 3600, "day" => 86400 }.freeze
+
+    # Seconds, or nil when the queue has no detectable SLA.
+    def self.detect(queue_name)
+      JobBoard.config.latency_warning_thresholds[queue_name.to_s] || from_name(queue_name)
+    end
+
+    # The latency-warning threshold: the detected SLA, else the global default.
+    def self.threshold_for(queue_name)
+      detect(queue_name) || JobBoard.config.latency_warning_threshold
+    end
+
+    # Queues with a detectable SLA first, strictest first; the rest alphabetical.
+    def self.sort(queues)
+      queues.sort_by do |queue|
+        sla = detect(queue.name)
+        [sla ? 0 : 1, sla || 0, queue.name]
+      end
+    end
+
+    def self.from_name(queue_name)
+      match = /\Awithin_(\d+)_(second|minute|hour|day)s?\z/i.match(queue_name.to_s)
+      match && match[1].to_i * UNITS.fetch(match[2].downcase)
+    end
+    private_class_method :from_name
+  end
+end

data/app/models/job_board/page.rb

@@ -0,0 +1,35 @@
+module JobBoard
+  # Keyset pagination over a relation ordered by id DESC.
+  # Fetches limit + 1 records to detect whether an older page exists.
+  class Page
+    include Enumerable
+
+    attr_reader :records, :rows
+
+    def initialize(relation, before: nil, limit: 25, &row_builder)
+      relation = relation.where(id: ...before.to_i) if before.present?
+      fetched = relation.limit(limit + 1).to_a
+      @more = fetched.size > limit
+      @records = fetched.first(limit)
+      @rows = row_builder ? @records.map(&row_builder) : @records
+    end
+
+    def more?
+      @more
+    end
+
+    # Keyset cursor for the next (older) page — the id of the raw record,
+    # which is an execution id for execution-backed lists and a job id for finished.
+    def next_before
+      records.last&.id
+    end
+
+    def each(&block)
+      rows.each(&block)
+    end
+
+    def empty?
+      records.empty?
+    end
+  end
+end

data/app/models/job_board/process_tree.rb

@@ -0,0 +1,49 @@
+module JobBoard
+  # Supervisor -> supervisee tree of SolidQueue processes with staleness flags,
+  # claimed-job counts, and the in-progress jobs each worker holds.
+  class ProcessTree
+    Node = Data.define(:process, :children, :claimed_count, :stale)
+
+    attr_reader :roots, :orphaned_claimed_count
+
+    def self.build(stale_threshold:)
+      new(stale_threshold: stale_threshold)
+    end
+
+    def initialize(stale_threshold:)
+      processes = SolidQueue::Process.order(:id).to_a
+      ids = processes.map(&:id).to_set
+      counts = SolidQueue::ClaimedExecution.group(:process_id).count
+      @claimed_by_process =
+        SolidQueue::ClaimedExecution.where(process_id: processes.map(&:id))
+          .includes(:job).group_by(&:process_id)
+
+      cutoff = stale_threshold.ago
+      children = processes.group_by(&:supervisor_id)
+      build_node = nil
+      build_node = lambda do |process|
+        Node.new(
+          process: process,
+          children: (children[process.id] || []).map(&build_node),
+          claimed_count: counts[process.id] || 0,
+          stale: process.last_heartbeat_at < cutoff
+        )
+      end
+
+      # Roots: no supervisor, or a supervisor that no longer exists.
+      root_processes = processes.select { |p| p.supervisor_id.nil? || !ids.include?(p.supervisor_id) }
+      supervisors, others = root_processes.partition { |p| p.kind.to_s.start_with?("Supervisor") }
+      @roots = (supervisors + others).map(&build_node)
+
+      @orphaned_claimed_count = SolidQueue::ClaimedExecution.orphaned.count
+    end
+
+    def claimed_executions_for(process)
+      @claimed_by_process[process.id] || []
+    end
+
+    def empty?
+      roots.empty?
+    end
+  end
+end