flightdeck 0.5.0

data/app/helpers/flightdeck/infrastructure_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module InfrastructureHelper
+    RECURRING_STATUS = {
+      ok: [ "OK", "finished" ],
+      failed: [ "LAST RUN FAILED", "failed" ],
+      unknown: [ "PURGED", "scheduled" ]
+    }.freeze
+
+    def dom_id_for_queue(name) = "fd-queue-#{name.parameterize.presence || Digest::MD5.hexdigest(name)}"
+    def dom_id_for_process(id) = "fd-process-#{id}"
+    def dom_id_for_recurring_task(id) = "fd-recurring-task-#{id}"
+
+    # A task that has never run has no status to report, and a task whose job has
+    # been purged is reported as purged rather than as a success we did not see.
+    def fd_recurring_status_pill(status)
+      return tag.span("—", class: "dim") if status.nil?
+
+      label, pill = RECURRING_STATUS.fetch(status, [ status.to_s.upcase, "scheduled" ])
+      tag.span(label, class: "fd-pill #{pill}")
+    end
+  end
+end

data/app/helpers/flightdeck/jobs_helper.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module JobsHelper
+    STATE_LABELS = {
+      all: "All",
+      ready: "Ready",
+      scheduled: "Scheduled",
+      in_progress: "In progress",
+      blocked: "Blocked",
+      finished: "Finished",
+      failed: "Failed",
+      unknown: "Unknown"
+    }.freeze
+
+    PILL_CLASSES = {
+      ready: "ready",
+      scheduled: "scheduled",
+      in_progress: "progress",
+      blocked: "blocked",
+      finished: "finished",
+      failed: "failed",
+      unknown: "scheduled"
+    }.freeze
+
+    def fd_state_label(state) = STATE_LABELS.fetch(state.to_sym, state.to_s.humanize)
+
+    def fd_state_pill(state)
+      tag.span(fd_state_label(state).upcase,
+               class: "fd-pill #{PILL_CLASSES.fetch(state.to_sym, "scheduled")}")
+    end
+
+    def fd_queue_badge(queue_name)
+      tag.span(queue_name.presence || "—", class: "fd-qbadge")
+    end
+
+    # Counts are capped by JobsQuery, so a capped value is rendered as "500,000+"
+    # rather than pretending to be exact.
+    def fd_count(count, capped: false)
+      "#{number_with_delimiter(count)}#{"+" if capped}"
+    end
+
+    def fd_time(time)
+      return "—" if time.blank?
+
+      tag.span(time.in_time_zone(Flightdeck.config.display_timezone).strftime("%H:%M:%S"),
+               title: fd_full_time(time))
+    end
+
+    def fd_full_time(time)
+      return "—" if time.blank?
+
+      time.in_time_zone(Flightdeck.config.display_timezone).strftime("%Y-%m-%d %H:%M:%S %Z")
+    end
+
+    def fd_duration(seconds)
+      return "—" if seconds.nil?
+
+      seconds = seconds.to_f.abs
+      case seconds
+      when 0...1 then "#{(seconds * 1000).round}ms"
+      when 1...60 then "#{seconds.round(1)}s"
+      when 60...3600 then "#{(seconds / 60).round}m"
+      when 3600...86_400 then "#{(seconds / 3600).round(1)}h"
+      else "#{(seconds / 86_400).round(1)}d"
+      end
+    end
+
+    def fd_ago(time)
+      return "—" if time.blank?
+
+      "#{fd_duration(Time.current - time)} ago"
+    end
+
+    # Best-effort "what has this job been doing" column. Only ever derived from
+    # timestamps Solid Queue actually keeps — nothing here is estimated.
+    def fd_progress_label(row)
+      case row.state
+      when :ready
+        "waited #{fd_duration(Time.current - row.due_at)}"
+      when :scheduled
+        row.scheduled_at&.future? ? "due in #{fd_duration(row.scheduled_at - Time.current)}" : "due now"
+      when :in_progress
+        started = row.execution_started_at
+        return "running" unless started
+
+        "waited #{fd_duration(started - row.due_at)} · running #{fd_duration(Time.current - started)}"
+      when :blocked
+        row.concurrency_key.presence ? "concurrency: #{row.concurrency_key}" : "blocked"
+      when :finished
+        row.finished_at ? "total #{fd_duration(row.finished_at - row.enqueued_at)}" : "—"
+      when :failed
+        row.failed_at ? "failed after #{fd_duration(row.failed_at - row.due_at)}" : "—"
+      else
+        "—"
+      end
+    end
+
+    # Shows the job's own arguments rather than the ActiveJob envelope they
+    # are wrapped in; see Flightdeck::ArgumentsPreview.
+    def fd_args_preview(preview, length: 120)
+      Flightdeck::ArgumentsPreview.format(preview, length: length)
+    end
+
+    def fd_jobs_url(overrides = {})
+      jobs_path(list_filters.merge(state: params[:state].presence).compact.merge(overrides))
+    end
+
+    # The frame refreshes itself by re-requesting the URL it is showing, so
+    # filters, state tab and cursor all survive a poll.
+    def fd_current_list_url
+      jobs_path(request.query_parameters)
+    end
+
+    def dom_id_for_job(id) = "fd-job-#{id}"
+
+    # Under an exception-class group header, repeating the class on every row is
+    # noise — the message is the part that differs.
+    def fd_error_cell(summary, grouped: false)
+      return "—" unless summary.present?
+
+      text = grouped ? summary.message.presence || summary.exception_class : summary.to_s
+      text.to_s
+    end
+
+    # URL the refreshed frame should poll after an action, rebuilt from the
+    # filters the action carried rather than from the POST's own path.
+    def fd_refreshed_list_url
+      jobs_path(list_filters.merge(state: @refreshed_state == :all ? nil : @refreshed_state).compact)
+    end
+
+    def fd_toast_level_class(level)
+      level.to_sym == :error ? "fd-toast error" : "fd-toast"
+    end
+  end
+end

