oci 2.0.0

data/lib/oci/object_storage/util.rb

@@ -0,0 +1 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.

data/lib/oci/regions.rb

@@ -0,0 +1,43 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  # Module defining available regions and helper methods to get value service endpoints
+  module Regions
+    REGION_ENUM = [
+      REGION_US_PHOENIX_1 = 'us-phoenix-1'.freeze,
+      REGION_US_ASHBURN_1 = 'us-ashburn-1'.freeze
+    ].freeze
+
+    SERVICE_ENDPOINT_PREFIX_MAPPING = {
+      BlockstorageClient: 'iaas',
+      ComputeClient: 'iaas',
+      VirtualNetworkClient: 'iaas',
+      IdentityClient: 'identity',
+      LoadBalancerClient: 'iaas',
+      ObjectStorageClient: 'objectstorage'
+    }.freeze
+
+    # Returns an endpoint for the given region and service.
+    #
+    # @param [String] region A region used to determine the service endpoint. This will usually
+    #   correspond to a value in {OCI::Regions::REGION_ENUM}, but may be an arbitrary string.
+    # @param [Symbol] service A symbol representing a service client class (e.g. :IdentityClient)
+    #
+    # @return [String] A fully qualified endpoint
+    def self.get_service_endpoint(region, service)
+      prefix = SERVICE_ENDPOINT_PREFIX_MAPPING[service]
+      raise "Service '#{service}' is not supported." unless prefix
+      format_endpoint(prefix, region)
+    end
+
+    # @return [Boolean] Returns true if the given string corresponds to a known region, as defined in
+    # {OCI::Regions::REGION_ENUM}.
+    def self.valid_region?(region)
+      REGION_ENUM.include? region
+    end
+
+    def self.format_endpoint(prefix, region)
+      "https://#{prefix}.#{region}.oraclecloud.com"
+    end
+  end
+end

data/lib/oci/response.rb

@@ -0,0 +1,80 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  # A response, which represents all successful API calls.
+  class Response
+    # The HTTP status, such as 200, 401, etc
+    #
+    # @return [Integer]
+    attr_reader :status
+
+    # A ResponseHeaders object containing all response headers
+    #
+    # @return [ResponseHeaders]
+    attr_reader :headers
+
+    # The body of the response. For example, this
+    # may contain a User object, or a list of Users.
+    attr_reader :data
+
+    # The value of the next page token, if available,
+    # taken from the opc-next-page header.
+    #
+    # @return [String]
+    attr_reader :next_page
+
+    # The request ID, taken from the opc-request-id header.
+    #
+    # @return [String]
+    attr_reader :request_id
+
+    attr_writer :api_call
+
+    def initialize(status, headers, data)
+      @status = status
+      @headers = OCI::ResponseHeaders.new(headers)
+      @data = data
+
+      @next_page = @headers['opc-next-page'] if headers
+      @request_id = @headers['opc-request-id'] if headers
+    end
+
+    # Returns true if there is another page available.
+    def has_next_page?
+      !next_page.nil?
+    end
+
+    include Enumerable
+
+    # For paged responses, yields each page until the last page is reached.
+    # For example:
+    #
+    #   OCI::Identity::IdentityClient.new.list_users(compartment, limit:'3').each { |r| r.data.each { |user| puts user.name }}
+    #
+    # The first response yielded is always the response that 'each' is being
+    # called on.
+    #
+    # If any of the requests result in an error, that error will be thrown
+    # as normal, which will abort the enumeration.
+    #
+    # While this can be called on non-paged responses, it will simply result
+    # in the response itself being yielded.
+    #
+    # @yieldparam [Response] response A response object for each page, starting with the response used to call 'each'.
+    def each
+      yield self
+      page = @next_page
+
+      while @api_call && page
+        next_response = @api_call.call(page)
+
+        if page == next_response.next_page
+          raise 'Paging failure: Two consecutive responses had the same next page token.'
+        end
+
+        page = next_response.next_page
+        yield next_response
+      end
+    end
+  end
+end

data/lib/oci/response_headers.rb

