Module: MaintenanceTasks::RunConcern Private

Extended by:
ActiveSupport::Concern
Included in:
Run
Defined in:
app/models/concerns/maintenance_tasks/run_concern.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Concern that holds the behavior of a maintenance task run. It is included in Run.

Instance Method Summary collapse

Instance Method Details

#active? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the Run is active, which is defined as having a status of enqueued, running, pausing, cancelling, paused or interrupted.

Returns:

  • (Boolean) —

    whether the Run is active.



231
232
233
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 231

def active?
  ACTIVE_STATUSES.include?(status.to_sym)
end

#cancel ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Cancels a Run.

If the Run is paused, it will transition directly to cancelled, since the Task is not being performed. In this case, the ended_at timestamp will be updated.

If the Run is not paused, the Run will transition to cancelling.

If the Run is already cancelling, and has last been updated more than 5 minutes ago, it will transition to cancelled, and the ended_at timestamp will be updated.



319
320
321
322
323
324
325
326
327
328
329
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 319

def cancel
  with_stale_object_retry do
    if paused? || stuck?
      self.status = :cancelled
      self.ended_at = Time.now
      persist_transition
    else
      cancelling!
    end
  end
end

#complete ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Handles the completion of a Run, setting a status of succeeded and the ended_at timestamp.



303
304
305
306
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 303

def complete
  self.status = :succeeded
  self.ended_at = Time.now
end

#completed? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the Run is completed, which is defined as having a status of succeeded, cancelled, or errored.

Returns:

  • (Boolean) —

    whether the Run is completed.



222
223
224
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 222

def completed?
  COMPLETED_STATUSES.include?(status.to_sym)
end

#configure_cursor_encoding! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



468
469
470
471
472
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 468

def configure_cursor_encoding!
  return unless MaintenanceTasks.serialize_cursors_as_json

  self.cursor_is_json = true
end

#csv_attachment_presence ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs validation on the presence of a :csv_file attachment. A Run for a Task that uses CsvCollection must have an attached :csv_file to be valid. Conversely, a Run for a Task that doesn’t use CsvCollection should not have an attachment to be valid. The appropriate error is added if the Run does not meet the above criteria.



371
372
373
374
375
376
377
378
379
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 371

def csv_attachment_presence
  if Task.named(task_name).has_csv_content? && !csv_file.attached?
    errors.add(:csv_file, "must be attached to CSV Task.")
  elsif !Task.named(task_name).has_csv_content? && csv_file.present?
    errors.add(:csv_file, "should not be attached to non-CSV Task.")
  end
rescue Task::NotFoundError
  nil
end

#csv_content_type ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs validation on the content type of the :csv_file attachment. A Run for a Task that uses CsvCollection must have a present :csv_file and a content type of “text/csv” to be valid. The appropriate error is added if the Run does not meet the above criteria.



385
386
387
388
389
390
391
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 385

def csv_content_type
  if csv_file.present? && csv_file.content_type != "text/csv"
    errors.add(:csv_file, "must be a CSV")
  end
rescue Task::NotFoundError
  nil
end

#csv_file ⇒ ActiveStorage::Attached::One

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Fetches the attached ActiveStorage CSV file for the run. Checks first whether the ActiveStorage::Attachment table exists so that we are compatible with apps that are not using ActiveStorage.

Returns:

  • (ActiveStorage::Attached::One) —

    the attached CSV file



414
415
416
417
418
419
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 414

def csv_file
  return unless defined?(ActiveStorage)
  return unless ActiveStorage::Attachment.table_exists?

  super
end

#cursor_is_json? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns True when the cursor value should be treated as serialized JSON.

Returns:

  • (Boolean) —

    True when the cursor value should be treated as serialized JSON.



452
453
454
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 452

def cursor_is_json?
  MaintenanceTasks.serialize_cursors_as_json && cursor_is_json
end

