flightdeck 0.5.0

data/app/assets/flightdeck/manifest.json

@@ -0,0 +1,16 @@
+{
+  "flightdeck.css": {
+    "file": "flightdeck-00403457c5d9.css",
+    "digest": "00403457c5d9",
+    "sha256": "00403457c5d9dd7455ccced13249ca5aa8f953e4532163f4493d58c561157350",
+    "content_type": "text/css; charset=utf-8",
+    "size": 118411
+  },
+  "flightdeck.js": {
+    "file": "flightdeck-c02e38040ddb.js",
+    "digest": "c02e38040ddb",
+    "sha256": "c02e38040ddb22871c1cb96daa7cb78242ceda0dd243c1ab3678fcf6f022d73e",
+    "content_type": "text/javascript; charset=utf-8",
+    "size": 150889
+  }
+}

data/app/controllers/concerns/flightdeck/toasts.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Shared response shape for the small member actions on the infrastructure
+  # pages: a toast plus a re-rendered frame over Turbo Streams, or a redirect
+  # carrying the same sentence in the flash when Turbo is not in play.
+  module Toasts
+    extend ActiveSupport::Concern
+
+    private
+      def toast(message, level: :success)
+        @toast = { message: message, level: level, continuable: false }
+      end
+
+      def respond_with_toast(template, fallback:)
+        respond_to do |format|
+          format.turbo_stream { render template, formats: :turbo_stream }
+          format.any do
+            flash[@toast[:level] == :error ? :alert : :notice] = @toast[:message]
+            redirect_to fallback
+          end
+        end
+      end
+  end
+end

data/app/controllers/flightdeck/application_controller.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support/security_utils"
+
+module Flightdeck
+  class ApplicationController < Flightdeck.base_controller_class
+    UNCONFIGURED_MESSAGE = <<~TEXT
+      Flightdeck is not configured for authentication, so it is refusing to
+      serve the dashboard.
+
+      Pick one of the following, then restart your app.
+
+      1. HTTP Basic via environment variables:
+
+           FLIGHTDECK_USERNAME=admin FLIGHTDECK_PASSWORD=a-long-secret
+
+      2. HTTP Basic via Rails credentials (bin/rails credentials:edit):
+
+           flightdeck:
+             username: admin
+             password: a-long-secret
+
+      3. HTTP Basic in an initializer (config/initializers/flightdeck.rb):
+
+           Flightdeck.configure do |config|
+             config.http_basic = { username: "admin", password: "a-long-secret" }
+           end
+
+      4. Reuse your application's own authentication by giving Flightdeck a
+         base controller to inherit from:
+
+           Flightdeck.configure do |config|
+             config.base_controller_class = "Admin::BaseController"
+           end
+
+      Flightdeck never serves unauthenticated requests, in any environment.
+    TEXT
+
+    protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
+
+    layout "flightdeck/application"
+
+    # Declared explicitly rather than relying on isolate_namespace: when the host
+    # supplies its own base controller, that controller's helper set is the one
+    # Rails wires up, and Flightdeck's own helpers would otherwise be missing.
+    helper Flightdeck::Engine.helpers
+
+    # Prepended so that an unauthenticated request is turned away before any
+    # other filter — including CSRF verification — gets a chance to answer it
+    # with a different status.
+    prepend_before_action :authenticate_flightdeck!
+
+    helper_method :list_filters
+
+    class << self
+      # True when the host handed us its own base controller: that controller's
+      # own filters are already in our callback chain, so Flightdeck must not
+      # layer a second, conflicting challenge on top of it.
+      def host_authenticated?
+        Flightdeck.config.base_controller_class.present?
+      end
+    end
+
+    private
+      # The filter set that identifies a list. Carried through pagination links,
+      # frame refreshes and "apply to all matching" so that every one of them is
+      # looking at exactly the same set of rows.
+      def list_filters
+        @list_filters ||= {
+          class_name: params[:class_name].presence,
+          queue_name: params[:queue_name].presence,
+          q: params[:q].presence
+        }.compact
+      end
+
+      def authenticate_flightdeck!
+        return if self.class.host_authenticated?
+
+        credentials = Flightdeck.config.resolve_http_basic
+        return render_unconfigured if credentials.nil?
+
+        authenticate_or_request_with_http_basic("Flightdeck") do |username, password|
+          secure_equal?(username, credentials[:username]) &
+            secure_equal?(password, credentials[:password])
+        end
+      end
+
+      def secure_equal?(given, expected)
+        ActiveSupport::SecurityUtils.secure_compare(given.to_s, expected.to_s)
+      end
+
+      def render_unconfigured
+        render plain: UNCONFIGURED_MESSAGE, status: :unauthorized, layout: false
+      end
+  end
+end

