maintenance_tasks 1.4.0 → 1.8.0

data/app/models/maintenance_tasks/csv_collection_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module MaintenanceTasks
+  # Strategy for building a Task that processes CSV files.
+  #
+  # @api private
+  class CsvCollectionBuilder
+    # 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(task)
+      CSV.new(task.csv_content, headers: true)
+    end
+
+    # The number of rows to be processed. Excludes the header row from the
+    # count and assumes a trailing newline is at the end of the CSV file.
+    # Note that this number is an approximation based on the number of
+    # newlines.
+    #
+    # @return [Integer] the approximate number of rows to process.
+    def count(task)
+      task.csv_content.count("\n") - 1
+    end
+
+    # Return that the Task processes CSV content.
+    def has_csv_content?
+      true
+    end
+
+    # Returns that the Task processes a collection.
+    def no_collection?
+      false
+    end
+  end
+end

data/app/models/maintenance_tasks/no_collection_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Strategy for building a Task that has no collection. These Tasks
+  # consist of a single iteration.
+  #
+  # @api private
+  class NoCollectionBuilder
+    # Specifies that this task does not process a collection.
+    def collection(_task)
+      :no_collection
+    end
+
+    # The number of rows to be processed. Always returns 1.
+    def count(_task)
+      1
+    end
+
+    # Return that the Task does not process CSV content.
+    def has_csv_content?
+      false
+    end
+
+    # Returns that the Task is collection-less.
+    def no_collection?
+      true
+    end
+  end
+end

data/app/models/maintenance_tasks/null_collection_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Base strategy for building a collection-based Task to be performed.
+  #
+  # @api private
+  class NullCollectionBuilder
+    # Placeholder method to raise in case a subclass fails to implement the
+    # expected instance method.
+    #
+    # @raise [NotImplementedError] with a message advising subclasses to
+    #   implement an override for this method.
+    def collection(task)
+      raise NoMethodError, "#{task.class.name} must implement `collection`."
+    end
+
+    # Total count of iterations to be performed.
+    #
+    # Tasks override this method to define the total amount of iterations
+    # expected at the start of the run. Return +nil+ if the amount is
+    # undefined, or counting would be prohibitive for your database.
+    #
+    # @return [Integer, nil]
+    def count(task)
+      :no_count
+    end
+
+    # Return that the Task does not process CSV content.
+    def has_csv_content?
+      false
+    end
+
+    # Returns that the Task processes a collection.
+    def no_collection?
+      false
+    end
+  end
+end

data/app/models/maintenance_tasks/progress.rb

@@ -50,14 +50,19 @@ module MaintenanceTasks
     def text
       count = @run.tick_count
       total = @run.tick_total
+
       if !total?
-        "Processed #{pluralize(count, "item")}."
+        "Processed #{number_to_delimited(count)} "\
+          "#{"item".pluralize(count)}."
       elsif over_total?
-        "Processed #{pluralize(count, "item")} (expected #{total})."
+        "Processed #{number_to_delimited(count)} "\
+          "#{"item".pluralize(count)} "\
+          "(expected #{number_to_delimited(total)})."
       else
         percentage = 100.0 * count / total
 
-        "Processed #{count} out of #{pluralize(total, "item")} "\
+        "Processed #{number_to_delimited(count)} out of "\
+          "#{number_to_delimited(total)} #{"item".pluralize(total)} "\
           "(#{number_to_percentage(percentage, precision: 0)})."
       end
     end

data/app/models/maintenance_tasks/run.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module MaintenanceTasks
   # Model that persists information related to a task being run from the UI.
   #
@@ -25,8 +26,13 @@ module MaintenanceTasks
       :cancelling,
       :interrupted,
     ]
+    STOPPING_STATUSES = [
+      :pausing,
+      :cancelling,
+    ]
     COMPLETED_STATUSES = [:succeeded, :errored, :cancelled]
     COMPLETED_RUNS_LIMIT = 10
+    STUCK_TASK_TIMEOUT = 5.minutes
 
     enum status: STATUSES.to_h { |status| [status, status.to_s] }
 
@@ -60,9 +66,40 @@ module MaintenanceTasks
 
     # 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
@@ -80,33 +117,53 @@ module MaintenanceTasks
         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: error.class.to_s,
-        error_message: error.message,
-        backtrace: Rails.backtrace_cleaner.clean(error.backtrace),
+        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_task_callbacks(:error)
+    rescue ActiveRecord::StaleObjectError
+      reload_status
+      retry
     end
 
-    # Refreshes just the status attribute on the Active Record object, and
-    # ensures ActiveModel::Dirty does not mark the object as changed.
+    # 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
-      updated_status = Run.uncached do
-        Run.where(id: id).pluck(:status).first
+      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
-      clear_attribute_changes([:status])
+      if updated_lock_version
+        self[self.class.locking_column] = updated_lock_version
+      end
+      clear_attribute_changes(columns_to_reload)
       self
     end
 
@@ -115,7 +172,7 @@ module MaintenanceTasks
     #
     # @return [Boolean] whether the Run is stopping.
     def stopping?