@@ -0,0 +1,144 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  # A readonly, case-insensitive http response header collection
+  class ResponseHeaders
+
+    # Initialize the readonly and case-insensitive http response headers with hash object.
+    #
+    # @param [Hash] headers the hash object contains http response headers.
+    def initialize(headers)
+      @headers = {}
+      return if headers.nil?
+      headers.each do |key, value|
+        key = key.downcase if key.is_a? String
+        @headers[key] = value.is_a?(Array) && value.length == 1 ? value[0] : value
+      end
+    end
+
+    # Element Reference-Retrieves the value object corresponding to the key object.
+    # If not found, returns nil.
+    #
+    # @param [Object] key the key object. It is case-insensitive if it is a String object.
+    def [](key)
+      key = key.downcase if key.is_a? String
+      @headers[key] || nil
+    end
+
+    # Calls block once for each key in hsh, passing the key-value pair as parameters.
+    # If no block is given, an enumerator is returned instead.
+    #
+    # @param [Block] block the callback block
+    def each(&block)
+      @headers.each(&block)
+    end
+
+    # Calls block once for each key in hsh, passing the key as a parameter.
+    # If no block is given, an enumerator is returned instead.
+    #
+    # @param [Block] block the callback block
+    def each_key(&block)
+      @headers.each_key(&block)
+    end
+
+    # Alias for: each
+    alias each_pair each
+
+    # Calls block once for each key in hsh, passing the value as a parameter.
+    # If no block is given, an enumerator is returned instead.
+    #
+    # @param [Block] block the callback block
+    def each_value(&block)
+      @headers.each_value(&block)
+    end
+
+    # Returns true if hsh contains no key-value pairs.
+    def empty?
+      @headers.empty?
+    end
+
+    # Returns true if hash and other are both hashes with the same content.
+    def eql?(other)
+      @headers.eql?(other)
+    end
+
+    # Returns a value from the hash for the given key. If the key cannot be found, there are several options: With no
+    # other arguments, it will raise an KeyError exception; if default is given, then that will be returned; if the
+    # optional code block is specified, then that will be run and its result returned.
+    def fetch(key, *args, &block)
+      key = key.downcase if key.is_a? String
+      @headers.fetch(key, *args, &block)
+    end
+
+    # Returns true if the given key is present in hsh.
+    #
+    # @param [Object] key to check. It is case-insensitive if it is a String object.
+    def key?(key)
+      key = key.downcase if key.is_a? String
+      @headers.key?(key)
+    end
+
+    # Alias for: key?
+    alias has_key? key?
+
+    # Returns true if the given value is present for some key in hsh.
+    #
+    # @param [Object] value to check.
+    def value?(value)
+      @headers.value?(value)
+    end
+
+    # Alias for: value?
+    alias has_value? value?
+
+    # Compute a hash-code for this hash. Two hashes with the same content will have the same hash code
+    # (and will compare using eql?).
+    def hash
+      @headers.hash
+    end
+
+    # Alias for: key?
+    alias include? key?
+
+    # Return the contents of this hash as a string.
+    def to_s
+      @headers.to_s
+    end
+
+    # Alias for: to_s
+    alias inspect to_s
+
+    # Returns the key of an occurrence of a given value. If the value is not found, returns nil.
+    #
+    # @param [Object] value to check.
+    def key(value)
+      @headers.key(value)
+    end
+
+    # Returns a new array populated with the keys from this hash.
+    def keys
+      @headers.keys
+    end
+
+    # Returns the number of key-value pairs in the hash.
+    def size
+      @headers.size
+    end
+
+    # Alias for: size
+    alias length size
+
+    # Alias for: key?
+    alias member? key?
+
+    # Returns the hash object.
+    def to_hash
+      @headers
+    end
+
+    # Returns a new array populated with the values from hsh.
+    def values
+      @headers.values
+    end
+  end
+end

data/lib/oci/signer.rb

