maintenance_tasks 1.1.1 → 1.3.0

data/app/jobs/maintenance_tasks/task_job.rb

@@ -3,134 +3,6 @@
 module MaintenanceTasks
   # Base class that is inherited by the host application's task classes.
   class TaskJob < ActiveJob::Base
-    include JobIteration::Iteration
-
-    before_perform(:before_perform)
-
-    on_start(:on_start)
-    on_complete(:on_complete)
-    on_shutdown(:on_shutdown)
-
-    after_perform(:after_perform)
-
-    rescue_from StandardError, with: :on_error
-
-    class << self
-      # Overrides ActiveJob::Exceptions.retry_on to declare it unsupported.
-      # The use of rescue_from prevents retry_on from being usable.
-      def retry_on(*, **)
-        raise NotImplementedError, 'retry_on is not supported'
-      end
-    end
-
-    private
-
-    def build_enumerator(_run, cursor:)
-      cursor ||= @run.cursor
-      collection = @task.collection
-
-      case collection
-      when ActiveRecord::Relation
-        enumerator_builder.active_record_on_records(collection, cursor: cursor)
-      when Array
-        enumerator_builder.build_array_enumerator(collection, cursor: cursor)
-      when CSV
-        JobIteration::CsvEnumerator.new(collection).rows(cursor: cursor)
-      else
-        raise ArgumentError, "#{@task.class.name}#collection must be either "\
-          'an Active Record Relation, Array, or CSV.'
-      end
-    end
-
-    # Performs task iteration logic for the current input returned by the
-    # enumerator.
-    #
-    # @param input [Object] the current element from the enumerator.
-    # @param _run [Run] the current Run, passed as an argument by Job Iteration.
-    def each_iteration(input, _run)
-      throw(:abort, :skip_complete_callbacks) if @run.stopping?
-      task_iteration(input)
-      @ticker.tick
-      @run.reload_status
-    end
-
-    def task_iteration(input)
-      @task.process(input)
-    rescue => error
-      @errored_element = input
-      raise error
-    end
-
-    def before_perform
-      @run = arguments.first
-      @task = Task.named(@run.task_name).new
-      if @task.respond_to?(:csv_content=)
-        @task.csv_content = @run.csv_file.download
-      end
-      @run.job_id = job_id
-
-      @run.running! unless @run.stopping?
-
-      @ticker = Ticker.new(MaintenanceTasks.ticker_delay) do |ticks, duration|
-        @run.persist_progress(ticks, duration)
-      end
-    end
-
-    def on_start
-      @run.update!(started_at: Time.now, tick_total: @task.count)
-    end
-
-    def on_complete
-      @run.status = :succeeded
-      @run.ended_at = Time.now
-    end
-
-    def on_shutdown
-      if @run.cancelling?
-        @run.status = :cancelled
-        @run.ended_at = Time.now
-      else
-        @run.status = @run.pausing? ? :paused : :interrupted
-        @run.cursor = cursor_position
-      end
-
-      @ticker.persist
-    end
-
-    # We are reopening a private part of Job Iteration's API here, so we should
-    # ensure the method is still defined upstream. This way, in the case where
-    # the method changes upstream, we catch it at load time instead of at
-    # runtime while calling `super`.
-    unless private_method_defined?(:reenqueue_iteration_job)
-      error_message = <<~HEREDOC
-        JobIteration::Iteration#reenqueue_iteration_job is expected to be
-        defined. Upgrading the maintenance_tasks gem should solve this problem.
-      HEREDOC
-      raise error_message
-    end
-    def reenqueue_iteration_job(should_ignore: true)
-      super() unless should_ignore
-      @reenqueue_iteration_job = true
-    end
-
-    def after_perform
-      @run.save!
-      if defined?(@reenqueue_iteration_job) && @reenqueue_iteration_job
-        reenqueue_iteration_job(should_ignore: false)
-      end
-    end
-
-    def on_error(error)
-      @ticker.persist if defined?(@ticker)
-      @run.persist_error(error)
-
-      task_context = {
-        task_name: @run.task_name,
-        started_at: @run.started_at,
-        ended_at: @run.ended_at,
-      }
-      errored_element = @errored_element if defined?(@errored_element)
-      MaintenanceTasks.error_handler.call(error, task_context, errored_element)
-    end
+    include TaskJobConcern
   end
 end

data/app/models/maintenance_tasks/csv_collection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'csv'
+require "csv"
 
 module MaintenanceTasks
   # Module that is included into Task classes by Task.csv_collection for

data/app/models/maintenance_tasks/progress.rb

@@ -4,6 +4,7 @@ module MaintenanceTasks
   # This class generates progress information about a Run.
   class Progress
     include ActiveSupport::NumberHelper
+    include ActionView::Helpers::TextHelper
 
     # Sets the Progress initial state with a Run.
     #
@@ -41,22 +42,23 @@ module MaintenanceTasks
       estimatable? ? @run.tick_total : @run.tick_count
     end
 
-    # The title for the progress information. This is a text that describes the
-    # progress of the Run so far. It includes the percentage that is done out of
-    # the maximum, if an estimate is possible.
+    # The text containing progress information. This describes the progress of
+    # the Run so far. It includes the percentage done out of the maximum, if an
+    # estimate is possible.
     #
