oci 2.0.6 → 2.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38b3af475a0f7eb30b1f26b775ae4121b5fdb7f8
-  data.tar.gz: 245eb1ec30aacc7266559e3f9a8669593282fd30
+  metadata.gz: 38997be752356f7675ae441e8484117e64d915db
+  data.tar.gz: a69876808a735db9203b22f513c5001f87c1dd6d
 SHA512:
-  metadata.gz: 45e486bdf5f719d842281e33fb05b98433346d786018009abb5d7c9b64b3d19dad1db37fa35d248f215baa5623fc78708e8f2136c6a6072ae075fcea7787c898
-  data.tar.gz: 009fdb794589d0821d5c789e3ea332a2a62acb02f4c7ca3f8a06790442594add8e3af721d97c0c34ec193d6e91a57d97d89e865f53449ed076979705a5caf82f
+  metadata.gz: 2576ec59cbd7d9add589c6ec00d8c710804bfec442b89cb361cfd091a0e41e7fe1ca46ddbd882136378acc751794ef2ecec709d40f404d90584e992721f949a0
+  data.tar.gz: 45c2aa5111c5fc29fc99acfe918b5f7c8ce66a815df125e472b99801f9083b5229dcf0c7d71cd9be959b09fb240f1b18fe0637e0cc18fdb4d80e286e8d3172e5

data/README.md

@@ -1,5 +1,5 @@
 # Oracle Cloud Infrastructure Ruby SDK
-**Version 2.0.6**
+**Version 2.0.7**
 
 This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Ruby SDK.
 
@@ -13,6 +13,7 @@ The Ruby SDK supports the following services:
 * Identity and Access Management Service
 * Load Balancing Service
 * Object Storage Service
+* Domain Name System Service
 
 **Licensing:** This SDK and sample is dual licensed under the Universal Permissive License 1.0 and the Apache License.
 
@@ -55,6 +56,27 @@ The following table provides details about some of the attributes of the SDK.
 		<td>The Ruby SDK uses Net::HTTP for HTTP requests, if needed, options may be passed to each Net::HTTP by specifying them in {OCI::ApiClient#request_option_overrides ApiClient.request_option_overrides}.</br>
 		Please check http://ruby-doc.org/stdlib-2.4.1/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start for the supported options.</td>
 	</tr>
+    <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>
+        </td>
+	</tr>
+    <tr>
+		<td>Upload Manager</td>
+		<td>
+            The Object Storage service supports multipart uploads to make large object uploads easier by splitting the large object into parts. The Ruby SDK supports raw multipart upload operations for advanced use cases, as well as a higher-level upload class that uses the multipart upload APIs.
+            <p>
+                <a href="https://docs.us-phoenix-1.oraclecloud.com/Content/Object/Tasks/managingmultipartuploads.htm">Managing Multipart Uploads</a> provides links to the APIs used for raw multipart upload operations. Higher-level uploads can be performed using the {OCI::ObjectStorage::Transfer::UploadManager}. 
+            </p>
+            <p>
+                The UploadManager simplifies interaction with the Object Storage service by abstracting away the method used to upload objects and can handle uploading an entire object at once, or in multiple parts if it is of sufficient size (which is configurable via a {OCI::ObjectStorage::Transfer::UploadManagerConfig} object). In the latter case, the UploadManager will split a large object into parts for you, upload the parts in parallel, and then recombine and commit the parts as a single object in Object Storage.
+            </p>
+            <p>
+                Examples of using the Upload Manager 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>
 </tbody>
 </table>
 

data/lib/oci.rb

@@ -15,22 +15,19 @@ require 'oci/version'
 require 'oci/waiter'
 
 require 'oci/auth/auth'
-
 require 'oci/audit/audit'
 require 'oci/core/core'
 require 'oci/database/database'
+require 'oci/dns/dns'
 require 'oci/identity/identity'
 require 'oci/load_balancer/load_balancer'
 require 'oci/object_storage/object_storage'
+require 'oci/object_storage/transfer/transfer'
 
 # Top level module for the Oracle Cloud Infrastructure SDK
 module OCI
-  @@sdk_name = ''
-  def self.sdk_name
-    @@sdk_name
-  end
-  def self.sdk_name=(value)
-    @@sdk_name = value
+  class << self
+    attr_accessor :sdk_name
   end
 end
 

data/lib/oci/api_client.rb

@@ -14,6 +14,20 @@ require_relative 'response'
 
 module OCI
   class ApiClient
+    # 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.
+    #
+    # The :multi type contains no delimiter because this means we should preserve values as
+    # 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: '|'
+    }
+
     # The Config object holding settings to be used in the API client.
     attr_accessor :config
 
@@ -113,6 +127,18 @@ module OCI
       agent
     end
 
