fragrant 0.0.1

data/vendor/grape/lib/grape/entity.rb

@@ -0,0 +1,378 @@
+require 'hashie'
+
+module Grape
+  # An Entity is a lightweight structure that allows you to easily
+  # represent data from your application in a consistent and abstracted
+  # way in your API. Entities can also provide documentation for the
+  # fields exposed.
+  #
+  # @example Entity Definition
+  #
+  #   module API
+  #     module Entities
+  #       class User < Grape::Entity
+  #         expose :first_name, :last_name, :screen_name, :location
+  #         expose :field, :documentation => {:type => "string", :desc => "describe the field"}
+  #         expose :latest_status, :using => API::Status, :as => :status, :unless => {:collection => true}
+  #         expose :email, :if => {:type => :full}
+  #         expose :new_attribute, :if => {:version => 'v2'}
+  #         expose(:name){|model,options| [model.first_name, model.last_name].join(' ')}
+  #       end
+  #     end
+  #   end
+  #
+  # Entities are not independent structures, rather, they create
+  # **representations** of other Ruby objects using a number of methods
+  # that are convenient for use in an API. Once you've defined an Entity,
+  # you can use it in your API like this:
+  #
+  # @example Usage in the API Layer
+  #
+  #   module API
+  #     class Users < Grape::API
+  #       version 'v2'
+  #
+  #       desc 'User index', { :object_fields => API::Entities::User.documentation }
+  #       get '/users' do
+  #         @users = User.all
+  #         type = current_user.admin? ? :full : :default
+  #         present @users, :with => API::Entities::User, :type => type
+  #       end
+  #     end
+  #   end
+  class Entity
+    attr_reader :object, :options
+
+    # The Entity DSL allows you to mix entity functionality into
+    # your existing classes.
+    module DSL
+      def self.included(base)
+        base.extend ClassMethods
+        ancestor_entity_class = base.ancestors.detect{|a| a.entity_class if a.respond_to?(:entity_class)}
+        base.const_set(:Entity, Class.new(ancestor_entity_class || Grape::Entity)) unless const_defined?(:Entity)
+      end
+
+      module ClassMethods
+        # Returns the automatically-created entity class for this
+        # Class.
+        def entity_class(search_ancestors=true)
+          klass = const_get(:Entity) if const_defined?(:Entity)
+          klass ||= ancestors.detect{|a| a.entity_class(false) if a.respond_to?(:entity_class) } if search_ancestors
+          klass
+        end
+
+        # Call this to make exposures to the entity for this Class.
+        # Can be called with symbols for the attributes to expose,
+        # a block that yields the full Entity DSL (See Grape::Entity),
+        # or both.
+        #
+        # @example Symbols only.
+        #
+        #   class User
+        #     include Grape::Entity::DSL
+        #     
+        #     entity :name, :email
+        #   end
+        #
+        # @example Mixed.
+        #
+        #   class User
+        #     include Grape::Entity::DSL
+        #     
+        #     entity :name, :email do
+        #       expose :latest_status, using: Status::Entity, if: :include_status
+        #       expose :new_attribute, :if => {:version => 'v2'}
+        #     end
+        #   end
+        def entity(*exposures, &block)
+          entity_class.expose *exposures if exposures.any?
+          entity_class.class_eval(&block) if block_given?
+          entity_class
+        end
+      end
+
+      # Instantiates an entity version of this object.
+      def entity
+        self.class.entity_class.new(self)
+      end
+    end
+
+    # This method is the primary means by which you will declare what attributes
+    # should be exposed by the entity.
+    #
+    # @option options :as Declare an alias for the representation of this attribute.
+    # @option options :if When passed a Hash, the attribute will only be exposed if the
+    #   runtime options match all the conditions passed in. When passed a lambda, the
+    #   lambda will execute with two arguments: the object being represented and the
+    #   options passed into the representation call. Return true if you want the attribute
+    #   to be exposed.
+    # @option options :unless When passed a Hash, the attribute will be exposed if the
+    #   runtime options fail to match any of the conditions passed in. If passed a lambda,
+    #   it will yield the object being represented and the options passed to the
+    #   representation call. Return true to prevent exposure, false to allow it.
+    # @option options :using This option allows you to map an attribute to another Grape
+    #   Entity. Pass it a Grape::Entity class and the attribute in question will
+    #   automatically be transformed into a representation that will receive the same
+    #   options as the parent entity when called. Note that arrays are fine here and
+    #   will automatically be detected and handled appropriately.
+    # @option options :proc If you pass a Proc into this option, it will
+    #   be used directly to determine the value for that attribute. It
+    #   will be called with the represented object as well as the
+    #   runtime options that were passed in. You can also just supply a
+    #   block to the expose call to achieve the same effect.
+    # @option options :documentation Define documenation for an exposed
+    #   field, typically the value is a hash with two fields, type and desc.
+    def self.expose(*args, &block)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      if args.size > 1
+        raise ArgumentError, "You may not use the :as option on multi-attribute exposures." if options[:as]
+        raise ArgumentError, "You may not use block-setting on multi-attribute exposures." if block_given?
+      end
+
+      raise ArgumentError, "You may not use block-setting when also using format_with" if block_given? && options[:format_with].respond_to?(:call)
+
+      options[:proc] = block if block_given?
+
+      args.each do |attribute|
+        exposures[attribute.to_sym] = options
+      end
+    end
+
+    # Returns a hash of exposures that have been declared for this Entity or ancestors. The keys
+    # are symbolized references to methods on the containing object, the values are
+    # the options that were passed into expose.
+    def self.exposures
+      @exposures ||= {}
+
+      if superclass.respond_to? :exposures
+        @exposures = superclass.exposures.merge(@exposures)
+      end
+
+      @exposures
+    end
+
+    # Returns a hash, the keys are symbolized references to fields in the entity,
+    # the values are document keys in the entity's documentation key. When calling
+    # #docmentation, any exposure without a documentation key will be ignored.
+    def self.documentation
+      @documentation ||= exposures.inject({}) do |memo, value|
+                           unless value[1][:documentation].nil? || value[1][:documentation].empty?
+                             memo[value[0]] = value[1][:documentation]
+                           end
+                           memo
+                         end
+
+      if superclass.respond_to? :documentation
+        @documentation = superclass.documentation.merge(@documentation)
+      end
+
+      @documentation
+    end
+
+    # This allows you to declare a Proc in which exposures can be formatted with.
+    # It take a block with an arity of 1 which is passed as the value of the exposed attribute.
+    #
+    # @param name [Symbol] the name of the formatter
+    # @param block [Proc] the block that will interpret the exposed attribute
+    #
+    #
+    #
+    # @example Formatter declaration
+    #
+    #   module API
+    #     module Entities
+    #       class User < Grape::Entity
+    #         format_with :timestamp do |date|
+    #           date.strftime('%m/%d/%Y')
+    #         end
+    #
+    #         expose :birthday, :last_signed_in, :format_with => :timestamp
+    #       end
+    #     end
+    #   end
+    #
+    # @example Formatters are available to all decendants
+    #
+    #   Grape::Entity.format_with :timestamp do |date|
+    #     date.strftime('%m/%d/%Y')
+    #   end
+    #
+    def self.format_with(name, &block)
+      raise ArgumentError, "You must pass a block for formatters" unless block_given?
+      formatters[name.to_sym] = block
+    end
+
+    # Returns a hash of all formatters that are registered for this and it's ancestors.
+    def self.formatters
+      @formatters ||= {}
+
+      if superclass.respond_to? :formatters
+        @formatters = superclass.formatters.merge(@formatters)
+      end
+
+      @formatters
+    end
+
+    # This allows you to set a root element name for your representation.
+    #
+    # @param plural   [String] the root key to use when representing
+    #   a collection of objects. If missing or nil, no root key will be used
+    #   when representing collections of objects.
+    # @param singular [String] the root key to use when representing
+    #   a single object. If missing or nil, no root key will be used when
+    #   representing an individual object.
+    #
+    # @example Entity Definition
+    #
+    #   module API
+    #     module Entities
+    #       class User < Grape::Entity
+    #         root 'users', 'user'
+    #         expose :id
+    #       end
+    #     end
+    #   end
+    #
+    # @example Usage in the API Layer
+    #
+    #   module API
+    #     class Users < Grape::API
+    #       version 'v2'
+    #
+    #       # this will render { "users": [ {"id":"1"}, {"id":"2"} ] }
+    #       get '/users' do
+    #         @users = User.all
+    #         present @users, :with => API::Entities::User
+    #       end
+    #
+    #       # this will render { "user": {"id":"1"} }
+    #       get '/users/:id' do
+    #         @user = User.find(params[:id])
+    #         present @user, :with => API::Entities::User
+    #       end
+    #     end
+    #   end
+    def self.root(plural, singular=nil)
+      @collection_root = plural
+      @root = singular
+    end
+
+    # This convenience method allows you to instantiate one or more entities by
+    # passing either a singular or collection of objects. Each object will be
+    # initialized with the same options. If an array of objects is passed in,
+    # an array of entities will be returned. If a single object is passed in,
+    # a single entity will be returned.
+    #
+    # @param objects [Object or Array] One or more objects to be represented.
+    # @param options [Hash] Options that will be passed through to each entity
+    #   representation.
+    #
+    # @option options :root [String] override the default root name set for the
+    #   entity. Pass nil or false to represent the object or objects with no
+    #   root name even if one is defined for the entity.
+    def self.represent(objects, options = {})
+      inner = if objects.respond_to?(:to_ary)
+        objects.to_ary().map{|o| self.new(o, {:collection => true}.merge(options))}
+      else
+        self.new(objects, options)
+      end
+
+      root_element = if options.has_key?(:root)
+        options[:root]
+      else
+        objects.respond_to?(:to_ary) ? @collection_root : @root
+      end
+      root_element ? { root_element => inner } : inner
+    end
+
+    def initialize(object, options = {})
+      @object, @options = object, options
+    end
+
+    def exposures
+      self.class.exposures
+    end
+
+    def documentation
+      self.class.documentation
+    end
+
+    def formatters
+      self.class.formatters
+    end
+
+    # The serializable hash is the Entity's primary output. It is the transformed
+    # hash for the given data model and is used as the basis for serialization to
+    # JSON and other formats.
+    #
+    # @param options [Hash] Any options you pass in here will be known to the entity
+    #   representation, this is where you can trigger things from conditional options
+    #   etc.
+    def serializable_hash(runtime_options = {})
+      return nil if object.nil?
+      opts = options.merge(runtime_options || {})
+      exposures.inject({}) do |output, (attribute, exposure_options)|
+        if (exposure_options.has_key?(:proc) || object.respond_to?(attribute)) && conditions_met?(exposure_options, opts)
+          partial_output = value_for(attribute, opts)
+          output[key_for(attribute)] =
+            if partial_output.respond_to? :serializable_hash
+              partial_output.serializable_hash(runtime_options)
+            elsif partial_output.kind_of?(Array) && !partial_output.map {|o| o.respond_to? :serializable_hash}.include?(false)
+              partial_output.map {|o| o.serializable_hash}
+            else
+              partial_output
+            end
+        end
+        output
+      end
+    end
+
+    alias :as_json :serializable_hash
+
+    protected
+
+    def key_for(attribute)
+      exposures[attribute.to_sym][:as] || attribute.to_sym
+    end
+
+    def value_for(attribute, options = {})
+      exposure_options = exposures[attribute.to_sym]
+
+      if exposure_options[:proc]
+        exposure_options[:proc].call(object, options)
+      elsif exposure_options[:using]
+        exposure_options[:using].represent(object.send(attribute), :root => nil)
+      elsif exposure_options[:format_with]
+        format_with = exposure_options[:format_with]
+
+        if format_with.is_a?(Symbol) && formatters[format_with]
+          formatters[format_with].call(object.send(attribute))
+        elsif format_with.is_a?(Symbol)
+          self.send(format_with, object.send(attribute))
+        elsif format_with.respond_to? :call
+          format_with.call(object.send(attribute))
+        end
+      else
+        object.send(attribute)
+      end
+    end
+
+    def conditions_met?(exposure_options, options)
+      if_condition = exposure_options[:if]
+      unless_condition = exposure_options[:unless]
+
+      case if_condition
+        when Hash; if_condition.each_pair{|k,v| return false if options[k.to_sym] != v }
+        when Proc; return false unless if_condition.call(object, options)
+      end
+
+      case unless_condition
+        when Hash; unless_condition.each_pair{|k,v| return false if options[k.to_sym] == v}
+        when Proc; return false if unless_condition.call(object, options)
+      end
+
+      true
+    end
+  end
+end

