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 (base) or JobEnvironment#retry_policy (per environment, via Job#environment). 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.



988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
 
# File 'lib/smplkit/jobs/models.rb', line 988

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.



943
944
945
 
# File 'lib/smplkit/jobs/models.rb', line 943

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.



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

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:



948
949
950
 
# File 'lib/smplkit/jobs/models.rb', line 948

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.



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

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.



932
933
934
 
# File 'lib/smplkit/jobs/models.rb', line 932

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.



953
954
955
 
# File 'lib/smplkit/jobs/models.rb', line 953

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.



940
941
942
 
# File 'lib/smplkit/jobs/models.rb', line 940

def max_retries
  @max_retries
end

#name ⇒ String

Returns Human-readable name for the policy.

Returns:

  • (String) —

    Human-readable name for the policy.



935
936
937
 
# File 'lib/smplkit/jobs/models.rb', line 935

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.



960
961
962
 
# File 'lib/smplkit/jobs/models.rb', line 960

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.



956
957
958
 
# File 'lib/smplkit/jobs/models.rb', line 956

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).



966
967
968
 
# File 'lib/smplkit/jobs/models.rb', line 966

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.



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

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.



978
979
980
 
# File 'lib/smplkit/jobs/models.rb', line 978

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.



986
987
988
 
# File 'lib/smplkit/jobs/models.rb', line 986

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:



1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
 
# File 'lib/smplkit/jobs/models.rb', line 1060

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. 



1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
 
# File 'lib/smplkit/jobs/models.rb', line 1037

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) 


1029
1030
1031
1032
1033
 
# File 'lib/smplkit/jobs/models.rb', line 1029

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) 


1017
1018
1019
1020
1021
1022
1023
 
# File 'lib/smplkit/jobs/models.rb', line 1017

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