ncore 1.0.0

data/lib/ncore/builder.rb

@@ -0,0 +1,34 @@
+module NCore
+  module Builder
+    extend ActiveSupport::Concern
+    
+    included do
+      class_eval <<-INCL, __FILE__, __LINE__+1
+        include NCore::Exceptions
+
+        module Api
+          include NCore::Configuration
+        end
+
+        class Resource
+          extend Api
+          include NCore::Base
+        end
+        class SingletonResource
+          extend Api
+          include NCore::SingletonBase
+        end
+
+        class GenericObject < Resource
+        end
+
+        class << self
+          def configure(&block)
+            Api.instance_eval &block
+          end
+        end
+      INCL
+    end
+
+  end
+end

data/lib/ncore/client.rb

@@ -0,0 +1,301 @@
+module NCore
+  module Client
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      def request(method, url, request_credentials, params={}, headers={})
+        request_credentials ||= retrieve_credentials
+        request_credentials = parse_credentials(request_credentials)
+
+        base_url = request_credentials[:url] || retrieve_default_url
+        base_url << '/' unless base_url.ends_with?('/')
+        url = base_url + url
+
+        headers = build_headers(headers, request_credentials.except(:url))
+
+        path = URI.parse(url).path
+        if [:get, :head, :delete].include? method
+          qs = build_query_string params
+          url += qs
+          path += qs
+          payload = nil
+        else
+          payload = MultiJson.encode params
+        end
+
+        rest_opts = {
+          body: payload,
+          # connect_timeout: 10,
+          headers: headers,
+          method: method,
+          path: path,
+          read_timeout: 50,
+          url: url,
+          write_timeout: 50,
+        }
+
+        response = execute_request(rest_opts)
+        parsed = parse_response(response)
+        [parsed, request_credentials]
+      end
+
+
+      private
+
+      def retrieve_credentials
+        if credentials.blank?
+          raise parent::Error, credentials_error_message
+        end
+        credentials
+      end
+
+      def parse_credentials(creds)
+        creds.with_indifferent_access
+      end
+
+      def retrieve_default_url
+        if default_url.blank?
+          raise parent::Error, credentials_error_message
+        end
+        default_url
+      end
+
+      def build_headers(headers, req_credentials)
+        h = {}
+        [default_headers, auth_headers(req_credentials), headers].each do |set|
+          set.each do |k,v|
+            k = k.to_s.titlecase.gsub(/ /,'-')
+            h[k] = v
+          end
+        end
+        h
+      end
+
+      def build_query_string(params)
+        if params.any?
+          query_string = params.map do |k,v|
+            if v.is_a?(Array)
+              if v.empty?
+                "#{k.to_s}[]="
+              else
+                v.map do |v2|
+                  "#{k.to_s}[]=#{CGI::escape(v2.to_s)}"
+                end.join('&')
+              end
+            else
+              "#{k.to_s}=#{CGI::escape(v.to_s)}"
+            end
+          end.join('&')
+          "?#{query_string}"
+        else
+          ''
+        end
+      end
+
+
+      def host_for_error(uri)
+        u = URI.parse uri
+        "#{u.host}:#{u.port}"
+      rescue
+        uri
+      end
+
+
+      # create a new excon client if necessary
+      # keeps a pool of the last 10 urls
+      #   in almost all cases this will be more than enough 
+      def excon_client(uri)
+        u = URI.parse uri
+        u.path = ''
+        u.user = u.password = u.query = nil
+        addr = u.to_s
+
+        if cl = pool[addr]
+          unless pool.keys.last == addr
+            pool.delete addr
+            pool[addr] = cl # move it to the end
+          end
+          cl
+        else
+          if pool.size >= 10 # keep a max of ten at once
+            to_close = pool.delete pool.keys.first
+            to_close.reset
+          end
+          ex_opts = {
+            connect_timeout: 10,
+            persistent: true
+          }
+          if verify_ssl_cert?
+            ex_opts.merge!(
+              ssl_ca_file: ssl_cert_bundle,
+              ssl_verify_peer: OpenSSL::SSL::VERIFY_PEER
+            )
+          else
+            ex_opts.merge! ssl_verify_peer: false
+          end
+          pool[addr] = Excon.new(addr, ex_opts)
+        end
+      end
+
+      def pool
+        Thread.current[:ncore_pool] ||= {}
+      end
+
+      def reset_pool
+        pool.each do |addr, cl|
+          cl.reset
+        end
+        pool.clear
+      end
+
+
+      def execute_request(rest_opts)
+        debug_request rest_opts if debug
+
+        tries = 0
+        response = nil
+        begin
+          ActiveSupport::Notifications.instrument(instrument_key, rest_opts) do
+
+            connection = excon_client(rest_opts[:url])
+            begin
+              tries += 1
+              response = connection.request rest_opts.except(:url)
+            rescue Excon::Errors::SocketError, Errno::EADDRNOTAVAIL => e
+              # retry when keepalive was closed
+              if tries <= 1 #&& e.message =~ /end of file reached/
+                retry
+              else
+                raise e
+              end
+            end
+            rest_opts[:status] = response.status rescue nil
+            debug_response response if debug
+          end
+        rescue Errno::ECONNRESET
+          raise parent::ConnectionError, "Connection reset for #{host_for_error rest_opts[:url]} : check network or visit #{status_page}."
+        rescue Errno::ECONNREFUSED
+          raise parent::ConnectionError, "Connection error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+        rescue Excon::Errors::SocketError => e
+          if e.message =~ /Unable to verify certificate/
+            raise parent::ConnectionError, "Unable to verify certificate for #{host_for_error rest_opts[:url]} : verify URL or disable SSL certificate verification (insecure)."
+          elsif e.message =~ /Name or service not known/
+            raise parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+          else
+            raise e
+          end
+        rescue SocketError => e
+          if e.message =~ /nodename nor servname provided/
+            raise parent::ConnectionError, "DNS error for #{host_for_error rest_opts[:url]} : check network and DNS or visit #{status_page}."
+          else
+            raise e
+          end
+        end
+
+        case response.status
+        when 401 # API auth valid; API call itself is an auth-related call and failed
+          raise parent::AuthenticationFailed
+        when 403 # API auth failed or insufficient permissions
+          raise parent::AccessDenied, "Access denied; check your API credentials and permissions."
+        when 404
+          raise parent::RecordNotFound
+        when 422
+          # pass through
+        when 429
+          raise parent::RateLimited
+        when 400..499
+          raise parent::Error, "Client error: #{response.status}\n  #{response.body}"
+        when 500..599
+          raise parent::Error, "Server error: #{response.status}\n  #{response.body}"
+        end
+        response
+      end
+
+      def parse_response(response)
+        if [202, 204].include?(response.status) && response.body.blank?
+          return {data: {}, errors: {}, metadata: {}}
+        end
+      
+        begin
+          json = MultiJson.load(response.body||'', symbolize_keys: false) || {}
+          json = json.with_indifferent_access
+        rescue MultiJson::DecodeError, MultiJson::LoadError
+          raise parent::Error, "Unable to parse API response; HTTP status: #{response.status}; body: #{response.body.inspect}"
+        end
+        errors = json.delete(:errors) || []
+        if errors.any?
+          errors = errors.values.flatten
+          metadata, json = json, {}
+        else
+          if json[:collection]
+            data = json.delete :collection
+            metadata, json = json, data
+            json = [] if json.blank?
+          else
+            metadata = nil
+          end
+        end
+        {data: json, errors: errors, metadata: metadata}
+      end
+
+
+      def auth_headers(creds)
+        creds.inject({}) do |h,(k,v)|
+          if v.present?
+            h["#{auth_header_prefix}-#{k}"] = v 
+          end
+          h
+        end
+      end
+
+      def verify_ssl_cert?
+        return @verify_ssl_cert unless @verify_ssl_cert.nil?
+        bundle_readable = File.readable?(ssl_cert_bundle)
+        if verify_ssl && bundle_readable
+          @verify_ssl_cert = true
+        else
+          m = 'WARNNG: SSL cert verification is disabled.'
+          unless verify_ssl
+            m += " Enable verification with: #{parent}::Api.verify_ssl = true."
+          end
+          unless bundle_readable
+            m += " Unable to read CA bundle #{ssl_cert_bundle}."
+          end
+          $stderr.puts m
+          @verify_ssl_cert = false
+        end
+      end
+
+      def debug_request(rest_opts)
+        return unless logger.debug?
+        logger << <<-DBG
+#{'-=- '*18}
+REQUEST:
+  #{rest_opts[:method].to_s.upcase} #{rest_opts[:url]}
+  #{rest_opts[:headers].map{|h,d| "#{h}: #{d}"}.join("\n  ")}
+  #{rest_opts[:body] || 'nil'}
+DBG
+      end
+
+      def debug_response(response)
+        return unless logger.debug?
+        json = MultiJson.load(response.body||'', symbolize_keys: false) rescue response.body
+        logger << <<-DBG
+RESPONSE:
+  #{response.headers['Status']} | #{response.headers['Content-Type']} | #{response.body.size} bytes
+  #{response.headers.except('Status', 'Connection', 'Content-Type', 'X-Request-Id').map{|h,d| "#{h}: #{d}"}.join("\n  ")}
+  #{json.pretty_inspect.split("\n").join("\n  ")}
+#{'-=- '*18}
+DBG
+      end
+
+    end # ClassMethods
+
+
+    def request(*args)
+      self.class.request(*args)
+    end
+
+  end
+end