data/vendor/grape/lib/grape/exceptions/base.rb

@@ -0,0 +1,17 @@
+module Grape
+  module Exceptions
+    class Base < StandardError
+      attr_reader :status, :message, :headers
+
+      def initialize(args = {})
+        @status = args[:status] || nil
+        @message = args[:message] || nil
+        @headers = args[:headers] || nil
+      end
+
+      def [](index)
+        self.send(index)
+      end 
+    end
+  end
+end

data/vendor/grape/lib/grape/exceptions/validation_error.rb

@@ -0,0 +1,10 @@
+require 'grape/exceptions/base'
+
+class ValidationError < Grape::Exceptions::Base
+  attr_accessor :param
+
+  def initialize(args = {})
+    @param = args[:param].to_s if args.has_key? :param
+    super
+  end
+end

data/vendor/grape/lib/grape/middleware/auth/basic.rb

@@ -0,0 +1,30 @@
+require 'rack/auth/basic'
+
+module Grape
+  module Middleware
+    module Auth
+      class Basic < Grape::Middleware::Base
+        attr_reader :authenticator
+        
+        def initialize(app, options = {}, &authenticator)
+          super(app, options)
+          @authenticator = authenticator
+        end
+        
+        def basic_request
+          Rack::Auth::Basic::Request.new(env)
+        end
+        
+        def credentials
+          basic_request.provided?? basic_request.credentials : [nil, nil]
+        end
+        
+        def before
+          unless authenticator.call(*credentials)
+            throw :error, :status => 401, :message => "API Authorization Failed."
+          end
+        end
+      end
+    end
+  end
+end

