wycats-merb-core 0.9.8

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

@@ -0,0 +1,107 @@
+module Merb
+  class << self
+
+    # ==== Returns
+    # Hash:: The available mime types.
+    def available_mime_types
+      ResponderMixin::TYPES
+    end
+
+    # Any specific outgoing headers should be included here.  These are not
+    # the content-type header but anything in addition to it.
+    # +transform_method+ should be set to a symbol of the method used to
+    # transform a resource into this mime type.
+    # For example for the :xml mime type an object might be transformed by
+    # calling :to_xml, or for the :js mime type, :to_json.
+    # If there is no transform method, use nil.
+    #
+    # ==== Autogenerated Methods
+    # Adding a mime-type adds a render_type method that sets the content
+    # type and calls render.
+    # 
+    # By default this does: def render_all, def render_yaml, def render_text,
+    # def render_html, def render_xml, def render_js, and def render_yaml
+    #
+    # ==== Parameters
+    # key<Symbol>:: The name of the mime-type. This is used by the provides API
+    # transform_method<~to_s>:: 
+    #   The associated method to call on objects to convert them to the
+    #   appropriate mime-type. For instance, :json would use :to_json as its
+    #   transform_method.
+    # mimes<Array[String]>::
+    #   A list of possible values sent in the Accept header, such as text/html,
+    #   that should be associated with this content-type.
+    # new_response_headers<Hash>::
+    #   The response headers to set for the the mime type. For example: 
+    #   'Content-Type' => 'application/json; charset=utf-8'; As a shortcut for
+    #   the common charset option, use :charset => 'utf-8', which will be
+    #   correctly appended to the mimetype itself.
+    # &block:: a block which recieves the current controller when the format
+    #   is set (in the controller's #content_type method)
+    def add_mime_type(key, transform_method, mimes, new_response_headers = {}, default_quality = 1, &block) 
+      enforce!(key => Symbol, mimes => Array)
+      
+      content_type = new_response_headers["Content-Type"] || mimes.first
+      
+      if charset = new_response_headers.delete(:charset)
+        content_type += "; charset=#{charset}"
+      end
+      
+      ResponderMixin::TYPES.update(key => 
+        {:accepts           => mimes, 
+         :transform_method  => transform_method,
+         :content_type      => content_type,
+         :response_headers  => new_response_headers,
+         :default_quality   => default_quality,
+         :response_block    => block })
+
+      mimes.each do |mime|
+        ResponderMixin::MIMES.update(mime => key)
+      end
+
+      Merb::RenderMixin.class_eval <<-EOS, __FILE__, __LINE__
+        def render_#{key}(thing = nil, opts = {})
+          self.content_type = :#{key}
+          render thing, opts
+        end
+      EOS
+    end
+
+    # Removes a MIME-type from the mime-type list.
+    #
+    # ==== Parameters
+    # key<Symbol>:: The key that represents the mime-type to remove.
+    #
+    # ==== Notes
+    # :all is the key for */*; It can't be removed.
+    def remove_mime_type(key)
+      return false if key == :all
+      ResponderMixin::TYPES.delete(key)
+    end
+
+    # ==== Parameters
+    # key<Symbol>:: The key that represents the mime-type.
+    #
+    # ==== Returns
+    # Symbol:: The transform method for the mime type, e.g. :to_json.
+    #
+    # ==== Raises
+    # ArgumentError:: The requested mime type is not valid.
+    def mime_transform_method(key)
+      raise ArgumentError, ":#{key} is not a valid MIME-type" unless ResponderMixin::TYPES.key?(key)
+      ResponderMixin::TYPES[key][:transform_method]
+    end
+
+    # The mime-type for a particular inbound Accepts header.
+    #
+    # ==== Parameters
+    # header<String>:: The name of the header to find the mime-type for.
+    #
+    # ==== Returns
+    # Hash:: The mime type information.
+    def mime_by_request_header(header)
+      available_mime_types.find {|key,info| info[:accepts].include?(header)}.first
+    end
+    
+  end
+end

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

