oci 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 710c56b90571dcc168a349f896579265e90fe8d7
-  data.tar.gz: 4a77c01309de5a1b22e14b123c4038c5e714f0a1
+  metadata.gz: 122d8a6833bc35b30fd21376077be42796aa9aad
+  data.tar.gz: dd242ebfcdc8c4d2c5bf8bdba3a1765de19fd80f
 SHA512:
-  metadata.gz: 56cda480d05e618cfb517a1b1a13bc9137e13852e789dfdcbc78fab0eedfdabe4c9be1e2a28d342ac119003da1323c987edcee78d7ebc5b15b5b5a03a01769da
-  data.tar.gz: c47dc6cce662d968890c7b8f5c405db3eee70f70cc5a265cca84c43d35fe8a632cdf9d8757f089c26903d00697c9713c47cf667cc1efc61e4b5d40d43ce727ec
+  metadata.gz: f425a54f1c47f002b7260d0de1aa36de516e7205f8d1388f5ade8b64a39e93429341dc0d0bd17e3686a1182f646f6771decc54aefae08aa01c7a01715aea3337
+  data.tar.gz: 5988a3c9418b0f107c986e926d673914735602c17223eb886e7e2c1c466f942b550edf92b11e7887c4b00b898c98b4921c2f1ad009e17a5189554a58ab803c10

data/README.md

@@ -1,5 +1,5 @@
 # Oracle Cloud Infrastructure Ruby SDK
-**Version 2.1.0**
+**Version 2.1.1**
 
 This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Ruby SDK.
 
@@ -68,7 +68,15 @@ The following table provides details about some of the attributes of the SDK.
 	</tr>
 	<tr>
 		<td>Waiters</td>
