maintenance_tasks 2.7.1 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dac65eae0e9b5f8066a994408059eb42689792fed29f36321632ff42a804a7cd
-  data.tar.gz: a8df371985f28c8d97a2e8363f263e93fa40c2291370c63da8bfa115bad0e21a
+  metadata.gz: f05710c874610ef0698738773b70923d2e6a4ec4ae4b452ac768b6bf2e696d2c
+  data.tar.gz: 2ab31dae65aa383d5edbccee747199960f5167cd33833230c044fd00f0ad6cfc
 SHA512:
-  metadata.gz: 5144b9f8ab67ae9ea05b16c74178a96239cf22611627822e6ca00205c145e1767bc51015f796fd95dd40b973f3e5b6b1e1e67a950c72c628995602c631e0e49a
-  data.tar.gz: caeefe52b00431e3ba41297cc10f3dfb17c184b57237e74e6825f50b683be58431c079bf4921ac2529286a0b926fdbbe2ee6e61dc4350e3457d477ce18dc1ba1
+  metadata.gz: 8f0f7eee33cc6615f658f49ec9d74322f7952f2afa47b4b539dd0a49131cea10df15f072402d51d611bbfbf4d8d297ace54da1896ab457e54280bc17284641c9
+  data.tar.gz: af3992b2c6de8c8b70d840d8c06d6a8cb2646063a9b23222a1814bfc1cc7866a9745277aafe32ef8ee48627b7916e51c672c9321be87a49a5efd443f353722fc

data/README.md

@@ -156,6 +156,32 @@ module Maintenance
 end
 ```
 
+#### Customizing the Batch Size
+
+When processing records from an Active Record Relation, records are fetched in
+batches internally, and then each record is passed to the `#process` method.
+Maintenance Tasks will query the database to fetch records in batches of 100 by
+default, but the batch size can be modified using the `collection_batch_size` macro:
+
+```ruby
+# app/tasks/maintenance/update_posts_task.rb
+
+module Maintenance
+  class UpdatePostsTask < MaintenanceTasks::Task
+    # Fetch records in batches of 1000
+    collection_batch_size(1000)
+
+    def collection
+      Post.all
+    end
+
+    def process(post)
+      post.update!(content: "New content!")
+    end
+  end
+end
+```
+
 ### Creating a CSV Task
 
 You can also write a Task that iterates on a CSV file. Note that writing CSV
@@ -459,6 +485,23 @@ to run. Since arguments are specified in the user interface via text area
 inputs, it’s important to check that they conform to the format your Task
 expects, and to sanitize any inputs if necessary.
 
+#### Validating Task Parameters
+
+Task attributes can be validated using Active Model Validations. Attributes are
+validated before a Task is enqueued.
+
+If an attribute uses an inclusion validator with a supported `in:` option, the
+set of values will be used to populate a dropdown in the user interface. The
+following types are supported:
+
+* Arrays
+* Procs and lambdas that optionally accept the Task instance, and return an Array.
+* Callable objects that receive one argument, the Task instance, and return an Array.
+* Methods that return an Array, called on the Task instance.
+
+For enumerables that don't match the supported types, a text field will be
+rendered instead.
+
 ### Custom cursor columns to improve performance
 
 The [job-iteration gem][job-iteration], on which this gem depends, adds an
@@ -515,8 +558,8 @@ your application.
 
 Usage example:
 
- ```ruby
- ActiveSupport::Notifications.subscribe("succeeded.maintenance_tasks") do |*, payload|
+```ruby
+ActiveSupport::Notifications.subscribe("succeeded.maintenance_tasks") do |*, payload|
   task_name = payload[:task_name]
   arguments = payload[:arguments]
   metadata = payload[:metadata]
@@ -727,9 +770,9 @@ end
 ### Writing tests for a Task that uses a custom enumerator
 
 Tests for tasks that use custom enumerators need to instantiate the task class
