waves 0.7.3 → 0.7.5

data/lib/commands/waves-server.rb

@@ -0,0 +1,55 @@
+require 'choice'
+
+Choice.options do
+  header 'Run a waves application server.'
+  header ''
+  option :port  do
+    short '-p'
+    long '--port=PORT'
+    desc 'Port to listen on.'
+    desc 'Defaults to value given in configuration.'
+    cast Integer
+  end
+  separator ''
+  option :host do
+    short '-h'
+    long '--host=HOST'
+    desc 'Host or IP address of the host to bind.'
+    desc 'Defaults to value given in configuration.'
+  end
+  separator ''
+  option :mode do
+    short '-c'
+    long '--config=CONFIG'
+    desc 'Configuration to use.'
+    desc 'Defaults to development.'
+    cast Symbol
+  end
+  separator ''
+  option :directory do
+    short '-D'
+    long '--dir=DIR'
+    desc 'Directory containing the application.'
+    desc 'Defaults to the current directory.'
+  end
+  separator ''
+  option :daemon do
+    short '-d'
+    long '--daemon'
+    desc 'Run as a daemon.'
+  end
+  separator ''
+  option :debugger do
+    short '-u'
+    long '--debugger'
+    desc 'Enable ruby-debug.'
+  end
+  separator ''
+  option :startup do
+    short '-s'
+    long '--startup'
+    desc 'Startup file to load.'
+    desc 'Defaults to "lib/startup.rb"'
+  end
+end
+Waves::Server.run( Choice.choices )

data/lib/controllers/base.rb

@@ -0,0 +1,11 @@
+module Waves
+  module Controllers
+    class Base
+
+      include Waves::Controllers::Mixin
+
+      def attributes; params[model_name.singular.intern]; end
+
+    end
+  end
+end

data/lib/controllers/mixin.rb

@@ -1,131 +1,159 @@
 module Waves
-  
+
   #
-  # Controllers in Waves are simply classes that provide a request / response context for operating on a model. While models are essentially just a way to manage data in an application, controllers manage data in response to a request. For example, a controller updates a model instance using parameters from the request.
+  # Controllers in Waves are simply classes that provide a request / response
+  # context for operating on a model. While models are essentially just a way
+  # to manage data in an application, controllers manage data in response to
+  # a request. For example, a controller updates a model instance using
+  # parameters from the request.
   #
-  # Controller methods simply return data (a resource), if necessary, that can be then used by views to determine how to render that data. Controllers do not determine which view will be invoked. They are independent of the view; one controller method might be suitable for several different views. In some cases, controllers can choose to directly modify the response and possibly even short-circuit the view entirely. A good example of this is a redirect.
+  # Public controller methods simply return data (a resource), if necessary, that
+  # can be then used by views to determine how to render that data.
+  # Controllers do not determine which view will be invoked. They are
+  # independent of the view; one controller method might be suitable for
+  # several different views. In some cases, controllers can choose to
+  # directly modify the response and possibly even short-circuit the view
+  # entirely. A good example of this is a redirect.
   #
-  # Controllers, like Views and Mappings, use the Waves::ResponseMixin to provide a rich context for working with the request and response objects. They can even call other controllers or views using the controllers method. In addition, they provide some basic reflection (access to the model and model_name that corresponds to the class name for the given model) and automatic parameter destructuring. This allows controller methods to access the request parameters as a hash, so that a POST variable named <tt>entry.title</tt> is accessed as <tt>params[:entry][:title]</tt>.
+  # Controllers, like Views and Mappings, use the Waves::ResponseMixin to
+  # provide a rich context for working with the request and response objects.
+  # They can even call other controllers or views using the controllers method.
+  # In addition, they provide some basic reflection (access to the model and
+  # model_name that corresponds to the class name for the given model) and
+  # automatic parameter destructuring. This allows controller methods to access
+  # the request parameters as a hash, so that a POST variable named
+  # <tt>entry.title</tt> is accessed as <tt>params[:entry][:title]</tt>.
   #
