maintenance_tasks 2.14.0 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ceffb83ecb318ecf0edd66c78f55d4dd51c6528d4faf72d6e7ca66efa83db02
-  data.tar.gz: 360bc77f347ac909ed96a30495f965cc908cc5fc7956f1edfa8c3b2aba385607
+  metadata.gz: f74ab248a9b57875d5e7b47234598a46fbc37033fb7d96c95e26b03c55d83793
+  data.tar.gz: cf2322966430eee4215131e9885aba07591d2e6f5081f6ab1683188ae5be8e80
 SHA512:
-  metadata.gz: b46d6c5afcb297a2be58c9e218cad173b4abf65d50784574ac5fb4afdbaeaf83fc9add501e0817c85190b6b0e4299988b9a3ca87d28a83147e912e10f8d98cfd
-  data.tar.gz: 5b4ecaeff775b36f909dfe80d50df4834d642ba1fbf09d9668d11d47d011a2bb1a8302b612a07d8bec9f0b4d14ffba2d33f53f6e46b9999b6b74df4c41f9571b
+  metadata.gz: 22bde697fa7b38899ff5dc4c7fc353776a29766f479a3fac4f988b921aaf62bd58534f55a2c9caa1b9bf227ddbbef249c1d521b863afc5ab59527ad32528a4e9
+  data.tar.gz: 1f51f3e1ead4af15d02886b950562e0a103baf055839e1e5e6f661b2dfd29d47626859fbd350e8d311293c88d4b4f59189ae70e32a8dbca54559d75ce5fafaa5

data/README.md

@@ -391,7 +391,10 @@ This method should return an `Enumerator`, yielding pairs of `[item, cursor]`.
 Maintenance Tasks takes care of persisting the current cursor position and will
 provide it as the `cursor` argument if your task is interrupted or resumed. The
 `cursor` is stored as a `String`, so your custom enumerator should handle