data/app/helpers/flightdeck/metrics_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  module MetricsHelper
+    TREND_GLYPHS = { up: "▲", down: "▼", flat: "▪" }.freeze
+
+    def fd_poll_ms = (Flightdeck.config.poll_interval.to_f * 1000).round
+    def fd_chart_poll_ms = (Flightdeck.config.chart_poll_interval.to_f * 1000).round
+
+    def fd_poll_seconds = Flightdeck.config.poll_interval.to_i
+
+    def fd_trend_glyph(trend) = TREND_GLYPHS.fetch(trend.to_sym, TREND_GLYPHS[:flat])
+
+    # --- topbar clock ---------------------------------------------------------
+    #
+    # Rendered server-side so the clock is right before JavaScript runs, and
+    # driven by an offset so it keeps showing the configured display timezone
+    # rather than the viewer's.
+
+    def fd_display_zone
+      ActiveSupport::TimeZone[Flightdeck.config.display_timezone] || ActiveSupport::TimeZone["UTC"]
+    end
+
+    def fd_clock_now = "#{Time.current.in_time_zone(fd_display_zone).strftime("%H:%M:%S")} #{fd_zone_label}"
+
+    def fd_zone_label
+      zone = fd_display_zone
+      zone.name == "UTC" ? "UTC" : Time.current.in_time_zone(zone).strftime("%Z")
+    end
+
+    def fd_zone_offset_seconds
+      fd_display_zone.now.utc_offset
+    end
+
+    # Colour follows whether the movement is good news, not which way the arrow
+    # points: more failures is an "up" arrow but bad news.
+    def fd_delta_class(tile)
+      return "flat" if tile.trend.to_sym == :flat
+
+      tile.good ? "up" : "down"
+    end
+
+    def fd_depth_share(depth, max)
+      return 0 if max.to_i.zero?
+
+      [ (depth.to_f / max * 100).round, 100 ].min
+    end
+  end
+end