#job_shutdown ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Handles transitioning the status on a Run when the job shuts down.



289
290
291
292
293
294
295
296
297
298
299
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 289

def job_shutdown
  if cancelling?
    self.status = :cancelled
    self.ended_at = Time.now
  elsif pausing?
    self.status = :paused
  elsif cancelled?
  else
    self.status = :interrupted
  end
end

#masked_arguments ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns all the run arguments with sensitive information masked.

Returns:

  • (Hash) —

    The masked arguments.



444
445
446
447
448
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 444

def masked_arguments
  return unless arguments.present?

  argument_filter.filter(arguments)
end

#pause ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Marks a Run as pausing.

If the Run has been stuck on pausing for more than 5 minutes, it forces the transition to paused. The ended_at timestamp will be updated.

Rescues and retries status transition if an ActiveRecord::StaleObjectError is encountered.



338
339
340
341
342
343
344
345
346
347
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 338

def pause
  with_stale_object_retry do
    if stuck?
      self.status = :paused
      persist_transition
    else
      pausing!
    end
  end
end

#persist_error(error) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Marks the run as errored and persists the error data.

Parameters:

  • error (StandardError) —

    the Error being persisted.



153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 153

def persist_error(error)
  with_stale_object_retry do
    self.started_at ||= Time.now
    update!(
      status: :errored,
      error_class: truncate(:error_class, error.class.name),
      error_message: truncate(:error_message, error.message),
      backtrace: MaintenanceTasks.backtrace_cleaner.clean(error.backtrace),
      ended_at: Time.now,
    )
  end
  run_error_callback
end

#persist_progress(number_of_ticks, duration) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Increments tick_count by number_of_ticks and time_running by duration, both directly in the DB. The attribute values are not set in the current instance, you need to reload the record.

Parameters:

  • number_of_ticks (Integer) —

    number of ticks to add to tick_count.

  • duration (Float) —

    the time in seconds that elapsed since the last increment of ticks.



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 136

def persist_progress(number_of_ticks, duration)
  self.class.update_counters(
    id,
    tick_count: number_of_ticks,
    time_running: duration,
    touch: true,
  )
  if locking_enabled?
    locking_column = self.class.locking_column
    self[locking_column] += 1
    clear_attribute_change(locking_column)
  end
end

#persist_transition ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Saves the run, persisting the transition of its status, and all other changes to the object.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 101

def persist_transition
  retry_count = 0
  begin
    save!
  rescue ActiveRecord::StaleObjectError
    if retry_count < MAX_RETRIES
      sleep(DELAYS_PER_ATTEMPT[retry_count])
      retry_count += 1

      success = succeeded?
      reload_status
      if success
        self.status = :succeeded
      else
        job_shutdown
      end

      retry
    else
      raise
    end
  end

  callback = CALLBACKS_TRANSITION[status]
  run_task_callbacks(callback) if callback
end

#reload_status ⇒ MaintenanceTasks::Run

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Refreshes the status and lock version attributes on the Active Record object, and ensures ActiveModel::Dirty doesn’t mark the object as changed.

This allows us to get the Run’s most up-to-date status without needing to reload the entire record.

Returns:



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 174

def reload_status
  columns_to_reload = if locking_enabled?
    [:status, self.class.locking_column]
  else
    [:status]
  end
  updated_status, updated_lock_version = self.class.uncached do
    self.class.where(id: id).pluck(*columns_to_reload).first
  end

  self.status = updated_status
  if updated_lock_version
    self[self.class.locking_column] = updated_lock_version
  end
  clear_attribute_changes(columns_to_reload)
  self
end

#running ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Marks a Run as running.

If the run is stopping already, it will not transition to running. Rescues and retries status transition if an ActiveRecord::StaleObjectError is encountered.



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 255

