johac 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c9a6e0cd9ab2cb5c7aba657db7c59a726d7ec85a
+  data.tar.gz: c25864469ee9ace99f7b21fc7982a1bec72a8f69
+SHA512:
+  metadata.gz: c6a3065a97f85e39e4a05963b559eb0d9260200c7898953485b58217df614f6c99f44846d9616ce50995fd7d1af9e83fba414ac528818e0cd9f838654d954ac7
+  data.tar.gz: 5bd7feade84a9af0a72e0341bf8ddb048867ce778d6aff22ee0f310d6d9a0ff38500d091c712cc5867d911eda69a4fec8687a96b65a985fc26376be97f021b2b

data/lib/johac/client.rb

@@ -0,0 +1,73 @@
+module Johac
+
+  # Base class for Johac API Client.
+  #
+  # Extend this class and provide API specific calls
+  class Client
+
+    attr_reader :config
+
+    # HTTP lib inclusion
+    #
+    # Supplies one method, {#connection}.
+    #
+    # The {#connection} method should return an object that responds to HTTP verbs (eg. #get, #post, #put, #delete).
+    include Connection
+
+    # @param config [Johac::Config]
+    def initialize(config=nil)
+      @config = Johac.merged_config(config)
+    end
+
+    # Reference to +base_uri+ set on {Johac.config} in {Johac.configure} or in the constructor.
+    #
+    # @return [String]
+    def uri
+      config.base_uri
+    end
+
+    # Reference to the current environment. Set explicitly in {Johac.configure} or via
+    # environment variables +JOHAC_ENV+ or +RAILS_ENV+.
+    #
+    # @return [String] One of "testing", "development", or "production"
+    def env
+      config.env
+    end
+
+    protected
+
+    def head(path, options={})
+      request { connection.head(path, options[:query], options[:headers]) }
+    end
+
+    def get(path, options={})
+      request { connection.get(path, options[:query], options[:headers]) }
+    end
+
+    def delete(path, options={})
+      request { connection.delete(path, options[:query], options[:headers]) }
+    end
+
+    def post(path, options={})
+      request { connection.post(path, options[:body], options[:headers]) }
+    end
+
+    def put(path, options={})
+      request { connection.put(path, options[:body], options[:headers]) }
+    end
+
+    def patch(path, options={})
+      request { connection.patch(path, options[:body], options[:headers]) }
+    end
+
+    private
+
+    # Wrap the response or error, or raise an exception if configured
+    def request(&block)
+      Johac::Response.new(yield)
+    rescue => e
+      @config.raise_exceptions ? (raise e) : Johac::Response.new(e)
+    end
+
+  end
+end

data/lib/johac/connection.rb