-		<td>Responses for get requests support waiting for a particular states using {OCI::Response#wait_until wait_until}. See example code later in this file.</td>
+		<td>
+            Responses for get requests support waiting for a particular states using {OCI::Response#wait_until wait_until}. See example code later in this file.
+            <p>
+                In addition to using waiters, you can use the CompositeOperation classes in the SDK (e.g. {OCI::Core::ComputeClientCompositeOperations}) to perform
+                an action on a resource and wait for it to enter a particular state (or states). The CompositeOperation classes provide convenience methods so that
+                you yourself do not have to invoke an operation and then separately invoke a waiter. An example of using the CompositeOperations classes can be found
+                in the examples folder of the Ruby SDK <a href="https://docs.us-phoenix-1.oraclecloud.com/tools/ruby/latest/download/oci-ruby-sdk.zip">download</a>
+            </p>
+        </td>
 	</tr>
 	<tr>
 		<td>HTTP Client</td>
@@ -77,7 +85,7 @@ The following table provides details about some of the attributes of the SDK.
     <tr>
 		<td>Instance Principals Authentication</td>
 		<td>
-            The Ruby SDK supports <a href="">Instance Principals</a> authentication via the use of the {OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner} class. An example of using Instance Principals authentication can be found in the examples folder of the Ruby SDK <a href="https://docs.us-phoenix-1.oraclecloud.com/tools/ruby/latest/download/oci-ruby-sdk.zip">download</a>
+            The Ruby SDK supports <a href="https://docs.us-phoenix-1.oraclecloud.com/Content/Identity/Tasks/callingservicesfrominstances.htm">Instance Principals</a> authentication via the use of the {OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner} class. An example of using Instance Principals authentication can be found in the examples folder of the Ruby SDK <a href="https://docs.us-phoenix-1.oraclecloud.com/tools/ruby/latest/download/oci-ruby-sdk.zip">download</a>
         </td>
 	</tr>
     <tr>

data/lib/oci.rb

@@ -31,6 +31,12 @@ require 'oci/object_storage/transfer/transfer'
 module OCI
   class << self
     attr_accessor :sdk_name
+
+    # Defines the logger used for debugging for the OCI module.
+    # For example, log to STDOUT by setting this to Logger.new(STDOUT).
+    #
+    # @return [Logger]
+    attr_accessor :logger
   end
 end
 

data/lib/oci/api_client.rb

@@ -14,7 +14,27 @@ require_relative 'version'
 require_relative 'response'
 
 module OCI
+  # The base API client which contains functionality make requests and receive responses from OCI
+  # services. This client also handles request serialization and response deserialization
   class ApiClient
+    class << self
+      private
+
+      def get_rfc339_formatted_date_string_with_z_offset(date_time)
+        as_utc = date_time.to_time.utc
+
+        # Port of the Java SDK behaviour where we omit fractional seconds if they would be 0
+        return as_utc.iso8601 if as_utc.strftime('%L').to_i.zero?
+        as_utc.iso8601(3)
+      end
+
+      def cgi_escape_query_param(raw_value)
+        return CGI.escape(get_rfc339_formatted_date_string_with_z_offset(raw_value)) if raw_value.is_a?(DateTime)
+
+        CGI.escape(raw_value.to_s)
+      end
+    end
+
     # Maps collection format types (as per the collectionFormat types described here:
     # https://swagger.io/docs/specification/2-0/describing-parameters/) to the delimiters
     # we should use to separate values.
@@ -23,11 +43,13 @@ module OCI
     # a collection rather than transforming them into a single string
     VALID_COLLECTION_FORMATS = {
       multi: nil,
-      csv: ',',
-      ssv: ' ',
-      tsv: "\t",  # this is double quoted so it is interpreted as a tab rather than as a literal slash ('\') followed by a 't'
-      pipes: '|'
-    }
+      csv: ','.freeze,
+      ssv: ' '.freeze,
+      pipes: '|'.freeze,
+
+      # this is double quoted so it is interpreted as a tab rather than as a literal slash ('\') followed by a 't'
+      tsv: "\t".freeze
+    }.freeze
 
     # The Config object holding settings to be used in the API client.
     attr_accessor :config
@@ -61,6 +83,9 @@ module OCI
       @proxy_settings = proxy_settings
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+
     # Call an API with given options.
     #
     # @param [Symbol] http_method HTTP method/verb (e.g. :post, :get)
@@ -69,6 +94,7 @@ module OCI
     # @option opts [Hash] :header_params Header parameters
     # @option opts [Hash] :query_params Query parameters
     # @option opts [Hash] :form_params Form parameters
+    # @option opts [String] :operation_signing_strategy The signing strategy for the api operation
     # @option opts [Object] :body HTTP body in JSON
     # @option [Block] block Allow to receive data from http body as streaming
     #
@@ -78,8 +104,13 @@ module OCI
     def call_api(http_method, path, endpoint, opts, &block)
       http_method = http_method.to_sym.downcase
 
-      return call_api_inner(http_method, path, endpoint, opts, &block) if !using_instance_principals? && http_method != :get
-      return instance_principals_signer_wrapped_call { call_api_inner(http_method, path, endpoint, opts, &block) } if using_instance_principals? && http_method != :get
+      if http_method != :get
+        return call_api_inner(http_method, path, endpoint, opts, &block) unless using_instance_principals?
+
+        return instance_principals_signer_wrapped_call do
+          call_api_inner(http_method, path, endpoint, opts, &block)
+        end
+      end
 
       # Wrap get calls in a lambda that can be called later for paging
       # and wait_until.
@@ -93,7 +124,7 @@ module OCI
         return call_api_inner(http_method, path, endpoint, opts, &block)
       }
 
-      response = proc.call(nil) if !using_instance_principals?
+      response = proc.call(nil) unless using_instance_principals?
       response = instance_principals_signer_wrapped_call { proc.call(nil) } if using_instance_principals?
 
       response.api_call = proc
@@ -116,54 +147,132 @@ module OCI
       # an IO
       return model.to_io if (model.respond_to?(:read) || model.respond_to?(:write)) && model.respond_to?(:to_io)
 
