oraclebmc 2.0.9 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0990773c9d867e8c1df64cefaa1388c9312938be
-  data.tar.gz: 53b013100afd6cb2c624db07e1a4bb1a0409f5ca
+  metadata.gz: b6aacb7956a1f987ff343b6806bde5538dd771a8
+  data.tar.gz: ebdf8ccf94e16332622d7937f465fdad9c486e62
 SHA512:
-  metadata.gz: 7973bb66cb99924dd867c0d10735026927028244fd16080da3c63b8d270f0c59e58a41979227fe781bae0774190760b892f167b610f170088b319590c6095f4d
-  data.tar.gz: 776201b2b5947e6973c97a8c2eca62da1d8cd89e0f389d0bb6f4882e4c38952474d585cd9d74768f9011d6345dd1e2b786ddb21cc5551b09834f51df6475352a
+  metadata.gz: db2e8a5b4414352d268ca630754908ab44a7e738edb94160bef4f7f15f9bfbdd1a7bc99ae0e44c9cea8807d9887863f54898cb444c79dac9d765554d818a0756
+  data.tar.gz: f59e6d888b1c8b735db7141218038376d5fbba1155d529484155d6ceb5d99d7f2292764561ed7fe81f37f6e0aa5be33522e887823638cb3ddeef494da10305f1

data/README_BMCS.md

@@ -1,5 +1,5 @@
 # Oracle Cloud Infrastructure Ruby SDK
-**Version 2.0.9**
+**Version 2.1.0**
 
 This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Ruby SDK.
 
@@ -41,7 +41,24 @@ The following table provides details about some of the attributes of the SDK.
 	</tr>
 	<tr>
 		<td>Errors</td>
-		<td>Unsuccessful requests will always raise an exception. {OracleBMC::Errors::ServiceError ServiceError} is raised when the service returns an error, and {OracleBMC::Errors::NetworkError NetworkError} is raised for network issues (such as failed host resolution).</td>
+        <td>
+            The main exception classes for the SDK are:
+            <ul>
+                <li>{OracleBMC::Errors::ServiceError ServiceError} is thrown when an OCI service returns a non-2xx HTTP status code</li>
+                <li>
+                    {OracleBMC::Errors::NetworkError NetworkError} is thrown when the issue is likely to be network-related rather than an application issue. This is defined as:
+                    <ul>
+                        <li>
+                            Requests that were sent from the SDK, but for which the outcome was not a response from an OCI service. Examples include a gateway timeout, read or connection timeouts from Net::HTTP, and any (Errno) exception that was generated by the request itself.
+                        </li>
+                        <li>Requests that result in a HTTP 408 (timeout)</li>
+                    </ul>
+                </li>
+                <li>
+                    {OracleBMC::Errors::ResponseParsingError ResponseParsingError} is thrown when a response is received from an OCI service, but the SDK could not parse it into the appropriate model type for inserting into an {OracleBMC::Response}
+                </li>
+            </ul>
+        </td>
 	</tr>
     <tr>
 		<td>Signing</td>
@@ -57,8 +74,7 @@ The following table provides details about some of the attributes of the SDK.
 	</tr>
 	<tr>
 		<td>HTTP Client</td>
