flight_control 2.0.0.beta.1 → 2.0.0.beta.3

data/app/helpers/flight_control/jobs_helper.rb

@@ -0,0 +1,105 @@
+module FlightControl::JobsHelper
+  def job_title(job)
+    job.job_class_name
+  end
+
+  def job_arguments(job)
+    renderable_job_arguments_for(job).join(", ")
+  end
+
+  def failed_job_error(job)
+    "#{job.last_execution_error.error_class}: #{job.last_execution_error.message}"
+  end
+
+  def clean_backtrace?
+    params["clean_backtrace"] == "true"
+  end
+
+  def failed_job_backtrace(job, server)
+    if clean_backtrace? && server&.backtrace_cleaner
+      server.backtrace_cleaner.clean(job.last_execution_error.backtrace).join("\n")
+    else
+      job.last_execution_error.backtrace.join("\n")
+    end
+  end
+
+  def job_duration(job)
+    return unless (seconds = job.duration)
+    tag.span formatted_duration(seconds), title: "#{seconds.round(3)} seconds"
+  end
+
+  def attribute_names_for_job_status(status)
+    case status.to_s
+    when "failed" then ["Error", "Duration", ""]
+    when "blocked" then ["Queue", "Blocked by", ""]
+    when "finished" then ["Queue", "Duration", "Finished"]
+    when "scheduled" then ["Queue", "Scheduled", ""]
+    when "in_progress" then ["Queue", "Run by", "Running for"]
+    else []
+    end
+  end
+
+  def job_delayed?(job)
+    job.scheduled_at.before?(FlightControl.scheduled_job_delay_threshold.ago)
+  end
+
+  def blocked_job_expiration(job)
+    "Expires #{bidirectional_time_distance_in_words_with_title(job.blocked_until)}".html_safe if job.blocked_until
+  end
+
+  private
+
+  DURATION_UNIT_ABBREVIATIONS = {years: "y", months: "mo", weeks: "w", days: "d", hours: "h", minutes: "m", seconds: "s"}
+
+  def formatted_duration(seconds)
+    if seconds < 1
+      "#{(seconds * 1000).round} ms"
+    elsif seconds < 60
+      "#{seconds.round(1)} s"
+    else
+      ActiveSupport::Duration.build(seconds.round).parts
+        .map { |unit, value| "#{value}#{DURATION_UNIT_ABBREVIATIONS[unit]}" }.join(" ")
+    end
+  end
+
+  def renderable_job_arguments_for(job)
+    job.serialized_arguments.collect do |argument|
+      as_renderable_argument(argument)
+    end
+  end
+
+  def as_renderable_argument(argument)
+    case argument
+    when Hash
+      as_renderable_hash(argument)
+    when Array
+      as_renderable_array(argument)
+    else
+      ActiveJob::Arguments.deserialize([argument]).first
+    end
+  rescue ActiveJob::DeserializationError
+    argument.to_s
+  end
+
+  def as_renderable_hash(argument)
+    if argument["_aj_globalid"]
+      # don't deserialize as the class might not exist in the host app running the engine
+      argument["_aj_globalid"]
+    elsif argument["_aj_serialized"] == "ActiveJob::Serializers::ModuleSerializer"
+      argument["value"]
+    elsif argument["_aj_serialized"]
+      ActiveJob::Arguments.deserialize([argument]).first
+    else
+      FlightControl.job_arguments_filter.apply_to(argument)
+        .without("_aj_symbol_keys", "_aj_ruby2_keywords")
+        .transform_values { |v| as_renderable_argument(v) }
+        .map { |k, v| "#{k}: #{v}" }
+        .join(", ")
+        .then { |s| "{#{s}}" }
+    end
+  end
+
+  def as_renderable_array(argument)
+    "[#{argument.collect { |part| as_renderable_argument(part) }.join(", ")}]"
+  end
+end

data/app/helpers/flight_control/navigation_helper.rb

