farscape 1.2.0

data/lib/farscape/agent.rb

@@ -0,0 +1,113 @@
+require 'farscape/representor'
+require 'farscape/clients'
+
+module Farscape
+  class Agent
+    
+    include BaseAgent
+    
+    PROTOCOL = :http
+
+    attr_reader :media_type
+    attr_reader :entry_point
+    
+    def initialize(entry = nil, media = :hale, safe = false, plugin_hash = {})
+      @entry_point = entry
+      @media_type = media
+      @safe_mode = safe
+      @plugin_hash = plugin_hash.empty? ? default_plugin_hash : plugin_hash
+      handle_extensions
+    end
+
+    def representor
+      safe? ? SafeRepresentorAgent : RepresentorAgent
+    end
+
+    def enter(entry = entry_point)
+      @entry_point ||= entry
+      raise "No Entry Point Provided!" unless entry
+      response = client.invoke(url: entry, headers: get_accept_header(media_type))
+      find_exception(response)
+    end
+
+    def find_exception(response)
+      error = client.dispatch_error(response)
+      begin
+        representing = representor.new(media_type, response, self)
+      rescue JSON::ParserError
+        representing = response
+      end
+      raise error.new(representing) if error
+      representing
+    end
+
+    # TODO share this information with serialization factory base
+    def get_accept_header(media_type)
+      media_types = { hale: 'application/vnd.hale+json' }
+      { 'Accept' => media_types[media_type] }
+    end
+
+    def client
+      Farscape.clients[PROTOCOL].new(self)
+    end
+
+    def safe
+      self.class.new(@entry_point, @media_type, true, @plugin_hash)
+    end
+
+    def unsafe
+      self.class.new(@entry_point, @media_type, false, @plugin_hash)
+    end
+
+    def safe?
+      @safe_mode
+    end
+
+    def plugins
+      @plugin_hash[:plugins]
+    end
+
+    def enabled_plugins
+      Plugins.enabled_plugins(@plugin_hash[:plugins])
+    end
+
+    def disabled_plugins
+      Plugins.disabled_plugins(@plugin_hash[:plugins])
+    end
+
+    def middleware_stack
+      @plugin_hash[:middleware_stack] ||= Plugins.construct_stack(enabled_plugins)
+    end
+
+    def using(name_or_type)
+      disabling_rules, plugins = Plugins.enable(name_or_type, @plugin_hash[:disabling_rules], @plugin_hash[:plugins])
+      plugin_hash = {
+        disabling_rules: disabling_rules,
+        plugins: plugins,
+        middleware_stack: nil
+      }
+      self.class.new(@entry_point, @media_type, @safe_mode, plugin_hash)
+    end
+
+    def omitting(name_or_type)
+      disabling_rules, plugins = Plugins.disable(name_or_type, @plugin_hash[:disabling_rules], @plugin_hash[:plugins])
+      plugin_hash = {
+        disabling_rules: disabling_rules,
+        plugins: plugins,
+        middleware_stack: nil
+      }
+      self.class.new(@entry_point, @media_type, @safe_mode, plugin_hash)
+    end
+
+    private
+    
+    def default_plugin_hash
+      {
+        plugins: Farscape.plugins.dup,  # A hash of plugins keyed by the plugin name
+        disabling_rules: Farscape.disabling_rules.dup, # A list of symbols that are Names or types of plugins
+        middleware_stack: nil
+      }
+    end
+
+  end
+end

data/lib/farscape/base_agent.rb

@@ -0,0 +1,15 @@
+module Farscape
+  module BaseAgent
+    
+    def handle_extensions
+      extensions = Plugins.extensions(enabled_plugins)
+      extensions = extensions[self.class.to_s.split(':')[-1].to_sym]
+      extensions.each { |cls| self.extend(cls) } if extensions
+    end
+
+    %w(disabled_plugins enabled_plugins plugins).each do |meth|
+      define_method(meth) { @agent.send(meth) }
+    end
+    
+  end
+end

data/lib/farscape/cache.rb

@@ -0,0 +1,13 @@
+require 'active_support/cache'
+
+module Farscape
+
+  def self.cache
+    @cache ||= ActiveSupport::Cache::MemoryStore.new
+  end
+
+  def self.cache=(new_cache)
+    @cache = new_cache
+  end
+
+end

data/lib/farscape/client/base_client.rb