+    def self.build_collection_params(collection, collection_format)
+      if collection_format.nil? || !VALID_COLLECTION_FORMATS.has_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])
+      end
+    end
+
     private
 
     def call_api_inner(http_method, path, endpoint, opts, &block)
@@ -145,7 +171,7 @@ module OCI
       if body.respond_to?(:read) && body.respond_to?(:write)
         request.body_stream = body
       else
-        if %i[post, put, delete].include?(http_method)
+        if %i[post, put, delete, patch].include?(http_method)
           body = build_request_body(header_params, form_params, body)
         end
 
@@ -253,23 +279,42 @@ module OCI
       if query_params.empty?
         url
       else
-        # First divide our query params into ones where the param value is and isn't 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. An example query_params is:
+        # 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 non_hash_params will be: { "stuff" => "things" }
+        # 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 } }
-        non_hash_params = query_params.select { |k,v| !v.is_a?(Hash) }.to_h
+        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 << non_hash_params.map{|k,v| "#{k}=#{CGI.escape(v.to_s)}"}.join('&') unless non_hash_params.empty?
+        base_query_string << simple_params.map{|k,v| "#{k}=#{CGI.escape(v.to_s)}"}.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}=#{CGI.escape(query_string_val)}"
+          end
+        end
 
         # Using the previous comment:
         #    k = "definedTags", v = { "tag1" => [...] }

data/lib/oci/auth/auth.rb

@@ -1,7 +1,10 @@
 # Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 
 module OCI
-  module Audit
+  # The Auth module contains classes to handle different authentication
+  # methods, for example using instance principals instead of an API key,
+  # against OCI services
+  module Auth
   end
 end
 
@@ -13,4 +16,4 @@ require 'oci/auth/url_based_certificate_retriever'
 
 require 'oci/auth/signers/security_token_signer'
 require 'oci/auth/signers/x509_federation_client_based_security_token_signer'
-require 'oci/auth/signers/instance_principals_security_token_signer'
+require 'oci/auth/signers/instance_principals_security_token_signer'

data/lib/oci/auth/federation_client.rb

@@ -22,7 +22,7 @@ module OCI
     # it will vend the last requested token if it is not expired).
     class FederationClient
       # A supplier which vends a private and public key for signing token requests to Auth Service.
-      # The public key will be sent as part of the token request and the private key should be used to 
+      # The public key will be sent as part of the token request and the private key should be used to
       # sign all requests made with the token vended by this client
       # @return [OCI::Auth::SessionKeySupplier] A supplier which vends a private and public key for signing token requests to Auth Service
       attr_reader :session_key_supplier
@@ -122,4 +122,4 @@ module OCI
         end
     end
   end
-end
+end

data/lib/oci/auth/internal/auth_token_request_signer.rb

@@ -11,10 +11,10 @@ module OCI
           api_key = "#{tenancy_id}/fed-x509/#{fingerprint}"
           private_key = private_key_pem
 
-          generic_headers = [:"date", :"(request-target)"]
+          generic_headers = %i[date (request-target)]
           super(api_key, private_key, headers_to_sign_in_all_requests: generic_headers)
         end
       end
     end
   end
-end
+end

data/lib/oci/auth/security_token_container.rb

@@ -18,8 +18,8 @@ module OCI
 
       def token_valid?
         expiration_epoch_seconds = @jwt[0]['exp']
-        return expiration_epoch_seconds > Time.now.to_i
+        expiration_epoch_seconds > Time.now.to_i
       end
     end
   end
-end
+end

data/lib/oci/auth/session_key_supplier.rb

@@ -1,13 +1,12 @@
 # Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 
 require 'openssl'
-require 'thread'
 
 module OCI
   module Auth
     # A supplier which can vend a public and private key to be used for signing requests
     class SessionKeySupplier
-      PUBLIC_EXPONENT = 65537  # Ruby docs suggest 3, 17 or 65537
+      PUBLIC_EXPONENT = 65_537 # Ruby docs suggest 3, 17 or 65537
       def initialize(key_size: 2048)
         @key_size = key_size
         @refresh_lock = Mutex.new
@@ -22,7 +21,7 @@ module OCI
         private_key = @private_key
         @refresh_lock.unlock
 
-        {'private_key': private_key, 'public_key': private_key.public_key}
+        { 'private_key': private_key, 'public_key': private_key.public_key }
       end
 
       # Generates a new public and private key
@@ -34,4 +33,4 @@ module OCI
       end
     end
   end
-end
+end

data/lib/oci/auth/signers/instance_principals_security_token_signer.rb

@@ -21,7 +21,7 @@ module OCI
       # the token:
       #
       #   * Using the metadata endpoint for the instance (http://169.254.169.254/opc/v1) we can discover the region the instance is in, its leaf certificate and any intermediate certificates (for requesting the token) and the tenancy (as) that is in the leaf certificate.
