opensearch-aws-sigv4 1.3.0 → 2.0.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a1bbddbba6e3e1872e65075cabeb1386e334a4e21107f0193869174653dfc52
-  data.tar.gz: 7fe1d0e9522f976db80affd18fb9927af8898a780d2c07a3abe4119a68013eb4
+  metadata.gz: 102c17b87f52f20a9d554f36347e9e458d846e6a00c0a98637fc308ba9e2846f
+  data.tar.gz: b2f41069ad25a0da064331550b1f83aea76f7abacc384c1c8b44b919057b3513
 SHA512:
-  metadata.gz: 9d11753e96e212bc8726dbfc149c788d2a291e44b7593b83860048f560a4988c4826ef5669547bf0b4fa3dd2dac91651a1ce7eb9de2c0c7d82b4df10c32ea88c
-  data.tar.gz: 593355060580e5f2b72c8be568282fb4f0a89369a75b6f30a9bae696285530fd3b38bd6450728030586bf66fb4d01cdf4d5d048ff4ca808ee6dc5acab896b418
+  metadata.gz: 47b70757731a9cd594d1491d95c1576a53eb73cabe494d98813a1b69f3b5eef6d0a37a7f8f4fefdfacc5c7e440a8a1d587199e42fe95b9e9c4c6381bf3dfb710
+  data.tar.gz: cdf066b67d5df7e6167d8cb8bd3ec02b94e33d354da124532e5004a5906f035f54d51c07c5f4a2e9d0efc95e26ddd93091d470a2a480a5479a674050e6422a2e

data/README.md

