rocket_pants 1.0.0.rc.1

data/lib/rocket_pants/controller/error_handling.rb

@@ -0,0 +1,108 @@
+module RocketPants
+  # Makes it easier to both throw named exceptions (corresponding to
+  # error states in the response) and to then process the response into
+  # something useable in the response.
+  module ErrorHandling
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from RocketPants::Error, :with => :render_error
+      class_attribute :error_mapping
+      self.error_mapping = {}
+    end
+
+    module ClassMethods
+
+      def map_error!(from, to)
+        error_mapping[from] = to
+        rescue_from from, :with => :render_error
+      end
+
+    end
+
+    # Dynamically looks up and then throws the error given by a symbolic name.
+    # Optionally takes a string message argument and a hash of 'context'.
+    # @overload error!(name, context = {})
+    #   @param [Symbol] name the name of the exception, looked up using RocketPants::Errors
+    #   @param [Hash{Symbol => Object}] context the options passed to the error message translation.
+    # @overload error!(name, message, context = {})
+    #   @param [Symbol] name the name of the exception, looked up using RocketPants::Errors
+    #   @param [String] message an optional message describing the error
+    #   @param [Hash{Symbol => Object}] context the options passed to the error message translation.
+    # @raise [RocketPants::Error] the error from the given options
+    def error!(name, *args)
+      context   = args.extract_options!
+      klass     = Errors[name] || Error
+      exception = klass.new(*args).tap { |e| e.context = context }
+      raise exception
+    end
+
+    # From a given exception, gets the corresponding error message using I18n.
+    # It will use context (if defined) on the exception for the I18n context base and
+    # will use either the result of Error#error_name (if present) or :system for
+    # the name of the error.
+    # @param [StandardError] exception the exception to get the message from
+    # @return [String] the found error message.
+    def lookup_error_message(exception)
+      # TODO: Add in notification hooks for non-standard exceptions.
+      name    = lookup_error_name(exception)
+      message = (exception.message == exception.class.name) ? 'An unknown error has occurred.' : exception.message
+      I18n.t name, lookup_error_context(exception).reverse_merge(:scope => :"rocket_pants.errors", :default => message)
+    end
+
+    # Lookup error name will automatically handle translating errors to a
+    # simpler, symbol representation. It's implemented like this to make it
+    # possible to override to a simple format.
+    # @param [StandardError] exception the exception to find the name for
+    # @return [Symbol] the name of the given error
+    def lookup_error_name(exception)
+      if exception.respond_to?(:error_name)
+        exception.error_name
+      else
+        :system
+      end
+    end
+
+    # Returns the error status code for a given exception.
+    # @param [StandardError] exception the exception to find the status for
+    # @return [Symbol] the name of the given error
+    def lookup_error_status(exception)
+      exception.respond_to?(:http_status) ? exception.http_status : 500
+    end
+
+    # Returns the i18n context for a given exception.
+    # @param [StandardError] exception the exception to find the context for
+    # @param [Hash] the i18n translation context.
+    def lookup_error_context(exception)
+      exception.respond_to?(:context) ? exception.context : {}
+    end
+
+    # Returns extra error details for a given object, making it useable
+    # for hooking in external exceptions.
+    def lookup_error_extras(exception)
+      {}
+    end
+
+    # Renders an exception as JSON using a nicer version of the error name and
+    # error message, following the typically error standard as laid out in the JSON
+    # api design.
+    # @param [StandardError] exception the error to render a response for.
+    def render_error(exception)
+      logger.debug "Rendering error for #{exception.class.name}: #{exception.message}" if logger
+      # When a normalised class is present, make sure we
+      # convert it to a useable error class.
+      normalised_class = exception.class.ancestors.detect do |klass|
+        klass < StandardError and error_mapping.has_key?(klass)
+      end
+      if normalised_class
+        exception = error_mapping[normalised_class].new(exception.message)
+      end
+      self.status = lookup_error_status(exception)
+      render_json({
+        :error             => lookup_error_name(exception).to_s,
+        :error_description => lookup_error_message(exception)
+      }.merge(lookup_error_extras(exception)))
+    end
+
+  end
+end

data/lib/rocket_pants/controller/instrumentation.rb

