maintenance_tasks 1.0.0 → 1.2.1

data/app/helpers/maintenance_tasks/{task_helper.rb → tasks_helper.rb}

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require 'ripper'
+require "ripper"
 
 module MaintenanceTasks
   # Helpers for formatting data in the maintenance_tasks views.
   #
   # @api private
-  module TaskHelper
+  module TasksHelper
     STATUS_COLOURS = {
-      'new' => ['is-primary'],
-      'enqueued' => ['is-primary is-light'],
-      'running' => ['is-info'],
-      'interrupted' => ['is-info', 'is-light'],
-      'pausing' => ['is-warning', 'is-light'],
-      'paused' => ['is-warning'],
-      'succeeded' => ['is-success'],
-      'cancelling' => ['is-light'],
-      'cancelled' => ['is-dark'],
-      'errored' => ['is-danger'],
+      "new" => ["is-primary"],
+      "enqueued" => ["is-primary is-light"],
+      "running" => ["is-info"],
+      "interrupted" => ["is-info", "is-light"],
+      "pausing" => ["is-warning", "is-light"],
+      "paused" => ["is-warning"],
+      "succeeded" => ["is-success"],
+      "cancelling" => ["is-light"],
+      "cancelled" => ["is-dark"],
+      "errored" => ["is-danger"],
     }
 
     # Formats a run backtrace.
@@ -44,12 +44,13 @@ module MaintenanceTasks
 
       progress = Progress.new(run)
 
-      tag.progress(
+      progress_bar = tag.progress(
         value: progress.value,
         max: progress.max,
-        title: progress.title,
-        class: ['progress'] + STATUS_COLOURS.fetch(run.status)
+        class: ["progress"] + STATUS_COLOURS.fetch(run.status)
       )
+      progress_text = tag.p(tag.i(progress.text))
+      tag.div(progress_bar + progress_text, class: "block")
     end
 
     # Renders a span with a Run's status, with the corresponding tag class
@@ -59,7 +60,7 @@ module MaintenanceTasks
     # @return [String] the span element containing the status, with the
     #   appropriate tag class attached.
     def status_tag(status)
-      tag.span(status.capitalize, class: ['tag'] + STATUS_COLOURS.fetch(status))
+      tag.span(status.capitalize, class: ["tag"] + STATUS_COLOURS.fetch(status))
     end
 
     # Returns the distance between now and the Run's expected completion time,
@@ -100,11 +101,18 @@ module MaintenanceTasks
         when :on_nl, :on_sp, :on_ignored_nl
           content
         else
-          tag.span(content, class: type.to_s.sub('on_', 'ruby-').dasherize)
+          tag.span(content, class: type.to_s.sub("on_", "ruby-").dasherize)
         end
       end
       safe_join(tokens)
     end
+
+    # Returns a download link for a Run's CSV attachment
+    def csv_file_download_path(run)
+      Rails.application.routes.url_helpers.rails_blob_path(
+        run.csv_file,
+        only_path: true
+      )
+    end
   end
-  private_constant :TaskHelper
 end

data/app/jobs/maintenance_tasks/task_job.rb

@@ -19,7 +19,7 @@ module MaintenanceTasks
       # 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'
+        raise NotImplementedError, "retry_on is not supported"
       end
     end
 
@@ -34,9 +34,11 @@ module MaintenanceTasks
         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 or an Array.'
+          "an Active Record Relation, Array, or CSV."
       end
     end
 
@@ -47,14 +49,24 @@ module MaintenanceTasks
     # @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.process(input)
+      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?
@@ -85,14 +97,45 @@ module MaintenanceTasks
       @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
-      @run.persist_error(error)
-      MaintenanceTasks.error_handler.call(error)
+      @ticker.persist if defined?(@ticker)
+
+      if defined?(@run)
+        @run.persist_error(error)
+
+        task_context = {
+          task_name: @run.task_name,
+          started_at: @run.started_at,
+          ended_at: @run.ended_at,
+        }
+      else
+        task_context = {}
+      end
+      errored_element = @errored_element if defined?(@errored_element)
+      MaintenanceTasks.error_handler.call(error, task_context, errored_element)
     end
   end
 end

data/app/models/maintenance_tasks/application_record.rb

@@ -2,9 +2,9 @@
 module MaintenanceTasks
   # Base class for all records used by this engine.
   #
-  # @api private
+  # Can be extended to setup different database where all tables related to
+  # maintenance tasks will live.
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
   end
-  private_constant :ApplicationRecord
 end

data/app/models/maintenance_tasks/csv_collection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module MaintenanceTasks
+  # Module that is included into Task classes by Task.csv_collection for
+  # processing CSV files.
+  #
+  # @api private
+  module CsvCollection
+    # The contents of a CSV file to be processed by a Task.
+    #
+    # @return [String] the content of the CSV file to process.
+    attr_accessor :csv_content
+
+    # Defines the collection to be iterated over, based on the provided CSV.
+    #
+    # @return [CSV] the CSV object constructed from the specified CSV content,
+    #   with headers.
+    def collection
+      CSV.new(csv_content, headers: true)
+    end
+
+    # The number of rows to be processed. Excludes the header row from the count
+    # and assumed a trailing new line in the CSV file. Note that this number is
+    # an approximation based on the number of new lines.
+    #
+    # @return [Integer] the approximate number of rows to process.
+    def count
+      csv_content.count("\n") - 1
+    end
+  end
+end

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)}."
-      elsif @run.tick_count > @run.tick_total
-        "Processed #{@run.tick_count} #{'item'.pluralize(@run.tick_count)} " \
-          "(expected #{@run.tick_total})."
+        "Processed #{pluralize(count, "item")}."
+      elsif over_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
 
