frenetic 0.0.20.alpha.6 → 1.0.0.alpha.1

data/lib/frenetic/concerns/member_rest_methods.rb

@@ -7,9 +7,7 @@ class Frenetic
     module ClassMethods
       def find( params )
         params = { id:params } unless params.is_a? Hash
-
         return as_mock(params) if test_mode?
-
         if response = api.get( member_url(params) ) and response.success?
           new response.body
         end

data/lib/frenetic/concerns/structured.rb

@@ -1,6 +1,5 @@
 class Frenetic
   module Structured
-
     # Stores the unique signature of each Resource Structure
     # Used to determine when a Structure has changed and thus
     # needs to be redefined.
@@ -28,9 +27,7 @@ class Frenetic
 
     def rebuild_structure!
       destroy_structure!
-
       @@signatures[struct_key] = signature
-
       Struct.new( struct_key, *@attrs.keys )
     end
 
@@ -44,9 +41,7 @@ class Frenetic
 
     def destroy_structure!
       return unless structure_defined?
-
       @@signatures.delete struct_key
-
       Struct.send :remove_const, struct_key
     end
   end

data/lib/frenetic/connection.rb

@@ -0,0 +1,110 @@
+require 'delegate'
+
+class Frenetic
+  class Connection < SimpleDelegator
+    attr_reader :builder_config, :connection_config, :errors
+
+    ConnectionConfigKeys = [:url, :params, :headers, :request, :ssl, :proxy]
+
+    def initialize(config = {})
+      @errors = {}
+      process_config(config)
+      validate_configuration!
+
+      connection = Faraday.new(connection_config) do |builder|
+        configure_authentication(builder)
+        configure_responder(builder)
+        configure_cache(builder)
+        configure_adapter(builder)
+      end
+      super(connection)
+    end
+
+    def valid?
+      @errors = {}
+      @errors[:adapter] = 'must be present' if !@config[:adapter]
+      @errors[:url] = 'must be present' if !@config[:url]
+      @errors.empty?
+    end
+
+    def process_config(raw_cfg)
+      @config = {}.merge(raw_cfg.to_hash)
+      @config[:url] = Addressable::URI.parse(raw_cfg[:url])
+      cfgs = @config.inject({builder:{}, conn:{}}) do |conf, (k,v)|
+        if ConnectionConfigKeys.include?(k)
+          conf[:conn][k] = v
+        else
+          conf[:builder][k] = v
+        end
+        conf
+      end
+      [
+        @builder_config = cfgs[:builder],
+        @connection_config = cfgs[:conn]
+      ]
+    end
+
+    def configure_authentication(builder)
+      use_basic_auth(builder) if builder_config[:username]
+      use_token_auth(builder) if builder_config[:api_token]
+    end
+
+    def configure_responder(builder)
+      builder.response(:hal_json)
+    end
+
+    def configure_cache(builder)
+      case builder_config[:cache]
+      when :rack then use_rack_cache(builder)
+      when :rails then use_rails_cache(builder)
+      end
+    end
+
+    def configure_adapter(builder)
+      builder.adapter(builder_config[:adapter])
+    end
+
+  private
+
+    def validate_configuration!
+      raise ConfigError.new(self) if !valid?
+    end
+
+    def use_basic_auth(builder)
+      builder.request :basic_auth, builder_config[:username], builder_config[:password]
+    end
+
+    def use_token_auth(builder)
+      builder.request :token_auth, builder_config[:api_token]
+    end
+
+    def use_rack_cache(builder)
+      require_lib('rack-cache', 'Frenetic Rack::Cache caching strategy')
+      builder.use(
+        FaradayMiddleware::RackCompatible,
+        Rack::Cache::Context,
+        {
+          metastore:     "file:tmp/rack/meta/#{cache_key}",
+          entitystore:   "file:tmp/rack/body/#{cache_key}",
+          ignore_headers: %w{Authorization Set-Cookie X-Content-Digest}
+        }
+      )
+    end
+
+    def use_rails_cache(builder)
+      require_lib 'faraday-http-cache', 'Frenetic Rails caching strategy'
+      builder.use(Faraday::HttpCache, store:Rails.cache, logger:Rails.logger)
+    end
+
+    def cache_key
+      Digest::MD5.hexdigest connection_config[:url].hostname
+    end
+
+    def require_lib(lib = nil, context = nil)
+      lib ? require(lib) : yield
+    rescue NameError, LoadError => err
+      context ||= self
+      raise ConfigError, "Could not load required `#{lib}` dependency for #{context}: #{err.message}"
+    end
+  end
+end

data/lib/frenetic/errors.rb