@@ -0,0 +1,30 @@
+require 'action_controller/log_subscriber'
+require 'abstract_controller/logger'
+
+module RocketPants
+  module Instrumentation
+    extend  ActiveSupport::Concern
+    include AbstractController::Logger
+    
+    def process_action(action, *args)
+      raw_payload = {
+        :controller => self.class.name,
+        :action     => self.action_name,
+        :params     => request.filtered_parameters,
+        :formats    => [:json],
+        :method     => request.method,
+        :path       => (request.fullpath rescue "unknown")
+      }
+
+      ActiveSupport::Notifications.instrument("start_processing.rocket_pants", raw_payload.dup)
+
+      ActiveSupport::Notifications.instrument("process_action.rocket_pants", raw_payload) do |payload|
+        result = super
+        payload[:status] = response.status
+        result
+      end
+    end
+    
+  end
+  ActionController::LogSubscriber.attach_to :rocket_pants
+end

data/lib/rocket_pants/controller/rescuable.rb

@@ -0,0 +1,66 @@
+module RocketPants
+  # An alternative to Rail's built in ActionController::Rescue module,
+  # tailored to deeply integrate rescue notififers into the application.
+  #
+  # Thus, it is relatively simple to 
+  module Rescuable
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    DEFAULT_NOTIFIER_CALLBACK = lambda do |controller, exception, req|
+      # Do nothing by default...
+    end
+    
+    NAMED_NOTIFIER_CALLBACKS = {
+      :airbrake => lambda { |c, e, r|
+        unless c.send(:airbrake_local_request?)
+          c.error_identifier = Airbrake.notify(e, c.send(:airbrake_request_data))
+        end
+      }
+    }
+
+    included do
+      class_attribute :exception_notifier_callback
+      attr_accessor :error_identifier
+      self.exception_notifier_callback ||= DEFAULT_NOTIFIER_CALLBACK
+    end
+
+    module ClassMethods
+
+      # Tells rocketpants to use the given exception handler to deal with errors.
+      # E.g. use_named_exception_handler! :airbrake
+      # @param [Symbol] name the name of the exception handler to use.
+      def use_named_exception_notifier(name)
+        handler = NAMED_NOTIFIER_CALLBACKS.fetch(name, DEFAULT_NOTIFIER_CALLBACK)
+        self.exception_notifier_callback = handler
+      end
+
+    end
+
+    # Overrides the lookup_error_extras method to also include an error_identifier field
+    # to be sent back to the client.
+    def lookup_error_extras(exception)
+      extras = super
+      extras = extras.merge(:error_identifier => error_identifier) if error_identifier
+      extras
+    end
+
+    private
+
+    # Overrides the processing internals to rescue any exceptions and handle them with the
+    # registered exception rescue handler.
+    def process_action(*args)
+      super
+    rescue Exception => exception
+      # Otherwise, use the default built in handler.
+      logger.error "Exception occured: #{exception.class.name} - #{exception.message}"
+      logger.error "Exception backtrace:"
+      exception.backtrace[0, 10].each do |backtrace_line|
+        logger.error "=> #{backtrace_line}"
+      end
+      exception_notifier_callback.call(self, exception, request)
+      render_error exception
+    end
+
+  end
+end

data/lib/rocket_pants/controller/respondable.rb