-      if model.is_a?(Array)
-        local_body = model.map{|m| object_to_hash(m) }
-      else
-        local_body = object_to_hash(model)
-      end
+      local_body = if model.is_a?(Array)
+                     model.map { |m| object_to_hash(m) }
+                   else
+                     object_to_hash(model)
+                   end
+
       local_body.to_json
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
 
     # Builds the client info string to be sent with each request.
     def build_request_id
-      return SecureRandom.uuid.gsub!('-', '').upcase
+      SecureRandom.uuid.delete!('-').upcase
     end
 
     # Builds the client info string to be sent with each request.
     def build_user_info
-      return "Oracle-RubySDK/#{VERSION}"
+      "Oracle-RubySDK/#{VERSION}"
     end
 
     # Build the user agent string to be send with each request.
     def build_user_agent
       agent = "#{build_user_info}#{OCI.sdk_name} (ruby #{RUBY_VERSION}; #{RUBY_PLATFORM})"
-
-      if config.additional_user_agent
-        agent = "#{agent} #{config.additional_user_agent}"
-      end
+      agent = "#{agent} #{config.additional_user_agent}" if config.additional_user_agent
 
       agent
     end
 
     def self.build_collection_params(collection, collection_format)
-      if collection_format.nil? || !VALID_COLLECTION_FORMATS.has_key?(collection_format.to_sym)
+      if collection_format.nil? || !VALID_COLLECTION_FORMATS.key?(collection_format.to_sym)
         raise "Invalid collection_format: #{collection_format}. Must be one of: #{VALID_COLLECTION_FORMATS.keys}"
       end
 
-      if collection_format == :multi
-        return collection
-      else
-        return collection.join(VALID_COLLECTION_FORMATS[collection_format.to_sym])
+      return collection if collection_format == :multi
+
+      collection.join(VALID_COLLECTION_FORMATS[collection_format.to_sym])
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+
+    def self.append_query_params(url, query_params)
+      return url if query_params.empty?
+
+      # First divide our query params into ones where the param value is a simple value (e.g. a string), an array or a hash.
+      # The params  where the value is a hash are, for example, tags we need to handle differently for inclusion in the query
+      # string. We also need to handle array params differently in the query string since the values should appear as separate entries
+      # in the query string with the same key (this corresponds to using collectionFormat=multi in Swagger)
+      #
+      # An example query_params is:
+      #
+      #   {
+      #       "stuff" => "things",
+      #       "anArrayType" => ["hello", "world"]
+      #       "definedTags" => { "tag1" => ["val1", "val2", "val3"], "tag2" => ["val1"] },
+      #       "definedTagsExists" => { "tag3" => true, "tag4" => true }
+      #   }
+      #
+      # So our simple_params will be: { "stuff" => "things" }
+      # And our array_params will be: { "anArrayType" => ["hello", "world"]}
+      # And our hash_params will be: { "definedTags" => { "tag1" => ["val1", "val2", "val3"], "tag2" => ["val1"] }, "definedTagsExists" => { "tag3" => true, "tag4" => true } }
+      simple_params = query_params.select { |_k, v| !v.is_a?(Hash) && !v.is_a?(Array) }.to_h
+      array_params = query_params.select { |_k, v| v.is_a?(Array) }.to_h
+      hash_params = query_params.select { |_k, v| v.is_a?(Hash) }.to_h
+
+      # Simple params just go key to value
+      base_query_string = ''
+
+      unless simple_params.empty?
+        base_query_string << simple_params.map { |k, v| "#{k}=#{cgi_escape_query_param(v)}" }.join('&')
+      end
+
+      # Using the previous comment:
+      #   k = "anArrayType", v = ["hello", "world"]
+      #
+      # And we want query string params like #{k}=#{v[0]}&#{k}=#{v[1]}&#{k}=#{v[2]}...
+      # So the same key is repeated, but each value is a different value from the array
+      array_params.each do |k, v|
+        v.each do |query_string_val|
+          base_query_string << '&' unless base_query_string.empty?
+          base_query_string << "#{k}=#{cgi_escape_query_param(query_string_val)}"
+        end
+      end
+
+      # Using the previous comment:
+      #    k = "definedTags", v = { "tag1" => [...] }
+      #
+      # Hash params are exploded as follows:
+      #
+      #    - If value in v is an array then we explode the content like: #{k}.#{v.key}=#{v.value[0]}&#{k}.#{v.key}=#{v.value[1]}&... so that there is
+      #      one query string parameter per item in the array
+      #    - If value in v is not an array then we explode the content like: #{k}.#{v.key}=#{v.value}
+      hash_params.each do |k, v|
+        v.each do |tag_key, tag_val|
+          # TODO: Should this be ERB::Util.url_encode instead? CGI.escape gives "+" here but url_encode will give %20
+          # CGI.escape is what we've been using until now, and it looks like it works...A literal "+" in the string will
+          # be encoded to %2B
+          query_string_val = if tag_val.is_a?(Array)
+                               # to_s tag_key to avoid errors around implicit conversion of symbols to strings
+                               tag_val.map do |tv|
+                                 "#{k}.#{cgi_escape_query_param(tag_key)}=#{cgi_escape_query_param(tv)}"
+                               end.join('&')
+                             else
+                               "#{k}.#{cgi_escape_query_param(tag_key)}=#{cgi_escape_query_param(tag_val)}"
+                             end
+          base_query_string << '&' unless base_query_string.empty?
+          base_query_string << query_string_val
+        end
       end
