merb-core 0.9.2 → 0.9.3

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

@@ -1,22 +1,23 @@
 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
+  include Merb::AuthenticationMixin
 
   attr_accessor :route
-  
+
   class << self
-    
+
     # ==== Parameters
     # klass<Merb::Controller>::
     #   The Merb::Controller inheriting from the base class.
@@ -34,7 +35,7 @@ class Merb::Controller < Merb::AbstractController
     # ==== Returns
     # Array[String]::
     #   An array of actions that should not be possible to dispatch to.
-    # 
+    #
     #---
     # @public
     def hide_action(*names)
@@ -51,7 +52,7 @@ class Merb::Controller < Merb::AbstractController
     # 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)
@@ -74,7 +75,7 @@ class Merb::Controller < Merb::AbstractController
     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
@@ -83,14 +84,14 @@ class Merb::Controller < Merb::AbstractController
     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, [])      
+      actions ? actions : write_inheritable_attribute(:_shown_actions, [])
     end
 
     # The list of actions that are callable, after taking defaults,
@@ -98,7 +99,7 @@ class Merb::Controller < Merb::AbstractController
     # once, the first time an action is dispatched for this controller.
     #
     # ==== Returns
-    # Array[String]:: A list of actions that should be callable.
+    # SimpleSet[String]:: A set of actions that should be callable.
     def callable_actions
       unless @callable_actions
         callables = []
@@ -106,40 +107,53 @@ class Merb::Controller < Merb::AbstractController
         begin
           callables << (klass.public_instance_methods(false) + klass._shown_actions) - klass._hidden_actions
           klass = klass.superclass
-        end until klass == Merb::Controller || klass == Object
+        end until klass == Merb::AbstractController || 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,
+
+    # This is a stub method so plugins can implement param filtering if they want.
+    #
+    # ==== Parameters
+    # params<Hash{Symbol => String}>:: A list of params
+    #
+    # ==== Returns
+    # Hash{Symbol => String}:: A new list of params, filtered as desired
+    #---
+    # @semipublic
+    def _filter_params(params)
+      params
+    end
+
+  end # class << self
+
+  # The location to look for a template for a particular controller, context,
   # 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.
+  # context<~to_s>:: The name of the action or template basename 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
+  # ==== Notes
   # 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  
-  
+  def _template_location(context, type = nil, controller = controller_name)
+    controller ? "#{controller}/#{context}.#{type}" : "#{context}.#{type}"
+  end
+
   # Build a new controller.
   #
   # Sets the variables that came in through the dispatch as available to
-  # the controller. 
+  # the controller.
   #
   # This method uses the :session_id_cookie_only and :query_string_whitelist
   # configuration options. See CONFIG for more details.
@@ -147,7 +161,7 @@ class Merb::Controller < Merb::AbstractController
   # ==== 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}>:: 
+  # headers<Hash{header => value}>::
   #   A hash of headers to start the controller with. These headers can be
   #   overridden later by the #headers method.
   #---
@@ -156,7 +170,7 @@ class Merb::Controller < Merb::AbstractController
     super()
     @request, @status, @headers = request, status, headers
   end
-  
+
   # Dispatch the action.
   #
   # ==== Parameters
@@ -178,37 +192,47 @@ class Merb::Controller < Merb::AbstractController
     end
     @_benchmarks[:action_time] = Time.now - start
   end
-  
+
   attr_reader :request, :headers
-  attr_accessor :status
-  
+  attr_reader :status
+
+  # Set the response status code.
+  #
+  # ==== Parameters
+  # s<Fixnum, Symbol>:: A status-code or named http-status
+  def status=(s)
+    if s.is_a?(Symbol) && STATUS_CODES.key?(s)
+      @status = STATUS_CODES[s]
+    elsif s.is_a?(Fixnum)
+      @status = s
+    else
+      raise ArgumentError, "Status should be of type Fixnum or Symbol, was #{s.class}"
+    end
+  end
+
   # ==== Returns
   # Hash:: The parameters from the request object
   def params()  request.params  end
-    
+
   # ==== Returns
-  # Merb::Cookies:: 
+  # Merb::Cookies::
   #   A new Merb::Cookies instance representing the cookies that came in
   #   from the request object
   #
-  # ==== Note
+  # ==== Notes
   # 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
+    ::Merb::Cookies.new(request.cookies, @headers)
   end
 end

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

@@ -53,7 +53,7 @@ module Merb
     # ==== Parameters
     # key<Symbol>:: The key that represents the mime-type to remove.
     #