data/lib/ncore/collection.rb

@@ -0,0 +1,11 @@
+module NCore
+  class Collection < Array
+
+    attr_accessor :metadata
+
+    def more_results?
+      metadata[:more_results]
+    end
+
+  end
+end

data/lib/ncore/configuration.rb

@@ -0,0 +1,56 @@
+module NCore
+  module Configuration
+    extend ActiveSupport::Concern
+
+    included do
+      init_config_options
+    end
+
+
+    module ClassMethods
+
+      def init_config_options
+        mattr_accessor :default_url
+        self.default_url = 'https://api.example.com/v1/'
+
+        mattr_accessor :default_headers
+        self.default_headers = {
+          accept: 'application/json',
+          content_type: 'application/json',
+          user_agent: "NCore/ruby v#{VERSION}"
+        }
+
+        mattr_accessor :credentials
+
+        mattr_accessor :debug
+        self.debug = false
+
+        mattr_accessor :strict_attributes
+        self.strict_attributes = true
+
+        mattr_accessor :instrument_key
+        self.instrument_key = 'request.ncore'
+
+        mattr_accessor :status_page
+        self.status_page = 'the status page'
+
+        mattr_accessor :auth_header_prefix
+        self.auth_header_prefix = 'X-Api'
+
+        mattr_accessor :credentials_error_message
+        self.credentials_error_message = %Q{Missing API credentials. Set default credentials using "#{self.parent.name}.credentials = {api_user: YOUR_API_USER, api_key: YOUR_API_KEY}"}
+
+        mattr_accessor :verify_ssl
+        self.verify_ssl = true
+
+        mattr_accessor :ssl_cert_bundle
+        self.ssl_cert_bundle = File.dirname(__FILE__)+'/ssl/ca-certificates.crt'
+
+        mattr_accessor :logger
+        self.logger = Logger.new(STDOUT)
+      end
+
+    end
+
+  end
+end

