ibm-cloud-sdk 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160845336c50ab1c67c274cb62fd5e52af7bf0d6e4b5a4a1b57c4ea3c5eb47db
-  data.tar.gz: 7762d522d6754815a4e19a927bdcce0d73a8c5a0d204980d44dfdf006d7254d4
+  metadata.gz: 49b6c34b47c964d6025eb8ca01efc3221fe33603c1c56b3e86167925f6132f60
+  data.tar.gz: df5e08b1f01c0e05fbec5e8f5887139dde7210be53b2cf538b0357b7efe5f0a1
 SHA512:
-  metadata.gz: f42fe440d6a3610c94b7336246eda2dfdf6f794afa501480e633563d3a25f2d27bc337ebf41f82b82dad3a3958c2dbbf094244da77021fbe188fffa5cb73d294
-  data.tar.gz: 7af6df6df99133b619aa62bcc03281dc58f8b1f79c1b26d57b6cbf490dfc85f0dbdd46d41306780d8ead81148d71bf9003b78b787d8d21a64c6974ac0fc546a7
+  metadata.gz: afe2bfaae5cb2a853cd7ba2523a2aed7f0da6f6c319d1c2d730993ab5dc93613e928a423a0a7e0310023e96ad71aaa2f8129b5908d0c767e3679fdae8fa063ec
+  data.tar.gz: 91d9e41682d13a1671d63c57fb2a4620b8b5f4d001c055036b7942b60a1e57b9e8a348a4615866851ff09389f6ed868ce7a62eff15b85c7bc8d564559f1180c2

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 All notable changes to the gem ibm-cloud-sdk-ruby will be documented here.
 
+## v0.1.7 - 2020-09-28
+- Added Logging in IBM Cloud
+- Add VCR to vpc spec
+- Add exception when status of response is not in 200 range or 404
+- Power IaaS Update docstrings, VM actions volumes
+
 ## v0.1.6 - 2020-09-23
 - Add PowerIaaS method to get instance info
 - Return region specific PowerVS storage types

data/Gemfile

@@ -5,3 +5,5 @@ gemspec
 
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
+gem 'vcr'
+gem 'webmock'

data/lib/ibm/cloud/sdk.rb

@@ -8,6 +8,7 @@ require "ibm/cloud/sdk/power_iaas"
 require "ibm/cloud/sdk/resource_controller"
 require "ibm/cloud/sdk/version"
 require "ibm/cloud/sdk/vpc/cloud_sdk"
+require "ibm/cloud/sdk/logging"
 
 module IBM
   module Cloud

data/lib/ibm/cloud/sdk/logging.rb

@@ -0,0 +1,21 @@
+require_relative 'null_logger'
+
+module IBM
+  module Cloud
+    module SDK
+      class << self
+        attr_writer :logger
+      end
+
+      def self.logger
+        @logger ||= NullLogger.new
+      end
+
+      module Logging
+        def logger
+          IBM::Cloud::SDK.logger
+        end
+      end
+    end
+  end
+end

data/lib/ibm/cloud/sdk/null_logger.rb

@@ -0,0 +1,19 @@
+require "logger"
+
+module IBM
+  module Cloud
+    module SDK
+      class NullLogger < Logger
+        def initialize(*_args)
+        end 
+
+        def add(*_args, &_block)
+        end 
+
+        def debug?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ibm/cloud/sdk/power_iaas.rb

@@ -1,7 +1,11 @@
+require_relative 'logging'
+
 module IBM
   module Cloud
     module SDK
       class PowerIaas < BaseService
+        include Logging
+
         # Create an API Client object for the Power IaaS service
         #
         # @param region [String] the IBM Power Cloud instance region
@@ -15,8 +19,12 @@ module IBM
           @region = region
           @token  = token
           @tenant = tenant
+          RestClient.log = logger
         end
 
