ibm_cloud_sdk_core 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4246cbde9bd7f851cb748bec1b534632334e64508202a822810d0e2bb2f5de6
+  data.tar.gz: 5f388df8543fd24288f66edb14ce0e11394c3d76aa89de1830442d3b51b78fd2
+SHA512:
+  metadata.gz: 57496087e3feb73ff6f6e8714ee22405cd43aaace2493af2c3b8d824b3ee198b3579a43c48f37b771bcbb9cca80b49c489c8659c9eba842673043b60b8c61287
+  data.tar.gz: 512e10063200783cf8032a1b1545df28244b7aad50bd1d5ba1653c4f010b082c2f3f03080b0a1c41490410da5687879b9a16c9ad5e7ac8404f549a308f069ee0

data/README.md

@@ -0,0 +1,3 @@
+# ruby-sdk-core
+This project contains the core functionality used by Ruby SDK's generated by the IBM OpenAPI 3 SDK Generator (openapi-sdkgen).
+Ruby code generated by openapi-sdkgen will depend on the classes contained in this project.

data/lib/ibm_cloud_sdk_core.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Module for the IBM Cloud SDK Core
+module IBMCloudSdkCore
+  require_relative("./ibm_cloud_sdk_core/base_service.rb")
+end

data/lib/ibm_cloud_sdk_core/api_exception.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require("json")
+
+module IBMCloudSdkCore
+  # Custom exception class for errors returned from the APIs
+  class ApiException < StandardError
+    attr_reader :code, :error, :info, :transaction_id, :global_transaction_id
+    # :param HTTP::Response response: The response object from the API
+    def initialize(code: nil, error: nil, info: nil, transaction_id: nil, global_transaction_id: nil, response: nil)
+      if code.nil? || error.nil?
+        @code = response.code
+        @error = response.reason
+        unless response.body.empty?
+          body_hash = JSON.parse(response.body.to_s)
+          error_message = body_hash["errors"] && body_hash["errors"][0] ? body_hash["errors"][0].message : nil
+          @code = body_hash["code"] || body_hash["error_code"] || body_hash["status"]
+          @error = error_message || body_hash["error"] || body_hash["message"]
+          %w[code error_code status errors error message].each { |k| body_hash.delete(k) }
+          @info = body_hash
+        end
+      else
+        # :nocov:
+        @code = code
+        @error = error
+        @info = info
+        # :nocov:
+      end
+      @transaction_id = transaction_id
+      @global_transaction_id = global_transaction_id
+    end
+
+    def to_s
+      msg = "Error: #{@error}, Code: #{@code}"
+      msg += ", Information: #{@info}" unless @info.nil?
+      msg += ", X-dp-watson-tran-id: #{@transaction_id}" unless @transaction_id.nil?
+      msg += ", X-global-transaction-id: #{@global_transaction_id}" unless @global_transaction_id.nil?
+      msg
+    end
+  end
+end

data/lib/ibm_cloud_sdk_core/base_service.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require("http")
+require("rbconfig")
+require("stringio")
+require("json")
+require_relative("./detailed_response.rb")
+require_relative("./api_exception.rb")
+require_relative("./iam_token_manager.rb")
+require_relative("./version.rb")
+
+DEFAULT_CREDENTIALS_FILE_NAME = "ibm-credentials.env"
+NORMALIZER = lambda do |uri| # Custom URI normalizer when using HTTP Client
+  HTTP::URI.parse uri
+end
+
+module IBMCloudSdkCore
+  # Class for interacting with the API
+  class BaseService
+    attr_accessor :password, :url, :username, :display_name
+    attr_reader :conn, :token_manager
+    def initialize(vars)
+      defaults = {
+        vcap_services_name: nil,
+        username: nil,
+        password: nil,
+        use_vcap_services: true,
+        iam_apikey: nil,
+        iam_access_token: nil,
+        iam_url: nil,
+        display_name: nil
+      }
+      vars = defaults.merge(vars)
+      @url = vars[:url]
+      @username = nil
+      @password = nil
+      @iam_apikey = nil
+      @token_manager = nil
+      @temp_headers = nil
+      @icp_prefix = vars[:password]&.start_with?("icp-") || vars[:iam_apikey]&.start_with?("icp-") ? true : false
+      @disable_ssl_verification = false
+      @display_name = vars[:display_name]
+
+      if (!vars[:iam_access_token].nil? || !vars[:iam_apikey].nil?) && !@icp_prefix
+        set_token_manager(iam_apikey: vars[:iam_apikey], iam_access_token: vars[:iam_access_token], iam_url: vars[:iam_url])
+      elsif !vars[:iam_apikey].nil? && @icp_prefix
+        @username = "apikey"
+        @password = vars[:iam_apikey]
+      elsif !vars[:username].nil? && !vars[:password].nil?
+        if vars[:username] == "apikey" && !@icp_prefix
+          iam_apikey(iam_apikey: vars[:password])
+        else
+          @username = vars[:username]
+          @password = vars[:password]
+        end
+      end
+
+      if @display_name && !@username && !@iam_apikey
+        service_name = @display_name.sub(" ", "_").downcase
+        load_from_credential_file(service_name)
+        @icp_prefix = @password&.start_with?("icp-") || @iam_apikey&.start_with?("icp-") ? true : false
+      end
+
+      if vars[:use_vcap_services] && !@username && !@iam_apikey
+        @vcap_service_credentials = load_from_vcap_services(service_name: vars[:vcap_services_name])
+        if !@vcap_service_credentials.nil? && @vcap_service_credentials.instance_of?(Hash)
+          @url = @vcap_service_credentials["url"]
+          @username = @vcap_service_credentials["username"] if @vcap_service_credentials.key?("username")
+          @password = @vcap_service_credentials["password"] if @vcap_service_credentials.key?("password")
+          @iam_apikey = @vcap_service_credentials["iam_apikey"] if @vcap_service_credentials.key?("iam_apikey")
+          @iam_access_token = @vcap_service_credentials["iam_access_token"] if @vcap_service_credentials.key?("iam_access_token")
+          @iam_url = @vcap_service_credentials["iam_url"] if @vcap_service_credentials.key?("iam_url")
+          @icp_prefix = @password&.start_with?("icp-") || @iam_apikey&.start_with?("icp-") ? true : false
+        end
+      end
+
+      raise ArgumentError.new('The username shouldn\'t start or end with curly brackets or quotes. Be sure to remove any {} and \" characters surrounding your username') if check_bad_first_or_last_char(@username)
+      raise ArgumentError.new('The password shouldn\'t start or end with curly brackets or quotes. Be sure to remove any {} and \" characters surrounding your password') if check_bad_first_or_last_char(@password)
+      raise ArgumentError.new('The url shouldn\'t start or end with curly brackets or quotes. Be sure to remove any {} and \" characters surrounding your url') if check_bad_first_or_last_char(@url)
+      raise ArgumentError.new('The apikey shouldn\'t start or end with curly brackets or quotes. Be sure to remove any {} and \" characters surrounding your apikey') if check_bad_first_or_last_char(@iam_apikey)
+
+      @conn = HTTP::Client.new(
+        headers: {}
+      ).use normalize_uri: { normalizer: NORMALIZER }
+    end
+
+    # Initiates the credentials based on the credential file
+    def load_from_credential_file(service_name, separator = "=")
+      credential_file_path = ENV["IBM_CREDENTIALS_FILE"]
+
+      # Home directory
+      if credential_file_path.nil?
+        file_path = ENV["HOME"] + DEFAULT_CREDENTIALS_FILE_NAME
+        credential_file_path = file_path if File.exist?(file_path)
+      end
+
+      # Top-level directory of the project
+      if credential_file_path.nil?
+        file_path = File.join(File.dirname(__FILE__), "/../../" + DEFAULT_CREDENTIALS_FILE_NAME)
+        credential_file_path = file_path if File.exist?(file_path)
+      end
+
+      return if credential_file_path.nil?
+
+      file_contents = File.open(credential_file_path, "r")
+      file_contents.each_line do |line|
+        key_val = line.strip.split(separator)
+        set_credential_based_on_type(service_name, key_val[0].downcase, key_val[1]) if key_val.length == 2
+      end
+    end
+
+    def load_from_vcap_services(service_name:)
+      vcap_services = ENV["VCAP_SERVICES"]
+      unless vcap_services.nil?
+        services = JSON.parse(vcap_services)
+        return services[service_name][0]["credentials"] if services.key?(service_name)
+      end
+      nil
+    end
+
+    def add_default_headers(headers: {})
+      raise TypeError unless headers.instance_of?(Hash)
+
+      headers.each_pair { |k, v| @conn.default_options.headers.add(k, v) }
+    end
+
+    def iam_access_token(iam_access_token:)
+      @token_manager = IAMTokenManager.new(iam_access_token: iam_access_token) if @token_manager.nil?
+      @iam_access_token = iam_access_token
+    end
+
+    def iam_apikey(iam_apikey:)
+      @token_manager = IAMTokenManager.new(iam_apikey: iam_apikey) if @token_manager.nil?
+      @iam_apikey = iam_apikey
+    end
+
+    # @return [DetailedResponse]
+    def request(args)
+      defaults = { method: nil, url: nil, accept_json: false, headers: nil, params: nil, json: {}, data: nil }
+      args = defaults.merge(args)
+      args[:data].delete_if { |_k, v| v.nil? } if args[:data].instance_of?(Hash)
+      args[:json] = args[:data].merge(args[:json]) if args[:data].respond_to?(:merge)
+      args[:json] = args[:data] if args[:json].empty? || (args[:data].instance_of?(String) && !args[:data].empty?)
+      args[:json].delete_if { |_k, v| v.nil? } if args[:json].instance_of?(Hash)
+      args[:headers]["Accept"] = "application/json" if args[:accept_json] && args[:headers]["Accept"].nil?
+      args[:headers]["Content-Type"] = "application/json" unless args[:headers].key?("Content-Type")
+      args[:json] = args[:json].to_json if args[:json].instance_of?(Hash)
+      args[:headers].delete_if { |_k, v| v.nil? } if args[:headers].instance_of?(Hash)
+      args[:params].delete_if { |_k, v| v.nil? } if args[:params].instance_of?(Hash)
+      args[:form].delete_if { |_k, v| v.nil? } if args.key?(:form)
+      args.delete_if { |_, v| v.nil? }
+      args[:headers].delete("Content-Type") if args.key?(:form) || args[:json].nil?
+
+      if @username == "apikey" && !@icp_prefix
+        iam_apikey(iam_apikey: @password)
+        @username = nil
+      end
+
+      conn = @conn
+      if !@iam_apikey.nil? && @icp_prefix
+        conn = @conn.basic_auth(user: "apikey", pass: @iam_apikey)
+      elsif !@token_manager.nil?
+        access_token = @token_manager.token
+        args[:headers]["Authorization"] = "Bearer #{access_token}"
+      elsif !@username.nil? && !@password.nil?
+        conn = @conn.basic_auth(user: @username, pass: @password)
+      end
+
+      args[:headers] = args[:headers].merge(@temp_headers) unless @temp_headers.nil?
+      @temp_headers = nil unless @temp_headers.nil?
+
+      if args.key?(:form)
+        response = conn.follow.request(
+          args[:method],
+          HTTP::URI.parse(@url + args[:url]),
+          headers: conn.default_options.headers.merge(HTTP::Headers.coerce(args[:headers])),
+          params: args[:params],
+          form: args[:form]
+        )
+      else
+        response = conn.follow.request(
+          args[:method],
+          HTTP::URI.parse(@url + args[:url]),
+          headers: conn.default_options.headers.merge(HTTP::Headers.coerce(args[:headers])),
+          body: args[:json],
+          params: args[:params]
+        )
+      end
+      return DetailedResponse.new(response: response) if (200..299).cover?(response.code)
+
+      raise ApiException.new(response: response)
+    end
+
+    # @note Chainable
+    # @param headers [Hash] Custom headers to be sent with the request
+    # @return [self]
+    def headers(headers)
+      raise TypeError("Expected Hash type, received #{headers.class}") unless headers.instance_of?(Hash)
+
+      @temp_headers = headers
+      self
+    end
+
+    # @!method configure_http_client(proxy: {}, timeout: {}, disable_ssl_verification: false)
+    # Sets the http client config, currently works with timeout and proxies
+    # @param proxy [Hash] The hash of proxy configurations
+    # @option proxy address [String] The address of the proxy
+    # @option proxy port [Integer] The port of the proxy
+    # @option proxy username [String] The username of the proxy, if authentication is needed
+    # @option proxy password [String] The password of the proxy, if authentication is needed
+    # @option proxy headers [Hash] The headers to be used with the proxy
+    # @param timeout [Hash] The hash for configuring timeouts. `per_operation` has priority over `global`
+    # @option timeout per_operation [Hash] Timeouts per operation. Requires `read`, `write`, `connect`
+    # @option timeout global [Integer] Upper bound on total request time
+    # @param disable_ssl_verification [Boolean] Disable the SSL verification (Note that this has serious security implications - only do this if you really mean to!)
+    def configure_http_client(proxy: {}, timeout: {}, disable_ssl_verification: false)
+      raise TypeError("proxy parameter must be a Hash") unless proxy.empty? || proxy.instance_of?(Hash)
+
+      raise TypeError("timeout parameter must be a Hash") unless timeout.empty? || timeout.instance_of?(Hash)
+
+      @disable_ssl_verification = disable_ssl_verification
+      if disable_ssl_verification
+        ssl_context = OpenSSL::SSL::SSLContext.new
+        ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        @conn.default_options = { ssl_context: ssl_context }
+      end
+      add_proxy(proxy) unless proxy.empty? || !proxy.dig(:address).is_a?(String) || !proxy.dig(:port).is_a?(Integer)
+      add_timeout(timeout) unless timeout.empty? || (!timeout.key?(:per_operation) && !timeout.key?(:global))
+    end
+
+    private
+
+    def set_credential_based_on_type(service_name, key, value)
+      return unless key.include?(service_name)
+
+      @iam_apikey = value if key.include?("iam_apikey")
+      @iam_url = value if key.include?("iam_url")
+      @url = value if key.include?("url")
+      @username = value if key.include?("username")
+      @password = value if key.include?("password")
+    end
+
+    def check_bad_first_or_last_char(str)
+      return str.start_with?("{", "\"") || str.end_with?("}", "\"") unless str.nil?
+    end
+
+    def set_token_manager(iam_apikey: nil, iam_access_token: nil, iam_url: nil)
+      @iam_apikey = iam_apikey
+      @iam_access_token = iam_access_token
+      @iam_url = iam_url
+      @token_manager = IAMTokenManager.new(iam_apikey: iam_apikey, iam_access_token: iam_access_token, iam_url: iam_url)
+    end
+
+    def add_timeout(timeout)
+      if timeout.key?(:per_operation)
+        raise TypeError("per_operation in timeout must be a Hash") unless timeout[:per_operation].instance_of?(Hash)
+
+        defaults = {
+          write: 0,
+          connect: 0,
+          read: 0
+        }
+        time = defaults.merge(timeout[:per_operation])
+        @conn = @conn.timeout(write: time[:write], connect: time[:connect], read: time[:read])
+      else
+        raise TypeError("global in timeout must be an Integer") unless timeout[:global].is_a?(Integer)
+
+        @conn = @conn.timeout(timeout[:global])
+      end
+    end
+
+    def add_proxy(proxy)
+      if (proxy[:username].nil? || proxy[:password].nil?) && proxy[:headers].nil?
+        @conn = @conn.via(proxy[:address], proxy[:port])
+      elsif !proxy[:username].nil? && !proxy[:password].nil? && proxy[:headers].nil?
+        @conn = @conn.via(proxy[:address], proxy[:port], proxy[:username], proxy[:password])
+      elsif !proxy[:headers].nil? && (proxy[:username].nil? || proxy[:password].nil?)
+        @conn = @conn.via(proxy[:address], proxy[:port], proxy[:headers])
+      else
+        @conn = @conn.via(proxy[:address], proxy[:port], proxy[:username], proxy[:password], proxy[:headers])
+      end
+    end
+  end
+end

data/lib/ibm_cloud_sdk_core/detailed_response.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require("json")
+
+module IBMCloudSdkCore
+  # Custom class for objects returned from API calls
+  class DetailedResponse
+    attr_reader :status, :headers, :result
+    def initialize(status: nil, headers: nil, body: nil, response: nil)
+      if status.nil? || headers.nil? || body.nil?
+        @status = response.code
+        @headers = response.headers.to_h
+        @headers = response.headers.to_hash if response.headers.respond_to?("to_hash")
+        @result = response.body.to_s
+        @result = JSON.parse(response.body.to_s) if !response.body.to_s.empty? && @headers.key?("Content-Type") && @headers["Content-Type"].start_with?("application/json")
+      else
+        @status = status
+        @headers = headers
+        @result = body
+      end
+    end
+  end
+end

data/lib/ibm_cloud_sdk_core/iam_token_manager.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require("http")
+require("json")
+require("rbconfig")
+require_relative("./version.rb")
+
+module IBMCloudSdkCore
+  # Class to manage IAM Token Authentication
+  class IAMTokenManager
+    DEFAULT_IAM_URL = "https://iam.bluemix.net/identity/token"
+    CONTENT_TYPE = "application/x-www-form-urlencoded"
+    ACCEPT = "application/json"
+    DEFAULT_AUTHORIZATION = "Basic Yng6Yng="
+    REQUEST_TOKEN_GRANT_TYPE = "urn:ibm:params:oauth:grant-type:apikey"
+    REQUEST_TOKEN_RESPONSE_TYPE = "cloud_iam"
+    REFRESH_TOKEN_GRANT_TYPE = "refresh_token"
+
+    attr_accessor :token_info, :user_access_token
+    def initialize(iam_apikey: nil, iam_access_token: nil, iam_url: nil)
+      @iam_apikey = iam_apikey
+      @user_access_token = iam_access_token
+      @iam_url = iam_url.nil? ? DEFAULT_IAM_URL : iam_url
+      @token_info = {
+        "access_token" => nil,
+        "refresh_token" => nil,
+        "token_type" => nil,
+        "expires_in" => nil,
+        "expiration" => nil
+      }
+    end
+
+    def request(method:, url:, headers: nil, params: nil, data: nil)
+      response = nil
+      if headers.key?("Content-Type") && headers["Content-Type"] == CONTENT_TYPE
+        response = HTTP.request(
+          method,
+          url,
+          body: HTTP::URI.form_encode(data),
+          headers: headers,
+          params: params
+        )
+      end
+      return JSON.parse(response.body.to_s) if (200..299).cover?(response.code)
+
+      require_relative("./api_exception.rb")
+      raise ApiException.new(response: response)
+    end
+
+    # The source of the token is determined by the following logic:
+    #   1. If user provides their own managed access token, assume it is valid and send it
+    #   2. If this class is managing tokens and does not yet have one, make a request for one
+    #   3. If this class is managing tokens and the token has expired refresh it. In case the refresh token is expired, get a new one
+    # If this class is managing tokens and has a valid token stored, send it
+    def token
+      return @user_access_token unless @user_access_token.nil? || (@user_access_token.respond_to?(:empty?) && @user_access_token.empty?)
+
+      if @token_info.all? { |_k, v| v.nil? }
+        token_info = request_token
+        save_token_info(
+          token_info: token_info
+        )
+        return @token_info["access_token"]
+      elsif token_expired?
+        token_info = refresh_token_expired? ? request_token : refresh_token
+        save_token_info(
+          token_info: token_info
+        )
+        return @token_info["access_token"]
+      else
+        @token_info["access_token"]
+      end
+    end
+
+    private
+
+    # Request an IAM token using an API key
+    def request_token
+      headers = {
+        "Content-Type" => CONTENT_TYPE,
+        "Authorization" => DEFAULT_AUTHORIZATION,
+        "Accept" => ACCEPT
+      }
+      data = {
+        "grant_type" => REQUEST_TOKEN_GRANT_TYPE,
+        "apikey" => @iam_apikey,
+        "response_type" => REQUEST_TOKEN_RESPONSE_TYPE
+      }
+      response = request(
+        method: "POST",
+        url: @iam_url,
+        headers: headers,
+        data: data
+      )
+      response
+    end
+
+    # Refresh an IAM token using a refresh token
+    def refresh_token
+      headers = {
+        "Content-Type" => CONTENT_TYPE,
+        "Authorization" => DEFAULT_AUTHORIZATION,
+        "accept" => ACCEPT
+      }
+      data = {
+        "grant_type" => REFRESH_TOKEN_GRANT_TYPE,
+        "refresh_token" => @token_info["refresh_token"]
+      }
+      response = request(
+        method: "POST",
+        url: @iam_url,
+        headers: headers,
+        data: data
+      )
+      response
+    end
+
+    # Check if currently stored token is expired.
+    # Using a buffer to prevent the edge case of the
+    # token expiring before the request could be made.
+    # The buffer will be a fraction of the total TTL. Using 80%.
+    def token_expired?
+      return true if @token_info["expiration"].nil? || @token_info["expires_in"].nil?
+
+      fraction_of_ttl = 0.8
+      time_to_live = @token_info["expires_in"].nil? ? 0 : @token_info["expires_in"]
+      expire_time = @token_info["expiration"].nil? ? 0 : @token_info["expiration"]
+      refresh_time = expire_time - (time_to_live * (1.0 - fraction_of_ttl))
+      current_time = Time.now.to_i
+      refresh_time < current_time
+    end
+
+    # Used as a fail-safe to prevent the condition of a refresh token expiring,
+    # which could happen after around 30 days. This function will return true
+    # if it has been at least 7 days and 1 hour since the last token was set
+    def refresh_token_expired?
+      return true if @token_info["expiration"].nil?
+
+      seven_days = 7 * 24 * 3600
+      current_time = Time.now.to_i
+      new_token_time = @token_info["expiration"] + seven_days
+      new_token_time < current_time
+    end
+
+    # Save the response from the IAM service request to the object's state
+    def save_token_info(token_info:)
+      @token_info = token_info
+    end
+  end
+end