merb-core 0.9.2

data/lib/merb-core/controller/exceptions.rb

@@ -0,0 +1,257 @@
+module Merb
+  # ControllerExceptions are a way of simplifying controller code by placing
+  # exceptional logic back into the MVC pattern.
+  #
+  # When a ControllerException is raised within your application merb will
+  # attempt to re-route the request to your Exceptions controller to render
+  # the error in a friendly mannor.
+  #
+  # For example you might have an action in your app that raises NotFound
+  # if a some resource was not available
+  #
+
+  #   def show
+  #     product = Product.find(params[:id])
+  #     raise NotFound if product.nil?
+  #     [...]
+  #   end
+  #
+  # This would halt execution of your action and re-route it over to your
+  # Exceptions controller which might look something like
+  #
+  # class Exceptions < Application
+
+  #   def not_found
+  #     render :layout => :none
+  #   end
+  # end
+  #
+  # As usual the not_found action will look for a template in
+  #   app/views/exceptions/not_found.html.erb
+  #
+  # Note: All standard ControllerExceptions have an HTTP status code associated 
+  # with them which is sent to the browser when the action it is rendered.
+  #
+  # Note: If you do not specifiy how to handle raised ControllerExceptions 
+  # or an unhandlable exception occurs within your customised exception action
+  # then they will be rendered using the built-in error template
+  # in development mode this "built in" template will show stack-traces for
+  # any of the ServerError family of exceptions (you can force the stack-trace
+  # to display in production mode using the :exception_details config option in 
+  # merb.yml)
+  #
+  #
+  # ==== Internal Exceptions 
+  #
+  # Any other rogue errors (not ControllerExceptions) that occur during the 
+  # execution of you app will be converted into the ControllerException 
+  # InternalServerError, and like all ControllerExceptions can be caught
+  # on your Exceptions controller.
+  #
+  # InternalServerErrors return status 500, a common use for cusomizing this
+  # action might be to send emails to the development team, warning that their
+  # application have exploded. Mock example:
+  #
+
+  #   def internal_server_error
+  #     MySpecialMailer.deliver(
+  #       "team@cowboys.com", 
+  #       "Exception occured at #{Time.now}", 
+  #       params[:exception])
+  #     render :inline => 'Something is wrong, but the team are on it!'
+  #   end
+  #
+  # Note: The special param[:exception] is available in all Exception actions 
+  # and contains the ControllerException that was raised (this is handy if
+  # you want to display the associated message or display more detailed info)
+  #
+  #
+  # ==== Extending ControllerExceptions
+  #
+  # To extend the use of the ControllerExceptions one may extend any of the 
+  # HTTPError classes.
+  #
+  # As an example we can create an exception called AdminAccessRequired.
+  #
+  #   class AdminAccessRequired < Merb::ControllerExceptions::Unauthorized; end
+  #
+  # Add the required action to our Exceptions controller
+  #
+  #   class Exceptions < Application
+
+  #     def admin_access_required
+  #       render
+  #     end
+  #   end
+  #
+  # In app/views/exceptions/admin_access_required.rhtml
+  # 
+  #   <h1>You're not an administrator!</h1>
+  #   <p>You tried to access <%= @tried_to_access %> but that URL is 
+  #   restricted to administrators.</p>
+  #
+  module ControllerExceptions #:nodoc: all
+    
+    # Mapping of status code names to their numeric value.
+    STATUS_CODES = {}
+
+    class Base < StandardError #:doc:
+
+      # ==== Returns
+      # String:: The snake cased name of the error without the namespace.
+      def name; self.class.name; end
+
+      # ==== Returns
+      # String:: The snake cased name of the class without the namespace.
+      def self.name
+        to_s.snake_case.split('::').last
+      end
+      
+      # Makes it possible to pass a status-code class to render :status.
+      #
+      # ==== Returns
+      # Fixnum:: The status code of this exception.
+      def self.to_i
+        STATUS
+      end
+      
+      # Registers any subclasses with status codes for easy lookup by
+      # set_status in Merb::Controller.
+      #
+      # Inheritance ensures this method gets inherited by any subclasses, so
+      # it goes all the way down the chain of inheritance.
+      #
+      # ==== Parameters
+      # 
+      # subclass<Merb::ControllerExceptions::Base>::
+      #   The Exception class that is inheriting from Merb::ControllerExceptions::Base
+      def self.inherited(subclass)
+        if subclass.const_defined?(:STATUS)
+          STATUS_CODES[subclass.name.snake_case.to_sym] = subclass.const_get(:STATUS)
+        end
+      end
+    end
+
+    class Informational                 < Merb::ControllerExceptions::Base; end
+
+      class Continue                    < Merb::ControllerExceptions::Informational; STATUS = 100; end
+
+      class SwitchingProtocols          < Merb::ControllerExceptions::Informational; STATUS = 101; end
+
+    class Successful                    < Merb::ControllerExceptions::Base; end
+
+      class OK                          < Merb::ControllerExceptions::Successful; STATUS = 200; end
+
+      class Created                     < Merb::ControllerExceptions::Successful; STATUS = 201; end
+
+      class Accepted                    < Merb::ControllerExceptions::Successful; STATUS = 202; end
+
+      class NonAuthoritativeInformation < Merb::ControllerExceptions::Successful; STATUS = 203; end
+
+      class NoContent                   < Merb::ControllerExceptions::Successful; STATUS = 204; end
+
+      class ResetContent                < Merb::ControllerExceptions::Successful; STATUS = 205; end
+
+      class PartialContent              < Merb::ControllerExceptions::Successful; STATUS = 206; end
+
+    class Redirection                   < Merb::ControllerExceptions::Base; end
+
+      class MultipleChoices             < Merb::ControllerExceptions::Redirection; STATUS = 300; end
+
+      class MovedPermanently            < Merb::ControllerExceptions::Redirection; STATUS = 301; end
+
+      class MovedTemporarily            < Merb::ControllerExceptions::Redirection; STATUS = 302; end
+
+      class SeeOther                    < Merb::ControllerExceptions::Redirection; STATUS = 303; end
+
+      class NotModified                 < Merb::ControllerExceptions::Redirection; STATUS = 304; end
+
+      class UseProxy                    < Merb::ControllerExceptions::Redirection; STATUS = 305; end
+
+      class TemporaryRedirect           < Merb::ControllerExceptions::Redirection; STATUS = 307; end
+
+    class ClientError                   < Merb::ControllerExceptions::Base; end
+
+      class BadRequest                  < Merb::ControllerExceptions::ClientError; STATUS = 400; end
+
+        class MultiPartParseError       < Merb::ControllerExceptions::BadRequest; end
+
+      class Unauthorized                < Merb::ControllerExceptions::ClientError; STATUS = 401; end
+
+      class PaymentRequired             < Merb::ControllerExceptions::ClientError; STATUS = 402; end
+
+      class Forbidden                   < Merb::ControllerExceptions::ClientError; STATUS = 403; end
+
+      class NotFound                    < Merb::ControllerExceptions::ClientError; STATUS = 404; end
+
+        class ActionNotFound            < Merb::ControllerExceptions::NotFound; end
+
+        class TemplateNotFound          < Merb::ControllerExceptions::NotFound; end
+
+        class LayoutNotFound            < Merb::ControllerExceptions::NotFound; end
+
+      class MethodNotAllowed            < Merb::ControllerExceptions::ClientError; STATUS = 405; end
+
+      class NotAcceptable               < Merb::ControllerExceptions::ClientError; STATUS = 406; end
+
+      class ProxyAuthenticationRequired < Merb::ControllerExceptions::ClientError; STATUS = 407; end
+
+      class RequestTimeout              < Merb::ControllerExceptions::ClientError; STATUS = 408; end
+
+      class Conflict                    < Merb::ControllerExceptions::ClientError; STATUS = 409; end
+
+      class Gone                        < Merb::ControllerExceptions::ClientError; STATUS = 410; end
+
+      class LengthRequired              < Merb::ControllerExceptions::ClientError; STATUS = 411; end
+
+      class PreconditionFailed          < Merb::ControllerExceptions::ClientError; STATUS = 412; end
+
+      class RequestEntityTooLarge       < Merb::ControllerExceptions::ClientError; STATUS = 413; end
+
+      class RequestURITooLarge          < Merb::ControllerExceptions::ClientError; STATUS = 414; end
+
+      class UnsupportedMediaType        < Merb::ControllerExceptions::ClientError; STATUS = 415; end
+
+      class RequestRangeNotSatisfiable  < Merb::ControllerExceptions::ClientError; STATUS = 416; end
+
+      class ExpectationFailed           < Merb::ControllerExceptions::ClientError; STATUS = 417; end
+
+    class ServerError                   < Merb::ControllerExceptions::Base; end
+
+      class NotImplemented              < Merb::ControllerExceptions::ServerError; STATUS = 501; end
+
+      class BadGateway                  < Merb::ControllerExceptions::ServerError; STATUS = 502; end
+
+      class ServiceUnavailable          < Merb::ControllerExceptions::ServerError; STATUS = 503; end
+
+      class GatewayTimeout              < Merb::ControllerExceptions::ServerError; STATUS = 504; end
+
+      class HTTPVersionNotSupported     < Merb::ControllerExceptions::ServerError; STATUS = 505; end
+
+      class InternalServerError         < Merb::ControllerExceptions::ServerError #:doc: 
+        STATUS = 500
+        # DEFAULT_TEMPLATE = ::Merb::Dispatcher::DEFAULT_ERROR_TEMPLATE
+        def initialize(exception = nil)
+          @exception = exception
+          @coderay = CodeRay rescue nil
+        end
+
+        def backtrace
+          @exception ? @exception.backtrace : backtrace
+        end
+
+        def message
+          @exception ? @exception.message : message
+        end
+      end
+  end
+  
+  # Required to show exceptions in the log file
+  #
+  # e<Exception>:: The exception that a message is being generated for
+  def self.exception(e) #:nodoc:
+    "#{ e.message } - (#{ e.class })\n" <<  
+    "#{(e.backtrace or []).join("\n")}" 
+  end
+
+end