-    # ==== Note
+    # ==== Notes
     # :all is the key for */*; It can't be removed.
     def remove_mime_type(key)
       return false if key == :all

data/lib/merb-core/controller/mixins/authentication.rb

@@ -0,0 +1,87 @@
+module Merb::AuthenticationMixin
+  
+  # Attempts to authenticate the user via HTTP Basic authentication. Takes a
+  # block with the username and password, if the block yields false the
+  # authentication is not accepted and :halt is thrown.
+  #
+  # If no block is passed, +basic_authentication+, the +request+ and +authenticate+
+  # methods can be chained. These can be used to independently request authentication
+  # or confirm it, if more control is desired.
+  #
+  # ==== Parameters
+  # realm<~to_s>:: The realm to authenticate against. Defaults to 'Application'.
+  # &authenticator:: A block to check if the authentication is valid.
+  #
+  # ==== Examples
+  #     class Application < Merb::Controller
+  #     
+  #       before :authenticate
+  #     
+  #       protected
+  #     
+  #       def authenticate
+  #         basic_authentication("My App") do |username, password|
+  #           password == "secret"
+  #         end
+  #       end
+  #     
+  #     end
+  #
+  #     class Application < Merb::Controller
+  #     
+  #       before :authenticate
+  #     
+  #       def authenticate
+  #         user = basic_authentication.authenticate do |username, password|
+  #           User.authenticate(username, password)
+  #         end
+  #     
+  #         if user
+  #           @current_user = user
+  #         else
+  #           basic_authentication.request
+  #         end
+  #       end
+  #     
+  #     end
+  #
+  #---
+  # @public
+  def basic_authentication(realm = "Application", &authenticator)
+    BasicAuthentication.new(self, realm, &authenticator)
+  end
+  
+  class BasicAuthentication #:nodoc:
+    # So we can have access to the status codes
+    include Merb::ControllerExceptions
+
+    def initialize(controller, realm = "Application", &authenticator)
+      @controller = controller
+      @realm = realm
+      authenticate_or_request(&authenticator) if authenticator
+    end
+
+    def authenticate(&authenticator)
+      auth = Rack::Auth::Basic::Request.new(@controller.request.env)
+
+      if auth.provided? and auth.basic?
+        authenticator.call(*auth.credentials)
+      else
+        false
+      end
+    end
+
+    def request
+      @controller.headers['WWW-Authenticate'] = 'Basic realm="%s"' % @realm
+      throw :halt, @controller.render("HTTP Basic: Access denied.\n", :status => Unauthorized.status, :layout => false)
+    end
+    
+    protected
+    
+    def authenticate_or_request(&authenticator)
+      authenticate(&authenticator) || request
+    end
+    
+  end
+
+end

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

@@ -186,15 +186,17 @@ module Merb
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
       disposition << %(; filename="#{opts[:filename]}")
