maintenance_tasks 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d591c21fb76efef72185bf183b0f4b0bc0a5b97a2606e083f6fbfc11325e029b
+  data.tar.gz: 6195855524490ebc663f1970134b6aed2abe7887345b6c17d2d0dccea9d81fb4
+SHA512:
+  metadata.gz: 3fa1e498d50830521cabeb8babda612a9762438cd1fdccf5cecf776ae069ec85cdbaedbded208bdfc1e72479b69ffb76a39b999e4c2f8d810811dc8672f0b5cc
+  data.tar.gz: 2d9aa8e0c134baa3864f2cd5e9fe53944a5d13a89c21caab26dcd394b3eb8845af62397f2d1be880c9f27d71cbe77db3865d16c7da53f0b70cc64cc7bf4153a4

data/README.md

@@ -0,0 +1,316 @@
+# MaintenanceTasks
+
+A Rails engine for queuing and managing maintenance tasks.
+
+## Table of Contents
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Creating a Task](#creating-a-task)
+    * [Considerations when writing Tasks](#considerations-when-writing-tasks)
+  * [Writing tests for a Task](#writing-tests-for-a-task)
+  * [Running a Task](#running-a-task)
+  * [Monitoring your Task's status](#monitoring-your-tasks-status)
+  * [How Maintenance Tasks runs a Task](#how-maintenance-tasks-runs-a-task)
+    * [Help! My Task is stuck](#help-my-task-is-stuck)
+  * [Configuring the gem](#configuring-the-gem)
+    * [Customizing the error handler](#customizing-the-error-handler)
+    * [Customizing the maintenance tasks module](#customizing-the-maintenance-tasks-module)
+    * [Customizing the underlying job class](#customizing-the-underlying-job-class)
+    * [Customizing the rate at which task progress gets updated](#customizing-the-rate-at-which-task-progress-gets-updated)
+* [Upgrading](#upgrading)
+* [Contributing](#contributing)
+* [Releasing new versions](#releasing-new-versions)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'maintenance_tasks'
+```
+
+And then execute:
+
+```bash
+$ bundle
+$ rails generate maintenance_tasks:install
+```
+
+The generator creates and runs a migration to add the necessary table to your
+database. It also mounts Maintenance Tasks in your `config/routes.rb`. By
+default the web UI can be accessed in the new `/maintenance_tasks` path.
+
+## Usage
+
+### Creating a Task
+
+A generator is provided to create tasks. Generate a new task by running:
+
+```bash
+$ rails generate maintenance_tasks:task update_posts
+```
+
+This creates the task file `app/tasks/maintenance/update_posts_task.rb`.
+
+The generated task is a subclass of `MaintenanceTasks::Task` that implements:
+
+* `collection`: return an Active Record Relation or an Array to be iterated
+  over.
+* `process`: do the work of your maintenance task on a single record
+* `count`: return the number of rows that will be iterated over (optional, to be
+  able to show progress)
+
+Example:
+
+```ruby
+# app/tasks/maintenance/update_posts_task.rb
+module Maintenance
+  class UpdatePostsTask < MaintenanceTasks::Task
+    def collection
+      Post.all
+    end
+
+    def count
+      collection.count
+    end
+
+    def process(post)
+      post.update!(content: 'New content!')
+    end
+  end
+end
+```
+
+#### Considerations when writing Tasks
+
+MaintenanceTasks relies on the queue adapter configured for your application to
+run the job which is processing your Task. The guidelines for writing Task may
+depend on the queue adapter but in general, you should follow these rules:
+
+* Duration of `Task#process`: processing a single element of the collection
+  should take less than 25 seconds, or the duration set as a timeout for Sidekiq
+  or the queue adapter configured in your application. It allows the Task to be
+  safely interrupted and resumed.
+* Idempotency of `Task#process`: it should be safe to run `process` multiple
+  times for the same element of the collection. Read more in [this Sidekiq best
+  practice][sidekiq-idempotent]. It's important if the Task errors and you run
+  it again, because the same element that errored the Task may well be processed
+  again. It especially matters in the situation described above, when the
+  iteration duration exceeds the timeout: if the job is re-enqueued, multiple
+  elements may be processed again.
+
+[sidekiq-idempotent]: https://github.com/mperham/sidekiq/wiki/Best-Practices#2-make-your-job-idempotent-and-transactional
+
+### Writing tests for a Task
+
+The task generator will also create a test file for your task in the folder
+`test/tasks/maintenance/`. At a minimum, it's recommended that the `#process`
+method in your task be tested. You may also want to test the `#collection` and
+`#count` methods for your task if they are sufficiently complex.
+
+Example:
+
+```ruby
+# test/tasks/maintenance/update_posts_task_test.rb
+
+require 'test_helper'
+
+module Maintenance
+  class UpdatePostsTaskTest < ActiveSupport::TestCase
+    test "#process performs a task iteration" do
+      post = Post.new
+
+      Maintenance::UpdatePostsTask.new.process(post)
+
+      assert_equal 'New content!', post.content
+    end
+  end
+end
+```
+
+### Running a Task
+
+You can run your new Task by accessing the Web UI and clicking on "Run".
+
+Alternatively, you can run your Task in the command line:
+
+```bash
+$ bundle exec maintenance_tasks perform Maintenance::UpdatePostsTask
+```
+
+You can also run a Task in Ruby by sending `run` with a Task name to a Runner
+instance:
+
+```ruby
+MaintenanceTasks::Runner.new.run('Maintenance::UpdatePostsTask')
+```
+
+### Monitoring your Task's status
+
+The web UI will provide updates on the status of your Task. Here are the states
+a Task can be in:
+
+* **new**: A Task that has not yet been run.
+* **enqueued**: A Task that is waiting to be performed after a user has
+  instructed it to run.
+* **running**: A Task that is currently being performed by a job worker.
+* **pausing**: A Task that was paused by a user, but needs to finish work
+  before stopping.
+* **paused**: A Task that was paused by a user and is not performing. It can be
+  resumed.
+* **interrupted**: A Task that has been momentarily interrupted by the job
+  infrastructure.
+* **cancelling**: A Task that was cancelled by a user, but needs to finish work
+  before stopping.
+* **cancelled**: A Task that was cancelled by a user and is not performing. It
+  cannot be resumed.
+* **succeeded**: A Task that finished successfully.
+* **errored**: A Task that encountered an unhandled exception while performing.
+
+### How Maintenance Tasks runs a Task
+
+Maintenance tasks can be running for a long time, and the purpose of the gem is
+to make it easy to continue running tasks through deploys, [Kubernetes Pod
+scheduling][k8s-scheduling], [Heroku dyno restarts][heroku-cycles] or other
+infrastructure or code changes.
+
+[k8s-scheduling]: https://kubernetes.io/docs/concepts/scheduling-eviction/
+[heroku-cycles]: https://www.heroku.com/dynos/lifecycle
+
+This means a Task can safely be interrupted, re-enqueued and resumed without any
+intervention at the end of an iteration, after the `process` method returns.
+
+By default, a running Task will be interrupted after running for more 5 minutes.
+This is [configured in the `job-iteration` gem][max-job-runtime] and can be
+tweaked in an initializer if necessary.
+
+[max-job-runtime]: https://github.com/Shopify/job-iteration/blob/master/guides/best-practices.md#max-job-runtime
+
+Running tasks will also be interrupted and re-enqueued when needed. For example
+[when Sidekiq workers shuts down for a deploy][sidekiq-deploy]:
+
+[sidekiq-deploy]: https://github.com/mperham/sidekiq/wiki/Deployment
+
+* When Sidekiq receives a TSTP or TERM signal, it will consider itself to be
+  stopping.
+* When Sidekiq is stopping, JobIteration stops iterating over the enumerator.
+  The position in the iteration is saved, a new job is enqueued to resume work,
+  and the Task is marked as interrupted.
+
+When Sidekiq is stopping, it will give workers 25 seconds to finish before
+forcefully terminating them (this is the default but can be configured with the
+`--timeout` option).  Before the worker threads are terminated, Sidekiq will try
+to re-enqueue the job so your Task will be resumed. However, the position in the
+collection won't be persisted so at least one iteration may run again.
+
+#### Help! My Task is stuck
+
+Finally, if the queue adapter configured for your application doesn't have this
+property, or if Sidekiq crashes, is forcefully terminated, or is unable to
+re-enqueue the jobs that were in progress, the Task may be in a seemingly stuck
+situation where it appears to be running but is not. In that situation, pausing
+or cancelling it will not result in the Task being paused or cancelled, as the
+Task will get stuck in a state of `pausing` or `cancelling`. As a work-around,
+if a Task is `cancelling` for more than 5 minutes, you will be able to cancel it
+for good, which will just mark it as cancelled, allowing you to run it again.
+
+### Configuring the gem
+
+There are a few configurable options for the gem. Custom configurations should
+be placed in a `maintenance_tasks.rb` initializer.
+
+#### Customizing the error handler
+
+Exceptions raised while a Task is performing are rescued and information about
+the error is persisted and visible in the UI.
+
+If your application uses Bugsnag to monitor errors, the gem will automatically
+notify Bugsnag of any errors raised while a Task is performing.
+
+If you want to integrate with another exception monitoring service or customize
+error handling, a callback can be defined:
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.error_handler = ->(error) { MyErrorMonitor.notify(error) }
+```
+
+#### Customizing the maintenance tasks module
+
+`MaintenanceTasks.tasks_module` can be configured to define the module in which
+tasks will be placed.
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.tasks_module = 'TaskModule'
+```
+
+If no value is specified, it will default to `Maintenance`.
+
+#### Customizing the underlying job class
+
+`MaintenanceTasks.job` can be configured to define a Job class for your tasks to
+use. This is a global configuration, so this Job class will be used across all
+maintenance tasks in your application.
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.job = 'CustomTaskJob'
+
+# app/jobs/custom_task_job.rb
+class CustomTaskJob < MaintenanceTasks::TaskJob
+  queue_as :low_priority
+end
+```
+
+The Job class **must inherit** from `MaintenanceTasks::TaskJob`.
+
+Note that `retry_on` is not supported for custom Job
+classes, so failed jobs cannot be retried.
+
+#### Customizing the rate at which task progress gets updated
+
+`MaintenanceTasks.ticker_delay` can be configured to customize how frequently
+task progress gets persisted to the database. It can be a `Numeric` value or an
+`ActiveSupport::Duration` value.
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.ticker_delay = 2.seconds
+```
+
+If no value is specified, it will default to 1 second.
+
+## Upgrading
+
+Use bundler to check for and upgrade to newer versions. After installing a new
+version, re-run the install command:
+
+```bash
+$ rails generate maintenance_tasks:install
+```
+
+This ensures that new migrations are installed and run as well.
+
+## Contributing
+
+Would you like to report an issue or contribute with code? We accept issues and
+pull requests. You can find the contribution guidelines on
+[CONTRIBUTING.md][contributing].
+
+[contributing]: https://github.com/Shopify/maintenance_tasks/blob/main/.github/CONTRIBUTING.md
+
+## Releasing new versions
+
+This gem is published to packagecloud. The procedure to publish a new version:
+
+* Update `spec.version` in `maintenance_tasks.gemspec`.
+* Run `bundle install` to bump the `Gemfile.lock` version of the gem.
+* Open a PR and merge on approval.
+* Create a [release on GitHub][release] with a version number that matches the
+  version defined in the gemspec.
+* Deploy via [Shipit][shipit] and see the new version on
+  <https://rubygems.org/gems/maintenance_tasks>.
+
+[release]: https://help.github.com/articles/creating-releases/
+[shipit]: https://shipit.shopify.io/shopify/maintenance_tasks/rubygems

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MaintenanceTasks'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load('rails/tasks/engine.rake')
+
+load('rails/tasks/statistics.rake')
+
+require 'bundler/gem_tasks'
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+task(test: 'app:test')
+task('test:system' => 'app:test:system')
+task(default: ['db:setup', 'test', 'test:system', 'rubocop'])

data/app/controllers/maintenance_tasks/application_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Base class for all controllers used by this engine.
+  #
+  # @api private
+  class ApplicationController < ActionController::Base
+    include Pagy::Backend
+
+    BULMA_CDN = 'https://cdn.jsdelivr.net'
+
+    content_security_policy do |policy|
+      policy.style_src(BULMA_CDN)
+      policy.frame_ancestors(:self)
+    end
+
+    before_action do
+      request.content_security_policy_nonce_generator ||=
+        ->(_request) { SecureRandom.base64(16) }
+      request.content_security_policy_nonce_directives = ['style-src']
+    end
+
+    protect_from_forgery with: :exception
+  end
+  private_constant :ApplicationController
+end

data/app/controllers/maintenance_tasks/runs_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Class communicates with the Run model to persist info related to task runs.
+  # It defines actions for creating and pausing runs.
+  #
+  # @api private
+  class RunsController < ApplicationController
+    before_action :set_run, except: :index
+
+    # Shows a full list of Runs.
+    def index
+      query = Run.all.order(id: :desc)
+      if params[:task_name].present?
+        task_name = Run.sanitize_sql_like(params[:task_name])
+        query = query.where('task_name LIKE ?', "%#{task_name}%")
+      end
+      @pagy, @runs = pagy(query)
+    end
+
+    # Updates a Run status to paused.
+    def pause
+      @run.pausing!
+      redirect_to(task_path(@run.task_name))
+    rescue ActiveRecord::RecordInvalid => error
+      redirect_to(task_path(@run.task_name), alert: error.message)
+    end
+
+    # Updates a Run status to cancelling.
+    def cancel
+      @run.cancel
+      redirect_to(task_path(@run.task_name))
+    rescue ActiveRecord::RecordInvalid => error
+      redirect_to(task_path(@run.task_name), alert: error.message)
+    end
+
+    private
+
+    def set_run
+      @run = Run.find(params.fetch(:id))
+    end
+  end
+  private_constant :RunsController
+end

data/app/controllers/maintenance_tasks/tasks_controller.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MaintenanceTasks
+  # Class handles rendering the maintenance_tasks page in the host application.
+  # It makes data about available, enqueued, performing, and completed
+  # tasks accessible to the views so it can be displayed in the UI.
+  #
+  # @api private
+  class TasksController < ApplicationController
+    before_action :set_refresh, only: [:index, :show]
+
+    # Renders the maintenance_tasks/tasks page, displaying
+    # available tasks to users, grouped by category.
+    def index
+      @available_tasks = TaskData.available_tasks.group_by(&:category)
+    end
+
+    # Renders the page responsible for providing Task actions to users.
+    # Shows running and completed instances of the Task.
+    def show
+      @task = TaskData.find(params.fetch(:id))
+      @pagy, @previous_runs = pagy(@task.previous_runs)
+    end
+
+    # Runs a given Task and redirects to the Task page.
+    def run
+      task = Runner.new.run(name: params.fetch(:id))
+      redirect_to(task_path(task))
+    rescue ActiveRecord::RecordInvalid => error
+      redirect_to(task_path(error.record.task_name), alert: error.message)
+    rescue Runner::EnqueuingError => error
+      redirect_to(task_path(error.run.task_name), alert: error.message)
+    end
+
+    private
+
+    def set_refresh
+      @refresh = 3
+    end
+  end
+  private_constant :TasksController
+end