data/lib/ncore/exceptions.rb

@@ -0,0 +1,45 @@
+module NCore
+  module Exceptions
+    extend ActiveSupport::Concern
+
+    included do
+      class_eval <<-INCL, __FILE__, __LINE__+1
+        class Error < StandardError ; end
+
+        class AccessDenied < Error ; end
+        class AuthenticationFailed < Error ; end
+        class ConnectionError < Error ; end
+        class RateLimited < Error ; end
+        class RecordNotFound < Error ; end
+        class UnsavedObjectError < Error ; end
+
+        class RecordInvalid < Error
+          attr_reader :object
+
+          def initialize(object)
+            @object = object
+            cl_name = object.class_name if object.respond_to?(:class_name)
+            cl_name ||= object.class.class_name if object.class.respond_to?(:class_name)
+            cl_name ||= object.name if object.respond_to?(:name)
+            cl_name ||= object.class.name
+            msg = "\#{cl_name} Invalid: \#{@object.errors.to_a.join(' ')}"
+            super msg
+          end
+        end
+
+        class QueryError < Error
+          attr_reader :errors
+
+          def initialize(errors)
+            @errors = errors
+            msg = "Error: \#{errors.to_a.join(' ')}"
+            super msg
+          end
+        end
+
+        class ValidationError < QueryError ; end
+      INCL
+    end
+
+  end
+end