+        # Get the API service Endpoint URL
+        #
+        # @return [String] Endpoint URL
         def endpoint
           "https://#{region.sub(/-\d$/, '')}.power-iaas.cloud.ibm.com/pcloud/v1"
         end
@@ -41,12 +49,15 @@ module IBM
 
         # Get an IBM Power Cloud PVM instance
         #
-        # @param pvm_instance_id [String] the PVM instance ID
+        # @param pvm_instance_id [String] PVM instance ID
         # @return [Hash] PVM Instances
         def get_pvm_instance(instance_id)
           get("cloud-instances/#{guid}/pvm-instances/#{instance_id}")
         end
 
+        # Perform 'start' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
         def start_pvm_instance(instance_id)
           post(
             "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
@@ -54,6 +65,9 @@ module IBM
           )
         end
 
+        # Perform 'stop' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
         def stop_pvm_instance(instance_id)
           post(
             "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
@@ -61,6 +75,22 @@ module IBM
           )
         end
 
+        # Perform 'immediate-shutdown' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
+        def immediate_shutdown_pvm_instance(instance_id)
+          post(
+            "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
+            {"action" => "immediate-shutdown"}.to_json
+          )
+        end
+
+        # Perform 'reboot' action on a PVMInstance
+        #
+        # This action has been deprecated and replaced by 'soft-reboot'
+        # and 'hard-reboot'
+        #
+        # @param pvm_instance_id [String] PVM instance ID
         def reboot_pvm_instance(instance_id)
           post(
             "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
@@ -68,10 +98,47 @@ module IBM
           )
         end
 
+        # Perform 'soft-reboot' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
+        def soft_reboot_pvm_instance(instance_id)
+          post(
+            "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
+            {"action" => "soft-reboot"}.to_json
+          )
+        end
+
+        # Perform 'hard-reboot' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
+        def hard_reboot_pvm_instance(instance_id)
+          post(
+            "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
+            {"action" => "hard-reboot"}.to_json
+          )
+        end
+
+        # Perform 'reset-state' action on a PVMInstance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
+        def reset_state_pvm_instance(instance_id)
+          post(
+            "cloud-instances/#{guid}/pvm-instances/#{instance_id}/action",
+            {"action" => "reset-state"}.to_json
+          )
+        end
+
+        # Create a new PVM instance
+        #
+        # @param instance_hash [Hash] New instance attributes
+        # @return [Hash] PVMInstance
         def create_pvm_instance(instance_hash)
           post("cloud-instances/#{guid}/pvm-instances", instance_hash.to_json)
         end
 
+        # Delete a PVM instance
+        #
+        # @param pvm_instance_id [String] PVM instance ID
         def delete_pvm_instance(instance_id)
           delete("cloud-instances/#{guid}/pvm-instances/#{instance_id}")
         end
@@ -89,7 +156,7 @@ module IBM
 
         # Get an IBM Power Cloud image
         #
-        # @param image_id [String] The ID of an Image
+        # @param image_id [String] Image ID
         # @return [Hash] Image
         def get_image(image_id)
           get("cloud-instances/#{guid}/images/#{image_id}")
@@ -97,6 +164,9 @@ module IBM
           nil
         end
 
+        # Delete an image from a cloud instance
+        #
+        # @param image_id [String] Image ID
         def delete_image(image_id)
           delete("cloud-instances/#{guid}/images/#{image_id}")
         end
@@ -114,7 +184,7 @@ module IBM
 
         # Get a specific volume
         #
-        # @param volume_id [String] The ID of a volume
+        # @param volume_id [String] Image ID
         # @return [Hash] Volume
         def get_volume(volume_id)
           get("cloud-instances/#{guid}/volumes/#{volume_id}")
@@ -122,7 +192,7 @@ module IBM
 
         # Delete a volume
         #
-        # @param volume_id [String] The ID of a volume
+        # @param volume_id [String] Volume ID
         def delete_volume(volume_id)
           delete("cloud-instances/#{guid}/volumes/#{volume_id}")
         end