def running
  if locking_enabled?
    with_stale_object_retry do
      running! unless stopping?
    end
  else
    # Preserve swap-and-replace solution for data races until users
    # run migration to upgrade to optimistic locking solution
    return if stopping?

    updated = self.class.where(id: id).where.not(status: STOPPING_STATUSES)
      .update_all(status: :running, updated_at: Time.now) > 0
    if updated
      self.status = :running
      clear_attribute_changes([:status])
    else
      reload_status
    end
  end
end

#stale? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the run is stale based on the staleness threshold.

Returns:

  • (Boolean) 


477
478
479
480
481
482
483
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 477

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

#start(count) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Starts a Run, setting its started_at timestamp and tick_total.

Parameters:

  • count (Integer) —

    the total iterations to be performed, as specified by the Task.



280
281
282
283
284
285
286
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 280

def start(count)
  with_stale_object_retry do
    update!(started_at: Time.now, tick_total: count)
  end

  task.run_callbacks(:start)
end

#started? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the Run has been started, which is indicated by the started_at timestamp being present.

Returns:

  • (Boolean) —

    whether the Run was started.



214
215
216
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 214

def started?
  started_at.present?
end

#stopped? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the Run is stopped, which is defined as having a status of paused, succeeded, cancelled, or errored.

Returns:

  • (Boolean) —

    whether the Run is stopped.



206
207
208
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 206

def stopped?
  completed? || paused?
end

#stopping? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the Run is stopping, which is defined as having a status of pausing or cancelling. The status of cancelled is also considered stopping since a Run can be cancelled while its job still exists in the queue, and we want to handle it the same way as a cancelling run.

Returns:

  • (Boolean) —

    whether the Run is stopping.



198
199
200
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 198

def stopping?
  STOPPING_STATUSES.include?(status.to_sym)
end

#stuck? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether a Run is stuck, which is defined as having a status of cancelling or pausing, and not having been updated in the last 5 minutes.

Returns:

  • (Boolean) —

    whether the Run is stuck.



353
354
355
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 353

def stuck?
  (cancelling? || pausing?) && updated_at <= MaintenanceTasks.stuck_task_duration.ago
end

#task ⇒ Task

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a Task instance for this Run. Assigns any attributes to the Task based on the Run’s parameters. Note that the Task instance is not supplied with :csv_content yet if it’s a CSV Task. This is done in the job, since downloading the CSV file can take some time.

Returns:

  • (Task) —

    a Task instance.



427
428
429
430
431
432
433
434
435
436
437
438
439
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 427

def task
  @task ||= begin
    task = Task.named(task_name).new
    if task.attribute_names.any? && arguments.present?
      task.assign_attributes(arguments)
    end

    task.metadata = metadata
    task
  rescue ActiveModel::UnknownAttributeError
    task
  end
end

#task_name_belongs_to_a_valid_task ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs validation on the task_name attribute. A Run must be associated with a valid Task to be valid. In order to confirm that, the Task is looked up by name.



360
361
362
363
364
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 360

def task_name_belongs_to_a_valid_task
  Task.named(task_name)
rescue Task::NotFoundError
  errors.add(:task_name, "must be the name of an existing Task.")
end

#time_to_completion ⇒ ActiveSupport::Duration

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the duration left for the Run to finish based on the number of ticks left and the average time needed to process a tick. Returns nil if the Run is completed, or if tick_count or tick_total is zero.

Returns:

  • (ActiveSupport::Duration) —

    the estimated duration left for the Run to finish.



241
242
243
244
245
246
247
248
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 241

def time_to_completion
  return if completed? || tick_count == 0 || tick_total.to_i == 0

  processed_per_second = (tick_count.to_f / time_running)
  ticks_left = (tick_total - tick_count)
  seconds_to_finished = ticks_left / processed_per_second
  seconds_to_finished.seconds
end

#validate_task_arguments ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs validation on the arguments to use for the Task. If the Task is invalid, the errors are added to the Run.



395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'app/models/concerns/maintenance_tasks/run_concern.rb', line 395

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