data/app/models/flightdeck/arguments_preview.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Turns a job's stored payload into the one part of it a list row wants: the
+  # actual job arguments.
+  #
+  # What Solid Queue stores is the whole ActiveJob serialization —
+  # `{"job_class":…,"job_id":…,"queue_name":…,"arguments":[…],…}` — so a raw
+  # preview is almost entirely boilerplate that is identical on every row. The
+  # job detail page still shows the full payload, where it is genuinely useful.
+  #
+  # The input is a byte prefix truncated by SQL, so the JSON is usually cut off
+  # mid-value. Parsing is lenient by design: extract what is there, and fall
+  # back to the raw prefix rather than showing nothing.
+  class ArgumentsPreview
+    KEY = /"arguments"\s*:\s*/
+    ELLIPSIS = "…"
+
+    def self.format(raw, length: 120)
+      new(raw).to_s(length: length)
+    end
+
+    def initialize(raw)
+      @raw = raw.to_s
+    end
+
+    def to_s(length: 120)
+      value = extract
+      return "" if value.blank?
+
+      value.gsub(/\s+/, " ").strip.truncate(length, omission: ELLIPSIS)
+    end
+
+    private
+      attr_reader :raw
+
+      def extract
+        return "" if raw.blank?
+
+        from_parsed_payload || from_truncated_payload || raw
+      end
+
+      # The happy path: the prefix happened to contain the whole payload.
+      def from_parsed_payload
+        parsed = JSON.parse(raw)
+        return nil unless parsed.is_a?(Hash) && parsed.key?("arguments")
+
+        JSON.generate(parsed["arguments"])
+      rescue JSON::ParserError
+        nil
+      end
+
+      # The usual path: the payload was cut off, so walk the arguments value
+      # ourselves and take as much of it as survived.
+      def from_truncated_payload
+        match = KEY.match(raw)
+        return nil unless match
+
+        balanced_prefix(raw[match.end(0)..].to_s)
+      end
+
+      # Reads one JSON value from the front of `text`, stopping either when it
+      # closes cleanly or when the string runs out mid-value.
+      def balanced_prefix(text)
+        return nil if text.empty?
+
+        depth = 0
+        in_string = false
+        escaped = false
+
+        text.each_char.with_index do |char, index|
+          if escaped
+            escaped = false
+          elsif char == "\\"
+            escaped = true
+          elsif char == '"'
+            in_string = !in_string
+          elsif !in_string
+            case char
+            when "[", "{" then depth += 1
+            when "]", "}"
+              depth -= 1
+              return text[0..index] if depth.zero?
+            when ","
+              # A top-level comma means the arguments value ended and the next
+              # payload key has begun.
+              return text[0...index] if depth.zero?
+            end
+          end
+        end
+
+        "#{text}#{ELLIPSIS}"
+      end
+  end
+end

data/app/models/flightdeck/bulk_action.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Applies a Solid Queue operation across a filtered relation in bounded,
+  # individually-committed batches.
+  #
+  # Three things keep this safe to run against a live queue:
+  #   * a hard record limit (`Flightdeck.config.bulk_action_limit`),
+  #   * a wall-clock deadline measured on the monotonic clock, and
+  #   * a commit per batch, so stopping early still leaves completed work done.
+  #
+  # Stopping early is a normal outcome, not an error: the caller reports
+  # "Retried 1,000 of ~14,200" and the same request can simply be submitted
+  # again to continue.
+  class BulkAction
+    BATCH_SIZE = 100
+    DEADLINE = 10.seconds
+
+    Result = Struct.new(:processed, :failed, :total, :total_capped, :stopped, keyword_init: true) do
+      def stopped_early? = stopped.present?
+      def remaining = [ total - processed, 0 ].max
+      def remaining? = stopped_early? && remaining.positive?
+      def total_label = total_capped ? "#{total}+" : total.to_s
+    end
+
+    attr_reader :relation, :limit, :deadline, :count_cap
+
+    def initialize(relation:, limit: nil, deadline: DEADLINE, count_cap: nil)
+      @relation = relation
+      @limit = (limit || Flightdeck.config.bulk_action_limit).to_i
+      @deadline = deadline
+      @count_cap = (count_cap || Flightdeck.config.count_cap).to_i
+    end
+
+    def call(&operation)
+      total = relation.limit(count_cap).count
+      started_at = monotonic_now
+      processed = 0
+      failed = 0
+      stopped = nil
+
+      relation.in_batches(of: BATCH_SIZE, order: :desc) do |batch|
+        SolidQueue::Record.transaction do
+          batch.each do |record|
+            if processed + failed >= limit
+              stopped = :limit
+              break
+            end
+
+            begin
+              operation.call(record)
+              processed += 1
+            rescue ActiveRecord::RecordNotFound, ActiveRecord::Deadlocked
+              # The queue moved under us — a worker finished or retried this job
+              # first. Skip it; the caller's counts stay honest.
+              failed += 1
+            end
+          end
+        end
+
+        break if stopped
+
+        if monotonic_now - started_at >= deadline
+          stopped = :deadline
+          break
+        end
+      end
+
+      Result.new(
+        processed: processed,
+        failed: failed,
+        total: total,
+        total_capped: total >= count_cap,
+        stopped: stopped
+      )
+    end
+
+    private
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+  end
+end

