oci 2.1.1 → 2.1.2

data/lib/oci/retry/functions/should_retry_on_error.rb

@@ -0,0 +1,28 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  module Retry
+    module Functions
+      # A module containing functions that can be used to determine whether to retry based on
+      # the error/exception encountered.
+      #
+      # These functions should take a single argument of a {OCI::Retry::Internal::RetryState}
+      # object
+      module ShouldRetryOnError
+        # Returns a proc which will retry on {OCI::Errors::NetworkError} and on {OCI::Errors::ServiceError}
+        # when the status code indicates a throttle (HTTP 429) or an internal server error
+        # (any HTTP 5xx)
+        #
+        # @return [Proc]
+        def self.retry_on_network_error_throttle_and_internal_server_errors
+          lambda do |retry_state|
+            return true if retry_state.last_exception.is_a?(OCI::Errors::NetworkError)
+            return false unless retry_state.last_exception.is_a?(OCI::Errors::ServiceError)
+
+            retry_state.last_exception.status_code == 429 || retry_state.last_exception.status_code >= 500
+          end
+        end
+      end
+    end
+  end
+end

data/lib/oci/retry/functions/sleep.rb

@@ -0,0 +1,85 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  module Retry
+    module Functions
+      # A module containing functions that can be used to calculate sleep times between retries.
+      #
+      # These functions should take two arguments: the first argument an object of type
+      # {OCI::Retry::RetryConfig} and the second an object of type {OCI::Retry::Internal::RetryState}
+      module Sleep
+        # Returns a proc which applies an exponential backoff with full jitter calculation. This is
+        # defined as:
+        #
+        #   random(0, min(base_sleep_time * (exponent**attempts), max_sleep_time_between_attempts))
+        #
+        # Where the base_sleep_time, exponent, max_sleep_time_between_attempts is taken from the
+        # {OCI::Retry::RetryConfig} provided to the proc and the attempts is taken from the
+        # {OCI::Retry::Internal::RetryState} provided to the proc.
+        #
+        # @return [Proc]
+        def self.exponential_backoff_with_full_jitter
+          lambda do |retry_config, retry_state|
+            random = Random.new
+            attempt = retry_state.current_attempt_number
+            base_sleep_millis = retry_config.base_sleep_time_millis
+            exponential_growth_factor = retry_config.exponential_growth_factor
+            max_sleep_time_millis = retry_config.max_sleep_between_attempts_millis
+
+            return random.rand(0..(base_sleep_millis * (exponential_growth_factor**attempt))) \
+              if max_sleep_time_millis.nil?
+
+            random.rand(0..[base_sleep_millis * (exponential_growth_factor**attempt), max_sleep_time_millis].min)
+          end
+        end
+        # rubocop:disable Metrics/AbcSize, Layout/EmptyLines
+
+
+        # Returns a proc which applies an exponential backoff with equal jitter calclulation. This is defined as:
+        #
+        #   base_sleep_time = min(base_sleep_time * (exponent**attempts), max_sleep_time)
+        #   (base_sleep_time / 2) + random(0, (base_sleep_time / 2))
+        #
+        # Where the base_sleep_time, exponent, max_sleep_time_between_attempts is taken from the
+        # {OCI::Retry::RetryConfig} provided to the proc and the attempts is taken from the
+        # {OCI::Retry::Internal::RetryState} provided to the proc.
+        #
+        # @return [Proc]
+        def self.exponential_backoff_with_equal_jitter
+          lambda do |retry_config, retry_state|
+            random = Random.new
+            attempt = retry_state.current_attempt_number
+            base_sleep_millis = retry_config.base_sleep_time_millis
+            exponential_growth_factor = retry_config.exponential_growth_factor
+            max_sleep_time_millis = retry_config.max_sleep_between_attempts_millis
+
+            sleep_raw = if max_sleep_time_millis.nil?
+                          base_sleep_millis * (exponential_growth_factor**attempt)
+                        else
+                          [base_sleep_millis * (exponential_growth_factor**attempt), max_sleep_time_millis].min
+                        end
+            (sleep_raw / 2) + random.rand(0..(sleep_raw / 2))
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Layout/EmptyLines
+
+        # Returns a proc which uses exponential backoff with full jitter for retries, except in the case of
+        # throttles where exponential backoff with equal jitter is used instead. This ensures some base
+        # level of sleep for throttles rather than, potentially, retrying again in quick succession
+        #
+        # @return [Proc]
+        def self.exponential_backoff_with_full_jitter_equal_on_throttle
+          lambda do |retry_config, retry_state|
+            use_equal_jitter =
+              !retry_state.last_exception.nil? &&
+              retry_state.last_exception.respond_to?(:status_code) &&
+              retry_state.last_exception.status_code == 429
+
+            return exponential_backoff_with_full_jitter.call(retry_config, retry_state) unless use_equal_jitter
+            exponential_backoff_with_equal_jitter.call(retry_config, retry_state)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/oci/retry/internal/retry_state.rb

