maintenance_tasks 1.0.0

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

@@ -0,0 +1,10 @@
+<h5 class="title is-5">
+  <%= time_tag run.created_at, title: run.created_at %>
+  <%= status_tag run.status if with_status %>
+</h5>
+
+<%= progress run %>
+
+<div class="content">
+  <%= render "maintenance_tasks/runs/info/#{run.status}", run: run %>
+</div>

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

@@ -0,0 +1,11 @@
+<div class="box">
+  <% if with_task_name %>
+    <h3 class="title is-3">
+      <%= link_to run.task_name, task_path(run.task_name) %>
+      <%= status_tag run.status %>
+    </h3>
+    <%= render 'maintenance_tasks/runs/info', run: run, with_status: false %>
+  <% else %>
+    <%= render 'maintenance_tasks/runs/info', run: run, with_status: true %>
+  <% end %>
+</div>

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

@@ -0,0 +1,15 @@
+<div class="block">
+  <%= form_with url: runs_path, method: :get do |form| %>
+    <div class="field has-addons">
+      <div class="control">
+        <%= form.search_field :task_name, value: params[:task_name], placeholder: "Task name", class: "input" %>
+      </div>
+      <div class="control">
+        <%= form.submit "Search", class: "button is-link" %>
+      </div>
+    </div>
+  <% end %>
+</div>
+
+<%= render @runs, with_task_name: true %>
+<%= pagination(@pagy) %>

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

@@ -0,0 +1,4 @@
+<p>
+  Ran for <%= time_running_in_words run %>,
+  cancelled <%= time_ago run.ended_at %>.
+</p>

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

@@ -0,0 +1 @@
+<p>Cancelling…</p>

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

@@ -0,0 +1 @@
+<p>Waiting to start.</p>

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

@@ -0,0 +1,25 @@
+<p>
+  Ran for <%= time_running_in_words run  %> until an error happened
+  <%= time_ago run.ended_at %>.
+</p>
+
+</p>
+
+<div class="card">
+  <header class="card-header">
+    <p class="card-header-title">
+      <%= run.error_class %>
+    </p>
+  </header>
+
+  <div class="card-content">
+    <div class="content">
+      <p><%= run.error_message %></p>
+
+      <% if run.backtrace.present? %>
+        <code><%= format_backtrace(run.backtrace) %></code>
+      <% end %>
+
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1 @@
+<p>Interrupted momentarily, resuming shortly…</p>

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

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

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

@@ -0,0 +1 @@
+<p>Pausing…</p>

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

@@ -0,0 +1,7 @@
+<p>
+  <% if run.estimated_completion_time %>
+    <%= estimated_time_to_completion(run).capitalize %> remaining.
+  <% else %>
+    Processed <%= pluralize run.tick_count, 'item' %> so far.
+  <% end %>
+</p>

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

@@ -0,0 +1,5 @@
+<p>
+  Ran for <%= time_running_in_words run %>,
+  finished <%= time_ago run.ended_at %>.
+</p>
+

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

@@ -0,0 +1,8 @@
+<div class="box">
+  <h3 class="title is-3">
+    <%= link_to task, task_path(task) %>
+    <%= status_tag(task.status) %>
+  </h3>
+
+  <%= render 'maintenance_tasks/runs/info', run: task.last_run, with_status: false if task.last_run %>
+</div>

data/app/views/maintenance_tasks/tasks/actions/_cancelled.html.erb

@@ -0,0 +1 @@
+<%= button_to 'Run', run_task_path(task), method: :put, class: 'button is-success', disabled: task.deleted? %>

data/app/views/maintenance_tasks/tasks/actions/_cancelling.html.erb

@@ -0,0 +1,4 @@
+<%= button_to 'Run', run_task_path(task), method: :put, class: 'button is-success', disabled: true %>
+<% if task.last_run.stuck? %>
+  <%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger', disabled: task.deleted? %>
+<% end %>

data/app/views/maintenance_tasks/tasks/actions/_enqueued.html.erb

@@ -0,0 +1,2 @@
+<%= button_to 'Pause', pause_task_run_path(task, task.last_run), method: :put, class: 'button is-warning', disabled: task.deleted? %>
+<%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger' %>

data/app/views/maintenance_tasks/tasks/actions/_errored.html.erb

@@ -0,0 +1 @@
+<%= button_to 'Run', run_task_path(task), method: :put, class: 'button is-success', disabled: task.deleted? %>

data/app/views/maintenance_tasks/tasks/actions/_interrupted.html.erb

@@ -0,0 +1,2 @@
+<%= button_to 'Pause', pause_task_run_path(task, task.last_run), method: :put, class: 'button is-warning', disabled: task.deleted? %>
+<%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger' %>

data/app/views/maintenance_tasks/tasks/actions/_new.html.erb

@@ -0,0 +1 @@
+<%= button_to 'Run', run_task_path(task), method: :put, class: 'button is-success', disabled: task.deleted? %>

