tiny-rest-client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ae594ba15f60d217c03513ffd00bfb867e607cf24e86f2faba66309ec41b252
-  data.tar.gz: c13258411fd7212dafade551a2b7384973837c47e47803eb35fb3244e1cad7ce
+  metadata.gz: 72d74c14f37ab28b47e2c0cf52bfa9f092d2457bad0d5487bbcbb32f1c5b12d5
+  data.tar.gz: 49eac5d225c02dd3675d1c90a41d71067fa150cebb0018d5126d2c8b0e19102e
 SHA512:
-  metadata.gz: '08e9d7be9ecb2f17dc0052cc4965f6336408d35712f9443a2be1e7315a7b2d7ee76ce715d0b181799370d1e6b986fd2ff3175d2790ec8c44031dc100920af77c'
-  data.tar.gz: 3d314db3b3a4d8efd17dd3730f82ef1adbf2dd545d4884a8d20ca0c30e479481ef596d6c8727fc8118a2f1fde6fb9770e8d753e42f62a6324daf7620afadb9db
+  metadata.gz: ee2b67e844a132f1d549cf814098d4af9592884d7a61723391fe98774d50c525b7ba346c59bd2fdfe27d0e2ba869071ca59402c473aac1438c1791cf4d1ca94f
+  data.tar.gz: b02d9ffc1f3e6601a942a7e6f4f2fa752f4e580fca1a7fee3a243887eb2fd9246813bc7372fa0a35416a27784969f6178cde4973f0a5985237740845dc28b7e7

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Class-level retries with configurable delay (throttling)
+  - `retries 3, delay: 0.5` - retry 3 times on 5xx errors with 500ms delay between attempts
+  - Default retryable codes: 500, 502, 503, 504
+  - Instance-level override supported
+
+## [0.2.1] - 2026-03-03
+
+### Fixed
+- Ensure the gem can be required without `require:` option in Gemfile
+- Add `lib/tiny-rest-client.rb` loader file for RubyGems auto-require compatibility
+
 ## [0.2.0] - 2026-03-03
 
 ### Added
@@ -12,7 +26,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Supports nested client names (e.g. `api/v1/stripe`)
   - Optional base URL argument
   - Configurable root namespace via `--namespace`
-  - Automatically generates properly namespaced client classes under `app/`
 
 ## [0.1.0] - 2026-02-22
 
@@ -28,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full Minitest suite (classic + spec style examples)
 - Basic README documentation
 
-[Unreleased]: https://github.com/Dabrovsky/tiny_rest_client/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Dabrovsky/tiny_rest_client/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Dabrovsky/tiny_rest_client/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Dabrovsky/tiny_rest_client/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Dabrovsky/tiny_rest_client/releases/tag/v0.1.0

data/README.md

@@ -1,6 +1,6 @@
 # TinyRestClient
 
-A minimal, opinionated HTTP client wrapper for Rails, built on top of Typhoeus. Perfect for quickly building clean, opinionated API clients with almost no boilerplate.
+A minimal HTTP client wrapper for Rails, built on top of Typhoeus. Perfect for quickly building clean, opinionated API clients with almost no boilerplate.
 
 ### Features
 
