maintenance_tasks 2.8.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b984293788834b153823e857dad5020b8cca1902037c97fd158401c1da3cfee3
-  data.tar.gz: 0c079b820fbfd3d7e26e7c19585ac8b41199de92f7a71e671a63c7db46b60d06
+  metadata.gz: 347d742ae5f71881fe2d54f7fff83b4129144eb72af60c2364a8069fc41412fe
+  data.tar.gz: 20ff959d1c2db4a003883955ef938414a462f16fa843d8f4ec526ff3333a0609
 SHA512:
-  metadata.gz: f43e5c6535246bf7259bb21cfd1eb3f48f356a9f1f2e83fea19096cdff8610a601d4ea96b623d63bbecbaa593d1022a34fd16210896f83852f64c3e3bf003b41
-  data.tar.gz: a506d5e89ec233e60a59c428801d8e2e79a57f6604f8ab9cf97882b71bf69f4304f7d1fa53ac33ecd4ab5bb76f9de3774cbf9d1bfdd7cdff52af1849379b7e6d
+  metadata.gz: 7f9e56bd030e2a6918d7e8e136108d6097cbcdaa8b73ebb9683072878f8789cb0b7da1b67c122d7dddf97553ca3dcb37b4e1af7670cbdf931825ec965cbbf9af
+  data.tar.gz: 384ec37a77b25d689ff46f965fd6cddd4ddc7669f520a99db808edc76c290c21ed8925b5d791839dd0d61738da6b944267fa65535b91ebd4ee6d8913293bb824

data/README.md

@@ -90,6 +90,13 @@ take a look at the [Active Job documentation][active-job-docs].
 [async-adapter]: https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/AsyncAdapter.html
 [active-job-docs]: https://guides.rubyonrails.org/active_job_basics.html#setting-the-backend
 
+### Action Controller & Action View Dependency
+
+The Maintenance Tasks framework relies on Action Controller and Action View to
+render the UI. If you're using Rails in API-only mode, see [Using Maintenance
+Tasks in API-only
+applications](#using-maintenance-tasks-in-api-only-applications).
+
 ### Autoloading
 
 The Maintenance Tasks framework does not support autoloading in `:classic` mode.
@@ -485,6 +492,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
@@ -541,8 +565,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]
@@ -871,6 +895,42 @@ a Task can be in:
 * **succeeded**: A Task that finished successfully.
 * **errored**: A Task that encountered an unhandled exception while performing.
 
+### Using Maintenance Tasks in API-only applications
+
+The Maintenance Tasks engine uses Rails sessions for flash messages and storing
+the CSRF token. For the engine to work in an API-only Rails application, you
+need to add a [session middleware][] and the `ActionDispatch::Flash`
+middleware. The engine also defines a strict [Content Security Policy][], make
+sure to include `ActionDispatch::ContentSecurityPolicy::Middleware` in your
+app's middleware stack to ensure the CSP is delivered to the user's browser.
+
+[session middleware]: https://guides.rubyonrails.org/api_app.html#using-session-middlewares
+[Content Security Policy]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+
+Configuring Rails applications is beyond the scope of this documentation, but
+one way to do this is to add these lines to your application configuration:
+
+```ruby
+# config/application.rb
+module YourApplication
+  class Application < Rails::Application
+    # ...
+    config.api_only = true
+
+    config.middleware.insert_before ::Rack::Head, ::ActionDispatch::Flash
+    config.middleware.insert_before ::Rack::Head, ::ActionDispatch::ContentSecurityPolicy::Middleware
+    config.session_store :cookie_store, key: "_#{railtie_name.chomp("_application")}_session", secure: true
+    config.middleware.insert_before ::ActionDispatch::Flash, config.session_store, config.session_options
+    config.middleware.insert_before config.session_store, ActionDispatch::Cookies
+  end
+end
+```
+
+You can read more in the [Using Rails for API-only Applications][rails api] Rails
+guide.
+
+[rails api]: https://guides.rubyonrails.org/api_app.html
+
 ### How Maintenance Tasks runs a Task
 
 Maintenance tasks can be running for a long time, and the purpose of the gem is
@@ -1128,7 +1188,7 @@ The value for `MaintenanceTasks.stuck_task_duration` must be an
 `ActiveSupport::Duration`. If no value is specified, it will default to 5
 minutes.
 
-### Metadata
+#### Metadata
 
 `MaintenanceTasks.metadata` can be configured to specify a proc from which to
 get extra information about the run. Since this proc will be ran in the context

data/app/controllers/maintenance_tasks/runs_controller.rb

@@ -6,6 +6,7 @@ module MaintenanceTasks
   #
   # @api private
   class RunsController < ApplicationController
+    helper TasksHelper
     before_action :set_run, except: :create
 
     # Creates a Run for a given Task and redirects to the Task page.