@@ -0,0 +1,185 @@
+module Johac
+
+  # Provides {#connection}.
+  #
+  # Uses the {https://github.com/lostisland/faraday faraday} lib to handle HTTP requests.
+  #
+  # @see https://github.com/lostisland/faraday
+  module Connection
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(:url => uri) do |faraday|
+        faraday.use :johac_connection_exceptions
+
+        faraday.request :json
+        faraday.request :johac_headers
+        faraday.request :johac_auth, @config.auth_scheme, @config.access_key, @config.secret_key
+
+        # Retry requests
+        faraday.request :retry, {
+          max: 2,
+          interval: 0.5,
+          backoff_factor: 3,
+          interval_randomness: 0.5,
+
+          # All connection errors + 429, 503, and 504
+          exceptions: [
+            Johac::Error::ConnectionError,
+            Johac::Error::RetryableError
+          ]
+        }
+
+        # apparently the response middleware acts like a stack, not a queue
+        faraday.response :json
+
+        # Raise connection errors as exceptions
+        faraday.response :johac_raise_error
+
+        faraday.adapter :johac_persistent do |http|
+          # http param is an instance of Net::HTTP::Persistent
+          #
+          http.open_timeout = 2
+          http.read_timeout = 60
+          http.idle_timeout = 120
+
+          # http.keep_alive
+          # http.max_requests
+          # http.socket_options
+          http.debug_output = STDOUT if env == 'development'
+        end
+      end
+    end
+
+  end
+
+  # Custom middleware.
+  module Connection::Middleware
+
+    # Wrapper of {Faraday::Adapter::NetHttpPersistent} adapter that allows for
+    # a block to be given when the faraday connection is created. Block is
+    # passed the newly created {Net::HTTP::Persistent} instance to be modified
+    # if desired.
+    #
+    # Allows for configuration of HTTP connection.
+    #
+    # @see https://github.com/lostisland/faraday
+    # @see https://github.com/drbrain/net-http-persistent
+    class PersistentAdapter < Faraday::Adapter::NetHttpPersistent
+
+      Faraday::Adapter.register_middleware :johac_persistent => self
+
+      # Extend Faraday::Adapter::NetHttpPersistent's initialize method with an
+      # optional block.
+      #
+      # @yield [Net::HTTP::Persistent] Stores the passed block for use when
+      #   creating a new HTTP connection.
+      def initialize(app, &block)
+        @config_block = block
+        super(app)
+      end
+
+      # Yield HTTP connection to supplied block.
+      def with_net_http_connection(env, &block)
+        http = super(env) { |v| v }
+        @config_block.call(http) if @config_block
+        yield http
+      end
+
+    end
+
+    # Write custom user agent to all requests.
+    class JohacHeaders < Faraday::Middleware
+
+      Faraday::Request.register_middleware :johac_headers => self
+
+      AgentString = "johac/#{Johac::Version} ruby/#{RUBY_VERSION}".freeze
+      Accept      = 'application/json'.freeze
+
+      def call(env)
+        env[:request_headers]['User-Agent'] = AgentString
+        env[:request_headers]['Accept'] = Accept
+        @app.call(env)
+      end
+
+    end
+
+    # Adds Authorization header to all requests.
+    class Authorization < Faraday::Middleware
+
+      Faraday::Request.register_middleware :johac_auth => self
+
+      def initialize(app, scheme, access_key, secret_key)
+        @scheme = scheme
+        @access_key = access_key
+        @secret_key = secret_key
+        super(app)
+      end
+
+      def call(env)
+        if auth = case @scheme
+                  when :basic then "Basic #{basic_auth_token}"
+                  when :hmac  then "hmac #{hmac_auth_token(env.url.path)}"
+                  end
+          env[:request_headers]['Authorization'] = auth
+        end
+        @app.call(env)
+      end
+
+      private
+
+      def basic_auth_token
+        Base64.strict_encode64("#{@access_key}:#{@secret_key}")
+      end
+
+      # TODO: Need a hook for generating the value
+      def hmac_auth_token(token)
+        OpenSSL::HMAC.hexdigest('sha1', @secret_key, token)
+      end
+
+    end
+
+    # Will raise some {Johac::Error::ResponseError} from an HTTP response using status codes.
+    class RaiseError < Faraday::Response::Middleware
+
+      Faraday::Response.register_middleware :johac_raise_error => self
+
+      def on_complete(env)
+        if e = ::Johac::Error::ResponseError.from_response(env.status, env.response_headers, env.body)
+          raise e
+        end
+      end
+
+    end
+
+    # Will raise some {Johac::Error::ConnectionError} if something happens with the connection.
+    class Exceptions < Faraday::Middleware
+
+      Faraday::Middleware.register_middleware :johac_connection_exceptions => self
+
+      def call(env)
+        @app.call(env)
+      rescue Faraday::Error::ConnectionFailed => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error::ResourceNotFound => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error::ParsingError => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error::TimeoutError => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error::SSLError => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error::ClientError => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Faraday::Error => e
+        raise ::Johac::Error::ConnectionError, e.message
+      rescue Net::HTTP::Persistent::Error => e
+        raise ::Johac::Error::ConnectionError, e.message, e.backtrace
+      end
+
+    end
+
+  end
+
+end

data/lib/johac/error.rb

