maintenance_tasks 2.12.0 → 2.14.0

data/app/models/maintenance_tasks/run.rb

@@ -5,499 +5,6 @@ module MaintenanceTasks
   #
   # @api private
   class Run < ApplicationRecord
-    # Various statuses a run can be in.
-    STATUSES = [
-      :enqueued,    # The task has been enqueued by the user.
-      :running,     # The task is being performed by a job worker.
-      :succeeded,   # The task finished without error.
-      :cancelling,  # The task has been told to cancel but is finishing work.
-      :cancelled,   # The user explicitly halted the task's execution.
-      :interrupted, # The task was interrupted by the job infrastructure.
-      :pausing,     # The task has been told to pause but is finishing work.
-      :paused,      # The task was paused in the middle of the run by the user.
-      :errored,     # The task code produced an unhandled exception.
-    ]
-
-    ACTIVE_STATUSES = [
-      :enqueued,
-      :running,
-      :paused,
-      :pausing,
-      :cancelling,
-      :interrupted,
-    ]
-    STOPPING_STATUSES = [
-      :pausing,
-      :cancelling,
-      :cancelled,
-    ]
-    COMPLETED_STATUSES = [:succeeded, :errored, :cancelled]
-
-    enum :status, STATUSES.to_h { |status| [status, status.to_s] }
-
-    after_save :instrument_status_change
-
-    validate :task_name_belongs_to_a_valid_task, on: :create
-    validate :csv_attachment_presence, on: :create
-    validate :csv_content_type, on: :create
-    validate :validate_task_arguments, on: :create
-
-    attr_readonly :task_name
-
-    if Rails.gem_version >= Gem::Version.new("7.1.alpha")
-      serialize :backtrace, coder: YAML
-      serialize :arguments, coder: JSON
-      serialize :metadata, coder: JSON
-    else
-      serialize :backtrace
-      serialize :arguments, JSON
-      serialize :metadata, JSON
-    end
-
-    scope :active, -> { where(status: ACTIVE_STATUSES) }
-    scope :completed, -> { where(status: COMPLETED_STATUSES) }
-
-    # Ensure ActiveStorage is in use before preloading the attachments
-    scope :with_attached_csv, -> do
-      return unless defined?(ActiveStorage)
-
-      with_attached_csv_file if ActiveStorage::Attachment.table_exists?
-    end
-
-    validates_with RunStatusValidator, on: :update
-
-    if MaintenanceTasks.active_storage_service.present?
-      has_one_attached :csv_file,
-        service: MaintenanceTasks.active_storage_service
-    elsif respond_to?(:has_one_attached)
-      has_one_attached :csv_file
-    end
-
-    # Sets the run status to enqueued, making sure the transition is validated
-    # in case it's already enqueued.
-    #
-    # Rescues and retries status transition if an ActiveRecord::StaleObjectError
-    # is encountered.
-    def enqueued!
-      status_will_change!
-      super
-    rescue ActiveRecord::StaleObjectError
-      reload_status
-      retry
-    end
-
-    CALLBACKS_TRANSITION = {
-      cancelled: :cancel,
-      interrupted: :interrupt,
-      paused: :pause,
-      succeeded: :complete,
-    }.transform_keys(&:to_s)
-    private_constant :CALLBACKS_TRANSITION
-
-    # Saves the run, persisting the transition of its status, and all other
-    # changes to the object.
-    def persist_transition
-      save!
-      callback = CALLBACKS_TRANSITION[status]
-      run_task_callbacks(callback) if callback
-    rescue ActiveRecord::StaleObjectError
-      success = succeeded?
-      reload_status
-      if success
-        self.status = :succeeded
-      else
-        job_shutdown
-      end
-      retry
-    end
-
-    # Increments +tick_count+ by +number_of_ticks+ and +time_running+ by
-    # +duration+, both directly in the DB.
-    # The attribute values are not set in the current instance, you need
-    # to reload the record.
-    #
-    # @param number_of_ticks [Integer] number of ticks to add to tick_count.
-    # @param duration [Float] the time in seconds that elapsed since the last
-    #   increment of ticks.
-    def persist_progress(number_of_ticks, duration)
-      self.class.update_counters(
-        id,
-        tick_count: number_of_ticks,
-        time_running: duration,
-        touch: true,
-      )
-      if locking_enabled?
-        locking_column = self.class.locking_column
-        self[locking_column] += 1
-        clear_attribute_change(locking_column)
-      end
-    end
-
-    # Marks the run as errored and persists the error data.
-    #
-    # @param error [StandardError] the Error being persisted.
-    def persist_error(error)
-      self.started_at ||= Time.now
-      update!(
-        status: :errored,
-        error_class: truncate(:error_class, error.class.name),
-        error_message: truncate(:error_message, error.message),
-        backtrace: MaintenanceTasks.backtrace_cleaner.clean(error.backtrace),
-        ended_at: Time.now,
-      )
-      run_error_callback
-    rescue ActiveRecord::StaleObjectError
-      reload_status
-      retry
-    end
-
-    # Refreshes the status and lock version attributes on the Active Record
-    # object, and ensures ActiveModel::Dirty doesn't mark the object as changed.
-    #
-    # This allows us to get the Run's most up-to-date status without needing
-    # to reload the entire record.
-    #
-    # @return [MaintenanceTasks::Run] the Run record with its updated status.
-    def reload_status
-      columns_to_reload = if locking_enabled?
-        [:status, self.class.locking_column]
-      else
-        [:status]
-      end
-      updated_status, updated_lock_version = self.class.uncached do
-        self.class.where(id: id).pluck(*columns_to_reload).first
-      end
-
-      self.status = updated_status
-      if updated_lock_version
-        self[self.class.locking_column] = updated_lock_version
-      end
-      clear_attribute_changes(columns_to_reload)
-      self
-    end
-
-    # Returns whether the Run is stopping, which is defined as having a status
-    # of pausing or cancelling. The status of cancelled is also considered
-    # stopping since a Run can be cancelled while its job still exists in the
-    # queue, and we want to handle it the same way as a cancelling run.
-    #
-    # @return [Boolean] whether the Run is stopping.
-    def stopping?
-      STOPPING_STATUSES.include?(status.to_sym)
-    end
-
-    # Returns whether the Run is stopped, which is defined as having a status of
-    # paused, succeeded, cancelled, or errored.
-    #
-    # @return [Boolean] whether the Run is stopped.
-    def stopped?
-      completed? || paused?
-    end
-
-    # Returns whether the Run has been started, which is indicated by the
-    # started_at timestamp being present.
-    #
-    # @return [Boolean] whether the Run was started.
-    def started?
-      started_at.present?
-    end
-
-    # Returns whether the Run is completed, which is defined as
-    # having a status of succeeded, cancelled, or errored.
-    #
-    # @return [Boolean] whether the Run is completed.
-    def completed?
-      COMPLETED_STATUSES.include?(status.to_sym)
-    end
-
-    # Returns whether the Run is active, which is defined as
-    # having a status of enqueued, running, pausing, cancelling,
-    # paused or interrupted.
-    #
-    # @return [Boolean] whether the Run is active.
-    def active?
-      ACTIVE_STATUSES.include?(status.to_sym)
-    end
-
-    # Returns the duration left for the Run to finish based on the number of
-    # ticks left and the average time needed to process a tick. Returns nil if
-    # the Run is completed, or if tick_count or tick_total is zero.
-    #
-    # @return [ActiveSupport::Duration] the estimated duration left for the Run
-    #   to finish.
-    def time_to_completion
-      return if completed? || tick_count == 0 || tick_total.to_i == 0
-
-      processed_per_second = (tick_count.to_f / time_running)
-      ticks_left = (tick_total - tick_count)
-      seconds_to_finished = ticks_left / processed_per_second
-      seconds_to_finished.seconds
-    end
-
-    # Marks a Run as running.
-    #
-    # If the run is stopping already, it will not transition to running.
-    # Rescues and retries status transition if an ActiveRecord::StaleObjectError
-    # is encountered.
-    def running
-      if locking_enabled?
-        begin
-          running! unless stopping?
-        rescue ActiveRecord::StaleObjectError
-          reload_status
-          retry
-        end
-      else
-        # Preserve swap-and-replace solution for data races until users
-        # run migration to upgrade to optimistic locking solution
-        return if stopping?
-
-        updated = self.class.where(id: id).where.not(status: STOPPING_STATUSES)
-          .update_all(status: :running, updated_at: Time.now) > 0
-        if updated
-          self.status = :running
-          clear_attribute_changes([:status])
-        else
-          reload_status
-        end
-      end
-    end
-
-    # Starts a Run, setting its started_at timestamp and tick_total.
-    #
-    # @param count [Integer] the total iterations to be performed, as
-    #   specified by the Task.
-    def start(count)
-      update!(started_at: Time.now, tick_total: count)
-      task.run_callbacks(:start)
-    rescue ActiveRecord::StaleObjectError
-      reload_status
-      retry
-    end
-
-    # Handles transitioning the status on a Run when the job shuts down.
-    def job_shutdown
-      if cancelling?
-        self.status = :cancelled
-        self.ended_at = Time.now
-      elsif pausing?
-        self.status = :paused
-      elsif cancelled?
-      else
-        self.status = :interrupted
-      end
-    end
-
-    # Handles the completion of a Run, setting a status of succeeded and the
-    # ended_at timestamp.
-    def complete
-      self.status = :succeeded
-      self.ended_at = Time.now
-    end
-
-    # Cancels a Run.
-    #
-    # If the Run is paused, it will transition directly to cancelled, since the
-    # Task is not being performed. In this case, the ended_at timestamp
-    # will be updated.
-    #
-    # If the Run is not paused, the Run will transition to cancelling.
-    #
-    # If the Run is already cancelling, and has last been updated more than 5
-    # minutes ago, it will transition to cancelled, and the ended_at timestamp
-    # will be updated.
-    def cancel
-      if paused? || stuck?
-        self.status = :cancelled
-        self.ended_at = Time.now
-        persist_transition
-      else
-        cancelling!
-      end
-    rescue ActiveRecord::StaleObjectError
-      reload_status
-      retry
-    end
-
-    # Marks a Run as pausing.
-    #
-    # If the Run has been stuck on pausing for more than 5 minutes, it forces
-    # the transition to paused. The ended_at timestamp will be updated.
-    #
-    # Rescues and retries status transition if an ActiveRecord::StaleObjectError
-    # is encountered.
-    def pause
-      if stuck?
-        self.status = :paused
-        persist_transition
-      else
-        pausing!
-      end
-    rescue ActiveRecord::StaleObjectError
-      reload_status
-      retry
-    end
-
-    # Returns whether a Run is stuck, which is defined as having a status of
-    # cancelling or pausing, and not having been updated in the last 5 minutes.
-    #
-    # @return [Boolean] whether the Run is stuck.
-    def stuck?
-      (cancelling? || pausing?) && updated_at <= MaintenanceTasks.stuck_task_duration.ago
-    end
-
-    # Performs validation on the task_name attribute.
-    # A Run must be associated with a valid Task to be valid.
-    # In order to confirm that, the Task is looked up by name.
-    def task_name_belongs_to_a_valid_task
-      Task.named(task_name)
-    rescue Task::NotFoundError
-      errors.add(:task_name, "must be the name of an existing Task.")
-    end
-
-    # Performs validation on the presence of a :csv_file attachment.
-    # A Run for a Task that uses CsvCollection must have an attached :csv_file
-    # to be valid. Conversely, a Run for a Task that doesn't use CsvCollection
-    # should not have an attachment to be valid. The appropriate error is added
-    # if the Run does not meet the above criteria.
-    def csv_attachment_presence
-      if Task.named(task_name).has_csv_content? && !csv_file.attached?
-        errors.add(:csv_file, "must be attached to CSV Task.")
-      elsif !Task.named(task_name).has_csv_content? && csv_file.present?
-        errors.add(:csv_file, "should not be attached to non-CSV Task.")
-      end
-    rescue Task::NotFoundError
-      nil
-    end
-
-    # Performs validation on the content type of the :csv_file attachment.
-    # A Run for a Task that uses CsvCollection must have a present :csv_file
-    # and a content type of "text/csv" to be valid. The appropriate error is
-    # added if the Run does not meet the above criteria.
-    def csv_content_type
-      if csv_file.present? && csv_file.content_type != "text/csv"
-        errors.add(:csv_file, "must be a CSV")
-      end
-    rescue Task::NotFoundError
-      nil
-    end
-
-    # Performs validation on the arguments to use for the Task. If the Task is
-    # invalid, the errors are added to the Run.
-    def validate_task_arguments
-      arguments_match_task_attributes if arguments.present?
-      if task.invalid?
-        error_messages = task.errors
-          .map { |error| "#{error.attribute.inspect} #{error.message}" }
-        errors.add(
-          :arguments,
-          "are invalid: #{error_messages.join("; ")}",
-        )
-      end
-    rescue Task::NotFoundError
-      nil
-    end
-
-    # Fetches the attached ActiveStorage CSV file for the run. Checks first
-    # whether the ActiveStorage::Attachment table exists so that we are
-    # compatible with apps that are not using ActiveStorage.
-    #
-    # @return [ActiveStorage::Attached::One] the attached CSV file
-    def csv_file
-      return unless defined?(ActiveStorage)
-      return unless ActiveStorage::Attachment.table_exists?
-
-      super
-    end
-
-    # Returns a Task instance for this Run. Assigns any attributes to the Task
-    # based on the Run's parameters. Note that the Task instance is not supplied
-    # with :csv_content yet if it's a CSV Task. This is done in the job, since
-    # downloading the CSV file can take some time.
-    #
-    # @return [Task] a Task instance.
-    def task
-      @task ||= begin
-        task = Task.named(task_name).new
-        if task.attribute_names.any? && arguments.present?
-          task.assign_attributes(arguments)
-        end
-
-        task.metadata = metadata
-        task
-      rescue ActiveModel::UnknownAttributeError
-        task
-      end
-    end
-
-    # Returns all the run arguments with sensitive information masked.
-    #
-    # @return [Hash] The masked arguments.
-    def masked_arguments
-      return unless arguments.present?
-
-      argument_filter.filter(arguments)
-    end
-
-    private
-
-    def instrument_status_change
-      return unless status_previously_changed? || id_previously_changed?
-      return if running? || pausing? || cancelling? || interrupted?
-
-      attr = {
-        run_id: id,
-        job_id: job_id,
-        task_name: task_name,
-        arguments: arguments,
-        metadata: metadata,
-        time_running: time_running,
-        started_at: started_at,
-        ended_at: ended_at,
-      }
-
-      attr[:error] = {
-        message: error_message,
-        class: error_class,
-        backtrace: backtrace,
-      } if errored?
-
-      ActiveSupport::Notifications.instrument("#{status}.maintenance_tasks", attr)
-    end
-
-    def run_task_callbacks(callback)
-      task.run_callbacks(callback)
-    rescue Task::NotFoundError
-      nil
-    end
-
-    def run_error_callback
-      task.run_callbacks(:error)
-    rescue
-      nil
-    end
-
-    def arguments_match_task_attributes
-      invalid_argument_keys = arguments.keys - task.attribute_names
-      if invalid_argument_keys.any?
-        error_message = <<~MSG.squish
-          Unknown parameters: #{invalid_argument_keys.map(&:to_sym).join(", ")}
-        MSG
-        errors.add(:base, error_message)
-      end
-    end
-
-    def truncate(attribute_name, value)
-      limit = self.class.column_for_attribute(attribute_name).limit
-      return value unless limit
-
-      value&.first(limit)
-    end
-
-    def argument_filter
-      @argument_filter ||= ActiveSupport::ParameterFilter.new(
-        Rails.application.config.filter_parameters + task.masked_arguments,
-      )
-    end
+    include RunConcern
   end
 end

