grape 0.2.6 → 0.3.0

data/grape.gemspec

@@ -18,13 +18,13 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rack-mount'
   s.add_runtime_dependency 'rack-accept'
   s.add_runtime_dependency 'activesupport'
-  # s.add_runtime_dependency 'rack-jsonp'
   s.add_runtime_dependency 'multi_json', '>= 1.3.2'
   s.add_runtime_dependency 'multi_xml', '>= 0.5.2'
   s.add_runtime_dependency 'hashie', '~> 1.2'
   s.add_runtime_dependency 'virtus'
   s.add_runtime_dependency 'builder'
 
+  s.add_development_dependency 'grape-entity', '>= 0.2.0'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'maruku'
   s.add_development_dependency 'yard'

data/lib/grape.rb

@@ -1,17 +1,39 @@
+require 'logger'
 require 'rack'
+require 'rack/mount'
 require 'rack/builder'
+require 'rack/accept'
+require 'rack/auth/basic'
+require 'rack/auth/digest/md5'
+require 'hashie'
+require 'active_support/all'
+require 'grape/util/deep_merge'
+require 'grape/util/content_types'
+require 'multi_json'
+require 'multi_xml'
+require 'virtus'
+require 'i18n'
+
+I18n.load_path << File.expand_path('../grape/locale/en.yml', __FILE__)
 
 module Grape
   autoload :API,                 'grape/api'
   autoload :Endpoint,            'grape/endpoint'
   autoload :Route,               'grape/route'
-  autoload :Entity,              'grape/entity'
   autoload :Cookies,             'grape/cookies'
   autoload :Validations,         'grape/validations'
 
   module Exceptions
-    autoload :Base,              'grape/exceptions/base'
-    autoload :ValidationError,   'grape/exceptions/validation_error'
+    autoload :Base,                           'grape/exceptions/base'
+    autoload :Validation,                     'grape/exceptions/validation'
+    autoload :MissingVendorOption,            'grape/exceptions/missing_vendor_option'
+    autoload :MissingMimeType,                'grape/exceptions/missing_mime_type'
+    autoload :MissingOption,                  'grape/exceptions/missing_option'
+    autoload :InvalidFormatter,               'grape/exceptions/invalid_formatter'
+    autoload :InvalidVersionerOption,         'grape/exceptions/invalid_versioner_option'
+    autoload :UnknownValidator,               'grape/exceptions/unknown_validator'
+    autoload :UnknownOptions,                 'grape/exceptions/unknown_options'
+    autoload :InvalidWithOptionForRepresent,  'grape/exceptions/invalid_with_option_for_represent'
   end
 
   module ErrorFormatter

data/lib/grape/api.rb

@@ -1,10 +1,3 @@
-require 'rack/mount'
-require 'rack/auth/basic'
-require 'rack/auth/digest/md5'
-require 'logger'
-require 'grape/util/deep_merge'
-require 'grape/util/content_types'
-
 module Grape
   # The API class is the primary entry point for
   # creating Grape APIs.Users should subclass this
@@ -73,12 +66,21 @@ module Grape
         settings.imbue(key, value)
       end
 
-      # Define a root URL prefix for your entire
-      # API.
+      # Define a root URL prefix for your entire API.
       def prefix(prefix = nil)
         prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
       end
 
+      # Do not route HEAD requests to GET requests automatically
+      def do_not_route_head!
+        set(:do_not_route_head, true)
+      end
+
+      # Do not automatically route OPTIONS
+      def do_not_route_options!
+        set(:do_not_route_options, true)
+      end
+
       # Specify an API version.
       #
       # @example API with legacy support.
@@ -102,7 +104,7 @@ module Grape
           options ||= {}
           options = {:using => :path}.merge!(options)
 
-          raise ArgumentError, "Must specify :vendor option." if options[:using] == :header && !options.has_key?(:vendor)
+          raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.has_key?(:vendor)
 
           @versions = versions | args
           nest(block) do
@@ -134,7 +136,7 @@ module Grape
           set(:default_error_formatter, Grape::ErrorFormatter::Base.formatter_for(new_format, {}))
           # define a single mime type
           mime_type = content_types[new_format.to_sym]
-          raise "missing mime type for #{new_format}" unless mime_type
+          raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type
           settings.imbue(:content_types, new_format.to_sym => mime_type)
         else
           settings[:format]
@@ -225,7 +227,7 @@ module Grape
       # @param model_class [Class] The model class that will be represented.
       # @option options [Class] :with The entity class that will represent the model.
       def represent(model_class, options)
-        raise ArgumentError, "You must specify an entity class in the :with option." unless options[:with] && options[:with].is_a?(Class)
+        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with] && options[:with].is_a?(Class)
         imbue(:representations, model_class => options[:with])
       end
 