@@ -0,0 +1,112 @@
+require 'active_support/inflector'
+require 'active_support/core_ext/array/conversions'
+
+class Frenetic
+  # Generic Frenetic exception class.
+  Error = Class.new(StandardError)
+
+  # Raised when there is a configuration error
+  class ConfigError < Error
+    def initialize(model)
+      @model = model
+      super(message)
+    end
+
+    def message
+      if @model.is_a? String
+        @model
+      else
+        errs = @model.errors.collect do |key, msg|
+          "#{key.to_s.titleize} #{msg}"
+        end
+        "Invalid Configuration: #{errs.to_sentence}"
+      end
+    end
+  end
+
+  # Raised when there is a Hypermedia error
+  HypermediaError = Class.new(Error)
+
+  # Raised when there is a Link Template error
+  LinkTemplateError = Class.new(Error)
+
+  # Raised when a Resource does not have a mock class defined.
+  #
+  # For example:
+  #
+  # class Widget < Frenetic::Resource
+  # end
+  #
+  # class MockWidget < Widget
+  #   include Frenetic::ResourceMockery
+  # end
+  #
+  # Would correctly create the necessary Mock Resource
+  class UndefinedResourceMock < Error
+    attr_reader :namespace, :resource
+    def initialize(namespace, resource)
+      @namespace = namespace
+      @resource = resource
+    end
+
+    def message
+      "Mock resource not defined for `#{namespace}`." \
+        " Create a new class that inherits from `#{resource}` and mixin" \
+        " `Frenetic::ResourceMockery` to define a mock."
+    end
+  end
+
+  # Parent class for all specific exceptions which are raised as a result of a
+  # network response.
+  class ResponseError < Error
+    attr_reader :env, :error, :method, :status, :url
+    def initialize(env)
+      env ||= {}
+      body = env.fetch(:body, {})
+      @env = env
+      @error = body['error']
+      @method = env[:method]
+      @status = env[:status]
+      @url = env[:url]
+      super(message)
+    end
+
+    def message
+      @error
+    end
+  end
+
+  # Raised when a network response returns a 400-level error
+  ClientError = Class.new(ResponseError)
+
+  # Raised when a network response returns a 500-level error
+  ServerError = Class.new(ResponseError)
+
+  # Parent class for all specific exceptions which are raised as a result of a
+  # parsing the network request response body.
+  class ParsingError < ResponseError
+    def message
+      "#{status} Error"
+    end
+  end
+
+  # Raised when there is a problem parsing the response body of a 400-level error
+  ClientParsingError = Class.new(ParsingError)
+
+  # Raised when there is a problem parsing the response body of a 400-level error
+  ServerParsingError = Class.new(ParsingError)
+
+  # Raised when there is a problem parsing the response body of an otherwise
+  # successful network request. Provides access to the original exception also.
+  class UnknownParsingError < ParsingError
+    attr_reader :original_exception
+    def initialize(env, err)
+      @original_exception = err
+      super(env)
+    end
+
+    def message
+      @original_exception.message
+    end
+  end
+end

data/lib/frenetic/hypermedia_link.rb

@@ -0,0 +1,74 @@
+require 'addressable/template'
+require 'active_support/core_ext/hash/indifferent_access'
+
+class Frenetic
+  class HypermediaLink
+    def initialize( link )
+      @link = link.with_indifferent_access
+    end
+
+    def href( tmpl_data = {} )
+      if templated?
+        expand tmpl_data
+      else
+        @link['href']
+      end
+    end
+    alias :to_url :href
+
+    def templated?
+      return false unless hash?
+
+      @link['templated'] == true
+    end
+
+    def expandable?( tmpl_data )
+      return false unless templated?
+
+      tmpl_data = normalize_data(tmpl_data)
+
+      (template.variables & tmpl_data.keys.map(&:to_s)).size == template.variables.size
+    end
+
+    def template
+      @template ||= Addressable::Template.new @link['href']
+    end
+
+    def as_json
+      @link
+    end
+
+    def rel
+      @link['rel']
+    end
+
+  private
+
+    def expand( tmpl_data )
+      tmpl_data = normalize_data(tmpl_data)
+
+      return template.expand( tmpl_data ).to_s if expandable? tmpl_data
+
+      raise Frenetic::HypermediaError,
+              "The data provided could not satisfy the template requirements.\n" \
+              "  Template: #{template.pattern}\n" \
+              "  Data: #{tmpl_data}"
+    end
+
+    def hash?
+      @link.is_a? Hash
+    end
+
+    def normalize_data( data )
+      return data if data.is_a? Hash
+
+      infer_template_values data
+    end
+
+    def infer_template_values( data )
+      key = template.variables.first
+
+      { key => data }
+    end
+  end
+end

data/lib/frenetic/hypermedia_link_set.rb