data/app/views/maintenance_tasks/tasks/actions/_paused.html.erb

@@ -0,0 +1,2 @@
+<%= button_to 'Resume', run_task_path(task), method: :put, class: 'button is-primary', disabled: task.deleted? %>
+<%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger' %>

data/app/views/maintenance_tasks/tasks/actions/_pausing.html.erb

@@ -0,0 +1,2 @@
+<%= button_to 'Pausing', pause_task_run_path(task, task.last_run), method: :put, class: 'button is-warning', disabled: true %>
+<%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger', disabled: task.deleted? %>

data/app/views/maintenance_tasks/tasks/actions/_running.html.erb

@@ -0,0 +1,2 @@
+<%= button_to 'Pause', pause_task_run_path(task, task.last_run), method: :put, class: 'button is-warning', disabled: task.deleted? %>
+<%= button_to 'Cancel', cancel_task_run_path(task, task.last_run), method: :put, class: 'button is-danger' %>

data/app/views/maintenance_tasks/tasks/actions/_succeeded.html.erb

@@ -0,0 +1 @@
+<%= button_to 'Run', run_task_path(task), method: :put, class: 'button is-success', disabled: task.deleted? %>

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

@@ -0,0 +1,22 @@
+<% if @available_tasks.empty? %>
+  <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>.
+    </p>
+  </div>
+<% else %>
+  <% if active_tasks = @available_tasks[:active] %>
+    <h3 class="title is-3">Active Tasks</h3>
+    <%= render partial: 'task', collection: active_tasks %>
+  <% end %>
+  <% if new_tasks = @available_tasks[:new] %>
+    <h3 class="title is-3">New Tasks</h3>
+    <%= render partial: 'task', collection: new_tasks %>
+  <% end %>
+  <% if completed_tasks = @available_tasks[:completed] %>
+    <h3 class="title is-3">Completed Tasks</h3>
+    <%= render partial: 'task', collection: completed_tasks %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,25 @@
+<% content_for :page_title, @task %>
+
+<h1 class="title is-1">
+  <%= @task %> <%= status_tag(@task.status) %>
+</h1>
+
+<%= render 'maintenance_tasks/runs/info', run: @task.last_run, with_status: false if @task.last_run %>
+
+<div class="buttons">
+  <%= render "maintenance_tasks/tasks/actions/#{@task.status}", task: @task %>
+</div>
+
+<% if (code = @task.code) %>
+  <pre><code><%= highlight_code(code) %></code></pre>
+<% end %>
+
+<% if @previous_runs.present? %>
+  <hr/>
+
+  <h4 class="title is-4">Previous Runs</h4>
+
+  <%= render @previous_runs, with_task_name: false %>
+
+  <%= pagination(@pagy) %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+MaintenanceTasks::Engine.routes.draw do
+  resources :runs, only: [:index], format: false
+
+  resources :tasks, only: [:index, :show], format: false do
+    member do
+      put 'run'
+    end
+
+    resources :runs, only: [], format: false do
+      member do
+        put 'pause'
+        put 'cancel'
+      end
+    end
+  end
+
+  root to: 'tasks#index'
+end

data/db/migrate/20201211151756_create_maintenance_tasks_runs.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+class CreateMaintenanceTasksRuns < ActiveRecord::Migration[6.0]
+  def change
+    create_table(:maintenance_tasks_runs) do |t|
+      t.string(:task_name, null: false)
+      t.datetime(:started_at)
+      t.datetime(:ended_at)
+      t.float(:time_running, default: 0.0, null: false)
+      t.integer(:tick_count, default: 0, null: false)
+      t.integer(:tick_total)
+      t.string(:job_id)
+      t.bigint(:cursor)
+      t.string(:status, default: :enqueued, null: false)
+      t.string(:error_class)
+      t.string(:error_message)
+      t.text(:backtrace)
+      t.timestamps
+      t.index(:task_name)
+      t.index([:task_name, :created_at], order: { created_at: :desc })
+    end
+  end
+end

data/exe/maintenance_tasks

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby -w
+
+# frozen_string_literal: true
+
+require File.expand_path('config/application', Dir.pwd)
+
+Rails.application.require_environment!
+
+require 'maintenance_tasks/cli'
+
+module MaintenanceTasks
+  CLI.start(ARGV)
+end

data/lib/generators/maintenance_tasks/install_generator.rb

@@ -0,0 +1,22 @@
+# 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.
+  #
+  # @api private
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    # Mounts the engine in the host application's config/routes.rb
+    def mount_engine
+      route("mount MaintenanceTasks::Engine => '/maintenance_tasks'")
+    end
+
+    # Copies engine migrations to host application and migrates the database
+    def install_migrations
+      rake('maintenance_tasks:install:migrations')
+      rake('db:migrate')
+    end
+  end
+  private_constant :InstallGenerator
+end

