strelka 0.0.1pre4

data/lib/strelka/app/filters.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+
+# Request/response filters plugin for Strelka::App.
+module Strelka::App::Filters
+	extend Strelka::App::Plugin
+
+	run_before :routing
+
+	### Class methods to add to classes with routing.
+	module ClassMethods
+
+		# Default filters hash
+		@filters = { :request => [], :response => [], :both => [] }
+
+		# The list of filters
+		attr_reader :filters
+
+
+		### Get/set the router class to use for mapping requests to handlers to +newclass.
+		def filter( which=:both, &block )
+			which = which.to_sym
+			raise ArgumentError, "invalid filter stage %p; expected one of: %p" %
+				[ which, self.filters.keys ] if !self.filters.key?( which )
+			self.filters[ which ] << block
+		end
+
+
+		### Return filters which should be applied to requests, i.e., those with a +which+ of
+		### :request or :both.
+		def request_filters
+			return self.filters[ :request ] + self.filters[ :both ]
+		end
+
+
+		### Return filters which should be applied to responses, i.e., those with a +which+ of
+		### :response or :both.
+		def request_filters
+			return self.filters[ :both ] + self.filters[ :response ]
+		end
+
+	end # module ClassMethods
+
+
+	### Apply filters to the given +request+ before yielding back to the App, then apply
+	### filters to the response that comes back.
+	def handler( request )
+		self.apply_request_filters( request )
+		response = super
+		self.apply_response_filters( response )
+	end
+
+
+	### Apply :request and :both filters to +request+.
+	def apply_request_filters( request )
+		self.class.request_filters.each {|filter| filter.call(request) }
+	end
+
+
+	### Apply :both and :response filters to +response+.
+	def apply_response_filters( response )
+		self.class.response_filters.each {|filter| filter.call(response) }
+	end
+
+end # module Strelka::App::Filters
+
+

data/lib/strelka/app/parameters.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+# Parameter declaration for Strelka::Apps
+module Strelka::App::Parameters
+	extend Strelka::App::Plugin
+
+	### Class methods to add to classes with routing.
+	module ClassMethods
+
+		# Pattern for matching route parameters
+		PARAMETER_PATTERN = %r{/:(?<paramname>[a-z]\w*)}i
+
+		# Param defaults
+		PARAMETER_DEFAULT_OPTIONS = {
+			:constraint  => //,
+			:required    => false,
+			:untaint     => false,
+			:description => nil,
+		}
+
+
+		# Default parameters hash
+		@parameters = {}
+
+		# The hash of declared parameters
+		attr_reader :parameters
+
+
+		### Declare a parameter with the specified +name+ that will be validated using the given
+		### +regexp+.
+		def param( name, regexp=nil, *flags )
+			Strelka.log.debug "New param %p" % [ name ]
+			name = name.to_sym
+
+			regexp = Regexp.compile( "(?<#{name}>" + regexp.to_s + ")" ) unless
+				regexp.names.include?( name.to_s )
+			Strelka.log.debug "  param constraint is: %p" % [ regexp ]
+
+			options = PARAMETER_DEFAULT_OPTIONS.dup
+			options[ :constraint ] = regexp
+			options[ :required ]   = true if flags.include?( :required )
+			options[ :untaint ]    = true if flags.include?( :untaint )
+			Strelka.log.debug "  param options are: %p" % [ options ]
+
+			self.parameters[ name ] = options
+		end
+
+
+		### Inheritance hook -- inheriting classes inherit their parents' parameter
+		### declarations, too.
+		def inherited( subclass )
+			super
+			subclass.instance_variable_set( :@parameters, self.parameters.dup )
+		end
+
+	end # module ClassMethods
+
+
+end # module Strelka::App::Parameters
+
+