data/app/models/flightdeck/cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Thin wrapper over Rails.cache for the dashboard's short-lived aggregates.
+  #
+  # Two things it guarantees:
+  #   * it degrades to simply calling the block, so a host running the null
+  #     store (or no cache at all) still gets a working dashboard;
+  #   * a mutation can ask for fresh numbers via .bypass, so the response to a
+  #     retry never shows the counts from before the retry.
+  module Cache
+    NAMESPACE = "flightdeck"
+
+    class << self
+      def fetch(*key_parts, expires_in:, &block)
+        store = Rails.cache
+        return block.call if store.nil? || expires_in.to_f <= 0
+
+        store.fetch(key_for(key_parts), expires_in: expires_in, force: bypass?, &block)
+      rescue StandardError
+        # A cache backend that is down must never take the dashboard with it.
+        block.call
+      end
+
+      # Inside this block every fetch recomputes and rewrites, so a page
+      # rendered straight after a mutation reflects it.
+      def bypass
+        previous = Thread.current[:flightdeck_cache_bypass]
+        Thread.current[:flightdeck_cache_bypass] = true
+        yield
+      ensure
+        Thread.current[:flightdeck_cache_bypass] = previous
+      end
+
+      def bypass? = Thread.current[:flightdeck_cache_bypass].present?
+
+      def key_for(parts)
+        [ NAMESPACE, *Array(parts).flatten.map { |part| normalize(part) } ].join(":")
+      end
+
+      private
+        def normalize(part)
+          case part
+          when Hash then part.sort_by { |key, _| key.to_s }.map { |key, value| "#{key}=#{value}" }.join(",")
+          when nil then ""
+          else part.to_s
+          end
+        end
+    end
+  end
+end

data/app/models/flightdeck/cron_schedule.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Turns the common cron shapes into a readable sentence.
+  #
+  # Fugit parses cron but does not describe it, so this is ours. It only claims
+  # to understand patterns it genuinely does: anything else returns nil and the
+  # view shows the raw cron on its own. A confidently wrong description of a
+  # schedule is worse than no description.
+  class CronSchedule
+    DAYS = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+    MONTHS = %w[- January February March April May June July August September October November December].freeze
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw.to_s.strip
+    end
+
+    def self.humanize(raw) = new(raw).to_human
+
+    # Cron fields, plus an optional trailing timezone that Solid Queue allows.
+    def fields
+      @fields ||= begin
+        parts = raw.split(/\s+/)
+        parts.size.between?(5, 6) ? parts : nil
+      end
+    end
+
+    def timezone
+      fields && fields.size == 6 ? fields[5] : nil
+    end
+
+    def to_human
+      return nil unless fields
+
+      minute, hour, day_of_month, month, day_of_week = fields.first(5)
+      return nil unless simple?(minute, hour, day_of_month, month, day_of_week)
+
+      [ frequency(minute, hour, day_of_month, month, day_of_week), timezone ].compact.join(" ").presence
+    end
+
+    private
+      # Only fields we can describe faithfully: a wildcard, a plain number, or a
+      # `*/n` step. Lists and ranges are left to the raw cron.
+      def simple?(*values)
+        values.all? { |value| value.match?(%r{\A(\*|\d+|\*/\d+)\z}) }
+      end
+
+      def frequency(minute, hour, day_of_month, month, day_of_week)
+        return every_n_minutes(minute) if step(minute) && hour == "*"
+        return "every minute" if minute == "*" && hour == "*"
+
+        return nil unless minute.match?(/\A\d+\z/)
+
+        return "every #{pluralize_hours(step(hour))} at :#{pad(minute)}" if step(hour)
+        return "every hour at :#{pad(minute)}" if hour == "*"
+        return nil unless hour.match?(/\A\d+\z/)
+
+        at = "at #{pad(hour)}:#{pad(minute)}"
+
+        if day_of_week != "*"
+          # cron ORs day-of-month with day-of-week when both are restricted, so
+          # "0 0 1 1 1" is not "Mondays" — it is "January 1st or any Monday in
+          # January". Refuse to describe that rather than describe it wrongly.
+          return nil unless day_of_month == "*" && month == "*"
+          return nil unless day_of_week.match?(/\A\d+\z/)
+
+          return "#{DAYS[day_of_week.to_i % 7]}s #{at}"
+        end
+
+        return "#{ordinal_day(day_of_month)} of #{month_name(month)} #{at}" if day_of_month != "*" && month != "*"
+        return "#{ordinal_day(day_of_month)} of every month #{at}" if day_of_month != "*"
+        return "every day of #{month_name(month)} #{at}" if month != "*"
+
+        "every day #{at}"
+      end
+
+      def every_n_minutes(minute)
+        n = step(minute)
+        n == 1 ? "every minute" : "every #{n} minutes"
+      end
+
+      def pluralize_hours(n) = n == 1 ? "hour" : "#{n} hours"
+
+      def ordinal_day(value)
+        return nil unless value.match?(/\A\d+\z/)
+
+        "day #{value.to_i}"
+      end
+
+      def month_name(value)
+        value.match?(/\A\d+\z/) ? MONTHS[value.to_i] : nil
+      end
+
+      def step(value)
+        value[%r{\A\*/(\d+)\z}, 1]&.to_i
+      end
+
+      def pad(value) = format("%02d", value.to_i)
+  end
+end