-serializing/deserializing the value if required.
+serializing/deserializing the value if required. Note that if you've enabled
+[JSON cursors](#json-cursors), the cursor will be automatically serialized and
+deserialized. However for this to work, the cursor values must be
+JSON-serializable.
 
 ```ruby
 # app/tasks/maintenance/custom_enumerator_task.rb
@@ -561,6 +564,9 @@ control the cursor columns, through the `cursor_columns` method in the
 the query is ordered by the primary key. If cursor columns values change during
 an iteration, records may be skipped or yielded multiple times.
 
+Note that in order to use this feature, you must first enable
+[JSON cursors](#json-cursors).
+
 ```ruby
 module Maintenance
   class UpdatePostsTask < MaintenanceTasks::Task
@@ -1317,6 +1323,46 @@ MaintenanceTasks.metadata = ->() do
 end
 ```
 
+#### JSON Cursors
+
+By default, cursor values are persisted in the database as a string. If you
+want to iterate over collections that require multiple values to keep track of
+the position, you can enable JSON cursors. This will cause the cursor to be
+serialized as JSON when persisted, and deserialized when read back.
+
+This is especially useful when you need to iterate over a model that uses a
+composite primary key.
+
+Be advised that this feature comes with a few caveats:
+
+1. Cursor values must be capable of being serialized to JSON and parsed from
+   JSON. If they are not, errors will occur during task execution.
+2. If a cursor contains a value that loses precision when serialized, it may
+   lead to unexpected behaviour.
+3. This feature utilizes a string column to store the JSON data. If your
+   database has a hard limit on how big a string value can be, be mindful that
+   certain cursor structures could result in a value that could exceed that
+   limit and cause issues.
+
+A new column was added to discern JSON cursors from plain string cursors. Make
+sure you have run the latest database migrations provided by the gem before
+enabling this feature. See [upgrading](#upgrading) for more information.
+
+```ruby
+# config/initializers/maintenance_tasks.rb
+MaintenanceTasks.serialize_cursors_as_json = true
+```
+
+#### Configure staleness threshold
+
+To specify a staleness threshold date interval which will mark task runs as stale, you can
+configure `MaintenanceTasks.task_staleness_threshold`. Tasks that have last run
+successfully after this threshold will be marked stale.
+
+The value for `MaintenanceTasks.task_staleness_threshold` must be an
+`ActiveSupport::Duration`. If no value is specified, it will default to 30 days. This can be disabled
+by setting `MaintenanceTasks.task_staleness_threshold` to `false`.
+
 ## Upgrading
 
 Use bundler to check for and upgrade to newer versions. After installing a new

data/app/helpers/maintenance_tasks/tasks_helper.rb

@@ -62,7 +62,7 @@ module MaintenanceTasks
     def status_tag(status)
       tag.span(
         status.capitalize,
-        class: ["tag", "has-text-weight-medium", "pr-2", "mr-4"] + STATUS_COLOURS.fetch(status),
+        class: ["tag", "has-text-weight-medium", "px-2", "mx-4"] + STATUS_COLOURS.fetch(status),
       )
     end
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module MaintenanceTasks
   # Concern that holds the behaviour of the job that runs the tasks. It is
   # included in {TaskJob} and if MaintenanceTasks.job is overridden, it must be
@@ -30,8 +32,18 @@ module MaintenanceTasks
 
     private
 
+    def serialized_cursor_position
+      cursor_position && @run.cursor_is_json? ? cursor_position.to_json : cursor_position
+    end
+
+    def deserialized_run_cursor
+      return JSON.parse(@run.cursor) if @run.cursor && @run.cursor_is_json?
+
+      @run.cursor
+    end
+
     def build_enumerator(_run, cursor:)
-      cursor ||= @run.cursor
+      cursor ||= deserialized_run_cursor
       self.cursor_position = cursor
       enumerator_builder = self.enumerator_builder
       @collection_enum = @task.enumerator_builder(cursor: cursor)
@@ -140,7 +152,7 @@ module MaintenanceTasks
 
     def on_shutdown
       @run.job_shutdown
-      @run.cursor = cursor_position
+      @run.cursor = serialized_cursor_position
       @ticker.persist
     end
 
@@ -177,7 +189,7 @@ module MaintenanceTasks
       @ticker.persist if defined?(@ticker)
 
       if defined?(@run)
-        @run.cursor = cursor_position
+        @run.cursor = serialized_cursor_position
         @run.persist_error(error)
 
         task_context = {

data/app/models/concerns/maintenance_tasks/run_concern.rb

@@ -447,6 +447,41 @@ module MaintenanceTasks
       argument_filter.filter(arguments)
     end
 
+    # @return [Boolean]
+    #   True when the cursor value should be treated as serialized JSON.
+    def cursor_is_json?
+      MaintenanceTasks.serialize_cursors_as_json && cursor_is_json
+    end
+
+    # Configures the Run to use the appropriate type of cursor encoding based
+    # on `MaintenanceTasks.serialize_cursors_as_json`.
+    #
+    # This method exists to gracefully handle the situation where the
+    # `cursor_is_json` column does not exist. As long as the application is not
+    # configured to use JSON cursors (the default), the Run will continue to
+    # function even without the new column.
+    #
+    # * When `MaintenanceTasks.serialize_cursors_as_json` is false, this method
+    #   no-ops.
+    # * When `MaintenanceTasks.serialize_cursors_as_json` is true, this method
+    #   will mutate the Run so that `cursor_is_json` is set to true.
+    def configure_cursor_encoding!
+      return unless MaintenanceTasks.serialize_cursors_as_json
+
+      self.cursor_is_json = true
+    end
+
+    # Returns whether the run is stale based on the staleness threshold.
+    #
+    # @return [Boolean]
+    def stale?
+      return false unless MaintenanceTasks.task_staleness_threshold.present?
+      return false unless succeeded?
+      return false unless ended_at.present?
+
+      ended_at < MaintenanceTasks.task_staleness_threshold.ago
+    end
+
     private
 
     def instrument_status_change

data/app/models/maintenance_tasks/runner.rb

@@ -41,6 +41,8 @@ module MaintenanceTasks
     #   to a value being too long for the column type.
     def run(name:, csv_file: nil, arguments: {}, run_model: Run, metadata: nil)
       run = run_model.new(task_name: name, arguments: arguments, metadata: metadata)
+      run.configure_cursor_encoding!
+
       if csv_file
         run.csv_file.attach(csv_file)
         run.csv_file.filename = filename(name)

data/app/models/maintenance_tasks/task_data_index.rb

@@ -64,6 +64,15 @@ module MaintenanceTasks
 
     alias_method :to_s, :name
 
+    # Delegates to the related run's stale? method when available.
+    #
+    # @return [Boolean] whether the related run is stale.
+    def stale?
+      return false unless related_run.present?
+
+      related_run.stale?
+    end
+
     # Returns the status of the latest active or completed Run, if present.
     # If the Task does not have any Runs, the Task status is `new`.
     #

data/app/views/layouts/maintenance_tasks/_navbar.html.erb

@@ -1,4 +1,4 @@
-<nav class="navbar" role="navigation" aria-label="main navigation">
+<nav class="navbar" role="navigation" aria-label="Main navigation">
   <div class="navbar-brand">
     <%= link_to 'Maintenance Tasks', root_path, class: 'navbar-item is-size-4 has-text-weight-semibold has-text-danger' %>
   </div>

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

@@ -46,6 +46,6 @@
     <% elsif run.active? %>
       <%= 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%>
+    <% end %>
   </div>
 </details>

data/app/views/maintenance_tasks/runs/info/_errored.html.erb

@@ -1,5 +1,5 @@
 <p>
-  Ran for <%= time_running_in_words run  %> until an error happened
+  Ran for <%= time_running_in_words run %> until an error happened
   <%= time_ago run.ended_at %>.
 </p>
 

data/app/views/maintenance_tasks/runs/info/_paused.html.erb

@@ -1,5 +1,5 @@
 <p>
-  Ran for <%= time_running_in_words run  %> until paused,
+  Ran for <%= time_running_in_words run %> until paused,
   <% if (time_to_completion = run.time_to_completion) %>
     <%= distance_of_time_in_words(time_to_completion) %> remaining.
   <% else %>

data/app/views/maintenance_tasks/runs/info/_running.html.erb

@@ -1,3 +1,3 @@
 <% if (time_to_completion = run.time_to_completion) %>
-  <p>Running for <%= time_running_in_words(run)  %>. <%= distance_of_time_in_words(time_to_completion).capitalize %> remaining.</p>
+  <p>Running for <%= time_running_in_words(run) %>. <%= distance_of_time_in_words(time_to_completion).capitalize %> remaining.</p>
 <% end %>

data/app/views/maintenance_tasks/runs/info/_succeeded.html.erb

@@ -2,4 +2,3 @@
   Ran for <%= time_running_in_words run %>,
   finished <%= time_ago run.ended_at %>.
 </p>
-

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

@@ -1,10 +1,22 @@
 <div class="cell box">
-  <h3 class="title is-5 has-text-weight-medium">
+  <h3 class="title is-5 has-text-weight-medium is-flex is-align-items-center">
     <%= link_to task, task_path(task) %>
     <%= status_tag(task.status) %>
   </h3>
 
   <% if (run = task.related_run) %>
+    <% if task.stale? %>
+      <div class="content is-size-7 is-flex is-align-items-center has-text-warning">
+        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="icon is-small">
+          <path stroke-linecap="round" stroke-linejoin="round" d="m11.25 11.25.041-.02a.75.75 0 0 1 1.063.852l-.708 2.836a.75.75 0 0 0 1.063.853l.041-.021M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9-3.75h.008v.008H12V8.25Z" />
+        </svg>
+
+        <p class="ml-1">
+          This task last ran <%= MaintenanceTasks.task_staleness_threshold.inspect %> ago. Consider removing it as it may be stale.
+        </p>
+      </div>
+    <% end %>
+
     <h5 class="title is-5 has-text-weight-medium">
       <%= time_tag run.created_at, title: run.created_at.utc %>
     </h5>

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

@@ -14,9 +14,9 @@
     <% end %>
     <% if new_tasks = @available_tasks[:new] %>
       <h3 class="title is-4 has-text-weight-bold">New Tasks</h3>
-	  <div class="grid is-col-min-20">
+      <div class="grid is-col-min-20">
         <%= render partial: 'task', collection: new_tasks %>
-	  </div>
+      </div>
     <% end %>
     <% if completed_tasks = @available_tasks[:completed] %>
       <h3 class="title is-4 has-text-weight-bold">Completed Tasks</h3>

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

@@ -44,7 +44,7 @@
 
 <%= tag.div(data: { refresh: @task.refresh? || "" }) do %>
   <% if @task.active_runs.any? %>
-    <hr/>
+    <hr>
 
     <h4 class="title is-4">Active Runs</h4>
 
@@ -52,7 +52,7 @@
   <% end %>
 
   <% if @task.runs_page.records.present? %>
-    <hr/>
+    <hr>
 
     <h4 class="title is-5 has-text-weight-bold">Previous Runs</h4>
 

data/db/migrate/20251128180556_add_cursor_is_json_flag_to_runs.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddCursorIsJsonFlagToRuns < ActiveRecord::Migration[7.1]
+  def change
+    add_column(:maintenance_tasks_runs, :cursor_is_json, :boolean, default: false, null: false)
+  end
+end

data/lib/maintenance_tasks.rb

@@ -109,6 +109,42 @@ module MaintenanceTasks
   #  @return [Boolean] whether to report unexpected errors as handled (true) or unhandled (false).
   mattr_accessor :report_errors_as_handled, default: true
 
+  # @!attribute serialize_cursors_as_json
+  #  @scope class
+  #  Controls whether or not cursor values are stored as JSON in the database.
+  #  Defaults to false.
+  #
+  #  Storing cursors as JSON enables more complex cursor structures. For
+  #  example, with JSON cursors a task can iterate over collections using
+  #  multiple fields or columns to track progress. This is particularly useful
+  #  for iterating over models with composite primary keys.
+  #
+  #  Be advised that this feature comes with a few caveats:
+  #
+  #  1. Cursor values must be capable of being serialized to JSON and parsed
+  #     from JSON. If they are not, errors will occur during task execution.
+  #  2. If a cursor contains a value that loses precision when serialized, it
+  #     may lead to unexpected behaviour.
+  #  3. This feature utilizes a string column to store the JSON data. If your
+  #     database has a hard limit on how big a string value can be, be mindful
+  #     that certain cursor structures could result in a value that could exceed
+  #     that limit and cause issues.
+  #
+  #  A new column was added to discern JSON cursors from plain string cursors.
+  #  Make sure you have run the latest database migrations provided by the gem
+  #  before enabling this feature.
+  #
+  #  @return [Boolean] whether or not to store cursor values as JSON.
+  mattr_accessor :serialize_cursors_as_json, default: false
+
+  # @!attribute task_staleness_threshold
+  #  @scope class
+  #  The threshold after which a task is considered stale.
+  #  Defaults to 30 days. Can be disabled by setting this to `false`.
+  #
+  #  @return [ActiveSupport::Duration, false] time interval after which a task is considered stale.
+  mattr_accessor :task_staleness_threshold, default: 30.days
+
   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 " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: maintenance_tasks
 version: !ruby/object:Gem::Version
-  version: 2.14.0
+  version: 2.15.0
 platform: ruby
 authors:
 - Shopify Engineering
@@ -167,6 +167,7 @@ files:
 - db/migrate/20220706101937_change_runs_tick_columns_to_bigints.rb
 - db/migrate/20220713131925_add_index_on_task_name_and_status_to_runs.rb
 - db/migrate/20230622035229_add_metadata_to_runs.rb
+- db/migrate/20251128180556_add_cursor_is_json_flag_to_runs.rb
 - exe/maintenance_tasks
 - lib/generators/maintenance_tasks/install_generator.rb
 - lib/generators/maintenance_tasks/task_generator.rb
@@ -183,7 +184,7 @@ homepage: https://github.com/Shopify/maintenance_tasks
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.14.0
+  source_code_uri: https://github.com/Shopify/maintenance_tasks/tree/v2.15.0
   allowed_push_host: https://rubygems.org
 rdoc_options: []
 require_paths:
@@ -199,7 +200,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Rails engine for queuing and managing maintenance tasks
 test_files: []