@@ -0,0 +1,122 @@
+require 'will_paginate/collection'
+
+module RocketPants
+  module Respondable
+    extend ActiveSupport::Concern
+
+    def self.normalise_object(object, options = {})
+      # Convert the object using a standard grape-like lookup chain.
+      if object.is_a?(Array) || object.is_a?(Set)
+        object.map { |o| normalise_object o, options }
+      elsif object.respond_to?(:serializable_hash)
+        object.serializable_hash options
+      elsif object.respond_to?(:as_json)
+        object.as_json options
+      else
+        object
+      end
+    end
+
+    RENDERING_OPTIONS = [:status, :content_type]
+
+    private
+
+    def normalise_object(object, options = {})
+      Respondable.normalise_object object, options.except(*RENDERING_OPTIONS)
+    end
+
+    # Given a json object or encoded json, will encode it
+    # and set it to be the output of the given page.
+    def render_json(json, options = {})
+      # Setup data from options
+      self.status       = options[:status] if options[:status]
+      self.content_type = options[:content_type] if options[:content_type]
+      options = options.slice(*RENDERING_OPTIONS)
+      # Don't convert raw strings to JSON.
+      json = ActiveSupport::JSON.encode(json) unless json.respond_to?(:to_str)
+      # Encode the object to json.
+      self.status        ||= :ok
+      self.content_type  ||= Mime::JSON
+      self.response_body   = json
+      headers['Content-Length'] = Rack::Utils.bytesize(json).to_s
+    end
+
+    # Renders a raw object, without any wrapping etc.
+    # Suitable for nicer object handling.
+    def responds(object, options = {})
+      render_json normalise_object(object, options), options
+    end
+
+    # Renders a single resource.
+    def resource(object, options = {})
+      pre_process_exposed_object object, :resource, true
+      render_json({
+       :response => normalise_object(object, options)
+      }, options)
+      post_process_exposed_object object, :resource, true
+    end
+
+    # Renders a normal collection to JSON.
+    def collection(collection, options = {})
+      pre_process_exposed_object collection, :collection, false
+      options = options.reverse_merge(:compact => true)
+      render_json({
+        :response => normalise_object(collection, options),
+        :count    => collection.length
+      }, options)
+      post_process_exposed_object collection, :collection, false
+    end
+
+    # Renders a paginated collecton to JSON.
+    def paginated(collection, options = {})
+      pre_process_exposed_object collection, :paginated, false
+      options = options.reverse_merge(:compact => true)
+      render_json({
+        :response   => normalise_object(collection, options),
+        :count      => collection.length,
+        :pagination => {
+          :previous => collection.previous_page.try(:to_i),
+          :next     => collection.next_page.try(:to_i),
+          :current  => collection.current_page.try(:to_i),
+          :per_page => collection.per_page.try(:to_i),
+          :count    => collection.total_entries.try(:to_i),
+          :pages    => collection.total_pages.try(:to_i)
+        }
+      }, options)
+      post_process_exposed_object collection, :paginated, false
+    end
+
+    # Exposes an object to the response - Essentiall, it tells the
+    # controller that this is what we need to render.
+    def exposes(object, options = {})
+      case object
+      when WillPaginate::Collection
+        paginated object, options
+      when Array
+        collection object, options
+      else
+        resource object, options
+      end
+    end
+    alias expose exposes
+
+    # Hooks in to allow you to perform pre-processing of objects
+    # when they are exposed. Used for plugins to the controller.
+    #
+    # @param [Object] resource the exposed object.
+    # @param [Symbol] type the type of object exposed, one of :resource, :collection or :paginated
+    # @param [true,false] singular Whether or not the given object is singular (e.g. :resource)
+    def pre_process_exposed_object(resource, type, singular)
+    end
+
+    # Hooks in to allow you to perform post-processing of objects
+    # when they are exposed. Used for plugins to the controller.
+    #
+    # @param [Object] resource the exposed object.
+    # @param [Symbol] type the type of object exposed, one of :resource, :collection or :paginated
+    # @param [true,false] singular Whether or not the given object is singular (e.g. :resource)
+    def post_process_exposed_object(resource, type, singular)
+    end
+
+  end
+end

data/lib/rocket_pants/controller/url_for.rb

@@ -0,0 +1,11 @@
+module RocketPants
+  module UrlFor
+    
+    def url_options
+      options = super
+      options = options.merge(:version => version) if version.present?
+      options
+    end
+    
+  end
+end

data/lib/rocket_pants/controller/versioning.rb

@@ -0,0 +1,39 @@
+module RocketPants
+  module Versioning
+    
+    extend ActiveSupport::Concern
+    
+    included do
+      class_attribute :_version_range
+    end
+    
+    module ClassMethods
+      
+      def version(version)
+        version = version..version if version.is_a?(Integer)
+        self._version_range = version
+        before_filter :verify_api_version
+      end
+      
+    end
+    
+    protected
+    
+    def version
+      if !instance_variable_defined?(:@version)
+        @version = begin
+          version = params[:version]
+          version.presence && Integer(version)
+        rescue ArgumentError
+          nil
+        end
+      end
+      @version
+    end
+    
+    def verify_api_version
+      error! :invalid_version unless version.present? && _version_range.include?(version)
+    end
+      
+  end
+end

