jobcelis 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14ada6cadbf711ee7cc825f0aff8b70a50b78e1f8d02c89212fc62f0c1f0e710
-  data.tar.gz: 20c1f1d0caed65c21c1f7d1b1b0b7401d3e198646173126ffd702a2f00cd0d4c
+  metadata.gz: 6063822db94053ab346b13e3bd90b843f62bb0cff1c86554b8999c147d29d5cb
+  data.tar.gz: 3c873ce53d2304093e6c1632aa439d72765c1373a2d154a48b102733c4580b93
 SHA512:
-  metadata.gz: b88bc7b7e364e2c9bd96c776dcd172cec1d16abb74855d2592afae4cb7e038d295d55f90f6115158042926e143428e4f0e82e54b58d558bbd9056e021e667625
-  data.tar.gz: d9441ab7c13079dc69063679f20e9bd7fffd46de94798a421b0660c0e0a389c7a9e0ba97fb07aa08a576b5565957002e5096131684a05a07ee51cd2425fbdce7
+  metadata.gz: 4935d8e1b10c18224ffb04a5d9908455720ed6e27a6093d4428b2116d153cb9814a6765cc0464abfdb8f791fdbe92f6562918f5be3f53da1d2bd735514b1e696
+  data.tar.gz: 85b68964a08b4b91df15f684eba19e5ea694e35ef317188358dfead5bc59ba7458a142cafa303c373f89d28f0ae27b6d15e1a775f1070a444bfc822dacc5d4e7

data/README.md

@@ -349,6 +349,22 @@ rescue Jobcelis::Error => e
 end
 ```
 
+## Retries
+
+The client retries a request automatically when the connection fails (refused or reset connection, DNS or TLS failure, timeout) or the API answers 429, 502, 503 or 504, for example while Jobcelis is being deployed. It waits 1 s, 2 s, 4 s, 8 s, 16 s and 30 s between attempts (with ±20 % jitter), or what the `Retry-After` header asks for, up to 60 s. By default it makes up to 6 retries, about 60 s in total. Other errors, such as 400 or 500, are raised immediately as `Jobcelis::Error`; after the last retry you get the same error you would get without retries.
+
+GET, PUT, PATCH and DELETE are retried in all of these cases. POST is retried on 429/502/503/504, and after a connection failure only when it carries an idempotency key, so a request can never be applied twice:
+
+- `send_event` sends an `X-Idempotency-Key` header, the same on every retry. Pass `idempotency_key:` to use your own key; otherwise a UUID is generated.
+- `send_events` adds an `idempotency_key` to every event that does not have one.
+
+Change or disable retries when you create the client:
+
+```ruby
+client = Jobcelis::Client.new(api_key: "your_api_key", max_retries: 3)
+client = Jobcelis::Client.new(api_key: "your_api_key", max_retries: 0) # no retries
+```
+
 ## Webhook Signature Verification
 
 ```ruby
@@ -380,4 +396,4 @@ BSL-1.1 (Business Source License)
 
 ## Releasing
 
-Bump the version in `jobcelis.gemspec` and `lib/jobcelis.rb` and merge to `main`. The [Release workflow](.github/workflows/release.yml) publishes it to RubyGems and tags the commit. Changes that do not bump the version publish nothing.
+Merge to `main`: the [Release workflow](.github/workflows/release.yml) publishes every change to the package as the next patch version (1.3.1 → 1.3.2) to RubyGems, writes the version into `jobcelis.gemspec` and `lib/jobcelis.rb` and tags the commit. Changes to docs, tests or CI publish nothing. For a minor or major version, raise it in `jobcelis.gemspec` and `lib/jobcelis.rb` in the same pull request. Every pull request runs [CI](.github/workflows/ci.yml), which runs the tests (`ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require File.expand_path(f) }'`).

data/lib/jobcelis/client.rb

@@ -3,6 +3,9 @@
 require "net/http"
 require "json"
 require "uri"
+require "time"
+require "openssl"
+require "securerandom"
 
 module Jobcelis
   # Client for the Jobcelis Event Infrastructure Platform API.
@@ -12,13 +15,32 @@ module Jobcelis
   #   client = Jobcelis::Client.new(api_key: "your_api_key")
   #
   class Client