@@ -0,0 +1,27 @@
+module Farscape
+  class Agent
+    # Client independent of protocol, only used for HTTP for now
+    class BaseClient
+
+      def interface_methods
+        {
+          safe: [],
+          unsafe: [],
+          idempotent: []
+        }
+      end
+
+      def safe_method?(meth)
+        interface_methods[:safe].include?(meth)
+      end
+
+      def unsafe_method?(meth)
+        interface_methods[:unsafe].include?(meth)
+      end
+
+      def idempotent_method?(meth)
+        interface_methods[:idempotent].include?(meth)
+      end
+    end
+  end
+end

data/lib/farscape/client/http_client.rb

@@ -0,0 +1,99 @@
+require 'faraday'
+require 'farscape/client/base_client'
+require 'farscape/plugins'
+require 'farscape/errors'
+
+module Farscape
+  class Agent
+    class HTTPClient < BaseClient
+
+      # The Faraday connection instance.
+      attr_reader :connection
+      attr_reader :Plugins
+
+      def initialize(agent)
+        @connection = Faraday.new do |builder|
+          builder.request :url_encoded
+          agent.middleware_stack.each do |middleware|
+            if middleware.key?(:config)
+              config = middleware[:config]
+              if config.is_a?(Array)
+                builder.use(middleware[:class], *config)
+              else
+                builder.use(middleware[:class], config)
+              end
+            else
+              builder.use(middleware[:class])
+            end
+          end
+
+          builder.adapter faraday_adapter
+        end
+      end
+
+      # Override this in a subclass to create clients with custom Faraday adapters
+      def faraday_adapter
+        Faraday.default_adapter
+      end
+
+      ##
+      # Makes a Faraday request given the specified options
+      #
+      # @options [Hash] The hash of Faraday options passed to the request, including url, method,
+      #  params, body, and headers.
+      # @return [Faraday::Response] The response object resulting from the Faraday call
+      def invoke(options = {})
+        defaults = { method:  'get'}
+        options = defaults.merge(options)
+
+        connection.send(options[:method].to_s.downcase) do |req|
+          req.url options[:url]
+          req.body = options[:body] if options.has_key?(:body)
+          options[:params].each { |k,v| req.params[k] = v } if options.has_key?(:params)
+          options[:headers].each { |k,v| req.headers[k] = v } if options.has_key?(:headers)
+        end
+      end
+
+      def interface_methods
+        {
+          idempotent: ['PUT', 'DELETE'],
+          unsafe: ['POST', 'PATCH'], # http://tools.ietf.org/html/rfc5789
+          safe: ['GET', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
+        }
+      end
+
+      def dispatch_error(response)
+        errors = Farscape::Exceptions
+        http_code = {
+          400 => errors::BadRequest,
+          401 => errors::Unauthorized,
+          403 => errors::Forbidden,
+          404 => errors::NotFound,
+          405 => errors::MethodNotAllowed,
+          406 => errors::NotAcceptable,
+          407 => errors::ProxyAuthenticationRequired,
+          408 => errors::RequestTimeout,
+          409 => errors::Conflict,
+          410 => errors::Gone,
+          411 => errors::LengthRequired,
+          412 => errors::PreconditionFailed,
+          413 => errors::RequestEntityTooLarge,
+          414 => errors::RequestUriTooLong,
+          415 => errors::UnsupportedMediaType,
+          416 => errors::RequestedRangeNotSatisfiable,
+          417 => errors::ExpectationFailed,
+          418 => errors::ImaTeapot,
+          422 => errors::UnprocessableEntity,
+          500 => errors::InternalServerError,
+          501 => errors::NotImplemented,
+          502 => errors::BadGateway,
+          503 => errors::ServiceUnavailable,
+          504 => errors::GatewayTimeout,
+          505 => errors::ProtocolVersionNotSupported,
+        }
+        http_code[response.status] || errors::ProtocolException unless response.success?
+      end
+
+    end
+  end
+end

data/lib/farscape/clients.rb

@@ -0,0 +1,9 @@
+require 'farscape/client/http_client'
+
+module Farscape
+
+  def self.clients
+    @clients ||= {http: Farscape::Agent::HTTPClient}
+  end
+
+end

data/lib/farscape/errors.rb

@@ -0,0 +1,172 @@
+require 'active_support/core_ext/string/filters'
+
+module Farscape
+  module Exceptions
+    class ProtocolException < IOError
+      attr_reader :representor
+
+      def initialize(representor)
+        @representor = representor
+      end
+
+      def message
+        @representor.representor.to_hash
+      end
+
+      def error_description
+        'Unknown Error'
+      end
+    end
+    
+    #4xx
+    class BadRequest < ProtocolException
+      def error_description
+        'The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.'
+      end
+    end
+    class Unauthorized < ProtocolException
+      def error_description
+        'The request requires user authentication.
+        The client MAY repeat the request with suitable Authorization.
+        If the request already included Authorization credentials,
+        then the response indicates that authorization has been refused for those credentials.'.squish
+      end
+    end
+    class Forbidden < ProtocolException
+      def error_description
+        'The server understood the request, but is refusing to fulfill it.
+        Authorization will not help and the request SHOULD NOT be repeated.'.squish
+      end
+    end
+    class NotFound < ProtocolException
+      def error_description
+        'The server has not found anything matching the Request-URI.
+        No indication is given of whether the condition is temporary or permanent.
+        This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.'.squish
+      end
+    end
+    class MethodNotAllowed < ProtocolException
+      def error_description
+        'The protocol method specified in the Request-Line is not allowed for the resource identified by the Request-URI.'
+      end
+    end
+    class NotAcceptable < ProtocolException
+      def error_description
+        'The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.'
+      end
+    end
+    class ProxyAuthenticationRequired < ProtocolException
+      def error_description
+        'The client must first authenticate itself with the proxy.
+        The client MAY repeat the request with suitable Proxy Authorization.'.squish
+      end
+    end
+    class RequestTimeout < ProtocolException
+      def error_description
+        'The client did not produce a request within the time that the server was prepared to wait.
+        The client MAY repeat the request without modifications at any later time.'.squish
+      end
+    end
+    class Conflict < ProtocolException
+      def error_description
+        'The request could not be completed due to a conflict with the current state of the resource.
+        This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
+        Conflicts are most likely to occur in response to an idempotent request.
+        For example, if versioning were being used and the entity included changes to a resource which conflict with those made by an earlier (third-party) request'.squish
+      end
+    end
+    class Gone < ProtocolException
+      def error_description
+        'The requested resource is no longer available at the server and no forwarding address is known.
+        This condition is expected to be considered permanent.
+        Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval.
+        This response is cacheable unless indicated otherwise.'.squish
+      end
+    end
+    class LengthRequired < ProtocolException
+      def error_description
+        'The server refuses to accept the request without a defined content length.'
+      end
+    end
+    class PreconditionFailed < ProtocolException
+      def error_description
+        'The precondition given by the client evaluated to false when it was tested on the server.'
+      end
+    end
+    class RequestEntityTooLarge < ProtocolException
+      def error_description
+        'The server is refusing to process a request because the request entity is larger than the server is willing or able to process.'.squish
+      end
+    end
+    class RequestUriTooLong < ProtocolException
+      def error_description
+        'The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.'
+        end
+    end
+    class UnsupportedMediaType < ProtocolException
+      def error_description
+        'The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.'
+      end
+    end
+    class RequestedRangeNotSatisfiable < ProtocolException
+      def error_description
+        'A request requested a resource within a range,
+        and none of the range-specifier values in this field overlap the current extent of the selected resource,
+        and the request did not specify range conditions.'.squish
+      end
+    end
+    class ExpectationFailed < ProtocolException
+      def error_description
+        'The expectation given by the client could not be met by this server.
+        If the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server.'.squish
+      end
+    end
+    class ImaTeapot < ProtocolException
+      def error_description
+        'The server is a teapot; the resulting entity body may be short and stout.
+        Demonstrations of this behaviour exist.'.squish
+      end
+    end
+
+    class UnprocessableEntity < ProtocolException
+      def error_description
+        'The request was well-formed but was unable to be followed due to semantic errors.'.squish
+      end
+    end
+
+    #5xx
+    class InternalServerError < ProtocolException
+      def error_description
+        'The server encountered an unexpected condition which prevented it from fulfilling the request.'
+      end
+    end
+    class NotImplemented < ProtocolException
+      def error_description
+        'The server does not support the functionality required to fulfill the request.'
+      end
+    end
+    class BadGateway < ProtocolException
+      def error_description
+        'The server received an invalid response from the upstream server it accessed in attempting to fulfill the request.'
+      end
+    end
+    class ServiceUnavailable < ProtocolException
+      def error_description
+        'The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
+        The implication is that this is a temporary condition which will be alleviated after some delay.'.squish
+      end
+    end
+    class GatewayTimeout < ProtocolException
+      def error_description
+        'The server did not receive a timely response from an upstream server specified it needed to access in attempting to complete the request.'
+      end
+    end
+    class ProtocolVersionNotSupported < ProtocolException
+      def error_description
+        'The server does not support, or refuses to support, the protocol or protocol version that was used in the request message.
+        The server is indicating that it is unable or unwilling to complete the request using the same protocol as the client'.squish
+      end
+    end
+
+  end
+end

data/lib/farscape/helpers/partially_ordered_list.rb

@@ -0,0 +1,75 @@
+# Convenience class that finds an order for a set of elements that satisfies an arbitrary sorting function that
+# can be undefined for some pairs.
+# TODO: Optimize and gemify (or find existing gem that does this)
+
+class PartiallyOrderedList
+  include Enumerable
+
+  class Element < Struct.new(:item, :preceders)
+    def inspect
+      if preceders.any?
+        "#{item} > {#{preceders.map(&:item).join(', ')}}"
+      else
+        item
+      end
+    end
+    def ==(other)
+      item == other.item
+    end
+  end
+
+  CircularOrderingError = Class.new(StandardError)
+
+  attr_accessor :elements, :ordering
+
+  def initialize(&block)
+    raise ArgumentError, "#{self.class}.new requires a block" unless block_given?
+    @elements = []
+    @ordering = block
+  end
+
+  def add(item)
+    @cached_ary = nil
+    new_el = Element.new(item, [])
+    elements.each do |old_el|
+      case ordering.call(old_el.item, new_el.item)
+      when -1
+        new_el.preceders << old_el
+      when 1
+        old_el.preceders << new_el
+      end
+    end
+    elements << new_el
+  end
+
+  def delete(item)
+    if element = elements.find { |elt| elt.item == item }
+      elements.delete(element)
+      @cached_ary.delete(element) if @cached_ary
+      elements.each { |elt| elt.preceders.delete(element) }
+      item
+    end
+  end
+
+  def each(&block)
+    return to_enum unless block_given?
+    if @cached_ary && @cached_ary.size == elements.size
+      @cached_ary.each{ |elt| yield elt.item }
+    else
+      @cached_ary = []
+      unadded = elements.map{ |elt| elt=elt.dup; elt.preceders = elt.preceders.dup; elt }
+      while unadded.any?
+        i = unadded.find_index { |candidate| candidate.preceders.none? }
+        if i
+          to_add = unadded.delete_at(i)
+          yield(to_add.item)
+          unadded.each { |elt| elt.preceders.delete(to_add) }
+          @cached_ary << to_add
+        else
+          raise CircularOrderingError.new("Could not resolve ordering for #{unadded.map(&:item)}")
+        end
+      end
+    end
+  end
+
+end

data/lib/farscape/logger.rb

@@ -0,0 +1,13 @@
+require 'logger'
+
+module Farscape
+
+  def self.logger
+    @logger ||= Logger.new(STDOUT)
+  end
+
+  def self.logger=(new_logger)
+    @logger = new_logger
+  end
+
+end

data/lib/farscape/plugins.rb

@@ -0,0 +1,71 @@
+require_relative 'helpers/partially_ordered_list'
+
+module Farscape
+  
+    extend Plugins
+
+    attr_reader :plugins
+    attr_reader :disabling_rules
+
+    @plugins = {} # A hash of plugins keyed by the plugin name
+    @disabling_rules = [] # A list of symbols that are Names or types of plugins
+    @middleware_stack = nil
+    
+    def self.plugins
+      @plugins
+    end
+
+    def self.disabling_rules
+      @disabling_rules
+    end
+      
+    def self.register_plugin(options)
+      @middleware_stack = nil
+      options[:enabled] = self.enabled?(options)
+      @plugins[options[:name]] = options
+    end
+
+    def self.register_plugins(a_list)
+      a_list.each { |options| register_plugin(options) }
+    end
+
+    # Returns the Poset representing middleware dependency
+    def self.middleware_stack
+      @middleware_stack ||= Plugins.construct_stack(enabled_plugins)
+    end
+
+    def self.enabled_plugins
+      Plugins.enabled_plugins(@plugins)
+    end
+
+    def self.disabled_plugins
+      Plugins.disabled_plugins(@plugins)
+    end
+    
+    def self.disabled?(options)
+      Plugins.disabled?(@plugins, @disabling_rules, options)
+    end
+    
+    def self.enabled?(options)
+      Plugins.enabled?(@plugins, @disabling_rules, options)
+    end
+
+    # Prevents a plugin from being registered, and disables it if it's already there
+    def self.disable!(name_or_type)
+      @middleware_stack = nil
+      @disabling_rules, @plugins = Plugins.disable(name_or_type, @disabling_rules, @plugins)
+    end
+
+    # Allows a plugin to be registered, and enables it if it's already there
+    def self.enable!(name_or_type)
+      @middleware_stack = nil
+      @disabling_rules, @plugins = Plugins.enable(name_or_type, @disabling_rules, @plugins)
+    end
+    
+    # Removes all plugins and disablings of plugins
+    def self.clear
+      @plugins = {}
+      @disabling_rules = []
+      @middleware_stack = nil
+    end
+end