antbird 0.15.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e72bd2b5755abdb64e991345baab5cdca8320fa1f511753e9c8845245b03427
-  data.tar.gz: 427b4282927adafe574eda5151c6b9abe5023bf03c148348deee995569264adb
+  metadata.gz: 2d00e228d8e4628e1e0a0f0fb34e0df4382c552266b1510f44734ef022757569
+  data.tar.gz: 6d4d6abd75ee27a4756eac51b6039b44f438f378ca4fe23ccd95905ce61eee25
 SHA512:
-  metadata.gz: 23752fde1a9a786036e97cc0fb3fd5d99ed803d5cdfdf2c5cdde557f4ffca28653f929e97f77d818eb5ee2437d10a6f7937a499b4f48be828674da984c84c00a
-  data.tar.gz: 0e6472c29d2ea5736a24898b0306310ce13b1f26bd93d2c84d09d54a8bfa8ddbb8b3defa0f0ed27389429bef1e434568f6ec11910e75f083f00b27d102f39575
+  metadata.gz: 0a0e44ac7de86a2671b3571ba407dd262f01ed976bb70648e397d112ccd28b5c169397a528231105fc9fd7b175f427185beadfd0508cf523b000104313a92059
+  data.tar.gz: e2aaf781014694479d8710dfefa417a1e29b993600ecf043aab7b44713e66630143e3a4ae1550bc9328184d5b6a4948b47d4daa2f6b19f36681ae8c44e57e6ae

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

@@ -13,34 +13,12 @@ jobs:
       matrix:
         # https://github.com/opensearch-project/OpenSearch/releases
         search_versions:
+          - 3.5.0
+          - 3.4.0
           - 3.3.2
           - 3.2.0
           - 3.1.0
           - 3.0.0
-          - 2.19.4
-          - 2.18.0
-          - 2.17.1
-          - 2.16.0
-          - 2.15.0
-          - 2.14.0
-          - 2.13.0
-          - 2.12.0
-          - 2.11.1
-          - 2.10.0
-          - 2.9.0
-          - 2.8.0
-          - 2.7.0
-          - 2.6.0
-          - 2.5.0
-          - 2.4.1
-          - 2.3.0
-          - 2.2.1
-          - 2.1.0
-          - 2.0.1
-          - 1.3.20
-          - 1.2.4
-          - 1.1.0
-          - 1.0.0
     services:
       opensearch:
         image: opensearchproject/opensearch:${{matrix.search_versions}}
@@ -49,7 +27,8 @@ jobs:
         env:
           discovery.type: single-node
           plugins.security.disabled: true
-          OPENSEARCH_INITIAL_ADMIN_PASSWORD: StrongPassowrd123
+          # a minimum 8 character password and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong. Password strength can be tested here: https://lowe.github.io/tryzxcvbn
+          OPENSEARCH_INITIAL_ADMIN_PASSWORD: "antbird@123Antbird"
     steps:
       - name: Configure sysctl limits
         run: |
@@ -60,8 +39,8 @@ jobs:
       - uses: actions/checkout@v6
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.2"
+          ruby-version: "4.0"
           bundler-cache: true
       - name: Wait for OpenSearch
-        run: timeout 60 bash -c "until curl --silent --output /dev/null 'localhost:9200/_cat/health?h=st'; do printf '.'; sleep 5; done; printf '\n'"
+        run: timeout 120 bash -c "until curl --silent --output /dev/null 'localhost:9200/_cat/health?h=st'; do printf '.'; sleep 5; done; printf '\n'"
       - run: bundle exec rspec

data/.gitignore

@@ -10,6 +10,6 @@
 # rspec failure tracking
 .rspec_status
 
-Gemfile.lock
-
 .envrc