data/lib/strelka/app/plugins.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+# Pluggable functionality mixin for Strelka::App.
+class Strelka::App
+
+	# The Hash of loaded plugin modules, keyed by their downcased and symbolified 
+	# name (e.g., Strelka::App::Templating => :templating)
+	class << self; attr_reader :loaded_plugins; end
+	@loaded_plugins = {}
+
+
+	# Plugin Module extension -- adds registration, sorting, etc.
+	module Plugin
+		include Comparable
+
+		### Mixin hook -- extend including objects instead.
+		def self::included( mod )
+			mod.extend( self )
+		end
+
+		### Extension hook -- Extend the given object with methods for setting it 
+		### up as a plugin for Strelka::Apps.
+		def self::extend_object( object )
+			Strelka.log.debug "Extending %p as a Strelka::App::Plugin" % [ object ]
+
+			super
+			name = object.plugin_name
+			object.instance_variable_set( :@load_order, {:before => [], :after => []} )
+
+			Strelka.log.debug "  adding %p (%p) to the plugin registry" % [ name, object ]
+			Strelka::App.loaded_plugins[ name ] = object
+		end
+
+
+		#############################################################
+		###	A P P E N D E D   M E T H O D S
+		#############################################################
+
+		# An Array of Arrays that tracks which plugins should be installed before and after
+		# itself, in that order.
+		attr_reader :load_order
+
+
+		### Comparable operator -- use the plugin load_order to compare Plugin modules.
+		def <=>( other_plugin )
+			if self.before?( other_plugin ) || other_plugin.after?( self )
+				return -1
+			elsif self.after?( other_plugin ) || other_plugin.before?( self )
+				return 1
+			else
+				return 0
+			end
+		end
+
+
+		### Returns true if the receiver has specified that it should run before +other_plugin+.
+		def before?( other_plugin )
+			return self.load_order[ :before ].include?( other_plugin.plugin_name )
+		end
+
+
+		### Returns true if the receiver has specified that it should run after +other_plugin+.
+		def after?( other_plugin )
+			return self.load_order[ :after ].include?( other_plugin.plugin_name )
+		end
+
+
+		### Return the name of the receiving plugin 
+		def plugin_name
+			name = self.name || "anonymous#{self.object_id}"
+			name.sub!( /.*::/, '' )
+			return name.downcase.to_sym
+		end
+
+
+		### Register the receiver as needing to be run before +other_plugins+ for requests, and 
+		### *after* them for responses.
+		def run_before( *other_plugins )
+			self.load_order[:before] += other_plugins
+		end
+
+
+		### Register the receiver as needing to be run after +other_plugins+ for requests, and 
+		### *before* them for responses.
+		def run_after( *other_plugins )
+			self.load_order[:after] += other_plugins
+		end
+
+	end # module Plugin
+
+
+	# Plugin system
+	module Plugins
+
+		### Inclusion callback -- add class methods and instance variables without 
+		### needing a separate call to #extend.
+		def self::included( klass )
+			klass.extend( ClassMethods )
+			super
+		end
+
+
+		### Extension callback -- add instance variables to extending objects.
+		def self::extended( object )
+			super
+			object.instance_variable_set( :@plugins, {} )
+		end
+
+
+		### Class methods to add to classes with plugins.
+		module ClassMethods
+
+			### Load the plugin with the given +name+, or nil if 
+			def load_plugin( name )
+
+				# Just return Modules as-is
+				return name if name.is_a?( Strelka::App::Plugin )
+
+				unless mod = Strelka::App.loaded_plugins[ name.to_sym ]
+					Strelka.log.debug "Loading plugin from strelka/app/#{name}"
+					require "strelka/app/#{name}"
+					mod = Strelka::App.loaded_plugins[ name.to_sym ] or
+						raise "#{name} plugin didn't load correctly."
+				end
+
+				return mod
+			end
+
+
+			### Install the plugin +mod+ in the receiving class.
+			def install_plugin( mod )
+				Strelka.log.debug "  adding %p to %p" % [ mod, self ]
+				include( mod )
+
+				if mod.const_defined?( :ClassMethods )
+					cm_mod = mod.const_get(:ClassMethods)
+					Strelka.log.debug "  adding class methods from %p" % [ cm_mod ]
+
+					extend( cm_mod )
+					cm_mod.instance_variables.each do |ivar|
+						Strelka.log.debug "  copying class instance variable %s" % [ ivar ]
+						ival = cm_mod.instance_variable_get( ivar )
+
+						# Don't duplicate modules/classes or immediates
+						case ival
+						when Module, TrueClass, FalseClass, Symbol, Numeric, NilClass
+							instance_variable_set( ivar, ival )
+						else
+							instance_variable_set( ivar, ival.dup )
+						end
+					end
+				end
+			end
+
+
+			### Load the plugins with the given +names+ and install them.
+			def plugins( *names )
+				# Load the associated Plugin Module objects
+				mods = names.flatten.collect {|name| self.load_plugin(name) }.sort
+
+				# Now install them in reverse order, as the ancestry array should have them
+				# in LIFO order
+				mods.reverse.each {|mod| self.install_plugin(mod) }
+			end
+			alias_method :plugin, :plugins
+
+		end # module ClassMethods
+
+
+		#
+		# :section: Extension Points
+		#
+
+		### The main extension-point for the plugin system. Strelka::App supers to this method
+		### with a block that processes the actual request, and the plugins implement this
+		### method to add their own functionality. 
+		def handle_request( request, &block )
+			raise LocalJumpError,
+				"no block given; plugin supering without preserving arguments?" unless block
+			return block.call( request )
+		end
+
+
+		### An alternate extension-point for the plugin system. Plugins can implement this method
+		### to alter or replace the +request+ before the regular request/response cycle begins.
+		def fixup_request( request )
+			return request
+		end
+
+
+		### An alternate extension-point for the plugin system. Plugins can implement this method
+		### to alter or replace the +response+ to the specified +request+ after the regular 
+		### request/response cycle is finished.
+		def fixup_response( request, response )
+			return response
+		end
+
+	end # module Plugins
+
+end # class Strelka::App
+
+