data/vendor/grape/lib/grape/middleware/auth/digest.rb

@@ -0,0 +1,30 @@
+require 'rack/auth/digest/md5'
+
+module Grape
+  module Middleware
+    module Auth
+      class Digest < Grape::Middleware::Base
+        attr_reader :authenticator
+        
+        def initialize(app, options = {}, &authenticator)
+          super(app, options)
+          @authenticator = authenticator
+        end
+        
+        def digest_request
+          Rack::Auth::Digest::Request.new(env)
+        end
+        
+        def credentials
+          digest_request.provided?? digest_request.credentials : [nil, nil]
+        end
+        
+        def before
+          unless authenticator.call(*credentials)
+            throw :error, :status => 401, :message => "API Authorization Failed."
+          end
+        end
+      end
+    end
+  end
+end

data/vendor/grape/lib/grape/middleware/auth/oauth2.rb

@@ -0,0 +1,72 @@
+module Grape::Middleware::Auth
+  # OAuth 2.0 authorization for Grape APIs.
+  class OAuth2 < Grape::Middleware::Base
+    def default_options
+      {
+        :token_class => 'AccessToken',
+        :realm => 'OAuth API',
+        :parameter => %w(bearer_token oauth_token),
+        :accepted_headers => %w(HTTP_AUTHORIZATION X_HTTP_AUTHORIZATION X-HTTP_AUTHORIZATION REDIRECT_X_HTTP_AUTHORIZATION),
+        :header => [/Bearer (.*)/i, /OAuth (.*)/i]
+      }
+    end
+    
+    def before
+      verify_token(token_parameter || token_header)
+    end
+
+    def token_parameter
+      Array(options[:parameter]).each do |p|
+        return request[p] if request[p]
+      end
+      nil
+    end
+
+    def token_header
+      return false unless authorization_header
+      Array(options[:header]).each do |regexp|
+        if authorization_header =~ regexp
+          return $1
+        end
+      end
+      nil
+    end
+
+    def authorization_header
+      options[:accepted_headers].each do |head|
+        return env[head] if env[head]
+      end
+      nil
+    end
+    
+    def token_class
+      @klass ||= eval(options[:token_class])
+    end
+    
+    def verify_token(token)
+      if token = token_class.verify(token)
+        if token.respond_to?(:expired?) && token.expired?
+          error_out(401, 'expired_token')
+        else
+          if !token.respond_to?(:permission_for?) || token.permission_for?(env)
+            env['api.token'] = token
+          else
+            error_out(403, 'insufficient_scope')
+          end
+        end
+      else
+        error_out(401, 'invalid_token')
+      end
+    end
+    
+    def error_out(status, error)
+      throw :error,
+        :message => error,
+        :status => status,
+        :headers => {
+          'WWW-Authenticate' => "OAuth realm='#{options[:realm]}', error='#{error}'"
+        }
+    end
+  end
+end
+    

