Class: Smplkit::Jobs::RetryPolicy

Inherits:
Object
  • Object
show all
Defined in:
lib/smplkit/jobs/models.rb

Overview

A named, reusable automatic-retry policy.

Active-record style: instantiate via client.jobs.retry_policies.new(…), mutate fields directly, and call #save to persist or #delete to remove. Reference a saved policy from a job’s Job#retry_policy (see JobsClient#new_recurring_job and Job#set_retry_policy). Retry policies are account-global — never environment-scoped.

A policy decides whether and how a failed run is retried. A job that references nothing uses the built-in “Default” policy, which never retries.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client = nil, id:, name:, max_retries:, backoff:, delay_seconds:, max_delay_seconds: nil, retry_on_timeout: false, retry_on_connection_error: false, retry_statuses: nil, retry_statuses_except: nil, created_at: nil, updated_at: nil, deleted_at: nil, version: nil) ⇒ RetryPolicy

Returns a new instance of RetryPolicy.



1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
 
# File 'lib/smplkit/jobs/models.rb', line 1028

def initialize(client = nil, id:, name:, max_retries:, backoff:, delay_seconds:,
               max_delay_seconds: nil, retry_on_timeout: false,
               retry_on_connection_error: false, retry_statuses: nil,
               retry_statuses_except: nil, created_at: nil,
               updated_at: nil, deleted_at: nil, version: nil)
  @client = client
  @id = id
  @name = name
  @max_retries = max_retries
  @backoff = backoff
  @delay_seconds = delay_seconds
  @max_delay_seconds = max_delay_seconds
  @retry_on_timeout = retry_on_timeout
  @retry_on_connection_error = retry_on_connection_error
  @retry_statuses = retry_statuses || []
  @retry_statuses_except = retry_statuses_except || []
  @created_at = created_at
  @updated_at = updated_at
  @deleted_at = deleted_at
  @version = version
end

Instance Attribute Details

#backoff ⇒ String

Returns How the wait between retries grows; one of Backoff.

Returns:

  • (String) —

    How the wait between retries grows; one of Backoff.



983
984
985
 
# File 'lib/smplkit/jobs/models.rb', line 983

def backoff
  @backoff
end

#created_at ⇒ String?

Returns ISO-8601 timestamp of first persist. nil for an unsaved instance.

Returns:

  • (String, nil) —

    ISO-8601 timestamp of first persist. nil for an unsaved instance.



1015
1016
1017
 
# File 'lib/smplkit/jobs/models.rb', line 1015

def created_at
  @created_at
end

#delay_seconds ⇒ Integer

Returns The wait before a retry, in seconds — the constant wait for Backoff::FIXED, or the base that doubles each retry for Backoff::EXPONENTIAL.

Returns:



988
989
990
 
# File 'lib/smplkit/jobs/models.rb', line 988

def delay_seconds
  @delay_seconds
end

#deleted_at ⇒ String?

Returns Timestamp when the policy was deleted; nil for live policies.

Returns:

  • (String, nil) —

    Timestamp when the policy was deleted; nil for live policies.



1022
1023
1024
 
# File 'lib/smplkit/jobs/models.rb', line 1022

def deleted_at
  @deleted_at
end

#id ⇒ String

Caller-supplied unique identifier for the policy (the resource id). Unique within the account and immutable; the service returns 409 if another live policy already uses this id.

Returns:

  • (String) —

    Caller-supplied unique identifier for the policy (the resource id). Unique within the account and immutable; the service returns 409 if another live policy already uses this id.



972
973
974
 
# File 'lib/smplkit/jobs/models.rb', line 972

def id
  @id
end

#max_delay_seconds ⇒ Integer?

Returns Ceiling on the wait between retries, for Backoff::EXPONENTIAL backoff only. nil (the default, omitted on the wire) leaves it uncapped; omit it for Backoff::FIXED.

Returns:

  • (Integer, nil) —

    Ceiling on the wait between retries, for Backoff::EXPONENTIAL backoff only. nil (the default, omitted on the wire) leaves it uncapped; omit it for Backoff::FIXED.



993
994
995
 
# File 'lib/smplkit/jobs/models.rb', line 993

def max_delay_seconds
  @max_delay_seconds
end

#max_retries ⇒ Integer

Returns How many times a failed run is retried after the initial attempt — 3 means up to 4 attempts total. 0 disables retries. Maximum 10.

Returns:

  • (Integer) —

    How many times a failed run is retried after the initial attempt — 3 means up to 4 attempts total. 0 disables retries. Maximum 10.



980
981
982
 
# File 'lib/smplkit/jobs/models.rb', line 980

def max_retries
  @max_retries
end

#name ⇒ String

Returns Human-readable name for the policy.

Returns:

  • (String) —

    Human-readable name for the policy.



975
976
977
 
# File 'lib/smplkit/jobs/models.rb', line 975

def name
  @name
end

#retry_on_connection_error ⇒ Boolean

Returns Retry a run whose destination could not be reached (a connection error). Defaults to false.