+
+.claude/settings.local.json

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    antbird (1.1.0)
+      faraday (>= 2.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    faraday (2.14.2)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      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.5)
+    logger (1.7.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    net-http-persistent (4.0.8)
+      connection_pool (>= 2.2.4, < 4)
+    octokit (10.0.0)
+      faraday (>= 1, < 3)
+      sawyer (~> 0.9)
+    public_suffix (7.0.5)
+    rake (13.3.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    sawyer (0.9.3)
+      addressable (>= 2.3.5)
+      faraday (>= 0.17.3, < 3)
+    uri (1.1.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  antbird!
+  faraday-net_http_persistent
+  faraday-retry
+  octokit
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+  4.0.8

data/README.md

@@ -1,8 +1,8 @@
 # Antbird
 
-Nearly auto-generated Elasticsearch/OpenSearch client
+Nearly auto-generated OpenSearch client (supports OpenSearch 3.x)
 
-[![Build Status](https://github.com/fukayatsu/antbird/workflows/build/badge.svg)](https://github.com/fukayatsu/antbird/actions)
+[![Build Status](https://github.com/fukayatsu/antbird/workflows/build-os/badge.svg)](https://github.com/fukayatsu/antbird/actions)
 
 ## Installation
 
@@ -29,7 +29,7 @@ client = Antbird::Client.new
 
 # OR
 
-client = Antbird::Client.new.scoped(index: 'test-index', type: 'test-type')
+client = Antbird::Client.new.scoped(index: 'test-index')
 
 # OR
 
@@ -37,19 +37,17 @@ client = Antbird::Client.new(
   url: 'http://localhost:9200',
   scope: {
     index: 'test-index',
-    type: 'test-type'
   }
 )
 
-# OR
+# OR with AWS OpenSearch Service
 
 require 'faraday/net_http_persistent'
 require 'faraday_middleware/aws_sigv4'
 client = Antbird::Client.new(
-  url: ENV['AMAZON_ELASTICSEARCH_SERVICE_URL'],
+  url: ENV['AMAZON_OPENSEARCH_SERVICE_URL'],
   scope: {
     index: 'test-index',
-    type: 'test-type'
   },
   adapter: :net_http_persistent
 ) do |f|
@@ -68,7 +66,7 @@ end
 
 ```ruby
 client = Antbird::Client.new(
-  scope: { index: 'test-index', type: 'test-type' }
+  scope: { index: 'test-index' }
 )
 
 client.indices_exists? # => false
@@ -76,10 +74,8 @@ client.indices_create(
   body: {
     settings: { number_of_shards: 1 },
     mappings: {
-      'test-type': {
-        properties: {
-          field1: { type: :text }
-        }
+      properties: {
+        field1: { type: :text }
       }
     }
   }
@@ -103,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.
@@ -113,9 +170,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/fukayatsu/antbird. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-### How to support newer version of Elasticsearch/OpenSearch
+### How to support newer version of OpenSearch
 
-1. Add Elasticsearch version to `jobs.build.strategy.matrix.search_versions` on `.github/workflows/build.yml` / `.github/workflows/build-os.yml`
+1. Add OpenSearch version to `jobs.build.strategy.matrix.search_versions` on `.github/workflows/build-os.yml`
    - Only one line for `x.y.*` version
 1. `script/generate_api_methods`
    - Set `GITHUB_TOKEN=***` env for GitHub API Limit
@@ -126,4 +183,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Antbird project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fukayatsu/antbird/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Antbird project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fukayatsu/antbird/blob/master/CODE_OF_CONDUCT.md).

data/antbird.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["fukayatsu"]
   spec.email         = ["fukayatsu@gmail.com"]
 
-  spec.summary       = %q{Nearly auto-generated Elasticsearch client}
-  spec.description   = %q{Antbird is a yet another low level API client for the Elasticsearch HTTP interface.}
+  spec.summary       = %q{Nearly auto-generated OpenSearch client}
+  spec.description   = %q{Antbird is a yet another low level API client for the OpenSearch HTTP interface.}
   spec.homepage      = "https://github.com/fukayatsu/antbird"
   spec.license       = "MIT"
 
@@ -20,13 +20,12 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.add_dependency "faraday", ">= 2.0.1"
 
   spec.add_development_dependency "faraday-retry"
   spec.add_development_dependency "faraday-net_http_persistent"
-  spec.add_development_dependency "bundler", "> 1.16", "< 3.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "octokit"

data/lib/antbird/client.rb

@@ -7,29 +7,27 @@ module Antbird
       scope: {},
       url: "http://localhost:9200",
       version: nil,
-      distribution: 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)
 
-      if version
-        @version      = version
-        @distribution = distribution
-      end
+      @version = version
 
       @api_specs = {}
     end
-    attr_reader :scope, :url, :distribution
-    attr_reader :read_timeout, :open_timeout, :adapter
+    attr_reader :scope, :url
+    attr_reader :read_timeout, :open_timeout, :write_timeout, :adapter
     attr_reader :api_specs, :last_request
 
     def scoped(new_scope = {})
@@ -37,17 +35,19 @@ module Antbird
         scope: new_scope,
         url: url,
         version: version,
-        distribution: distribution,
         read_timeout: read_timeout,
-        open_timeout: open_timeout
+        open_timeout: open_timeout,
+        write_timeout: write_timeout,
+        adapter: adapter,
+        &@block
       )
     end
 
-    def request(api_name, api_spec, params)
-      validate_params(api_spec, params)
+    def request(api_name, api_spec, params, path_params = [:index, :type, :id])
+      validate_params(api_spec, params, path_params)
 
       body   = extract_body(params)
-      scopes = extract_scopes(params)
+      scopes = extract_scopes(params, path_params)
       forced_method = extract_method(params)
 
       # Greedy match
@@ -87,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 = {
@@ -103,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}"
@@ -148,9 +148,9 @@ module Antbird
       params.delete(:method)&.to_sym
     end
 
-    def extract_scopes(params)
+    def extract_scopes(params, path_params = [:index, :type, :id])
       scopes = {}
-      [:index, :type, :id].each do |s|
+      path_params.each do |s|
         scope = params.delete(s)
         next unless scope
         scopes[s] = scope
@@ -188,44 +188,61 @@ 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
     end
 
-    def elasticsearch?
-      !opensearch?
-    end
-
-    def opensearch?
-      ensure_version_and_distribution
+    def version
+      return @version if @version
 
-      distribution == 'opensearch'
+      ensure_version
+      @version
     end
 
-    def elasticsearch_v7_0_compatible?
-      return true if opensearch?
+    private
 
-      elasticsearch? && Gem::Version.new(version) >= Gem::Version.new('7.0.0')
-    end
+    # 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
 
-    def elasticsearch_v7_6_compatible?
-      return true if opensearch?
+      if http_timeout
+        return { timeout: http_timeout, open_timeout: http_timeout, write_timeout: http_timeout }
+      end
 
-      elasticsearch? && Gem::Version.new(version) >= Gem::Version.new('7.6.0')
+      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 version
-      return @version if @version
-
-      ensure_version_and_distribution
-      @version
+    def apply_timeouts(req, timeout_options)
+      timeout_options.each { |key, value| req.options[key] = value }
     end
 
-    private
-
     # NOTE: stable sort
     def sort_url_paths(url_paths)
       i = 0
@@ -246,16 +263,50 @@ module Antbird
       end
     end
 
-    def validate_params(api_spec, params)
-      # TODO case: required parameter is missing
-      # TODO case: invalid parameter name
-      # TODO case: invalid parameter format
+    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)
         raise ArgumentError, 'Body is missing'
       end
+
+      return unless api_spec.key?('params')
+
+      api_params = api_spec['params']
+      common = respond_to?(:common_params) ? common_params.fetch('params', {}).keys.map(&:to_sym) : []
+      valid_keys = api_params.keys.map(&:to_sym) + path_params + SPECIAL_PARAMS + common
+
+      unknown = params.keys - valid_keys
+      unless unknown.empty?
+        raise ArgumentError, "Unknown parameters: #{unknown.join(', ')}"
+      end
+
+      api_params.each do |name, defn|
+        if defn['required'] && !params.key?(name.to_sym)
+          raise ArgumentError, "Required parameter missing: #{name}"
+        end
+
+        value = params[name.to_sym]
+        next if value.nil?
+
+        validate_param_type(name, value, defn['type'])
+      end
+    end
+
+    def validate_param_type(name, value, type)
+      case type
+      when 'boolean'
+        unless value == true || value == false
+          raise ArgumentError, "Parameter '#{name}' must be a boolean"
+        end
+      when 'number', 'integer', 'int'
+        unless value.is_a?(Numeric)
+          raise ArgumentError, "Parameter '#{name}' must be a number"
+        end
+      end
     end
 
-    def ensure_version_and_distribution
+    def ensure_version
       return if @version
 
       response = connection.get('/')
@@ -265,26 +316,27 @@ module Antbird
 
       version_hash = response.body.dig('version')
       @version = version_hash['number']
-      @distribution = version_hash['distribution']
     end
 
     def class_version
       version.split('.')[0, 2].join('_')
     end
 
+    SUPPORTED_MAJOR_VERSION = 3
+
     def ensure_api_spec_loaded
       return if api_specs_loaded?
 
-      ensure_version_and_distribution
+      ensure_version
 
-      if opensearch?
-        require "antbird/rest_api/rest_api_opensearch_v#{class_version}"
-        extend Antbird::RestApi.const_get "RestApiOpensearchV#{class_version}"
-      else
-        require "antbird/rest_api/rest_api_v#{class_version}"
-        extend Antbird::RestApi.const_get "RestApiV#{class_version}"
+      major = version.split('.').first.to_i
+      unless major == SUPPORTED_MAJOR_VERSION
+        raise "Unsupported OpenSearch version: #{version}. Antbird currently supports OpenSearch #{SUPPORTED_MAJOR_VERSION}.x only."
       end
 
+      require "antbird/rest_api/rest_api_opensearch_v#{class_version}"
+      extend Antbird::RestApi.const_get "RestApiOpensearchV#{class_version}"
+
       @api_specs_loaded = true
     end