data/lib/strelka/app/routing.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+require 'strelka/app/defaultrouter' unless defined?( Strelka::App::DefaultRouter )
+
+require 'strelka/app/plugins'
+
+# Default routing logic for Strelka::Apps
+module Strelka::App::Routing
+	extend Strelka::App::Plugin
+	include Strelka::Loggable,
+	        Strelka::Constants
+
+	run_after :templating, :filters, :parameters
+
+
+	# Class methods to add to classes with routing.
+	module ClassMethods
+
+		# The list of routes to pass to the Router when the application is created
+		attr_reader :routes
+		@routes = []
+
+		# The class of object to instantiate for routing
+		attr_accessor :routerclass
+		@routerclass = Strelka::App::DefaultRouter
+
+
+		### Return a Hash of the methods defined by routes.
+		def route_methods
+			return self.instance_methods.grep( /^#{HTTP::RFC2616_VERB_REGEX}\b/ )
+		end
+
+
+		### Define a route for the GET verb and the given +pattern+.
+		def get( pattern='', options={}, &block )
+			self.add_route( :GET, pattern, options, &block )
+		end
+
+
+		### Define a route for the POST verb and the given +pattern+.
+		def post( pattern='', options={}, &block )
+			self.add_route( :POST, pattern, options, &block )
+		end
+
+
+		### Get/set the router class to use for mapping requests to handlers to +newclass.
+		def router( newclass=nil )
+			if newclass
+				Strelka.log.info "%p will use the %p router" % [ self, newclass ]
+				self.routerclass = newclass
+			end
+
+			return self.routerclass
+		end
+
+
+		### Define a route method for the specified +verb+ and +pattern+ with the
+		### specified +options+, and the +block+ as its body.
+		def add_route( verb, pattern, options={}, &block )
+
+			# Start the name of the route method with the HTTP verb, then split the
+			# route pattern into its components
+			methodparts = [ verb.upcase ]
+			patternparts = self.split_route_pattern( pattern )
+			Strelka.log.debug "Split pattern %p into parts: %p" % [ pattern, patternparts ]
+
+			# Make a method name from the directories and the named captures of the patterns 
+			# in the route
+			patternparts.each do |part|
+				if part.is_a?( Regexp )
+					methodparts << '_' + part.names.join( '_' )
+				else
+					methodparts << part
+				end
+			end
+			Strelka.log.debug "  route methodname parts are: %p" % [ methodparts ]
+			methodname = methodparts.join( '_' )
+
+			# Define the method using the block from the route as its body
+			Strelka.log.debug "  adding route method %p for %p route: %p" % [ methodname, verb, block ]
+			define_method( methodname, &block )
+
+			# Now add all the parts to the routes array for the router created by 
+			# instances 
+			self.routes << [ verb, patternparts, self.instance_method(methodname), options ]
+		end
+
+
+		### Split the given +pattern+ into its path components and 
+		def split_route_pattern( pattern )
+			pattern.slice!( 0, 1 ) if pattern.start_with?( '/' )
+
+			return pattern.split( '/' ).collect do |component|
+				# Map patterns to their parameter constraint regex
+				if component.start_with?( ':' )
+					Strelka.log.debug "  searching for a param for %p" % [ component ]
+					param = self.parameters[ component[1..-1].to_sym ] or
+						raise ScriptError, "no parameter %p defined" % [ component ]
+					param[ :constraint ]
+				else
+					component
+				end
+			end
+		end
+
+
+		### Inheritance hook -- inheriting classes inherit their parents' routes table.
+		def inherited( subclass )
+			super
+			subclass.instance_variable_set( :@routes, self.routes.dup )
+		end
+
+	end # module ClassMethods
+
+
+	### Create a new router object for each class with Routing.
+	def initialize( * )
+		super
+		@router ||= self.class.routerclass.new( self.class.routes )
+	end
+
+
+	# The App's router object
+	attr_reader :router
+
+
+	### Dispatch the request using the Router.
+	def handle_request( request, &block )
+		if handler = self.router.route_request( request )
+			return handler.bind( self ).call( request )
+		else
+			finish_with HTTP::NOT_FOUND, "The requested resource was not found on this server."
+		end
+	end
+
+end # module Strelka::App::Routing
+
+

data/lib/strelka/app/templating.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+
+require 'inversion'
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+require 'strelka/app/plugins'
+
+
+# Templating plugin for Strelka::Apps.
+module Strelka::App::Templating
+	include Strelka::Constants
+	extend Strelka::App::Plugin
+
+	run_before :routing, :filters
+
+
+	# Class methods to add to classes with templating.
+	module ClassMethods
+
+		# The map of template names to template file paths.
+		@template_map = {}
+		attr_reader :template_map
+
+		@layout_template = nil
+		attr_accessor :layout_template
+
+
+		### Get/set the templates declared for the App. 
+		def templates( newhash=nil )
+			if newhash
+				self.template_map.merge!( newhash )
+			end
+
+			return self.template_map
+		end
+
+
+		### Declare a template that will act as a wrapper for all other templates
+		def layout( tmplpath=nil )
+			self.layout_template = tmplpath if tmplpath
+			return self.layout_template
+		end
+
+	end # module ClassMethods
+
+
+	### Preload any templates registered with the template map.
+	def initialize( * )
+		super
+		@template_map = self.load_template_map
+		@layout = self.load_layout_template
+	end
+
+
+	######
+	public
+	######
+
+	# The map of template names to Inversion::Template instances.
+	attr_reader :template_map
+
+	# The layout template (an Inversion::Template), if one was declarted
+	attr_reader :layout
+
+
+	### Return the template keyed by the given +name+.
+	### :TODO: Add auto-reloading, 
+	def template( name )
+		template = self.template_map[ name ] or
+			raise ArgumentError, "no %p template registered!" % [ name ]
+		template.reload if template.changed?
+		return template.dup
+	end
+
+
+	### Load instances for all the template paths specified in the App's class
+	### and return them in a hash keyed by name (Symbol).
+	def load_template_map
+		return self.class.template_map.inject( {} ) do |map, (name, path)|
+			map[ name ] = Inversion::Template.load( path )
+			map
+		end
+	end
+
+
+	### Load an Inversion::Template for the layout template and return it if one was declared.
+	### If none was declared, returns +nil+.
+	def load_layout_template
+		return nil unless ( lt_path = self.class.layout_template )
+		return Inversion::Template.load( lt_path )
+	end
+
+
+	### Intercept responses on the way back out and turn them into a Mongrel2::HTTPResponse
+	### with a String for its entity body. It will take action if the response is one of:
+	###
+	### 1. A Mongrel2::Response with an Inversion::Template as its body.
+	### 2. An Inversion::Template by itself.
+	### 3. A Symbol that matches one of the keys of the registered templates.
+	###
+	### In all three of these cases, the return value will be a Mongrel2::Request with a
+	### body set to the rendered value of the template in question, and with its status
+	### set to '200 OK' unless it is already set to something else.
+	###
+	### If there is a registered layout template, and any of the three cases is true, the
+	### layout template is loaded, its #body attributes set to the content template,
+	### and its rendered output set as the body of the response instead.
+	###
+	### Every other response is returned without modification.
+	def handle_request( request, &block )
+		response = super
+		self.log.debug "Templating: examining %p response." % [ response.class ]
+		template = nil
+
+		# Response is a template name
+		if response.is_a?( Symbol ) && self.template_map.key?( response )
+			self.log.debug "  response is a template name (Symbol); using the %p template" % [ response ]
+			template = self.template( response )
+			response = request.response
+
+		# Template object
+		elsif response.is_a?( Inversion::Template )
+			self.log.debug "  response is an %p; wrapping it in a Response object" % [ response.class ]
+			template = response
+			response = request.response
+
+		# Template object already in a Response
+		elsif response.is_a?( Mongrel2::Response ) && response.body.is_a?( Inversion::Template )
+			template = response.body
+			self.log.debug "  response is a %p in the body of a %p" % [ template.class, response.class ]
+
+		# Not templated; returned as-is
+		else
+			self.log.debug "  response isn't templated; returning it as-is"
+			return response
+		end
+
+		# Wrap the template in a layout if there is one
+		if self.layout
+			l_template = self.layout.dup
+			self.log.debug "  wrapping response in layout %p" % [ l_template ]
+			l_template.body = template
+			template = l_template
+		end
+
+		self.log.debug "  rendering the template into the response body"
+		response.body = template.render
+		response.status ||= HTTP::OK
+
+		return response
+	end
+
+end # module Strelka::App::Templating
+
+