@@ -22,6 +22,7 @@ A minimal, opinionated HTTP client wrapper for Rails, built on top of Typhoeus.
 - [Rails Generator](#rails-generator)
 - [Configuration](#configuration)
 - [Authorization](#authorization)
+- [Retries & Delay (Throttling)](#retries--delay-throttling)
 - [Making Requests](#making-requests)
 - [Response Handling](#response-handling)
 - [Contributing](#contributing)
@@ -32,7 +33,7 @@ A minimal, opinionated HTTP client wrapper for Rails, built on top of Typhoeus.
 Add this line to your Gemfile:
 
 ```bash
-gem "tiny-rest-client", require: "tiny_rest_client"
+gem "tiny-rest-client"
 ```
 
 Or install it manually:
@@ -57,7 +58,7 @@ class MyClient < TinyRestClient::Core
   # pass bunch of headers (optional)
   headers "User-Agent": "MyTest/1.0", "Accept": "application/json"
 
-  # define actions
+  # define actions (optional)
   def fetch_todos(**)
     get("/todos", **)
   end
@@ -84,7 +85,7 @@ client = MyClient.new
 client.fetch_todos(page: 1, per_page: 20)
 client.fetch_todo(1)
 client.create_todo(name: "Custom")
-client.update_todo(status: "finished")
+client.update_todo(1, { status: "finished" })
 client.destroy_todo(1)
 ```
 
@@ -98,11 +99,11 @@ rails generate tiny_rest_client:client NAME [URL] [options]
 
 ### Available options
 
-| Option          | Default       | Description                                                 | Example Usage        |
-|-----------------|---------------|-------------------------------------------------------------|----------------------|
-| NAME            | (required)    | Client name (supports nesting like `api/v1/stripe`)         | `rails g ... api/v1/stripe` |
+| Option          | Default       | Description                                                 |
+|-----------------|---------------|-------------------------------------------------------------|
+| NAME            | (required)    | Client name (supports nesting like `api/v1/stripe`)         |
 | URL             | (none)        | Base API URL | `rails g ... stripe https://api.stripe.com`  |
-| --namespace     | `clients`     | Root folder under `app/` (e.g. `app/services/...`)          | `--namespace=services` |
+| --namespace     | `clients`     | Root folder under `app/` (e.g. `app/services/`)             |
 
 ### Basic usage
 
@@ -128,7 +129,7 @@ You can configure client setup at the class level:
 class MyClient < TinyRestClient::Core
   api_path "https://api.example.com/v1"
   authorization :bearer, token: "your_token"
-  headers "Accept": "application/json", "User-Agent", "MyApp/1.0"
+  headers "Accept": "application/json", "User-Agent": "MyApp/1.0"
 end
 
 client = MyClient.new
@@ -207,6 +208,40 @@ end
 MyClient.new(auth: { basic_auth: { user: "name", password: "secret" } })
 ```
 
+## Retries & Delay (Throttling)
+
+The library supports automatic retries on server errors and a simple fixed delay (throttling) between requests, both configurable at class or instance level.
+
+### Retries
+
+Retries only happen on configurable HTTP status codes (default: 500, 502, 503, 504).
+
+```ruby
+class MyClient < TinyRestClient::Core
+  # retry 3 times on default 5xx errors
+  retries 3
+
+  # custom retryable codes
+  retries 5, on: [500..599]
+end
+
+# per-instance
+client = MyClient.new(retries: { count: 3, on: [500..599] })
+```
+
+### Delay (Throttling)
+
+Add a fixed delay (seconds) between each request - useful for rate-limited APIs (default: 1.0 second).
+
+```ruby
+class MyClient < TinyRestClient::Core
+  retries 3, delay: 1.0   # wait 1 second between every retry
+end
+
+# per-instance
+client = MyClient.new(retries: { count: 3, delay: 1.0 })
+```
+
 ## Making Requests
 
 The standard HTTP methods are available directly on every client instance automatically include any headers or authorization configuration you defined.
@@ -231,14 +266,16 @@ helpers:
 |--------|-------------|
 | success? | Helper that represent successful response. |
 | failure? | The opposite. |
+| timed_out? | Returns request timeout status |
 | code | HTTP status code (e.g. `200`, `404`). |
-| status | Return code symbol (e.g. `:ok`, `:couldnt_connect`). |
+| status | Returns code symbol (e.g. `:ok`, `:couldnt_connect`). |
 | headers | Hash of response headers (keys are not normalized). |
 | body | Auto-parsed JSON (symbolized keys). If parsing fails, returns the original raw string. |
 
 ```ruby
 response.success?    # true if code 200–299
 response.failure?    # opposite
+response.timed_out?  # Typhoeus timed_out status
 response.code        # HTTP status code
 response.status      # Typhoeus return_code symbol
 response.body        # auto-parsed JSON hash or raw string
@@ -251,8 +288,9 @@ TinyRestClient does not raise exceptions for HTTP status codes.
 
 Network-level errors (timeouts, connection failures, etc.) are reflected in:
 
-* response.status
 * response.success? / response.failure?
+* response.timed_out?
+* response.status
 
 This makes error handling explicit and predictable.
 

data/lib/tiny-rest-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "#{File.dirname(__FILE__)}/tiny_rest_client"

data/lib/tiny_rest_client/middleware/retry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Middleware
+  module Retry
+    DEFAULT_OPTIONS = {
+      count: 0,                   # 0 = no retries by default
+      on: [500, 502, 503, 504],   # only these server errors by default
+      delay: 1.0                  # 1 second between retries by default
+    }.freeze
+
+    def self.call(request, options = {})
+      opts = DEFAULT_OPTIONS.merge(options)
+      attempt = 0
+
+      loop do
+        attempt += 1
+
+        begin
+          response = request.run
+          return response if response.success?
+
+          if attempt <= opts[:count] && opts[:on].include?(response.code)
+            sleep opts[:delay].to_f
+            next
+          end
+
+          return response
+        rescue Typhoeus::Errors::TyphoeusError => e
+          if attempt <= opts[:count]
+            sleep opts[:delay].to_f
+            retry
+          end
+
+          raise Typhoeus::Errors::TyphoeusError, e
+        end
+      end
+    end
+  end
+end

data/lib/tiny_rest_client/request.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
 class Request
-  attr_reader :method, :api_path, :headers, :body, :params, :endpoint, :rest
+  attr_reader :method, :api_path, :headers, :body, :params, :endpoint, :retries, :rest
 
-  def initialize(method, api_path, endpoint: "", headers: nil, auth_config: nil, body: nil, params: nil)
+  def initialize(method, api_path, endpoint: "", headers: nil, auth_config: nil, body: nil, params: nil, retries: nil)
     @method = method || :get
     @api_path = api_path || raise(ArgumentError, "Define api_path base URL")
     @endpoint = endpoint
     @headers = headers
     @body = body
     @params = params
+    @retries = retries
     @rest = {}
 
     configure_auth(auth_config)
@@ -20,7 +21,8 @@ class Request
       code: response.code,
       status: response.return_code,
       body: response.body,
-      headers: response.headers
+      headers: response.headers,
+      timed_out: response.timed_out?
     )
   rescue Typhoeus::Errors::TyphoeusError => e
     Response.new(
@@ -48,6 +50,6 @@ class Request
   end
 
   def response
-    @response ||= request.run
+    @response ||= Middleware::Retry.call(request, retries)
   end
 end

data/lib/tiny_rest_client/response.rb

@@ -3,13 +3,14 @@
 # The Response class represents a response object that
 # can be used to represent success or failure outcomes
 class Response
-  attr_reader :code, :status, :body, :headers
+  attr_reader :code, :status, :body, :headers, :timed_out
 
-  def initialize(code: nil, status: nil, body: nil, headers: nil)
+  def initialize(code: nil, status: nil, body: nil, headers: nil, timed_out: false)
     @code = code&.to_i
     @status = status
     @headers = headers
     @body = parse_body(body)
+    @timed_out = timed_out
   end
 
   def success?
@@ -20,6 +21,12 @@ class Response
     !success?
   end
 
+  def timed_out?
+    timed_out
+  end
+
+  private
+
   def parse_body(raw_body)
     return raw_body unless raw_body.is_a?(String)
 

data/lib/tiny_rest_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TinyRestClient
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/tiny_rest_client.rb

@@ -8,6 +8,7 @@ require "tiny_rest_client/strategies/auth/basic_auth"
 require "tiny_rest_client/strategies/auth/bearer"
 require "tiny_rest_client/strategies/auth/api_key"
 require "tiny_rest_client/strategies/auth/registry"
+require "tiny_rest_client/middleware/retry"
 require "tiny_rest_client/request"
 require "tiny_rest_client/response"
 require "tiny_rest_client/version"
@@ -44,14 +45,27 @@ module TinyRestClient
           @headers || {}
         end
       end
+
+      def retries(count = nil, on: nil, delay: nil)
+        if count.nil?
+          @retry_options ||= Middleware::Retry::DEFAULT_OPTIONS.dup
+        else
+          @retry_options = {
+            count: count || Middleware::Retry::DEFAULT_OPTIONS[:count],
+            on: Array(on || Middleware::Retry::DEFAULT_OPTIONS[:on]),
+            delay: delay || Middleware::Retry::DEFAULT_OPTIONS[:delay]
+          }
+        end
+      end
     end
 
-    attr_reader :api_path, :auth_config, :headers
+    attr_reader :api_path, :auth_config, :headers, :retries
 
-    def initialize(api_path: nil, auth: nil, headers: {})
+    def initialize(api_path: nil, auth: nil, headers: {}, retries: nil)
       @api_path = api_path || self.class.api_path || raise(ArgumentError, "Undefined api_path base URL")
       @auth_config = auth || self.class.authorization
       @headers = merge_headers(headers)
+      @retries = retries || self.class.retries
     end
 
     def head(endpoint, params = {})
@@ -89,7 +103,7 @@ module TinyRestClient
     end
 
     def common_params
-      { headers:, auth_config: }
+      { headers:, auth_config:, retries: }.compact_blank
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tiny-rest-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dabrovski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-03 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -39,7 +39,9 @@ files:
 - lib/generators/tiny_rest_client/templates/client.rb.tt
 - lib/generators/tiny_rest_client/templates/client_spec.rb.tt
 - lib/generators/tiny_rest_client/templates/client_test.rb.tt
+- lib/tiny-rest-client.rb
 - lib/tiny_rest_client.rb
+- lib/tiny_rest_client/middleware/retry.rb
 - lib/tiny_rest_client/railtie.rb
 - lib/tiny_rest_client/request.rb
 - lib/tiny_rest_client/response.rb