maintenance_tasks 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '017924f32ef1d9cb9e8ef6b739e1dc7ab60695dce1ee03c9f9f14fcaa35dfdde'
-  data.tar.gz: 17d3d2e220dd8b3cc7270797398abe33e5c90e38a3d19b28a571cb61c94a567c
+  metadata.gz: 649f66cc11a303666134c75aad8575b81eb376e358f69312180e21a14528ce50
+  data.tar.gz: b564b46e647c467c5d93a6198ab112729623059cfe194d1115d095c8ab8d9953
 SHA512:
-  metadata.gz: '0942f2e8f1d23e1dc180a13deef7af7c198dcb348fdd62ed0c9107d4eded0a7908c0477c6e15c954658f4a99a41c5858fec4b02477d8deed4f72f44c4ae7cb5e'
-  data.tar.gz: 61c1d448e4c1eaf7a8076dc253d72de1d515b70ed4623b76a290b24dd4e6f0c76aff6fccde27619eceffc497ca750910aa9590363f2c3cbd2085a75a8838a18f
+  metadata.gz: f313350c5a80fa8840b23976eb7cde8776f825bc25a9b6a8fb7ce5d6f1abe8148d547ae7b2c1368a72caf980a2a12377e33b7c325e1447de3c0a0b0686d87a8d
+  data.tar.gz: '084950e7be06503e12d437294c784d02e2f0449c76db6297c5f95fcfd40845e4ce7e3354e16fbe12dd99b82554946f16fbc3415c047c17109aab1303c6b81b9b'

data/LICENSE.md

@@ -0,0 +1,18 @@
+Copyright 2020-present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -2,34 +2,6 @@
 
 A Rails engine for queuing and managing maintenance tasks.
 