@@ -0,0 +1,43 @@
+require 'delegate'
+require 'active_support/core_ext/object/blank'
+
+require 'frenetic/hypermedia_link'
+
+class Frenetic
+  class HypermediaLinkSet < Delegator
+    def initialize( link_set = [] )
+      link_set = [link_set] unless link_set.is_a? Array
+
+      @link_set = link_set.map do |link|
+        if link.is_a? HypermediaLink
+          link
+        else
+          HypermediaLink.new link
+        end
+      end
+    end
+
+    def href( tmpl_vars = {} )
+      return @link_set.first.href if tmpl_vars.blank?
+
+      link = find_relevant_link( tmpl_vars ) and link.href( tmpl_vars )
+    end
+
+    def []( relation )
+      @link_set.find{ |link| link.rel == relation.to_s }
+    end
+
+    def find_relevant_link( tmpl_vars )
+      @link_set.find{ |link| link.expandable? tmpl_vars } or
+        raise Frenetic::HypermediaError,
+                "Could not find a relevant link for the data provided.\n" \
+                "Are any of the links missing the templated:true property?\n" \
+                "  Template Data: #{tmpl_vars}\n" \
+                "  Link Set: #{@link_set.collect(&:as_json)}"
+    end
+
+    def __getobj__
+      @link_set
+    end
+  end
+end

data/lib/frenetic/middleware/hal_json.rb

@@ -7,23 +7,20 @@ class Frenetic
       def process_response(env)
         super
 
-        if (500...599).include? env[:status]
-          raise ServerError, env[:body]['error']
-        elsif (400...499).include? env[:status]
-          raise ClientError, env[:body]['error']
+        case env[:status]
+        when 500...599 then raise ServerError.new(env)
+        when 400...499 then raise ClientError.new(env)
         end
       rescue Faraday::Error::ParsingError => err
-        if (500...599).include? env[:status]
-          raise ServerError, "#{env[:status]} Error encountered"
-        elsif (400...499).include? env[:status]
-          raise ClientError, "#{env[:status]} Error encountered"
-        else
-          raise ParsingError, err.message
+        case env[:status]
+        when 500...599 then raise ServerParsingError.new(env)
+        when 400...499 then raise ClientParsingError.new(env)
+        else raise UnknownParsingError.new(env, err)
         end
       end
-
     end
   end
 end
 
-Faraday.register_middleware :response, hal_json:lambda { Frenetic::Middleware::HalJson }
+Faraday::Response.register_middleware \
+  hal_json:lambda { Frenetic::Middleware::HalJson }

data/lib/frenetic/resource.rb

@@ -1,4 +1,5 @@
 require 'delegate'
+require 'ostruct'
 require 'active_support/inflector'
 require 'active_support/core_ext/hash/indifferent_access'
 
@@ -37,14 +38,12 @@ class Frenetic
     end
 
     def self.properties
+      return mock_class.default_attributes if test_mode?
       (api.schema[namespace]||{})['properties'] or raise HypermediaError, %Q{Could not find schema definition for the resource "#{namespace}"}
     end
 
     def self.mock_class
-      @mock_class or raise Frenetic::ClientError,
-                            "Mock resource not defined for #{namespace}." \
-                            " Subclass #{self} and mixin Frenetic::ResourceMockery" \
-                            " to define a mock"
+      @mock_class or raise Frenetic::UndefinedResourceMock.new(namespace, self)
     end
 
     def self.as_mock( params = {} )
@@ -53,12 +52,14 @@ class Frenetic
 
     def initialize( p = {} )
       build_params p
-      @attrs  = {}
+      @attrs = {}
 
       properties.keys.each do |k|
         @attrs[k] = @params[k]
       end
 
+      extract_embedded_resources
+
       build_structure
     end
 
@@ -91,7 +92,7 @@ class Frenetic
         "#{k}=#{val}"
       end.join(' ')
 
-      ivars = (instance_variables - [:@structure]).map do |k|
+      ivars = (instance_variables - [:@structure, :@attributes]).map do |k|
         val = instance_variable_get k
         val = val.is_a?(String) ? "\"#{val}\"" : val || 'nil'
 
@@ -110,6 +111,21 @@ class Frenetic
       @params = (p || {}).with_indifferent_access
     end
 
+    def extract_embedded_resources
+      class_namespace = self.class.to_s.deconstantize
+
+      @params.fetch('_embedded',{}).each do |k,v|
+        class_name = "#{class_namespace}::#{k.classify}"
+        klass      = class_name.constantize rescue OpenStruct
+
+        @attrs[k] = if self.class.test_mode? || is_a?(ResourceMockery)
+          klass.as_mock v
+        else
+          klass.new v
+        end
+      end
+    end
+
     def build_structure
       @structure = structure.new( *@attrs.values )
     end