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.



981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
 
# File 'lib/smplkit/jobs/models.rb', line 981

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.



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

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.



968
969
970
 
# File 'lib/smplkit/jobs/models.rb', line 968

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:



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

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.



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

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.



925
926
927
 
# File 'lib/smplkit/jobs/models.rb', line 925

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.



946
947
948
 
# File 'lib/smplkit/jobs/models.rb', line 946

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.



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

def max_retries
  @max_retries
end

#name ⇒ String

Returns Human-readable name for the policy.

Returns:

  • (String) —

    Human-readable name for the policy.



928
929
930
 
# File 'lib/smplkit/jobs/models.rb', line 928

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.



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

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.



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

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



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

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.



964
965
966
 
# File 'lib/smplkit/jobs/models.rb', line 964

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.



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

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.



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

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:



1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
 
# File 'lib/smplkit/jobs/models.rb', line 1053

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. 



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

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) 


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

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) 


1010
1011
1012
1013
1014
1015
1016
 
# File 'lib/smplkit/jobs/models.rb', line 1010

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