@@ -0,0 +1,48 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'time'
+
+module OCI
+  module Retry
+    module Internal
+      # A property bag containing the current state of making a retriable call
+      class RetryState
+        # The current number of attempts which have been made.  This is one-based (i.e. the first attempt is 1,
+        # the second is 2 etc.)
+        attr_reader :current_attempt_number
+
+        # When we started making retriable calls, in epoch milliseconds
+        #
+        # @return [Integer]
+        attr_reader :start_time_epoch_millis
+
+        # The last exception which was raised when making a retriable call
+        #
+        # @return [Exception]
+        attr_accessor :last_exception
+
+        def initialize
+          @current_attempt_number = 0
+        end
+
+        # Increments the number of attempts which have been made by 1
+        def increment_attempts
+          @current_attempt_number += 1
+        end
+
+        # Sets the {#start_time_epoch_millis} property to the current time in epoch milliseconds. This can
+        # only be done once.
+        def start
+          raise 'The start_time for the retry state has already been set' unless @start_time_epoch_millis.nil?
+          @start_time_epoch_millis = (Time.now.to_f * 1000).to_i
+        end
+
+        def to_s
+          "{ 'current_attempt': '#{current_attempt_number}', " \
+          "'start_time_epoch_millis': '#{start_time_epoch_millis}', " \
+          "'last_exception': '#{last_exception}' }"
+        end
+      end
+    end
+  end
+end

data/lib/oci/retry/retry.rb

@@ -0,0 +1,85 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  # Module for retry strategies for use with the SDK when calling OCI services
+  module Retry
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+
+    # Takes a block and then executes it with retries based on the provided configuration.
+    #
+    # @param [OCI::Retry::RetryConfig] retry_config The configuration to be used for retries, defining what
+    #   exceptions to retry on, how to calculate sleep times between retries etc. If the parameter value is nil
+    #   then no retries are performed and the block is called once
+    #
+    # @param [String] operation_name A friendly name for the operation being called so that it can be written
+    #   to the logs
+    #
+    # @return [Object] The result of the block passed to this method
+    def self.make_retrying_call(retry_config, call_name: nil)
+      raise 'A block must be provided' unless block_given?
+
+      # If no retry configuration has been given, just do a single call
+      return yield if retry_config.nil?
+
+      retry_state = OCI::Retry::Internal::RetryState.new
+      retry_state.start
+
+      loop do
+        begin
+          OCI.logger.debug("[RETRYING_CALL] #{call_name}") if OCI.logger
+          return yield
+        rescue => e # rubocop:disable Style/RescueStandardError
+          retry_state.increment_attempts
+          retry_state.last_exception = e
+          if retry_config.should_retry?(retry_state)
+            if OCI.logger
+              OCI.logger.debug(
+                "[RETRYING] #{call_name} failed. Sleeping then retrying. Retry state: #{retry_state}"
+              )
+            end
+            retry_config.do_sleep(retry_state)
+          else
+            if OCI.logger
+              OCI.logger.debug(
+                "[RETRIES_EXHAUSTED] #{call_name} failed and exhausted retries. Retry state: #{retry_state}"
+              )
+            end
+            raise
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+    # Generates a token which can be used as a value for the opc-retry-token header value. The token will
+    # consist of uppercase letters (A-Z), lowercase letters (a-z) and digits (0-9)
+    #
+    # @param [Integer] token_length how many characters the token should be
+    #
+    # @return [String]
+    def self.generate_opc_retry_token(token_length = 32)
+      raise 'The token must be at least one character long' if token_length.nil? || token_length < 1
+
+      available_chars = ('a'..'z').to_a + ('A'..'Z').to_a + ('0'..'9').to_a
+      retry_token = ''
+      token_length.times { retry_token << available_chars[rand(available_chars.size)] }
+
+      retry_token
+    end
+
+    # A module containing functions that can be used with retries (e.g. for sleeping and working
+    # out whether a particular error/exception can be retried)
+    module Functions
+    end
+
+    # Internal functionality to support the {OCI::Retry} module. Not intended for public use.
+    module Internal
+    end
+  end
+end
+
+require 'oci/retry/retry_config'
+require 'oci/retry/functions/should_retry_on_error'
+require 'oci/retry/functions/sleep'
+require 'oci/retry/internal/retry_state'