-      #   * The signer leverages {OCI::Auth::FederationClient} so it can refresh the security token and also get the private key needed to sign requests (via the client's session_key_supplier)  
+      #   * The signer leverages {OCI::Auth::FederationClient} so it can refresh the security token and also get the private key needed to sign requests (via the client's session_key_supplier)
       class InstancePrincipalsSecurityTokenSigner < OCI::Auth::Signers::X509FederationClientBasedSecurityTokenSigner
         # The region the instance is in, as returned from the metadata endpoint for the instance (http://169.254.169.254/opc/v1/instance/region)
         # @return [String] The region for the instance
@@ -41,25 +41,38 @@ module OCI
         # @param [String] signing_strategy Whether this signer is used for Object Storage requests or not. Acceptable values are {OCI::BaseSigner::STANDARD} and {OCI::BaseSigner::OBJECT_STORAGE}. If not provided, defaults to {OCI::BaseSigner::STANDARD}
         # @param [Array<String>] headers_to_sign_in_all_requests An array of headers which will be signed in each request. If not provided, defaults to {OCI::BaseSigner::GENERIC_HEADERS}
         # @param [Array<String>] body_headers_to_sign An array of headers which should be signed on requests with bodies. If not provided, defaults to {OCI::BaseSigner::BODY_HEADERS}
-        def initialize(federation_endpoint: nil, federation_client_cert_bundle: nil, signing_strategy: OCI::BaseSigner::STANDARD, headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS, body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS)
-          @leaf_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(LEAF_CERTIFICATE_URL, private_key_url: LEAF_CERTIFICATE_PRIVATE_KEY_URL)
-          @intermediate_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(INTERMEDIATE_CERTIFICATE_URL)
+        def initialize(
+          federation_endpoint: nil,
+          federation_client_cert_bundle: nil,
+          signing_strategy: OCI::BaseSigner::STANDARD,
+          headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS,
+          body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS
+        )
+
+          @leaf_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(
+            LEAF_CERTIFICATE_URL, private_key_url: LEAF_CERTIFICATE_PRIVATE_KEY_URL
+          )
+          @intermediate_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(
+            INTERMEDIATE_CERTIFICATE_URL
+          )
           @session_key_supplier = OCI::Auth::SessionKeySupplier.new
-          @tenancy_id = OCI::Auth::Util.get_tenancy_id_from_certificate(@leaf_certificate_retriever.certificate)
+          @tenancy_id = OCI::Auth::Util.get_tenancy_id_from_certificate(
+            @leaf_certificate_retriever.certificate
+          )
 
           raw_region = Net::HTTP.get(URI(GET_REGION_URL)).strip
           symbolised_raw_region = raw_region.to_sym
-          if OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES.has_key?(symbolised_raw_region)
-            @region = OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES[symbolised_raw_region]
-          else
-            @region = raw_region
-          end
+          @region = if OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES.key?(symbolised_raw_region)
+                      OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES[symbolised_raw_region]
+                    else
+                      raw_region
+                    end
 