@@ -0,0 +1,123 @@
+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
+  #
+  # If you need to request basic authentication inside an action you need to use the request! method.
+  #
+  # ====Example
+  #
+  #    class Sessions < Application
+  #  
+  #      def new
+  #        case content_type
+  #        when :html
+  #          render
+  #        else
+  #          basic_authentication.request!
+  #        end
+  #      end
+  # 
+  #    end 
+  #
+  #---
+  # @public
+  def basic_authentication(realm = "Application", &authenticator)
+    @_basic_authentication ||= BasicAuthentication.new(self, realm, &authenticator)
+  end
+  
+  class BasicAuthentication
+    # So we can have access to the status codes
+    include Merb::ControllerExceptions
+
+    def initialize(controller, realm = "Application", &authenticator)
+      @controller = controller
+      @realm = realm
+      @auth = Rack::Auth::Basic::Request.new(@controller.request.env)
+      authenticate_or_request(&authenticator) if authenticator
+    end
+
+    def authenticate(&authenticator)
+      if @auth.provided? and @auth.basic?
+        authenticator.call(*@auth.credentials)
+      else
+        false
+      end
+    end
+
+    def request
+      request!
+      throw :halt, @controller.render("HTTP Basic: Access denied.\n", :status => Unauthorized.status, :layout => false)
+    end
+    
+    # This is a special case for use outside a before filter.  Use this if you need to 
+    # request basic authenticaiton as part of an action
+    def request!
+      @controller.status = Unauthorized.status
+      @controller.headers['WWW-Authenticate'] = 'Basic realm="%s"' % @realm
+    end
+    
+    # Checks to see if there has been any basic authentication credentials provided
+    def provided?
+      @auth.provided?
+    end
+    
+    def username
+      provided? ? @auth.credentials.first : nil
+    end
+    
+    def password
+      provided? ? @auth.credentials.last : nil
+    end
+    
+    protected
+    
+    def authenticate_or_request(&authenticator)
+      authenticate(&authenticator) || request
+    end
+    
+  end
+
+end

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

@@ -0,0 +1,83 @@
+# Provides conditional get support in Merb core.
+# Conditional get support is intentionally
+# simple and does not do fancy stuff like making
+# ETag value from Ruby objects for you.
+#
+# The most interesting method for end user is
+# +request_fresh?+ that is used after setting of
+# last modification time or ETag:
+#
+# ==== Example
+#
+# def show
+#   self.etag = Digest::SHA1.hexdigest(calculate_cache_key(params))
+#
+#   if request_fresh?
+#     self.status = 304
+#     return ''
+#   else
+#     @product = Product.get(params[:id])
+#     display @product
+#   end
+# end
+module Merb::ConditionalGetMixin
+
+  # Sets ETag response header by calling
+  # #to_s on the argument.
+  #
+  # ==== Parameters
+  # tag<~to_s>::
+  #   value of ETag header enclosed in double quotes
+  #   as required by the RFC
+  def etag=(tag)
+    headers[Merb::Const::ETAG] = %("#{tag}")
+  end
+
+  # ==== Returns
+  # <String>::
+  #   Value of ETag response header or nil if it's not set.
+  def etag
+    headers[Merb::Const::ETAG]
+  end
+
+  # ==== Returns
+  # <Boolean>::
+  # true if ETag response header equals If-None-Match request header,
+  # false otherwise
+  def etag_matches?(tag = self.etag)
+    tag == self.request.if_none_match
+  end
+
+  # Sets Last-Modified response header.
+  #
+  # ==== Parameters
+  # tag<Time>::
+  # resource modification timestamp converted into format
+  # required by the RFC
+  def last_modified=(time)
+    headers[Merb::Const::LAST_MODIFIED] = time.httpdate
+  end
+
+  # ==== Returns
+  # <String>::
+  #   Value of Last-Modified response header or nil if it's not set.
+  def last_modified
+    Time.rfc2822(headers[Merb::Const::LAST_MODIFIED])
+  end
+
+  # ==== Returns
+  # <Boolean>::
+  # true if Last-Modified response header is < than
+  # If-Modified-Since request header value, false otherwise.
+  def not_modified?(time = self.last_modified)
+    request.if_modified_since && time && time <= request.if_modified_since
+  end
+
+  # ==== Returns
+  # <Boolean>::
+  # true if either ETag matches or entity is not modified,
+  # so request is fresh; false otherwise
+  def request_fresh?
+    etag_matches?(self.etag) || not_modified?(self.last_modified)
+  end
+end

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