-    # @return [String] the title for the Run progress.
-    def title
+    # @return [String] the text for the Run progress.
+    def text
+      count = @run.tick_count
+      total = @run.tick_total
       if !total?
-        "Processed #{@run.tick_count} #{'item'.pluralize(@run.tick_count)}."
+        "Processed #{pluralize(count, "item")}."
       elsif over_total?
-        "Processed #{@run.tick_count} #{'item'.pluralize(@run.tick_count)} " \
-          "(expected #{@run.tick_total})."
+        "Processed #{pluralize(count, "item")} (expected #{total})."
       else
-        percentage = 100.0 * @run.tick_count / @run.tick_total
+        percentage = 100.0 * count / total
 
-        "Processed #{@run.tick_count} out of #{@run.tick_total} "\
-          "(#{number_to_percentage(percentage, precision: 0)})"
+        "Processed #{count} out of #{pluralize(total, "item")} "\
+          "(#{number_to_percentage(percentage, precision: 0)})."
       end
     end
 

data/app/models/maintenance_tasks/run.rb

@@ -41,9 +41,20 @@ module MaintenanceTasks
 
     scope :active, -> { where(status: ACTIVE_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
 
-    has_one_attached :csv_file
+    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.
@@ -187,12 +198,23 @@ module MaintenanceTasks
     # if the Run does not meet the above criteria.
     def csv_attachment_presence
       if Task.named(task_name) < CsvCollection && !csv_file.attached?
-        errors.add(:csv_file, 'must be attached to CSV Task.')
-      elsif !(Task.named(task_name) < CsvCollection) && csv_file.attached?
-        errors.add(:csv_file, 'should not be attached to non-CSV Task.')
+        errors.add(:csv_file, "must be attached to CSV Task.")
+      elsif !(Task.named(task_name) < CsvCollection) && csv_file.present?
+        errors.add(:csv_file, "should not be attached to non-CSV Task.")
       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
   end
 end

data/app/models/maintenance_tasks/runner.rb

@@ -8,7 +8,7 @@ module MaintenanceTasks
     # @deprecated Use {Runner} directly instead.
     def new
       ActiveSupport::Deprecation.warn(
-        'Use Runner.run instead of Runner.new.run'
+        "Use Runner.run instead of Runner.new.run"
       )
       self
     end
@@ -57,7 +57,7 @@ module MaintenanceTasks
     def enqueue(run)
       unless MaintenanceTasks.job.constantize.perform_later(run)
         raise "The job to perform #{run.task_name} could not be enqueued. "\
-          'Enqueuing has been prevented by a callback.'
+          "Enqueuing has been prevented by a callback."
       end
     rescue => error
       run.persist_error(error)

data/app/models/maintenance_tasks/runs_page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+module MaintenanceTasks
+  # This class is responsible for handling cursor-based pagination for Run
+  # records.
+  #
+  # @api private
+  class RunsPage
+    # The number of Runs to show on a single Task page.
+    RUNS_PER_PAGE = 20
+
+    # Initializes a Runs Page with a Runs relation and a cursor. This page is
+    # used by the views to render a set of Runs.
+    # @param runs [ActiveRecord::Relation<MaintenanceTasks::Run>] the relation
+    #   of Run records to be paginated.
+    # @param cursor [String, nil] the id that serves as the cursor when
+    #   querying the Runs dataset to produce a page of Runs. If nil, the first
+    #   Runs in the relation are used.
+    def initialize(runs, cursor)
+      @runs = runs
+      @cursor = cursor
+    end
+
+    # Returns the records for a Page, taking into account the cursor if one is
+    # present. Limits the number of records to 20.
+    #
+    # @return [ActiveRecord::Relation<MaintenanceTasks::Run>] a limited amount
+    #  of Run records.
+    def records
+      @records ||= begin
+        runs_after_cursor = if @cursor.present?
+          @runs.where("id < ?", @cursor)
+        else
+          @runs
+        end
+        runs_after_cursor.limit(RUNS_PER_PAGE)
+      end
+    end
+
+    # Returns the cursor to use for the next Page of Runs. It is the id of the
+    # last record on the current Page.
+    #
+    # @return [Integer] the id of the last record for the Page.
+    def next_cursor
+      records.last.id
+    end
+
+    # Returns whether this Page is the last one.
+    #
+    # @return [Boolean] whether this Page contains the last Run record in the
+    #   Runs dataset that is being paginated.
+    def last?
+      @runs.unscope(:includes).pluck(:id).last == next_cursor
+    end
+  end
+end

data/app/models/maintenance_tasks/task_data.rb

@@ -41,7 +41,7 @@ module MaintenanceTasks
         task_names = Task.available_tasks.map(&:name)
         available_task_runs = Run.where(task_name: task_names)
         last_runs = Run.where(
-          id: available_task_runs.select('MAX(id) as id').group(:task_name)
+          id: available_task_runs.select("MAX(id) as id").group(:task_name)
         )
 
         task_names.map do |task_name|
@@ -111,7 +111,7 @@ module MaintenanceTasks
     #
     # @return [String] the Task status.
     def status
-      last_run&.status || 'new'
+      last_run&.status || "new"
     end
 
     # Retrieves the Task's category, which is one of active, new, or completed.
@@ -135,7 +135,7 @@ module MaintenanceTasks
     private
 
     def runs
-      Run.where(task_name: name).with_attached_csv_file.order(created_at: :desc)
+      Run.where(task_name: name).with_attached_csv.order(created_at: :desc)
     end
   end
 end

data/app/tasks/maintenance_tasks/task.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-
 module MaintenanceTasks
   # Base class that is inherited by the host application's task classes.
   class Task
@@ -7,6 +6,13 @@ module MaintenanceTasks
 
     class NotFoundError < NameError; end
 
+    # The throttle conditions for a given Task. This is provided as an array of
+    # hashes, with each hash specifying two keys: throttle_condition and
+    # backoff. Note that Tasks inherit conditions from their superclasses.
+    #
+    # @api private
+    class_attribute :throttle_conditions, default: []
+
     class << self
       # Finds a Task with the given name.
       #
@@ -38,6 +44,10 @@ module MaintenanceTasks
       # An input to upload a CSV will be added in the form to start a Run. The
       # collection and count method are implemented.
       def csv_collection
+        if !defined?(ActiveStorage) || !ActiveStorage::Attachment.table_exists?
+          raise NotImplementedError, "Active Storage needs to be installed\n"\
+            "To resolve this issue run: bin/rails active_storage:install"
+        end
         include(CsvCollection)
       end
 
@@ -68,6 +78,19 @@ module MaintenanceTasks
         new.count
       end
 
+      # Add a condition under which this Task will be throttled.
+      #
+      # @param backoff [ActiveSupport::Duration] optionally, a custom backoff
+      #   can be specified. This is the time to wait before retrying the Task.
+      #   If no value is specified, it defaults to 30 seconds.
+      # @yieldreturn [Boolean] where the throttle condition is being met,
+      #   indicating that the Task should throttle.
+      def throttle_on(backoff: 30.seconds, &condition)
+        self.throttle_conditions += [
+          { throttle_on: condition, backoff: backoff },
+        ]
+      end
+
       private
 
       def load_constants

data/app/validators/maintenance_tasks/run_status_validator.rb

@@ -13,7 +13,7 @@ module MaintenanceTasks
       #   before starting.
       # enqueued -> errored occurs when the task job fails to be enqueued, or
       #   if the Task is deleted before is starts running.
-      'enqueued' => ['running', 'pausing', 'cancelling', 'errored'],
+      "enqueued" => ["running", "pausing", "cancelling", "errored"],
       # pausing -> paused occurs when the task actually halts performing and
       #   occupies a status of paused.
       # pausing -> cancelling occurs when the user cancels a task immediately
@@ -24,14 +24,14 @@ module MaintenanceTasks
       #   nothing in its collection to process.
       # pausing -> errored occurs when the job raises an exception after the
       #   user has paused it.
-      'pausing' => ['paused', 'cancelling', 'succeeded', 'errored'],
+      "pausing" => ["paused", "cancelling", "succeeded", "errored"],
       # cancelling -> cancelled occurs when the task actually halts performing
       #   and occupies a status of cancelled.
       # cancelling -> succeeded occurs when the task completes immediately after
       #   being cancelled. See description for pausing -> succeeded.
       # cancelling -> errored occurs when the job raises an exception after the
       #   user has cancelled it.
-      'cancelling' => ['cancelled', 'succeeded', 'errored'],
+      "cancelling" => ["cancelled", "succeeded", "errored"],
       # running -> succeeded occurs when the task completes successfully.
       # running -> pausing occurs when a user pauses the task as
       #   it's performing.
@@ -40,17 +40,17 @@ module MaintenanceTasks
       # running -> interrupted occurs when the job infra shuts down the task as
       #   it's performing.
       # running -> errored occurs when the job raises an exception when running.
-      'running' => [
-        'succeeded',
-        'pausing',
-        'cancelling',
-        'interrupted',
-        'errored',
+      "running" => [
+        "succeeded",
+        "pausing",
+        "cancelling",
+        "interrupted",
+        "errored",
       ],
       # paused -> enqueued occurs when the task is resumed after being paused.
       # paused -> cancelling when the user cancels the task after it is paused.
       # paused -> cancelled when the user cancels the task after it is paused.
-      'paused' => ['enqueued', 'cancelling', 'cancelled'],
+      "paused" => ["enqueued", "cancelling", "cancelled"],
       # interrupted -> running occurs when the task is resumed after being
       #   interrupted by the job infrastructure.
       # interrupted -> pausing occurs when the task is paused by the user while
@@ -59,7 +59,7 @@ module MaintenanceTasks
       #   while it is interrupted.
       # interrupted -> errored occurs when the task is deleted while it is
       #   interrupted.
-      'interrupted' => ['running', 'pausing', 'cancelling', 'errored'],
+      "interrupted" => ["running", "pausing", "cancelling", "errored"],
     }
 
     # Validate whether a transition from one Run status