postmen 1.0.0.pre.alpha.1 → 1.0.0.pre.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef3279747f60ddf021d56412eed1d833adb77f1c
-  data.tar.gz: e93b892733da84d2b7d3ae556c004baef30bc9f6
+  metadata.gz: 05652c1c08402bef17419ea6b02586580eae907e
+  data.tar.gz: 8f6676faa166b9ba2f59248593198cfc4d60e8c0
 SHA512:
-  metadata.gz: 721df92fa7baf87693a78098a04cf5f1986f8829ff2f83a752899767fd2aa147ab252f16065b807408108e3872ae6e81c972c024c7231c06ea6c09ec4a02a625
-  data.tar.gz: 9436a466ca9044c098e05e3df986861bbe5f64dd257f944f486341cddc5dfbd791437bc0dee7ffea3df7e234f352fd96f38893dd0380dbd7ced2ab4f7f5867db
+  metadata.gz: 47156b956f5511b485afbee474f381f78e080d7844d642e7d39654417039cfc5b7bea409adef20ffc65df77d8d5bc1bcc5f31f1b04ab8f0b7d9230e30abdf9a0
+  data.tar.gz: bf6f08c3f8ace491be96fe8d75b90a82663386008a64ecb6ddd633ea7a1dcb5f3aa4ad9061e4dab3e3a91162cf8acc9bb37c548e7bc84127283133c3ee778ec8

data/lib/postmen/connection.rb

@@ -5,6 +5,12 @@ class Postmen
     # Maximum number of retries
     MAX_REQUESTS = 5
 
+    # Main domain used during normal usage.
+    MAIN_DOMAIN = 'postmen.com'.freeze
+
+    # Failover domain used during DNS issues with main domain
+    FAILOVER_DOMAIN = 'postmen.net'.freeze
+
     def initialize
       @requests = 0
     end
@@ -17,12 +23,9 @@ class Postmen
     #   .get('/labels')
     #   .get('/labels', { params: { limit: 5 } })
     def get(path, options = {})
-      Response.new(raw_get(path, options)).tap(&:parse_response!)
-    rescue RateLimitExceeded
-      @requests += 1
-      raise if @requests > MAX_REQUESTS
-      sleep(60)
-      retry
+      with_error_handling do
+        Response.new(raw_get(path, options)).tap(&:parse_response!)
+      end
     end
 
     # Performs a HTTP POST request.
@@ -33,7 +36,9 @@ class Postmen
     #   .post('/labels')
     #   .post('/labels', { json: { my: { sample: :data } } })
     def post(path, options = {})
-      Response.new(raw_post(path, options))
+      with_error_handling do
+        Response.new(raw_post(path, options))
+      end
     end
 
     # Performs a HTTP PUT request.
@@ -44,8 +49,11 @@ class Postmen
     #   .put('/shipper-accounts/123/info')
     #   ..put('/shipper-accounts/123/info', { json: { my: { sample: :data } } })
     def put(path, options = {})
-      Response.new(raw_put(path, options))
+      with_error_handling do
+        Response.new(raw_put(path, options)).tap(&:parse_response!)
+      end
     end
+
     # Performs a HTTP DELETE request
     #
     # @param path [String]
@@ -57,8 +65,74 @@ class Postmen
         .delete(get_full_url(path))
     end
 
+    # Returns the endpoint used in SDK, based on the region(subdomain) and
+    # a failover switch
+    #
+    # @param subdomain [String] The region/subdomain used.
+    # @param failover [Boolean]
+    def self.endpoint(subdomain, failover = false)
+      URI::HTTPS.build(scheme: 'https',
+                       host: hostname(subdomain, failover),
+                       path: '/v3').to_s
+    end
+
+    # Returns the hostname based on the region(subdomain) and a failover switch
+    #
+    # @param subdomain [String] The region/subdomain used.
+    # @param failover [Boolean]
+    def self.hostname(subdomain, failover)
+      base = failover ? FAILOVER_DOMAIN : MAIN_DOMAIN
+      [subdomain, base].join('.')
+    end
+
     private
 
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def with_error_handling
+      raise ArgumentError unless block_given?
+
+      begin
+        yield
+      # Rescue from any  connection issues
+      rescue HTTP::ConnectionError
+        # Raise error if we already tried to use failover domain
+        raise if Postmen.failover?
+        # Switch to failover domain & retry the request
+        Postmen.failover!
+        retry
+      # Handle Rate limits.
+      # Rate limits are being reset every 60 seconds - we're retrying
+      # given request after that.
+      # @see https://docs.postmen.com/ratelimit.html Documentation
+      rescue RateLimitExceeded
+        @requests += 1
+        raise if @requests > MAX_REQUESTS
+        sleep(60)
+        retry
+      # If the resource was not found, simply re-raise the exception
+      rescue ResourceNotFound
+        raise
+      # Handle request errors.
+      # Our current error handling policy depends on the error type.
+      # If the API returns information, that the request is retriable,
+      # We're waiting 5 seconds, and trying again with exact same request.
+      # To prevent having infinite loops, we're trying maximum 5 times.
+      # In case that we were unable to make successfull request with that 5 tries,
+      # MaximumNumberOfRetriesReachedError is being raised.
+      #
+      # @raise RequestError if the request is not retriable
+      # @raise MaximumNumberOfRetriesReachedError if the API returned error after 5 retries
+      rescue RequestError => error
+        raise unless error.retriable?
+        raise MaximumNumberOfRetriesReachedError, self if @requests > MAX_REQUESTS
+        @requests += 1
+        sleep(5)
+        retry
+      end
+    end
+
     def raw_get(path, options)
       HTTP
         .headers(headers)