data/lib/generators/maintenance_tasks/task_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Generator used for creating maintenance tasks in the host application.
+  #
+  # @api private
+  class TaskGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
+    desc 'This generator creates a task file at app/tasks and a corresponding '\
+      'test.'
+
+    check_class_collision suffix: 'Task'
+
+    # Creates the Task file.
+    def create_task_file
+      template_file = File.join(
+        "app/tasks/#{tasks_module_file_path}",
+        class_path,
+        "#{file_name}_task.rb"
+      )
+      template('task.rb', template_file)
+    end
+
+    # Creates the Task test file, according to the app's test framework.
+    # A spec file is created if the app uses RSpec.
+    # Otherwise, an ActiveSupport::TestCase test is created.
+    def create_test_file
+      return unless test_framework
+
+      if test_framework == :rspec
+        create_task_spec_file
+      else
+        create_task_test_file
+      end
+    end
+
+    private
+
+    def create_task_test_file
+      template_file = File.join(
+        "test/tasks/#{tasks_module_file_path}",
+        class_path,
+        "#{file_name}_task_test.rb"
+      )
+      template('task_test.rb', template_file)
+    end
+
+    def create_task_spec_file
+      template_file = File.join(
+        "spec/tasks/#{tasks_module_file_path}",
+        class_path,
+        "#{file_name}_task_spec.rb"
+      )
+      template('task_spec.rb', template_file)
+    end
+
+    def file_name
+      super.sub(/_task\z/i, '')
+    end
+
+    def tasks_module
+      MaintenanceTasks.tasks_module
+    end
+
+    def tasks_module_file_path
+      tasks_module.underscore
+    end
+
+    def test_framework
+      Rails.application.config.generators.options[:rails][:test_framework]
+    end
+  end
+  private_constant :TaskGenerator
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module <%= tasks_module %>
+<% module_namespacing do -%>
+  class <%= class_name %>Task < MaintenanceTasks::Task
+    def collection
+      # Collection to be iterated over
+      # Must be Active Record Relation or Array
+    end
+
+    def process(element)
+      # The work to be done in a single iteration of the task
+    end
+
+    def count
+      # Optionally, define the number of rows that will be iterated over
+      # This is used to track the task's progress
+    end
+  end
+<% end -%>
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require 'rails_helper'
+
+module <%= tasks_module %>
+<% module_namespacing do -%>
+  RSpec.describe <%= class_name %>Task do
+    # describe '#process' do
+      # it 'performs a task iteration' do
+        # <%= tasks_module %>::<%= class_name %>Task.new.process(element)
+      # end
+    # end
+  end
+<% end -%>
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require 'test_helper'
+
+module <%= tasks_module %>
+<% module_namespacing do -%>
+  class <%= class_name %>TaskTest < ActiveSupport::TestCase
+    # test "#process performs a task iteration" do
+    #   <%= tasks_module %>::<%= class_name %>Task.new.process(element)
+    # end
+  end
+<% end -%>
+end

data/lib/maintenance_tasks.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+require 'action_controller'
+require 'action_view'
+require 'active_job'
+require 'active_record'
+
+require 'job-iteration'
+require 'maintenance_tasks/engine'
+require 'pagy'
+require 'pagy/extras/bulma'
+
+# 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.
+module MaintenanceTasks
+  # The module to namespace Tasks in, as a String. Defaults to 'Maintenance'.
+  # @param [String] the tasks_module value.
+  mattr_accessor :tasks_module, default: 'Maintenance'
+
+  # Defines the job to be used to perform Tasks. This job must be either
+  # `MaintenanceTasks::TaskJob` or a class that inherits from it.
+  #
+  # @param [String] the name of the job class.
+  mattr_writer :job, default: 'MaintenanceTasks::TaskJob'
+
+  # After each iteration, the progress of the task may be updated. This duration
+  # in seconds limits these updates, skipping if the duration since the last
+  # update is lower than this value, except if the job is interrupted, in which
+  # case the progress will always be recorded.
+  #
+  # @param [ActiveSupport::Duration, Numeric] Duration of the delay to update
+  #   the ticker during Task iterations.
+  mattr_accessor :ticker_delay, default: 1.second
+
+  # Defines a callback to be performed when an error occurs in the task.
+  mattr_accessor :error_handler, default: ->(_error) {}
+
+  class << self
+    # Retrieves the class that is configured as the Task Job to be used to
+    # perform Tasks.
+    #
+    # @return [TaskJob] the job class.
+    def job
+      @@job.constantize
+    end
+
+    # Attempts to configure Bugsnag integration. If the application uses
+    # Bugsnag, it is automatically configured to report on errors raised while
+    # a Task is performing.
+    def configure_bugsnag_integration
+      load('maintenance_tasks/integrations/bugsnag_handler.rb')
+    rescue LoadError
+      nil
+    end
+  end
+end
+
+MaintenanceTasks.configure_bugsnag_integration