maintenance_tasks 1.0.0

data/app/models/maintenance_tasks/runner.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # This class is responsible for running a given Task.
+  class Runner
+    # Exception raised when a Task Job couldn't be enqueued.
+    class EnqueuingError < StandardError
+      # Initializes a Enqueuing Error.
+      #
+      # @param run [Run] the Run which failed to be enqueued.
+      # @return [EnqueuingError] an Enqueuing Error instance.
+      def initialize(run)
+        super("The job to perform #{run.task_name} could not be enqueued")
+        @run = run
+      end
+
+      attr_reader :run
+    end
+
+    # Runs a Task.
+    #
+    # This method creates a Run record for the given Task name and enqueues the
+    # Run.
+    #
+    # @param name [String] the name of the Task to be run.
+    #
+    # @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:)
+      run = Run.active.find_by(task_name: name) || Run.new(task_name: name)
+
+      run.enqueued!
+      enqueue(run)
+      Task.named(name)
+    end
+
+    private
+
+    def enqueue(run)
+      unless MaintenanceTasks.job.perform_later(run)
+        raise "The job to perform #{run.task_name} could not be enqueued. "\
+          'Enqueuing has been prevented by a callback.'
+      end
+    rescue => error
+      run.persist_error(error)
+      raise EnqueuingError, run
+    end
+  end
+end

data/app/models/maintenance_tasks/task_data.rb

@@ -0,0 +1,137 @@
+# 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
+  # deleted.
+  #
+  # Instances of this class replace a Task class instance in cases where we
+  # don't need the actual Task subclass.
+  #
+  # @api private
+  class TaskData
+    class << self
+      # Initializes a Task Data by name, raising if the Task does not exist.
+      #
+      # For the purpose of this method, a Task does not exist if it's deleted
+      # and doesn't have a Run. While technically, it could have existed and
+      # been deleted since, if it never had a Run we may as well consider it
+      # non-existent since we don't have interesting data to show.
+      #
+      # @param name [String] the name of the Task subclass.
+      # @return [TaskData] a Task Data instance.
+      # @raise [Task::NotFoundError] if the Task does not exist and doesn't have
+      #   a Run.
+      def find(name)
+        task_data = new(name)
+        task_data.last_run || Task.named(name)
+        task_data
+      end
+
+      # Returns a list of sorted Task Data objects that represent the
+      # available Tasks.
+      #
+      # Tasks are sorted by category, and within a category, by Task name.
+      # Determining a Task's category require its latest Run record.
+      # To optimize calls to the database, a single query is done to get the
+      # last Run for each Task, and Task Data instances are initialized with
+      # these last_run values.
+      #
+      # @return [Array<TaskData>] the list of Task Data.
+      def available_tasks
+        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)
+        )
+
+        task_names.map do |task_name|
+          last_run = last_runs.find { |run| run.task_name == task_name }
+          TaskData.new(task_name, last_run)
+        end.sort_by!(&:name)
+      end
+    end
+
+    # Initializes a Task Data with a name and optionally a last_run.
+    #
+    # @param name [String] the name of the Task subclass.
+    # @param last_run [MaintenanceTasks::Run] optionally, a Run record to
+    #   set for the Task.
+    def initialize(name, last_run = :none_passed)
+      @name = name
+      @last_run = last_run unless last_run == :none_passed
+    end
+
+    # @return [String] the name of the Task.
+    attr_reader :name
+
+    alias_method :to_s, :name
+
+    # The Task's source code.
+    #
+    # @return [String] the contents of the file which defines the Task.
+    # @return [nil] if the Task file was deleted.
+    def code
+      return if deleted?
+      task = Task.named(name)
+      file = task.instance_method(:collection).source_location.first
+      File.read(file)
+    end
+
+    # Retrieves the latest Run associated with the Task.
+    #
+    # @return [MaintenanceTasks::Run] the Run record.
+    # @return [nil] if there are no Runs associated with the Task.
+    def last_run
+      return @last_run if defined?(@last_run)
+      @last_run = runs.first
+    end
+
+    # Returns the set of Run records associated with the Task previous to the
+    # last Run. This collection represents a historic of past Runs for
+    # information purposes, since the base for Task Data information comes
+    # primarily from the last Run.
+    #
+    # @return [ActiveRecord::Relation<MaintenanceTasks::Run>] the relation of
+    #   record previous to the last Run.
+    def previous_runs
+      return Run.none unless last_run
+      runs.where.not(id: last_run.id)
+    end
+
+    # @return [Boolean] whether the Task has been deleted.
+    def deleted?
+      Task.named(name)
+      false
+    rescue Task::NotFoundError
+      true
+    end
+
+    # The Task status. It returns the status of the last Run, if present. If the
+    # Task does not have any Runs, the Task status is `new`.
+    #
+    # @return [String] the Task status.
+    def status
+      last_run&.status || 'new'
+    end
+
+    # Retrieves the Task's category, which is one of active, new, or completed.
+    #
+    # @return [Symbol] the category of the Task.
+    def category
+      if last_run.present? && last_run.active?
+        :active
+      elsif last_run.nil?
+        :new
+      else
+        :completed
+      end
+    end
+
+    private
+
+    def runs
+      Run.where(task_name: name).order(created_at: :desc)
+    end
+  end
+  private_constant :TaskData
+end