-          if federation_endpoint
-            @federation_endpoint = federation_endpoint
-          else
-            @federation_endpoint = "#{OCI::Regions.get_service_endpoint(@region, :Auth)}/v1/x509"
-          end
+          @federation_endpoint = if federation_endpoint
+                                   federation_endpoint
+                                 else
+                                   "#{OCI::Regions.get_service_endpoint(@region, :Auth)}/v1/x509"
+                                 end
 
           @federation_client = OCI::Auth::FederationClient.new(
             @federation_endpoint,
@@ -71,7 +84,7 @@ module OCI
           )
 
           super(
-            @federation_client, 
+            @federation_client,
             signing_strategy: signing_strategy,
             headers_to_sign_in_all_requests: headers_to_sign_in_all_requests,
             body_headers_to_sign: body_headers_to_sign
@@ -80,4 +93,4 @@ module OCI
       end
     end
   end
-end
+end

data/lib/oci/auth/signers/security_token_signer.rb

@@ -16,12 +16,19 @@ module OCI
         # @param [String] signing_strategy Whether this signer is used for Object Storage requests or not. Acceptable values are {OCI::BaseSigner::STANDARD} and {OCI::BaseSigner::OBJECT_STORAGE}. If not provided, defaults to {OCI::BaseSigner::STANDARD}
         # @param [Array<String>] headers_to_sign_in_all_requests An array of headers which will be signed in each request. If not provided, defaults to {OCI::BaseSigner::GENERIC_HEADERS}
         # @param [Array<String>] body_headers_to_sign An array of headers which should be signed on requests with bodies. If not provided, defaults to {OCI::BaseSigner::BODY_HEADERS}
-        def initialize(security_token, private_key, pass_phrase: nil, signing_strategy: OCI::BaseSigner::STANDARD, headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS, body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS)
+        def initialize(
+          security_token,
+          private_key,
+          pass_phrase: nil,
+          signing_strategy: OCI::BaseSigner::STANDARD,
+          headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS,
+          body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS
+        )
           super(
-            "ST$#{security_token}", 
-            private_key, 
-            pass_phrase: pass_phrase, 
-            signing_strategy: signing_strategy, 
+            "ST$#{security_token}",
+            private_key,
+            pass_phrase: pass_phrase,
+            signing_strategy: signing_strategy,
             headers_to_sign_in_all_requests: headers_to_sign_in_all_requests,
             body_headers_to_sign: body_headers_to_sign
           )
@@ -29,4 +36,4 @@ module OCI
       end
     end
   end
-end
+end

data/lib/oci/auth/signers/x509_federation_client_based_security_token_signer.rb

@@ -3,14 +3,13 @@
 require 'oci/base_signer'
 require 'openssl'
 require 'securerandom'
-require 'thread'
 
 require_relative 'security_token_signer'
 
 module OCI
   module Auth
     module Signers
-      # A SecurityTokenSigner where the token and private key are sourced from a provided federation_client. The token is retrieved via 
+      # A SecurityTokenSigner where the token and private key are sourced from a provided federation_client. The token is retrieved via
       # the client's security_token method, and the private key is retrieved by reading it from the session_key_supplier in the client.
       class X509FederationClientBasedSecurityTokenSigner < OCI::Auth::Signers::SecurityTokenSigner
         # Creates a new X509FederationClientBasedSecurityTokenSigner
@@ -19,7 +18,12 @@ module OCI
         # @param [String] signing_strategy Whether this signer is used for Object Storage requests or not. Acceptable values are {OCI::BaseSigner::STANDARD} and {OCI::BaseSigner::OBJECT_STORAGE}. If not provided, defaults to {OCI::BaseSigner::STANDARD}
         # @param [Array<String>] headers_to_sign_in_all_requests An array of headers which will be signed in each request. If not provided, defaults to {OCI::BaseSigner::GENERIC_HEADERS}
         # @param [Array<String>] body_headers_to_sign An array of headers which should be signed on requests with bodies. If not provided, defaults to {OCI::BaseSigner::BODY_HEADERS}
-        def initialize(federation_client, signing_strategy: OCI::BaseSigner::STANDARD, headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS, body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS)
+        def initialize(
+          federation_client,
+          signing_strategy: OCI::BaseSigner::STANDARD,
+          headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS,
+          body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS
+        )
           @federation_client = federation_client
           @refresh_lock = Mutex.new
 
@@ -67,4 +71,4 @@ module OCI
       end
     end
   end
-end
+end

data/lib/oci/auth/url_based_certificate_retriever.rb

@@ -3,7 +3,6 @@
 require 'net/http'
 require 'openssl'
 require 'securerandom'
-require 'thread'
 require 'uri'
 
 module OCI
@@ -50,11 +49,11 @@ module OCI
         pem
       end
 
-      # @return [OpenSSL::X509::Certificate] The certificate as an {OpenSSL::X509::Certificate}. This converts the 
+      # @return [OpenSSL::X509::Certificate] The certificate as an {OpenSSL::X509::Certificate}. This converts the
       # PEM-formatted string into a {OpenSSL::X509::Certificate}
       def certificate
         cert_pem = certificate_pem
-        OpenSSL::X509::Certificate.new(cert_pem) 
+        OpenSSL::X509::Certificate.new(cert_pem)
       end
 
       # @return [String] The private key as a PEM-formatted string
@@ -101,4 +100,4 @@ module OCI
       end
     end
   end
-end
+end

data/lib/oci/auth/util.rb

@@ -2,6 +2,8 @@
 
 module OCI
   module Auth
+    # Contains utility methods to support functionality in the {OCI::Auth} module, for example being able
+    # to extract information from certificates and scrubbing certificate information for calls to Auth Service
     module Util
       def self.get_tenancy_id_from_certificate(x509_certificate)
         subject_array = x509_certificate.subject.to_a
@@ -23,10 +25,10 @@ module OCI
 
       def self.sanitize_certificate_string(cert_string)
         cert_string.gsub('-----BEGIN CERTIFICATE-----', '')
-          .gsub('-----END CERTIFICATE-----', '')
-          .gsub('-----BEGIN PUBLIC KEY-----', '')
-          .gsub('-----END PUBLIC KEY-----', '')
-          .gsub("\n", '')
+                   .gsub('-----END CERTIFICATE-----', '')
+                   .gsub('-----BEGIN PUBLIC KEY-----', '')
+                   .gsub('-----END PUBLIC KEY-----', '')
+                   .delete("\n")
       end
     end
   end