super_pdp 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80df88af44b2d803aa180b0d205329440167089782755f4ac1635b94a5066d54
-  data.tar.gz: 5083f9d514fb7163910a0d8ed9b3129762c1f561e11ceb50ec3f0f214148f56f
+  metadata.gz: 1c19819ce17d392aee66a03b36d190a6b33cc032c2e76a52fdf42586801b9d5e
+  data.tar.gz: 232d936312f901357e196a037f116606eff4e270ff65dcc56fad88fa847d7c6f
 SHA512:
-  metadata.gz: 252df23df32876233d65684b4afb80b2756e788a7b51b0d6dc3fc6cc3b504dd83a15064ab69ff49a09432fd97b2dcccf7d5fb32180d04fbf21f3b19577cb5baf
-  data.tar.gz: 2ce4577ad5003b603dba86a1bdd1946bc45735b3631c686e82e883ff236e547152478b5992bc18375241fc4a697248a63d4631caa6651c0e54dd11e81e27d895
+  metadata.gz: e9282838649f3d7191b8d6eb0f39dd01de19173eaa68ffcea93d80b88754ac29189612f6fdb72711e49a4b9695a742417c190aa2d4c40c85cace33596fc6cb59
+  data.tar.gz: 05e4597cf5aae2c9ca7246ea09d08aa4d4d4abe06b28e31d7859285c0e662992849a58badb7afc7a233eae7a04b61620f28c93922b269333507184c2dc9740ce

data/README.md

@@ -61,7 +61,23 @@ pdp.post("/some/new/route", { key: "value" })
 ```
 
 Responses are parsed JSON (`Hash`/`Array`). Non-2xx raises `SuperPDP::APIError`
-(`#status`, `#body`).
+(`#status`, `#body`), or a status-specific subclass you can rescue directly:
+`UnauthorizedError` (401/403), `NotFoundError` (404), `RateLimitError` (429, with
+`#retry_after` in seconds). All subclass `APIError`, so `rescue SuperPDP::APIError`
+still catches everything.
+
+## Retries
+
+Transient failures on **idempotent** requests (`GET`/`DELETE`) are retried
+automatically: HTTP 429 and 502/503/504, plus connection errors. The server's
+`Retry-After` header is honored; otherwise it backs off exponentially. `POST`
+and `PATCH` are never retried (a half-applied write is worse than an error).
+
+```ruby
+SuperPDP.new(client_id: "...", client_secret: "...",
+             max_retries: 2,    # total attempts = max_retries + 1 (default 2)
+             retry_base: 0.5)   # backoff seconds: retry_base * 2**(attempt-1)
+```
 
 ## Test
 

data/lib/super_pdp/client.rb

@@ -14,17 +14,27 @@ module SuperPDP
   class Client
     DEFAULT_BASE_URL = "https://api.superpdp.tech"
     API_PREFIX = "/v1.beta"
+    USER_AGENT = "super_pdp/#{VERSION} (Ruby #{RUBY_VERSION})".freeze
+
+    # Transient failures retried automatically (idempotent verbs only).
+    RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+    RETRYABLE_METHODS = %i[get delete].freeze
+    RETRYABLE_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+                        Errno::ECONNREFUSED, IOError].freeze
 
     attr_reader :base_url
 
     def initialize(access_token: nil, client_id: nil, client_secret: nil,
-                   base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 60)
+                   base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 60,
+                   max_retries: 2, retry_base: 0.5)
       @access_token = access_token
       @client_id = client_id
       @client_secret = client_secret
       @base_url = base_url
       @open_timeout = open_timeout
       @read_timeout = read_timeout
+      @max_retries = max_retries
+      @retry_base = retry_base
       @token_expires_at = nil
       @token_mutex = Mutex.new
 
@@ -95,16 +105,44 @@ module SuperPDP
     def patch(path, body = {}, query = {}) = request(:patch, path, body: body, query: query)
     def delete(path, query = {}) = request(:delete, path, query: query)
 
+    # Retries transient failures (429 + 502/503/504 + connection errors) with
+    # backoff for idempotent verbs only. See RETRYABLE_* constants.
     def request(method, path, query: {}, body: nil, raw: false)
       uri = build_uri(path, query)
+      attempt = 0
+      loop do
+        attempt += 1
+        res =
+          begin
+            perform(method, uri, body)
+          rescue *RETRYABLE_ERRORS
+            raise unless retryable?(method, attempt)
+
+            sleep backoff(attempt)
+            next
+          end
+        return handle_response(res, raw: raw) unless retry_status?(method, res.code.to_i, attempt)
+
+        sleep(retry_after(res) || backoff(attempt))
+      end
+    end
+
+    private
+
+    def perform(method, uri, body)
       req = build_request(method, uri, body)
       req["Authorization"] = "Bearer #{token}"
-
-      res = http(uri).request(req)
-      handle_response(res, raw: raw)
+      http(uri).request(req)
     end
 
-    private
+    def retryable?(method, attempt) = RETRYABLE_METHODS.include?(method) && attempt <= @max_retries
+    def retry_status?(method, status, attempt) = retryable?(method, attempt) && RETRYABLE_STATUSES.include?(status)
+    def backoff(attempt) = @retry_base * (2**(attempt - 1))
+
+    def retry_after(res)
+      v = res["Retry-After"]
+      v =~ /\A\d+\z/ ? Integer(v) : nil # honor integer seconds; ignore HTTP-date form
+    end
 
     def build_uri(path, query)
       full = path.start_with?("/v1") || path.start_with?("http") ? path : "#{API_PREFIX}#{path}"
@@ -128,6 +166,7 @@ module SuperPDP
       }.fetch(method)
       req = klass.new(uri)
       req["Accept"] = "application/json"
+      req["User-Agent"] = USER_AGENT
       if body
         req["Content-Type"] = "application/json"
         req.body = body.is_a?(String) ? body : JSON.generate(body)
@@ -148,7 +187,16 @@ module SuperPDP
       body = raw ? res.body : parse_json(res.body)
       return body if status.between?(200, 299)
 
-      raise APIError.new(status, body)
+      raise error_for(status, body, res)
+    end
+
+    def error_for(status, body, res)
+      case status
+      when 401, 403 then UnauthorizedError.new(status, body)
+      when 404      then NotFoundError.new(status, body)
+      when 429      then RateLimitError.new(status, body, retry_after(res))
+      else               APIError.new(status, body)
+      end
     end
 
     def parse_json(str)
@@ -183,6 +231,7 @@ module SuperPDP
       uri = URI.join(@base_url, "/oauth2/token")
       req = Net::HTTP::Post.new(uri)
       req["Accept"] = "application/json"
+      req["User-Agent"] = USER_AGENT
       req.set_form_data(
         grant_type: "client_credentials",
         client_id: @client_id,

data/lib/super_pdp/error.rb

@@ -15,5 +15,23 @@ module SuperPDP
     end
   end
 
+  # Status-specific subclasses so callers can rescue by kind. All subclass
+  # APIError, so `rescue SuperPDP::APIError` still catches every non-2xx.
+  # 401, 403
+  class UnauthorizedError < APIError; end
+  # 404
+  class NotFoundError < APIError; end
+
+  # 429
+  class RateLimitError < APIError
+    attr_reader :retry_after # integer seconds from Retry-After, or nil
+
+    def initialize(status, body, retry_after = nil)
+      @retry_after = retry_after
+      super(status, body)
+    end
+  end
+
+  # Token/credential-refresh failures (not an HTTP APIError).
   class AuthError < Error; end
 end

data/lib/super_pdp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SuperPDP
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: super_pdp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Thomas Demoncy