jobcelis 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a04bededbf270f66972ecdf3e5762992eee208742f91405d08bb05c59ec8093a
-  data.tar.gz: 3a15fc8b9891decb54f5b2daea5bd5eba3d70ea7c0fda0a2d78581aa8a944aa9
+  metadata.gz: 6063822db94053ab346b13e3bd90b843f62bb0cff1c86554b8999c147d29d5cb
+  data.tar.gz: 3c873ce53d2304093e6c1632aa439d72765c1373a2d154a48b102733c4580b93
 SHA512:
-  metadata.gz: 4b5873ae607564ba60a02da3b9bec3ef477212d78c957db33f8ad4be8eaa7e597b603888218a68f7261febaaf0d15cbae118dc8ddad59a5815d6534c8c224db1
-  data.tar.gz: 7686a3e2b909fe1df8b2c83d381b0a7b4da79b554bd912c6312b69f869fa0b5d4eb26030c87df0328b9e30d412c5cedb3aef3c8fe1df18effb8e9c27f287b74e
+  metadata.gz: 4935d8e1b10c18224ffb04a5d9908455720ed6e27a6093d4428b2116d153cb9814a6765cc0464abfdb8f791fdbe92f6562918f5be3f53da1d2bd735514b1e696
+  data.tar.gz: 85b68964a08b4b91df15f684eba19e5ea694e35ef317188358dfead5bc59ba7458a142cafa303c373f89d28f0ae27b6d15e1a775f1070a444bfc822dacc5d4e7

data/LICENSE

@@ -1,21 +1,67 @@
-MIT License
-
-Copyright (c) 2026 Jobcelis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Vladimir Celi
+Licensed Work:        Jobcelis
+                      The Licensed Work is (c) 2026 Vladimir Celi.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided your use does not include offering the
+                      Licensed Work to third parties as a hosted or
+                      managed service, where the service provides users
+                      with access to any substantial set of the features
+                      or functionality of the Licensed Work.
+Change Date:          2030-03-08
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: support@jobcelis.com
+
+Notice
+
+Business Source License 1.1 (BUSL-1.1)
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

data/README.md

@@ -248,6 +248,9 @@ topics = client.list_topics
 # API token
 token = client.get_token
 new_token = client.regenerate_token
+
+# Limit the token to scopes and client IPs (empty allowed_ips = any IP)
+client.update_token_restrictions(scopes: ["events:read", "events:write"], allowed_ips: ["203.0.113.10"])
 ```
 
 ## Multi-Project Management
@@ -346,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
@@ -374,3 +393,7 @@ end
 ## License
 
 BSL-1.1 (Business Source License)
+
+## Releasing
+
+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.
@@ -389,6 +417,12 @@ module Jobcelis
       post("/api/v1/token/regenerate", {})
     end
 
+    # Limit the API token to scopes and client IPs. Omitted arguments are left
+    # unchanged; an empty allowed_ips list means any IP.
+    def update_token_restrictions(scopes: nil, allowed_ips: nil)
+      patch("/api/v1/token", { scopes: scopes, allowed_ips: allowed_ips }.compact)
+    end
+
     # ------------------------------------------------------------------
     # Projects (multi)
     # ------------------------------------------------------------------
@@ -646,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)
@@ -709,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
 
@@ -725,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.2.1"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jobcelis
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Jobcelis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-10 00:00:00.000000000 Z
+date: 2026-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: Ruby client for the Jobcelis API — events, webhooks, jobs, pipelines,
   and more. Connects to https://jobcelis.com by default.
 email: support@jobcelis.com
@@ -42,7 +56,7 @@ licenses:
 - BUSL-1.1
 metadata:
   homepage_uri: https://jobcelis.com
-  source_code_uri: https://github.com/vladimirCeli/jobcelis-ruby
+  source_code_uri: https://github.com/jobcelis-team/jobcelis-ruby
   documentation_uri: https://jobcelis.com/docs
 post_install_message:
 rdoc_options: []