data/app/models/maintenance_tasks/ticker.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # This class encapsulates the logic behind updating the tick counter.
+  #
+  # It's initialized with a duration for the throttle, and a block to persist
+  # the number of ticks to increment.
+  #
+  # When +tick+ is called, the block will be called with the increment,
+  # provided the duration since the last update (or initialization) has been
+  # long enough.
+  #
+  # To not lose any increments, +persist+ should be used, which may call the
+  # block with any leftover ticks.
+  #
+  # @api private
+  class Ticker
+    # Creates a Ticker that will call the block each time +tick+ is called,
+    # unless the tick is being throttled.
+    #
+    # @param throttle_duration [ActiveSupport::Duration, Numeric] Duration
+    #   since initialization or last call that will cause a throttle.
+    # @yieldparam ticks [Integer] the increment in ticks to be persisted.
+    def initialize(throttle_duration, &persist)
+      @throttle_duration = throttle_duration
+      @persist = persist
+      @last_persisted = Time.now
+      @ticks_recorded = 0
+    end
+
+    # Increments the tick count by one, and may persist the new value if the
+    # threshold duration has passed since initialization or the tick count was
+    # last persisted.
+    def tick
+      @ticks_recorded += 1
+      persist if persist?
+    end
+
+    # Persists the tick increments by calling the block passed to the
+    # initializer. This is idempotent in the sense that calling it twice in a
+    # row will call the block at most once (if it had been throttled).
+    def persist
+      return if @ticks_recorded == 0
+      now = Time.now
+      duration = now - @last_persisted
+      @last_persisted = now
+      @persist.call(@ticks_recorded, duration)
+      @ticks_recorded = 0
+    end
+
+    private
+
+    def persist?
+      Time.now - @last_persisted >= @throttle_duration
+    end
+  end
+  private_constant :Ticker
+end

data/app/tasks/maintenance_tasks/task.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Base class that is inherited by the host application's task classes.
+  class Task
+    extend ActiveSupport::DescendantsTracker
+
+    class NotFoundError < NameError; end
+
+    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)
+        name.constantize
+      rescue NameError
+        raise NotFoundError.new("Task #{name} not found.", name)
+      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
+
+      private
+
+      def load_constants
+        namespace = MaintenanceTasks.tasks_module.safe_constantize
+        return unless namespace
+        namespace.constants.map { |constant| namespace.const_get(constant) }
+      end
+    end
+
+    # 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
+      raise NotImplementedError,
+        "#{self.class.name} must implement `collection`."
+    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 NotImplementedError,
+        "#{self.class.name} must implement `process`."
+    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
+    end
+
+    # Convenience method to allow tasks define enumerators with cursors for
+    # compatibility with Job Iteration.
+    #
+    # @return [JobIteration::EnumeratorBuilder] instance of an enumerator
+    #   builder available to tasks.
+    def enumerator_builder
+      JobIteration.enumerator_builder.new(nil)
+    end
+  end
+end