-  # Controllers often do not have to be explicitly defined. Instead, one or more default controllers can be defined that are used as exemplars for a given model. By default, the +waves+ command generates a single default, placed in the application's <tt>controllers/default.rb</tt> file. This can be modified to change the default behavior for all controllers. Alternatively, the <tt>rake generate:controller</tt> command can be used to explicitly define a controller.
+  # Controllers often do not have to be explicitly defined. Instead, one or more
+  # default controllers can be defined that are used as exemplars for a given
+  # model. By default, the +waves+ command generates a single default, placed in
+  # the application's <tt>controllers/default.rb</tt> file. This can be modified
+  # to change the default behavior for all controllers. Alternatively, the
+  # <tt>rake generate:controller</tt> command can be used to explicitly define a
+  # controller.
   #
   # As an example, the code for the default controller is below for the Blog application.
   #
   #   module Blog
-  #   	module Controllers
-  #   		class Default
+  #     module Controllers
+  #       class Default
   #
   #         # Pick up the default controller methods, like param, url, etc.
-  #   			include Waves::Controllers::Mixin
+  #         include Waves::Controllers::Mixin
   #
   #         # This gets me the parameters associated with this model
-  #   			def attributes; params[model_name.singular.intern]; end
+  #         def attributes; params[model_name.singular.intern]; end
   #
   #         # A simple generic delegator to the model
-  #   			def all; model.all; end
+  #         def all; model.all; end
   #
   #         # Find a specific instance based on a name or raise a 404
-  #   			def find( name ); model[ :name => name ] or not_found; end
+  #         def find( name ); model[ :name => name ] or not_found; end
   #
   #         # Create a new instance based on the request params
-  #   			def create; model.create( attributes ); end
+  #         def create; model.create( attributes ); end
   #
   #         # Update an existing record. find will raise a 404 if not found.
-  #   			def update( name )
-  #   			  instance = find( name )
-  #   			  instance.set( attributes )
-  #   			  instance.save_changes
-  #   			end
+  #         def update( name )
+  #           instance = find( name )
+  #           instance.set( attributes )
+  #           instance.save_changes
+  #         end
   #
   #         # Find and delete - or will raise a 404 if it doesn't exist
-  #   			def delete( name ); find( name ).destroy; end
+  #         def delete( name ); find( name ).destroy; end
   #
-  #   		end
-  #   	end
+  #       end
+  #     end
   #   end
   #
-  # Since the mapping file handles "glueing" controllers to views, controllers don't have to be at all concerned with views. They don't have to set instance variables, layouts, or contain logic to select the appropriate view based on the request. All they do is worry about updating the model when necessary based on the request.  
+  # Since the mapping file handles "glueing" controllers to views, controllers
+  # don't have to be at all concerned with views. They don't have to set
+  # instance variables, layouts, or contain logic to select the appropriate
+  # view based on the request. All they do is worry about updating the model
+  # when necessary based on the request.
 
-	module Controllers
+  module Controllers
 
     #