+
+      url << '?' unless base_query_string.empty?
+      url << base_query_string
+
+      url
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
 
     private
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity
     def call_api_inner(http_method, path, endpoint, opts, &block)
       query_params = opts[:query_params] || {}
       header_params = @default_headers.merge(opts[:header_params] || {})
       form_params = opts[:form_params] || {}
       body = opts[:body] || nil
+      operation_signing_strategy = opts[:operation_signing_strategy] || nil
 
       url = ApiClient.append_query_params(build_request_url(path, endpoint), query_params)
       uri = URI(url)
@@ -189,18 +298,13 @@ module OCI
       if body.respond_to?(:read) && body.respond_to?(:write)
         request.body_stream = body
       else
-        if %i[post, put, delete, patch].include?(http_method)
-          body = build_request_body(header_params, form_params, body)
-        end
-
+        body = build_request_body(header_params, form_params, body) if %i[post put delete patch].include?(http_method)
         request.body = body
       end
 
-      if @config.logger
-        @config.logger.debug "HTTP request body param ~BEGIN~\n#{body}\n~END~\n"
-      end
+      @config.logger.debug "HTTP request body param ~BEGIN~\n#{body}\n~END~\n" if @config.logger
 
-      @signer.sign(http_method, url, header_params, body)
+      @signer.sign(http_method, url, header_params, body, operation_signing_strategy)
 
       header_params.each do |key, value|
         request[key.to_s] = value
@@ -214,8 +318,8 @@ module OCI
 
       unless @request_option_overrides.empty?
         http.methods.grep(/\A(\w+)=\z/) do |meth|
-          key = $1.to_sym
-          @request_option_overrides.key?(key) or next
+          key = Regexp.last_match(1).to_sym
+          @request_option_overrides.key?(key) || next
           http.__send__(meth, @request_option_overrides[key])
         end
       end
@@ -277,6 +381,7 @@ module OCI
       return handle_success_response(request, response_ref, opts[:return_type]) if success?(response_ref)
       handle_non_success_response(request, response_ref)
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity
 
     def get_http_object(hostname, port)
       return Net::HTTP.new(hostname, port) if @proxy_settings.nil?
@@ -313,9 +418,7 @@ module OCI
       processed_keys = {}
 
       response.each_header do |key, value|