@@ -0,0 +1,157 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+require 'base64'
+require 'digest'
+require 'openssl'
+require 'securerandom'
+require 'time'
+require 'uri'
+require 'cgi'
+
+module OCI
+
+  # Used to sign HTTP requests as required by Oracle Cloud Infrastructure.
+  class Signer
+    # enum to define the signing strategy
+    SIGNING_STRATEGY_ENUM = [STANDARD = 'standard', OBJECT_STORAGE = 'object_storage']
+
+    # The Oracle Cloud Infrastructure API signature version
+    SIGNATURE_VERSION = "1"
+
+    # Creates a Signer
+    #
+    # @param [String] user OCID of the user to be used for authentication, for example "ocidv1:user:oc1:phx:1460406592659:aaaaaaaawcbqrkycbolrirg2n3xjl5fyxe".
+    # @param [String] fingerprint Fingerprint of the key used for authentication, for example "20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34"
+    # @param [String] tenancy OCID of the tenancy
+    # @param [String] private_key_file It can be nil if private_key_content is provided. Full path and filename of the unencrypted PEM file, for example "/Users/bgustafs/.ssh/id_rsa.pem"
+    # @param [String] pass_phrase Optional pass phrase used to encrypt the private key
+    # @param [String] private_key_content Optional if private_key_file is provided. The value should be the content of the unencrypted PEM file.
+    # @param [SIGNING_STRATEGY_ENUM] signing_strategy Optional signing for standard service or object storage service
+    def initialize(user, fingerprint, tenancy, private_key_file, pass_phrase:nil, private_key_content:nil, signing_strategy:STANDARD)
+      fail 'Missing required parameter user.' unless user
+      fail 'Missing required parameter fingerprint.' unless fingerprint
+      fail 'Missing required parameter tenancy.' unless tenancy
+      fail 'Missing required parameter private_key_file or private_key_content.' unless private_key_file || private_key_content
+
+      @key_id = tenancy + "/" + user + "/" + fingerprint
+      @private_key_file = private_key_file
+      @private_key_content = private_key_content
+      @pass_phrase = pass_phrase
+      @signing_strategy = signing_strategy
+    end
+
+    # Generates the correct signature and adds it to the
+    # headers that are passed in. Also injects any required
+    # headers that might be missing.
+    #
+    # @param [Symbol] method The HTTP method, such as :get or :post.
+    # @param [String] uri The URI, such as 'https://iaas.us-phoenix-1.oraclecloud.com/20160918/volumeAttachments/'
+    # @param [Hash] headers A hash of headers
+    # @param [String] body The request body
+    def sign(method, uri, headers, body)
+      method = method.to_sym.downcase
+      uri = URI(uri)
+      path = uri.query.nil? ? uri.path : "#{uri.path}?#{uri.query}"
+      inject_missing_headers(method, headers, body, uri)
+      signature = compute_signature(headers, method, path)
+      unless signature.nil?
+        inject_authorization_header(headers, method, signature)
+      end
+    end
+
+    private
+
+    GENERIC_HEADERS = [:"date", :"(request-target)", :"host"]
+    BODY_HEADERS = [:"content-length", :"content-type", :"x-content-sha256"]
+
+    OPERATION_HEADER_MAPPING = {
+        options: [],
+        get: GENERIC_HEADERS,
+        head: GENERIC_HEADERS,
+        delete: GENERIC_HEADERS,
+        put: GENERIC_HEADERS + BODY_HEADERS,
+        post: GENERIC_HEADERS + BODY_HEADERS
+    }
+
+    def inject_missing_headers(method, headers, body, uri)
+
+      headers["date"] ||= Time.now.utc.httpdate
+      headers["accept"] ||= "*/*"
+      headers["host"] ||= uri.host
+
+      # For object storage service's put method, we don't need to set content type
+      if method != :put || @signing_strategy != OBJECT_STORAGE
+        headers["content-type"] ||= "application/json"
+      else
+        headers[:'Content-Type'] ||= 'application/octet-stream'
+      end
+
+      if method == :put || method == :post
+        body ||= ''
+
+        # For object storage service's put method, we don't need to set content length and x-content sha256
+        if method != :put || @signing_strategy != OBJECT_STORAGE
+          headers["content-length"] ||= body.length.to_s
+          headers["x-content-sha256"] ||= Digest::SHA256.base64digest(body)
+        else
+          if body.respond_to?(:read) && body.respond_to?(:write)
+            headers['Content-Length'] ||= body.respond_to?('size') ? body.size : body.stat.size
+          else
+            headers['Content-Length'] ||= body.length.to_s
+          end
+        end
+      end
+    end
+
+    def inject_authorization_header(headers, method, signature)
+
+      if method == :put && @signing_strategy == OBJECT_STORAGE
+        header_mapping = GENERIC_HEADERS
+      else
+        header_mapping = OPERATION_HEADER_MAPPING[method]
+      end
+
+      signed_headers = header_mapping.map(&:to_s).join(" ")
+      headers["authorization"] = [
+          %(Signature headers="#{signed_headers}"),
+          %(keyId="#{@key_id}"),
+          %(algorithm="rsa-sha256"),
+          %(signature="#{signature}"),
+          %(version="#{SIGNATURE_VERSION}")
+      ].join(",")
+    end
+
+    def compute_signature(headers, method, path)
+      if method == :put && @signing_strategy == OBJECT_STORAGE
+        header_mapping = GENERIC_HEADERS
+      else
+        header_mapping = OPERATION_HEADER_MAPPING[method]
+      end
+
+      return if header_mapping.empty?
+      signing_string = header_mapping.map do |header|
+        if header == :"(request-target)"
+          "#{header}: #{method.downcase} #{path}"
+        else
+          "#{header}: #{headers[header.to_s]}"
+        end
+      end.join("\n")
+
+      signature = private_key.sign(OpenSSL::Digest::SHA256.new, signing_string.encode("ascii"))
+      Base64.strict_encode64(signature)
+    end
+
+    def private_key
+      # If a pass_phase was not provided and the key is in fact encrypted, then passing in
+      # nil for the passphrase here will show a user prompt and block until there is a response.
+      # Passing in an empty string will work for some versions of Ruby's openssl wrapper, but
+      # other versions will enforce the 4 character password minimum at this point. Passing in
+      # a dummy password that's greater than 4 characters avoids both problems, and will
+      # always succeed if the file is not encrypted.
+      @private_key ||= OpenSSL::PKey::RSA.new(
+          @private_key_content.nil? ? File.read(@private_key_file) : @private_key_content,
+          @pass_phrase || SecureRandom.uuid)
+    end
+  end
+
+end