-	  # This mixin provides some handy methods for Waves controllers. You will probably
-	  # want to include it in any controllers you define for your application. The default
-	  # controllers generated using the +wave+ command already do this.
-	  #
-	  # Basically, what the mixin does is adapt the class so that it can be used within
-	  # mappings (see Waves::Mapping); add some simple reflection to allow controller methods
-	  # to be written generically (i.e., without reference to a specific model); and provide
-	  # parameter destructuring for the request parameters.
-	  #
-
-		module Mixin
-		  
-			attr_reader :request
-			
-			include Waves::ResponseMixin
-
-      # When you include this Mixin, a +process+ class method is added to your class, 
-      # which accepts a request object and a block. The request object is used to initialize
-      # the controller and the block is evaluated using +instance_eval+. This allows the
-      # controller to be used within a mapping file.
-      
-			def self.included( c )
-				def c.process( request, &block )
-					self.new( request ).instance_eval( &block )
-				end
-			end
-				
-			def initialize( request ); @request = request; end
-			
-			# The params variable is taken from the request object and "destructured", so that
-			# a parameter named 'blog.title' becomes:
-			#
-			#   params['blog']['title']
-			#
-			# If you want to access the original parameters object, you can still do so using
-			# +request.parameters+ instead of simply +params+.
-			def params; @params ||= destructure(request.params); end
-			
-			# You can access the name of the model related to this controller using this method.
-			# It simply takes the basename of the module and converts it to snake case, so if the
-			# model uses a different plurality, this won't, in fact, be the model name.
-			def model_name; self.class.basename.snake_case; end
-			
-			# This uses the model_name method to attempt to identify the model corresponding to this
-			# controller. This allows you to write generic controller methods such as:
-			#
-			#   model.find( name )
-			#
-			# to find an instance of a given model. Again, the plurality of the controller and 
-			# model must be the same for this to work.
-			def model; Waves.application.models[ model_name.intern ]; end
-			
-			private
-			
-			def destructure(hash)
-				rval = {}
-				hash.keys.map{ |key|key.split('.') }.each do |keys|
-					destructure_with_array_keys(hash,'',keys,rval)
-				end
-				rval
-			end
-			
-			def destructure_with_array_keys(hash,prefix,keys,rval)
-				if keys.length == 1
-					val = hash[prefix+keys.first]
-					rval[keys.first.intern] = case val
-				  when String then val.strip
-			    when Hash then val
-			    end
-				else
-					rval = ( rval[keys.first.intern] ||= {} )
-					destructure_with_array_keys(hash,(keys.shift<<'.'),keys,rval)
-				end
-			end
-										
-		end
-	
-	end
-
-end
+    # Waves::Controllers::Mixin adapts a controller class for use in mappings and provides utility methods.     
+    # It is included in controllers autocreated by the Default foundation, so you do not need to include
+    # it in subclasses of the same. 
+    #
+    # The utility methods include simple reflection to allow controller methods
+    # to be written generically (i.e., without reference to a specific model) and
+    # parameter destructuring for the request parameters.
+    #
+
+    module Mixin
+
+      attr_reader :request
+
+      include Waves::ResponseMixin
+
+      # When this mixin is included it adds a class method named +process+,
+      # which accepts a request object and a block. The +process+ method initializes the
+      # controller with the request, then evaluates the block using +instance_eval+. This allows the
+      # controller to be used from within a mapping lambda (i.e. a ResponseProxy).
+
+      def self.included( mod )
+        def mod.process( request, &block )
+          self.new( request ).instance_eval( &block )
+        end
+      end
+
+      def initialize( request )
+        @request = request
+      end
+
+      # The params variable is taken from the request object and "destructured", so that
+      # a parameter named 'blog.title' becomes:
+      #
+      #   params['blog']['title']
+      #
+      # If you want to access the original parameters object, you can still do so using
+      # +request.params+ instead of simply +params+.
+      def params; @params ||= destructure(request.params); end
+
+      # Returns the name of the model corresponding to this controller by taking the basename
+      # of the module and converting it to snake case. If the model plurality is different than
+      # the controller, this will not, in fact, be the model name.
+      def model_name; self.class.basename.snake_case; end
+
+      # Returns the model corresponding to this controller by naively assuming that 
+      # +model_name+ must be correct. This allows you to write generic controller methods such as:
+      #
+      #   model.find( name )
+      #
+      # to find an instance of a given model. Again, the plurality of the controller and
+      # model must be the same for this to work.
+      def model; Waves.application.models[ model_name.intern ]; end
+
+      private
+
+      def destructure(hash)
+        rval = {}
+        hash.keys.map{ |key|key.split('.') }.each do |keys|
+          destructure_with_array_keys(hash,'',keys,rval)
+        end
+        rval
+      end
+
+      def destructure_with_array_keys(hash,prefix,keys,rval)
+        if keys.length == 1
+          val = hash[prefix+keys.first]
+          rval[keys.first.intern] = case val
+          when String then val.strip
+          when Hash then val
+          end
+        else
+          rval = ( rval[keys.first.intern] ||= {} )
+          destructure_with_array_keys(hash,(keys.shift<<'.'),keys,rval)
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/dispatchers/base.rb