data/app/validators/maintenance_tasks/run_status_validator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+module MaintenanceTasks
+  # Custom validator class responsible for ensuring that transitions between
+  # Run statuses are valid.
+  #
+  # @api private
+  class RunStatusValidator < ActiveModel::Validator
+    # Valid status transitions a Run can make.
+    VALID_STATUS_TRANSITIONS = {
+      # enqueued -> running occurs when the task starts performing.
+      # enqueued -> pausing occurs when the task is paused before starting.
+      # enqueued -> cancelling occurs when the task is cancelled
+      #   before starting.
+      # enqueued -> errored occurs when the task job fails to be enqueued.
+      '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
+      #   after it was paused, such that the task had not actually halted yet.
+      # pausing -> succeeded occurs when the task completes immediately after
+      #   being paused. This can happen if the task is on its last iteration
+      #   when it is paused, or if the task is paused after enqueue but has
+      #   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'],
+      # 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'],
+      # running -> succeeded occurs when the task completes successfully.
+      # running -> pausing occurs when a user pauses the task as
+      #   it's performing.
+      # running -> cancelling occurs when a user cancels the task as
+      #   it's performing.
+      # 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',
+      ],
+      # 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'],
+      # 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
+      #   it is interrupted.
+      # interrupted -> cancelling occurs when the task is cancelled by the user
+      #   while it is interrupted.
+      'interrupted' => ['running', 'pausing', 'cancelling'],
+    }
+
+    # Validate whether a transition from one Run status
+    # to another is acceptable.
+    #
+    #  @param record [MaintenanceTasks::Run] the Run object being validated.
+    def validate(record)
+      return unless (previous_status, new_status = record.status_change)
+
+      valid_new_statuses = VALID_STATUS_TRANSITIONS.fetch(previous_status, [])
+
+      unless valid_new_statuses.include?(new_status)
+        add_invalid_status_error(record, previous_status, new_status)
+      end
+    end
+
+    private
+
+    def add_invalid_status_error(record, previous_status, new_status)
+      record.errors.add(
+        :status,
+        "Cannot transition run from status #{previous_status} to #{new_status}"
+      )
+    end
+  end
+  private_constant :RunStatusValidator
+end

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

@@ -0,0 +1,11 @@
+<nav class="navbar is-dark is-spaced" 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>
+
+  <div id="navbarMenu" class="navbar-menu is-active">
+    <div class="navbar-start">
+      <%= link_to "Runs", runs_path, class: 'navbar-item' %>
+    </div>
+  </div>
+</nav>

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

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="<%= I18n.locale %>">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <title>
+      <% if content_for?(:page_title) %>
+        <%= content_for :page_title %> -
+      <% end %>
+
+      Maintenance Tasks
+    </title>
+
+    <%= csrf_meta_tags %>
+
+    <%=
+      stylesheet_link_tag URI.join(controller.class::BULMA_CDN, 'npm/bulma@0.9.1/css/bulma.css'),
+        media: :all,
+        integrity: 'sha256-67AR2JVjhMZCLVxapLuBSMap5RrXbksv4vlllenHBSE=',
+        crossorigin: 'anonymous'
+    %>
+
+    <style nonce="<%= content_security_policy_nonce %>">
+      .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; }
+    </style>
+
+    <% if defined?(@refresh) %>
+      <meta http-equiv="refresh" content="<%= @refresh %>">
+    <% end %>
+  </head>
+
+  <body>
+    <%= render 'layouts/maintenance_tasks/navbar' %>
+
+    <section class="section">
+      <div class="container">
+        <% if notice %>
+          <div class="notification is-success"><%= notice %></div>
+        <% elsif alert %>
+          <div class="notification is-warning"><%= alert %></div>
+        <% end %>
+
+        <%= yield %>
+      </div>
+    </div>
+  </body>
+</html>