maintenance_tasks 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 347d742ae5f71881fe2d54f7fff83b4129144eb72af60c2364a8069fc41412fe
-  data.tar.gz: 20ff959d1c2db4a003883955ef938414a462f16fa843d8f4ec526ff3333a0609
+  metadata.gz: 4ac2fd148131a277d37ddc609173b8549d01d3e6a9f78786cf729bd5da4f65b0
+  data.tar.gz: a2db7dfe8a9b0a958d943f88305fbe6d8988fd171901c49cd688070d8125124e
 SHA512:
-  metadata.gz: 7f9e56bd030e2a6918d7e8e136108d6097cbcdaa8b73ebb9683072878f8789cb0b7da1b67c122d7dddf97553ca3dcb37b4e1af7670cbdf931825ec965cbbf9af
-  data.tar.gz: 384ec37a77b25d689ff46f965fd6cddd4ddc7669f520a99db808edc76c290c21ed8925b5d791839dd0d61738da6b944267fa65535b91ebd4ee6d8913293bb824
+  metadata.gz: c8e4c707d55ca479cca9f1592cc65359cc460d70cfd1e4ea4b2caf7c0a92617b4f243feb83c9f3657cb81a76691ed660c91bdafba73634b819a0fa44a719a2c8
+  data.tar.gz: 0efab90ffbdea1131f72de57443c8ed01fc30550d88c3ebbfe77b8e48a37c27dec8ec2ed7591ebdf9ea463e82ff4df7fcb649b111076a7302e10fce5720eb437

data/README.md

@@ -74,9 +74,9 @@ 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.
 