data/lib/postmen/errors.rb

@@ -0,0 +1,52 @@
+class Postmen
+  # Generic Exception class, all other exceptions should inherit from this class
+  Error = Class.new(StandardError)
+
+  # Generic exception raised if the API returns an error
+  class RequestError < Error
+    extend Forwardable
+
+    def_delegators :@request, :meta, :data
+
+    def initialize(request)
+      @request = request
+    end
+
+    # Indicates whether request is retryable.
+    # @see https://docs.postmen.com/errors.html API Documentation
+    def retryable?
+      meta.fetch(:retryable, false)
+    end
+
+    # Returns details for the request error
+    # @see https://docs.postmen.com/#meta API Documentation
+    def details
+      meta[:details]
+    end
+
+    # Internal API error code
+    # @see https://docs.postmen.com/errors.html List of Error codes
+    def code
+      meta[:code]
+    end
+
+    # Returns human-readable error message
+    # @see https://docs.postmen.com/#meta API Documentation
+    def message
+      meta[:message]
+    end
+
+    private
+
+    attr_reader :request
+  end
+
+  # Exception raised if rate limit was exceeded
+  RateLimitExceeded = Class.new(Error)
+  # Exception raised in case of any connection error
+  ConnectionError = Class.new(Error)
+  # Exception raised if retriable request reached maximum number of attempts.
+  MaximumNumberOfRetriesReachedError = Class.new(Error)
+  # Expcetion raised if resource was not found.
+  ResourceNotFound = Class.new(RequestError)
+end

data/lib/postmen/response.rb

@@ -16,12 +16,24 @@ class Postmen
       @meta ||= parsed_response[:meta]
     end
 
+    # Holds the data
+    # @see https://docs.postmen.com/#data API Documentation
+    # @return [Hash]
+    def data
+      @data ||= parsed_response[:data]
+    end
+
     # Parses the json response
     # @return [Hash]
     def parsed_response
       @parsed_response ||= JSON.parse(body, symbolize_names: true)
     end
 
+    # Checks if response were successfull
+    def success?
+      meta[:code] == 200
+    end
+
     # Checks if rate limit was exceeded
     def rate_limit_exceeded?
       code == 429

data/lib/postmen/shipper_account.rb

@@ -47,11 +47,46 @@ class Postmen
     #
     # @see https://docs.postmen.com/api.html#shipper-accounts-update-a-shipper-account-credentials
     # @return [ShipperAccount] Updated ShipperAccount resource