@@ -1,52 +1,67 @@
 module Waves
 
-	module Dispatchers
-
-	  class NotFoundError < Exception ; end
-		
-		class Redirect < Exception 
-			attr_reader :path
-			def initialize( path )
-				@path = path
-			end
-		end
-		
-		# The Base dispatcher simply makes it easier to write dispatchers by inheriting
-		# from it. It creates a Waves request, ensures the request processing is done
-		# within a mutex, benchmarks the request processing, logs it, and handles common 
-		# exceptions and redirects. Derived classes need only process the request within 
-		# their +safe+ method, which takes a Waves::Request and returns a Waves::Response.
-		
-		class Base
-				
-			# Like any Rack application, Waves' dispatchers must provide a call method
-			# taking an +env+ parameter. 
-			def call( env )
-			  Waves::Server.synchronize do
-  				request = Waves::Request.new( env )
-  				response = request.response
-  			  t = Benchmark.realtime do 
-    				begin
-    					safe( request )
-    				rescue Dispatchers::Redirect => redirect
-    					response.status = '302'
-    					response.location = redirect.path
-    				rescue Dispatchers::NotFoundError => e
-    					html = Waves.application.views[:errors].process( request ) do
-    				    not_found_404( :error => e ) 
-    				  end
-    					response.status = '404'
-    					response.content_type = 'text/html'
-    					response.write( html )
-    				end
-    			end
-      		Waves::Logger.info "#{request.method}: #{request.url} handled in #{(t*1000).round} ms."
-  				response.finish
-  			end
-  		end
-
-		end
-
-	end	
-	
-end
+  module Dispatchers
+
+    # A NotFoundError means what you think it means.  The dispatchers included with Waves do not
+    # natively intercept this exception.  Instead an exception handler must be registered in the application
+    # mappings.  The Simple foundation registers a minimal handler, while the Default foundation registers
+    # a slightly fleshier one.
+    class NotFoundError < Exception ; end
+
+    # Redirect exceptions are rescued by the Waves dispatcher and used to set the 
+    # response status and location.
+    class Redirect < Exception
+      attr_reader :path, :status
+      def initialize( path, status = '302' )
+        @path = path
+        @status = status
+      end
+    end
+
+    # Waves::Dispatchers::Base provides the basic request processing structure.
+    # All other Waves dispatchers should inherit from it.  It creates a Waves request, 
+    # determines whether to enclose the request processing in a mutex, benchmarks it, 
+    # logs it, and handles common exceptions and redirects. Derived classes need only 
+    # process the request within the +safe+ method, which must take a Waves::Request and return a Waves::Response.
+
+    class Base
+
+      # As with any Rack application, a Waves dispatcher must provide a call method
+      # that takes an +env+ parameter.
+      def call( env )
+        if Waves.config.synchronize?
+          Waves::Application.instance.synchronize { _call( env ) }
+        else
+          _call( env )
+        end
+      end
+
+      # Called by event driven servers like thin and ebb. Returns true if
+      # the server should run the request in a separate thread, as determined by
+      # Configurations::Mapping#threaded?
+      def deferred?( env )
+        Waves::Application.instance.mapping.threaded?( env )
+      end
+      
+      private
+      
+      def _call( env )
+        request = Waves::Request.new( env )
+        response = request.response
+        t = Benchmark.realtime do
+          begin
+            safe( request )
+          rescue Dispatchers::Redirect => redirect
+            response.status = redirect.status
+            response.location = redirect.path
+          end
+        end
+        Waves::Logger.info "#{request.method}: #{request.url} handled in #{(t*1000).round} ms."
+        response.finish
+      end
+
+    end
+
+  end
+
+end

data/lib/dispatchers/default.rb

@@ -1,54 +1,81 @@
 module Waves