data/app/models/maintenance_tasks/task.rb

@@ -33,6 +33,12 @@ module MaintenanceTasks
     # @api private
     class_attribute :masked_arguments, default: []
 
+    # The frequency at which to reload the run status during iteration.
+    # Defaults to the global MaintenanceTasks.status_reload_frequency setting.
+    #
+    # @api private
+    class_attribute :status_reload_frequency, default: MaintenanceTasks.status_reload_frequency
+
     define_callbacks :start, :complete, :error, :cancel, :pause, :interrupt
 
     attr_accessor :metadata
@@ -167,6 +173,15 @@ module MaintenanceTasks
         self.masked_arguments += attributes
       end
 
+      # Configure how frequently the run status should be reloaded during iteration.
+      # Use this to reduce database queries when processing large collections.
+      #
+      # @param frequency [ActiveSupport::Duration, Numeric] reload status every N seconds (default: 1 second).
+      #   Setting this to 10.seconds means status will be reloaded every 10 seconds.
+      def reload_status_every(frequency)
+        self.status_reload_frequency = frequency
+      end
+
       # Initialize a callback to run after the task starts.
       #
       # @param filter_list apply filters to the callback
@@ -220,14 +235,10 @@ module MaintenanceTasks
       #
       # @param exceptions list of exceptions to rescue and report
       # @param report_options [Hash] optionally, supply additional options for `Rails.error.report`.