-        if key.start_with?(prefix)
-          processed_keys[key[prefix_size..-1]] = value
-        end
+        processed_keys[key[prefix_size..-1]] = value if key.start_with?(prefix)
       end
 
       processed_keys.each do |key, value|
@@ -348,12 +451,16 @@ module OCI
     def handle_success_response(request, response, return_type)
       data = return_type ? deserialize(request, response, return_type) : nil
 
-      @config.logger.debug("API Response Received:\nData: #{data.inspect}\nStatus code: #{response.code}\nHeaders: #{response.header}") \
-        if @config.logger
+      if @config.logger
+        @config.logger.debug(
+          "API Response Received:\nData: #{data.inspect}\nStatus code: #{response.code}\nHeaders: #{response.header}"
+        )
+      end
 
       Response.new(response.code.to_i, response.header, data)
     end
 
+    # rubocop:disable Metrics/AbcSize
     def handle_non_success_response(request, response)
       # For errors, we expect a plain JSON object so pass 'Object' here in order to serialize it into a hash
       data = deserialize(request, response, 'Object')
@@ -384,78 +491,7 @@ module OCI
         )
       end
     end
-
-    def self.append_query_params(url, query_params)
-      if query_params.empty?
-        url
-      else
-        # First divide our query params into ones where the param value is a simple value (e.g. a string), an array or a hash.
-        # The params  where the value is a hash are, for example, tags we need to handle differently for inclusion in the query
-        # string. We also need to handle array params differently in the query string since the values should appear as separate entries
-        # in the query string with the same key (this corresponds to using collectionFormat=multi in Swagger)
-        #
-        # An example query_params is:
-        #
-        #   {
-        #       "stuff" => "things",
-        #       "anArrayType" => ["hello", "world"]
-        #       "definedTags" => { "tag1" => ["val1", "val2", "val3"], "tag2" => ["val1"] },
-        #       "definedTagsExists" => { "tag3" => true, "tag4" => true }
-        #   }
-        #
-        # So our simple_params will be: { "stuff" => "things" }
-        # And our array_params will be: { "anArrayType" => ["hello", "world"]}
-        # And our hash_params will be: { "definedTags" => { "tag1" => ["val1", "val2", "val3"], "tag2" => ["val1"] }, "definedTagsExists" => { "tag3" => true, "tag4" => true } }
-        simple_params = query_params.select { |k,v| !v.is_a?(Hash) && !v.is_a?(Array) }.to_h
-        array_params = query_params.select { |k,v| v.is_a?(Array) }.to_h
-        hash_params = query_params.select { |k,v| v.is_a?(Hash) }.to_h
-
-        # Simple params just go key to value
-        base_query_string = ''
-        base_query_string << simple_params.map{|k,v| "#{k}=#{self.cgi_escape_query_param(v)}"}.join('&') unless simple_params.empty?
-
-        # Using the previous comment:
-        #   k = "anArrayType", v = ["hello", "world"]
-        #
-        # And we want query string params like #{k}=#{v[0]}&#{k}=#{v[1]}&#{k}=#{v[2]}...
-        # So the same key is repeated, but each value is a different value from the array
-        array_params.each do |k,v|
-          v.each do |query_string_val|
-            base_query_string << '&' unless base_query_string.empty?
-            base_query_string << "#{k}=#{self.cgi_escape_query_param(query_string_val)}"
-          end
-        end
-
-        # Using the previous comment:
-        #    k = "definedTags", v = { "tag1" => [...] }
-        #
-        # Hash params are exploded as follows:
-        #
-        #    - If value in v is an array then we explode the content like: #{k}.#{v.key}=#{v.value[0]}&#{k}.#{v.key}=#{v.value[1]}&... so that there is
-        #      one query string parameter per item in the array
-        #    - If value in v is not an array then we explode the content like: #{k}.#{v.key}=#{v.value}
-        hash_params.each do |k,v|
-          v.each do |tag_key, tag_val|
-            # TODO: Should this be ERB::Util.url_encode instead? CGI.escape gives "+" here but url_encode will give %20
-            # CGI.escape is what we've been using until now, and it looks like it works...A literal "+" in the string will
-            # be encoded to %2B
-            query_string_val = if tag_val.is_a?(Array)
-                                  # to_s tag_key to avoid errors around implicit conversion of symbols to strings
-                                  tag_val.map { |tv| "#{k}.#{self.cgi_escape_query_param(tag_key)}=#{self.cgi_escape_query_param(tv)}" }.join('&')
-                                else
-                                  "#{k}.#{self.cgi_escape_query_param(tag_key)}=#{self.cgi_escape_query_param(tag_val)}"
-                                end
-            base_query_string << '&' unless base_query_string.empty?
-            base_query_string << query_string_val
-          end
-        end
-
-        url << '?' unless base_query_string.empty?
-        url << base_query_string
-
-        url
-      end
-    end
+    # rubocop:enable Metrics/AbcSize
 
     # Check if the given MIME is a JSON MIME.
     # JSON MIME examples:
@@ -468,6 +504,9 @@ module OCI
       !(mime =~ /\Aapplication\/json(;.*)?\z/i).nil?
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+
     # Deserialize the response to the given return type.
     #
     # @param [Response] response HTTP response
@@ -494,9 +533,9 @@ module OCI
       end
 
       begin
-        data = JSON.parse("[#{body}]", :symbolize_names => true)[0]
+        data = JSON.parse("[#{body}]", symbolize_names: true)[0]
       rescue JSON::ParserError
-        if %w(String Date DateTime).include?(return_type)
+        if %w[String Date DateTime].include?(return_type)
           data = body
         else
           # If we received an error here then we received a response from the OCI service that
@@ -522,15 +561,16 @@ module OCI
 
       OCI::Internal::Util.convert_to_type return_type, data
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/EmptyLines
 
     def build_request_url(path, endpoint)
       # Add leading and trailing slashes to path
       path = "/#{path}".gsub(/\/+/, '/')
+      endpoint = endpoint.chop if endpoint.end_with? '/'
 
-      if endpoint.end_with? '/'
-        endpoint = endpoint.chop
-      end
+      # rubocop:disable Lint/UriEscapeUnescape
       URI.encode(endpoint + path)
+      # rubocop:enable Lint/UriEscapeUnescape
     end
 
     # Builds the HTTP request body
@@ -542,7 +582,8 @@ module OCI
     def build_request_body(header_params, form_params, body)
       # http form
       if header_params['content-type'] == 'application/x-www-form-urlencoded' ||
-          header_params['content-type'] == 'multipart/form-data'
+         header_params['content-type'] == 'multipart/form-data'
+
         data = {}
         form_params.each do |key, value|
           case value
@@ -583,7 +624,7 @@ module OCI
         begin
           return yield
         rescue OCI::Errors::ServiceError => e
-          raise if attempt >= (max_attempts - 1)  # .times is zero-based
+          raise if attempt >= (max_attempts - 1) # .times is zero-based
           raise if e.status != 401
 
           @signer.refresh_security_token
@@ -591,21 +632,5 @@ module OCI
         end
       end
     end
-
-    def self.get_rfc339_formatted_date_string_with_z_offset(date_time)
-      as_utc = date_time.to_time.utc
-
-      # Port of the Java SDK behaviour where we omit fractional seconds if they would be 0
-      return as_utc.iso8601() if as_utc.strftime('%L').to_i == 0
-      as_utc.iso8601(3)
-    end
-
-    def self.cgi_escape_query_param(raw_value)
-      if raw_value.is_a?(DateTime)
-        CGI.escape(get_rfc339_formatted_date_string_with_z_offset(raw_value))
-      else
-        CGI.escape(raw_value.to_s)
-      end
-    end
   end
 end