@@ -0,0 +1,61 @@
+module FlightControl::NavigationHelper
+  attr_reader :page_title, :current_section
+
+  def back_to_main_app_path
+    FlightControl.back_to_main_app_path.presence || main_app.try(:root_path)
+  end
+
+  def navigation_sections
+    {queues: ["Queues", application_queues_path(@application)]}.tap do |sections|
+      supported_job_statuses.without(:pending).each do |status|
+        sections[navigation_section_for_status(status)] = ["#{status.to_s.titleize} jobs (#{jobs_count_with_status(status)})", application_jobs_path(@application, status)]
+      end
+
+      sections[:workers] = ["Workers", application_workers_path(@application)] if workers_exposed?
+      sections[:recurring_tasks] = ["Recurring tasks", application_recurring_tasks_path(@application)] if recurring_tasks_supported?
+      sections[:job_launches] = ["Run job", new_application_job_launch_path(@application)]
+    end
+  end
+
+  def navigation_section_for_status(status)
+    if status.nil? || status == :pending
+      :queues
+    else
+      :"#{status}_jobs"
+    end
+  end
+
+  def navigation(title: nil, section: nil)
+    @page_title = title
+    @current_section = section
+  end
+
+  def selected_application?(application)
+    FlightControl::Current.application.name == application.name
+  end
+
+  def selectable_applications
+    FlightControl.applications.reject { |app| selected_application?(app) }
+  end
+
+  def selected_server?(server)
+    FlightControl::Current.server.name == server.name
+  end
+
+  def jobs_count_with_status(status)
+    count = ActiveJob.jobs.with_status(status).count
+    if count.infinite?
+      "..."
+    else
+      number_to_human(count,
+        format: "%n%u",
+        units: {
+          thousand: "K",
+          million: "M",
+          billion: "B",
+          trillion: "T",
+          quadrillion: "Q"
+        })
+    end
+  end
+end

data/app/javascript/flight_control/application.js

@@ -0,0 +1,3 @@
+// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
+import "@hotwired/turbo-rails"
+import "controllers"

data/app/javascript/flight_control/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
+
+export { application }

data/app/javascript/flight_control/controllers/form_controller.js

@@ -0,0 +1,8 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  submit(event) {
+    const form = event.target.form || event.target.closest("form")
+    if (form) form.requestSubmit()
+  }
+}

data/app/javascript/flight_control/controllers/index.js

@@ -0,0 +1,11 @@
+// Import and register all your controllers from the importmap under controllers/*
+
+import { application } from "controllers/application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+
+// Lazy load controllers as they appear in the DOM (remember not to preload controllers in import map!)
+// import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+// lazyLoadControllersFrom("controllers", application)

data/app/javascript/flight_control/controllers/local_time_controller.js

@@ -0,0 +1,27 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Replaces a server-rendered UTC timestamp with "<browser-local time> · <UTC time>".
+// Leaves the UTC-only fallback in place when the browser's timezone is UTC.
+export default class extends Controller {
+  static values = { datetime: String }
+
+  connect() {
+    const date = new Date(this.datetimeValue)
+    if (isNaN(date)) return
+
+    const local = this.format(date)
+    const utc = this.format(date, "UTC")
+    this.element.textContent = local === utc ? utc : `${local} · ${utc}`
+  }
+
+  format(date, timeZone = undefined) {
+    // en-CA yields "2026-07-10, 12:32:15 UTC"
+    return new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit",
+      hourCycle: "h23",
+      timeZoneName: "short"
+    }).format(date).replace(",", "")
+  }
+}

data/app/models/flight_control/application_record.rb

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

data/app/models/flight_control/current.rb

@@ -0,0 +1,3 @@
+class FlightControl::Current < ActiveSupport::CurrentAttributes
+  attribute :application, :server
+end

data/app/models/flight_control/job_launch.rb