@@ -294,16 +296,19 @@ module Grape
       end
 
       def mount(mounts)
-        mounts = {mounts => '/'} unless mounts.respond_to?(:each_pair)
+        mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
         mounts.each_pair do |app, path|
           if app.respond_to?(:inherit_settings)
-            app.inherit_settings(settings.clone)
+            app_settings = settings.clone
+            mount_path = Rack::Mount::Utils.normalize_path([ settings[:mount_path], path ].compact.join("/"))
+            app_settings.set :mount_path, mount_path
+            app.inherit_settings(app_settings)
           end
-          endpoints << Grape::Endpoint.new(settings.clone,
+          endpoints << Grape::Endpoint.new(settings.clone, {
             :method => :any,
             :path => path,
             :app => app
-          )
+          })
         end
       end
 
@@ -431,7 +436,7 @@ module Grape
         end
       end
 
-     def inherited(subclass)
+      def inherited(subclass)
         subclass.reset!
         subclass.logger = logger.clone
       end
@@ -452,7 +457,22 @@ module Grape
     end
 
     def call(env)
-      @route_set.call(env)
+      status, headers, body = @route_set.call(env)
+      headers.delete('X-Cascade') unless cascade?
+      [ status, headers, body ]
+    end
+
+    # Some requests may return a HTTP 404 error if grape cannot find a matching
+    # route. In this case, Rack::Mount adds a X-Cascade header to the response
+    # and sets it to 'pass', indicating to grape's parents they should keep
+    # looking for a matching route on other resources.
+    #
+    # In some applications (e.g. mounting grape on rails), one might need to trap
+    # errors from reaching upstream. This is effectivelly done by unsetting
+    # X-Cascade. Default :cascade is true.
+    def cascade?
+      cascade = ((self.class.settings || {})[:version_options] || {})[:cascade]
+      cascade.nil? ? true : cascade
     end
 
     reset!
@@ -473,16 +493,19 @@ module Grape
       resources.flatten.each do |route|
         allowed_methods[route.route_compiled] << route.route_method
       end
-
       allowed_methods.each do |path_info, methods|
+        if methods.include?('GET') && ! methods.include?("HEAD") && ! self.class.settings[:do_not_route_head]
+          methods = methods | [ 'HEAD' ]
+        end
         allow_header = (["OPTIONS"] | methods).join(", ")
-        unless methods.include?("OPTIONS")
+        unless methods.include?("OPTIONS") || self.class.settings[:do_not_route_options]
           @route_set.add_route( proc { [204, { 'Allow' => allow_header }, []]}, {
             :path_info      => path_info,
             :request_method => "OPTIONS"
           })
         end
         not_allowed_methods = %w(GET PUT POST DELETE PATCH HEAD) - methods
+        not_allowed_methods << "OPTIONS" if self.class.settings[:do_not_route_options]
         not_allowed_methods.each do |bad_method|
           @route_set.add_route( proc { [405, { 'Allow' => allow_header }, []]}, {
             :path_info      => path_info,

data/lib/grape/endpoint.rb

@@ -1,7 +1,3 @@
-require 'rack'
-require 'grape'
-require 'hashie'
-
 module Grape
   # An Endpoint is the proxy scope in which all routing
   # blocks are executed. In other words, any methods
@@ -39,17 +35,22 @@ module Grape
     def initialize(settings, options = {}, &block)
       @settings = settings
       if block_given?
-        method_name = "#{options[:method]} #{settings.gather(:namespace).join( "/")} #{Array(options[:path]).join("/")}"
+        method_name = [ 
+          options[:method],
+          settings.gather(:namespace).join("/"),
+          settings.gather(:mount_path).join("/"),
+          Array(options[:path]).join("/")
+        ].join(" ")
         @source = block
         @block = self.class.generate_api_method(method_name, &block)
       end
       @options = options
 
-      raise ArgumentError, "Must specify :path option." unless options.key?(:path)
+      raise Grape::Exceptions::MissingOption.new(:path) 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)
+      raise Grape::Exceptions::MissingOption.new(:method) unless options.key?(:method)
       options[:method] = Array(options[:method])
 
       options[:route_options] ||= {}
@@ -61,13 +62,19 @@ module Grape
 
     def mount_in(route_set)
       if endpoints
-        endpoints.each{|e| e.mount_in(route_set)}
+        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 })
+          methods = [ route.route_method ]
+          if ! settings[:do_not_route_head] && route.route_method == "GET"
+            methods << "HEAD"
+          end
+          methods.each do |method|
+            route_set.add_route(self, {
+              :path_info => route.route_compiled,
+              :request_method => method,
+            }, { :route_info => route })
+          end
         end
       end
     end
@@ -110,6 +117,7 @@ module Grape
 
     def prepare_path(path)
       parts = []