@@ -135,6 +205,22 @@ module IBM
           post("cloud-instances/#{guid}/volumes", volume_hash.to_json)
         end
 
+        # Attach a volume
+        #
+        # @param pvm_instance_id [String] PVM Instance ID
+        # @param  volume_id [String] Volume ID
+        def attach_volume(pvm_instance_id, volume_id)
+          post("cloud-instances/#{guid}/volumes/#{volumd_id}")
+        end
+
+        # Detach a volume
+        #
+        # @param pvm_instance_id [String] PVM Instance ID
+        # @param  volume_id [String] Volume ID
+        def detach_volume(pvm_instance_id, volume_id)
+          delete("cloud-instances/#{guid}/volumes/#{volumd_id}")
+        end
+
         # Get all networks in an IBM Power Cloud instance
         #
         # @return [Array<Hash>] all networks for this IBM Power Cloud instance
@@ -147,7 +233,7 @@ module IBM
 
         # Get an IBM Power Cloud network
         #
-        # @param network_id [String] the network ID
+        # @param network_id [String] Network ID
         # @return [Hash] Network
         def get_network(network_id)
           get("cloud-instances/#{guid}/networks/#{network_id}")
@@ -161,42 +247,64 @@ module IBM
         end
 
         # Get a storage types list in IBM  Power Cloud.
-        # note: this mehod to be refactored under the common 
+        # note: this method to be refactored under the common
         # IBM::Cloud::SDK::PowerIaas.endpoint when the rest api become available.
         #
-        # @return [Hash] StorageType
+        # @return [Array<Hash>] StorageType
         def get_storage_types
           JSON.parse(RestClient.get("https://#{region.sub(/-\d$/, '')}.power-iaas.cloud.ibm.com/broker/v1/storage-types", headers))[region]
         end
 
+        # Create a new network
+        #
+        # @param network_hash [Hash] New network attributes
+        # @return [Hash] Network
         def create_network(network_hash)
           post("cloud-instances/#{guid}/networks", network_hash.to_json)
         end
 
+        # Delete a network
+        #
+        # @param network_id [String] Network ID
         def delete_network(network_id)
           delete("cloud-instances/#{guid}/networks/#{network_id}")
         end
 
+        # Get all ports for a network
+        #
+        # @param network_id [String] Network ID
+        # @return [Array<Hash>] NetworkPort
         def get_network_ports(network_id)
           get("cloud-instances/#{guid}/networks/#{network_id}/ports")["ports"]
         end
 
+        # List the tenant's SSH Keys
+        #
+        # @return [Array<Hash>] SSHKey
         def get_ssh_keys
           get("tenants/#{tenant}")["sshKeys"]
         end
 
+        # Add a new SSH key to the tenant
+        #
+        # @param name [String] User defined name for the SSH key
+        # @param sshkey [String] SSH RSA key
+        # @return [Hash] SSHKey
         def create_key_pair(name, sshkey)
           payload = {"name" => name, "sshkey" => sshkey}
           post("tenants/#{tenant}/sshkeys", payload.to_json)
         end
 
+        # Delete SSH key from the tenant
+        #
+        # @param sshkey_name [String] SSH Key name
         def delete_key_pair(name)
           delete("tenants/#{tenant}/sshkeys/#{name}")
         end
 
         # Get an SAP profile
         #
-        # @param sap_profile_id [String] The ID of an SAP profile
+        # @param sap_profile_id [String] SAP Profile ID
         # @return [Hash] SAP profile
         def get_sap_profile(sap_profile_id)
           get("cloud-instances/#{guid}/sap/#{sap_profile_id}")
@@ -219,7 +327,7 @@ module IBM
         # instance is the standard 'PVMInstance' type and can be accessed via
         # the existing *_pvm_instance methods.
         #
