antbird 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 472e058c1be7a6fdadf9949dc8c73c644ba5c82f3eea3b76fc502623fac4bea8
-  data.tar.gz: 35d0eff4b83b58a11f9299fca6210922f3243b3c166d7cc20385492bebf80570
+  metadata.gz: 4fa1a5ef17ca8b183c23e877b88386b4b28bdf9da8cfc35faf1285be1adb8a13
+  data.tar.gz: b7084f2d7fd314254d20f6f382f6947b456efde369ec444ec7621f68ae567920
 SHA512:
-  metadata.gz: 569096a452fa059ee7527a8fc48a372fc0c7aa1c6001f467b0ce355240656ac787ae6a4ecdc7065d54d1c3daeecc31bbdc812304e023b5fafe32a0669b770838
-  data.tar.gz: d0c653d432e0ea31f1e98cc56b5486f126d1697483efae7a4f66f31e0b73669d2a5387be8d41b19e8a9759374df635791d88e3814c16d149001ac0b380c7de28
+  metadata.gz: e552dc0dfa4fdfa137a157de7f6b110047542c9c1e79ad881e9b7aeeb48a463e9021ce209b9dac868357aeab16bb2d5f58f37e0644f5faf402852c93a9314a5f
+  data.tar.gz: dbac1bc2360ab6120349d8a003d75929142fce2a286f65623b3e9dd75e9699d13e7c113c4394035b7b0d33e88cb7ecb1b7eb6d772c98462f36be527199f653bf

data/.github/workflows/build-os.yml

@@ -13,6 +13,9 @@ jobs:
       matrix:
         # https://github.com/opensearch-project/OpenSearch/releases
         search_versions:
+          - 3.8.0
+          - 3.7.0
+          - 3.6.0
           - 3.5.0
           - 3.4.0
           - 3.3.2
@@ -36,7 +39,7 @@ jobs:
           sudo sysctl -w vm.swappiness=1
           sudo sysctl -w fs.file-max=262144
           sudo sysctl -w vm.max_map_count=262144
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: "4.0"

data/Gemfile.lock

@@ -1,28 +1,28 @@
 PATH
   remote: .
   specs:
-    antbird (1.0.0)
+    antbird (1.2.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.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.2)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
     faraday-net_http_persistent (2.3.1)
       faraday (~> 2.5)
       net-http-persistent (>= 4.0.4, < 5)
     faraday-retry (2.4.0)
       faraday (~> 2.0)
-    json (2.19.2)
+    json (3.0.1)
     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/json_decoder.rb

@@ -0,0 +1,20 @@
+require 'json'
+
+module Antbird
+  class Client
+    # Faraday's JSON response middleware hands parser options to the decoder as
+    # a positional Hash (`decoder.parse(body, options)`). json 3.0 turned
+    # JSON.parse into `parse(source, **options)`, so that call raises
+    # ArgumentError and every response fails with Faraday::ParsingError.
+    # Decoding through here keeps antbird working on both json 2.x and 3.x.
+    module JsonDecoder
+      module_function
+
+      def parse(body, options = {})
+        return ::JSON.parse(body) if options.nil? || options.empty?
+
+        ::JSON.parse(body, **options)
+      end
+    end
+  end
+end

data/lib/antbird/client.rb

@@ -1,5 +1,6 @@
 require 'faraday'
 require 'antbird/client/errors'
+require 'antbird/client/json_decoder'
 
 module Antbird
   class Client
@@ -9,14 +10,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 +28,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 +38,7 @@ module Antbird
         version: version,
         read_timeout: read_timeout,
         open_timeout: open_timeout,
+        write_timeout: write_timeout,
         adapter: adapter,
         &@block
       )
@@ -84,7 +88,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 +104,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}"
@@ -183,10 +187,11 @@ module Antbird
         @block&.call(conn)
 
         conn.request :json
-        conn.response :json, content_type: /\bjson$/
+        conn.response :json, content_type: /\bjson$/, parser_options: { decoder: [JsonDecoder, :parse] }
 
-        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 +206,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 +264,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)