-      response.headers.update(
+      headers.update(
         'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
         'Content-Disposition'       => disposition,
         'Content-Transfer-Encoding' => 'binary',
         'CONTENT-LENGTH'            => opts[:content_length]
       )
-      response.send_status(opts[:content_length])
-      response.send_header
-      stream
+      Proc.new{|response|
+        response.send_status(opts[:content_length])
+        response.send_header
+        stream.call(response)
+      }
     end
 
     # Uses the nginx specific +X-Accel-Redirect+ header to send a file directly
@@ -208,22 +210,19 @@ module Merb
       return
     end  
   
-    # Sets a cookie to be included in the response. This method is used
-    # primarily internally in Merb.
+    # Sets a cookie to be included in the response.
     #
     # If you need to set a cookie, then use the +cookies+ hash.
     #
     # ==== Parameters
     # name<~to_s>:: A name for the cookie.
     # value<~to_s>:: A value for the cookie.
-    # expires<~gmtime:~strftime>:: An expiration time for the cookie.
+    # expires<~gmtime:~strftime, Hash>:: An expiration time for the cookie, or a hash of cookie options.
+    # ---
+    # @public
     def set_cookie(name, value, expires)
-      (headers['Set-Cookie'] ||=[]) << (Merb::Const::SET_COOKIE % [
-        name.to_s, 
-        ::Merb::Request.escape(value.to_s), 
-        # Cookie expiration time must be GMT. See RFC 2109
-        expires.gmtime.strftime(Merb::Const::COOKIE_EXPIRATION_FORMAT)
-      ])
+      options = expires.is_a?(Hash) ? expires : {:expires => expires}
+      cookies.set_cookie(name, value, options)
     end
     
     # Marks a cookie as deleted and gives it an expires stamp in the past. This
@@ -256,7 +255,9 @@ module Merb
       # ==== Raises
       # NotImplemented:: The Rack adapter doens't support streaming.
       def must_support_streaming!
-        raise(NotImplemented, "Current Rack adapter does not support streaming") unless request.env['rack.streaming']
+        unless request.env['rack.streaming']
+          raise(Merb::ControllerExceptions::NotImplemented, "Current Rack adapter does not support streaming")
+        end
       end
   end
-end
+end

data/lib/merb-core/controller/mixins/render.rb

@@ -5,11 +5,49 @@ module Merb::RenderMixin
   # ==== Parameters
   # base<Module>:: Module that is including RenderMixin (probably a controller)
   def self.included(base)
+    base.extend(ClassMethods)
     base.class_eval do
-      class_inheritable_accessor :_layout, :_cached_templates
+      class_inheritable_accessor :_default_render_options
     end
   end
   
+  module ClassMethods
+    
+    # Return the default render options.
+    #
+    # ==== Returns
+    # Hash:: An options hash
+    def default_render_options
+      self._default_render_options ||= {}
+    end
+    
+    # Set default render options at the class level.
+    #
+    # ==== Parameters
+    # opts<Hash>:: An options hash
+    def render_options(opts)
+      self._default_render_options = opts
+    end
+    
+    # Set the default layout to use or nil/false to disable layout rendering.
+    # This is a shortcut for render_options :layout => false. 
+    #
+    # ==== Parameters
+    # layout<~to_s>:: The layout that should be used for this class
+    # 
+    # ==== Returns
+    # Hash:: The default render options.
+    def layout(layout)
+      self.default_render_options.update(:layout => (layout ? layout : false))
+    end
+    
+    # Enable the default layout logic - reset the layout option.
+    def default_layout
+      self.default_render_options.delete(:layout)
+    end
+    
+  end
+  
   # Render the specified item, with the specified options.
   #
   # ==== Parameters
@@ -46,6 +84,9 @@ module Merb::RenderMixin
     # render :format => :xml means render nil, :format => :xml
     opts, thing = thing, nil if thing.is_a?(Hash)
     
+    # Merge with class level default render options
+    opts = self.class.default_render_options.merge(opts)
+    
     # If you don't specify a thing to render, assume they want to render the current action
     thing ||= action_name.to_sym
 
@@ -91,7 +132,9 @@ module Merb::RenderMixin
   # thing<String, Symbol>::
   #   The thing to attempt to render via #render before calling the transform
   #   method on the object. Defaults to nil.
-  # opts<Hash>:: An options hash that will be passed on to #render
+  # opts<Hash>:: 
+  #   An options hash that will be used for rendering
+  #   (passed on to #render or serialization methods like #to_json or #to_xml)
   # 
   # ==== Returns
   # String::
@@ -111,32 +154,59 @@ module Merb::RenderMixin
   #   display @object, :layout => "zoo"
   #   #=> display @object, nil, :layout => "zoo"
   #
-  # ==== Note
+  # If you need to pass extra parameters to serialization method, for instance,
+  # to exclude some of attributes or serialize associations, just pass options
+  # for it.
+  # For instance, 
+  #
+  # display	@locations, :except => [:locatable_type, :locatable_id], :include => [:locatable]
+  #
+  # serializes object with polymorphic association,	not raw	locatable_* attributes.
+  #
+  #  
+  # ==== Options
+  #
+  # :template                a template to use for rendering
+  # :layout                  a layout to use for rendering
+  
+  # all other options        options that will be pass to serialization method
+  #                          like #to_json or #to_xml
+  #
+  # ==== Notes
   # The transformed object will not be used in a layout unless a :layout is
   # explicitly passed in the opts.
+  #
   def display(object, thing = nil, opts = {})
     # display @object, "path/to/foo" means display @object, nil, :template => "path/to/foo"
     # display @object, :template => "path/to/foo" means display @object, nil, :template => "path/to/foo"
-    opts[:template], thing = thing, nil if thing.is_a?(String) || thing.is_a?(Hash)
+    template_opt = opts.delete(:template)
+    
+    case thing
+    when String
+      template_opt, thing = thing, nil
+    when Hash
+      opts, thing = thing, nil
+    end
     
     # Try to render without the object
-    render(thing || action_name.to_sym, opts)
+    render(thing || action_name.to_sym, opts.merge(:template => template_opt))
   
   # If the render fails (i.e. a template was not found)
   rescue TemplateNotFound
+    # Merge with class level default render options
+    opts = self.class.default_render_options.merge(opts)
     
     # Figure out what to transform and raise NotAcceptable unless there's a transform method assigned
     transform = Merb.mime_transform_method(content_type)
     raise NotAcceptable unless transform && object.respond_to?(transform)
-    
-    # Throw the transformed object for later consumption by the layout
-    throw_content(:for_layout, object.send(transform))
-  
+
     # Only use a layout if one was specified
-    if opts[:layout]
+    layout_opt = opts.delete(:layout)
+    
+    if layout_opt
       # Look for the layout under the default layout directly. If it's not found, reraise
       # the TemplateNotFound error
-      template = _template_location(opts[:layout], layout.index(".") ? content_type : nil, "layout")      
+      template = _template_location(layout_opt, layout.index(".") ? content_type : nil, "layout")      
       layout = _template_for(_template_root / template) ||
         (raise TemplateNotFound, "No layout found at #{_template_root / template}.*")      
               
@@ -145,6 +215,12 @@ module Merb::RenderMixin
     
     # Otherwise, just render the transformed object
     else
+      unless opts.empty?
+        # there are options for serialization method
+        throw_content(:for_layout, object.send(transform, opts))
+      else
+        throw_content(:for_layout, object.send(transform))
+      end  
       catch_content(:for_layout)
     end
   end
@@ -195,7 +271,11 @@ module Merb::RenderMixin
       end.join
     else
       @_merb_partial_locals = opts
-      sent_template = send(template_method)
+      if template_method && self.respond_to?(template_method)
+        sent_template = send(template_method)
+      else
+        raise TemplateNotFound, "Could not find template at #{template_location}.*"
+      end
     end
     @_merb_partial_locals = @_old_partial_locals.pop
     sent_template
@@ -235,9 +315,7 @@ module Merb::RenderMixin
   #   one in to this method), and not found. No error will be raised if no
   #   layout was specified, and the default layouts were not found.
   def _get_layout(layout = nil)
-    if _layout && !layout
-      layout = _layout.instance_of?(Symbol) && self.respond_to?(_layout, true) ? send(_layout) : _layout
-    end
+    layout = layout.instance_of?(Symbol) && self.respond_to?(layout, true) ? send(layout) : layout
     layout = layout.to_s if layout
     
     # If a layout was provided, throw an error if it's not found
@@ -258,24 +336,30 @@ module Merb::RenderMixin
   # and template location of the first match.
   #
   # ==== Parameters
-  # thing<Object>:: The controller action.
+  # context<Object>:: The controller action or template basename.
   # content_type<~to_s>:: The content type. Defaults to nil.
   # controller<~to_s>:: The name of the controller. Defaults to nil.
   #
   # ==== Options (opts)
   # :template<String>::
   #   The location of the template to use. Defaults to whatever matches this
-  #   thing, content_type and controller.
+  #   context, content_type and controller.
   #
   # ==== Returns
   # Array[Symbol, String]::
   #   A pair consisting of the template method and location.
-  def _template_for(thing, content_type, controller=nil, opts={})
+  def _template_for(context, content_type, controller=nil, opts={})
     template_method = nil
     template_location = nil
     
     self.class._template_roots.reverse_each do |root, template_location| 
-      template_location = root / (opts[:template] || self.send(template_location, thing, content_type, controller))
+      if opts[:template] # use the given template as the location context
+        template_location = root / self.send(template_location, opts[:template], content_type, nil)
+        template_method = Merb::Template.template_for(template_location)
+        break if template_method && self.respond_to?(template_method)
+      end
+      
+      template_location = root / (opts[:template] || self.send(template_location, context, content_type, controller))
       template_method = Merb::Template.template_for(template_location)
       break if template_method && self.respond_to?(template_method)
     end
@@ -296,6 +380,16 @@ module Merb::RenderMixin
     @_caught_content[obj]
   end
   
+  # Called in templates to test for the existence of previously thrown content.
+  #
+  # ==== Parameters
+  # obj<Object>:: The key in the thrown_content hash. Defaults to :for_layout.
+  #---
+  # @public
+  def thrown_content?(obj = :for_layout)
+    @_caught_content.key?(obj)
+  end
+  
   # Called in templates to store up content for later use. Takes a string
   # and/or a block. First, the string is evaluated, and then the block is
   # captured using the capture() helper provided by the template languages. The