grape 0.1.5 → 0.2.0

data/lib/grape/cookies.rb

@@ -0,0 +1,41 @@
+module Grape
+  class Cookies
+
+      def initialize
+        @cookies = {}
+        @send_cookies = {}
+      end
+
+      def read(request)
+        request.cookies.each do |name, value|
+          @cookies[name.to_sym] = value
+        end
+      end
+
+      def write(header)
+        @cookies.select { |key, value|
+            @send_cookies[key.to_sym] == true
+        }.each { |name, value|
+          Rack::Utils.set_cookie_header!(
+            header, name, value.instance_of?(Hash) ? value : { :value => value })
+        }
+      end
+
+      def [](name)
+        @cookies[name]
+      end
+
+      def []=(name, value)
+        @cookies[name.to_sym] = value
+        @send_cookies[name.to_sym] = true
+      end
+
+      def each(&block)
+        @cookies.each(&block)
+      end
+
+      def delete(name)
+        self.[]=(name, { :value => 'deleted', :expires => Time.at(0) })
+      end
+    end
+end

data/lib/grape/endpoint.rb

@@ -1,5 +1,6 @@
 require 'rack'
 require 'grape'
+require 'hashie'
 
 module Grape
   # An Endpoint is the proxy scope in which all routing
@@ -7,37 +8,119 @@ module Grape
   # on the instance level of this class may be called
   # from inside a `get`, `post`, etc. block.
   class Endpoint
-    def self.generate(&block)
-      c = Class.new(Grape::Endpoint)
-      c.class_eval do
-        @block = block
+    attr_accessor :block, :options, :settings
+    attr_reader :env, :request
+
+    def initialize(settings, options = {}, &block)
+      @settings = settings
+      @block = block
+      @options = options
+
+      raise ArgumentError, "Must specify :path option." unless options.key?(:path)
+      options[:path] = Array(options[:path])
+      options[:path] = ['/'] if options[:path].empty?
+
+      raise ArgumentError, "Must specify :method option." unless options.key?(:method)
+      options[:method] = Array(options[:method])
+
+      options[:route_options] ||= {}
+    end
+
+    def routes
+      @routes ||= prepare_routes
+    end
+
+    def mount_in(route_set)
+      if options[:app] && options[:app].respond_to?(:endpoints)
+        options[:app].endpoints.each{|e| e.mount_in(route_set)}
+      else
+        routes.each do |route|
+          route_set.add_route(self, {
+            :path_info => route.route_compiled,
+            :request_method => route.route_method,
+          }, { :route_info => route })
+        end
       end
-      c
     end
-    
-    class << self
-      attr_accessor :block
+
+    def prepare_routes
+      routes = []
+      options[:method].each do |method|
+        options[:path].each do |path|
+          prepared_path = prepare_path(path)
+
+          anchor = options[:route_options][:anchor]
+          anchor = anchor.nil? ? true : anchor
+
+          path = compile_path(prepared_path, anchor && !options[:app])
+          regex = Rack::Mount::RegexpWithNamedGroups.new(path)
+          path_params = {}
+          # named parameters in the api path
+          named_params = regex.named_captures.map { |nc| nc[0] } - [ 'version', 'format' ]
+          named_params.each { |named_param| path_params[named_param] = "" }
+          # route parameters declared via desc or appended to the api declaration
+          route_params = (options[:route_options][:params] || {})
+          path_params.merge!(route_params)
+          request_method = (method.to_s.upcase unless method == :any)
+          routes << Route.new(options[:route_options].clone.merge({
+            :prefix => settings[:root_prefix],
+            :version => settings[:version] ? settings[:version].join('|') : nil,
+            :namespace => namespace,
+            :method => request_method,
+            :path => prepared_path,
+            :params => path_params,
+            :compiled => path,
+            })
+          )
+        end
+      end
+      routes
     end
-    
-    def self.call(env)
-      new.call(env)
+
+    def prepare_path(path)
+      parts = []
+      parts << settings[:root_prefix] if settings[:root_prefix]
+      parts << ':version' if settings[:version] && settings[:version_options][:using] == :path
+      parts << namespace.to_s if namespace
+      parts << path.to_s if path && '/' != path
+      parts.last << '(.:format)'
+      Rack::Mount::Utils.normalize_path(parts.join('/'))
     end
-    
-    attr_reader :env, :request
-    
+
+    def namespace
+      Rack::Mount::Utils.normalize_path(settings.stack.map{|s| s[:namespace]}.join('/'))
+    end
+
+    def compile_path(prepared_path, anchor = true)
+      endpoint_options = {}
+      endpoint_options[:version] = /#{settings[:version].join('|')}/ if settings[:version]
+      Rack::Mount::Strexp.compile(prepared_path, endpoint_options, %w( / . ? ), anchor)
+    end
+
+    def call(env)
+      dup.call!(env)
+    end
+
+    def call!(env)
+      env['api.endpoint'] = self
+      if options[:app]
+        options[:app].call(env)
+      else
+        builder = build_middleware
+        builder.run options[:app] || lambda{|env| self.run(env) }
+        builder.call(env)
+      end
+    end
+
     # The parameters passed into the request as
     # well as parsed from URL segments.
     def params
-      @params ||= request.params.merge(env['rack.routing_args'] || {}).inject({}) do |h,(k,v)|
-        h[k.to_s] = v
-        h[k.to_sym] = v
-        h
-      end
+      @params ||= Hashie::Mash.new.deep_merge(request.params).deep_merge(env['rack.routing_args'] || {})
     end