-      pausing? || cancelling?
+      STOPPING_STATUSES.include?(status.to_sym)
     end
 
     # Returns whether the Run is stopped, which is defined as having a status of
@@ -166,6 +223,65 @@ module MaintenanceTasks
       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)
+      run_task_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
+      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
@@ -179,10 +295,26 @@ module MaintenanceTasks
     # will be updated.
     def cancel
       if paused? || stuck?
-        update!(status: :cancelled, ended_at: Time.now)
+        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.
+    #
+    # Rescues and retries status transition if an ActiveRecord::StaleObjectError
+    # is encountered.
+    def pausing!
+      super
+    rescue ActiveRecord::StaleObjectError
+      reload_status
+      retry
     end
 
     # Returns whether a Run is stuck, which is defined as having a status of
@@ -190,7 +322,7 @@ module MaintenanceTasks
     #
     # @return [Boolean] whether the Run is stuck.
     def stuck?
-      cancelling? && updated_at <= 5.minutes.ago
+      cancelling? && updated_at <= STUCK_TASK_TIMEOUT.ago
     end
 
     # Performs validation on the presence of a :csv_file attachment.
@@ -199,9 +331,9 @@ module MaintenanceTasks
     # 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?
+      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) < CsvCollection) && csv_file.present?
+      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
@@ -275,6 +407,12 @@ module MaintenanceTasks
 
     private
 
+    def run_task_callbacks(callback)
+      task.run_callbacks(callback)
+    rescue
+      nil
+    end
+
     def arguments_match_task_attributes
       invalid_argument_keys = arguments.keys - task.attribute_names
       if invalid_argument_keys.any?
@@ -284,5 +422,11 @@ module MaintenanceTasks
         errors.add(:base, error_message)
       end
     end
+
+    def truncate(attribute_name, value)
+      limit = MaintenanceTasks::Run.column_for_attribute(attribute_name).limit
+      return value unless limit
+      value&.first(limit)
+    end
   end
 end

data/app/models/maintenance_tasks/runner.rb

@@ -47,21 +47,25 @@ module MaintenanceTasks
     #   creating the Run.
     # @raise [ActiveRecord::ValueTooLong] if the creation of the Run fails due
     #   to a value being too long for the column type.
-    def run(name:, csv_file: nil, arguments: {})
-      run = Run.active.find_by(task_name: name) ||
-        Run.new(task_name: name, arguments: arguments)
-      run.csv_file.attach(csv_file) if csv_file
-
-      run.enqueued!
-      enqueue(run)
+    def run(name:, csv_file: nil, arguments: {}, run_model: Run)
+      run = run_model.active.find_by(task_name: name) ||
+        run_model.new(task_name: name, arguments: arguments)
+      if csv_file
+        run.csv_file.attach(csv_file)
+        run.csv_file.filename = filename(name)
+      end
+      job = instantiate_job(run)
+      run.job_id = job.job_id
       yield run if block_given?
+      run.enqueued!
+      enqueue(run, job)
       Task.named(name)
     end
 
     private
 
-    def enqueue(run)
-      unless MaintenanceTasks.job.constantize.perform_later(run)
+    def enqueue(run, job)
+      unless job.enqueue
         raise "The job to perform #{run.task_name} could not be enqueued. "\
           "Enqueuing has been prevented by a callback."
       end
@@ -69,5 +73,14 @@ module MaintenanceTasks
       run.persist_error(error)
       raise EnqueuingError, run
     end
+
+    def filename(task_name)
+      formatted_task_name = task_name.underscore.gsub("/", "_")
+      "#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}_#{formatted_task_name}.csv"
+    end
+
+    def instantiate_job(run)
+      MaintenanceTasks.job.constantize.new(run)
+    end
   end
 end

data/app/models/maintenance_tasks/runs_page.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module MaintenanceTasks
   # This class is responsible for handling cursor-based pagination for Run
   # records.