-      #   By default: <code>{ source: "maintenance_tasks" }</code> or (Rails <v7.1) <code>{ handled: true }</code>.
+      #   By default: <code>{ handled: true, source: "maintenance-tasks" }</code>.
       def report_on(*exceptions, **report_options)
         rescue_from(*exceptions) do |exception|
-          if Rails.gem_version >= Gem::Version.new("7.1")
-            Rails.error.report(exception, source: "maintenance_tasks", **report_options)
-          else
-            Rails.error.report(exception, handled: true, **report_options)
-          end
+          Rails.error.report(exception, source: "maintenance-tasks", **report_options)
         end
       end
 

data/app/views/layouts/maintenance_tasks/_navbar.html.erb

@@ -1,4 +1,4 @@
-<nav class="navbar is-light" role="navigation" aria-label="main navigation">
+<nav class="navbar" role="navigation" aria-label="main navigation">
   <div class="navbar-brand">
     <%= link_to 'Maintenance Tasks', root_path, class: 'navbar-item is-size-4 has-text-weight-semibold has-text-danger' %>
   </div>

data/app/views/layouts/maintenance_tasks/application.html.erb

@@ -3,6 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
+    <%= capybara_lockstep if defined?(Capybara::Lockstep) %>
 
     <title>
       <% if content_for?(:page_title) %>
