maintenance_tasks 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f05710c874610ef0698738773b70923d2e6a4ec4ae4b452ac768b6bf2e696d2c
-  data.tar.gz: 2ab31dae65aa383d5edbccee747199960f5167cd33833230c044fd00f0ad6cfc
+  metadata.gz: 347d742ae5f71881fe2d54f7fff83b4129144eb72af60c2364a8069fc41412fe
+  data.tar.gz: 20ff959d1c2db4a003883955ef938414a462f16fa843d8f4ec526ff3333a0609
 SHA512:
-  metadata.gz: 8f0f7eee33cc6615f658f49ec9d74322f7952f2afa47b4b539dd0a49131cea10df15f072402d51d611bbfbf4d8d297ace54da1896ab457e54280bc17284641c9
-  data.tar.gz: af3992b2c6de8c8b70d840d8c06d6a8cb2646063a9b23222a1814bfc1cc7866a9745277aafe32ef8ee48627b7916e51c672c9321be87a49a5efd443f353722fc
+  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.
@@ -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/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.0
 platform: ruby
 authors:
 - Shopify Engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2024-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -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.9.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: []