@@ -1,14 +1,20 @@
 [<img src="OpenSearch.svg" width="400">](https://opensearch.org)
 
-# OpenSearch AWS Sigv4 Client
+# OpenSearch AWS SigV4 Request Signer
 
-The `opensearch-aws-sigv4` library provides an AWS Sigv4 client for connecting to [Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/index.html).
-
-This library is an AWS Sigv4 wrapper for [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main), which is a Ruby client for OpenSearch. The `OpenSearch::Aws::Sigv4Client`, therefore, has all features of `OpenSearch::Client`.
+The `opensearch-aws-sigv4` library provides an AWS Sigv4 request signer for [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main), which is a Ruby client for OpenSearch.
 
 ## Compatibility
 
-The `opensearch-aws-sigv4` library is compatible with all versions of `opensearch-ruby`.
+The compatibility between `opensearch-aws-sigv4` and `opensearch-ruby` is as follows:
+
+| `opensearch-aws-sigv4` Version | Compatible `opensearch-ruby` Versions |
+|-------------------------------|--------------------------------------|
+| `< 2.0`                       | `> 4.0`                             |
+| `>= 2.0`                      | `<= 4.0`                            |
+
+- **`opensearch-aws-sigv4 < 2.0`** is compatible with all versions of **`opensearch-ruby > 4.0`**.
+- **`opensearch-aws-sigv4 >= 2.0`** is compatible with all versions of **`opensearch-ruby <= 4.0`**.
 
 ## User Guide
 

data/USER_GUIDE.md

@@ -23,7 +23,7 @@ bundle install
 
 ## Usage
 
-This library is an AWS Sigv4 wrapper for [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main), which is a Ruby client for OpenSearch. The `OpenSearch::Aws::Sigv4Client`, therefore, has all features of `OpenSearch::Client`.
+This library provides an AWS SigV4 request signer for [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main), which is a Ruby client for OpenSearch.
 
 ### Amazon OpenSearch Service
 To sign requests for the Amazon OpenSearch Service:
@@ -32,22 +32,30 @@ To sign requests for the Amazon OpenSearch Service:
 require 'opensearch-aws-sigv4'
 require 'aws-sigv4'
 
-signer = Aws::Sigv4::Signer.new(service: 'es', # signing service name, use "aoss" for OpenSearch Serverless
-                                region: 'us-west-2', # signing service region
-                                access_key_id: 'key_id',
-                                secret_access_key: 'secret')
+request_signer = OpenSearch::Aws::Sigv4RequestSigner.new(
+  service: 'es', # signing service name, use "aoss" for OpenSearch Serverless
+  region: 'us-west-2', # signing service region
+  access_key_id: 'key_id',
+  secret_access_key: 'secret'
+)
 
-client = OpenSearch::Aws::Sigv4Client.new({
-    host: 'https://your.amz-managed-opensearch.domain', # serverless endpoint for OpenSearch Serverless
-    log: true
-}, signer)
+client = OpenSearch::Client.new(
+  host: 'https://your.amz-managed-opensearch.domain', # serverless endpoint for OpenSearch Serverless
+  request_signer: request_signer
+)
 
 # create an index and document
 index = 'prime'
 client.indices.create(index: index)
-client.index(index: index, id: '1', body: { name: 'Amazon Echo', 
-                                            msrp: '5999', 
-                                            year: 2011 })
+client.index(
+  index: index,
+  id: '1',
+  body: {
+    name: 'Amazon Echo',
+    msrp: '5999',
+    year: 2011
+  }
+)
 
 # search for the document
 client.search(body: { query: { match: { name: 'Echo' } } })
@@ -60,37 +68,37 @@ client.indices.delete(index: index)
 ```
 
 ### Enable Sigv4 Debug Logging
-If you run into credentials errors, usually from expired session, set the `sigv4_debug` option to `true` when creating the client to print out the Sigv4 Signing Debug information.
 
-```ruby
-client = OpenSearch::Aws::Sigv4Client.new({
-    host: 'https://your.amz-managed-opensearch.domain',
-}, signer, sigv4_debug: true)
+The `opensearch-aws-sigv4` gem outputs the contents of the signature at the `debug` level via the logger passed to the `OpenSearch::Client`.
+
+To inspect the actual signature content being generated for each request (e.g. for debugging purposes or troubleshooting), pass a logger configured with `DEBUG` level like this:
 
-client.info
+```ruby
+request_signer = OpenSearch::Aws::Sigv4RequestSigner.new(
+  service: 'es', # signing service name, use "aoss" for OpenSearch Serverless
+  region: 'us-west-2', # signing service region
+  access_key_id: 'key_id',
+  secret_access_key: 'secret'
+)
+
+logger = Logger.new($stdout)
+logger.level = Logger::DEBUG
+
+client = OpenSearch::Client.new(
+  host: 'https://your.amz-managed-opensearch.domain', # serverless endpoint for OpenSearch Serverless
+  logger: logger,
+  request_signer: request_signer
+)
+
+puts client.info
 ```
 
-```shell
-(2023-04-25 11:02:59 -0600)  Sigv4 - STRING TO SIGN: 
-AWS4-HMAC-SHA256
-20230425T170259Z
-20230425/us-east-1/aoss/aws4_request
-0e20bdc5eda484f2b0e65f8a33514c48471500da91b1f0c8bb6b86770b5dc6c4
-
-(2023-04-25 11:02:59 -0600)  Sigv4 - CANONICAL REQUEST:
-GET
-/
-
-host:your.amz-managed-opensearch.domain
-x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
-x-amz-date:20230425T170259Z
-
-host;x-amz-content-sha256;x-amz-date
-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
-
-(2023-04-25 11:02:59 -0600)  Sigv4 - SIGNATURE HEADERS:
-{"host"=>"your.amz-managed-opensearch.domain", 
-"x-amz-date"=>"20230425T170259Z", 
-"x-amz-content-sha256"=>"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", 
-"authorization"=>"AWS4-HMAC-SHA256 Credential=ABCDEFGH/20230425/us-east-1/aoss/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=858f171c834231ae3c885c670217f94c68f010e85c50b0ad095444966fb5df0c"}
+This will output log messages like this:
+
+```
+I, [2025-03-31T20:32:24.398301 #77479]  INFO -- : Signing request with AWS SigV4: GET http://your.amz-managed-opensearch.domain/
+D, [2025-03-31T20:32:24.399198 #77479] DEBUG -- : Signed headers with AWS SigV4: {"host" => "your.amz-managed-opensearch.domain", "x-amz-date" => "20250331T113224Z", "x-amz-content-sha256" => "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "authorization" => "AWS4-HMAC-SHA256 Credential=key_id/20250331/us-west-2/es/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=57c69c2da9597c40625e2dbef3806bdfa0e9e50c99918d2ae10a264110352e51"}
+...
 ```
+
+By default, the signer will use the logger from the `opensearch-ruby` gem. To ensure safe logging in a production environment, make sure its level is set to `INFO` to avoid logging debug-level signed headers.

data/lib/opensearch-aws-sigv4/version.rb

@@ -12,7 +12,7 @@
 module OpenSearch
   module Aws
     module Sigv4
-      VERSION = '1.3.0'
+      VERSION = '2.0.0-beta.1'
     end
   end
 end

data/lib/opensearch-aws-sigv4.rb

@@ -14,100 +14,63 @@ require 'opensearch-ruby'
 require 'aws-sigv4/signer'
 require 'faraday'
 require 'json'
+require 'forwardable'
 
 module OpenSearch
   module Aws
-    # AWS Sigv4 Wrapper for OpenSearch::Client.
-    # This client accepts a Sigv4 Signer during initialization, and signs every request
-    # with a Sigv4 Signature with the provided signer.
+    # AWS Sigv4 request signer for <tt>OpenSearch::Transport::Client</tt>.
     #
-    # @example
-    #   signer = Aws::Sigv4::Signer.new(service: 'es',
-    #                                   region: 'us-east-1',
-    #                                   access_key_id: '<access_key_id>',
-    #                                   secret_access_key: '<secret_access_key>',
-    #                                   session_token: '<session_token>')
+    # @link https://github.com/opensearch-project/opensearch-ruby/blob/main/DEVELOPER_GUIDE.md#create-a-request-signer
     #
-    #   client = OpenSearch::Aws::Sigv4Client.new(
-    #       { host: 'https://my-os-domain.us-east-1.es.amazonaws.com/' },
-    #       signer
-    #   )
+    # @param [Hash] options Signer options
+    # @option options [String] :service ('es') The AWS service name.
+    # @option options [String] :region The AWS region.
+    # @option options [String] :access_key_id The AWS access key ID.
+    # @option options [String] :secret_access_key The AWS secret access key.
+    # @option options [String] :session_token (optional) The AWS session token.
     #
-    #   puts client.cat.health
+    # @example
+    #   client = OpenSearch::Client.new({
+    #     host: 'https://my-os-domain.us-east-1.es.amazonaws.com/',
+    #     request_signer: OpenSearch::Aws::Sigv4RequestSigner.new(
+    #       service: 'es',
+    #       region: 'us-east-1',
+    #       access_key_id: '<access_key_id>',
+    #       secret_access_key: '<secret_access_key>',
+    #       session_token: '<session_token>'
+    #     )
+    #   })
     #
-    # @attr [Aws::Sigv4::Signer] sigv4_signer Signer used to sign every request
-    class Sigv4Client < ::OpenSearch::Client
-      attr_accessor :sigv4_signer
+    #   puts client.cat.health
+    class Sigv4RequestSigner
+      extend Forwardable
+
+      attr_reader :signer
 
-      # @param [Hash] transport_args arguments for OpenSearch::Transport::Client.
-      # @param [&block] block code block to be passed to OpenSearch::Transport::Client.
-      # @param [Aws::Sigv4::Signer] sigv4_signer an instance of AWS Sigv4 Signer.
-      # @param [Hash] options
-      # @option options [Boolean] :sigv4_debug whether to log debug info for Sigv4 Signing
-      def initialize(transport_args, sigv4_signer, options: {}, &block)
-        unless sigv4_signer.is_a?(::Aws::Sigv4::Signer)
-          raise ArgumentError, "Please pass a Aws::Sigv4::Signer. A #{sigv4_signer.class} was given."
-        end
+      def_delegators :@signer, :service, :region, :credentials_provider, :unsigned_headers, :apply_checksum_header
 
-        @sigv4_signer = sigv4_signer
-        @sigv4_debug = options[:sigv4_debug]
-        @logger = nil
-        super(transport_args, &block)
+      def initialize(options = {})
+        @signer = ::Aws::Sigv4::Signer.new({
+          service: 'es'
+        }.merge(options))
       end
 
-      # @see OpenSearch::Transport::Transport::Base::perform_request
-      def perform_request(method, path, params = {}, body = nil, headers = nil)
+      def sign_request(method:, path:, params:, body:, headers:, host:, port:, url:, logger:) # rubocop:disable Lint/UnusedMethodArgument
+        logger&.info("Signing request with AWS SigV4: #{method} #{url}")
+
         signature_body = body.is_a?(Hash) ? body.to_json : body.to_s
-        signature = sigv4_signer.sign_request(
+        signature = @signer.sign_request(
           http_method: method,
-          url: signature_url(path, params),
+          url: url,
           headers: headers,
-          body: signature_body
+          body: signature_body,
+          logger: logger
         )
-        headers = (headers || {}).merge(signature.headers)
-
-        log_signature_info(signature)
-        super(method, path, params, signature_body, headers)
-      end
 
-      private
-
-      def verify_open_search
-        @verified = true
-      end
+        signed_headers = signature.headers
+        logger&.debug("Signed headers with AWS SigV4: #{signed_headers}")
 
-      def signature_url(path, params)
-        host = @transport.transport.hosts.dig(0, :host)
-        path = "/#{path}" unless path.start_with?('/')
-        params = params.clone
-        params.delete(:ignore)
-        params.delete('ignore')
-        query_string = params.empty? ? '' : Faraday::Utils::ParamsHash[params].to_query.to_s
-        URI::HTTP.build(host: host, path: path, query: query_string)
-      end
-
-      # @param [Aws::Sigv4::Signature] signature
-      def log_signature_info(signature)
-        return unless @sigv4_debug
-
-        log('string to sign', signature.string_to_sign)
-        log('canonical request', signature.canonical_request)
-        log('signature headers', signature.headers)
-      end
-
-      def log(title, message)
-        logger.debug("#{title.upcase}:\n\e[36m#{message}\e[0m")
-      end
-
-      def logger
-        return @logger if @logger
-
-        require 'logger'
-        @logger = Logger.new(
-          $stdout,
-          progname: 'Sigv4',
-          formatter: proc { |_severity, datetime, progname, msg| "\e[34m(#{datetime})  #{progname} - #{msg}\e[0m\n\n" }
-        )
+        (headers || {}).merge(signed_headers)
       end
     end
   end

data/opensearch-aws-sigv4.gemspec

@@ -33,7 +33,6 @@ Gem::Specification.new do |s|
   }
 
   s.files         = Dir['lib/**/*', '*.gemspec']
-  s.test_files    = Dir['spec/unit/**/*']
   s.require_paths = ['lib']
   s.bindir        = 'bin'
   s.executables   = 'opensearch_sigv4_console'
@@ -41,14 +40,13 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files  = %w[README.md USER_GUIDE.md LICENSE]
   s.rdoc_options      = ['--charset=UTF-8']
 
-  signing_key = File.expand_path('gem-private_key.pem')
+  signing_key = File.expand_path(ENV.fetch('GEM_PRIVATE_KEY', 'gem-private_key.pem'))
   if $PROGRAM_NAME.end_with?('gem') && ARGV.first == 'build' && File.exist?(signing_key)
     s.signing_key = signing_key
-    s.cert_chain  = ['.github/opensearch-rubygems.pem']
+    s.cert_chain  = [ENV.fetch('GEM_PUBLIC_CERT', '.github/opensearch-rubygems.pem')]
   end
 
-  s.required_ruby_version = '>= 2.5'
+  s.required_ruby_version = '>= 3.0'
 
-  s.add_dependency 'aws-sigv4', '>= 1'
-  s.add_dependency 'opensearch-ruby', '>= 1.0.1', '< 4.0'
+  s.add_dependency 'aws-sigv4', '~> 1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opensearch-aws-sigv4
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0.pre.beta.1
 platform: ruby
 authors:
 - OpenSearch Contributors
@@ -30,42 +30,22 @@ cert_chain:
   m0rB25J1sO2yjlalRdBoV5p7OKaWG4CGMr+q6vCC2za7yrtZiYOOv+KpWmheTwds
   P1nbdIL2eAXGfNU3cbtYisS1sSYi7VSkS52pVk8Jgtw=
   -----END CERTIFICATE-----
-date: 2025-03-18 00:00:00.000000000 Z
+date: 2025-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sigv4
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
-- !ruby/object:Gem::Dependency
-  name: opensearch-ruby
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
 description: |
   A wrapper for opensearch-ruby gem that provides AWS Sigv4 signing.
   It behaves like OpenSearch::Client, but signs every request with AWS Sigv4
@@ -87,7 +67,6 @@ files:
 - lib/opensearch-aws-sigv4/version.rb
 - lib/opensearch_aws_sigv4.rb
 - opensearch-aws-sigv4.gemspec
-- spec/unit/open_search/aws/sigv4_client_spec.rb
 homepage: https://github.com/opensearch-project/opensearch-ruby-aws-sigv4
 licenses:
 - Apache-2.0
@@ -106,16 +85,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Ruby AWS Sigv4 Client for OpenSearch
-test_files:
-- spec/unit/open_search/aws/sigv4_client_spec.rb
+test_files: []

data/spec/unit/open_search/aws/sigv4_client_spec.rb

@@ -1,107 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-#
-# The OpenSearch Contributors require contributions made to
-# this file be licensed under the Apache-2.0 license or a
-# compatible open source license.
-#
-# Modifications Copyright OpenSearch Contributors. See
-# GitHub history for details.
-
-# frozen_string_literal: true
-
-require_relative '../../../spec_helper'
-require 'aws-sigv4'
-require 'timecop'
-
-describe OpenSearch::Aws::Sigv4Client do
-  subject(:client) do
-    described_class.new(
-      { host: 'http://localhost:9200',
-        transport_options: { ssl: { verify: false } } },
-      signer
-    )
-  end
-
-  let(:signer) do
-    Aws::Sigv4::Signer.new(service: 'es',
-                           region: 'us-west-2',
-                           access_key_id: 'key_id',
-                           secret_access_key: 'secret')
-  end
-
-  describe '.initialize' do
-    context 'when a Sigv4 Signer is NOT provided' do
-      let(:signer) { nil }
-
-      it 'raises an argument error' do
-        expect { client }.to raise_error ArgumentError, 'Please pass a Aws::Sigv4::Signer. A NilClass was given.'
-      end
-    end
-
-    context 'when a Sigv4 Signer is provided' do
-      it 'does NOT raise any error' do
-        expect { client }.not_to raise_error
-      end
-    end
-  end
-
-  describe '#perform_request' do
-    let(:response) { { body: 'Response Body' } }
-    let(:transport_double) do
-      double = instance_double(OpenSearch::Transport::Client, perform_request: response)
-      allow(double).to receive_message_chain(:transport, :hosts, :dig).and_return('localhost')
-      double
-    end
-    let(:signed_headers) do
-      { 'authorization' => 'AWS4-HMAC-SHA256 Credential=key_id/20220101/us-west-2/es/aws4_request, '\
-                           'SignedHeaders=host;x-amz-content-sha256;x-amz-date, ' \
-                           'Signature=9c4c690110483308f62a91c2ca873857750bca2607ba1aabdae0d2303950310a',
-        'host' => 'localhost',
-        'x-amz-content-sha256' => 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
-        'x-amz-date' => '20220101T000000Z' }
-    end
-
-    before do
-      Timecop.freeze(Time.utc(2022))
-      client.transport = transport_double
-    end
-
-    after { Timecop.return }
-
-    it 'signs the request before passing it to @transport' do
-      output = client.perform_request('GET', '/', {}, '', {})
-      expect(output).to eq(response)
-      expect(transport_double).to have_received(:perform_request).with('GET', '/', {}, '', signed_headers)
-    end
-
-    it 'excludes the `ignore` param to make a signature' do
-      output = client.perform_request('GET', '/', { ignore: 404 }, '', {})
-      expect(output).to eq(response)
-      expect(transport_double).to have_received(:perform_request).with('GET', '/', { ignore: 404 }, '', signed_headers)
-    end
-
-    it 'skips the opensearch verification' do
-      allow(client).to receive(:open_search_validation_request)
-      client.perform_request('GET', '/_stats', {}, '', {})
-      expect(client).not_to have_received(:open_search_validation_request)
-    end
-
-    it 'passes the same body to sign_request and super' do
-      body = {
-        char_filter: {
-          test: {
-            type: 'mapping',
-            mappings: ["’ => '"]
-          }
-        }
-      }
-      signature_body = body.to_json
-
-      allow(signer).to receive(:sign_request).with(a_hash_including(body: signature_body)).and_call_original
-
-      client.perform_request('GET', '/', {}, body, {})
-
-      expect(transport_double).to have_received(:perform_request).with('GET', '/', {}, signature_body, kind_of(Hash))
-    end
-  end
-end