@@ -19,7 +20,9 @@ module MaintenanceTasks
       )
       redirect_to(task_path(task))
     rescue ActiveRecord::RecordInvalid => error
-      redirect_to(task_path(error.record.task_name), alert: error.message)
+      flash.now.alert = error.message
+      @task = TaskDataShow.prepare(error.record.task_name, arguments: error.record.arguments)
+      render(template: "maintenance_tasks/tasks/show")
     rescue ActiveRecord::ValueTooLong => error
       task_name = params.fetch(:task_id)
       redirect_to(task_path(task_name), alert: error.message)

data/app/controllers/maintenance_tasks/tasks_controller.rb

@@ -18,14 +18,11 @@ module MaintenanceTasks
     # Renders the page responsible for providing Task actions to users.
     # Shows running and completed instances of the Task.
     def show
-      task_name = params.fetch(:id)
-      @task = TaskDataShow.new(task_name)
-      @task.active_runs.load
-      set_refresh if @task.active_runs.any?
-      @runs_page = RunsPage.new(@task.completed_runs, params[:cursor])
-      if @task.active_runs.none? && @runs_page.records.none?
-        Task.named(task_name)
-      end
+      @task = TaskDataShow.prepare(
+        params.fetch(:id),
+        runs_cursor: params[:cursor],
+        arguments: params.except(:id, :controller, :action).permit!,
+      )
     end
 
     private

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/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/runs_page.rb

@@ -21,6 +21,9 @@ module MaintenanceTasks
       @cursor = cursor
     end
 
+    # @return [String, nil] the cursor for the page of Runs.
+    attr_reader :cursor
+
     # Returns the records for a Page, taking into account the cursor if one is
     # present. Limits the number of records to 20.
     #

data/app/models/maintenance_tasks/task_data_show.rb

@@ -11,17 +11,39 @@ module MaintenanceTasks
   #
   # @api private
   class TaskDataShow
-    # Initializes a Task Data with a name and optionally a related run.
+    # Initializes a Task Data with a name.
     #
     # @param name [String] the name of the Task subclass.
-    def initialize(name)
+    # @param runs_cursor [String, nil] the cursor for the runs page.
+    # @param arguments [Hash, nil] the Task arguments.
+    def initialize(name, runs_cursor: nil, arguments: nil)
       @name = name
+      @arguments = arguments
+      @runs_page = RunsPage.new(completed_runs, runs_cursor)
+    end
+
+    class << self
+      # Prepares a Task Data from a task name.
+      #
+      # @param name [String] the name of the Task subclass.
+      # @param runs_cursor [String, nil] the cursor for the runs page.
+      # @param arguments [Hash, nil] the Task arguments.
+      # @raise [Task::NotFoundError] if the Task doesn't have runs (for the given cursor) and doesn't exist.
+      def prepare(name, runs_cursor: nil, arguments: nil)
+        new(name, runs_cursor:, arguments:)
+          .load_active_runs
+          .ensure_task_exists
+      end
     end
 
     # @return [String] the name of the Task.
     attr_reader :name
     alias_method :to_s, :name
 
+    # @return [RunsPage] the current page of completed runs, based on the cursor
+    #   passed in initialize.
+    attr_reader :runs_page
+
     # The Task's source code.
     #
     # @return [String] the contents of the file which defines the Task.
@@ -38,6 +60,11 @@ module MaintenanceTasks
       File.read(file)
     end
 
+    # @return [Boolean] whether the task data needs to be refreshed.
+    def refresh?
+      active_runs.any?
+    end
+
     # Returns the set of currently active Run records associated with the Task.
     #
     # @return [ActiveRecord::Relation<MaintenanceTasks::Run>] the relation of
@@ -79,12 +106,34 @@ module MaintenanceTasks
       end
     end
 
-    # @return [MaintenanceTasks::Task, nil] an instance of the Task class.
+    # @return [MaintenanceTasks::Task] an instance of the Task class.
     # @return [nil] if the Task file was deleted.
     def new
       return if deleted?
 
-      MaintenanceTasks::Task.named(name).new
+      task = MaintenanceTasks::Task.named(name).new
+      begin
+        task.assign_attributes(@arguments) if @arguments
+      rescue ActiveModel::UnknownAttributeError
+        # nothing to do
+      end
+      task
+    end
+
+    # Preloads the records from the active_runs ActiveRecord::Relation
+    # @return [self]
+    def load_active_runs
+      active_runs.load
+      self
+    end
+
+    # @raise [Task::NotFoundError] if the Task doesn't have Runs (for the given cursor) and doesn't exist.
+    # @return [self]
+    def ensure_task_exists
+      if active_runs.none? && runs_page.records.none?
+        Task.named(name)
+      end
+      self
     end
 
     private

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

