ramaze 0.1.3 → 0.1.4

data/lib/ramaze/dispatcher/error.rb

@@ -11,6 +11,10 @@ module Ramaze
     # actions in your controllers.
 
     class Error
+
+      # The class of exception is matched when an error occurs and the status
+      # code is set. The absolute URLs are used as fallback in case of a total
+      # failure.
       HANDLE_ERROR = {
                           Exception => [ 500, '/error' ],
             Ramaze::Error::NoAction => [ 404, '/error' ],
@@ -20,10 +24,16 @@ module Ramaze
       class << self
         trait :last_error => nil
 
+        # Takes exception, of metainfo only :controller is used at the moment.
+        # Then goes on to try and find the correct response status and path.
+        # In case metainfo has a controller we try to get the action for the
+        # path on it, dispatching there if we find one.
+        # Otherwise a plain-text error message is set as response.
         def process(error, metainfo = {})
           log_error(error)
 
           Thread.current[:exception] = error
+          response = Response.current
 
           key = error.class.ancestors.find{|a| HANDLE_ERROR[a]}
           status, path = *HANDLE_ERROR[key || Exception]
@@ -32,23 +42,25 @@ module Ramaze
           if controller = metainfo[:controller]
             begin
               action = Controller.resolve(controller.mapping + path)
-              return Dispatcher.build_response(action.render, status)
-            rescue Ramaze::Error
+              return response.build(action.render, status)
+            rescue Ramaze::Error => e
               Inform.debug("No custom error page found on #{controller}, going to #{path}")
             end
           end
 
           unless error.message =~ %r(`#{path.split('/').last}')
-            Response.current.status = status
+            response.status = status
             return Dispatcher.dispatch_to(path) if path and Global.error_page
           end
 
-          Dispatcher.build_response(error.message, status)
+          response.build(error.message, status)
         rescue Object => ex
           Inform.error(ex)
-          Dispatcher.build_response(ex.message, status)
+          response.build(ex.message, status)
         end
 
+        # Only logs new errors with full backtrace, repeated errors are shown
+        # only with their message.
         def log_error error
           error_message = error.message
 
@@ -60,6 +72,8 @@ module Ramaze
           end
         end
 
+        # Handle to current exception.
+        # Only works inside request/response cycle.
         def current
           Thread.current[:exception]
         end

data/lib/ramaze/dispatcher/file.rb

@@ -15,14 +15,14 @@ module Ramaze
 
         def process(path)
           return unless file = open_file(path)
-          Dispatcher.build_response(file, Ramaze::STATUS_CODE['OK'])
+          Response.current.build(file, Ramaze::STATUS_CODE['OK'])
         end
 
         # returns file-handle with the open file on success, setting the
         # Content-Type as found in Tool::MIME
 
         def open_file(path)
-          file = Global.public_root/path
+          file = ::File.join(Global.public_root, path =~ /\/$/ ? path + 'index' : path)
 
           if ::File.file?(file)
             response = Response.current

data/lib/ramaze/dispatcher.rb

@@ -10,6 +10,7 @@ require 'ramaze/tool/mime'
 require 'ramaze/dispatcher/action'
 require 'ramaze/dispatcher/error'
 require 'ramaze/dispatcher/file'
+require 'ramaze/dispatcher/directory'
 
 module Ramaze
 
@@ -19,53 +20,63 @@ module Ramaze
   module Dispatcher
 
     # requests are passed to every
+    FILTER = [ Dispatcher::File, Dispatcher::Directory,
+               Dispatcher::Action ] unless defined?(FILTER)
 
-    FILTER = [ Dispatcher::File, Dispatcher::Action ] unless defined?(FILTER)
-
+    # Response codes to cache the output of for repeated requests.
     trait :shielded => [ STATUS_CODE["Not Found"] ]
 
     class << self
       include Trinity
 
+      # Entry point for Adapter#respond, takes a Rack::Request and
+      # Rack::Response, sets up the environment and the goes on to dispatch
+      # for the given path from rack_request.
       def handle rack_request, rack_response
         setup_environment(rack_request, rack_response)
 
         path = request.path_info.squeeze('/')
         Inform.info("Request from #{request.remote_addr}: #{path}")
 
-        if Global.shield
-          shielded_dispatch(path)
-        else
-          dispatch(path)
-        end
+        general_dispatch path
       rescue Object => error
-        Dispatcher::Error.process(error, :path => path, :request => request)
+        meta = { :path => path,
+                 :request => request,
+                 :controller => Thread.current[:controller] }
+        Dispatcher::Error.process(error, meta)
       end
 
-      def dispatch(path)
-        catch(:respond) do
-          redirection = catch(:redirect) do
-            found = filter(path)
-            throw(:respond, found)
+      # protcets against recursive dispatch and reassigns the path_info in the
+      # request, the rest of the request is kept intact.
+      def dispatch_to(path)
+        if request.path_info == path
+          if error = Thread.current[:exception]
+            raise error
+          else
+            raise "Recursive redirect from #{path} to #{path}"
           end
-
-          body, status, head = redirection.values_at(:body, :status, :head)
-          Inform.info("Redirect to `#{head['Location']}'")
-          throw(:respond, build_response(body, status, head))
         end
-      end
-
-      def dispatch_to path
-        raise "Redirect to #{path} from #{path}" if request.path_info == path
         request.path_info = path
+        general_dispatch path
+      end
 
+      # splits up the dispatch based on Global.shield
+      def general_dispatch(path)
         if Global.shield
-          shielded_dispatch(path)
+          shielded_dispatch path
         else
-          dispatch(path)
+          dispatch path
         end
       end
 
+      # Protects somewhat against hammering of erroring paths, since error-pages
+      # take a while to build in the default mode it is possible to decrease
+      # overall speed quite a bit by hitting Ramaze with such paths.
+      # shielded_dispatch checks the path and caches erronous responses so they
+      # won't be recreated but simply pushed out again without stopping at the
+      # Controller.
+      # Please note that this is just minor protection and the best option is to
+      # create a performant error-page instead.
       def shielded_dispatch(path)
         shield_cache = Cache.shield
         handled = shield_cache[path]
@@ -80,10 +91,25 @@ module Ramaze
         end
       end
 
+      # filters the path until a response or redirect is thrown or a filter is
+      # successful, builds a response from the returned hash in case of throws.
+      def dispatch(path)
+        catch(:respond) do
+          redirection = catch(:redirect) do
+            found = filter(path)
+            throw(:respond, found)
+          end
+
+          body, status, head = redirection.values_at(:body, :status, :head)
+          Inform.info("Redirect to `#{head['Location']}'")
+          throw(:respond, response.build(body, status, head))
+        end
+      end
+
       # Calls .process(path) on every class in Dispatcher::FILTER until one
       # returns something else than false/nil.
 
-      def filter path
+      def filter(path)
         result = nil
         FILTER.each do |dispatcher|
           result = dispatcher.process(path)
@@ -92,24 +118,11 @@ module Ramaze
 
         meta = {
           :path => path,
-          :controller => Thread.current[:failed_controller]
+          :controller => Thread.current[:controller]
         }
         Dispatcher::Error.process(result, meta)
       end
 
-      # build a response, default values are from the current response.
-
-      def build_response body = response.body, status = response.status, head = response.header
-        set_cookie if Global.cookies
-        head.each do |key, value|
-          response[key] = value
-        end
-
-        response.body, response.status = body, status
-
-        return response
-      end
-
       # finalizes the session and assigns the key to the response via
       # set_cookie.
 
@@ -128,7 +141,7 @@ module Ramaze
       def setup_environment rack_request, rack_response
         this = Thread.current
         this[:request]  = rack_request
-        this[:session]  = Session.new(request)
+        this[:session]  = Session.new(request) if Global.sessions
         this[:response] = rack_response
       end
     end

data/lib/ramaze/global/dsl.rb

@@ -2,7 +2,7 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
-  CLIOption = Struct.new('CLIOption', :name, :default, :doc, :cli)
+  CLIOption = Struct.new('CLIOption', :name, :default, :doc, :cli, :short)
   OPTIONS     = {}
   CLI_OPTIONS = []
 
@@ -24,10 +24,11 @@ module Ramaze
       def o(doc, options = {})
         cli_given = options.has_key?(:cli)
         cli = options.delete(:cli)
+        short = options.delete(:short)
         name, default = options.to_a.flatten
 
         if cli_given
-          option = CLIOption.new(name, default, doc, cli)
+          option = CLIOption.new(name, default, doc, cli, short)
           CLI_OPTIONS << option
         end
 

data/lib/ramaze/global/globalstruct.rb

@@ -7,8 +7,10 @@ module Ramaze
     end
   end
 
+  # Class for Ramaze::Global instance.
   class GlobalStruct
 
+    # mapping of :adapter => to the right class-name.
     ADAPTER_ALIAS = {
       :webrick => :WEBrick,
       :mongrel => :Mongrel,
@@ -16,6 +18,7 @@ module Ramaze
       :fcgi    => :Fcgi,
     }
 
+    # mapping of :cache => to the right class-name.
     CACHE_ALIAS = {
       :memcached => :MemcachedCache,
       :memory    => :MemoryCache,
@@ -23,21 +26,21 @@ module Ramaze
     }
 
     class << self
-      def setup options = {}
-        self.fill(options)
-      end
+      alias setup fill
     end
 
+    # Called from Ramaze::start, sets all the options.
     def startup(options = {})
       options.each do |key, value|
         if (method(key) rescue false)
-          self[key] = value
+          send("#{key}=", value)
         else
           create_member(key, value)
         end
       end
     end
 
+    # batch-assignment of key/value from hash, yields self if a block is given.
     def setup(hash = {})
       hash.each do |key, value|
         self.send("#{key}=", value)
@@ -45,8 +48,11 @@ module Ramaze
       yield(self) if block_given?
     end
 
+
     # Object wraps
 
+    # get right classname, require the file for given adapter and answer with
+    # the actual class.
     def adapter
       if internal = self[:adapter]
         class_name = ADAPTER_ALIAS[internal.to_sym]
@@ -55,28 +61,44 @@ module Ramaze
       end
     end
 
+    # get right classname, require the file for given cache and answer with
+    # the actual class.
     def cache
       cache_name = self[:cache].to_sym
       class_name = CACHE_ALIAS[cache_name] || cache_name
       cache = Ramaze.const_get(class_name)
     end
 
+    # a range built from port and the number of spawns.
     def ports
       (port.to_i..(port.to_i + (spawn.to_i - 1)))
     end
 
+    # reassigns the interval in the instance of SourceReload that is running or
+    # just waiting.
     def sourcereload=(interval)
       self[:sourcereload] = interval
       sri = Thread.main[:sourcereload]
       sri.interval = interval if sri
     end
 
+    def template_root=(tr)
+      self[:template_root] = File.expand_path(tr)
+    end
+
+    def public_root=(pr)
+      self[:public_root] = File.expand_path(pr)
+    end
+
+
     # External helpers
 
+    # Answers with values for given keys by sending each to self
     def values_at(*keys)
       keys.map{|key| __send__(key)}
     end
 
+    # Creates a new attr_accessor like method-pair.
     def create_member key, value = nil
       Inform.warn "Create #{key}=#{value.inspect} on Global"
 

data/lib/ramaze/global.rb

@@ -18,7 +18,7 @@ module Ramaze
       :backtrace_size => 10, :cli => 10
 
     o "Turn benchmarking every request on.",
-      :benchmarking => false, :cli => false
+      :benchmarking => false, :cli => false, :short => :b
 
     o "Use this for general caching and as base for Cache.new.",
       :cache => :memory, :cli => [:memory, :memcached, :yaml]
@@ -26,9 +26,6 @@ module Ramaze
     o "Turn on naive caching of all requests.",
       :cache_all => false, :cli => false
 
-    o "Turn on cookies for all requests.",
-      :cookies => true, :cli => true
-
     o "Compile Templates",
       :compile => false, :cli => false
 
@@ -36,11 +33,17 @@ module Ramaze
       :controllers => Set.new
 
     o "Start Ramaze within an IRB session",
-      :console => false, :cli => false
+      :console => false, :cli => false, :short => :c
 
     o "Turn on customized error pages.",
       :error_page => true, :cli => true
 
+    o "Caching actions to the filesystem in Global.public_root",
+      :file_cache => false, :cli => false
+
+    o "Base directory for meta information of file-caching",
+      :file_cache_meta_dir => "cache_meta", :cli => "cache_meta"
+
     o "Specify what IP Ramaze will respond to - 0.0.0.0 for all",
       :host => "0.0.0.0", :cli => '0.0.0.0'
 
@@ -51,10 +54,10 @@ module Ramaze
       :origin => :main
 
     o "Specify port",
-      :port => 7000, :cli => 7000
+      :port => 7000, :cli => 7000, :short => :p
 
-    o "Specify the public directory of your application serving static files",
-      :public_root => File.expand_path('./public')
+    o "Specify directory to serve static files",
+      :public_root => './public', :cli => './public'
 
     o "Record all Request objects by assigning a filtering Proc to me.",
       :record => false
@@ -62,6 +65,9 @@ module Ramaze
     o "Don't wait until all adapter-threads are finished or killed.",
       :run_loose => false, :cli => false
 
+    o "Turn on session for all requests.",
+      :sessions => true, :cli => true
+
     o "Turn on BF/DoS protection for error-responses",
       :shield => false, :cli => false
 
@@ -72,13 +78,16 @@ module Ramaze
       :sourcereload => 3, :cli => 3
 
     o "How many adapters Ramaze should spawn.",
-      :spawn => 1, :cli => 1
+      :spawn => 1, :cli => 1, :short => :s
 
     o "Test before start if adapters will be able to connect",
       :test_connections => true, :cli => true
 
-    o "Specify template root for dynamic files relative to main.rb",
-      :template_root => 'template'
+    o "Specify directory to serve dynamic files",
+      :template_root => './template', :cli => './template'
+
+    o "Enable directory listing",
+      :list_directories => false, :cli => false
   end
 
   require 'ramaze/global/globalstruct'

data/lib/ramaze/helper/aspect.rb

@@ -6,19 +6,27 @@ module Ramaze
   # A helper that provides the means to wrap actions of the controller with
   # other methods.
   #
-  # For examples please look at the test/tc_aspect.rb
+  # For examples please look at the spec/ramaze/helper/aspect.rb
   #
   # This is not a default helper due to the possible performance-issues.
   # However, it should be only an overhead of about 6-8 calls, so if you
   # want this feature it shouldn't have too large impact ;)
+  #
+  # Like every other helper, you can use it in your controller with:
+  #
+  #   helper :aspect
 
   module AspectHelper
+
+    # Define traits on class this module is included into.
+
     def self.included(klass)
       klass.trait[:aspects] ||= { :before => {}, :after => {} }
     end
 
     private
 
+    # run block before given actions.
     def before(*meths, &block)
       aspects = trait[:aspects][:before]
       meths.each do |meth|
@@ -27,12 +35,13 @@ module Ramaze
     end
     alias pre before
 
+    # Run block before all actions.
     def before_all(&block)
-      meths = instance_methods(false)
-      before(*meths, &block)
+      trait[:aspects][:before][:all] = block
     end
     alias pre_all before_all
 
+    # run block after given actions.
     def after(*meths, &block)
       aspects = trait[:aspects][:after]
       meths.each do |meth|
@@ -41,34 +50,43 @@ module Ramaze
     end
     alias post after
 
+    # Run block after all actions.
     def after_all(&block)
-      meths = instance_methods(false)
-      after(*meths, &block)
+      trait[:aspects][:after][:all] = block
     end
     alias post_all after_all
 
+    # run block before and after given actions.
     def wrap(*meths, &block)
       before(*meths, &block)
       after(*meths, &block)
     end
 
+    # run block before and after all actions.
     def wrap_all(&block)
-      meths = instance_methods(false)
-      wrap(*meths, &block)
+      trait[:aspects][:before][:all] = block
+      trait[:aspects][:after][:all] = block
     end
   end
 
   class Action
+
+    # overwrites the default Action hook and runs the neccesary blocks in its
+    # scope.
     def before_process
       return unless aspects = controller.ancestral_trait[:aspects]
-      block = aspects[:before][method]
-      instance.instance_eval(&block) if block
+      [ aspects[:before][name], aspects[:before][:all] ].compact.map do |block|
+        instance.instance_eval(&block) if block
+      end
     end
 
+    # overwrites the default Action hook and runs the neccesary blocks in its
+    # scope.
     def after_process
       return unless aspects = controller.ancestral_trait[:aspects]
-      block = aspects[:after][method]
-      instance.instance_eval(&block) if block
+      [ aspects[:after][name], aspects[:after][:all] ].compact.map do |block|
+        instance.instance_eval(&block) if block
+      end
     end
   end
 end