@@ -0,0 +1,66 @@
+module Johac
+
+  # {Johac} exception overrides.
+  #
+  # Rescue {Johac::Error Johac::Error} to catch all Johac errors.
+  class Error < StandardError
+
+    # Exception to be used when dealing with HTTP responses from a Johac API.
+    class ResponseError < Error
+
+      attr_reader :code
+      attr_reader :body
+
+      # Will attempt to decode a response body via JSON, and look for the 'message' key in the resulting (assumed) hash. If response body cannot be parsed via JSON the entire response body is set as the message for the exception.
+      #
+      # @param body [String] Response body.
+      # @param headers [Hash] Response headers.
+      def initialize(code, body, headers)
+        @code = code
+        @body = if headers['Content-Type'] == 'application/json'
+          JSON.parse(body) rescue body
+        else
+          body
+        end
+        super(body)
+      end
+
+      # If a problem is detected in an HTTP response, build the proper exception, otherwise return nil.
+      #
+      # @param status_code [Integer] HTTP response code.
+      # @param body [String] Response body.
+      # @param headers [Hash] Response headers.
+      #
+      # @return [Johac::Error::RetryableError] A client or server error which may be retried
+      # @return [Johac::Error::ClientError] The client has made a mistake and should take corrective action.
+      # @return [Johac::Error::ServerError] If there was a problem server-side, we're on it.
+      # @return [nil] If no error was detected in the response.
+      def self.from_response(status_code, headers, body)
+        if klass =  case status_code
+                    when 429 then RetryableError
+                    when 503 then RetryableError
+                    when 504 then RetryableError
+                    when 400..499 then ClientError
+                    when 500..599 then ServerError
+                    end
+          klass.new(status_code, body, headers)
+        end
+      end
+
+    end
+
+    # An error that we should retry
+    class RetryableError        < ResponseError; end
+
+    # There was a problem on our side, we're working on it.
+    class ServerError           < ResponseError; end
+
+    # There was a problem with the requested or submitted resource.
+    class ClientError           < ResponseError; end
+
+    # Error specific to the http connection.
+    class ConnectionError       < Error; end
+
+  end
+
+end

data/lib/johac/response.rb

@@ -0,0 +1,128 @@
+module Johac
+  class Response
+
+    attr_reader :response
+    attr_reader :exception
+
+    include Enumerable
+
+    def initialize(result)
+      if result.kind_of?(Faraday::Response)
+        @response = result
+      else
+        @exception = result
+      end
+    end
+
+    # Determine if the request failed
+    #
+    # @return true if response failed (http or expcetion)
+    def error?
+      exception != nil || status >= 400
+    end
+
+    # HTTP Status code
+    #
+    # @return response status code
+    def status
+      response_status || exception_status || 0
+    end
+
+    # HTTP Status code
+    #
+    # @return response status code
+    def code
+      status
+    end
+
+    # HTTP Response body as a JSON parsed object
+    #
+    # @return Hash/Array of the JSON parsed body, or empty hash
+    def body
+      response_body || exception_body || {}
+    end
+
+    # @return OpenStruct object of hash
+    def object
+      OpenStruct.new(body)
+    end
+
+    # Map body hash to another value using a block
+    #
+    # @param block [Block] mapping function block
+    #
+    # @return result of block
+    def map_object(&block)
+      yield body
+    end
+
+    # Dig for a item in the body
+    #
+    # @param args [Varargs] path of value
+    #
+    # @see {Hash.dig}
+    # @see {Array.dig}
+    #
+    # @return value of key path
+    def dig(*args)
+      body.dig(*args)
+    end
+
+    # Enumerate over response body opject
+    #
+    # @see {Enumerable}
+    # @param block [Block] to invoke
+    def each(&block)
+      body.each(&block)
+    end
+
+    # Invoke a block of code if the response fails, with
+    # the exception as the paramter.
+    #
+    # @param block [Block] to invoke
+    def on_error(&block)
+      if error?
+        yield exception
+      end
+      self
+    end
+
+    # Invoke a block of code if the response succeeds, with the content
+    # as a parameter
+    #
+    # @param block [Block] to invoke
+    def on_success(&block)
+      unless error?
+        yield body
+      end
+      self
+    end
+
+    protected
+
+    def response_status
+      response? ? response.status : nil
+    end
+
+    def response_body
+      response? ? response.body : nil
+    end
+
+    def exception_status
+      response_error? ? exception.code : nil
+    end
+
+    def exception_body
+      response_error? ? exception.body : nil
+    end
+
+    def response_error?
+      exception.kind_of?(Johac::Error::ResponseError)
+    end
+
+    def response?
+      response != nil
+    end
+
+  end
+end