-        # @param sap_profile_id [String] The ID of an SAP profile
+        # @param sap_profile_id [String] SAP Profile ID
         # @return [Hash] SAP profile
         def create_sap_pvm_instance(instance_hash)
           post("cloud-instances/#{guid}/sap", instance_hash.to_json)

data/lib/ibm/cloud/sdk/version.rb

@@ -1,7 +1,7 @@
 module IBM
   module Cloud
     module SDK
-      VERSION = "0.1.6"
+      VERSION = "0.1.7"
     end
   end
 end

data/lib/ibm/cloud/sdk/vpc.rb

@@ -4,6 +4,7 @@
 require_relative 'vpc/base_vpc'
 require_relative 'vpc/base_collection'
 require_relative 'vpc/base_instance'
+require_relative 'vpc/exceptions'
 
 require_relative 'vpc/floatingips'
 require_relative 'vpc/flowlogcollectors'

data/lib/ibm/cloud/sdk/vpc/exceptions.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module IBM
+  module Cloud
+    module SDK
+      module VPC
+        # Module to contain all custom exception classes.
+        module Exceptions
+          # An exception for http with a response attribute.
+          # @param response [IBM::Cloud::SDK::VPC::Response] The original response object.
+          # @param msg [String] A human readable message.
+          class ExceptionWithResponse < RuntimeError
+            def initialize(response, msg)
+              @response = response
+              super(msg)
+            end
+            # @return [IBM::Cloud::SDK::VPC::Response] The response
+            attr_reader :response
+          end
+
+          # An exception for http status errors with a response attribute.
+          # @param response [IBM::Cloud::SDK::VPC::Response] The original response object.
+          class HttpStatusError < ExceptionWithResponse
+            def initialize(response)
+              msg = "Invalid status #{response.code} for url \"#{response.url}\", #{response.reason}. #{response.body}"
+              super(response, msg)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ibm/cloud/sdk/vpc/helpers/connection.rb

@@ -8,8 +8,10 @@ module IBM
   module Cloud
     module SDK
       module VPC
-
-        # Contols tokens.
+        # The Connection object to be used for all HTTP requests.
+        # @param api_key [String] The API Key to be used for this account.
+        # @param logger [Logger] An instantiated logger instance.
+        # @param client [HTTP::Client] An instantiated HTTP client.
         class Connection
           def initialize(api_key, logger: nil, client: nil)
             @api_key = api_key
@@ -20,17 +22,36 @@ module IBM
 
           attr_reader :client
 
+          # Send a HTTP request. Checks the validity of the response.
+          # @param verb [String] THe HTTP verb to use for this request.
+          # @param uri [String] The Full URL to send.
+          # @option opts [Hash] :params Parameters for URL encoding parameters.
+          # @option opts [Hash] :json Used when sending a hash as application/json content type.
+          # @option opts [Hash] :form Used when sending a hash as a form.
+          # @option opts [Hash] :headers Used to modify headers for request.
+          # @return [IBM::Cloud::SDK::VPC::Response] Wrapped response to query.
+          # @raise [IBM::Cloud::SDK::VPC::Exceptions::HttpStatusError] Response code is not either in 200-series or 404.
           def adhoc(verb, uri, opts = {})
-            response = @client.auth(@token.authorization_header).request(verb.to_sym, uri, opts)
+            unverified_request(verb, uri, opts).raise_for_status?
+          end
+
+          # Send a HTTP request. Don't do any validation checks.
+          # @see :adhoc for options.
+          def unverified_request(verb, uri, opts = {})
+            response = @client.auth(@token.authorization_header).request(verb.to_s.downcase.to_sym, uri, opts)
             Response.new(response)
           end
 
+          # Get bearer token string for clients not using the adhoc method.
           def authorization_header
             @token.authorization_header
           end
         end
 