@@ -23,23 +23,23 @@
 
   <div class="buttons">
     <% if run.paused? %>
-      <%= button_to 'Resume', resume_task_run_path(@task, run), method: :put, class: 'button is-primary', disabled: @task.deleted? %>
-      <%= button_to 'Cancel', cancel_task_run_path(@task, run), method: :put, class: 'button is-danger' %>
+      <%= button_to 'Resume', resume_task_run_path(@task, run), class: 'button is-primary', disabled: @task.deleted? %>
+      <%= button_to 'Cancel', cancel_task_run_path(@task, run), class: 'button is-danger' %>
     <% elsif run.errored? %>
-      <%= button_to 'Resume', resume_task_run_path(@task, run), method: :put, class: 'button is-primary', disabled: @task.deleted? %>
+      <%= button_to 'Resume', resume_task_run_path(@task, run), class: 'button is-primary', disabled: @task.deleted? %>
     <% elsif run.cancelling? %>
       <% if run.stuck? %>
-        <%= button_to 'Cancel', cancel_task_run_path(@task, run), method: :put, class: 'button is-danger', disabled: @task.deleted? %>
+        <%= button_to 'Cancel', cancel_task_run_path(@task, run), class: 'button is-danger', disabled: @task.deleted? %>
       <% end %>
     <% elsif run.pausing? %>
-      <%= button_to 'Pausing', pause_task_run_path(@task, run), method: :put, class: 'button is-warning', disabled: true %>
-      <%= button_to 'Cancel', cancel_task_run_path(@task, run), method: :put, class: 'button is-danger' %>
+      <%= button_to 'Pausing', pause_task_run_path(@task, run), class: 'button is-warning', disabled: true %>
+      <%= button_to 'Cancel', cancel_task_run_path(@task, run), class: 'button is-danger' %>
       <% if run.stuck? %>
-        <%= button_to 'Force pause', pause_task_run_path(@task, run), method: :put, class: 'button is-danger', disabled: @task.deleted? %>
+        <%= button_to 'Force pause', pause_task_run_path(@task, run), class: 'button is-danger', disabled: @task.deleted? %>
       <% end %>
     <% elsif run.active? %>
-      <%= button_to 'Pause', pause_task_run_path(@task, run), method: :put, class: 'button is-warning', disabled: @task.deleted? %>
-      <%= button_to 'Cancel', cancel_task_run_path(@task, run), method: :put, class: 'button is-danger' %>
+      <%= button_to 'Pause', pause_task_run_path(@task, run), class: 'button is-warning', disabled: @task.deleted? %>
+      <%= button_to 'Cancel', cancel_task_run_path(@task, run), class: 'button is-danger' %>
     <% end%>
   </div>
 </div>

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

@@ -38,7 +38,7 @@
   <pre><code><%= highlight_code(code) %></code></pre>
 <% end %>
 
-<%= tag.div(data: { refresh: (defined?(@refresh) && @refresh) || "" }) do %>
+<%= tag.div(data: { refresh: @task.refresh? || "" }) do %>
   <% if @task.active_runs.any? %>
     <hr/>
 
@@ -47,13 +47,13 @@
     <%= render partial: "maintenance_tasks/runs/run", collection: @task.active_runs %>
   <% end %>
 
-  <% if @runs_page.records.present? %>
+  <% if @task.runs_page.records.present? %>
     <hr/>
 
     <h4 class="title is-4">Previous Runs</h4>
 
-    <%= render partial: "maintenance_tasks/runs/run", collection: @runs_page.records %>
+    <%= render partial: "maintenance_tasks/runs/run", collection: @task.runs_page.records %>
 
-    <%= link_to "Next page", task_path(@task, cursor: @runs_page.next_cursor) unless @runs_page.last? %>
+    <%= link_to "Next page", task_path(@task, cursor: @task.runs_page.next_cursor) unless @task.runs_page.last? %>
   <% end %>
 <% end %>

data/config/routes.rb

@@ -4,11 +4,12 @@ MaintenanceTasks::Engine.routes.draw do
   resources :tasks, only: [:index, :show], format: false do
     resources :runs, only: [:create], format: false do
       member do
-        put "pause"
-        put "cancel"
-        put "resume"
+        post "pause"
+        post "cancel"
+        post "resume"
       end
     end
+    get :runs, to: redirect("tasks/%{task_id}")
   end
 
   root to: "tasks#index"

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.8.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Shopify Engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-29 00:00:00.000000000 Z
+date: 2024-12-03 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
@@ -185,7 +185,7 @@ homepage: https://github.com/Shopify/maintenance_tasks
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.8.0
+  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.10.0
   allowed_push_host: https://rubygems.org
 post_install_message:
 rdoc_options: []
@@ -195,14 +195,14 @@ 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.17
+rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: A Rails engine for queuing and managing maintenance tasks