-    
+
     # The API version as specified in the URL.
     def version; env['api.version'] end
-    
+
     # End the request and display an error to the
     # end user with the specified message.
     #
@@ -46,7 +129,7 @@ module Grape
     def error!(message, status=403)
       throw :error, :message => message, :status => status
     end
-    
+
     # Set or retrieve the HTTP status code.
     #
     # @param status [Integer] The HTTP Status Code to return for this request.
@@ -61,9 +144,9 @@ module Grape
           else
             200
         end
-      end        
+      end
     end
-    
+
     # Set an individual header or retrieve
     # all headers that have been set.
     def header(key = nil, val = nil)
@@ -73,15 +156,161 @@ module Grape
         @header
       end
     end
+
+    # Set or get a cookie
+    #
+    # @example
+    #   cookies[:mycookie] = 'mycookie val'
+    #   cookies['mycookie-string'] = 'mycookie string val'
+    #   cookies[:more] = { :value => '123', :expires => Time.at(0) }
+    #   cookies.delete :more
+    #
+    def cookies
+      @cookies ||= Cookies.new
+    end
+
+    # Allows you to define the response body as something other than the
+    # return value.
+    #
+    # @example
+    #   get '/body' do
+    #     body "Body"
+    #     "Not the Body"
+    #   end
+    #
+    #   GET /body # => "Body"
+    def body(value = nil)
+      if value
+        @body = value
+      else
+        @body
+      end
+    end
+
+    # Allows you to make use of Grape Entities by setting
+    # the response body to the serializable hash of the
+    # entity provided in the `:with` option. This has the
+    # added benefit of automatically passing along environment
+    # and version information to the serialization, making it
+    # very easy to do conditional exposures. See Entity docs
+    # for more info.
+    #
+    # @example
+    #
+    #   get '/users/:id' do
+    #     present User.find(params[:id]),
+    #       :with => API::Entities::User,
+    #       :admin => current_user.admin?
+    #   end
+    def present(object, options = {})
+      entity_class = options.delete(:with)
+
+      object.class.ancestors.each do |potential|
+        entity_class ||= (settings[:representations] || {})[potential]
+      end
+
+      root = options.delete(:root)
+
+      representation = if entity_class
+        embeds = {:env => env}
+        embeds[:version] = env['api.version'] if env['api.version']
+        entity_class.represent(object, embeds.merge(options))
+      else
+        object
+      end
+
+      representation = { root => representation } if root
+      body representation
+    end
     
-    def call(env)
+    # Returns route information for the current request.
+    #
+    # @example
+    #
+    #   desc "Returns the route description."
+    #   get '/' do
+    #     route.route_description
+    #   end
+    def route
+      env["rack.routing_args"][:route_info]
+    end
+
+    protected
+
+    def run(env)
       @env = env
       @header = {}
       @request = Rack::Request.new(@env)
+
+      self.extend helpers
+      cookies.read(@request)
+      run_filters befores
+      response_text = instance_eval &self.block
+      run_filters afters
+      cookies.write(header)
       
-      response_text = instance_eval &self.class.block
+      [status, header, [body || response_text]]
+    end
+
+    def build_middleware
+      b = Rack::Builder.new
+
+      b.use Grape::Middleware::Error,
+        :default_status => settings[:default_error_status] || 403,
+        :rescue_all => settings[:rescue_all],
+        :rescued_errors => settings[:rescued_errors],
+        :format => settings[:error_format] || :txt,
+        :rescue_options => settings[:rescue_options],
+        :rescue_handlers => settings[:rescue_handlers] || {}
+
+      b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
+      b.use Rack::Auth::Digest::MD5, settings[:auth][:realm], settings[:auth][:opaque], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_digest
+      b.use Grape::Middleware::Prefixer, :prefix => settings[:root_prefix] if settings[:root_prefix]
+
+      if settings[:version]
+        b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]), {
+          :versions        => settings[:version],
+          :version_options => settings[:version_options]
+        }
+      end
       
-      [status, header, [response_text]]
+      b.use Grape::Middleware::Formatter,
+        :format => settings[:format],
+        :default_format => settings[:default_format] || :txt,
+        :content_types => settings[:content_types]
+
+      aggregate_setting(:middleware).each do |m|
+        m = m.dup
+        block = m.pop if m.last.is_a?(Proc)
+        if block
+          b.use *m, &block
+        else
+          b.use *m
+        end
+      end
+
+      b
+    end
+
+    def helpers
+      m = Module.new
+      settings.stack.each{|frame| m.send :include, frame[:helpers] if frame[:helpers]}
+      m
     end
+
+    def aggregate_setting(key)
+      settings.stack.inject([]) do |aggregate, frame|
+        aggregate += (frame[key] || [])
+      end
+    end
+
+    def run_filters(filters)
+      (filters || []).each do |filter|
+        instance_eval &filter
+      end
+    end
+
+    def befores; aggregate_setting(:befores) end
+    def afters; aggregate_setting(:afters) end
   end
 end

data/lib/grape/entity.rb

@@ -0,0 +1,227 @@
+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.
+  #
+  # @example Entity Definition
+  #
+  #   module API
+  #     module Entities
+  #       class User < Grape::Entity
+  #         expose :first_name, :last_name, :screen_name, :location
+  #         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'
+  #
+  #       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
+
+    # 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.
+    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
+
+      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
+
+    # 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
+
+    # 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)|
+        output[key_for(attribute)] = value_for(attribute, opts) if conditions_met?(exposure_options, opts)
+        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)
+      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