data/app/controllers/flightdeck/assets_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Deliberately not an ApplicationController subclass: assets are immutable,
+  # digest-addressed and carry no data, so they are served without auth and
+  # without the cost of the full ActionController::Base stack.
+  class AssetsController < ActionController::Metal
+    include ActionController::Head
+
+    CACHE_CONTROL = "public, max-age=31536000, immutable"
+
+    def show
+      entry = Flightdeck::Assets.find(params[:name])
+      return head(:not_found) unless entry
+
+      etag = %("#{entry["digest"]}")
+      headers["Cache-Control"] = CACHE_CONTROL
+      headers["ETag"] = etag
+      headers["X-Content-Type-Options"] = "nosniff"
+
+      return head(:not_modified) if stale_etag_match?(etag)
+
+      body = Flightdeck::Assets.read(params[:name])
+      return head(:not_found) unless body
+
+      headers["Content-Type"] = entry["content_type"] || Flightdeck::Assets.content_type_for(entry["file"])
+      self.status = 200
+      self.response_body = body
+    end
+
+    private
+      def stale_etag_match?(etag)
+        matches = request.get_header("HTTP_IF_NONE_MATCH")
+        return false if matches.nil?
+
+        matches == "*" || matches.split(",").any? { |candidate| candidate.strip == etag }
+      end
+  end
+end

data/app/controllers/flightdeck/jobs/actions_controller.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module Jobs
+    # Shared machinery for the two destructive jobs actions. Subclasses say what
+    # rows they act on and what Solid Queue method does the work; everything
+    # about scoping, batching, counting and responding lives here.
+    #
+    # Three scopes, one action:
+    #   * one job          POST /jobs/:id/retry
+    #   * selected jobs    POST /jobs/retry   with job_ids[]
+    #   * all matching     POST /jobs/retry   with scope=all + the list filters
+    class ActionsController < Flightdeck::ApplicationController
+      def create
+        result =
+          if params[:id].present?
+            act_on_single
+          elsif params[:scope] == "all"
+            act_on_all_matching
+          else
+            act_on_selected
+          end
+
+        respond_with(result)
+      end
+
+      private
+        # --- subclass contract ------------------------------------------------
+
+        # Relation of execution rows this action may act on, already filtered.
+        def target_relation
+          raise NotImplementedError
+        end
+
+        # The Solid Queue call that performs the action on one execution row.
+        def apply(execution)
+          raise NotImplementedError
+        end
+
+        def verb = raise(NotImplementedError)
+        def past_tense = raise(NotImplementedError)
+
+        # --- scopes -----------------------------------------------------------
+
+        def find_single(job_id)
+          target_relation.find_by(job_id: job_id)
+        end
+
+        def act_on_single
+          execution = find_single(params[:id])
+          return failure("That job is no longer #{blocked_reason}.") unless execution
+
+          apply(execution)
+          success("#{past_tense.capitalize} job ##{params[:id]}.")
+        rescue SolidQueue::Execution::UndiscardableError => error
+          failure(error.message)
+        end
+
+        # Selected ids are re-checked against the live relation rather than
+        # trusted: between rendering the page and clicking the button a worker
+        # may have retried, finished or discarded any of them.
+        def act_on_selected
+          ids = Array(params[:job_ids]).map { |id| Integer(id, exception: false) }.compact.uniq
+          return failure("Nothing selected.") if ids.empty?
+
+          if ids.size > Flightdeck.config.bulk_action_limit
+            return failure("Select at most #{number_with_delimiter(Flightdeck.config.bulk_action_limit)} jobs.")
+          end
+
+          executions = target_relation.where(job_id: ids).to_a
+          return failure("Those jobs are no longer #{blocked_reason}.") if executions.empty?
+
+          applied = 0
+          SolidQueue::Record.transaction do
+            executions.each do |execution|
+              apply(execution)
+              applied += 1
+            end
+          end
+
+          missing = ids.size - applied
+          message = "#{past_tense.capitalize} #{pluralize_jobs(applied)}."
+          message += " #{missing} had already moved on." if missing.positive?
+          success(message)
+        end
+
+        def act_on_all_matching
+          result = BulkAction.new(relation: target_relation).call { |execution| apply(execution) }
+
+          success(bulk_message(result), continuable: result.remaining?)
+        end
+
+        def bulk_message(result)
+          if result.stopped_early? && result.remaining?
+            "#{past_tense.capitalize} #{number_with_delimiter(result.processed)} of " \
+              "~#{result.total_label} — continue?"
+          else
+            "#{past_tense.capitalize} #{pluralize_jobs(result.processed)}."
+          end
+        end
+
+        # --- responses --------------------------------------------------------
+
+        def success(message, continuable: false)
+          { message: message, level: :success, continuable: continuable }
+        end
+
+        def failure(message)
+          { message: message, level: :error, continuable: false }
+        end
+
+        def respond_with(result)
+          @toast = result
+
+          respond_to do |format|
+            format.turbo_stream do
+              build_refreshed_list
+              render "flightdeck/jobs/actions/create", formats: :turbo_stream
+            end
+            format.html { redirect_back_to_list(result) }
+            format.any { redirect_back_to_list(result) }
+          end
+        end
+
+        # The list the action was launched from, re-queried so the same response
+        # that carries the toast also carries settled rows and counts.
+        def build_refreshed_list
+          # Bypass the count cache: this response exists precisely to show the
+          # effect of the action that just ran.
+          Flightdeck::Cache.bypass do
+            @refreshed_state = refreshed_state
+            @refreshed_query = JobsQuery.new(**list_filters, state: @refreshed_state)
+            @refreshed_rows = @refreshed_query.rows
+            @refreshed_groups = GroupedFailures.build(@refreshed_rows) if @refreshed_state == :failed
+          end
+        end
+
+        def refreshed_state
+          state = params[:state].presence&.to_sym || default_state
+          JobsQuery::STATES.include?(state) ? state : :all
+        end
+
+        def redirect_back_to_list(result)
+          flash[result[:level] == :error ? :alert : :notice] = result[:message]
+          redirect_to jobs_path(list_filters.merge(state: params[:state].presence || default_state))
+        end
+
+        def default_state = :failed
+
+        def blocked_reason = "eligible"
+
+        def pluralize_jobs(count)
+          "#{number_with_delimiter(count)} #{"job".pluralize(count)}"
+        end
+
+        def number_with_delimiter(value)
+          view_context.number_with_delimiter(value)
+        end
+
+        # The filters the list was showing, used to rebuild the exact same set
+        # server-side for "apply to all matching".
+        def scoped_query(state:)
+          JobsQuery.new(**list_filters, state: state)
+        end
+    end
+  end
+end