@@ -0,0 +1,75 @@
+class FlightControl::JobLaunch
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :job_class_name, :string
+  attribute :arguments_json, :string, default: "[]"
+  attribute :queue_name, :string
+
+  validates :job_class_name, presence: true
+  validate :validate_job_class
+  validate :validate_arguments
+
+  # Job classes defined in the host application. Not memoized on purpose:
+  # class reloading in development would leave stale classes behind.
+  def self.job_classes
+    Rails.application.eager_load! unless Rails.application.config.eager_load
+    ActiveJob::Base.descendants.select { |job_class| job_class.name.present? && implements_perform?(job_class) }.sort_by(&:name)
+  end
+
+  # ActiveJob::Execution defines a perform placeholder that raises NotImplementedError,
+  # so abstract base classes like ApplicationJob still own that placeholder.
+  def self.implements_perform?(job_class)
+    job_class.instance_method(:perform).owner != ActiveJob::Execution
+  end
+
+  def enqueue
+    return nil unless valid?
+
+    job = configured_job_class.perform_later(*positional_arguments, **keyword_arguments)
+    if job&.successfully_enqueued?
+      job
+    else
+      errors.add(:base, "job could not be enqueued#{": #{job.enqueue_error.message}" if job&.enqueue_error}")
+      nil
+    end
+  rescue => error
+    errors.add(:base, "job could not be enqueued: #{error.message}")
+    nil
+  end
+
+  private
+
+  def job_class
+    # Only classes from the discovered list can be launched; never constantize user input.
+    self.class.job_classes.detect { |klass| klass.name == job_class_name }
+  end
+
+  def configured_job_class
+    queue_name.present? ? job_class.set(queue: queue_name) : job_class
+  end
+
+  def parsed_arguments
+    @parsed_arguments ||= JSON.parse(arguments_json.presence || "[]")
+  end
+
+  def positional_arguments
+    parsed_arguments.last.is_a?(Hash) ? parsed_arguments[0...-1] : parsed_arguments
+  end
+
+  def keyword_arguments
+    parsed_arguments.last.is_a?(Hash) ? parsed_arguments.last.transform_keys(&:to_sym) : {}
+  end
+
+  def validate_job_class
+    if job_class_name.present? && job_class.nil?
+      errors.add(:job_class_name, "is not a job class of this application")
+    end
+  end
+
+  def validate_arguments
+    errors.add(:arguments_json, "must be a JSON array") unless parsed_arguments.is_a?(Array)
+  rescue JSON::ParserError
+    errors.add(:arguments_json, "is not valid JSON")
+  end
+end

data/app/models/flight_control/page.rb

@@ -0,0 +1,49 @@
+class FlightControl::Page
+  DEFAULT_PAGE_SIZE = 10
+
+  attr_reader :index, :page_size
+
+  def initialize(relation, page: 1, page_size: DEFAULT_PAGE_SIZE)
+    @relation = relation
+    @page_size = page_size
+    @index = [page, 1].max
+  end
+
+  def records
+    @relation.limit(page_size).offset(offset)
+  end
+
+  def first?
+    index == 1
+  end
+
+  def last?
+    index == pages_count || empty? || records.empty?
+  end
+
+  def empty?
+    total_count == 0
+  end
+
+  def previous_index
+    [index - 1, 1].max
+  end
+
+  def next_index
+    pages_count ? [index + 1, pages_count].min : index + 1
+  end
+
+  def pages_count
+    (total_count.to_f / page_size).ceil unless total_count.infinite?
+  end
+
+  def total_count
+    @total_count ||= @relation.count # Potentially expensive when filtering a lot of records, with the adapter in charge of doing the filtering in memory
+  end
+
+  private
+
+  def offset
+    (index - 1) * page_size
+  end
+end

data/app/models/flight_control/recurring_task.rb

@@ -0,0 +1,26 @@
+class FlightControl::RecurringTask
+  include ActiveModel::Model
+
+  attr_accessor :id, :job_class_name, :command, :arguments, :schedule, :last_enqueued_at, :next_time, :queue_name, :priority
+
+  def initialize(queue_adapter: ActiveJob::Base.queue_adapter, **kwargs)
+    @queue_adapter = queue_adapter
+    super(**kwargs)
+  end
+
+  def jobs
+    ActiveJob::JobsRelation.new(queue_adapter: queue_adapter).where(recurring_task_id: id)
+  end
+
+  def enqueue
+    queue_adapter.enqueue_recurring_task(id)
+  end
+
+  def runnable?
+    queue_adapter.can_enqueue_recurring_task?(id)
+  end
+
+  private
+
+  attr_reader :queue_adapter
+end

data/app/models/flight_control/worker.rb

@@ -0,0 +1,18 @@
+class FlightControl::Worker
+  include ActiveModel::Model
+
+  attr_accessor :id, :name, :hostname, :last_heartbeat_at, :configuration, :raw_data
+
+  def initialize(queue_adapter: ActiveJob::Base.queue_adapter, **kwargs)
+    @queue_adapter = queue_adapter
+    super(**kwargs)
+  end
+
+  def jobs
+    @jobs ||= ActiveJob::JobsRelation.new(queue_adapter: queue_adapter).in_progress.where(worker_id: id)
+  end
+
+  private
+
+  attr_reader :queue_adapter
+end

data/app/views/flight_control/job_launches/new.html.erb

@@ -0,0 +1,53 @@
+<% navigation(title: "Run job", section: :job_launches) %>
+
+<%= form_with model: @job_launch, url: application_job_launches_path(@application) do |form| %>
+  <% if @job_launch.errors.any? %>
+    <article class="message is-danger">
+      <div class="message-body">
+        <ul>
+          <% @job_launch.errors.full_messages.each do |message| %>
+            <li><%= message %></li>
+          <% end %>
+        </ul>
+      </div>
+    </article>
+  <% end %>
+
+  <div class="field">
+    <%= form.label :job_class_name, "Job class", class: "label" %>
+    <div class="control">
+      <div class="select">
+        <%= form.select :job_class_name, @job_classes.map(&:name), include_blank: "Select a job class..." %>
+      </div>
+    </div>
+  </div>
+
+  <div class="field">
+    <%= form.label :arguments_json, "Arguments", class: "label" %>
+    <div class="control">
+      <%= form.text_area :arguments_json, class: "textarea is-family-monospace", rows: 4, placeholder: '[ 123, "abc", { "some_option": true } ]' %>
+    </div>
+    <p class="help">
+      A JSON array with the job's arguments. A trailing JSON object is passed as keyword arguments.
+      Leave <code>[]</code> to run the job without arguments.
+    </p>
+  </div>
+
+  <div class="field">
+    <%= form.label :queue_name, "Queue (optional)", class: "label" %>
+    <div class="control">
+      <%= form.text_field :queue_name, class: "input", list: "queue-names", placeholder: "Job class default", autocomplete: "off" %>
+    </div>
+    <datalist id="queue-names" class="is-hidden">
+      <% @queue_names.each do |queue_name| %>
+        <option value="<%= queue_name %>"></option>
+      <% end %>
+    </datalist>
+  </div>
+
+  <div class="field">
+    <div class="control">
+      <%= form.submit "Enqueue job", class: "button is-primary" %>
+    </div>
+  </div>
+<% end %>

data/app/views/flight_control/jobs/_date_range_filter.html.erb

@@ -0,0 +1,11 @@
+<%# locals: (form:, attribute:, label:) %>
+
+<div class="control">
+  <%= form.label :"#{attribute}_start", "#{label} from", class: "label" %>
+  <%= form.datetime_field :"#{attribute}_start", value: @job_filters[attribute]&.begin, class: "input is-rounded" %>
+</div>
+
+<div class="control">
+  <%= form.label :"#{attribute}_end", "#{label} to", class: "label" %>
+  <%= form.datetime_field :"#{attribute}_end", value: @job_filters[attribute]&.end, class: "input is-rounded" %>
+</div>

data/app/views/flight_control/jobs/_error_information.html.erb

@@ -0,0 +1,24 @@
+<% if job.failed? %>
+  <h2 class="subtitle">Error information</h2>
+
+  <table class="table">
+    <tbody>
+    <tr>
+      <th>Type</th>
+      <td> <%= job.last_execution_error.error_class %> </td>
+    </tr>
+    <tr>
+      <th>Message</th>
+      <td> <%= job.last_execution_error.try(:message) || job.last_execution_error.inspect %> </td>
+    </tr>
+    </tbody>
+  </table>
+
+  <%= turbo_frame_tag "job-backtrace" do %>
+    <% if @server.backtrace_cleaner %>
+      <%= render "flight_control/jobs/failed/backtrace_toggle", application: @application, job: job %>
+    <% end %>
+
+    <pre class="is-family-monospace mb-4 backtrace-content"><%= failed_job_backtrace(job, @server) %></pre>
+  <% end %>
+<% end %>

data/app/views/flight_control/jobs/_filters.html.erb

@@ -0,0 +1,49 @@
+<div class="filter level-left">
+  <%= form_for :filter, url: application_jobs_path(FlightControl::Current.application, jobs_status), method: :get,
+    data: { controller: "form", action: "change->form#submit" } do |form| %>
+
+    <div class="field is-grouped is-grouped-multiline">
+      <div class="control">
+        <%= form.label :job_class_name, class: "label" %>
+        <div class="select is-rounded">
+          <%= form.text_field :job_class_name, value: @job_filters[:job_class_name], class: "input", list: "job-classes", placeholder: "Filter by job class...", autocomplete: "off" %>
+        </div>
+      </div>
+
+      <div class="control">
+        <%= form.label :queue_name, class: "label" %>
+        <div class="select is-rounded">
+          <%= form.text_field :queue_name, value: @job_filters[:queue_name], class: "input", list: "queue-names", placeholder: "Filter by queue name...", autocomplete: "off" %>
+        </div>
+      </div>
+
+      <% if jobs_status == "finished" %>
+        <%= render "flight_control/jobs/date_range_filter", form: form, attribute: :finished_at, label: "Finished" %>
+      <% else %>
+        <%= render "flight_control/jobs/date_range_filter", form: form, attribute: :enqueued_at, label: "Enqueued" %>
+      <% end %>
+
+      <% if jobs_status == "scheduled" %>
+        <%= render "flight_control/jobs/date_range_filter", form: form, attribute: :scheduled_at, label: "Scheduled" %>
+      <% end %>
+
+      <%= hidden_field_tag :server_id, FlightControl::Current.server.id %>
+
+      <datalist id="job-classes" class="is-hidden">
+        <% job_class_names.each do |job_class_name| %>
+          <option value="<%= job_class_name %>"></option>
+        <% end %>
+      </datalist>
+
+      <datalist id="queue-names" class="is-hidden">
+        <% queue_names.each do |queue_name| %>
+          <option value="<%= queue_name %>"></option>
+        <% end %>
+      </datalist>
+
+      <div class="control is-align-self-flex-end">
+        <%= link_to "Clear", application_jobs_path(FlightControl::Current.application, jobs_status), class: "button" %>
+      </div>
+    </div>
+  <% end %>
+</div>

data/app/views/flight_control/jobs/_general_information.html.erb

@@ -0,0 +1,77 @@
+<table class="table">
+  <tbody>
+  <tr>
+    <th>Arguments</th>
+    <td>
+      <div class="is-family-monospace">
+        <%= job_arguments(job) %>
+      </div>
+    </td>
+  </tr>
+  <tr>
+    <th>Job id</th>
+    <td><%= job.job_id %></td>
+  </tr>
+  <tr>
+    <th>Queue</th>
+    <td>
+      <div class="tag">
+        <%= link_to job.queue_name, application_queue_path(@application, job.queue) %>
+      </div>
+    </td>
+  </tr>
+  <tr>
+    <th>Enqueued</th>
+    <td>
+      <%= timestamp_with_relative_time(job.enqueued_at.to_datetime) %>
+    </td>
+  </tr>
+  <% if job.executions > 0 %>
+    <tr>
+      <th>Retries</th>
+      <td><%= job.executions %></td>
+    </tr>
+  <% end %>
+  <% if job.scheduled? %>
+    <tr>
+      <th>Scheduled</th>
+      <td>
+        <%= bidirectional_time_distance_in_words_with_title(job.scheduled_at) %>
+        <% if job_delayed?(job) %>
+          <div class="is-danger tag ml-4">delayed</div>
+        <% end %>
+      </td>
+    </tr>
+  <% end %>
+  <% if job.failed? %>
+    <tr>
+      <th>Failed</th>
+      <td>
+        <%= time_distance_in_words_with_title(job.failed_at) %> ago
+      </td>
+    </tr>
+  <% end %>
+  <% if job.finished_at.present? %>
+    <tr>
+      <th>Finished</th>
+      <td>
+        <%= timestamp_with_relative_time(job.finished_at) %>
+      </td>
+    </tr>
+    <tr>
+      <th>Duration</th>
+      <td>
+        <%= job.duration.round(3) %> seconds
+      </td>
+    </tr>
+  <% end %>
+  <% if job.worker_id.present? %>
+    <tr>
+      <th>Processed by</th>
+      <td>
+        <%= link_to "worker #{job.worker_id}", application_worker_path(@application, job.worker_id) %>
+      </td>
+    </tr>
+  <% end %>
+  </tbody>
+</table>

data/app/views/flight_control/jobs/_job.html.erb

@@ -0,0 +1,13 @@
+<tr class="job">
+  <td>
+    <%= link_to job_title(job), application_job_path(@application, job.job_id) %>
+
+    <% if job.serialized_arguments.present? %>
+      <div class="is-family-monospace"><%= truncate(job_arguments(job), length: 300) %></div>
+    <% end %>
+
+    <div class="has-text-grey is-size-7">Enqueued <%= time_distance_in_words_with_title(job.enqueued_at.to_datetime) %> ago</div>
+  </td>
+
+  <%= render "flight_control/jobs/#{jobs_status}/job", job: job %>
+</tr>

data/app/views/flight_control/jobs/_jobs_page.html.erb

@@ -0,0 +1,13 @@
+<table class="jobs <%= jobs_status %> table queues is-hoverable is-fullwidth">
+  <thead>
+    <tr>
+      <th class="job-header">Job</th>
+      <% attribute_names_for_job_status(jobs_status).each do |attribute| %>
+        <th><%= attribute %></th>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+    <%= render partial: "flight_control/jobs/job", collection: jobs_page.records %>
+  </tbody>
+</table>

data/app/views/flight_control/jobs/_raw_data.html.erb

@@ -0,0 +1,4 @@
+<h2 class="subtitle">Raw data</h2>
+<pre>
+  <%= JSON.pretty_generate(job.filtered_raw_data.without("backtrace")) %>
+</pre>