data/lib/oci/retry/retry_config.rb

@@ -0,0 +1,121 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'time'
+
+module OCI
+  module Retry
+    # The configuration for a retry strategy
+    class RetryConfig
+      # The maximum number of attempts before we stop trying to make calls. This is one-based (i.e. the first attempt is 1,
+      # the second is 2 etc.) and nil indicates that there is no maximum.
+      #
+      # @return [Integer]
+      attr_reader :max_attempts
+
+      # The maximum amount of time (in milliseconds) that can elapse for all attempts before we stop trying
+      # to make calls. A nil value indicates that there is no maximum
+      #
+      # @return [Integer]
+      attr_reader :max_elapsed_time_millis
+
+      # A proc which can be called to determine whether a particular exception can be retried. This proc should
+      # take a single argument of type {OCI::Retry::Internal::RetryState}. The exception can be accessed via
+      # {OCI::Retry::Intenral::RetryState#last_exception}
+      #
+      # @return [Proc]
+      attr_reader :should_retry_exception_proc
+
+      # A proc which can be called to determine the next sleep time (in milliseconds) when retrying. This proc
+      # should take two arguments, the first argument of type {OCI::Retry::RetryConfig} and the second of type
+      # {OCI::Retry::Internal::RetryState}
+      #
+      # @return [Proc]
+      attr_reader :sleep_calc_millis_proc
+
+      # For exponential backoff and retry calculations, the base time (in milliseconds) which we multiply by
+      # some exponential value
+      #
+      # @return [Integer]
+      attr_reader :base_sleep_time_millis
+
+      # For exponential backoff and retry calculations, the exponent we'll raise to the number of attempts.
+      # The result would then be multiplied by the value in {#base_sleep_time_millis}
+      #
+      # @return [Integer]
+      attr_reader :exponential_growth_factor
+
+      # For exponential backoff and retry calclulation, the maximum amount of time (in milliseconds) to
+      # sleep between attempts. A nil value indicates that there is no maximum
+      #
+      # @return [Integer]
+      attr_reader :max_sleep_between_attempts_millis
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+
+      def initialize(
+        base_sleep_time_millis:,
+        exponential_growth_factor:,
+        should_retry_exception_proc:,
+        sleep_calc_millis_proc:,
+        max_attempts: nil,
+        max_elapsed_time_millis: nil,
+        max_sleep_between_attempts_millis: nil
+      )
+        raise 'base_sleep_time_millis must be greater than or equal to 1' \
+          if base_sleep_time_millis.nil? || base_sleep_time_millis < 1
+
+        raise 'exponential_growth_factor must be greater than or equal to 1' \
+          if exponential_growth_factor.nil? || exponential_growth_factor < 1
+
+        raise 'should_retry_exception_proc must be provided' if should_retry_exception_proc.nil?
+        raise 'sleep_calc_millis_proc must be provided' if sleep_calc_millis_proc.nil?
+
+        @base_sleep_time_millis = base_sleep_time_millis
+        @exponential_growth_factor = exponential_growth_factor
+        @should_retry_exception_proc = should_retry_exception_proc
+        @sleep_calc_millis_proc = sleep_calc_millis_proc
+
+        unless max_attempts.nil?
+          raise 'max_attempts must be greater than or equal to 1' if max_attempts < 1
+          @max_attempts = max_attempts
+        end
+
+        unless max_elapsed_time_millis.nil?
+          raise 'max_elapsed_time_millis must be greater than or equal to 0' if max_elapsed_time_millis < 0
+          @max_elapsed_time_millis = max_elapsed_time_millis
+        end
+
+        raise 'max_sleep_between_attempts_millis must be greater than or equal to 0' \
+          if max_sleep_between_attempts_millis && max_sleep_between_attempts_millis < 0
+        @max_sleep_between_attempts_millis = max_sleep_between_attempts_millis if max_sleep_between_attempts_millis
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/EmptyLines
+
+      # Determines whether we should retry a call based on the current state of making a retriable call and the values
+      # defined in this configuration.
+      #
+      # @param [OCI::Retry::Internal::RetryState] retry_state The current state of making a retriable call
+      #
+      # @return [Boolean] true if we should retry based on the current state and this configuration, and false
+      #   otherwise
+      def should_retry?(retry_state)
+        current_time = (Time.now.to_f * 1000).to_i
+        time_difference_millis = current_time - retry_state.start_time_epoch_millis
+
+        return false if @max_attempts && retry_state.current_attempt_number >= @max_attempts
+        return false if @max_elapsed_time_millis && time_difference_millis > @max_elapsed_time_millis
+
+        should_retry_exception_proc.call(retry_state)
+      end
+
+      # Sleeps for some amount of time based on the current state of making a retriable call
+      #
+      # @param [OCI::Retry::Internal::RetryState] retry_state The current state of making a retriable call
+      def do_sleep(retry_state)
+        sleep_time_millis = sleep_calc_millis_proc.call(self, retry_state)
+        sleep(sleep_time_millis / 1000.0)
+      end
+    end
+  end
+end