data/lib/rocket_pants/exceptions.rb

@@ -0,0 +1,112 @@
+module RocketPants
+  
+  # Represents the standard error type as defined by the API.
+  # RocketPants::Error instances will be caught and automatically rendered as JSON
+  # by the controller during processing.
+  class Error < StandardError
+    
+    # @overload error_name
+    #   Returns the error name for this error class, defaulting to
+    #   the class name underscorized minus _error.
+    #   @return [Symbol] the given errors name.
+    # @overload error_name(value)
+    #   Sets the error name for the current class.
+    #   @param [#to_sym] the name of this error.
+    def self.error_name(value = nil)
+      if value.nil?
+        @name ||= name.underscore.split("/").last.sub(/_error$/, '').to_sym
+      else
+        @name = (value.presence && value.to_sym)
+      end
+    end
+    
+    # @overload http_status
+    #   Returns the http status code of this error, defaulting to 400 (Bad Request).
+    # @overload http_status(value)
+    #   Sets the http status code for this error to a given symbol / integer.
+    #   @param value [String, Fixnum] value the new status code.
+    def self.http_status(value = nil)
+      if value.nil?
+        @http_status ||= 400
+      else
+        @http_status = (value.presence && value)
+      end
+    end
+    
+    # Gets the name of this error from the class.
+    def error_name
+      self.class.error_name
+    end
+    
+    # Gets the http status of this error from the class.
+    def http_status
+      self.class.http_status
+    end
+    
+    # Setter for optional data about this error, used for translation.
+    attr_writer :context
+    
+    # Gets the context for this error, defaulting to nil.
+    # @return [Hash] the context for this param.
+    def context
+      @context ||= {}
+    end
+    
+    error_name :unknown
+
+  end
+  
+  # A simple map of data about errors that the rocket pants system can handle.
+  class Errors
+    
+    @@errors = {}
+    
+    # Returns a hash of all known errors, keyed by their error name.
+    # @return [Hash{Symbol => RocketPants::Error}] the hash of known errors.
+    def self.all
+      @@errors.dup
+    end
+    
+    # Looks up a specific error from the given name, returning nil if none are found.
+    # @param [#to_sym] name the name of the error to look up.
+    # @return [Error, nil] the error class if found, otherwise nil.
+    def self.[](name)
+      @@errors[name.to_sym]
+    end
+    
+    # Adds a given Error class in the list of all errors, making it suitable
+    # for lookup via [].
+    # @see Errors[]
+    # @param [Error] error the error to register.
+    def self.add(error)
+      @@errors[error.error_name] = error
+    end
+    
+    # Creates an error class to represent a given error state.
+    # @param [Symbol] name the name of the given error
+    # @param [Hash] options the options used to create the error class.
+    # @option options [Symbol] :class_name the name of the class (under `RocketPants`), defaulting to the classified name.
+    # @option options [Symbol] :error_name the name of the error, defaulting to the name parameter.
+    # @option options [Symbol] :http_status the status code for the given error, doing nothing if absent.
+    # @example Adding a RocketPants::NinjasUnavailable class w/ `:service_unavailable` as the status code:
+    #   register! :ninjas_unavailable, :http_status => :service_unavailable
+    def self.register!(name, options = {})
+      klass_name = (options[:class_name] || name.to_s.classify).to_sym
+      klass = Class.new(Error)
+      klass.error_name(options[:error_name] || name.to_s.underscore)
+      klass.http_status(options[:http_status]) if options[:http_status].present?
+      (options[:under] || RocketPants).const_set klass_name, klass
+      add klass
+      klass
+    end
+    
+    # The default set of exceptions.
+    register! :throttled,       :http_status => :service_unavailable
+    register! :unauthenticated, :http_status => :unauthorized
+    register! :invalid_version, :http_status => :not_found
+    register! :not_implemented, :http_status => :service_unavailable
+    register! :not_found,       :http_status => :not_found
+    
+  end
+  
+end