@@ -0,0 +1,319 @@
+module Merb
+  # Module that is mixed in to all implemented controllers.
+  module ControllerMixin
+    
+    # Enqueu a block to run in a background thread outside of the request
+    # response dispatch
+    #
+    # ==== Parameters
+    # takes a block to run later
+    #
+    # ==== Example
+    # run_later do
+    #   SomeBackgroundTask.run
+    # end
+    #
+    def run_later(&blk)
+      Merb::Dispatcher.work_queue << blk
+    end
+    
+    # Renders the block given as a parameter using chunked encoding.
+    #
+    # ==== Parameters
+    # &blk:: 
+    #   A block that, when called, will use send_chunks to send chunks of data
+    #   down to the server. The chunking will terminate once the block returns.
+    #
+    # ==== Examples
+    #   def stream
+    #     prefix = '<p>'
+    #     suffix = "</p>\r\n"
+    #     render_chunked do
+    #       IO.popen("cat /tmp/test.log") do |io|
+    #         done = false
+    #         until done
+    #           sleep 0.3
+    #           line = io.gets.chomp
+    #           
+    #           if line == 'EOF'
+    #             done = true
+    #           else
+    #             send_chunk(prefix + line + suffix)
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    def render_chunked(&blk)
+      must_support_streaming!
+      headers['Transfer-Encoding'] = 'chunked'
+      Proc.new { |response|
+        @response = response
+        response.send_status_no_connection_close('')
+        response.send_header
+        blk.call
+        response.write("0\r\n\r\n")
+      }
+    end
+
+    # Writes a chunk from +render_chunked+ to the response that is sent back to
+    # the client. This should only be called within a +render_chunked+ block.
+    #
+    # ==== Parameters
+    # data<String>:: a chunk of data to return.
+    def send_chunk(data)
+      @response.write('%x' % data.size + "\r\n")
+      @response.write(data + "\r\n")
+    end
+    
+    # ==== Parameters
+    # &blk::
+    #   A proc that should get called outside the mutex, and which will return
+    #   the value to render.
+    #
+    # ==== Returns
+    # Proc::
+    #   A block that Mongrel can call later, allowing Merb to release the
+    #   thread lock and render another request.
+    def render_deferred(&blk)
+      must_support_streaming!
+      Proc.new {|response|
+        result = blk.call
+        response.send_status(result.length)
+        response.send_header
+        response.write(result)
+      }
+    end
+    
+    # Renders the passed in string, then calls the block outside the mutex and
+    # after the string has been returned to the client.
+    #
+    # ==== Parameters
+    # str<String>:: A +String+ to return to the client.
+    # &blk:: A block that should get called once the string has been returned.
+    #
+    # ==== Returns
+    # Proc::
+    #   A block that Mongrel can call after returning the string to the user.
+    def render_then_call(str, &blk)
+      must_support_streaming!
+      Proc.new {|response|
+        response.send_status(str.length)
+        response.send_header
+        response.write(str)
+        blk.call        
+      }      
+    end
+
+    # ==== Parameters
+    # url<String>::
+    #   URL to redirect to. It can be either a relative or fully-qualified URL.
+    # opts<Hash>:: An options hash (see below)
+    #
+    # ==== Options (opts)
+    # :message<Hash>::
+    #   Messages to pass in url query string as value for "_message"
+    # :permanent<Boolean>::
+    #   When true, return status 301 Moved Permanently
+    #
+    # ==== Returns
+    # String:: Explanation of redirect.
+    #
+    # ==== Examples
+    #   redirect("/posts/34")
+    #   redirect("/posts/34", :message => { :notice => 'Post updated successfully!' })
+    #   redirect("http://www.merbivore.com/")
+    #   redirect("http://www.merbivore.com/", :permanent => true)
+    def redirect(url, opts = {})
+      default_redirect_options = { :message => nil, :permanent => false }
+      opts = default_redirect_options.merge(opts)
+      if opts[:message]
+        notice = Merb::Request.escape([Marshal.dump(opts[:message])].pack("m"))
+        url = url =~ /\?/ ? "#{url}&_message=#{notice}" : "#{url}?_message=#{notice}"
+      end
+      self.status = opts[:permanent] ? 301 : 302
+      Merb.logger.info("Redirecting to: #{url} (#{self.status})")
+      headers['Location'] = url
+      "<html><body>You are being <a href=\"#{url}\">redirected</a>.</body></html>"
+    end
+    
+    def message
+      @_message = defined?(@_message) ? @_message : request.message
+    end
+    
+    # Sends a file over HTTP.  When given a path to a file, it will set the
+    # right headers so that the static file is served directly.
+    #
+    # ==== Parameters
+    # file<String>:: Path to file to send to the client.
+    # opts<Hash>:: Options for sending the file (see below).
+    #
+    # ==== Options (opts)
+    # :disposition<String>::
+    #   The disposition of the file send. Defaults to "attachment".
+    # :filename<String>::
+    #   The name to use for the file. Defaults to the filename of file.
+    # :type<String>:: The content type.
+    #
+    # ==== Returns
+    # IO:: An I/O stream for the file.
+    def send_file(file, opts={})
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename] ? opts[:filename] : File.basename(file)}")
+      headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary'
+      )
+      File.open(file, 'rb')
+    end
+    
+    # Send binary data over HTTP to the user as a file download. May set content type,
+    # apparent file name, and specify whether to show data inline or download as an attachment.
+    #
+    # ==== Parameters
+    # data<String>:: Path to file to send to the client.
+    # opts<Hash>:: Options for sending the data (see below).
+    #
+    # ==== Options (opts)
+    # :disposition<String>::
+    #   The disposition of the file send. Defaults to "attachment".
+    # :filename<String>::
+    #   The name to use for the file. Defaults to the filename of file.
+    # :type<String>:: The content type.
+    def send_data(data, opts={})
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename]}") if opts[:filename]
+      headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary'
+      )
+      data
+    end
+    
+    # Streams a file over HTTP.
+    #
+    # ==== Parameters
+    # opts<Hash>:: Options for the file streaming (see below).
+    # &stream::
+    #   A block that, when called, will return an object that responds to
+    #   +get_lines+ for streaming.
+    #
+    # ==== Options
+    # :disposition<String>::
+    #   The disposition of the file send. Defaults to "attachment".
+    # :type<String>:: The content type.
+    # :content_length<Numeric>:: The length of the content to send.
+    # :filename<String>:: The name to use for the streamed file.
+    #
+    # ==== Examples
+    #   stream_file({ :filename => file_name, :type => content_type,
+    #     :content_length => content_length }) do |response|
+    #     AWS::S3::S3Object.stream(user.folder_name + "-" + user_file.unique_id, bucket_name) do |chunk|
+    #       response.write chunk
+    #     end
+    #   end
+    def stream_file(opts={}, &stream)
+      must_support_streaming!
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename]}")
+      headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary',
+        # Rack specification requires header values to respond to :each
+        'CONTENT-LENGTH'            => opts[:content_length].to_s
+      )
+      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
+    # from nginx. For more information, see the nginx wiki:
+    # http://wiki.codemongers.com/NginxXSendfile
+    #
+    # and the following sample gist:
+    # http://gist.github.com/11225
+    #
+    # there's also example application up on GitHub:
+    #
+    # http://github.com/michaelklishin/nginx-x-accel-redirect-example-application/tree/master
+    #
+    # Unless Content-Disposition is set before calling this method,
+    # it is set to attachment with streamed file name.
+    #
+    # ==== Parameters
+    # path<String>:: Path to file to send to the client.
+    # content_type<String>:: content type header value. By default is set to empty string to let
+    #                        Nginx detect it.
+    #
+    # ==== Return
+    # One space string.
+    def nginx_send_file(path, content_type = "")
+      # Let Nginx detect content type unless it is explicitly set
+      headers['Content-Type']        = content_type
+      headers["Content-Disposition"] ||= "attachment; filename=#{path.split('/').last}"
+      
+      headers['X-Accel-Redirect']    = path
+      
+      return ' '
+    end  
+  
+    # 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, Hash>:: An expiration time for the cookie, or a hash of cookie options.
+    # ---
+    # @public
+    def set_cookie(name, value, expires)
+      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
+    # method is used primarily internally in Merb.
+    #
+    # Use the +cookies+ hash to manipulate cookies instead.
+    #
+    # ==== Parameters
+    # name<~to_s>:: A name for the cookie to delete.
+    def delete_cookie(name)
+      set_cookie(name, nil, Merb::Const::COOKIE_EXPIRED_TIME)
+    end
+    
+    # Escapes the string representation of +obj+ and escapes it for use in XML.
+    #
+    # ==== Parameter
+    # obj<~to_s>:: The object to escape for use in XML.
+    #
+    # ==== Returns
+    # String:: The escaped object.
+    def escape_xml(obj)
+      Erubis::XmlHelper.escape_xml(obj.to_s)
+    end
+    alias h escape_xml
+    alias escape_html escape_xml
+    
+    private
+      # Checks whether streaming is supported by the current Rack adapter.
+      #
+      # ==== Raises
+      # NotImplemented:: The Rack adapter doens't support streaming.
+      def must_support_streaming!
+        unless request.env['rack.streaming']
+          raise(Merb::ControllerExceptions::NotImplemented, "Current Rack adapter does not support streaming")
+        end
+      end
+  end
+end