data/lib/oci/version.rb

@@ -1,5 +1,5 @@
 # Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 
 module OCI
-  VERSION = '2.1.1'.freeze
+  VERSION = '2.1.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oci
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.2
 platform: ruby
 authors:
 - Oracle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-18 00:00:00.000000000 Z
+date: 2018-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -98,14 +98,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7.6
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7.6
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.12
 - !ruby/object:Gem::Dependency
   name: os
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +126,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.55'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.55'
 description: Ruby SDK for Oracle Cloud Infrastructure.
 email:
 - joe.levy@oracle.com
@@ -462,12 +488,15 @@ files:
 - "./lib/oci/load_balancer/models/create_backend_details.rb"
 - "./lib/oci/load_balancer/models/create_backend_set_details.rb"
 - "./lib/oci/load_balancer/models/create_certificate_details.rb"
+- "./lib/oci/load_balancer/models/create_hostname_details.rb"
 - "./lib/oci/load_balancer/models/create_listener_details.rb"
 - "./lib/oci/load_balancer/models/create_load_balancer_details.rb"
 - "./lib/oci/load_balancer/models/create_path_route_set_details.rb"
 - "./lib/oci/load_balancer/models/health_check_result.rb"
 - "./lib/oci/load_balancer/models/health_checker.rb"
 - "./lib/oci/load_balancer/models/health_checker_details.rb"
+- "./lib/oci/load_balancer/models/hostname.rb"
+- "./lib/oci/load_balancer/models/hostname_details.rb"
 - "./lib/oci/load_balancer/models/ip_address.rb"
 - "./lib/oci/load_balancer/models/listener.rb"
 - "./lib/oci/load_balancer/models/listener_details.rb"
@@ -487,6 +516,7 @@ files:
 - "./lib/oci/load_balancer/models/update_backend_details.rb"
 - "./lib/oci/load_balancer/models/update_backend_set_details.rb"
 - "./lib/oci/load_balancer/models/update_health_checker_details.rb"
+- "./lib/oci/load_balancer/models/update_hostname_details.rb"
 - "./lib/oci/load_balancer/models/update_listener_details.rb"
 - "./lib/oci/load_balancer/models/update_load_balancer_details.rb"
 - "./lib/oci/load_balancer/models/update_path_route_set_details.rb"
@@ -526,6 +556,11 @@ files:
 - "./lib/oci/regions.rb"
 - "./lib/oci/response.rb"
 - "./lib/oci/response_headers.rb"
+- "./lib/oci/retry/functions/should_retry_on_error.rb"
+- "./lib/oci/retry/functions/sleep.rb"
+- "./lib/oci/retry/internal/retry_state.rb"
+- "./lib/oci/retry/retry.rb"
+- "./lib/oci/retry/retry_config.rb"
 - "./lib/oci/signer.rb"
 - "./lib/oci/version.rb"
 - "./lib/oci/waiter.rb"