-in order to call `#build_enumerator`. Once the task instance is set up, validate
-that `#build_enumerator` returns an enumerator yielding pairs of [item, cursor]
-as expected.
+in order to call `#enumerator_builder`. Once the task instance is set up,
+validate that `#enumerator_builder` returns an enumerator yielding pairs of
+`[item, cursor]` as expected.
 
 ```ruby
 # test/tasks/maintenance/custom_enumerating_task.rb
@@ -742,8 +785,8 @@ module Maintenance
       @task = CustomEnumeratingTask.new
     end
 
-    test "#build_enumerator returns enumerator yielding pairs of [item, cursor]" do
-      enum = @task.build_enumerator(cursor: 0)
+    test "#enumerator_builder returns enumerator yielding pairs of [item, cursor]" do
+      enum = @task.enumerator_builder(cursor: 0)
       expected_items = [:b, :c]
 
       assert_equal 2, enum.size

data/app/helpers/maintenance_tasks/tasks_helper.rb

@@ -102,8 +102,13 @@ module MaintenanceTasks
     end
 
     # Resolves values covered by the inclusion validator for a task attribute.
-    # Only Arrays are supported, option types such as:
-    # Procs, lambdas, symbols, and Range are not supported and return nil.
+    # Supported option types:
+    # - Arrays
+    # - Procs and lambdas that optionally accept the Task instance, and return an Array.
+    # - Callable objects that receive one argument, the Task instance, and return an Array.
+    # - Methods that return an Array, called on the Task instance.
+    #
+    # Other types are not supported and will return nil.
     #
     # Returned values are used to populate a dropdown list of options.
     #
@@ -111,20 +116,39 @@ module MaintenanceTasks
     # @param parameter_name [String] The parameter name.
     #
     # @return [Array] value of the resolved inclusion option.
-    def resolve_inclusion_value(task_class, parameter_name)
+    def resolve_inclusion_value(task, parameter_name)
+      task_class = task.class
       inclusion_validator = task_class.validators_on(parameter_name).find do |validator|
         validator.kind == :inclusion
       end
       return unless inclusion_validator
 
       in_option = inclusion_validator.options[:in] || inclusion_validator.options[:within]
-      in_option if in_option.is_a?(Array)
+      resolved_in_option = case in_option
+      when Proc
+        if in_option.arity == 0
+          in_option.call
+        else
+          in_option.call(task)
+        end
+      when Symbol
+        method = task.method(in_option)
+        method.call if method.arity.zero?
+      else
+        if in_option.respond_to?(:call)
+          in_option.call(task)
+        else
+          in_option
+        end
+      end
+
+      resolved_in_option if resolved_in_option.is_a?(Array)
     end
 
     # Return the appropriate field tag for the parameter, based on its type.
     # If the parameter has a `validates_inclusion_of` validator, return a dropdown list of options instead.
     def parameter_field(form_builder, parameter_name)
-      inclusion_values = resolve_inclusion_value(form_builder.object.class, parameter_name)
+      inclusion_values = resolve_inclusion_value(form_builder.object, parameter_name)
       return form_builder.select(parameter_name, inclusion_values, prompt: "Select a value") if inclusion_values
 
       case form_builder.object.class.attribute_types[parameter_name]

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

@@ -39,7 +39,9 @@ module MaintenanceTasks
       when :no_collection
         enumerator_builder.build_once_enumerator(cursor: nil)
       when ActiveRecord::Relation
-        enumerator_builder.active_record_on_records(collection, cursor: cursor, columns: @task.cursor_columns)
+        options = { cursor: cursor, columns: @task.cursor_columns }
+        options[:batch_size] = @task.active_record_enumerator_batch_size if @task.active_record_enumerator_batch_size
+        enumerator_builder.active_record_on_records(collection, **options)
       when ActiveRecord::Batches::BatchEnumerator
         if collection.start || collection.finish
           raise ArgumentError, <<~MSG.squish
@@ -164,6 +166,7 @@ module MaintenanceTasks
     end
 
     def on_error(error)
+      task_context = {}
       @ticker.persist if defined?(@ticker)
 
       if defined?(@run)
@@ -175,8 +178,6 @@ module MaintenanceTasks
           started_at: @run.started_at,
           ended_at: @run.ended_at,
         }
-      else
-        task_context = {}
       end
       errored_element = @errored_element if defined?(@errored_element)
     ensure

data/app/models/maintenance_tasks/run.rb

@@ -386,40 +386,20 @@ module MaintenanceTasks
       nil
     end
 
-    # Support iterating over ActiveModel::Errors in Rails 6.0 and Rails 6.1+.
-    # To be removed when Rails 6.0 is no longer supported.
-    if Rails::VERSION::STRING.match?(/^6.0/)
-      # Performs validation on the arguments to use for the Task. If the Task is
-      # invalid, the errors are added to the Run.
-      def validate_task_arguments
-        arguments_match_task_attributes if arguments.present?
-        if task.invalid?
-          error_messages = task.errors
-            .map { |attribute, message| "#{attribute.inspect} #{message}" }
-          errors.add(
-            :arguments,
-            "are invalid: #{error_messages.join("; ")}",
-          )
-        end
-      rescue Task::NotFoundError
-        nil
-      end
-    else
-      # Performs validation on the arguments to use for the Task. If the Task is
-      # invalid, the errors are added to the Run.
-      def validate_task_arguments
-        arguments_match_task_attributes if arguments.present?
-        if task.invalid?
-          error_messages = task.errors
-            .map { |error| "#{error.attribute.inspect} #{error.message}" }
-          errors.add(
-            :arguments,
-            "are invalid: #{error_messages.join("; ")}",
-          )
-        end
-      rescue Task::NotFoundError
-        nil
+    # Performs validation on the arguments to use for the Task. If the Task is
+    # invalid, the errors are added to the Run.
+    def validate_task_arguments
+      arguments_match_task_attributes if arguments.present?
+      if task.invalid?
+        error_messages = task.errors
+          .map { |error| "#{error.attribute.inspect} #{error.message}" }
+        errors.add(
+          :arguments,
+          "are invalid: #{error_messages.join("; ")}",
+        )
       end
+    rescue Task::NotFoundError
+      nil
     end
 
     # Fetches the attached ActiveStorage CSV file for the run. Checks first

data/app/models/maintenance_tasks/task.rb

@@ -18,6 +18,12 @@ module MaintenanceTasks
     # @api private
     class_attribute :throttle_conditions, default: []
 
+    # The number of active records to fetch in a single query when iterating
+    # over an Active Record collection task.
+    #
+    # @api private
+    class_attribute :active_record_enumerator_batch_size
+
     # @api private
     class_attribute :collection_builder_strategy, default: NullCollectionBuilder.new
 
@@ -138,6 +144,14 @@ module MaintenanceTasks
         self.throttle_conditions += [{ throttle_on: condition, backoff: backoff_as_proc }]
       end
 
+      # Limit the number of records that will be fetched in a single query when
+      # iterating over an Active Record collection task.
+      #
+      # @param size [Integer] the number of records to fetch in a single query.
+      def collection_batch_size(size)
+        self.active_record_enumerator_batch_size = size
+      end
+
       # Initialize a callback to run after the task starts.
       #
       # @param filter_list apply filters to the callback

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

@@ -44,7 +44,7 @@
 
     <h4 class="title is-4">Active Runs</h4>
 
-    <%= render @task.active_runs %>
+    <%= render partial: "maintenance_tasks/runs/run", collection: @task.active_runs %>
   <% end %>
 
   <% if @runs_page.records.present? %>
@@ -52,7 +52,7 @@
 
     <h4 class="title is-4">Previous Runs</h4>
 
-    <%= render @runs_page.records %>
+    <%= render partial: "maintenance_tasks/runs/run", collection: @runs_page.records %>
 
     <%= link_to "Next page", task_path(@task, cursor: @runs_page.next_cursor) unless @runs_page.last? %>
   <% end %>

data/lib/generators/maintenance_tasks/install_generator.rb

@@ -10,7 +10,7 @@ module MaintenanceTasks
 
     # Mounts the engine in the host application's config/routes.rb
     def mount_engine
-      route("mount MaintenanceTasks::Engine => \"/maintenance_tasks\"")
+      route("mount MaintenanceTasks::Engine, at: \"/maintenance_tasks\"")
     end
 
     # Copies engine migrations to host application and migrates the database

data/lib/patches/active_record_batch_enumerator.rb

@@ -1,23 +1,24 @@
 # frozen_string_literal: true
 
-# TODO: Remove this patch once all supported Rails versions include the changes
-# upstream - https://github.com/rails/rails/pull/42312/commits/a031a43d969c87542c4ee8d0d338d55fcbb53376
-module ActiveRecordBatchEnumerator
-  # The primary key value from which the BatchEnumerator starts,
-  #   inclusive of the value.
-  attr_reader :start
+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 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 relation from which the BatchEnumerator yields batches.
+    attr_reader :relation
 
-  # The size of the batches yielded by the BatchEnumerator.
-  def batch_size
-    @of
+    # The size of the batches yielded by the BatchEnumerator.
+    def batch_size
+      @of
+    end
   end
-end
 
-ActiveRecord::Batches::BatchEnumerator.include(ActiveRecordBatchEnumerator)
+  ActiveRecord::Batches::BatchEnumerator.include(ActiveRecordBatchEnumerator)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: maintenance_tasks
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.9.0
 platform: ruby
 authors:
 - Shopify Engineering
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-12 00:00:00.000000000 Z
+date: 2024-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -16,42 +16,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +108,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.6.2
-description: 
+description:
 email: gems@shopify.com
 executables:
 - maintenance_tasks
@@ -185,9 +185,9 @@ homepage: https://github.com/Shopify/maintenance_tasks
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.7.1
+  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.9.0
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -195,15 +195,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 3.5.23
+signing_key:
 specification_version: 4
 summary: A Rails engine for queuing and managing maintenance tasks
 test_files: []