data/app/models/maintenance_tasks/task.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Base class that is inherited by the host application's task classes.
+  class Task
+    extend ActiveSupport::DescendantsTracker
+    include ActiveSupport::Callbacks
+    include ActiveModel::Attributes
+    include ActiveModel::AttributeAssignment
+    include ActiveModel::Validations
+
+    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: []
+
+    # @api private
+    class_attribute :collection_builder_strategy,
+      default: NullCollectionBuilder.new
+
+    define_callbacks :start, :complete, :error, :cancel, :pause, :interrupt
+
+    class << self
+      # Finds a Task with the given name.
+      #
+      # @param name [String] the name of the Task to be found.
+      #
+      # @return [Task] the Task with the given name.
+      #
+      # @raise [NotFoundError] if a Task with the given name does not exist.
+      def named(name)
+        task = name.safe_constantize
+        raise NotFoundError.new("Task #{name} not found.", name) unless task
+        unless task.is_a?(Class) && task < Task
+          raise NotFoundError.new("#{name} is not a Task.", name)
+        end
+        task
+      end
+
+      # Returns a list of concrete classes that inherit from the Task
+      # superclass.
+      #
+      # @return [Array<Class>] the list of classes.
+      def available_tasks
+        load_constants
+        descendants
+      end
+
+      # Make this Task a task that handles CSV.
+      #
+      # 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
+        unless defined?(ActiveStorage)
+          raise NotImplementedError, "Active Storage needs to be installed\n"\
+            "To resolve this issue run: bin/rails active_storage:install"
+        end
+
+        self.collection_builder_strategy =
+          MaintenanceTasks::CsvCollectionBuilder.new
+      end
+
+      # Make this a Task that calls #process once, instead of iterating over
+      # a collection.
+      def no_collection
+        self.collection_builder_strategy =
+          MaintenanceTasks::NoCollectionBuilder.new
+      end
+
+      delegate :has_csv_content?, :no_collection?,
+        to: :collection_builder_strategy
+
+      # Processes one item.
+      #
+      # Especially useful for tests.
+      #
+      # @param args [Object, nil] the item to process
+      def process(*args)
+        new.process(*args)
+      end
+
+      # Returns the collection for this Task.
+      #
+      # Especially useful for tests.
+      #
+      # @return the collection.
+      def collection
+        new.collection
+      end
+
+      # Returns the count of items for this Task.
+      #
+      # Especially useful for tests.
+      #
+      # @return the count of items.
+      def count
+        new.count
+      end
+
+      # Add a condition under which this Task will be throttled.
+      #
+      # @param backoff [ActiveSupport::Duration, #call] a custom backoff
+      #   can be specified. This is the time to wait before retrying the Task,
+      #   defaulting to 30 seconds. If provided as a Duration, the backoff is
+      #   wrapped in a proc. Alternatively,an object responding to call can be
+      #   used. It must return an ActiveSupport::Duration.
+      # @yieldreturn [Boolean] where the throttle condition is being met,
+      #   indicating that the Task should throttle.
+      def throttle_on(backoff: 30.seconds, &condition)
+        backoff_as_proc = backoff
+        backoff_as_proc = -> { backoff } unless backoff.respond_to?(:call)
+
+        self.throttle_conditions += [
+          { throttle_on: condition, backoff: backoff_as_proc },
+        ]
+      end
+
+      # Initialize a callback to run after the task starts.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_start(*filter_list, &block)
+        set_callback(:start, :after, *filter_list, &block)
+      end
+
+      # Initialize a callback to run after the task completes.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_complete(*filter_list, &block)
+        set_callback(:complete, :after, *filter_list, &block)
+      end
+
+      # Initialize a callback to run after the task pauses.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_pause(*filter_list, &block)
+        set_callback(:pause, :after, *filter_list, &block)
+      end
+
+      # Initialize a callback to run after the task is interrupted.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_interrupt(*filter_list, &block)
+        set_callback(:interrupt, :after, *filter_list, &block)
+      end
+
+      # Initialize a callback to run after the task is cancelled.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_cancel(*filter_list, &block)
+        set_callback(:cancel, :after, *filter_list, &block)
+      end
+
+      # Initialize a callback to run after the task produces an error.
+      #
+      # @param filter_list apply filters to the callback
+      #   (see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-set_callback)
+      def after_error(*filter_list, &block)
+        set_callback(:error, :after, *filter_list, &block)
+      end
+
+      private
+
+      def load_constants
+        namespace = MaintenanceTasks.tasks_module.safe_constantize
+        return unless namespace
+        namespace.constants.map { |constant| namespace.const_get(constant) }
+      end
+    end
+
+    # The contents of a CSV file to be processed by a Task.
+    #
+    # @return [String] the content of the CSV file to process.
+    def csv_content
+      raise NoMethodError unless has_csv_content?
+
+      @csv_content
+    end
+
+    # Set the contents of a CSV file to be processed by a Task.
+    #
+    # @param csv_content [String] the content of the CSV file to process.
+    def csv_content=(csv_content)
+      raise NoMethodError unless has_csv_content?
+
+      @csv_content = csv_content
+    end
+
+    # Returns whether the Task handles CSV.
+    #
+    # @return [Boolean] whether the Task handles CSV.
+    def has_csv_content?
+      self.class.has_csv_content?
+    end
+
+    # Returns whether the Task is collection-less.
+    #
+    # @return [Boolean] whether the Task is collection-less.
+    def no_collection?
+      self.class.no_collection?
+    end
+
+    # The collection to be processed, delegated to the strategy.
+    #
+    # @return the collection.
+    def collection
+      self.class.collection_builder_strategy.collection(self)
+    end
+
+    # Placeholder method to raise in case a subclass fails to implement the
+    # expected instance method.
+    #
+    # @param _item [Object] the current item from the enumerator being iterated.
+    #
+    # @raise [NotImplementedError] with a message advising subclasses to
+    #   implement an override for this method.
+    def process(_item)
+      raise NoMethodError, "#{self.class.name} must implement `process`."
+    end
+
+    # Total count of iterations to be performed, delegated to the strategy.
+    #
+    # @return [Integer, nil]
+    def count
+      self.class.collection_builder_strategy.count(self)
+    end
+  end
+end