data/app/models/flightdeck/error_summary.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # A failed execution's `error` column is JSON that can run to many kilobytes
+  # once a backtrace is in it. List views only ever read a bounded prefix of it,
+  # which means the JSON is usually truncated mid-string — so parse when we can
+  # and fall back to scanning for the two fields we need.
+  class ErrorSummary
+    UNKNOWN = "UnknownError"
+
+    attr_reader :exception_class, :message
+
+    def self.parse(raw)
+      new(raw)
+    end
+
+    def self.none
+      new(nil)
+    end
+
+    def initialize(raw)
+      @exception_class, @message = extract(raw)
+    end
+
+    def present?
+      exception_class.present?
+    end
+
+    def group_key
+      exception_class.presence || UNKNOWN
+    end
+
+    def to_s
+      return "" unless present?
+
+      message.present? ? "#{exception_class}: #{message}" : exception_class
+    end
+
+    private
+      def extract(raw)
+        return [ nil, nil ] if raw.blank?
+
+        parsed = safe_parse(raw)
+        return [ parsed["exception_class"].presence, parsed["message"].to_s ] if parsed.is_a?(Hash)
+
+        [
+          raw[/"exception_class"\s*:\s*"((?:[^"\\]|\\.)*)"/, 1]&.then { |value| unescape(value) },
+          raw[/"message"\s*:\s*"((?:[^"\\]|\\.)*)"/, 1]&.then { |value| unescape(value) }.to_s
+        ]
+      end
+
+      def safe_parse(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def unescape(value)
+        JSON.parse(%("#{value}"))
+      rescue JSON::ParserError
+        value
+      end
+  end
+end

data/app/models/flightdeck/grouped_failures.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Flightdeck
+  # Groups the failed rows of the *current page* by exception class.
+  #
+  # Grouping happens in Ruby on purpose. Extracting the exception class in SQL
+  # would mean a JSON function per adapter (and an unindexed scan of a large
+  # text column either way), which is a bad trade for a header row.
+  class GroupedFailures
+    Group = Struct.new(:key, :rows, keyword_init: true) do
+      def count = rows.size
+      def job_ids = rows.map(&:id)
+      def first_failed_at = rows.filter_map(&:failed_at).min
+      def last_failed_at = rows.filter_map(&:failed_at).max
+    end
+
+    def self.build(rows)
+      rows
+        .group_by { |row| row.error_summary.group_key }
+        .map { |key, grouped| Group.new(key: key, rows: grouped) }
+        .sort_by { |group| [ -group.count, group.key ] }
+    end
+  end
+end