-    # @param api_key  [String]  Your project API key.
-    # @param base_url [String]  Base URL of the Jobcelis API (default: https://jobcelis.com).
-    # @param timeout  [Integer] Request timeout in seconds (default: 30).
-    def initialize(api_key:, base_url: "https://jobcelis.com", timeout: 30)
+    # Responses that mean the request was not processed and can be sent again.
+    RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+
+    # Connection, DNS, TLS and timeout failures.
+    NETWORK_ERRORS = [
+      SocketError, IOError, EOFError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH, Errno::ETIMEDOUT, Errno::EPIPE
+    ].freeze
+
+    MAX_BACKOFF = 30.0
+    MAX_RETRY_AFTER = 60.0
+
+    # @param api_key          [String]  Your project API key.
+    # @param base_url         [String]  Base URL of the Jobcelis API (default: https://jobcelis.com).
+    # @param timeout          [Integer] Request timeout in seconds (default: 30).
+    # @param max_retries      [Integer] Retries for network errors and 429/502/503/504 responses
+    #   (default: 6, about 60 s in total). 0 disables retries.
+    # @param retry_base_delay [Float]   Delay in seconds before the first retry, doubled on each
+    #   following one up to 30 s (default: 1.0).
+    def initialize(api_key:, base_url: "https://jobcelis.com", timeout: 30, max_retries: 6, retry_base_delay: 1.0)
       @api_key  = api_key
       @base_url = base_url.chomp("/")
       @timeout  = timeout
+      @max_retries = [Integer(max_retries), 0].max
+      @retry_base_delay = Float(retry_base_delay)
       @auth_token = nil
     end
 
@@ -58,13 +80,19 @@ module Jobcelis
     # ------------------------------------------------------------------
 
     # Send a single event.
+    #
+    # The request carries an X-Idempotency-Key header so it can be retried
+    # safely: pass +idempotency_key:+ to choose it, otherwise a UUID is generated.
     def send_event(topic, payload, **kwargs)
-      post("/api/v1/events", { topic: topic, payload: payload, **kwargs })
+      key = kwargs[:idempotency_key] || kwargs["idempotency_key"] || new_idempotency_key
+      request("POST", "/api/v1/events", body: { topic: topic, payload: payload, **kwargs }, idempotency_key: key.to_s)
     end
 
     # Send up to 1000 events in a batch.
+    #
+    # Events without an +idempotency_key+ get a generated one so the batch can be retried safely.
     def send_events(events)
-      post("/api/v1/events/batch", { events: events })
+      post("/api/v1/events/batch", { events: with_idempotency_keys(events) })
     end
 
     # Get event details.
@@ -652,53 +680,95 @@ module Jobcelis
     end
 
     def public_post(path, body)
-      uri = build_uri(path)
-      http = build_http(uri)
-
-      req = Net::HTTP::Post.new(uri)
-      req["Content-Type"] = "application/json"
-      req.body = JSON.generate(body)
+      resp = send_with_retries("POST", path, body: body, auth: false)
+      handle_response(resp)
+    end
 
-      resp = http.request(req)
+    def request(method, path, params: nil, body: nil, idempotency_key: nil)
+      resp = send_with_retries(method, path, params: params, body: body, idempotency_key: idempotency_key)
       handle_response(resp)
     end
 
-    def request(method, path, params: nil, body: nil)
+    def request_raw(method, path, params: nil)
+      resp = send_with_retries(method, path, params: params)
+      raise_for_status(resp)
+      resp.body
+    end
+
+    # Sends the request, retrying network errors and 429/502/503/504 responses
+    # with exponential backoff. POST requests are only retried after a network
+    # error when they carry an idempotency key, so they can never be applied twice.
+    def send_with_retries(method, path, params: nil, body: nil, auth: true, idempotency_key: nil)
       uri = build_uri(path, params)
-      http = build_http(uri)
+      payload = JSON.generate(body) if body
+      idempotent = method.upcase != "POST" || !idempotency_key.nil?
+      attempt = 0
 
