opensearch-aws-sigv4 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c18c127380978f8f6c155763004c09c2f47f8fe510060f78f5e2dd22dfda7d9
-  data.tar.gz: 1bf9b1df47af0b02f6e95950aab3bd51aa107e0d1b70dad9b210c894bcc5074f
+  metadata.gz: 8afd49d01221929f86b5bf1792d12a963cb969b5edc6a9abb242241c31170221
+  data.tar.gz: 278f930240341ab20ed9fe5f8182c1344b1825f7af7232001d096a320c90d9f7
 SHA512:
-  metadata.gz: 6425d6f4b4925292cca4d1ab444643b40399ce6728b865715537df1c061c776bcb759b9fbd1f5d891a72e78ebf457ec601f4d3e0bb106e151d274a9aadb0e81c
-  data.tar.gz: 0376e3c9a1b67e4885335ecd1a751cd2db67725242f5a09f84cfa905dcbed18b2cbe64043e8ffcbb1b638bc5b71917982be13da6186c6f04cbb9f10f73c18d1f
+  metadata.gz: cf3e31f4899441290c6ea65c452d52a1a21b5c36debc1c3bb1c0545d963526b86321ccaf0b136c75dd0dda5851bfe91a869154a08a3b01db2368ebe45c56955d
+  data.tar.gz: 2f5d79ef941d038d2c2f04a39266a8919c1c09626492da0946476b73b57c34565d8fcc05863c084e98f46e75f5d9e9f42416f5048a9674cd179ce1fbcf62c2c5

data/CHANGELOG.md