-        # Get a token.
+        # The IAM token manager.
+        # @param api_key [String] The API Key to be used for this account.
+        # @param logger [Logger] An instantiated logger instance.
+        # @param client [HTTP::Client] An instantiated HTTP client.
         class Token
           def initialize(api_key, logger: nil, client: nil)
             @api_key = api_key
@@ -39,6 +60,9 @@ module IBM
             @data = fetch
           end
 
+          # Retrieve a new access_token from IAM.
+          # @return [IBM::Cloud::SDK::VPC::Response] Wrapped response to query.
+          # @raise [IBM::Cloud::SDK::VPC::Exceptions::HttpStatusError] Response code is not either in 200-series or 404.
           def fetch
             payload = {
               form: {
@@ -47,14 +71,20 @@ module IBM
               }
             }
             response = HTTP.post('https://iam.cloud.ibm.com/identity/token', payload)
-            @data = Response.new(response).json
+            @data = Response.new(response).raise_for_status?.json
           end
 
+          # Check to see if the access_token is expired. Fetch a new token if none exists.
+          # @return [IBM::Cloud::SDK::VPC::Response] Wrapped response to query.
+          # @raise [IBM::Cloud::SDK::VPC::Exceptions::HttpStatusError] Response code is not either in 200-series or 404.
           def expired?
             fetch unless @data
             @data.fetch(:expiration).to_i <= Time.now.to_i + 600
           end
 
+          # Get a Bearer token string. Before returning check to see if token is expired.
+          # @return [String] The Bearer token header used in subsequent requests.
+          # @raise [IBM::Cloud::SDK::VPC::Exceptions::HttpStatusError] Response code is not either in 200-series or 404.
           def authorization_header
             fetch if expired?
             "#{@data.fetch(:token_type)} #{@data.fetch(:access_token)}"

data/lib/ibm/cloud/sdk/vpc/helpers/response.rb

@@ -8,82 +8,124 @@ module IBM
     module SDK
       module VPC
         # Encapsulate the HTTP response.
+        # @param response [HTTP::Response] The HTTP response object.
         class Response
           def initialize(response)
             @response = response
           end
 
+          # The raw HTTP response.
+          # @return [HTTP::Response]
           attr_reader :response
 
           # Return the response in a hash or array.
+          # @return [Hash] When response is a hash.
+          # @return [Array] When response is an array.
+          # @raise [Exceptions::ExceptionWithResponse] Contents of body is not properly formatted json.
           def json
             JSON.parse(body, symbolize_names: true)
           rescue StandardError
-            raise "Error while parsing response body. #{response.body}"
+            raise Exceptions::ExceptionWithResponse.new(self, "#{url} Error while parsing response body. #{response.body}")
           end
 
           # Return the raw response string.
+          # @return [String]
+          # @return [nil] Response does not have body method.
           def body
-            response.body.to_s
+            response&.body.to_s
           end
 
           # Return the response code.
+          # @return [Integer] Response has code method.
+          # @return [nil] Response does not have code method.
           def code
-            response.code
+            response&.code
           end
 
-          alias_method :status, :code
+          alias status code
 
           # Return the raw connection object.
+          # @return [HTTP::Connection]
+          # @return [nil] Response does not have a connection method.
           def connection
-            response.connection
+            response&.connection
+          end
+
+          # Chainable method to verify the status code. Raise an exception for non 200-series or 404 status codes.
+          # @return [Response] Allows for method to be chainable.
+          # @raise [Exceptions::HttpStatusError] Raise if status checks failed.
+          def raise_for_status?
+            return self if (200..299).include?(code)
+            return self if code == 404
+
+            raise Exceptions::HttpStatusError.new(self)
           end
 
           # Return the content type of the response.
+          # @return [String] The mimetype of the response.
+          # @return [nil] Response does not have response method that responds to mime_type.
           def content_type
-            response.response.mime_type
+            response&.response&.mime_type
           end
 
           # Return the textual reason.
