antbird 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 472e058c1be7a6fdadf9949dc8c73c644ba5c82f3eea3b76fc502623fac4bea8
-  data.tar.gz: 35d0eff4b83b58a11f9299fca6210922f3243b3c166d7cc20385492bebf80570
+  metadata.gz: 2d00e228d8e4628e1e0a0f0fb34e0df4382c552266b1510f44734ef022757569
+  data.tar.gz: 6d4d6abd75ee27a4756eac51b6039b44f438f378ca4fe23ccd95905ce61eee25
 SHA512:
-  metadata.gz: 569096a452fa059ee7527a8fc48a372fc0c7aa1c6001f467b0ce355240656ac787ae6a4ecdc7065d54d1c3daeecc31bbdc812304e023b5fafe32a0669b770838
-  data.tar.gz: d0c653d432e0ea31f1e98cc56b5486f126d1697483efae7a4f66f31e0b73669d2a5387be8d41b19e8a9759374df635791d88e3814c16d149001ac0b380c7de28
+  metadata.gz: 0a0e44ac7de86a2671b3571ba407dd262f01ed976bb70648e397d112ccd28b5c169397a528231105fc9fd7b175f427185beadfd0508cf523b000104313a92059
+  data.tar.gz: e2aaf781014694479d8710dfefa417a1e29b993600ecf043aab7b44713e66630143e3a4ae1550bc9328184d5b6a4948b47d4daa2f6b19f36681ae8c44e57e6ae

data/Gemfile.lock

@@ -1,17 +1,17 @@
 PATH
   remote: .
   specs:
-    antbird (1.0.0)
+    antbird (1.1.0)
       faraday (>= 2.0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.9)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     connection_pool (3.0.2)
     diff-lcs (1.6.2)
-    faraday (2.14.1)
+    faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -22,7 +22,7 @@ GEM
       net-http-persistent (>= 4.0.4, < 5)
     faraday-retry (2.4.0)
       faraday (~> 2.0)
-    json (2.19.2)
+    json (2.19.5)
     logger (1.7.0)
     net-http (0.9.1)
       uri (>= 0.11.1)

data/README.md