Returns:

  • (Boolean) —

    Retry a run whose destination could not be reached (a connection error). Defaults to false.



1000
1001
1002
 
# File 'lib/smplkit/jobs/models.rb', line 1000

def retry_on_connection_error
  @retry_on_connection_error
end

#retry_on_timeout ⇒ Boolean

Returns Retry a run that timed out. Defaults to false.

Returns:

  • (Boolean) —

    Retry a run that timed out. Defaults to false.



996
997
998
 
# File 'lib/smplkit/jobs/models.rb', line 996

def retry_on_timeout
  @retry_on_timeout
end

#retry_statuses ⇒ Array<String>

Returns Allowlist of response-status patterns to retry on a non-success response. Each element is an exact 3-digit code (e.g. “429”) or a class token (+“1xx”+ … “5xx”). Defaults to an empty list (retries no statuses).

Returns:

  • (Array<String>) —

    Allowlist of response-status patterns to retry on a non-success response. Each element is an exact 3-digit code (e.g. “429”) or a class token (+“1xx”+ … “5xx”). Defaults to an empty list (retries no statuses).



1006
1007
1008
 
# File 'lib/smplkit/jobs/models.rb', line 1006

def retry_statuses
  @retry_statuses
end

#retry_statuses_except ⇒ Array<String>

Returns Patterns subtracted from #retry_statuses, using the same exact-code or class syntax. A status matching both lists is not retried — except wins on overlap. Defaults to an empty list.

Returns:

  • (Array<String>) —

    Patterns subtracted from #retry_statuses, using the same exact-code or class syntax. A status matching both lists is not retried — except wins on overlap. Defaults to an empty list.



1011
1012
1013
 
# File 'lib/smplkit/jobs/models.rb', line 1011

def retry_statuses_except
  @retry_statuses_except
end

#updated_at ⇒ String?

Returns ISO-8601 timestamp of the most recent mutation.

Returns:

  • (String, nil) —

    ISO-8601 timestamp of the most recent mutation.



1018
1019
1020
 
# File 'lib/smplkit/jobs/models.rb', line 1018

def updated_at
  @updated_at
end

#version ⇒ Integer?

Returns Monotonic version counter, bumped on every server-side write.

Returns:

  • (Integer, nil) —

    Monotonic version counter, bumped on every server-side write.



1026
1027
1028
 
# File 'lib/smplkit/jobs/models.rb', line 1026

def version
  @version
end

Class Method Details

.from_resource(resource, client: nil) ⇒ RetryPolicy

Returns The hydrated policy.

Parameters:

  • resource (Object) —

    The JSON:API resource (id + attributes).

  • client (RetryPoliciesClient, nil) (defaults to: nil) —

    Client to bind the policy to.

Returns:



1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
 
# File 'lib/smplkit/jobs/models.rb', line 1100

def self.from_resource(resource, client: nil)
  a = resource.attributes
  new(
    client,
    id: resource.id,
    name: a.name,
    max_retries: a.max_retries,
    backoff: a.backoff,
    delay_seconds: a.delay_seconds,
    max_delay_seconds: a.max_delay_seconds,
    retry_on_timeout: a.retry_on_timeout || false,
    retry_on_connection_error: a.retry_on_connection_error || false,
    retry_statuses: a.retry_statuses || [],
    retry_statuses_except: a.retry_statuses_except || [],
    created_at: a.created_at,
    updated_at: a.updated_at,
    deleted_at: a.deleted_at,
    version: a.version
  )
end

Instance Method Details

#_apply(other) ⇒ 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. 



1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
 
# File 'lib/smplkit/jobs/models.rb', line 1077

def _apply(other)
  @id = other.id
  @name = other.name
  @max_retries = other.max_retries
  @backoff = other.backoff
  @delay_seconds = other.delay_seconds
  @max_delay_seconds = other.max_delay_seconds
  @retry_on_timeout = other.retry_on_timeout
  @retry_on_connection_error = other.retry_on_connection_error
  @retry_statuses = other.retry_statuses
  @retry_statuses_except = other.retry_statuses_except
  @created_at = other.created_at
  @updated_at = other.updated_at
  @deleted_at = other.deleted_at
  @version = other.version
end

#delete ⇒ nil Also known as: delete!

Delete this policy on the server.

Returns:

  • (nil) 


1069
1070
1071
1072
1073
 
# File 'lib/smplkit/jobs/models.rb', line 1069

def delete
  raise "RetryPolicy was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?

  @client.delete(@id)
end

#save ⇒ self Also known as: save!

Create this policy, or full-replace it if it already exists.

Upsert behavior is driven by #created_at: a policy with no created_at is created (POST); otherwise it’s full-replace updated (PUT). After the call, every field is refreshed from the server response.

Returns:

  • (self) 


1057
1058
1059
1060
1061
1062
1063
 
# File 'lib/smplkit/jobs/models.rb', line 1057

def save
  raise "RetryPolicy was constructed without a client; cannot save" if @client.nil?

  updated = @created_at.nil? ? @client._create_retry_policy(self) : @client._update_retry_policy(self)
  _apply(updated)
  self
end