data/lib/johac/version.rb

@@ -0,0 +1,3 @@
+module Johac
+  Version = '0.9.0'
+end

data/lib/johac.rb

@@ -0,0 +1,95 @@
+$: << File.dirname(__FILE__)
+
+require 'json'
+require 'faraday'
+require 'faraday_middleware'
+require 'net/http/persistent'
+require 'base64'
+require 'ostruct'
+
+module Johac
+
+  class << self
+
+    # Simple config class used to store global {Johac::Client} settings.
+    #
+    # @attr base_uri    [String] Hostname of Johac API.
+    # @attr auth_scheme [Symbol] Authorization scheme to be used on all requests, +:basic+ or +:hmac+.
+    # @attr access_key  [String] Public access key used for authorization of requests.
+    # @attr secret_key  [String] Private key used for authorization of requests.
+    # @attr env         [String] Environment. 'testing', 'development', or 'production'.
+    Config = Struct.new(:base_uri, :auth_scheme, :access_key, :secret_key, :env, :logger, :raise_exceptions)
+
+
+    # Configure the global defaults for all clients built.
+    #
+    # @yield [config] Passes a config object to the block.
+    # @yieldparam config [Johac::Config] Config object.
+    #
+    # @example
+    #   Johac.defaults do |config|
+    #     config.base_uri = 'http://api.myservice.com'
+    #     config.auth_scheme = :basic
+    #     config.access_key = 'user'
+    #     config.secret_key = 'password'
+    #   end
+    #
+    # @return [Johac::Config]
+    def defaults(&block)
+      c = @config ||= Config.new
+      c.env = environment || 'production'
+      yield c
+      c
+    end
+
+    # Return the config object for the global {Johac::Client} instance.
+    # @return [Johac::Config]
+    def config
+      unless defined? @config
+        raise "#{self.name} not configured. Configure via #{self.name}.configure { |cfg| ... }, or via client constructor"
+      end
+      @config
+    end
+
+    # Merge the new config with defaults
+    def merged_config(overrides)
+      case overrides
+      when Hash
+        dup_config.tap do |conf|
+          overrides.each do |k, v|
+            conf[k] = v
+          end
+        end
+      when Struct
+        dup_config.tap do |conf|
+          overrides.each_pair do |k, v|
+            conf[k] = v
+          end
+        end
+      else
+        config
+      end
+    end
+
+    protected
+
+    def environment
+      ENV.values_at('JOHAC_ENV', 'RAILS_ENV').compact.first
+    end
+
+    private
+
+    def dup_config
+      defined?(@config) ? @config.dup : Config.new
+    end
+
+  end
+
+end
+
+require 'johac/version'
+require 'johac/error'
+require 'johac/connection'
+require 'johac/response'
+require 'johac/client'
+

metadata

@@ -0,0 +1,186 @@
+--- !ruby/object:Gem::Specification
+name: johac
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Dan Simpson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-05-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.9.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.9.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.7.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.7.5
+description: Opintionated library for implement HTTP+JSON API clients
+email: dan.simpson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/johac.rb
+- lib/johac/client.rb
+- lib/johac/connection.rb
+- lib/johac/error.rb
+- lib/johac/response.rb
+- lib/johac/version.rb
+homepage: https://github.com/dansimpson/johac
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: JSON Over HTTP API Client
+test_files: []
+has_rdoc: true