data/vendor/grape/lib/grape/middleware/base.rb

@@ -0,0 +1,154 @@
+require 'multi_json'
+require 'multi_xml'
+
+module Grape
+  module Middleware
+    class Base
+      attr_reader :app, :env, :options
+
+      # @param [Rack Application] app The standard argument for a Rack middleware.
+      # @param [Hash] options A hash of options, simply stored for use by subclasses.
+      def initialize(app, options = {})
+        @app = app
+        @options = default_options.merge(options)
+      end
+
+      def default_options; {} end
+
+      def call(env)
+        dup.call!(env)
+      end
+
+      def call!(env)
+        @env = env
+        before
+        @app_response = @app.call(@env)
+        after || @app_response
+      end
+
+      # @abstract
+      # Called before the application is called in the middleware lifecycle.
+      def before; end
+      # @abstract
+      # Called after the application is called in the middleware lifecycle.
+      # @return [Response, nil] a Rack SPEC response or nil to call the application afterwards.
+      def after; end
+
+      def request
+        Rack::Request.new(self.env)
+      end
+
+      def response
+        Rack::Response.new(@app_response)
+      end
+
+
+      module Formats
+
+        CONTENT_TYPES = {
+          :xml => 'application/xml',
+          :json => 'application/json',
+          :atom => 'application/atom+xml',
+          :rss => 'application/rss+xml',
+          :txt => 'text/plain'
+        }
+        FORMATTERS = {
+          :json => :encode_json,
+          :txt => :encode_txt,
+          :xml => :encode_xml
+        }
+        PARSERS = {
+          :json => :decode_json,
+          :xml => :decode_xml
+        }
+
+        def formatters
+          FORMATTERS.merge(options[:formatters] || {})
+        end
+
+        def parsers
+          PARSERS.merge(options[:parsers] || {})
+        end
+
+        def content_types
+          CONTENT_TYPES.merge(options[:content_types] || {})
+        end
+
+        def content_type
+          content_types[options[:format]] || 'text/html'
+        end
+
+        def mime_types
+          content_types.invert
+        end
+
+        def formatter_for(api_format)
+          spec = formatters[api_format]
+          case spec
+          when nil
+            lambda { |obj| obj }
+          when Symbol
+            method(spec)
+          else
+            spec
+          end
+        end
+
+        def parser_for(api_format)
+          spec = parsers[api_format]
+          case spec
+          when nil
+            nil
+          when Symbol
+            method(spec)
+          else
+            spec
+          end
+        end
+
+        def decode_json(object)
+          MultiJson.load(object)
+        end
+
+        def serializable?(object)
+         object.respond_to?(:serializable_hash) ||
+           object.kind_of?(Array) && !object.map {|o| o.respond_to? :serializable_hash }.include?(false) ||
+           object.kind_of?(Hash)
+        end
+
+        def serialize(object)
+          if object.respond_to? :serializable_hash
+            object.serializable_hash
+          elsif object.kind_of?(Array) && !object.map {|o| o.respond_to? :serializable_hash }.include?(false)
+            object.map {|o| o.serializable_hash }
+          elsif object.kind_of?(Hash)
+            object.inject({}) { |h,(k,v)| h[k] = serialize(v); h }
+          else
+            object
+          end
+        end
+
+        def encode_json(object)
+          return object if object.is_a?(String)
+          return MultiJson.dump(serialize(object)) if serializable?(object)
+          return object.to_json if object.respond_to?(:to_json)
+
+          MultiJson.dump(object)
+        end
+
+        def encode_txt(object)
+          object.respond_to?(:to_txt) ? object.to_txt : object.to_s
+        end
+
+        def decode_xml(object)
+          MultiXml.parse(object)
+        end
+
+        def encode_xml(object)
+          object.respond_to?(:to_xml) ? object.to_xml : object.to_s
+        end
+      end
+
+    end
+  end
+end