@@ -67,8 +69,11 @@ module MaintenanceTasks
     end
 
     def estimatable?
-      total? && @run.tick_total > @run.tick_count
+      total? && !over_total?
+    end
+
+    def over_total?
+      @run.tick_count > @run.tick_total
     end
   end
-  private_constant :Progress
 end

data/app/models/maintenance_tasks/run.rb

@@ -33,14 +33,28 @@ module MaintenanceTasks
     validates :task_name, on: :create, inclusion: { in: ->(_) {
       Task.available_tasks.map(&:to_s)
     } }
+    validate :csv_attachment_presence, on: :create
+
     attr_readonly :task_name
 
     serialize :backtrace
 
     scope :active, -> { where(status: ACTIVE_STATUSES) }
 
+    # Ensure ActiveStorage is in use before preloading the attachments
+    scope :with_attached_csv, -> do
+      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
+    else
+      has_one_attached :csv_file
+    end
+
     # Sets the run status to enqueued, making sure the transition is validated
     # in case it's already enqueued.
     def enqueued!
@@ -175,6 +189,30 @@ module MaintenanceTasks
     def stuck?
       cancelling? && updated_at <= 5.minutes.ago
     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) < CsvCollection && !csv_file.attached?
+        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 ActiveStorage::Attachment.table_exists?
+      super
+    end
   end
-  private_constant :Run
 end

data/app/models/maintenance_tasks/runner.rb

@@ -2,7 +2,17 @@
 
 module MaintenanceTasks
   # This class is responsible for running a given Task.
-  class Runner
+  module Runner
+    extend self
+
+    # @deprecated Use {Runner} directly instead.
+    def new
+      ActiveSupport::Deprecation.warn(
+        "Use Runner.run instead of Runner.new.run"
+      )
+      self
+    end
+
     # Exception raised when a Task Job couldn't be enqueued.
     class EnqueuingError < StandardError
       # Initializes a Enqueuing Error.
@@ -20,17 +30,22 @@ module MaintenanceTasks
     # Runs a Task.
     #
     # This method creates a Run record for the given Task name and enqueues the
-    # Run.
+    # Run. If a CSV file is provided, it is attached to the Run record.
     #
     # @param name [String] the name of the Task to be run.
+    # @param csv_file [attachable, nil] a CSV file that provides the collection
+    #   for the Task to iterate over when running, in the form of an attachable
+    #   (see https://edgeapi.rubyonrails.org/classes/ActiveStorage/Attached/One.html#method-i-attach).
+    #   Value is nil if the Task does not use CSV iteration.
     #
     # @return [Task] the Task that was run.
     #
     # @raise [EnqueuingError] if an error occurs while enqueuing the Run.
     # @raise [ActiveRecord::RecordInvalid] if validation errors occur while
     #   creating the Run.
-    def run(name:)
+    def run(name:, csv_file: nil)
       run = Run.active.find_by(task_name: name) || Run.new(task_name: name)
+      run.csv_file.attach(csv_file) if csv_file
 
       run.enqueued!
       enqueue(run)
@@ -40,9 +55,9 @@ module MaintenanceTasks
     private
 
     def enqueue(run)
-      unless MaintenanceTasks.job.perform_later(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