-In case you use an exception reporting service (e.g. Bugsnag) you might want to
-define an error handler. See [Customizing the error
-handler](#customizing-the-error-handler) for more information.
+This gem uses the [Rails Error Reporter](https://guides.rubyonrails.org/error_reporting.html) to report errors. If you are using a bug
+tracking service you may want to subscribe to the reporter. See [Reporting Errors](#reporting-errors)
+for more information.
 
 ### Active Job Dependency
 
@@ -988,44 +988,58 @@ If you are stuck in `pausing` and wish to preserve your tasks's position
 There are a few configurable options for the gem. Custom configurations should
 be placed in a `maintenance_tasks.rb` initializer.
 
-#### Customizing the error handler
+#### Reporting errors
 
 Exceptions raised while a Task is performing are rescued and information about
 the error is persisted and visible in the UI.
 
-If you want to integrate with an exception monitoring service (e.g. Bugsnag),
-you can define an error handler:
+Errors are also sent to the `Rails.error.reporter`, which can be configured by your
+application. See the [Error Reporting in Rails Applications](https://guides.rubyonrails.org/error_reporting.html) guide for more details.
 
-```ruby
-# config/initializers/maintenance_tasks.rb
-
-MaintenanceTasks.error_handler = ->(error, task_context, _errored_element) do
-  Bugsnag.notify(error) do |notification|
-    notification.add_metadata(:task, task_context)
-  end
-end
-```
-
-The error handler should be a lambda that accepts three arguments:
+Reports to the error reporter will contain the following data:
 
 * `error`: The exception that was raised.
-* `task_context`: A hash with additional information about the Task and the
+* `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
+  * `run_id`: The id of the errored Task run
+  * `tick_count`: The tick count at the time of the error
+  * `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 leaking
+    sensitive data and **convert it to a format** that is compatible with your bug
+    tracker.
+* `source`: This will be `maintenance_tasks`
+
+Note that `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).
+
+#### Reporting errors during iteration
+
+By default, errors raised during task iteration will be raised to the application
+and iteration will stop. However, you may want to handle some errors and continue
+iteration. `MaintenanceTasks::Task.report_on` can be used to rescue certain
+exceptions and report them to the Rails error reporter.
+
+```ruby
+class MyTask < MaintenanceTasks::Task
+  report_on(MyException)
+end
+```
+
+`MaintenanceTasks::Task` also includes `ActiveSupport::Rescuable` which you can use
+to implement custom error handling.
 
-  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 leaking
-  sensitive data and **convert it to a format** that is compatible with your bug
-  tracker. For example, Bugsnag only sends the id and class name of Active
-  Record objects in order to protect sensitive data. CSV rows, on the other
-  hand, are converted to strings and passed raw to Bugsnag, so make sure to
-  filter any personal data from these objects before adding them to a report.
+```ruby
+class MyTask < MaintenanceTasks::Task
+  rescue_from(MyException) do |exception|
+    handle(exception)
+  end
+end
+```
 
 #### Customizing the maintenance tasks module
 

data/app/helpers/maintenance_tasks/application_helper.rb

@@ -14,7 +14,7 @@ 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_tag(datetime, title: datetime.utc, class: "is-clickable") do
         time_ago_in_words(datetime) + " ago"
       end
     end

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

@@ -33,6 +33,7 @@ module MaintenanceTasks
     def build_enumerator(_run, cursor:)
       cursor ||= @run.cursor
       self.cursor_position = cursor
+      enumerator_builder = self.enumerator_builder
       @collection_enum = @task.enumerator_builder(cursor: cursor)
 
       @collection_enum ||= case (collection = @task.collection)
@@ -75,6 +76,9 @@ module MaintenanceTasks
         MSG
       end
 
+      unless @collection_enum.is_a?(JobIteration.enumerator_builder::Wrapper)
+        @collection_enum = enumerator_builder.wrap(enumerator_builder, @collection_enum)
+      end
       throttle_enumerator(@collection_enum)
     end
 
@@ -108,7 +112,7 @@ module MaintenanceTasks
       end
     rescue => error
       @errored_element = input
-      raise error
+      raise error unless @task.rescue_with_handler(error)
     end
 
     def before_perform
@@ -177,11 +181,20 @@ module MaintenanceTasks
           task_name: @run.task_name,
           started_at: @run.started_at,
           ended_at: @run.ended_at,
+          run_id: @run.id,
+          tick_count: @run.tick_count,
         }
       end
-      errored_element = @errored_element if defined?(@errored_element)
+      task_context[:errored_element] = @errored_element if defined?(@errored_element)
     ensure
-      MaintenanceTasks.error_handler.call(error, task_context, errored_element)
+      if MaintenanceTasks.instance_variable_get(:@error_handler)
+        errored_element = task_context.delete(:errored_element)
+        MaintenanceTasks.error_handler.call(error, task_context.except(:run_id, :tick_count), errored_element)
+      elsif Rails.gem_version >= Gem::Version.new("7.1")
+        Rails.error.report(error, context: task_context, source: "maintenance-tasks")
+      else
+        Rails.error.report(error, handled: true, context: task_context)
+      end
     end
   end
 end

data/app/models/maintenance_tasks/run.rb

@@ -33,11 +33,7 @@ module MaintenanceTasks
     ]
     COMPLETED_STATUSES = [:succeeded, :errored, :cancelled]
 
-    if Rails.gem_version >= Gem::Version.new("7.0.alpha")
-      enum :status, STATUSES.to_h { |status| [status, status.to_s] }
-    else
-      enum status: STATUSES.to_h { |status| [status, status.to_s] }
-    end
+    enum :status, STATUSES.to_h { |status| [status, status.to_s] }
 
     after_save :instrument_status_change
 

data/app/models/maintenance_tasks/task.rb

@@ -8,6 +8,7 @@ module MaintenanceTasks
     include ActiveModel::Attributes
     include ActiveModel::AttributeAssignment
     include ActiveModel::Validations
+    include ActiveSupport::Rescuable
 
     class NotFoundError < NameError; end
 
@@ -200,6 +201,20 @@ module MaintenanceTasks
         set_callback(:error, :after, *filter_list, &block)
       end
 
+      # Rescue listed exceptions during an iteration and report them to the error reporter, then
+      # continue iteration.
+      #
+      # @param exceptions list of exceptions to rescue and report
+      def report_on(*exceptions)
+        rescue_from(*exceptions) do |exception|
+          if Rails.gem_version >= Gem::Version.new("7.1")
+            Rails.error.report(exception, source: "maintenance_tasks")
+          else
+            Rails.error.report(exception, handled: true)
+          end
+        end
+      end
+
       private
 
       def load_constants

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

@@ -1,6 +1,6 @@
 <div class="box">
   <h5 class="title is-5">
-    <%= time_tag run.created_at, title: run.created_at.utc.iso8601 %>
+    <%= time_tag run.created_at, title: run.created_at.utc %>
     <%= status_tag run.status %>
     <span class="is-pulled-right" title="Run ID">#<%= run.id %></span>
   </h5>

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

@@ -6,7 +6,7 @@
 
   <% if (run = task.related_run) %>
     <h5 class="title is-5">
-      <%= time_tag run.created_at, title: run.created_at %>
+      <%= time_tag run.created_at, title: run.created_at.utc %>
     </h5>
 
     <%= progress run %>

data/lib/maintenance_tasks/engine.rb

@@ -21,6 +21,12 @@ module MaintenanceTasks
       MaintenanceTasks.backtrace_cleaner = Rails.backtrace_cleaner
     end
 
+    if Rails.gem_version >= Gem::Version.new("7.1")
+      initializer "maintenance_tasks.deprecator" do
+        Rails.application.deprecators[:maintenance_tasks] = MaintenanceTasks.deprecator
+      end
+    end
+
     config.to_prepare do
       _ = TaskJobConcern # load this for JobIteration compatibility check
     end

data/lib/maintenance_tasks.rb

@@ -8,8 +8,6 @@ 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.
@@ -63,16 +61,6 @@ module MaintenanceTasks
   #     use when cleaning a Run's backtrace.
   mattr_accessor :backtrace_cleaner
 
-  # @!attribute error_handler
-  #   @scope class
-  #
-  #   The callback to perform when an error occurs in the Task.  See the
-  #   {file:README#label-Customizing+the+error+handler} for details.
-  #
-  #   @return [Proc] the callback to perform when an error occurs in the Task.
-  mattr_accessor :error_handler, default:
-    ->(_error, _task_context, _errored_element) {}
-
   # @!attribute parent_controller
   #   @scope class
   #
@@ -96,4 +84,30 @@ module MaintenanceTasks
   #
   #  @return [ActiveSupport::Duration] the threshold in seconds after which a task is considered stuck.
   mattr_accessor :stuck_task_duration, default: 5.minutes
+
+  class << self
+    DEPRECATION_MESSAGE = "MaintenanceTasks.error_handler is deprecated and will be removed in the 3.0 release. " \
+      "Instead, reports will be sent to the Rails error reporter. Do not set a handler and subscribe" \
+      "to the error reporter instead."
+    private_constant :DEPRECATION_MESSAGE
+
+    # @deprecated
+    def error_handler
+      deprecator.warn(DEPRECATION_MESSAGE)
+
+      @error_handler
+    end
+
+    # @deprecated
+    def error_handler=(proc)
+      deprecator.warn(DEPRECATION_MESSAGE)
+
+      @error_handler = proc
+    end
+
+    # @api-private
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("3.0", "MaintenanceTasks")
+    end
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: maintenance_tasks
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Shopify Engineering
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-03 00:00:00.000000000 Z
+date: 2025-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -16,42 +15,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +85,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +107,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.6.2
-description:
 email: gems@shopify.com
 executables:
 - maintenance_tasks
@@ -179,15 +177,13 @@ files:
 - lib/maintenance_tasks.rb
 - lib/maintenance_tasks/cli.rb
 - lib/maintenance_tasks/engine.rb
-- lib/patches/active_record_batch_enumerator.rb
 - lib/tasks/maintenance_tasks_tasks.rake
 homepage: https://github.com/Shopify/maintenance_tasks
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.10.0
+  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.11.0
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -202,8 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: A Rails engine for queuing and managing maintenance tasks
 test_files: []

data/lib/patches/active_record_batch_enumerator.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-if Rails.gem_version < Gem::Version.new("7.0")
-  # Add attribute readers.
-  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)
-end