+          # @return [String] HTTP Reason
+          # @return [nil] Response does not have reaspn method that responds.
           def reason
-            response.reason
+            response&.reason
           end
 
           # Return the sent url as a string.
+          # @return [String] Full URL sent
+          # @return [nil] Response does not have response method that responds to mime_type.
           def url
-            response.uri.to_s
+            response&.uri.to_s
           end
 
           # Return the sent url as a URI class.
+          # @see https://github.com/httprb/http/blob/master/lib/http/uri.rb URI Class doc.
+          # @return [HTTP::URI]
+          # @return [nil] Response does not have response method that responds to mime_type.
           def uri
-            response.uri
+            response&.uri
           end
 
           # Verify that the json response is a hash.
+          # @return [Hash] Response from JSON
+          # @raise [RuntimeError] JSON object is not a Hash.
           def hash_response
             check_object(Hash)
           end
 
           # Verify that the json response is an array.
+          # @return [Array] Response from JSON
+          # @raise [RuntimeError] JSON object is not a Array.
           def array_response
             check_object(Array)
           end
 
           # Find a subkey within the returned response.
+          # @param key [String] Name of a first level key.
+          # @return [Any] Response from JSON
+          # @raise [RuntimeError] JSON object is not a Array.
           def subkey(key)
             ret = hash_response
             sym_key = key.to_sym
             return ret.fetch(sym_key) if ret.key?(sym_key)
 
-            raise "Key #{key} not found in #{ret}."
+            msg = "Key #{key} not found in #{ret}."
+            raise Exceptions::ExceptionWithResponse.new(self, msg)
           end
 
           # Check to see if the returned object is the expected object.
+          # @param obj [Object] The object to test the response against.
+          # @raise [Exceptions::ExceptionWithResponse] Parsed JSON is not the expecte class.
           def check_object(obj)
             ret = json
             return ret if ret.instance_of?(obj)
 
-            raise "Expected #{obj} in response for #{url}. The returned object is a #{ret.class}."
+            msg = "Expected #{obj} in response for #{url}. The returned object is a #{ret.class}."
+            raise Exceptions::ExceptionWithResponse.new(self, msg)
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ibm-cloud-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - IBM Cloud Developers
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-23 00:00:00.000000000 Z
+date: 2020-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -60,6 +60,8 @@ files:
 - lib/ibm/cloud/sdk/base_service.rb
 - lib/ibm/cloud/sdk/iam.rb
 - lib/ibm/cloud/sdk/iam/token.rb
+- lib/ibm/cloud/sdk/logging.rb
+- lib/ibm/cloud/sdk/null_logger.rb
 - lib/ibm/cloud/sdk/power_iaas.rb
 - lib/ibm/cloud/sdk/resource_controller.rb
 - lib/ibm/cloud/sdk/resource_controller/resource.rb
@@ -69,6 +71,7 @@ files:
 - lib/ibm/cloud/sdk/vpc/base_instance.rb
 - lib/ibm/cloud/sdk/vpc/base_vpc.rb
 - lib/ibm/cloud/sdk/vpc/cloud_sdk.rb
+- lib/ibm/cloud/sdk/vpc/exceptions.rb
 - lib/ibm/cloud/sdk/vpc/floatingips.rb
 - lib/ibm/cloud/sdk/vpc/flowlogcollectors.rb
 - lib/ibm/cloud/sdk/vpc/helpers/connection.rb
@@ -108,7 +111,7 @@ licenses:
 - '"Apache-2.0"'
 metadata:
   homepage_uri: https://github.com/IBM-Cloud/ibm-cloud-sdk-ruby
-  changelog_uri: https://github.com/IBM-Cloud/ibm-cloud-sdk-ruby/blob/v0.1.6/CHANGELOG.md
+  changelog_uri: https://github.com/IBM-Cloud/ibm-cloud-sdk-ruby/blob/v0.1.7/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: