ibm-cloud-sdk 0.1.4 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 181a2894e2d8045bea0d2a33cf81570480eee1f668017b8ade96b1801d0465b2
-  data.tar.gz: 5399f7e3e4f4b483a72e673d351605cb1f8bb09f216e5fd1a9439742f736aedf
+  metadata.gz: dc39c6125bcaf6730a73477c76e7e40d2eb131cf6ca34466537d65f615ed8e6a
+  data.tar.gz: ac29b18c76bff0ed290878e12007f1bf639654ed239ce7c27e99431acde25a17
 SHA512:
-  metadata.gz: 237fd30c5dd4efa622de5be57a2df9e2285dcabc3d15f415d6efb6bec31b36254cbaf6c3cb32a6d8b7113b7e8709e4eddee64736515030e5e3227694dc464b4e
-  data.tar.gz: ed36bdf032519bc35c1563f62fe279f6744b3f25b97fef4358ebd689958a48a17a5a1eafbf85f72a3c62e372dfb764b35463cc292eede788b3ad127170664ced
+  metadata.gz: 845d945f1e0722745858a2256decc3fd73628fd172ba88a8e49a51a7edbf06418965cc609566288e31c2965ff88f2eff33f7691628bd33ef26da0309827c5058
+  data.tar.gz: ee6c2c63c3472db99d9d773d77e045180594958b0ee4627b964f64365e1ea6a07c7a3159706ef326d9b87702a97218d7648c057737b14e4afc02bf4f40ae6c5f

data/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 All notable changes to the gem ibm-cloud-sdk-ruby will be documented here.
 
+## v0.1.9 - 2020-10-02
+- Fix PowerVS Volume attach/detach calls
+
+## v0.1.8 - 2020-10-01
+- Add second level instances
+
+## 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
+- Move VPC instance into instances and add initialization method.
+
+## v0.1.5 - 2020-09-21
+- Added Enumerable based pagination support
+- Move instance profiles
+- Improve resource lookup by GUID
+- Add support to create a PowerIaas volume
+
 ## v0.1.4 - 2020-09-17
 - Added support for the IBM Virtual Private Cloud (VPC) service
 

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,12 +19,23 @@ 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
 
+        # Get Power Cloud Instance information
+        #
+        # @return [Hash] CloudInstance
+        def get_pcloud_instance
+          get("cloud-instances/#{guid}")
+        end
+
         # Get all PVM instances in an IBM Power Cloud instance
         #
         # @return [Array<Hash>] all PVM Instances for this instance
@@ -34,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",
@@ -47,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",
@@ -54,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",
@@ -61,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
@@ -82,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}")
@@ -90,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
@@ -107,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}")
@@ -115,11 +192,35 @@ 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
 
+        # Create a volume
+        #
+        # @param volume_hash [Hash] New volume attributes
+        # @return [Hash] Volume
+        def create_volume(volume_hash)
+          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}/pvm-instances/#{pvm_instance_id}/volumes/#{volume_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}/pvm-instances/#{pvm_instance_id}/volumes/#{volume_id}")
+        end
+
         # Get all networks in an IBM Power Cloud instance
         #
         # @return [Array<Hash>] all networks for this IBM Power Cloud instance
@@ -132,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}")
@@ -146,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))
+          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}")
@@ -204,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/resource_controller.rb

@@ -2,6 +2,7 @@ module IBM
   module Cloud
     module SDK
       class ResourceController < BaseService
+        require "ibm/cloud/sdk/resource_controller/resource"
         def endpoint
           "https://resource-controller.cloud.ibm.com/v2"
         end
@@ -10,15 +11,8 @@ module IBM
           @token = token
         end
 
-        def get_resources
-          resources = get("resource_instances")["resources"] || []
-
-          require "ibm/cloud/sdk/resource_controller/resource"
-          resources.map { |instance| Resource.new(instance) }
-        end
-
         def get_resource(guid)
-          get_resources.detect { |resource| resource.guid == guid }
+          Resource.new(get("resource_instances/#{guid}"))
         end
 
         private

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

@@ -1,7 +1,7 @@
 module IBM
   module Cloud
     module SDK
-      VERSION = "0.1.4"
+      VERSION = "0.1.9"
     end
   end
 end

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

@@ -4,11 +4,13 @@
 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'
 require_relative 'vpc/ike_policies'
 require_relative 'vpc/images'
+require_relative 'vpc/instance_profiles'
 require_relative 'vpc/instances'
 require_relative 'vpc/ipsec_policies'
 require_relative 'vpc/keys'
@@ -32,17 +34,16 @@ module IBM
         # Create an API Client object for the  VPC IaaS service
         #
         # @param region [String] the IBM Power Cloud instance region
-        # @param token [IAMtoken] the IBM Cloud IAM Token object
-        # @param logger [Logger] an instance of an instanciated logger.
-        def initialize(region, api_key, logger: nil)
+        # @param connection [IBM::Cloud::SDK::VPC::Connection] A connection object.
+        # @param logger [Logger] An instance of an instanciated logger.
+        def initialize(region, connection, logger: nil)
           @region = region
-          @api_key = api_key
-          @token = api_key
+          @connection = connection
 
-          @logger = logger || Logger.new($stdout)
+          @logger = logger || Logger.new($stdout, level: :warn)
         end
 
-        attr_reader :token, :logger
+        attr_reader :connection, :logger
         attr_accessor :region
 
         # The Region API endpoint.
@@ -67,6 +68,10 @@ module IBM
           VPC::Images.new(self)
         end
 
+        def instance_profiles
+          VPC::InstanceProfiles.new(self)
+        end
+
         def instances
           VPC::Instances.new(self)
         end

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

@@ -1,14 +1,20 @@
 # typed: true
 # frozen_string_literal: true
 
+require_relative('base_mixins/has_child')
+
 module IBM
   module Cloud
     module SDK
       # Container that encapsulates the VPC API.
       class BaseCollection < BaseVPC
+        # This class is used as a base for collection APIs.
+        # @param parent [Object] The parent instance in the API chain.
+        # @param endpoint [string] A path from the parent to the desired endpoint. In most cases is should be 1 word.
+        # @param array_key [string] The key that the API response holds the endpoint data. When nil the endpoint will be used.
+        # @param child_class [Object] The Object to be used when instanciating the single instance for this class.
         def initialize(parent, endpoint, array_key: nil, child_class: nil)
           # Setup empty base instance variables.
-          @data = nil
           @params = nil
 
           array_key ||= endpoint
@@ -17,50 +23,83 @@ module IBM
           @array_key ||= array_key
           @instance ||= child_class
 
+          (class << self; include ChildMixin; end) if child_class
+
           super(parent, endpoint)
         end
 
+        # A chainable method to set query filters on the collection.
+        # @example vpc.images.params(limit: 1).all
+        #
+        # @param start [String] A server-supplied token determining what resource to start the page on.
+        # @param limit [Integer] The number of resources to return on a page  allowed values are between 1 and 100
+        # @param resource_group [String] Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers
+        # @return [BaseCollection] This class with the param instance variable set.
+        def params(start: nil, limit: nil, resource_group: nil)
+          @params = {}
+          @params[:start] = start if start
+          @params[:limit] = limit if limit
+          @params[:resource_group] = resource_group if resource_group
+          self
+        end
+
         # Retrieve the collection from the cloud.
+        # @return [IBM::Cloud::SDK::VPC::Response] The http response object.
         def fetch
           @data ||= get(params: @params)
-          @data
         end
 
+        # Get an iterable for the resource collection.
+        # @return [Enumerator] Use standard each, next idioms.
         def all
-          response = fetch.subkey(@array_key)
-          return response if response.is_a?(Array)
+          each_resource(url)
+        end
 
-          raise "#{self.class}.#{__method__} Expecting response to be an Array not a #{response.class}"
+        # Fetch all data and return in an array.
+        # @return [Array] Hashes of the returned data.
+        def data
+          all.to_a
         end
 
-        def params(start: nil, limit: nil, resource_group: nil)
-          @params = {}
-          @params['start'] = start if start
-          @params['limit'] = limit if limit
-          @params['resource_group'] = resource_group if resource_group
-          self
+        # Determine if the collection has a total_count key in its response.
+        # @return [Boolean]
+        def has_count?
+          fetch.json&.key?(:total_count)
         end
 