-      req = build_request(method, uri)
-      req["Content-Type"] = "application/json"
-      req["X-Api-Key"] = @api_key
-      req["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-      req.body = JSON.generate(body) if body
+      loop do
+        begin
+          resp = perform_request(method, uri, payload, auth, idempotency_key)
+        rescue *NETWORK_ERRORS
+          raise if !idempotent || attempt >= @max_retries
 
-      resp = http.request(req)
-      handle_response(resp)
+          attempt += 1
+          sleep(backoff_delay(attempt))
+          next
+        end
+
+        return resp unless RETRYABLE_STATUSES.include?(resp.code.to_i) && attempt < @max_retries
+
+        attempt += 1
+        sleep(retry_after(resp) || backoff_delay(attempt))
+      end
     end
 
-    def request_raw(method, path, params: nil)
-      uri = build_uri(path, params)
+    def perform_request(method, uri, payload, auth, idempotency_key)
       http = build_http(uri)
-
       req = build_request(method, uri)
       req["Content-Type"] = "application/json"
-      req["X-Api-Key"] = @api_key
-      req["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-
-      resp = http.request(req)
-
-      unless resp.is_a?(Net::HTTPSuccess)
-        detail = begin
-                   parsed = JSON.parse(resp.body)
-                   parsed.is_a?(Hash) ? (parsed["error"] || parsed) : parsed
-                 rescue JSON::ParserError
-                   resp.body
-                 end
-        raise Jobcelis::Error.new(resp.code.to_i, detail)
+      if auth
+        req["X-Api-Key"] = @api_key
+        req["Authorization"] = "Bearer #{@auth_token}" if @auth_token
       end
+      req["X-Idempotency-Key"] = idempotency_key if idempotency_key
+      req.body = payload if payload
+      http.request(req)
+    end
 
-      resp.body
+    # Delay before retry number +attempt+ (1-based): base * 2^(attempt-1), capped, with +/-20% jitter.
+    def backoff_delay(attempt)
+      delay = [@retry_base_delay * (2**(attempt - 1)), MAX_BACKOFF].min
+      delay * (0.8 + (rand * 0.4))
+    end
+
+    # Seconds to wait from a Retry-After header (seconds or HTTP date), capped at 60 s.
+    def retry_after(resp)
+      value = resp["Retry-After"]
+      return nil if value.nil? || value.strip.empty?
+
+      seconds = if value.strip.match?(/\A\d+(\.\d+)?\z/)
+                  value.to_f
+                else
+                  Time.httpdate(value.strip) - Time.now
+                end
+      seconds.clamp(0, MAX_RETRY_AFTER)
+    rescue ArgumentError
+      nil
+    end
+
+    def new_idempotency_key
+      SecureRandom.uuid
+    end
+
+    # Gives every batch item without an idempotency_key its own key, without
+    # changing the caller's hashes, so a retried batch never duplicates events.
+    def with_idempotency_keys(events)
+      events.map do |event|
+        next event unless event.is_a?(Hash)
+        next event if event.key?(:idempotency_key) || event.key?("idempotency_key")
+
+        event.merge(idempotency_key: new_idempotency_key)
+      end
     end
 
     def build_uri(path, params = nil)
@@ -715,6 +785,8 @@ module Jobcelis
       http.use_ssl = (uri.scheme == "https")
       http.open_timeout = @timeout
       http.read_timeout = @timeout
+      # Retries are handled by send_with_retries
+      http.max_retries = 0
       http
     end
 
@@ -731,19 +803,23 @@ module Jobcelis
     end
 
     def handle_response(resp)
-      unless resp.is_a?(Net::HTTPSuccess)
-        detail = begin
-                   parsed = JSON.parse(resp.body)
-                   parsed.is_a?(Hash) ? (parsed["error"] || parsed) : parsed
-                 rescue JSON::ParserError
-                   resp.body
-                 end
-        raise Jobcelis::Error.new(resp.code.to_i, detail)
-      end
+      raise_for_status(resp)
 
       return nil if resp.code == "204"
 
       JSON.parse(resp.body)
     end
+
+    def raise_for_status(resp)
+      return if resp.is_a?(Net::HTTPSuccess)
+
+      detail = begin
+                 parsed = JSON.parse(resp.body)
+                 parsed.is_a?(Hash) ? (parsed["error"] || parsed) : parsed
+               rescue JSON::ParserError
+                 resp.body
+               end
+      raise Jobcelis::Error.new(resp.code.to_i, detail)
+    end
   end
 end

data/lib/jobcelis.rb

@@ -5,5 +5,5 @@ require_relative "jobcelis/webhook_verifier"
 require_relative "jobcelis/client"
 
 module Jobcelis
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jobcelis
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Jobcelis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http