data/app/controllers/flightdeck/jobs/discards_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module Jobs
+    # Discarding delegates to Solid Queue's Execution#discard, which destroys the
+    # job and its execution row together and lets Solid Queue release whatever
+    # concurrency locks the job was holding.
+    #
+    # A job that is currently being executed cannot be discarded — Solid Queue
+    # raises UndiscardableError, and Flightdeck surfaces that rather than trying
+    # to work around it.
+    class DiscardsController < ActionsController
+      DISCARDABLE_STATES = %i[ready scheduled blocked failed].freeze
+
+      private
+        def target_relation
+          scoped_query(state: discard_state).filtered_relation
+        end
+
+        def discard_state
+          state = params[:state].presence&.to_sym || :failed
+          DISCARDABLE_STATES.include?(state) ? state : :failed
+        end
+
+        # A single discard may arrive from any list, so look for the job in every
+        # table it could legitimately be sitting in rather than trusting the
+        # state the page happened to be showing.
+        def find_single(job_id)
+          DISCARDABLE_STATES.lazy.filter_map do |state|
+            JobRow.model_for(state).find_by(job_id: job_id)
+          end.first
+        end
+
+        def apply(execution)
+          execution.discard
+        end
+
+        def verb = "discard"
+        def past_tense = "discarded"
+        def blocked_reason = "discardable"
+        def default_state = discard_state
+    end
+  end
+end

data/app/controllers/flightdeck/jobs/retries_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module Jobs
+    # Retrying is Solid Queue's own FailedExecution#retry: it resets the job's
+    # execution counters, re-dispatches it and deletes the failure row, all
+    # under a lock. Flightdeck never reimplements any of that.
+    class RetriesController < ActionsController
+      private
+        def target_relation
+          scoped_query(state: :failed).filtered_relation
+        end
+
+        def apply(execution)
+          execution.retry
+        end
+
+        def verb = "retry"
+        def past_tense = "retried"
+        def blocked_reason = "failed"
+    end
+  end
+end

