Class: Zeridion::Flare::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/zeridion_flare/client.rb

Overview

Synchronous Flare API client.

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.zeridion.com"
API_PREFIX = 
"/flare/v1"
RETRYABLE_STATUSES = 
[429, 502, 503, 504].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: DEFAULT_BASE_URL, max_retries: 3, retry_base_delay_ms: 500, retry_max_delay_ms: 30_000, timeout_seconds: 30, max_response_bytes: 10 * 1024 * 1024, transport: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    API key. Falls back to FLARE_API_KEY env var.

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    Base URL — default https://api.zeridion.com

  • max_retries (Integer) (defaults to: 3) —

    Set 0 to disable retries.

  • retry_base_delay_ms (Integer) (defaults to: 500) —

    Base for exponential schedule.

  • retry_max_delay_ms (Integer) (defaults to: 30_000) —

    Cap on a single backoff wait.

  • timeout_seconds (Numeric) (defaults to: 30) —

    Per-request read timeout.

  • transport (Object) (defaults to: nil) —

    Object responding to #send_request; default NetHttpTransport.

  • max_response_bytes (Integer) (defaults to: 10 * 1024 * 1024) —

    Hard cap on response body bytes the client will read. Protects against a misbehaving or malicious server sending an unbounded body that would otherwise blow Ruby memory. Defaults to 10 MiB; set 0 to disable.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/zeridion_flare/client.rb', line 73

def initialize(
  api_key: nil,
  base_url: DEFAULT_BASE_URL,
  max_retries: 3,
  retry_base_delay_ms: 500,
  retry_max_delay_ms: 30_000,
  timeout_seconds: 30,
  max_response_bytes: 10 * 1024 * 1024,
  transport: nil
)
  api_key ||= ENV["FLARE_API_KEY"]
  if api_key.nil? || api_key.to_s.empty?
    raise ArgumentError,
          "Client: api_key is required (pass directly or set the FLARE_API_KEY environment variable)"
  end
  @api_key = api_key
  @base_url = base_url.chomp("/")
  @max_retries = max_retries
  @retry_base_delay_ms = retry_base_delay_ms
  @retry_max_delay_ms = retry_max_delay_ms
  @timeout_seconds = timeout_seconds
  @max_response_bytes = max_response_bytes
  @transport = transport || NetHttpTransport.new
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



60
61
62
 
# File 'lib/zeridion_flare/client.rb', line 60

def api_key
  @api_key
end

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



60
61
62
 
# File 'lib/zeridion_flare/client.rb', line 60

def base_url
  @base_url
end

Instance Method Details

#ack_worker(body, idempotency_key: nil, request_id: nil) ⇒ Object 



169
170
171
172
 
# File 'lib/zeridion_flare/client.rb', line 169

def ack_worker(body, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/workers/ack", body: body, idempotency_key: idempotency_key, request_id: request_id)
  decode(maybe_raise(resp))
end

#cancel_job(job_id, idempotency_key: nil, request_id: nil) ⇒ Object 



128
129
130
131
132
133
134
 
# File 'lib/zeridion_flare/client.rb', line 128

def cancel_job(job_id, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/jobs/#{escape_path(job_id)}/cancel",
                 idempotency_key: idempotency_key, request_id: request_id)
  return nil if resp[:status] == 409

  decode(maybe_raise(resp))
end

#create_job(body, idempotency_key: nil, request_id: nil) ⇒ Object

── Jobs ────────────────────────────────────────────────────────────



100
101
102
103
 
# File 'lib/zeridion_flare/client.rb', line 100

def create_job(body, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/jobs", body: body, idempotency_key: idempotency_key, request_id: request_id)
  decode(maybe_raise(resp))
end

#get_job(job_id, idempotency_key: nil, request_id: nil) ⇒ Object 



105
106
107
108
109
110
 
# File 'lib/zeridion_flare/client.rb', line 105

def get_job(job_id, idempotency_key: nil, request_id: nil)
  resp = request("GET", "/jobs/#{escape_path(job_id)}", idempotency_key: idempotency_key, request_id: request_id)
  return nil if resp[:status] == 404

  decode(maybe_raise(resp))
end

#heartbeat(body, idempotency_key: nil, request_id: nil) ⇒ Object

Send a single liveness/progress beat for one in-flight job. STRICT here (raises on non-2xx); the worker runtime swallows. Returns the decoded response Hash, e.g. => "ok" or => "cancel".



163
164
165
166
167
 
# File 'lib/zeridion_flare/client.rb', line 163

def heartbeat(body, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/workers/heartbeat", body: body, idempotency_key: idempotency_key,
                                                request_id: request_id)
  decode(maybe_raise(resp))
end

#list_jobs(state: nil, queue: nil, job_type: nil, created_after: nil, created_before: nil, limit: nil, cursor: nil, idempotency_key: nil, request_id: nil) ⇒ Object 



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/zeridion_flare/client.rb', line 112

def list_jobs(
  state: nil, queue: nil, job_type: nil, created_after: nil,
  created_before: nil, limit: nil, cursor: nil,
  idempotency_key: nil, request_id: nil
)
  params = {
    "state" => state, "queue" => queue, "job_type" => job_type,
    "created_after" => created_after, "created_before" => created_before,
    "limit" => limit, "cursor" => cursor,
  }.reject { |_, v| v.nil? }
  path = "/jobs"
  path += "?#{URI.encode_www_form(params)}" unless params.empty?
  resp = request("GET", path, idempotency_key: idempotency_key, request_id: request_id)
  decode(maybe_raise(resp))
end

#poll_workers(body, idempotency_key: nil, request_id: nil) ⇒ Object 



155
156
157
158
 
# File 'lib/zeridion_flare/client.rb', line 155

def poll_workers(body, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/workers/poll", body: body, idempotency_key: idempotency_key, request_id: request_id)
  decode(maybe_raise(resp))
end

#register_worker(body, idempotency_key: nil, request_id: nil) ⇒ Object

Announce this worker's identity, served queues + job types, and any recurring schedules. Best-effort on the server; STRICT here (raises on non-2xx) — the worker runtime is responsible for swallowing failures.



149
150
151
152
153
 
# File 'lib/zeridion_flare/client.rb', line 149

def register_worker(body, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/workers/register", body: body, idempotency_key: idempotency_key,
                                               request_id: request_id)
  decode(maybe_raise(resp))
end

#retry_job(job_id, idempotency_key: nil, request_id: nil) ⇒ Object 



136
137
138
139
140
141
142
 
# File 'lib/zeridion_flare/client.rb', line 136

def retry_job(job_id, idempotency_key: nil, request_id: nil)
  resp = request("POST", "/jobs/#{escape_path(job_id)}/retry",
                 idempotency_key: idempotency_key, request_id: request_id)
  return nil if resp[:status] == 409

  decode(maybe_raise(resp))
end