-    def update_credentials(params = {})
-      Connection.new.put(
+    # @raise [RequestError]
+    def update_credentials!(params = {})
+      response = Connection.new.put(
         "/shipper-accounts/#{@id}/credentials",
-        ShipperAccountUpdateCredentialsQuery.new(params).to_hash
+        ShipperAccountUpdateCredentialsQuery.new(params).to_query
+      )
+
+      raise RequestError, response unless response.success?
+
+      ShipperAccount.new(response.data)
+    end
+
+    # Update a ShipperAccount credentials
+    #
+    # @see https://docs.postmen.com/api.html#shipper-accounts-update-a-shipper-account-credentials
+    # @return [ShipperAccount] Updated ShipperAccount resource
+    # @return [Hash] a Hash with detailed information about what went wrong
+    def update_credentials(params = {})
+      update_credentials!(params)
+    rescue RequestError => error
+      error.meta
+    end
+
+    # Update a shipper account information
+    #
+    # @see https://docs.postmen.com/api.html#shipper-accounts-update-a-shipper-account-information API Documentation
+    # @example
+    #   .update(description: "Your new description")
+    #   .update(address: {})
+    # @return [ShipperAccount] Updated ShipperAccount resource
+    # @raise [RequestError]
+    def update!(params = {})
+      response = Connection.new.put(
+        "/shipper-accounts/#{@id}/info",
+        ShipperAccountUpdateQuery.new(params.merge(subject: self)).to_query
       )
+
+      raise RequestError, response unless response.success?
+
+      ShipperAccount.new(response.data)
     end
 
     # Update a shipper account information
@@ -61,8 +96,11 @@ class Postmen
     #   .update(description: "Your new description")
     #   .update(address: {})
     # @return [ShipperAccount] Updated ShipperAccount resource
+    # @return [Hash] a Hash with detailed information about what went wrong
     def update(params = {})
-      Connection.new.put("/shipper-accounts/#{@id}/info", ShipperAccountUpdateQuery.new(params.merge(subject: self)).to_query)
+      update!(params)
+    rescue RequestError => error
+      error.meta
     end
   end
 end

data/lib/postmen/shipper_account_collection.rb

@@ -33,7 +33,12 @@ class Postmen
     # @see https://docs.postmen.com/api.html#shipper-accounts-create-a-shipper-account API documentation
     # @return [ShipperAccount]
     def self.create(params)
-      ShipperAccount.new(Connection.new.post('/shipper-accounts', CreateShipperAccountQuery.new(params).to_query).parsed_response[:data])
+      ShipperAccount.new(
+        Connection.new.post(
+          '/shipper-accounts',
+          CreateShipperAccountQuery.new(params).to_query
+        ).parsed_response[:data]
+      )
     end
   end
 end

data/lib/postmen/version.rb

@@ -1,4 +1,4 @@
 class Postmen
   # SDK Version
-  VERSION = '1.0.0-alpha.1'.freeze
+  VERSION = '1.0.0-alpha.2'.freeze
 end

data/lib/postmen.rb

@@ -6,6 +6,7 @@ require 'pathname'
 require 'forwardable'
 
 require 'postmen/version'
+require 'postmen/errors'
 require 'postmen/types'
 require 'postmen/connection'
 require 'postmen/collection_proxy'
@@ -37,17 +38,6 @@ require 'postmen/manifest_collection'
 class Postmen
   extend Dry::Configurable
 
-  # Generic Exception class, all other exceptions should inherit from this class
-  Error = Class.new(StandardError)
-  # Exception raised if rate limit was exceeded
-  RateLimitExceeded = Class.new(Error)
-  # Exception raised in case of any connection error
-  ConnectionError = Class.new(Error)
-  # Generic exception raised if the API returns an error
-  RequestError = Class.new(Error)
-  # Expcetion raised if resource was not found.
-  ResourceNotFound = Class.new(RequestError)
-
   # @#!attribute [rw] api_key [String] API key taken from the application.
   setting :api_key
 
@@ -57,11 +47,14 @@ class Postmen
   # @#!attribute endpoint [String] Endoint name - specify if you'd like to use custom endpoint
   setting :endpoint
 
+  # @#!attribute failover [Bool] Indicates if the SDK is using failover domain.
+  setting :failover, false
+
   # Returns the endpoint used in all queries
   #
   # @return [String] endpoint url
   def self.endpoint
-    config.endpoint || "https://#{config.region}-api.postmen.com/v3"
+    config.endpoint || Connection.endpoint("#{config.region}-api", config.failover)
   end
 
   # Returns path where gem is installed
@@ -70,4 +63,14 @@ class Postmen
   def self.root
     Pathname.new(File.expand_path(File.join(File.dirname(__FILE__), '../')))
   end
+
+  # Checks wheter we're in failover mode
+  def self.failover?
+    !!config.failover
+  end
+
+  # Switch to failover domain
+  def self.failover!
+    config.failover = true
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: postmen
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha.1
+  version: 1.0.0.pre.alpha.2
 platform: ruby
 authors:
 - postmen.com
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-03 00:00:00.000000000 Z
+date: 2017-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -161,6 +161,7 @@ files:
 - lib/postmen.rb
 - lib/postmen/collection_proxy.rb
 - lib/postmen/connection.rb
+- lib/postmen/errors.rb
 - lib/postmen/label.rb
 - lib/postmen/label_collection.rb
 - lib/postmen/manifest.rb