data/app/controllers/flightdeck/jobs_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  class JobsController < ApplicationController
+    rescue_from JobsQuery::InvalidState, with: :unknown_state
+    rescue_from ActiveRecord::RecordNotFound, with: :job_gone
+
+    def index
+      @query = JobsQuery.new(**list_filters, state: state_param, before_id: params[:before_id])
+      @rows = @query.rows
+      @state_counts = JobsQuery.state_counts(**list_filters)
+      @groups = GroupedFailures.build(@rows) if state_param == :failed && group_failures?
+    end
+
+    def show
+      @job = JobDetail.find(params[:id])
+    end
+
+    private
+      def state_param
+        value = params[:state].presence&.to_sym || :all
+        raise JobsQuery::InvalidState, "unknown job state #{params[:state].inspect}" unless JobsQuery::STATES.include?(value)
+
+        value
+      end
+
+      def group_failures?
+        params[:group_by].blank? || params[:group_by] == "exception_class"
+      end
+
+      def unknown_state
+        redirect_to jobs_path, alert: "Unknown job state."
+      end
+
+      def job_gone
+        redirect_to jobs_path(state: params[:state]), alert: "That job no longer exists."
+      end
+  end
+end

data/app/controllers/flightdeck/overview_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  class OverviewController < ApplicationController
+    def index
+      @overview = Overview.new
+      @window = Metrics::Series.window_for(params[:range])
+      @series = @overview.series(window: @window.key)
+    end
+  end
+end

data/app/controllers/flightdeck/processes_controller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  class ProcessesController < ApplicationController
+    include Toasts
+
+    before_action :load_registry
+
+    def index
+    end
+
+    # Pruning is Solid Queue's Process#prune: it fails the process's claimed
+    # executions with a ProcessPrunedError and deregisters the row. Flightdeck
+    # only decides *whether* a process may be pruned.
+    def prune
+      node = @registry.find(params[:id])
+      return missing unless node
+
+      unless node.prunable?
+        toast "#{node.kind} #{node.name} is still sending heartbeats — only unresponsive " \
+              "processes can be pruned.", level: :error
+        return respond_with_toast("flightdeck/processes/prune", fallback: processes_path)
+      end
+
+      claimed = node.claimed_count
+      node.process.prune
+      load_registry
+
+      toast "Pruned #{node.kind} #{node.name}#{released(claimed)}."
+      respond_with_toast "flightdeck/processes/prune", fallback: processes_path
+    end
+
+    private
+      def load_registry
+        @registry = ProcessRegistry.new
+      end
+
+      def released(claimed)
+        return "" if claimed.zero?
+
+        " and released #{helpers.pluralize(claimed, "claimed execution")}"
+      end
+
+      def missing
+        toast "That process is no longer registered.", level: :error
+        respond_with_toast "flightdeck/processes/prune", fallback: processes_path
+      end
+  end
+end

data/app/controllers/flightdeck/queues_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  class QueuesController < ApplicationController
+    include Toasts
+
+    before_action :load_stats
+    before_action :require_known_queue, only: %i[pause resume]
+
+    def index
+    end
+
+    # Pausing and resuming are Solid Queue's own Queue#pause / #resume: they own
+    # what a pause means, and Flightdeck never writes solid_queue_pauses itself.
+    def pause
+      SolidQueue::Queue.new(@queue_name).pause
+      reload_stats
+      toast "Paused #{@queue_name}. Workers will stop picking up its jobs."
+      respond_with_toast "flightdeck/queues/update", fallback: queues_path
+    end
+
+    def resume
+      SolidQueue::Queue.new(@queue_name).resume
+      reload_stats
+      toast "Resumed #{@queue_name}."
+      respond_with_toast "flightdeck/queues/update", fallback: queues_path
+    end
+
+    private
+      def load_stats
+        @stats = QueueStats.new
+        @sparklines = Metrics::Series.queue_sparklines
+      end
+
+      def reload_stats
+        Flightdeck::Cache.bypass { load_stats }
+      end
+
+      # Only queues Flightdeck is actually showing can be paused. That keeps an
+      # arbitrary parameter from creating pause rows for queues that do not
+      # exist.
+      def require_known_queue
+        @queue_name = params[:name].to_s
+
+        return if @stats.find(@queue_name)
+
+        toast "Unknown queue #{@queue_name.presence || "(blank)"}.", level: :error
+        respond_with_toast "flightdeck/queues/update", fallback: queues_path
+      end
+  end
+end