-## Table of Contents
-
-* [Demo](#demo)
-* [Installation](#installation)
-  * [Active Job Dependency](#active-job-dependency)
-* [Usage](#usage)
-  * [Creating a Task](#creating-a-task)
-  * [Creating a CSV Task](#creating-a-csv-task)
-  * [Considerations when writing Tasks](#considerations-when-writing-tasks)
-  * [Writing tests for a Task](#writing-tests-for-a-task)
-  * [Writing tests for a CSV Task](#writing-tests-for-a-csv-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)
-
-## Demo
-
-Watch this demo video to see the gem in action:
-
 [![Link to demo video](static/demo.png)](https://www.youtube.com/watch?v=BTuvTQxlFzs)
 
 ## Installation
@@ -140,6 +112,46 @@ title,content
 My Title,Hello World!
 ```
 
+### Throttling
+
+Maintenance Tasks often modify a lot of data and can be taxing on your database.
+The gem provides a throttling mechanism that can be used to throttle a Task when
+a given condition is met. If a Task is throttled, it will be interrupted and
+retried after a backoff period has passed. The default backoff is 30 seconds.
+Specify the throttle condition as a block:
+
+```ruby
+# app/tasks/maintenance/update_posts_throttled_task.rb
+module Maintenance
+  class UpdatePostsThrottledTask < MaintenanceTasks::Task
+    throttle_on(backoff: 1.minute) do
+      DatabaseStatus.unhealthy?
+    end
+
+    def collection
+      Post.all
+    end
+
+    def count
+      collection.count
+    end
+
+    def process(post)
+      post.update!(content: "New content added on #{Time.now.utc}")
+    end
+  end
+end
+```
+
+Note that it's up to you to define a throttling condition that makes sense for
+your app. Shopify implements `DatabaseStatus.healthy?` to check various MySQL
+metrics such as replication lag, DB threads, whether DB writes are available, 
+etc.
+
+Tasks can define multiple throttle conditions. Throttle conditions are inherited
+by descendants, and new conditions will be appended without impacting existing
+conditions.
+
 ### Considerations when writing Tasks
 
 MaintenanceTasks relies on the queue adapter configured for your application to
@@ -338,12 +350,15 @@ end
 
 The error handler should be a lambda that accepts three arguments:
 
-* `error`: The object containing the exception that was raised.
+* `error`: The exception that was raised.
 * `task_context`: A hash with additional information about the Task and the
   error:
   * `task_name`: The name of the Task that errored
   * `started_at`: The time the Task started
   * `ended_at`: The time the Task errored
+  Note that `task_context` may be empty if the Task produced an error before any
+  context could be gathered (for example, if deserializing the job to process
+  your Task failed).
 * `errored_element`: The element, if any, that was being processed when the
   Task raised an exception. If you would like to pass this object to your
   exception monitoring service, make sure you **sanitize the object** to avoid
@@ -400,6 +415,36 @@ MaintenanceTasks.ticker_delay = 2.seconds
 
 If no value is specified, it will default to 1 second.
 
+#### Customizing which Active Storage service to use
+
+The Active Storage framework in Rails 6.1 and up supports multiple storage
+services per environment. To specify which service to use,
+`MaintenanceTasks.active_storage_service` can be configured with the service's
+key, as specified in your application's `config/storage.yml`:
+
+```yaml
+# config/storage.yml
+user_data:
+  service: GCS
+  credentials: <%= Rails.root.join("path/to/user/data/keyfile.json") %>
+  project: "my-project"
+  bucket: "user-data-bucket"
+
+internal:
+  service: GCS
+  credentials: <%= Rails.root.join("path/to/internal/keyfile.json") %>
+  project: "my-project"
+  bucket: "internal-bucket"
+```
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.active_storage_service = :internal
+```
+
+There is no need to configure this option if your application uses only one
+storage service per environment.
+
 ## Upgrading
 
 Use bundler to check for and upgrade to newer versions. After installing a new
@@ -419,15 +464,28 @@ pull requests. You can find the contribution guidelines on
 
 [contributing]: https://github.com/Shopify/maintenance_tasks/blob/main/.github/CONTRIBUTING.md
 
+### Dependabot updates
+
+Whenever Dependabot creates a PR for a gem bump, check out the branch locally
+and run `bin/update-gemfile <gem>` to ensure all the gemfiles have the gem
+updated consistently.
+
 ## Releasing new versions
 
+Updates should be added to the latest draft release on GitHub as Pull Requests
+are merged.
+
+Once a release is ready, follow these steps:
+
 * Update `spec.version` in `maintenance_tasks.gemspec`.
-* Run `bundle install` to bump the `Gemfile.lock` version of the gem.
+* Run `bin/gemfile-update install` to bump the version in all the lockfiles.
 * 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>.
+* Ensure the release has documented all changes and publish it.
+* Create a new [draft release on GitHub][release] with the title 'Upcoming
+  Release'. The tag version can be left blank. This will be the starting point
+  for documenting changes related to the next release.
 
 [release]: https://help.github.com/articles/creating-releases/
 [shipit]: https://shipit.shopify.io/shopify/maintenance_tasks/rubygems

data/app/controllers/maintenance_tasks/application_controller.rb

@@ -5,9 +5,7 @@ module MaintenanceTasks
   #
   # Can be extended to add different authentication and authorization code.
   class ApplicationController < ActionController::Base
-    include Pagy::Backend
-
-    BULMA_CDN = 'https://cdn.jsdelivr.net'
+    BULMA_CDN = "https://cdn.jsdelivr.net"
 
     content_security_policy do |policy|
       policy.style_src(BULMA_CDN)
@@ -17,7 +15,7 @@ module MaintenanceTasks
     before_action do
       request.content_security_policy_nonce_generator ||=
         ->(_request) { SecureRandom.base64(16) }
-      request.content_security_policy_nonce_directives = ['style-src']
+      request.content_security_policy_nonce_directives = ["style-src"]
     end
 
     protect_from_forgery with: :exception

data/app/controllers/maintenance_tasks/tasks_controller.rb

@@ -20,7 +20,7 @@ module MaintenanceTasks
     def show
       @task = TaskData.find(params.fetch(:id))
       set_refresh if @task.last_run&.active?
-      @pagy, @previous_runs = pagy(@task.previous_runs)
+      @runs_page = RunsPage.new(@task.previous_runs, params[:cursor])
     end
 
     # Runs a given Task and redirects to the Task page.

data/app/helpers/maintenance_tasks/application_helper.rb

@@ -4,17 +4,6 @@ module MaintenanceTasks
   #
   # @api private
   module ApplicationHelper
-    include Pagy::Frontend
-
-    # Renders pagination for the page, if there is more than one page present.
-    #
-    # @param pagy [Pagy] the pagy instance containing pagination details,
-    #   including the number of pages the results are spread across.
-    # @return [String] the HTML to render for pagination.
-    def pagination(pagy)
-      raw(pagy_bulma_nav(pagy)) if pagy.pages > 1
-    end
-
     # Renders a time element with the given datetime, worded as relative to the
     # current time.
     #
@@ -24,8 +13,8 @@ module MaintenanceTasks
     # @param datetime [ActiveSupport::TimeWithZone] the time to be presented.
     # @return [String] the HTML to render with the relative datetime in words.
     def time_ago(datetime)
-      time_tag(datetime, title: datetime.utc.iso8601, class: 'is-clickable') do
-        time_ago_in_words(datetime) + ' ago'
+      time_tag(datetime, title: datetime.utc.iso8601, class: "is-clickable") do
+        time_ago_in_words(datetime) + " ago"
       end
     end
   end

data/app/helpers/maintenance_tasks/tasks_helper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'ripper'
+require "ripper"
 
 module MaintenanceTasks
   # Helpers for formatting data in the maintenance_tasks views.
@@ -8,16 +8,16 @@ module MaintenanceTasks
   # @api private
   module TasksHelper
     STATUS_COLOURS = {
-      'new' => ['is-primary'],
-      'enqueued' => ['is-primary is-light'],
-      'running' => ['is-info'],
-      'interrupted' => ['is-info', 'is-light'],
-      'pausing' => ['is-warning', 'is-light'],
-      'paused' => ['is-warning'],
-      'succeeded' => ['is-success'],
-      'cancelling' => ['is-light'],
-      'cancelled' => ['is-dark'],
-      'errored' => ['is-danger'],
+      "new" => ["is-primary"],
+      "enqueued" => ["is-primary is-light"],
+      "running" => ["is-info"],
+      "interrupted" => ["is-info", "is-light"],
+      "pausing" => ["is-warning", "is-light"],
+      "paused" => ["is-warning"],
+      "succeeded" => ["is-success"],
+      "cancelling" => ["is-light"],
+      "cancelled" => ["is-dark"],
+      "errored" => ["is-danger"],
     }
 
     # Formats a run backtrace.
@@ -44,12 +44,13 @@ module MaintenanceTasks
 
       progress = Progress.new(run)
 
-      tag.progress(
+      progress_bar = tag.progress(
         value: progress.value,
         max: progress.max,
-        title: progress.title,
-        class: ['progress'] + STATUS_COLOURS.fetch(run.status)
+        class: ["progress"] + STATUS_COLOURS.fetch(run.status)
       )
+      progress_text = tag.p(tag.i(progress.text))
+      tag.div(progress_bar + progress_text, class: "block")
     end
 
     # Renders a span with a Run's status, with the corresponding tag class
@@ -59,7 +60,7 @@ module MaintenanceTasks
     # @return [String] the span element containing the status, with the
     #   appropriate tag class attached.
     def status_tag(status)
-      tag.span(status.capitalize, class: ['tag'] + STATUS_COLOURS.fetch(status))
+      tag.span(status.capitalize, class: ["tag"] + STATUS_COLOURS.fetch(status))
     end
 
     # Returns the distance between now and the Run's expected completion time,
@@ -100,7 +101,7 @@ module MaintenanceTasks
         when :on_nl, :on_sp, :on_ignored_nl
           content
         else
-          tag.span(content, class: type.to_s.sub('on_', 'ruby-').dasherize)
+          tag.span(content, class: type.to_s.sub("on_", "ruby-").dasherize)
         end
       end
       safe_join(tokens)

data/app/jobs/concerns/maintenance_tasks/task_job_concern.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+module MaintenanceTasks
+  # Concern that holds the behaviour of the job that runs the tasks. It is
+  # included in {TaskJob} and if MaintenanceTasks.job is overridden, it must be
+  # included in the job.
+  module TaskJobConcern
+    extend ActiveSupport::Concern
+    include JobIteration::Iteration
+
+    included do
+      before_perform(:before_perform)
+
+      on_start(:on_start)
+      on_complete(:on_complete)
+      on_shutdown(:on_shutdown)
+
+      after_perform(:after_perform)
+
+      rescue_from StandardError, with: :on_error
+    end
+
+    class_methods do
+      # Overrides ActiveJob::Exceptions.retry_on to declare it unsupported.
+      # The use of rescue_from prevents retry_on from being usable.
+      def retry_on(*, **)
+        raise NotImplementedError, "retry_on is not supported"
+      end
+    end
+
+    private
+
+    def build_enumerator(_run, cursor:)
+      cursor ||= @run.cursor
+      collection = @task.collection
+
+      collection_enum = case collection
+      when ActiveRecord::Relation
+        enumerator_builder.active_record_on_records(collection, cursor: cursor)
+      when Array
+        enumerator_builder.build_array_enumerator(collection, cursor: cursor)
+      when CSV
+        JobIteration::CsvEnumerator.new(collection).rows(cursor: cursor)
+      else
+        raise ArgumentError, "#{@task.class.name}#collection must be either "\
+          "an Active Record Relation, Array, or CSV."
+      end
+
+      @task.throttle_conditions.reduce(collection_enum) do |enum, condition|
+        enumerator_builder.build_throttle_enumerator(enum, **condition)
+      end
+    end
+
+    # Performs task iteration logic for the current input returned by the
+    # enumerator.
+    #
+    # @param input [Object] the current element from the enumerator.
+    # @param _run [Run] the current Run, passed as an argument by Job Iteration.
+    def each_iteration(input, _run)
+      throw(:abort, :skip_complete_callbacks) if @run.stopping?
+      task_iteration(input)
+      @ticker.tick
+      @run.reload_status
+    end
+
+    def task_iteration(input)
+      @task.process(input)
+    rescue => error
+      @errored_element = input
+      raise error
+    end
+
+    def before_perform
+      @run = arguments.first
+      @task = Task.named(@run.task_name).new
+      if @task.respond_to?(:csv_content=)
+        @task.csv_content = @run.csv_file.download
+      end
+      @run.job_id = job_id
+
+      @run.running! unless @run.stopping?
+
+      @ticker = Ticker.new(MaintenanceTasks.ticker_delay) do |ticks, duration|
+        @run.persist_progress(ticks, duration)
+      end
+    end
+
+    def on_start
+      @run.update!(started_at: Time.now, tick_total: @task.count)
+    end
+
+    def on_complete
+      @run.status = :succeeded
+      @run.ended_at = Time.now
+    end
+
+    def on_shutdown
+      if @run.cancelling?
+        @run.status = :cancelled
+        @run.ended_at = Time.now
+      else
+        @run.status = @run.pausing? ? :paused : :interrupted
+        @run.cursor = cursor_position
+      end
+
+      @ticker.persist
+    end
+
+    # We are reopening a private part of Job Iteration's API here, so we should
+    # ensure the method is still defined upstream. This way, in the case where
+    # the method changes upstream, we catch it at load time instead of at
+    # runtime while calling `super`.
+    unless JobIteration::Iteration
+        .private_method_defined?(:reenqueue_iteration_job)
+      error_message = <<~HEREDOC
+        JobIteration::Iteration#reenqueue_iteration_job is expected to be
+        defined. Upgrading the maintenance_tasks gem should solve this problem.
+      HEREDOC
+      raise error_message
+    end
+    def reenqueue_iteration_job(should_ignore: true)
+      super() unless should_ignore
+      @reenqueue_iteration_job = true
+    end
+
+    def after_perform
+      @run.save!
+      if defined?(@reenqueue_iteration_job) && @reenqueue_iteration_job
+        reenqueue_iteration_job(should_ignore: false)
+      end
+    end
+
+    def on_error(error)
+      @ticker.persist if defined?(@ticker)
+
+      if defined?(@run)
+        @run.persist_error(error)
+
+        task_context = {
+          task_name: @run.task_name,
+          started_at: @run.started_at,
+          ended_at: @run.ended_at,
+        }
+      else
+        task_context = {}
+      end
+      errored_element = @errored_element if defined?(@errored_element)
+      MaintenanceTasks.error_handler.call(error, task_context, errored_element)
+    end
+  end
+end