data/lib/merb-core/controller/merb_controller.rb

@@ -0,0 +1,214 @@
+class Merb::Controller < Merb::AbstractController
+  
+  class_inheritable_accessor :_hidden_actions, :_shown_actions
+  cattr_accessor :_subclasses, :_session_id_key, :_session_secret_key, :_session_expiry
+  self._subclasses = Set.new
+
+  def self.subclasses_list() _subclasses end
+  
+  self._session_secret_key = nil
+  self._session_id_key = Merb::Config[:session_id_key] || '_session_id'
+  self._session_expiry = Merb::Config[:session_expiry] || Merb::Const::WEEK * 2
+  
+  include Merb::ResponderMixin
+  include Merb::ControllerMixin
+
+  attr_accessor :route
+  
+  class << self
+    
+    # ==== Parameters
+    # klass<Merb::Controller>::
+    #   The Merb::Controller inheriting from the base class.
+    def inherited(klass)
+      _subclasses << klass.to_s
+      self._template_root = Merb.dir_for(:view) unless self._template_root
+      super
+    end
+
+    # Hide each of the given methods from being callable as actions.
+    #
+    # ==== Parameters
+    # *names<~to-s>:: Actions that should be added to the list.
+    #
+    # ==== Returns
+    # Array[String]::
+    #   An array of actions that should not be possible to dispatch to.
+    # 
+    #---
+    # @public
+    def hide_action(*names)
+      self._hidden_actions = self._hidden_actions | names.map { |n| n.to_s }
+    end
+
+    # Makes each of the given methods being callable as actions. You can use
+    # this to make methods included from modules callable as actions.
+    #
+    # ==== Parameters
+    # *names<~to-s>:: Actions that should be added to the list.
+    #
+    # ==== Returns
+    # Array[String]::
+    #   An array of actions that should be dispatched to even if they would not
+    #   otherwise be.
+    # 
+    # ==== Example
+    #   module Foo
+    #     def self.included(base)
+    #       base.show_action(:foo)
+    #     end
+    #
+    #     def foo
+    #       # some actiony stuff
+    #     end
+    #
+    #     def foo_helper
+    #       # this should not be an action
+    #     end
+    #   end
+    #
+    #---
+    # @public
+    def show_action(*names)
+      self._shown_actions = self._shown_actions | names.map {|n| n.to_s}
+    end
+
+    # This list of actions that should not be callable.
+    # 
+    # ==== Returns
+    # Array[String]:: An array of actions that should not be dispatchable.
+    def _hidden_actions
+      actions = read_inheritable_attribute(:_hidden_actions)
+      actions ? actions : write_inheritable_attribute(:_hidden_actions, [])
+    end
+
+    # This list of actions that should be callable.
+    # 
+    # ==== Returns
+    # Array[String]::
+    #   An array of actions that should be dispatched to even if they would not
+    #   otherwise be.
+    def _shown_actions
+      actions = read_inheritable_attribute(:_shown_actions)
+      actions ? actions : write_inheritable_attribute(:_shown_actions, [])      
+    end
+
+    # The list of actions that are callable, after taking defaults,
+    # _hidden_actions and _shown_actions into consideration. It is calculated
+    # once, the first time an action is dispatched for this controller.
+    #
+    # ==== Returns
+    # Array[String]:: A list of actions that should be callable.
+    def callable_actions
+      unless @callable_actions
+        callables = []
+        klass = self
+        begin
+          callables << (klass.public_instance_methods(false) + klass._shown_actions) - klass._hidden_actions
+          klass = klass.superclass
+        end until klass == Merb::Controller || klass == Object
+        @callable_actions = Merb::SimpleSet.new(callables.flatten)
+      end
+      @callable_actions
+    end
+    
+  end
+  
+  # The location to look for a template for a particular controller, action,
+  # and mime-type. This is overridden from AbstractController, which defines a
+  # version of this that does not involve mime-types.
+  #
+  # ==== Parameters
+  # action<~to_s>:: The name of the action that will be rendered.
+  # type<~to_s>::
+  #    The mime-type of the template that will be rendered. Defaults to nil.
+  # controller<~to_s>::
+  #   The name of the controller that will be rendered. Defaults to
+  #   controller_name.
+  #
+  # ==== Note
+  # By default, this renders ":controller/:action.:type". To change this,
+  # override it in your application class or in individual controllers.
+  #
+  #---
+  # @public
+  def _template_location(action, type = nil, controller = controller_name)
+    "#{controller}/#{action}.#{type}"
+  end  
+  
+  # Build a new controller.
+  #
+  # Sets the variables that came in through the dispatch as available to
+  # the controller. 
+  #
+  # This method uses the :session_id_cookie_only and :query_string_whitelist
+  # configuration options. See CONFIG for more details.
+  #
+  # ==== Parameters
+  # request<Merb::Request>:: The Merb::Request that came in from Mongrel.
+  # status<Integer>:: An integer code for the status. Defaults to 200.
+  # headers<Hash{header => value}>:: 
+  #   A hash of headers to start the controller with. These headers can be
+  #   overridden later by the #headers method.
+  #---
+  # @semipublic
+  def initialize(request, status=200, headers={'Content-Type' => 'text/html; charset=utf-8'})
+    super()
+    @request, @status, @headers = request, status, headers
+  end
+  
+  # Dispatch the action.
+  #
+  # ==== Parameters
+  # action<~to_s>:: An action to dispatch to. Defaults to :index.
+  #
+  # ==== Returns
+  # String:: The string sent to the logger for time spent.
+  #
+  # ==== Raises
+  # ActionNotFound:: The requested action was not found in class.
+  #---
+  # @semipublic
+  def _dispatch(action=:index)
+    start = Time.now
+    if self.class.callable_actions.include?(action.to_s)
+      super(action)
+    else
+      raise ActionNotFound, "Action '#{action}' was not found in #{self.class}"
+    end
+    @_benchmarks[:action_time] = Time.now - start
+  end
+  
+  attr_reader :request, :headers
+  attr_accessor :status
+  
+  # ==== Returns
+  # Hash:: The parameters from the request object
+  def params()  request.params  end
+    
+  # ==== Returns
+  # Merb::Cookies:: 
+  #   A new Merb::Cookies instance representing the cookies that came in
+  #   from the request object
+  #
+  # ==== Note
+  # Headers are passed into the cookie object so that you can do:
+  #   cookies[:foo] = "bar"
+  def cookies() @_cookies ||= _setup_cookies end
+    
+  # ==== Returns
+  # Hash:: The session that was extracted from the request object.
+  def session() request.session end
+    
+  private
+
+  # Create a default cookie jar, and pre-set a fixation cookie
+  # if fixation is enabled
+  def _setup_cookies
+    cookies = ::Merb::Cookies.new(request.cookies, @headers)
+    if request.params.key?(_session_id_key) && route.allow_fixation?
+      cookies[_session_id_key] = request.params[_session_id_key]
+    end
+    cookies
+  end
+end