+        # Get the total count if it exists in the response. Returns nil otherwise.
+        # @return [Integer] The total count reuturned by the server.
         def count
-          fetch.subkey('total_count')
+          fetch.json&.fetch(:total_count, nil)
         end
 
-        def limit
-          fetch.subkey('limit')
+        # A generic post method to create a resource on the collection.
+        # @param payload [Hash] A hash of parameters to send to the server.
+        # @param payload_type [String] One of the following options json, form, or body.
+        # @return [IBM::Cloud::SDK::VPC::Response] The http response object.
+        def create(payload, payload_type = 'json')
+          adhoc(method: 'post', payload_type: payload_type, payload: payload)
         end
 
-        def instance(id)
-          @instance.new(self, id)
-        end
+        private
 
-        def next
-          fetch.subkey('next')
-        rescue RuntimeError
-          nil
-        end
+        # Create a generator that removes the need for pagination.
+        def each_resource(url, &block)
+          return enum_for(:each_resource, url) unless block_given?
+          return unless url
+
+          response = @connection.adhoc('get', url, metadata(@params)).json
+          resources = response.fetch(@array_key.to_sym)
+
+          resources&.each do |value|
+            yield value
+          end
+          return unless response.key?(:next)
+
+          next_url = response.dig(:next, :href)
+          return unless next_url
 
-        def create(payload)
-          post(payload)
+          each_resource(next_url, &block)
         end
       end
     end

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

@@ -7,7 +7,7 @@ module IBM
       # Container that encapsulates the VPC API.
       class BaseInstance < BaseVPC
         def details
-          get.hash
+          get.hash_response
         end
 
         def update(payload)

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

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module IBM
+  module Cloud
+    module SDK
+      # Access a specific instance by either id or name depending on API.
+      module ChildMixin
+        # Get an instance of the collection object.
+        # @param id [String] ID of Name to search on depending on API.
+        # @return [] The instance object.
+        def instance(id)
+          @instance.new(self, id)
+        end
+
+        # Return the first_instance returned from a collection get.
+        def first_instance
+          result = params(limit: 1).all.first
+          return nil unless result
+          return nil unless result.key?(:id)
+
+          instance(result.fetch(:id))
+        end
+      end
+    end
+  end
+end

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

@@ -8,14 +8,14 @@ module IBM
       class BaseVPC
         def initialize(parent, endpoint = nil)
           @endpoint = parent.url(endpoint)
-          @token = parent.token
+          @connection = parent.connection
           @logger = parent.logger
         end
 
-        attr_reader :endpoint, :token, :logger
+        attr_reader :endpoint, :connection, :logger
 
         def adhoc(method: 'get', path: nil, params: {}, payload_type: 'json', payload: {})
-          @token.adhoc(method.to_sym, url(path), metadata(params, payload_type, payload))
+          @connection.adhoc(method.to_sym, url(path), metadata(params, payload_type, payload))
         end
 
         def get(path: nil, params: {})
@@ -23,7 +23,7 @@ module IBM
         end
 
         def post(payload = {}, path: nil, params: {}, type: 'json')
-          adhoc(method: 'post', path: path, params: params, payload: payload)
+          adhoc(method: 'post', path: path, params: params, payload: payload, payload_type: type)
         end
 
         def put(payload = {}, path: nil, params: {})

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

@@ -12,7 +12,7 @@ module IBM
         @logger ||= Logger.new($stdout, level: :warn)
 
         @client = HTTP.use(http_options(options))
-        @token = IBM::Cloud::SDK::VPC::Connection.new(api_key, logger: @logger, client: @client)
+        @connection = IBM::Cloud::SDK::VPC::Connection.new(api_key, logger: @logger, client: @client)
       end
 
       def http_options(options = {})
@@ -24,10 +24,10 @@ module IBM
         )
       end
 
-      attr_reader :logger, :token
+      attr_reader :logger, :connection
 
       def vpc(region = 'us-east')
-        IBM::Cloud::SDK::Vpc.new(region, @token, logger: @logger)
+        IBM::Cloud::SDK::Vpc.new(region, @connection, logger: @logger)
       end
     end
-end
+end

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,80 +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 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 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

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

@@ -5,7 +5,7 @@ module IBM
   module Cloud
     module SDK
       module VPC
-        module INSTANCES
+        module INSTANCE
           # Actions for an instance.
           class Actions < BaseCollection
             def initialize(parent)

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

@@ -5,7 +5,7 @@ module IBM
   module Cloud
     module SDK
       module VPC
-        module INSTANCES
+        module INSTANCE
           # Get a Floating IP.
           class FloatingIps < BaseCollection
             def initialize(parent)

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

@@ -7,41 +7,16 @@ module IBM
   module Cloud
     module SDK
       module VPC
-        module INSTANCES
+        module INSTANCE
           # All netowrk interfaces.
-          class NetworkInterfaces < BaseVPC
+          class NetworkInterfaces < BaseCollection
             def initialize(parent)
-              super(parent, 'network_interfaces')
-            end
-
-            def all
-              get.subkey('network_interfaces')
-              # get
-            end
-
-            def update(payload)
-              post(payload)
-            end
-
-            def instance(id)
-              NetworkInterface.new(self, id)
+              super(parent, 'network_interfaces', child_class: NetworkInterface)
             end
           end
 
           # A single network insterface.
-          class NetworkInterface < BaseVPC
-            def remove
-              delete
-            end
-
-            def details
-              get
-            end
-
-            def update(payload)
-              patch(payload)
-            end
-
+          class NetworkInterface < BaseInstance
             def floating_ips
               FloatingIps.new(self)
             end

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

@@ -5,39 +5,16 @@ module IBM
   module Cloud
     module SDK
       module VPC
-        module INSTANCES
+        module INSTANCE
           # Get all attached volumes.
-          class VolumeAttachments < BaseVPC
+          class VolumeAttachments < BaseCollection
             def initialize(parent)
-              super(parent, 'volume_attachments')
-            end
-
-            def all
-              get
-            end
-
-            def create(payload)
-              post(payload)
-            end
-
-            def instance(id)
-              VolumeAttachment.new(self, id)
+              super(parent, 'volume_attachments', child_class: VolumeAttachment)
             end
           end
 
           # A single attached volume.
-          class VolumeAttachment < BaseVPC
-            def details
-              get
-            end
-
-            def update(payload)
-              patch(payload)
-            end
-
-            def remove
-              delete
-            end
+          class VolumeAttachment < BaseInstance
           end
         end
       end

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

@@ -0,0 +1,21 @@
+# typed: true
+# frozen_string_literal: true
+
+module IBM
+  module Cloud
+    module SDK
+      module VPC
+        # Work with multiple profiles.
+        class InstanceProfiles < BaseCollection
+          def initialize(parent)
+            super(parent, 'instance/profiles', child_class: Profile, array_key: 'profiles')
+          end
+        end
+
+        # Get a single profile.
+        class Profile < BaseInstance
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,9 @@
 # typed: true
 # frozen_string_literal: true
 
-require_relative('instance')
+require_relative 'instance/actions'
+require_relative 'instance/network_interfaces'
+require_relative 'instance/volume_attachments'
 
 module IBM
   module Cloud
@@ -11,7 +13,45 @@ module IBM
         # Work with multiple VM instances.
         class Instances < BaseCollection
           def initialize(parent)
-            super(parent, 'instances', child_class: INSTANCES::Instance)
+            super(parent, 'instances', child_class: Instance)
+          end
+
+          # A chainable method to set query filters on the collection.
+          # @example vpc.images.params(limit: 1).all
+          #
+          # @param start [String] A server-supplied token determining what resource to start the page on.
+          # @param limit [Integer] The number of resources to return on a page  allowed values are between 1 and 100
+          # @param name [String] Filters the collection to resources with the exact specified name
+          # @param vpc_id [String] Filters the collection to resources in the VPC with the specified identifier
+          # @param vpc_crn [String] Filters the collection to resources in the VPC with the specified CRN
+          # @param vpc_name [String] Filters the collection to resources in the VPC with the exact specified name
+          # @return [BaseCollection] This class with the param instance variable set.
+          def params(start: nil, limit: nil, name: nil, vpc_id: nil, vpc_crn: nil, vpc_name: nil)
+            super(start: start, limit: limit)
+            @params['name'] = name if name
+            @params['vpc.id'] = vpc_id if vpc_id
+            @params['vpc.crn'] = vpc_crn if vpc_crn
+            @params['vpc.name'] = vpc_name if vpc_name
+            self
+          end
+        end
+
+        # Work with a single instance.
+        class Instance < BaseInstance
+          def actions
+            INSTANCE::Actions.new(self)
+          end
+
+          def network_interfaces
+            INSTANCE::NetworkInterfaces.new(self)
+          end
+
+          def volume_attachments
+            INSTANCE::VolumeAttachments.new(self)
+          end
+
+          def initialization
+            adhoc(method: 'get', path: 'initialization').json
           end
         end
       end

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

@@ -27,7 +27,7 @@ module IBM
         end
 
         # A single zone.
-        class Zone < BaseVPC
+        class Zone < BaseInstance
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ibm-cloud-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.9
 platform: ruby
 authors:
 - IBM Cloud Developers
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-17 00:00:00.000000000 Z
+date: 2020-10-02 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
@@ -67,20 +69,21 @@ files:
 - lib/ibm/cloud/sdk/vpc.rb
 - lib/ibm/cloud/sdk/vpc/base_collection.rb
 - lib/ibm/cloud/sdk/vpc/base_instance.rb
+- lib/ibm/cloud/sdk/vpc/base_mixins/has_child.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
 - lib/ibm/cloud/sdk/vpc/helpers/response.rb
 - lib/ibm/cloud/sdk/vpc/ike_policies.rb
 - lib/ibm/cloud/sdk/vpc/images.rb
-- lib/ibm/cloud/sdk/vpc/instance.rb
 - lib/ibm/cloud/sdk/vpc/instance/actions.rb
 - lib/ibm/cloud/sdk/vpc/instance/floating_ips.rb
 - lib/ibm/cloud/sdk/vpc/instance/network_interfaces.rb
-- lib/ibm/cloud/sdk/vpc/instance/profiles.rb
 - lib/ibm/cloud/sdk/vpc/instance/volume_attachments.rb
+- lib/ibm/cloud/sdk/vpc/instance_profiles.rb
 - lib/ibm/cloud/sdk/vpc/instances.rb
 - lib/ibm/cloud/sdk/vpc/ipsec_policies.rb
 - lib/ibm/cloud/sdk/vpc/keys.rb
@@ -109,7 +112,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.4/CHANGELOG.md
+  changelog_uri: https://github.com/IBM-Cloud/ibm-cloud-sdk-ruby/blob/v0.1.9/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:

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

@@ -1,36 +0,0 @@
-# typed: true
-# frozen_string_literal: true
-
-require_relative 'instance/actions'
-require_relative 'instance/network_interfaces'
-require_relative 'instance/volume_attachments'
-require_relative 'instance/profiles'
-
-module IBM
-  module Cloud
-    module SDK
-      module VPC
-        module INSTANCES
-          # Work with a single instance.
-          class Instance < BaseInstance
-            def actions
-              Actions.new(self)
-            end
-
-            def network_interfaces
-              NetworkInterfaces.new(self)
-            end
-
-            def volume_attachments
-              VolumeAttachments.new(self)
-            end
-
-            def profiles
-              Profiles.new(self)
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,34 +0,0 @@
-# typed: true
-# frozen_string_literal: true
-
-module IBM
-  module Cloud
-    module SDK
-      module VPC
-        module INSTANCES
-          # Work with multiple profiles.
-          class Profiles < BaseVPC
-            def initialize(parent)
-              super(parent, 'instance/profiles')
-            end
-
-            def all
-              get
-            end
-
-            def instance(name)
-              Profile.new(self, name)
-            end
-          end
-
-          # Get a single profile.
-          class Profile < BaseVPC
-            def details
-              get
-            end
-          end
-        end
-      end
-    end
-  end
-end