data/lib/oci/version.rb

@@ -0,0 +1,5 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  VERSION = "2.0.0"
+end

data/lib/oci/waiter.rb

@@ -0,0 +1,101 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  module Waiter
+    module Errors
+      # Raised when a call to wait_until reaches the maximum wait time.
+      class MaximumWaitTimeExceededError < RuntimeError; end
+
+      # Raised when wait_until is called on a response that does not
+      # support waiters. Typically, waiters are only supported for
+      # get operations.
+      class WaitUntilNotSupportedError < RuntimeError; end
+
+      # If thrown from the yield statement of a waiter, it will cause the
+      # waiter to fail with this exception.
+      class WaiterFailedError < RuntimeError; end
+    end
+  end
+
+  # Adds to the Response class in lib/oci/response.rb to define wait behavior
+  class Response
+    # Wait until the value of the given property in the response data has
+    # the given value. This will block the current thread until the
+    # the desired state is reached, the maximum wait time is reached, or the
+    # optional yield block throws :stop_succeed or :stop_fail. This is only
+    # supported for responses resulting from GET operations. A typical use
+    # case is to wait on an instance until it is in a running state:
+    #
+    #     compute_client.get_instance(@instance_id).wait_until(:lifecycle_state, OCI::Core::Models::Instance::LIFECYCLE_STATE_RUNNING)
+    #
+    # Although this can be run on any property of the data resulting from any
+    # GET operation, the most common use case is to check state properties on
+    # operations that GET a single object.
+    #
+    # The wait will poll at an increasing interval up to 'max_interval_seconds'
+    # for a maximum total time of 'max_wait_seconds'. If the maximum time
+    # is exceeded, then it will raise a {OCI::Waiter::Errors::MaximumWaitTimeExceededError}.
+    #
+    # On successful completion the final Response object will be returned. The
+    # original Response object will not be altered.
+    #
+    # If any responses result in an error, then the error will be thrown as normal
+    # resulting in the wait being aborted.
+    #
+    # @param [Symbol] property The property of the response data to evaluate. For example, :lifecycle_state.
+    # @param state The value of the property that will indicate successful completion of the wait.
+    # @param [Integer] max_interval_seconds The maximum interval between queries, in seconds.
+    # @param [Integer] max_wait_seconds The maximum time to wait, in seconds.
+    # @yieldparam [Response] response A response object for every additional successful call to the get request.
+    #   Throw :stop_succeed from the yield to stop the waiter and return the current response.
+    #   Throw :stop_fail from the yield to stop the waiter and throw a WaiterFailedError.
+    # @return [Response] The final response, which will contain the property in the specified state.
+    def wait_until(property, state, max_interval_seconds: 30, max_wait_seconds: 1200)
+      raise 'Cannot wait on a response without data.' unless data
+      raise 'Response data does not contain the given property.' unless data.methods.include? property
+
+      raise Waiter::Errors::WaitUntilNotSupportedError, 'wait_until is not supported by this response.' unless @api_call
+
+      response = self
+      interval_seconds = 1
+      start_time = Time.now
+
+      loop do
+        return response if response.data.send(property) == state
+
+        elapsed_seconds = (Time.now - start_time).to_i
+
+        if elapsed_seconds + interval_seconds > max_wait_seconds
+          raise Waiter::Errors::MaximumWaitTimeExceededError, 'Maximum wait time has been exceeded.' \
+            unless max_wait_seconds > elapsed_seconds
+
+          # Make one last request right at the maximum wait time.
+          interval_seconds = max_wait_seconds - elapsed_seconds
+        end
+
+        sleep(interval_seconds)
+
+        interval_seconds *= 2
+        if interval_seconds > max_interval_seconds
+          interval_seconds = max_interval_seconds
+        end
+
+        response = @api_call.call(nil)
+
+        next unless block_given?
+
+        continue = false
+        catch(:stop_fail) do
+          catch(:stop_succeed) do
+            yield response
+            continue = true
+          end
+
+          return response unless continue
+        end
+
+        raise Waiter::Errors::WaiterFailedError unless continue
+      end
+    end
+  end
+end