@@ -99,6 +99,67 @@ client.bulk(body: [
 ])
 ```
 
+### Timeouts
+
+Default connection timeouts are configured when the client is created:
+
+```ruby
+client = Antbird::Client.new(
+  read_timeout: 5,   # seconds (default)
+  open_timeout: 2,   # seconds (default)
+  write_timeout: 30, # seconds (default: nil => falls back to read_timeout)
+)
+```
+
+`write_timeout` is optional. When omitted it is left unset and the adapter
+falls back to `read_timeout` for the write phase, preserving existing behavior.
+
+Timeouts can be overridden per operation. There are two ways to do it:
+
+1. `http_timeout` — a shorthand that sets the `read`, `open` and `write`
+   timeouts all at once for that single request:
+
+   ```ruby
+   # This request alone uses a 60s timeout for read/open/write.
+   client.search(body: { query: { match_all: {} } }, http_timeout: 60)
+
+   # Long-running reindex; give it more time without affecting other calls.
+   client.reindex(body: { source: { index: 'a' }, dest: { index: 'b' } }, http_timeout: 600)
+   ```
+
+2. `read_timeout` / `open_timeout` / `write_timeout` — override individual
+   phases. These may be combined with each other:
+
+   ```ruby
+   client.bulk(body: [{ index: { _id: '1' } }, { field1: 'a' }], open_timeout: 3, write_timeout: 30)
+   ```
+
+When none of these is given, the client falls back to the values configured at
+initialization time.
+
+`http_timeout` is mutually exclusive with `read_timeout` / `open_timeout` /
+`write_timeout`. Passing `http_timeout` together with any of them raises an
+`ArgumentError`:
+
+```ruby
+client.search(body: { query: { match_all: {} } }, http_timeout: 60, open_timeout: 3) # => ArgumentError
+```
+
+All of the above are client-side (HTTP) timeouts and do not collide with the
+server-side `timeout` query parameter that some OpenSearch APIs accept — both
+can be passed together:
+
+```ruby
+client.bulk(
+  body: [{ index: { _id: '1' } }, { field1: 'a' }],
+  timeout: '30s',    # OpenSearch server-side timeout (query parameter)
+  http_timeout: 60,  # HTTP read/open/write timeout (Faraday)
+)
+```
+
+> `read_timeout` sets Faraday's global `:timeout` (preserving its original
+> behavior), while `open_timeout` / `write_timeout` set those specific phases.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/antbird/client.rb

@@ -9,14 +9,16 @@ module Antbird
       version: nil,
       read_timeout: 5,
       open_timeout: 2,
+      write_timeout: nil,
       adapter: ::Faraday.default_adapter,
       &block)
 
-      @read_timeout = read_timeout
-      @open_timeout = open_timeout
-      @adapter      = adapter
-      @block        = block
-      @url          = url
+      @read_timeout  = read_timeout
+      @open_timeout  = open_timeout
+      @write_timeout = write_timeout
+      @adapter       = adapter
+      @block         = block
+      @url           = url
 
       @scope        = scope.transform_keys(&:to_sym)
 
@@ -25,7 +27,7 @@ module Antbird
       @api_specs = {}
     end
     attr_reader :scope, :url
-    attr_reader :read_timeout, :open_timeout, :adapter
+    attr_reader :read_timeout, :open_timeout, :write_timeout, :adapter
     attr_reader :api_specs, :last_request
 
     def scoped(new_scope = {})
@@ -35,6 +37,7 @@ module Antbird
         version: version,
         read_timeout: read_timeout,
         open_timeout: open_timeout,
+        write_timeout: write_timeout,
         adapter: adapter,
         &@block
       )
@@ -84,7 +87,7 @@ module Antbird
           methods.first
         end
 
-      read_timeout = params.delete(:read_timeout)
+      timeout_options = extract_timeout_options(params)
       params.reject! { |_, v| v.nil? }
 
       @last_request = {
@@ -100,29 +103,29 @@ module Antbird
         when :head
           connection.head(api_path) do |req|
             req.params = params unless params.empty?
-            req.options[:timeout] = read_timeout if read_timeout
+            apply_timeouts(req, timeout_options)
           end
         when :get
           connection.get(api_path) do |req|
             req.params = params unless params.empty?
             req.body = body if body
-            req.options[:timeout] = read_timeout if read_timeout
+            apply_timeouts(req, timeout_options)
           end
         when :put
           connection.put(api_path, body) do |req|
             req.params = params unless params.empty?
-            req.options[:timeout] = read_timeout if read_timeout
+            apply_timeouts(req, timeout_options)
           end
         when :post
           connection.post(api_path, body) do |req|
             req.params = params unless params.empty?
-            req.options[:timeout] = read_timeout if read_timeout
+            apply_timeouts(req, timeout_options)
           end
         when :delete
           connection.delete(api_path) do |req|
             req.params = params unless params.empty?
             req.body = body if body
-            req.options[:timeout] = read_timeout if read_timeout
+            apply_timeouts(req, timeout_options)
           end
         else
           raise ArgumentError, "Unknown HTTP request method: #{method.inspect}"
@@ -185,8 +188,9 @@ module Antbird
         conn.request :json
         conn.response :json, content_type: /\bjson$/
 
-        conn.options[:timeout]      = read_timeout
-        conn.options[:open_timeout] = open_timeout
+        conn.options[:timeout]       = read_timeout
+        conn.options[:open_timeout]  = open_timeout
+        conn.options[:write_timeout] = write_timeout if write_timeout
 
         conn.adapter adapter
       end
@@ -201,6 +205,44 @@ module Antbird
 
     private
 
+    # Builds the per-operation Faraday timeout options from the request params.
+    # - http_timeout: overrides read/open/write timeouts all at once. It is
+    #   mutually exclusive with read_timeout/open_timeout/write_timeout.
+    # - read_timeout: legacy per-operation override (sets Faraday's :timeout).
+    # - open_timeout / write_timeout: per-operation overrides for those phases.
+    # The granular options may be combined with each other.
+    # When none is given, the connection-level defaults are used.
+    #
+    # The read phase is set via Faraday's :timeout key (consistent with the
+    # legacy read_timeout path and the connection-level default); :open_timeout
+    # and :write_timeout are set explicitly so http_timeout overrides them even
+    # when the connection configures its own defaults.
+    def extract_timeout_options(params)
+      http_timeout  = params.delete(:http_timeout)
+      read_timeout  = params.delete(:read_timeout)
+      open_timeout  = params.delete(:open_timeout)
+      write_timeout = params.delete(:write_timeout)
+
+      if http_timeout && (read_timeout || open_timeout || write_timeout)
+        raise ArgumentError,
+          ":http_timeout cannot be combined with :read_timeout, :open_timeout or :write_timeout"
+      end
+
+      if http_timeout
+        return { timeout: http_timeout, open_timeout: http_timeout, write_timeout: http_timeout }
+      end
+
+      options = {}
+      options[:timeout]       = read_timeout  if read_timeout
+      options[:open_timeout]  = open_timeout  if open_timeout
+      options[:write_timeout] = write_timeout if write_timeout
+      options
+    end
+
+    def apply_timeouts(req, timeout_options)
+      timeout_options.each { |key, value| req.options[key] = value }
+    end
+
     # NOTE: stable sort
     def sort_url_paths(url_paths)
       i = 0
@@ -221,7 +263,7 @@ module Antbird
       end
     end
 
-    SPECIAL_PARAMS = %i[body method read_timeout].freeze
+    SPECIAL_PARAMS = %i[body method http_timeout read_timeout open_timeout write_timeout].freeze
 
     def validate_params(api_spec, params, path_params)
       if api_spec.dig('body', 'required') && !params.key?(:body)

data/lib/antbird/version.rb

@@ -1,3 +1,3 @@
 module Antbird
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: antbird
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - fukayatsu
@@ -143,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Nearly auto-generated OpenSearch client
 test_files: []