@@ -15,20 +16,44 @@
     <%= csrf_meta_tags %>
 
     <%=
-      stylesheet_link_tag(URI.join(controller.class::BULMA_CDN, "npm/bulma@1.0.3/css/versions/bulma-no-dark-mode.min.css"),
+      stylesheet_link_tag(URI.join(controller.class::BULMA_CDN, "npm/bulma@1.0.4/css/bulma.min.css"),
         media: :all,
-        integrity: "sha256-HCNMQcqH/4MnGR0EYg2S3/BXYMM1z9lrFV10ANRd79o",
+        integrity: "sha256-Z/om3xyp6V2PKtx8BPobFfo9JCV0cOvBDMaLmquRS+4=",
         crossorigin: "anonymous") unless request.xhr?
     %>
 
     <style>
-      .ruby-comment { color: #6a737d;}
-      .ruby-const { color: #e36209; }
-      .ruby-embexpr-beg, .ruby-embexpr-end, .ruby-period { color: #24292e; }
-      .ruby-ident, .ruby-symbeg { color: #6f42c1; }
-      .ruby-ivar, .ruby-cvar, .ruby-gvar, .ruby-int, .ruby-imaginary, .ruby-float, .ruby-rational { color: #005cc5; }
-      .ruby-kw { color: #d73a49; }
-      .ruby-label, .ruby-tstring-beg, .ruby-tstring-content, .ruby-tstring-end { color: #032f62; }
+      :root {
+        --ruby-comment: #6a737d;
+        --ruby-const: #e36209;
+        --ruby-embexpr: #24292e;
+        --ruby-ident: #6f42c1;
+        --ruby-number: #005cc5;
+        --ruby-keyword: #d73a49;
+        --ruby-string: #032f62;
+        --required-color: #ff6685;
+      }
+
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --ruby-comment: #8b949e;
+          --ruby-const: #ffa657;
+          --ruby-embexpr: #c9d1d9;
+          --ruby-ident: #d2a8ff;
+          --ruby-number: #79c0ff;
+          --ruby-keyword: #ff7b72;
+          --ruby-string: #a5d6ff;
+          --required-color: #ff6685;
+        }
+      }
+
+      .ruby-comment { color: var(--ruby-comment); }
+      .ruby-const { color: var(--ruby-const); }
+      .ruby-embexpr-beg, .ruby-embexpr-end, .ruby-period { color: var(--ruby-embexpr); }
+      .ruby-ident, .ruby-symbeg { color: var(--ruby-ident); }
+      .ruby-ivar, .ruby-cvar, .ruby-gvar, .ruby-int, .ruby-imaginary, .ruby-float, .ruby-rational { color: var(--ruby-number); }
+      .ruby-kw { color: var(--ruby-keyword); }
+      .ruby-label, .ruby-tstring-beg, .ruby-tstring-content, .ruby-tstring-end { color: var(--ruby-string); }
 
       .select, select { width: 100%; }
       summary { cursor: pointer; }
@@ -51,12 +76,19 @@
       }
 
       .box {
-        box-shadow: 0 4px 6px -1px #0000001a,
-                    0 2px 4px -2px #0000001a;
+        box-shadow: 0 0 6px 0 #0000001a,
+                    0 2px 4px -1px #0000001a;
       }
+
+      @media (prefers-color-scheme: dark) {
+        .box {
+          background-color: var(--bulma-background);
+        }
+      }
+
       .label.is-required:after {
         content: " (required)";
-        color: #ff6685;
+        color: var(--required-color);
         font-size: 12px;
       }
     </style>
@@ -99,6 +131,6 @@
 
         <%= yield %>
       </div>
-    </div>
+    </section>
   </body>
 </html>

data/db/migrate/20201211151756_create_maintenance_tasks_runs.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class CreateMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
+class CreateMaintenanceTasksRuns < ActiveRecord::Migration[7.0]
   def change
     create_table(:maintenance_tasks_runs, id: primary_key_type) do |t|
       t.string(:task_name, null: false)

data/db/migrate/20210219212931_change_cursor_to_string.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class ChangeCursorToString < ActiveRecord::Migration[6.0]
+class ChangeCursorToString < ActiveRecord::Migration[7.0]
   # This migration will clear all existing data in the cursor column with MySQL.
   # Ensure no Tasks are paused when this migration is deployed, or they will be resumed from the start.
   # Running tasks are able to gracefully handle this change, even if interrupted.

data/db/migrate/20210225152418_remove_index_on_task_name.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class RemoveIndexOnTaskName < ActiveRecord::Migration[6.0]
+class RemoveIndexOnTaskName < ActiveRecord::Migration[7.0]
   def up
     change_table(:maintenance_tasks_runs) do |t|
       t.remove_index(:task_name)

data/db/migrate/20210517131953_add_arguments_to_maintenance_tasks_runs.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class AddArgumentsToMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
+class AddArgumentsToMaintenanceTasksRuns < ActiveRecord::Migration[7.0]
   def change
     add_column(:maintenance_tasks_runs, :arguments, :text)
   end

data/db/migrate/20211210152329_add_lock_version_to_maintenance_tasks_runs.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class AddLockVersionToMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
+class AddLockVersionToMaintenanceTasksRuns < ActiveRecord::Migration[7.0]
   def change
     add_column(
       :maintenance_tasks_runs,

data/db/migrate/20220706101937_change_runs_tick_columns_to_bigints.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class ChangeRunsTickColumnsToBigints < ActiveRecord::Migration[6.0]
+class ChangeRunsTickColumnsToBigints < ActiveRecord::Migration[7.0]
   def up
     change_table(:maintenance_tasks_runs, bulk: true) do |t|
       t.change(:tick_count, :bigint)