+      parts << settings[:mount_path].to_s.split("/") if settings[:mount_path]
       parts << settings[:root_prefix].to_s.split("/") if settings[:root_prefix]
 
       uses_path_versioning = settings[:version] && settings[:version_options][:using] == :path
@@ -117,7 +125,7 @@ module Grape
       path_is_empty = path && (path.to_s =~ /^\s*$/ || path.to_s == '/')
 
       parts << ':version' if uses_path_versioning
-      if !uses_path_versioning || (!namespace_is_empty || !path_is_empty)
+      if ! uses_path_versioning || (! namespace_is_empty || ! path_is_empty)
         parts << namespace.to_s if namespace
         parts << path.to_s if path
         format_suffix = '(.:format)'
@@ -243,6 +251,17 @@ module Grape
       end
     end
 
+    # Retrieves all available request headers.
+    def headers
+      @headers ||= @env.dup.inject({}) { |h, (k, v)|
+        if k.start_with? 'HTTP_'
+          k = k[5..-1].gsub('_', '-').downcase.gsub(/^.|[-_\s]./) { |x| x.upcase }
+          h[k] = v
+        end
+        h
+      }
+    end
+
     # Set response content-type
     def content_type(val)
       header('Content-Type', val)

data/lib/grape/exceptions/base.rb

@@ -1,6 +1,10 @@
 module Grape
   module Exceptions
     class Base < StandardError
+
+      BASE_MESSAGES_KEY = 'grape.errors.messages'
+      BASE_ATTRIBUTES_KEY = 'grape.errors.attributes'
+
       attr_reader :status, :message, :headers
 
       def initialize(args = {})
@@ -11,7 +15,52 @@ module Grape
 
       def [](index)
         self.send(index)
-      end 
+      end
+
+      protected
+      # TODO: translate attribute first
+      # if BASE_ATTRIBUTES_KEY.key respond to a string message, then short_message is returned
+      # if BASE_ATTRIBUTES_KEY.key respond to a Hash, means it may have problem , summary and resolution
+      def compose_message(key, attributes = {} )
+        short_message = translate_message(key, attributes)
+        if short_message.is_a? Hash
+          @problem = problem(key, attributes)
+          @summary = summary(key, attributes)
+          @resolution = resolution(key, attributes)
+          [ ["Problem", @problem], ["Summary", @summary], ["Resolution", @resolution]].reduce("") do |message, detail_array|
+            message <<  "\n#{detail_array[0]}:\n  #{detail_array[1]}" unless detail_array[1].blank?
+            message
+          end
+        else
+          short_message
+        end
+      end
+
+      def problem(key, attributes)
+        translate_message("#{key}.problem", attributes)
+      end
+
+      def summary(key, attributes)
+        translate_message("#{key}.summary", attributes)
+      end
+
+      def resolution(key, attributes)
+        translate_message("#{key}.resolution", attributes)
+      end
+
+
+      def translate_attribute(key, options = {})
+        translate("#{BASE_ATTRIBUTES_KEY}.#{key}", { :default => key }.merge(options))
+      end
+
+      def translate_message(key, options = {})
+        translate("#{BASE_MESSAGES_KEY}.#{key}", {:default => '' }.merge(options))
+      end
+
+      def translate(key, options = {})
+        ::I18n.translate(key, options)
+      end
+
     end
   end
 end

data/lib/grape/exceptions/invalid_formatter.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class InvalidFormatter < Base
+
+      def initialize(klass, to_format)
+        super(:message => compose_message("invalid_formatter", :klass => klass, :to_format => to_format))
+      end
+
+    end
+
+  end
+end

data/lib/grape/exceptions/invalid_versioner_option.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+
+    class InvalidVersionerOption < Base
+
+      def initialize(strategy)
+        super(:message => compose_message("invalid_versioner_option", :strategy => strategy))
+      end
+
+    end
+
+  end
+end

data/lib/grape/exceptions/invalid_with_option_for_represent.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class InvalidWithOptionForRepresent < Base
+
+      def initialize
+        super(:message => compose_message("invalid_with_option_for_represent"))
+      end
+
+    end
+
+  end
+
+end
+

data/lib/grape/exceptions/missing_mime_type.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class MissingMimeType < Base
+
+      def initialize(new_format)
+        super(:message => compose_message("missing_mime_type", :new_format => new_format))
+      end
+
+    end
+
+  end
+
+end

data/lib/grape/exceptions/missing_option.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class MissingOption < Base
+
+      def initialize(option)
+        super(:message => compose_message("missing_option", :option => option))
+      end
+
+    end
+
+  end
+end

data/lib/grape/exceptions/missing_vendor_option.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+module Grape
+  module Exceptions
+    class MissingVendorOption < Base
+
+      def initialize
+        super(:message => compose_message("missing_vendor_option"))
+      end
+
+    end
+
+  end
+end