data/app/controllers/flightdeck/recurring_tasks_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  class RecurringTasksController < ApplicationController
+    include Toasts
+
+    before_action :load_catalog
+
+    def index
+    end
+
+    # "Run now" is the task's own enqueue, so the recurring execution is
+    # recorded exactly as the scheduler would have recorded it.
+    def run
+      row = @catalog.find(params[:id])
+      return missing unless row
+
+      active_job = row.task.enqueue(at: Time.current)
+      load_catalog
+
+      if active_job
+        @enqueued_job_id = active_job.try(:provider_job_id)
+        toast "Enqueued #{row.key}#{job_reference}."
+      else
+        toast "#{row.key} was not enqueued — it has already run for this slot, or the job " \
+              "class refused to enqueue.", level: :error
+      end
+
+      respond_with_toast "flightdeck/recurring_tasks/run", fallback: recurring_tasks_path
+    end
+
+    private
+      def load_catalog
+        @catalog = RecurringCatalog.new
+      end
+
+      def job_reference
+        @enqueued_job_id ? " as job ##{@enqueued_job_id}" : ""
+      end
+
+      def missing
+        toast "That recurring task no longer exists.", level: :error
+        respond_with_toast "flightdeck/recurring_tasks/run", fallback: recurring_tasks_path
+      end
+  end
+end

data/app/helpers/flightdeck/application_helper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module ApplicationHelper
+    # Path to a built asset, resolved through the committed manifest. Returns
+    # nil when assets have not been built yet (fresh checkout / dev), so the
+    # layout can simply omit the tag instead of blowing up.
+    def flightdeck_asset_path(logical_name)
+      digested = Flightdeck::Assets.digested_name(logical_name)
+      return nil unless digested
+
+      flightdeck.asset_file_path(name: digested)
+    end
+
+    # Sidebar counts are capped like every other count, and degrade to "—"
+    # rather than taking the whole page down if the queue database is
+    # unreachable.
+    def fd_nav_count(state)
+      query = Flightdeck::JobsQuery.new(state: state)
+      fd_count(query.count, capped: query.count_capped?)
+    rescue ActiveRecord::ActiveRecordError
+      "—"
+    end
+
+    # Infrastructure counts, cached like every other count and degrading to "—"
+    # rather than taking the whole page down if the queue database is away.
+    def fd_nav_queue_count
+      nav_count("queues") { Flightdeck::QueueStats.new.rows.size }
+    end
+
+    def fd_nav_process_count
+      nav_count("processes") { SolidQueue::Process.count }
+    end
+
+    def fd_nav_recurring_count
+      nav_count("recurring") { SolidQueue::RecurringTask.count }
+    end
+
+    def fd_nav_any_dead_processes?
+      nav_count("dead_processes") do
+        SolidQueue::Process.where(last_heartbeat_at: ..SolidQueue.process_alive_threshold.ago).exists?
+      end == true
+    end
+
+    def fd_nav_active?(state)
+      return false unless controller_name == "jobs" && action_name == "index"
+
+      current = params[:state].presence&.to_sym || :all
+      current == state
+    end
+
+    def nav_count(name, &block)
+      Flightdeck::Cache.fetch("nav", name, expires_in: Flightdeck.config.poll_interval, &block)
+    rescue ActiveRecord::ActiveRecordError
+      "—"
+    end
+
+    def flightdeck_brand_svg(size: 26)
+      tag.svg(width: size, height: size, viewBox: "0 0 26 26", fill: "none", "aria-hidden": true) do
+        safe_join([
+          tag.circle(cx: 13, cy: 13, r: 11.5, stroke: "var(--accent-ink)", "stroke-width": 1.6),
+          tag.path(d: "M3 15 C 8 10.5, 18 10.5, 23 15", stroke: "var(--accent-ink)", "stroke-width": 1.6, fill: "none"),
+          tag.path(d: "M9.5 13.2 h7 M13 11.4 v1.8", stroke: "var(--ink)", "stroke-width": 1.6, "stroke-linecap": "round")
+        ])
+      end
+    end
+  end
+end