-	
-	module Dispatchers
-	
-	  #
-	  # The default dispatcher essentially checks the application's mapping to see
-	  # what to do with the request URL. It checks before and after filters (wrap
-	  # filters are just a combination of both) as well as path and url mappings.
-	  # 
-	  # The default dispatcher also attempts to set the content type based on the 
-	  # MIME type implied by any file extension used in the request URL using Mongrel's
-	  # MIME types YAML file.
-	  #
-	  # You can write your own dispatcher and use it in your application's configuration 
-	  # file. By default, they use the default dispatcher, like this:
-	  #
-	  #   application do
-		#	    use Rack::ShowExceptions
-		#	    run Waves::Dispatchers::Default.new
-		#   end
-		#				
-    
-		class Default < Base
-		
-		  # All dispatchers using the Dispatchers::Base to provide thread-safety, logging, etc.
-		  # must provide a +safe+ method to handle creating a response from a request.
-		  # Takes a Waves::Request and returns a Waves::Reponse
-			def safe( request  )
-			  
-				response = request.response
-		
-				Waves::Server.reload if Waves::Server.debug?
-				response.content_type = Waves::Server.config.mime_types[ request.path ] || 'text/html'
-
-				mapping = Waves::Server.mapping[ request ]
-
-				mapping[:before].each do | block, args |
-				  ResponseProxy.new(request).instance_exec(*args,&block)
-				end
-			
-				block, args = mapping[:action]
-				response.write( ResponseProxy.new(request).instance_exec(*args, &block) )
-
-				mapping[:after].each do | block, args |
-				  ResponseProxy.new(request).instance_exec(*args,&block)
-				end
-  													
-			end
-			
-		end
-		
-	end
-		
+
+  module Dispatchers
+
+    #
+    # Waves::Dispatchers::Default matches requests against an application's mappings to 
+    # determine what main action to take, as well as what before, after, always, and exception-handling
+    # blocks must run.
+    #
+    # The default dispatcher also attempts to set the content type based on the
+    # file extension used in the request URL. It does this using the class defined in
+    # the current configuration's +mime_types+ attribute, which defaults to Mongrel's
+    # MIME type handler.
+    #
+    # You can write your own dispatcher and use it in your application's configuration
+    # file. By default, they use the default dispatcher, like this:
+    #
+    #   application do
+    #     use Rack::ShowExceptions
+    #     run Waves::Dispatchers::Default.new
+    #   end
+    #
+
+    class Default < Base
+
+      # All dispatchers using the Dispatchers::Base to provide thread-safety, logging, etc.
+      # must provide a +safe+ method to handle creating a response from a request.
+      # Takes a Waves::Request and returns a Waves::Reponse
+      def safe( request  )
+
+        response = request.response
+
+        Waves::Application.instance.reload if Waves::Application.instance.debug?
+        response.content_type = Waves::Application.instance.config.mime_types[ request.path ] || 'text/html'
+
+        mapping = Waves::Application.instance.mapping[ request ]
+
+        begin
+
+          mapping[:before].each do | block, args |
+            ResponseProxy.new(request).instance_exec(*args,&block)
+          end
+
+          request.not_found unless mapping[:action]
+
+          block, args = mapping[:action]
+          response.write( ResponseProxy.new(request).instance_exec(*args, &block) )
+          
+          mapping[:after].each do | block, args |
+            ResponseProxy.new(request).instance_exec(*args,&block)
+          end
+
+        rescue Exception => e
+          
+          handler = mapping[:handlers].detect do | exception, block, args |
+            e.is_a? exception
+          end
+          if handler
+            ResponseProxy.new(request).instance_exec(*handler[2], &handler[1])
+          else
+            raise e
+          end
+          
+        ensure
+          mapping[:always].each do | block, args |
+            begin
+              ResponseProxy.new(request).instance_exec(*args,&block) 
+            rescue Exception => e
+              Waves::Logger.info e.to_s
+            end
+          end
+          
+        end
+
+      end
+
+    end
+
+  end
+
 end