maintenance_tasks 1.3.0 → 1.7.0

data/app/models/maintenance_tasks/task.rb

@@ -0,0 +1,225 @@
+# 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: []
+
+    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
+
+      # Returns whether the Task handles CSV.
+      #
+      # @return [Boolean] whether the Task handles CSV.
+      def has_csv_content?
+        collection_builder_strategy.has_csv_content?
+      end
+
+      # Processes one item.
+      #
+      # Especially useful for tests.
+      #
+      # @param item the item to process.
+      def process(item)
+        new.process(item)
+      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
+
+    # 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

data/app/models/maintenance_tasks/task_data.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module MaintenanceTasks
   # Class that represents the data related to a Task. Such information can be
   # sourced from a Task or from existing Run records for a Task that was since
@@ -40,7 +41,7 @@ module MaintenanceTasks
       def available_tasks
         task_names = Task.available_tasks.map(&:name)
         available_task_runs = Run.where(task_name: task_names)
-        last_runs = Run.where(
+        last_runs = Run.with_attached_csv.where(
           id: available_task_runs.select("MAX(id) as id").group(:task_name)
         )
 
@@ -73,7 +74,11 @@ module MaintenanceTasks
     def code
       return if deleted?
       task = Task.named(name)
-      file = task.instance_method(:process).source_location.first
+      file = if Object.respond_to?(:const_source_location)
+        Object.const_source_location(task.name).first
+      else
+        task.instance_method(:process).source_location.first
+      end
       File.read(file)
     end
 
@@ -129,7 +134,23 @@ module MaintenanceTasks
 
     # @return [Boolean] whether the Task inherits from CsvTask.
     def csv_task?
-      !deleted? && Task.named(name) < CsvCollection
+      !deleted? && Task.named(name).has_csv_content?
+    end
+
+    # @return [Array<String>] the names of parameters the Task accepts.
+    def parameter_names
+      if deleted?
+        []
+      else
+        Task.named(name).attribute_names
+      end
+    end
+
+    # @return [MaintenanceTasks::Task, nil] an instance of the Task class.
+    # @return [nil] if the Task file was deleted.
+    def new
+      return if deleted?
+      MaintenanceTasks::Task.named(name).new
     end
 
     private

data/app/validators/maintenance_tasks/run_status_validator.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module MaintenanceTasks
   # Custom validator class responsible for ensuring that transitions between
   # Run statuses are valid.
@@ -48,9 +49,8 @@ module MaintenanceTasks
         "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", "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

data/app/views/maintenance_tasks/runs/_arguments.html.erb

@@ -0,0 +1,22 @@
+<% if run.arguments.present? %>
+  <div class="table-container">
+    <h6 class="title is-6">Arguments:</h6>
+    <table class="table">
+      <tbody>
+        <% run.arguments.each do |key, value| %>
+          <tr>
+            <td class="is-family-monospace"><%= key %></td>
+            <td>
+              <% next if value.nil? || value.empty? %>
+              <% if value.include?("\n") %>
+                <pre><%= value %><pre>
+              <% else %>
+                <code><%= value %><code>
+              <% end %>
+            </td>
+          </tr>
+          <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>

data/app/views/maintenance_tasks/runs/_csv.html.erb

@@ -0,0 +1,5 @@
+<% if run.csv_file.present? %>
+  <div class="block">
+    <%= link_to("Download CSV", csv_file_download_path(run)) %>
+  </div>
+<% end %>

data/app/views/maintenance_tasks/runs/_run.html.erb

@@ -1,3 +1,20 @@
 <div class="box">
-  <%= render 'maintenance_tasks/runs/info', run: run, with_status: true %>
+  <h5 class="title is-5">
+    <%= time_tag run.created_at, title: run.created_at %>
+    <%= status_tag run.status %>
+  </h5>
+
+  <%= progress run %>
+
+  <div class="content">
+    <%= render "maintenance_tasks/runs/info/#{run.status}", run: run %>
+  </div>
+
+  <div class="content" id="custom-content">
+    <%= render "maintenance_tasks/runs/info/custom", run: run %>
+  </div>
+
+  <%= render "maintenance_tasks/runs/csv", run: run %>
+  <%= tag.hr if run.csv_file.present? && run.arguments.present? %>
+  <%= render "maintenance_tasks/runs/arguments", run: run %>
 </div>

data/app/views/maintenance_tasks/runs/info/_errored.html.erb

@@ -3,8 +3,6 @@
   <%= time_ago run.ended_at %>.
 </p>
 
-</p>
-
 <div class="card">
   <header class="card-header">
     <p class="card-header-title">

data/app/views/maintenance_tasks/runs/info/_paused.html.erb

@@ -1,7 +1,7 @@
 <p>
   Ran for <%= time_running_in_words run  %> until paused,
-  <% if run.estimated_completion_time %>
-    <%= estimated_time_to_completion(run) %> remaining.
+  <% if (time_to_completion = run.time_to_completion) %>
+    <%= distance_of_time_in_words(time_to_completion) %> remaining.
   <% else %>
     processed <%= pluralize run.tick_count, 'item' %> so far.
   <% end %>

data/app/views/maintenance_tasks/runs/info/_running.html.erb

@@ -1,5 +1,3 @@
-<p>
-  <% if run.estimated_completion_time %>
-    <%= estimated_time_to_completion(run).capitalize %> remaining.
-  <% end %>
-</p>
+<% if (time_to_completion = run.time_to_completion) %>
+  <p>Running for <%= time_running_in_words(run)  %>. <%= distance_of_time_in_words(time_to_completion).capitalize %> remaining.</p>
+<% end %>

data/app/views/maintenance_tasks/tasks/_task.html.erb

@@ -4,5 +4,23 @@
     <%= status_tag(task.status) %>
   </h3>
 
-  <%= render 'maintenance_tasks/runs/info', run: task.last_run, with_status: false if task.last_run %>
+  <% if (run = task.last_run) %>
+    <h5 class="title is-5">
+      <%= time_tag run.created_at, title: run.created_at %>
+    </h5>
+
+    <%= progress run %>
+
+    <div class="content">
+      <%= render "maintenance_tasks/runs/info/#{run.status}", run: run %>
+    </div>
+
+    <div class="content" id="custom-content">
+      <%= render "maintenance_tasks/runs/info/custom", run: run %>
+    </div>
+
+    <%= render "maintenance_tasks/runs/csv", run: run %>
+    <%= tag.hr if run.csv_file.present? && run.arguments.present? %>
+    <%= render "maintenance_tasks/runs/arguments", run: run %>
+  <% end %>
 </div>

data/app/views/maintenance_tasks/tasks/index.html.erb

@@ -2,8 +2,8 @@
   <div class="content is-large">
     <h3 class="title is-3"> The MaintenanceTasks gem has been successfully installed! </h3>
     <p>
-      Any new Tasks will show up here. To start writing your first Task, 
-      run <code>rails generate maintenance_tasks:task my_task</code>.
+      Any new Tasks will show up here. To start writing your first Task,
+      run <code>bin/rails generate maintenance_tasks:task my_task</code>.
     </p>
   </div>
 <% else %>

data/app/views/maintenance_tasks/tasks/show.html.erb

@@ -4,10 +4,29 @@
   <%= @task %> <%= status_tag(@task.status) %>
 </h1>
 
-<%= render 'maintenance_tasks/runs/info', run: @task.last_run, with_status: false if @task.last_run %>
+<% last_run = @task.last_run %>
+<% if last_run %>
+  <h5 class="title is-5">
+    <%= time_tag last_run.created_at, title: last_run.created_at %>
+  </h5>
+
+  <%= progress last_run %>
+
+  <div class="content">
+    <%= render "maintenance_tasks/runs/info/#{last_run.status}", run: last_run %>
+  </div>
+
+  <div class="content" id="custom-content">
+    <%= render "maintenance_tasks/runs/info/custom", run: last_run %>
+  </div>
+
+  <%= render "maintenance_tasks/runs/csv", run: last_run %>
+  <%= tag.hr if last_run.csv_file.present? %>
+  <%= render "maintenance_tasks/runs/arguments", run: last_run %>
+  <%= tag.hr if last_run.arguments.present? %>
+<% end %>
 
 <div class="buttons">
-  <% last_run = @task.last_run %>
   <% if last_run.nil? || last_run.completed? %>
     <%= form_with url: run_task_path(@task), method: :put do |form| %>
       <% if @task.csv_task? %>
@@ -16,6 +35,22 @@
           <%= form.file_field :csv_file %>
         </div>
       <% end %>
+      <% parameter_names = @task.parameter_names %>
+      <% if parameter_names.any? %>
+        <div class="block">
+          <%= form.fields_for :task_arguments, @task.new do |ff| %>
+            <% parameter_names.each do |parameter_name| %>
+              <div class="field">
+                <%= ff.label parameter_name, parameter_name, class: "label is-family-monospace" %>
+                <div class="control">
+                  <%= parameter_field(ff, parameter_name) %>
+                </div>
+              </div>
+            <% end %>
+          <% end %>
+        </div>
+      <% end %>
+      <%= render "maintenance_tasks/tasks/custom", form: form %>
       <div class="block">
         <%= form.submit 'Run', class: "button is-success", disabled: @task.deleted? %>
       </div>

data/config/routes.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 MaintenanceTasks::Engine.routes.draw do
   resources :tasks, only: [:index, :show], format: false do
     member do

data/db/migrate/20201211151756_create_maintenance_tasks_runs.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 class CreateMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
   def change
     create_table(:maintenance_tasks_runs) do |t|

data/db/migrate/20210225152418_remove_index_on_task_name.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 class RemoveIndexOnTaskName < ActiveRecord::Migration[6.0]
   def up
     change_table(:maintenance_tasks_runs) do |t|

data/db/migrate/20210517131953_add_arguments_to_maintenance_tasks_runs.rb

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

data/db/migrate/20211210152329_add_lock_version_to_maintenance_tasks_runs.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddLockVersionToMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
+  def change
+    add_column(:maintenance_tasks_runs, :lock_version, :integer,
+      default: 0, null: false)
+  end
+end

data/lib/generators/maintenance_tasks/install_generator.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module MaintenanceTasks
   # Generator used to set up the engine in the host application. It handles
   # mounting the engine and installing migrations.

data/lib/generators/maintenance_tasks/templates/task.rb.tt

@@ -9,7 +9,9 @@ module <%= tasks_module %>
     end
 
     def process(element)
-      # The work to be done in a single iteration of the task
+      # The work to be done in a single iteration of the task.
+      # This should be idempotent, as the same element may be processed more
+      # than once if the task is interrupted and resumed.
     end
 
     def count

data/lib/maintenance_tasks/cli.rb

@@ -25,18 +25,25 @@ module MaintenanceTasks
     LONGDESC
 
     # Specify the CSV file to process for CSV Tasks
-    option :csv, desc: "Supply a CSV file to be processed by a CSV Task, "\
-      '--csv "path/to/csv/file.csv"'
+    desc = "Supply a CSV file to be processed by a CSV Task, "\
+      "--csv path/to/csv/file.csv"
+    option :csv, desc: desc
+    # Specify arguments to supply to a Task supporting parameters
+    desc = "Supply arguments for a Task that accepts parameters as a set of "\
+      "<key>:<value> pairs."
+    option :arguments, type: :hash, desc: desc
 
     # Command to run a Task.
     #
     # It instantiates a Runner and sends a run message with the given Task name.
     # If a CSV file is supplied using the --csv option, an attachable with the
-    # File IO object is sent along with the Task name to run.
+    # File IO object is sent along with the Task name to run. If arguments are
+    # supplied using the --arguments option, these are also passed to run.
     #
     # @param name [String] the name of the Task to be run.
     def perform(name)
-      task = Runner.run(name: name, csv_file: csv_file)
+      arguments = options[:arguments] || {}
+      task = Runner.run(name: name, csv_file: csv_file, arguments: arguments)
       say_status(:success, "#{task.name} was enqueued.", :green)
     rescue => error
       say_status(:error, error.message, :red)

data/lib/maintenance_tasks/engine.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "active_record/railtie"
 
 module MaintenanceTasks
@@ -7,10 +8,23 @@ module MaintenanceTasks
   class Engine < ::Rails::Engine
     isolate_namespace MaintenanceTasks
 
-    initializer "eager_load_for_classic_autoloader" do
+    initializer "maintenance_tasks.warn_classic_autoloader" do
+      unless Rails.autoloaders.zeitwerk_enabled?
+        ActiveSupport::Deprecation.warn(<<~MSG.squish)
+          Autoloading in classic mode is deprecated and support will be removed in the next
+          release of Maintenance Tasks. Please use Zeitwerk to autoload your application.
+        MSG
+      end
+    end
+
+    initializer "maintenance_tasks.eager_load_for_classic_autoloader" do
       eager_load! unless Rails.autoloaders.zeitwerk_enabled?
     end
 
+    initializer "maintenance_tasks.configs" do
+      MaintenanceTasks.backtrace_cleaner = Rails.backtrace_cleaner
+    end
+
     config.to_prepare do
       _ = TaskJobConcern # load this for JobIteration compatibility check
       unless Rails.autoloaders.zeitwerk_enabled?

data/lib/maintenance_tasks.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "action_controller"
 require "action_view"
 require "active_job"
@@ -7,6 +8,8 @@ require "active_record"
 require "job-iteration"
 require "maintenance_tasks/engine"
 
+require "patches/active_record_batch_enumerator"
+
 # The engine's namespace module. It provides isolation between the host
 # application's code and the engine-specific code. Top-level engine constants
 # and variables are defined under this module.
@@ -50,6 +53,16 @@ module MaintenanceTasks
   #     app's config/storage.yml.
   mattr_accessor :active_storage_service
 
+  # @!attribute backtrace_cleaner
+  #   @scope class
+  #
+  #   The Active Support backtrace cleaner that will be used to clean the
+  #   backtrace of a Task that errors.
+  #
+  #   @return [ActiveSupport::BacktraceCleaner, nil] the backtrace cleaner to
+  #     use when cleaning a Run's backtrace.
+  mattr_accessor :backtrace_cleaner
+
   # @private
   def self.error_handler
     return @error_handler if defined?(@error_handler)
@@ -61,7 +74,7 @@ module MaintenanceTasks
     unless error_handler.arity == 3
       ActiveSupport::Deprecation.warn(
         "MaintenanceTasks.error_handler should be a lambda that takes three "\
-         "arguments: error, task_context, and errored_element."
+          "arguments: error, task_context, and errored_element."
       )
       @error_handler = ->(error, _task_context, _errored_element) do
         error_handler.call(error)

data/lib/patches/active_record_batch_enumerator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# TODO: Remove this patch once all supported Rails versions include the changes
+# upstream - https://github.com/rails/rails/pull/42312/commits/a031a43d969c87542c4ee8d0d338d55fcbb53376
+module ActiveRecordBatchEnumerator
+  # The primary key value from which the BatchEnumerator starts,
+  #   inclusive of the value.
+  attr_reader :start
+
+  # The primary key value at which the BatchEnumerator ends,
+  #   inclusive of the value.
+  attr_reader :finish
+
+  # The relation from which the BatchEnumerator yields batches.
+  attr_reader :relation
+
+  # The size of the batches yielded by the BatchEnumerator.
+  def batch_size
+    @of
+  end
+end
+
+ActiveRecord::Batches::BatchEnumerator.include(ActiveRecordBatchEnumerator)