-		<td>The Ruby SDK uses Net::HTTP for HTTP requests, if needed, options may be passed to each Net::HTTP by specifying them in {OracleBMC::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>
+		<td>The Ruby SDK uses Net::HTTP for HTTP requests. Information on how to configure the client, including configuring a proxy, can be found in the <b>Configuring the HTTP Client</b> section of this page</td>
 	</tr>
     <tr>
 		<td>Instance Principals Authentication</td>
@@ -71,7 +87,7 @@ The following table provides details about some of the attributes of the SDK.
 		<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 {OracleBMC::ObjectStorage::Transfer::UploadManager}. 
+                <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 {OracleBMC::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 {OracleBMC::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.
@@ -104,11 +120,11 @@ To use the Ruby SDK, you must have:
 
 ### Troubleshooting an Installation
 If you see "Unable to resolve dependencies”, you can install the dependencies manually:
-	
+
 	gem install inifile
 
 ## SDK modules and namespacing
-The top level module name for the Ruby SDK is `OCI`, however using `OracleBMC` as the top level namespace is also supported. For example, you can reference the configuration object as both `OCI::Config` and `OracleBMC::Config`. 
+The top level module name for the Ruby SDK is `OCI`, however using `OracleBMC` as the top level namespace is also supported. For example, you can reference the configuration object as both `OCI::Config` and `OracleBMC::Config`.
 
 Using `OCI` as the top level module name is preferred and it is also used in the SDK API Reference. Additionally, if you inspect the type of an SDK object it will always be reported as being under the `OCI::` module.
 
@@ -121,7 +137,7 @@ To use any of the APIs, you must supply a {OracleBMC::Config Config} object. You
 
 ## Forward Compatibility
 
-Some response fields are enum-typed. In the future, individual services may return values not covered by existing enums for that field. To address this possibility, every enum-type response field has an additional value named "UNKNOWN_ENUM_VALUE". If a service returns a value that is not recognized by your version of the SDK, then the response field will be set to this value. Please ensure that your code handles the "UNKNOWN_ENUM_VALUE" case if you have conditional logic based on an enum-typed field. 
+Some response fields are enum-typed. In the future, individual services may return values not covered by existing enums for that field. To address this possibility, every enum-type response field has an additional value named "UNKNOWN_ENUM_VALUE". If a service returns a value that is not recognized by your version of the SDK, then the response field will be set to this value. Please ensure that your code handles the "UNKNOWN_ENUM_VALUE" case if you have conditional logic based on an enum-typed field.
 
 ## Writing Your First Ruby Program with the SDK
 
@@ -149,9 +165,164 @@ Or you can create a {OracleBMC::Config Config} programmatically. Note that the g
 
 The default config file location is `~/.oci/config` (on Windows `C:\Users\{user}\.oci\config`).
 
-## Service Errors
+## Configuring the HTTP Client
+
+The underlying HTTP client used by the SDK can be configured by setting the {OracleBMC::ApiClient#request_option_overrides ApiClient.request_option_overrides} on the client. An example on how to do this, showing all supported options, is:
+
+    require 'oci'
+
+    identity = OracleBMC::Identity::IdentityService.new
+
+    identity.api_client.request_option_overrides = {
+      # The path to the PEM-formatted CA certificate file.
+      # The file can contain several CA certificates
+    	ca_file: '/path/to/pem/file',
+
+    	# The path to a directory of PEM-formatted CA certificate files
+    	ca_path_cert: '/path/to/cert/directory',
+
+    	# An OpenSSL::X509::Certificate object as client certificate
+      cert: OpenSSL::X509::Certificate.new(...),
+
+    	# The X509::Store to verify peer certificate.
+    	cert_store: OpenSSL::X509::Store.new(...),
+
+    	# One of the available ciphers from OpenSSL::SSL::SSLContext#ciphers
+    	ciphers: ...,
+
+    	close_on_empty_response: true,
+
+    	# An OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object
+    	key: ...,
+
+    	# The SSL timeout in seconds
+    	ssl_timeout: 60,
+
+    	# The SSL version to use. See OpenSSL::SSL::SSLContext#ssl_version
+    	ssl_version: ...,
+
+    	# The verify callback for the server certification verification
+    	verify_callback: ...,
+
+    	# The maximum depth for the certificate chain verification
+    	verify_depth: 3,
+
+    	# Either OpenSSL::SSL::VERIFY_PEER or OpenSSL::SSL::VERIFY_NONE
+    	# Using OpenSSL::SSL::VERIFY_NONE (i.e. not validating the SSL certificate) is not
+    	# recommended
+    	verify_mode: OpenSSL::SSL::VERIFY_PEER
+    }
+
+Note that these correspond to a subset of the keys that can be provided as `opts` to the `Net::HTTP` [start](https://ruby-doc.org/stdlib-2.4.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start) method.
+
+### Setting a proxy
+If the SDK is running in an environment which requires the use of a proxy server for outgoing HTTP requests, this can be configured by providing via:
+
+* Providing an environment variable; or
+* Providing an {OracleBMC::ApiClientProxySettings} object. Here is an example of the different ways to create this object:
+
+#### Proxy via environment variable
+As the the SDK uses `Net::HTTP`, the `http_proxy` environment variable can be used to specify a proxy:
+
+    export HTTP_PROXY="http://10.10.1.10:3128"
+
+When using the environment variable approach, no code changes need to be made.
+
+Note that this does not support providing a username and password to the proxy, *except* when using Ruby 2.5+ on Linux, FreeBSD or macOS (Darwin). Otherwise, if a username and password is required then the {OracleBMC::ApiClientProxySettings} object method can be used.
+
+#### Proxy via the ApiClientProxySettings object
+An {OracleBMC::ApiClientProxySettings} object can be used to capture proxy settings. Here are the different ways an object can be created:
+
+
+	# This creates an ApiClientProxySettings with a nil proxy address and will make the API client
+	# bypass all proxies
+	proxy_settings = OracleBMC::ApiClientProxySettings.new(nil)
+
+	# This creates an ApiClientProxySettings that will use the proxy at 10.10.1.10:3128 and will
+	# not provide a username and password to the proxy
+	proxy_settings = OracleBMC::ApiClientProxySettings.new("10.10.1.10", 3128)
+
+	# This creates an ApiClientProxySettings with a username and password. In Production, you should # use an appropriate password/secret management mechanism to vend the username and password
+	# rather than having the credentials in code
+	proxy_settings = OracleBMC::ApiClientProxySettings.new("10.10.1.10", 3128, "username", "pass")
+
+Once an {OracleBMC::ApiClientProxySettings} object has been created, it can be used when creating or modifying a client:
 
-Any operation resulting in a service error will cause an exception of type OracleBMC::Errors::ServiceError to be thrown by the SDK. For information about common service errors returned by OCI, see [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm). 
+	# At client creation time
+	identity = OracleBMC::Identity::IdentityService.new(proxy_settings: proxy_settings)
+
+	# When updating a client
+	identity.api_client.proxy_settings = proxy_settings
+
+	# The proxy_settings can also be nil'ed out. This will make the ApiClient fall back to
+	# using the http_proxy environment variable (if present)
+	identity.api_client.proxy_settings=. nil
+
+## Exceptions
+
+### Service Errors
+Any operation that receives a response with a non-2xx HTTP status code from an OCI service will cause an exception of type {OracleBMC::Errors::ServiceError ServiceError} to be thrown by the SDK. 
+
+For information about common service errors returned by OCI, see [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
+
+The key attributes to inspect when dealing with a {OracleBMC::Errors::ServiceError} are:
+
+* {OracleBMC::Errors::ServiceError#request_id request_id} if you need to contact Oracle about a particular request, please provide this request ID
+* {OracleBMC::Errors::ServiceError#status_code status_code} contains the HTTP status code of the response
+* {OracleBMC::Errors::ServiceError#service_code service_code} should contain a value from the *Error Code* field as described in the *API Errors* page
+* {OracleBMC::Errors::ServiceError#request_made request_made} contains the actual `Net::HTTPRequest` which was sent by the SDK
+
+You can also call {OracleBMC::Errors::ServiceError#to_s to_s} on the error to get a summary of the key information about the error.
+
+#### HTTP 3xx Responses
+The SDK will throw exceptions of type {OracleBMC::Errors::ServiceError ServiceError} on HTTP 3xx responses. This impacts operations that support conditional GETs. This includes {OracleBMC::ObjectStorage::ObjectStorageClient#get_object} and {OracleBMC::ObjectStorage::ObjectStorageClient#head_object} methods as these can return responses with a HTTP status code of 304 if passed an `if_none_match`, which corresponds to the current etag of the object or bucket.
+
+In order to account for this, you should catch {OracleBMC::Errors::ServiceError ServiceError} and check its `status_code` attribute for the HTTP status code. For example: 
+
+    require 'oraclebmc'
+
+    object_storage = OracleBMC::ObjectStorage::ObjectStorageClient.new
+
+    begin
+        get_object_response = object_storage.get_object('my_namespace', 'my_bucket', 'my_object', if_none_match: 'some_etag_value')
+    rescue OracleBMC::Errors::ServiceError => err
+        # Do nothing if the object exists but has not been modified (based on the etag value), otherwise raise the exception
+        raise if err.status_code != 304
+    end
+
+
+### Network Errors
+{OracleBMC::Errors::NetworkError NetworkError} is thrown when the issue is likely to be network related rather than an application issue. This is defined as:
+
+* Requests which were sent from the SDK but the outcome was not a response from an OCI service. Further examples of include:
+  * Gateway timeouts
+  * Read or connection timeouts
+  * Any {Errno} exception which was generated by making the request
+* Requests which resulted in a HTTP 408 (timeout)
+
+The key attributes to inspect when dealing with a {OracleBMC::Errors::NetworkError} are:
+
+* {OracleBMC::Errors::NetworkError#request_made request_made} and {OracleBMC::Errors::NetworkError#response_received response_received} contain the `Net::HTTPRequest` and `Net::HTTPResponse`, respectively
+* {OracleBMC::Errors::NetworkError#code code} contains the HTTP status code of the response
+
+You can also call {OracleBMC::Errors::NetworkError#to_s to_s} on the error to get a summary of the key information about the error. In addition, the {OracleBMC::Errors::NetworkError#cause NetworkError.cause} of the {OracleBMC::Errors::NetworkError NetworkError} can be inspected to see the original error that caused the {OracleBMC::Errors::NetworkError NetworkError} to be thrown.
+
+### Response Parsing Errors
+{OracleBMC::Errors::ResponseParsingError ResponseParsingError} is thrown when a response was received from an OCI service but the SDK could not parse it into the appropriate model type to put into an {OracleBMC::Response}. 
+
+The key attributes to inspect when dealing with a {OracleBMC::Errors::ResponseParsingError} are: 
+
+* {OracleBMC::Errors::ResponseParsingError#request_made request_made} and {OracleBMC::Errors::ResponseParsingError#response_received response_received} contain the `Net::HTTPRequest` and `Net::HTTPResponse`, respectively
+* {OracleBMC::Errors::ResponseParsingError#response_body response_body} contains the response data which failed to parse
+
+You can also call {OracleBMC::Errors::ResponseParsingError#to_s to_s} on the error to get a summary of the key information about the error. In addition, the {OracleBMC::Errors::ResponseParsingError#cause ResponseParsingError.cause} of the {OracleBMC::Errors::ResponseParsingError ResponseParsingError} can be inspected to see the original error that caused the {OracleBMC::Errors::ResponseParsingError ResponseParsingError} to be thrown.
+
+### Other Errors
+The other errors you may encounter while using the SDK are:
+
+* {OracleBMC::Errors::MaximumWaitTimeExceededError MaximumWaitTimeExceededError} when using {OracleBMC::Response#wait_until} or when using {OracleBMC::LoadBalancer::Util#wait_on_work_request}
+* {OracleBMC::Errors::WorkRequestFailedError WorkRequestFailedError} when using {OracleBMC::LoadBalancer::Util#wait_on_work_request}. The {OracleBMC::Errors::WorkRequestFailedError#work_request work_request} attribute can be inspected to get the actual work request details
+* {OracleBMC::Errors::MultipartUploadError MultipartUploadError} when using {OracleBMC::ObjectStorage::Transfer::UploadManager UploadManager}. The {OracleBMC::Errors::MultipartUploadError#errors errors} attribute can be inspected to see what errors occurred during the upload, and the {OracleBMC::Errors::MultipartUploadError#upload_id upload_id} can be used if you wish to try and resume the upload via the UploadManager's {OracleBMC::ObjectStorage::Transfer::UploadManager#resume resume} method
 
 ## Examples
 The example code in this section shows how various parts of the Ruby SDK work. More examples can be found in the SDK download.
@@ -344,6 +515,3 @@ Ways to get in touch:
 * [Stack Overflow](https://stackoverflow.com/): Please use the [oracle-cloud-infrastructure](https://stackoverflow.com/questions/tagged/oracle-cloud-infrastructure) and [oci-ruby-sdk](https://stackoverflow.com/questions/tagged/oci-ruby-sdk) tags in your post
 * [Developer Tools section](https://community.oracle.com/community/cloud_computing/bare-metal/content?filterID=contentstatus%5Bpublished%5D~category%5Bdeveloper-tools%5D&filterID=contentstatus%5Bpublished%5D~objecttype~objecttype%5Bthread%5D) of the Oracle Cloud forums
 * [My Oracle Support](https://support.oracle.com)
-
-
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oraclebmc
 version: !ruby/object:Gem::Version
-  version: 2.0.9
+  version: 2.1.0
 platform: ruby
 authors:
 - Oracle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-07 00:00:00.000000000 Z
+date: 2018-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oci
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 2.1.0
 description: "Ruby SDK for Oracle Cloud Infrastructure. \n  \n    This gem is deprecated
   and will no longer be maintained starting March 2018. Please move to 'oci' (https://rubygems.org/gems/oci)
   instead to avoid interruption."