@@ -3,12 +3,18 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 ### Added
-- Added support for Amazon OpenSearch Serverless ([#131](https://github.com/opensearch-project/opensearch-ruby/issues/131))
-
+- Ability to printout Sigv4 Signature for debugging ([#149](https://github.com/opensearch-project/opensearch-ruby/issues/149))
 ### Changed
 ### Deprecated
 ### Removed
 ### Fixed
+
+### Security
+
+## [1.1.0]
+### Added
+- Added support for Amazon OpenSearch Serverless ([#131](https://github.com/opensearch-project/opensearch-ruby/issues/131))
+### Fixed
 - Sign validation requests when using AWS Sigv4 ([#134](https://github.com/opensearch-project/opensearch-ruby/pull/134))
 
 ### Security

data/README.md

@@ -1,101 +1,18 @@
-# OpenSearch Aws Sigv4 Client
+- [OpenSearch AWS Sigv4 Client](#opensearch-aws-sigv4-client)
+  - [Compatibility](#compatibility)
+  - [User Guide](#user-guide)
+  - [License](#license)
+# OpenSearch AWS Sigv4 Client
 
-The `opensearch-aws-sigv4` library provides an AWS Sigv4 client for [OpenSearch](http://opensearch.com).
+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).
 
 ## Compatibility
 
-The OpenSearch Aws Sigv4 Client is compatible with Ruby 2.5 and higher.
+See [COMPATIBILITY](../COMPATIBILITY.md).
 
-The client's API is compatible with OpenSearch's API versions from 1.0.0 till current.
+## User Guide
 
-See [COMPATIBILITY](../COMPATIBILITY.md) for more details.
-
-## Installation
-
-Install the package from [Rubygems](https://rubygems.org):
-
-    gem install opensearch-aws-sigv4
-
-To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://gembundler.com):
-
-    gem 'opensearch-aws-sigv4', git: 'git://github.com/opensearch-project/opensearch-ruby.git'
-
-or install it from a source code checkout:
-
-    git clone https://github.com/opensearch-project/opensearch-ruby
-    cd opensearch-ruby/opensearch-aws-sigv4
-    bundle install
-    rake install
-
-## Usage
-
-This library is an AWS Sigv4 wrapper for 
-[`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-ruby),
-which is a Ruby client for OpenSearch. The `OpenSearch::Aws::Sigv4Client` is, therefore, has all features of `OpenSearch::Client`.
-And since `opensearch-ruby` is a dependency of `opensearch-aws-sigv4`, you only need to install `opensearch-aws-sigv4`.
-
-### Amazon Managed OpenSearch
-Via the Sigv4 Client, you can interact with an Amazon Managed OpenSearch cluster just like would with a self-managed cluster:
-
-```ruby
-require 'opensearch-aws-sigv4'
-require 'aws-sigv4'
-
-signer = Aws::Sigv4::Signer.new(service: 'es',
-                                region: 'us-west-2',
-                                access_key_id: 'key_id',
-                                secret_access_key: 'secret')
-
-client = OpenSearch::Aws::Sigv4Client.new(
-  { host: 'https://your.amz-managed-opensearch.domain',
-    log: true }, 
-  signer)
-
-client.cluster.health
-
-client.transport.reload_connections!
-
-client.search q: 'test'
-```
-
-Please refer to [opensearch-ruby](https://github.com/opensearch-project/opensearch-ruby/blob/main/opensearch-ruby/README.md) documentation for further details.
-
-### Amazon OpenSearch Serverless
-You can also use this client to connect to Amazon OpenSearch Serverless (AOSS). Remember to change the service for the signer to `aoss`:
-
-```ruby
-require 'opensearch-aws-sigv4'
-require 'aws-sigv4'
-
-signer = Aws::Sigv4::Signer.new(service: 'aoss',
-                                region: 'us-west-2',
-                                access_key_id: 'key_id',
-                                secret_access_key: 'secret')
-
-client = OpenSearch::Aws::Sigv4Client.new(
-  { host: 'https://your.amz-opensearch-serverless.endpoint',
-    log: true },
-  signer)
-
-index = 'prime'
-client.indices.create(index: index)
-client.index(index: index, id: '1', body: { name: 'Amazon Echo', 
-                                            msrp: '5999', 
-                                            year: 2011 })
-client.search(body: { query: { match: { name: 'Echo' } } })
-client.delete(index: index, id: '1')
-client.indices.delete(index: index)
-
-# Most administrative commands like the ones below will result in a 404 error for AOSS
-client.cluster.stats
-client.cat.health
-```
-
-*NOTES:* AOSS does NOT support all API endpoints provided by a standard OpenSearch cluster. Refer to [AOSS Developer's Guide](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-genref.html) for more detail.
-
-## Development
-
-You can run `rake -T` to check the test tasks. Use `COVERAGE=true` before running a test task to check the coverage with Simplecov.
+See [USER_GUIDE](USER_GUIDE.md).
 
 ## License
 

data/USER_GUIDE.md

@@ -0,0 +1,59 @@
+- [User Guide](#user-guide)
+  - [Setup](#setup)
+  - [Usage](#usage)
+    - [Amazon OpenSearch Service](#amazon-opensearch-service)
+# User Guide
+## Setup
+
+To add the gem to your project, install it using [RubyGems](https://rubygems.org/):
+
+```
+gem install opensearch-aws-sigv4
+```
+
+or add it to your Gemfile:
+```
+gem opensearch-aws-sigv4
+```
+and run:
+```
+bundle install
+```
+
+## Usage
+
+This library is an AWS Sigv4 wrapper for [`opensearch-ruby`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-ruby), which is a Ruby client for OpenSearch. The `OpenSearch::Aws::Sigv4Client`, therefore, has all features of `OpenSearch::Client`.
+
+### Amazon OpenSearch Service
+To sign requests for the Amazon OpenSearch Service:
+
+```ruby
+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')
+
+client = OpenSearch::Aws::Sigv4Client.new({
+    host: 'https://your.amz-managed-opensearch.domain', # serverless endpoint for OpenSearch Serverless
+    log: true
+}, 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 })
+
+# search for the document
+client.search(body: { query: { match: { name: 'Echo' } } })
+
+# delete the document
+client.delete(index: index, id: '1')
+
+# delete the index
+client.indices.delete(index: index)
+```

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

@@ -10,7 +10,7 @@
 module OpenSearch
   module Aws
     module Sigv4
-      VERSION = '1.1.0'.freeze
+      VERSION = '1.2.0'.freeze
     end
   end
 end

data/lib/opensearch-aws-sigv4.rb

@@ -39,12 +39,16 @@ module OpenSearch
       # @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.
-      def initialize(transport_args = {}, sigv4_signer, &block)
+      # @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
 
         @sigv4_signer = sigv4_signer
+        @sigv4_debug = options[:sigv4_debug]
+        @logger = nil
         super(transport_args, &block)
       end
 
@@ -57,6 +61,8 @@ module OpenSearch
           headers: headers,
           body: signature_body)
         headers = (headers || {}).merge(signature.headers)
+
+        log_signature_info(signature)
         super(method, path, params, body, headers)
       end
 
@@ -72,6 +78,29 @@ module OpenSearch
         query_string = params.empty? ? '' : "#{Faraday::Utils::ParamsHash[params].to_query}"
         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" })
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opensearch-aws-sigv4
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Theo Truong
@@ -31,7 +31,7 @@ cert_chain:
   r+j7FLyKuk5DzIxiCp8QN5dU71BbGUmsHf/C5UV76WLPOFX/szeaHhPwpjR3sK7r
   5zLgCV1KP7cgDdCYMlmZGeSViU8NV+Yy8/ghrzGpqVw=
   -----END CERTIFICATE-----
-date: 2023-01-20 00:00:00.000000000 Z
+date: 2023-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sigv4
@@ -220,6 +220,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- USER_GUIDE.md
 - bin/opensearch_sigv4_console
 - lib/opensearch-aws-sigv4.rb
 - lib/opensearch-aws-sigv4/version.rb