maintenance_tasks 2.9.0 → 2.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f05710c874610ef0698738773b70923d2e6a4ec4ae4b452ac768b6bf2e696d2c
-  data.tar.gz: 2ab31dae65aa383d5edbccee747199960f5167cd33833230c044fd00f0ad6cfc
+  metadata.gz: 4b660fdfcef27420bf9b08ddc50c9cfac5ff0977c4435b54ecd2b468a3e4fde8
+  data.tar.gz: 30bac0da63839406dc623d07c85904b7a727d3af5c177736cbd72ea828ca41c9
 SHA512:
-  metadata.gz: 8f0f7eee33cc6615f658f49ec9d74322f7952f2afa47b4b539dd0a49131cea10df15f072402d51d611bbfbf4d8d297ace54da1896ab457e54280bc17284641c9
-  data.tar.gz: af3992b2c6de8c8b70d840d8c06d6a8cb2646063a9b23222a1814bfc1cc7866a9745277aafe32ef8ee48627b7916e51c672c9321be87a49a5efd443f353722fc
+  metadata.gz: 071dafa23a89bd949e40f10ef199ae892d5ae81ca2ad1e15e6c7de0260dafbd55f735d67c310f5de7ef499991982eb3bad69fce4024f8f8761e4357ac3fdc42b
+  data.tar.gz: 77265626bdeafaa6486a3843846d519168be0712399ebe3cd7a4ecbb42f5888f208f566346d6d628643ee0dcf06ff1c4b914f2ab3ef9ec73f60b9444ef3f05c0

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.
@@ -888,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
@@ -1145,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/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
 

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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: maintenance_tasks
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.10.1
 platform: ruby
+original_platform: ''
 authors:
 - Shopify Engineering
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2024-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -108,7 +108,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.6.2
-description:
 email: gems@shopify.com
 executables:
 - maintenance_tasks
@@ -185,9 +184,8 @@ homepage: https://github.com/Shopify/maintenance_tasks
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.9.0
+  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.10.1
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -202,8 +200,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.1
 specification_version: 4
 summary: A Rails engine for queuing and managing maintenance tasks
 test_files: []