strelka 0.0.1pre4 → 0.0.1.pre129

data/lib/strelka/app/router.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+require 'pluginfactory'
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+require 'strelka/mixins'
+
+# Abstract base class for pluggable routing strategies for the Routing
+# plugin.
+#
+# This class can't be instantiated itself, but it does act as a factory for
+# loading and instantiating its subclasses:
+#
+#     # Create an instance of the default router strategy with the given
+#     # routes and options.
+#     Strelka::App::Router.create( 'default', routes, options )
+#
+# To define your own strategy, you'll need to inherit this class, name it
+# <tt>Strelka::App::{Something}Router</tt>, save it in a file named
+# <tt>strelka/app/{something}router.rb</tt>, and be sure to override the
+# #add_route and #route_request methods.
+class Strelka::App::Router
+	include PluginFactory,
+	        Strelka::Loggable,
+			Strelka::AbstractClass
+
+	### PluginFactory API -- return the Array of directories to search for plugins.
+	def self::derivative_dirs
+		return ['strelka/app']
+	end
+
+
+	### Create a new router that will route requests according to the specified
+	### +routes+.
+	###
+	### If the optional +options+ hash is specified, it is passed to the router
+	### strategy.
+	def initialize( routes=[], options={} )
+		routes.each do |tuple|
+			self.log.debug "  adding route: %p" % [ tuple ]
+			self.add_route( *tuple )
+		end
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# :call-seq:
+	#   add_route( http_verb, path_array, routing_info )
+	#
+	# Add a route for the specified +http_verb+, +path_array+, and +routing_info+. The
+	# +http_verb+ will be one of the methods from
+	# {RFC 2616}[http://tools.ietf.org/html/rfc2616#section-9] as a Symbol (e.g.,
+	# +:GET+, +:DELETE+). The +path_array+ will be the route path split up by
+	# path separator. The +routing_info+ is a Hash that contains the action
+   	# that will be run when the route matches, routing options, and any other
+	# routing information associated with the route.
+	pure_virtual :add_route
+
+
+	##
+	# :call-seq:
+	#   route_request( request )
+	#
+	# Determine the most-specific route for the specified +request+ and return
+	# the routing info Hash.
+	pure_virtual :route_request
+
+end # class Strelka::App::Router

data/lib/strelka/app/routing.rb

@@ -2,11 +2,81 @@
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
-require 'strelka/app/defaultrouter' unless defined?( Strelka::App::DefaultRouter )
 
+require 'strelka/app/router'
+require 'strelka/exceptions'
 require 'strelka/app/plugins'
 
-# Default routing logic for Strelka::Apps
+# Sinatra-ish routing logic for Strelka::Apps
+#
+# This plugin adds the ability to declare hooks for requests based on their
+# attributes. The default router (Strelka::App::DefaultRouter) uses only the
+# HTTP verb and the path, but you can also define your own router class if
+# you want to include other attributes.
+#
+# You declare a hook using the HTTP verb, followed by the path, followed by
+# a Hash of options and a block that will be called when a matching request
+# is handled.
+#
+# When two or more hooks match the same request, the most-specific match
+# wins. The mongrel2 route part of the path is stripped before comparing.
+#
+# The hooks are given a Strelka::Request object, and are expected to
+# return either a Strelka::Response or something that can be made
+# into one.
+#
+# == Examples
+#
+#   class HelloWorld < Strelka::App
+#
+#       plugins :routing
+#
+#       # match any GET request
+#       get do |req|
+#           return req.response << 'Hello, World!'
+#       end
+#
+#       # match any GET request whose path starts with '/goodbye'
+#       get '/goodbye' do |req|
+#           return req.response << "Goodbye, cruel World!"
+#       end
+#
+#
+#   end # class HelloWorld
+#
+# == Routing Strategies
+#
+# The algorithm used to map requests to routes are defined by an object
+# that implements the Strategy pattern. These routing strategies are pluggable,
+# so if Mongrel2's the "longest-match wins" routing isn't to your taste,
+# you can specify a different one using the +router+ declaration. Strelka
+# comes with one alternative "exclusive" router that implements a more
+# restrictive mapping:
+#
+#   class ExclusiveHelloWorld < Strelka::App
+#
+#       plugins :routing
+#       router :exclusive
+#
+#       # match a GET request for the exact route only
+#       get do |req|
+#           return req.response << 'Hello, World!'
+#       end
+#
+#       # only match a GET request for '/goodbye'
+#       get '/goodbye' do |req|
+#           return req.response << "Goodbye, cruel World!"
+#       end
+#
+#      # Every other request responds with a 404
+#
+#   end # class ExclusiveHelloWorld
+#
+# == Custom Routers
+#
+# See the Strelka::App::Router for information on how to define your own
+# routing strategies.
+#
 module Strelka::App::Routing
 	extend Strelka::App::Plugin
 	include Strelka::Loggable,
@@ -16,20 +86,35 @@ module Strelka::App::Routing
 
 
 	# Class methods to add to classes with routing.
-	module ClassMethods
+	module ClassMethods # :nodoc:
 
 		# 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
+		# The name of the routing strategy class to use
 		attr_accessor :routerclass
-		@routerclass = Strelka::App::DefaultRouter
+		@routerclass = :default
 
 
 		### Return a Hash of the methods defined by routes.
 		def route_methods
-			return self.instance_methods.grep( /^#{HTTP::RFC2616_VERB_REGEX}\b/ )
+			return self.instance_methods.grep( /^#{HTTP::RFC2616_VERB_REGEX}(_|$)/ )
+		end
+
+
+		### Returns +true+ if the app has a route for the specified +verb+ and +path+.
+		def has_route?( http_verb, path )
+			path_pattern = self.split_route_pattern( path )
+			self.routes.find {|tuple| tuple[0] == http_verb && tuple[1] == path_pattern }
+		end
+
+
+		# OPTIONS GET HEAD POST PUT DELETE TRACE CONNECT
+
+		### Define a route for the OPTIONS verb and the given +pattern+.
+		def options( pattern='', options={}, &block )
+			self.add_route( :OPTIONS, pattern, options, &block )
 		end
 
 
@@ -45,10 +130,34 @@ module Strelka::App::Routing
 		end
 
 
+		### Define a route for the PUT verb and the given +pattern+.
+		def put( pattern='', options={}, &block )
+			self.add_route( :PUT, pattern, options, &block )
+		end
+
+
+		### Define a route for the DELETE verb and the given +pattern+.
+		def delete( pattern='', options={}, &block )
+			self.add_route( :DELETE, pattern, options, &block )
+		end
+
+
+		### Define a route for the TRACE verb and the given +pattern+.
+		def trace( pattern='', options={}, &block )
+			self.add_route( :TRACE, pattern, options, &block )
+		end
+
+
+		### Define a route for the CONNECT verb.
+		def connect( options={}, &block )
+			self.add_route( :CONNECT, '', 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 ]
+				Strelka.log.info "%p router class set to: %p" % [ self, newclass ]
 				self.routerclass = newclass
 			end
 
@@ -82,9 +191,19 @@ module Strelka::App::Routing
 			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 ]
+			# Remove any existing route for the same verb, patternparts, and options
+			# (support for overriding inherited routes)
+			self.routes.delete_if do |r|
+				r[0] == verb && r[1] == patternparts && r[2][:options] == options
+			end
+
+			# Now add all the parts to the routes array for the router created by
+			# instances
+			self.routes << [
+				verb,
+				patternparts,
+				{:action => self.instance_method(methodname), :options => options}
+			]
 		end
 
 
@@ -93,12 +212,12 @@ module Strelka::App::Routing
 			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 ]
+					raise ScriptError,
+						"parameter-based routing not supported without a 'parameters' plugin" unless
+						self.respond_to?( :extract_route_from_constraint )
+					self.extract_route_from_constraint( component )
 				else
 					component
 				end
@@ -118,7 +237,7 @@ module Strelka::App::Routing
 	### Create a new router object for each class with Routing.
 	def initialize( * )
 		super
-		@router ||= self.class.routerclass.new( self.class.routes )
+		@router ||= Strelka::App::Router.create( self.class.routerclass, self.class.routes )
 	end
 
 
@@ -128,8 +247,11 @@ module Strelka::App::Routing
 
 	### Dispatch the request using the Router.
 	def handle_request( request, &block )
-		if handler = self.router.route_request( request )
-			return handler.bind( self ).call( request )
+		if route = self.router.route_request( request )
+			# Track which route was chosen for later plugins
+			request.notes[:routing][:route] = route
+			# Bind the action of the route and call it
+			return route[:action].bind( self ).call( request, &block )
 		else
 			finish_with HTTP::NOT_FOUND, "The requested resource was not found on this server."
 		end

data/lib/strelka/app/templating.rb

@@ -13,11 +13,12 @@ module Strelka::App::Templating
 	include Strelka::Constants
 	extend Strelka::App::Plugin
 
-	run_before :routing, :filters
+	run_before :routing, :negotiation
+	run_after :filters
 
 
 	# Class methods to add to classes with templating.
-	module ClassMethods
+	module ClassMethods # :nodoc:
 
 		# The map of template names to template file paths.
 		@template_map = {}
@@ -100,7 +101,7 @@ module Strelka::App::Templating
 	### 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
+	### In all three of these cases, the return value will be a Mongrel2::Response 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.
 	###
@@ -111,6 +112,7 @@ module Strelka::App::Templating
 	### 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
 
@@ -145,6 +147,13 @@ module Strelka::App::Templating
 			template = l_template
 		end
 
+		# Set some default stuff on the top-level template
+		template.request          = request
+		template.strelka_version  = Strelka.version_string( true )
+		template.mongrel2_version = Mongrel2.version_string( true )
+		template.route            = request.notes[:routing][:route]
+
+		# Now render the response body
 		self.log.debug "  rendering the template into the response body"
 		response.body = template.render
 		response.status ||= HTTP::OK

data/lib/strelka/app.rb

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+require 'rubygems' # For the Rubygems API
+
 require 'mongrel2/handler'
 require 'strelka' unless defined?( Strelka )
 
@@ -14,13 +16,147 @@ class Strelka::App < Mongrel2::Handler
 	include Strelka::App::Plugins
 
 
-	@default_content_type = nil
+	# Glob for matching Strelka apps relative to a gem's data directory
+	APP_GLOB_PATTERN = '{apps,handlers}/**/*'
+
+
+	# Class instance variables
+	@default_type = nil
+	@loading_file = nil
+	@subclasses   = Hash.new {|h,k| h[k] = [] }
+
+
+	# The Hash of Strelka::App subclasses, keyed by the Pathname of the file they were 
+	# loaded from, or +nil+ if they weren't loaded via ::load.
+	class << self; attr_reader :subclasses; end
+
+
+	### Inheritance callback -- add subclasses to @subclasses so .load can figure out which
+	### classes correspond to which files.
+	def self::inherited( subclass )
+		super
+		@subclasses[ @loading_file ] << subclass if self == Strelka::App
+	end
+
+
+	### Overridden from Mongrel2::Handler -- use the value returned from .default_appid if
+	### one is not specified, and automatically install the config DB if it hasn't been
+	### already.
+	def self::run( appid=nil )
+		appid ||= self.default_appid
+
+		Strelka.logger.level = Logger::DEBUG if $VERBOSE
+
+		super( appid )
+
+	end
+
+
+	### Calculate a default application ID for the class based on either its ID 
+	### constant or its name and return it.
+	def self::default_appid
+		Strelka.log.info "Looking up appid for %p" % [ self.class ]
+		appid = nil
+
+		if self.const_defined?( :ID )
+			appid = self.const_get( :ID )
+			Strelka.log.info "  app has an ID: %p" % [ appid ]
+		else
+			appid = ( self.name || "anonymous#{self.object_id}" ).downcase
+			appid.gsub!( /[^[:alnum:]]+/, '-' )
+			Strelka.log.info "  deriving one from the class name: %p" % [ appid ]
+		end
+
+		return appid
+	end
+
+
+	### Return a Hash of Strelka app files as Pathname objects from installed gems,
+	### keyed by gemspec name .
+	def self::discover_paths
+		appfiles = {}
+
+		# Find all the gems that depend on Strelka
+		gems = Gem::Specification.find_all do |gemspec|
+			gemspec.dependencies.find {|dep| dep.name == 'strelka'}
+		end
+
+		Strelka.log.debug "Found %d gems with a Strelka dependency" % [ gems.length ]
+
+		# Find all the files under those gems' data directories that match the application
+		# pattern
+		gems.sort.reverse.each do |gemspec|
+			# Only look at the latest version of the gem
+			next if appfiles.key?( gemspec.name )
+			appfiles[ gemspec.name ] = []
+
+			Strelka.log.debug "  checking %s for apps in its datadir" % [ gemspec.name ]
+			pattern = File.join( gemspec.full_gem_path, "data", gemspec.name, APP_GLOB_PATTERN )
+			Strelka.log.debug "    glob pattern is: %p" % [ pattern ]
+			gemapps = Pathname.glob( pattern )
+			Strelka.log.debug "    found %d app files" % [ gemapps.length ]
+			appfiles[ gemspec.name ] += gemapps
+		end
+
+		return appfiles
+	end
+
+
+	### Return an Array of Strelka::App classes loaded from the installed Strelka gems.
+	def self::discover
+		discovered_apps = []
+		app_paths = self.discover_paths
+
+		Strelka.log.debug "Loading apps from %d discovered paths" % [ app_paths.length ]
+		app_paths.each do |gemname, paths|
+			Strelka.log.debug "  loading gem %s" % [ gemname ]
+			gem( gemname )
+
+			Strelka.log.debug "  loading apps from %s: %d handlers" % [ gemname, paths.length ]
+			paths.each do |path|
+				classes = begin
+					Strelka::App.load( path )
+				rescue StandardError, ScriptError => err
+					Strelka.log.error "%p while loading Strelka apps from %s: %s" %
+						[ err.class, path, err.message ]
+					Strelka.log.debug "Backtrace: %s" % [ err.backtrace.join("\n\t") ]
+					[]
+				end
+				Strelka.log.debug "  loaded app classes: %p" % [ classes ]
+
+				discovered_apps += classes
+			end
+		end
+
+		return discovered_apps
+	end
+
+
+	### Load the specified +file+, and return any Strelka::App subclasses that are loaded
+	### as a result.
+	def self::load( file )
+		Strelka.log.debug "Loading application/s from %p" % [ file ]
+		@loading_file = Pathname( file ).expand_path
+		self.subclasses.delete( @loading_file )
+		Kernel.load( @loading_file.to_s )
+		new_subclasses = self.subclasses[ @loading_file ]
+		Strelka.log.debug "  loaded %d new app class/es" % [ new_subclasses.size ]
+
+		return new_subclasses
+	ensure
+		@loading_file = nil
+	end
+
+
+	#
+	# :section: Application declarative methods
+	#
 
 	### Get/set the Content-type of requests that don't set one. Leaving this unset will
 	### leave the Content-type unset.
-	def self::default_content_type( newtype=nil )
-		@default_content_type = newtype if newtype
-		return @default_content_type
+	def self::default_type( newtype=nil )
+		@default_type = newtype if newtype
+		return @default_type
 	end
 
 
@@ -32,17 +168,28 @@ class Strelka::App < Mongrel2::Handler
 	public
 	######
 
+	### Run the app -- overriden to set the process name to something interesting.
+	def run
+		procname = "%p %s" % [ self.class, self.conn ]
+		$0 = procname
+
+		super
+	end
+
+
 	### The main Mongrel2 entrypoint -- accept Strelka::Requests and return
 	### Strelka::Responses.
 	def handle( request )
 		response = nil
 
-		# Run fixup hooks on the request
-		request = self.fixup_request( request )
-
 		# Dispatch the request after allowing plugins to to their thing
 		status_info = catch( :finish ) do
+
+			# Run fixup hooks on the request
+			request = self.fixup_request( request )
 			response = self.handle_request( request )
+			response = self.fixup_response( response )
+
 			nil # rvalue for the catch
 		end
 
@@ -50,23 +197,15 @@ class Strelka::App < Mongrel2::Handler
 		if status_info
 			self.log.debug "Preparing a status response: %p" % [ status_info ]
 			return self.prepare_status_response( request, status_info )
-
-		# Normal response
-		else
-			self.log.debug "Preparing a regular response: %p" % [ response ]
-			response ||= request.response
-			return self.fixup_response( request, response )
 		end
 
+		return response
 	rescue => err
-		# Propagate Spec failures
-		raise if err.class.name =~ /^RSpec::/
-
 		msg = "%s: %s %s" % [ err.class.name, err.message, err.backtrace.first ]
 		self.log.error( msg )
 		err.backtrace[ 1..-1 ].each {|frame| self.log.debug('  ' + frame) }
 
-		status_info = { :status => HTTP::SERVER_ERROR, :message => msg }
+		status_info = { :status => HTTP::SERVER_ERROR, :message => 'internal server error' }
 		return self.prepare_status_response( request, status_info )
 	end
 
@@ -105,24 +244,35 @@ class Strelka::App < Mongrel2::Handler
 	### Mongrel and return it. This is an alternate extension-point for plugins that 
 	### wish to modify or replace the response after the whole request cycle is
 	### completed.
-	def fixup_response( request, response )
+	def fixup_response( response )
 		self.log.debug "Fixing up response: %p" % [ response ]
 		self.fixup_response_content_type( response )
-		self.fixup_head_response( response ) if request.verb == :HEAD
+		self.fixup_head_response( response ) if
+			response.request && response.request.verb == :HEAD
 		self.log.debug "  after fixup: %p" % [ response ]
 
-		super
+		return super
 	end
 
 
 	### If the +response+ doesn't yet have a Content-type header, and the app has
-	### defined a default (via App.default_content_type), set it to the default.
+	### defined a default (via App.default_type), set it to the default.
 	def fixup_response_content_type( response )
+
+		# Make the error for returning something other than a Response object a little
+		# nicer.
+		unless response.respond_to?( :content_type )
+			self.log.error "expected response (%p, a %p) to respond to #content_type" %
+				[ response, response.class ]
+			finish_with( HTTP::SERVER_ERROR, "malformed response" )
+		end
+
 		restype = response.content_type
 
 		if !restype
-			if (( default = self.class.default_content_type ))
-				self.log.debug "Setting default content type"
+			if (( default = self.class.default_type ))
+				self.log.debug "Setting content type of the response to the default: %p" %
+					[ default ]
 				response.content_type = default
 			else
 				self.log.debug "No default content type"
@@ -164,7 +314,7 @@ class Strelka::App < Mongrel2::Handler
 		# Some status codes allow explanatory text to be returned; some forbid it. Append the
 		# message for those that allow one.
 		unless request.verb == :HEAD || HTTP::BODILESS_HTTP_RESPONSE_CODES.include?( status_code )
-			response.content_type = 'text/plain'
+			response.content_type = status_info[ :content_type ] || 'text/plain'
 			response.puts( message )
 		end
 

data/lib/strelka/constants.rb

@@ -11,14 +11,6 @@ module Strelka::Constants
 	# Import Mongrel2's constants, too
 	include Mongrel2::Constants
 
-	# Override the path to the default Sqlite configuration database
-	# remove_const( :DEFAULT_CONFIG_URI )
-	DEFAULT_CONFIG_URI = 'strelka.sqlite'
-
-	# The admin server port
-	DEFAULT_ADMIN_PORT = 7337
-
-
 	# Extend Mongrel2's HTTP constants collection
 	module HTTP
 		include Mongrel2::Constants::HTTP
@@ -35,18 +27,6 @@ module Strelka::Constants
 		# The list of HTTP verbs considered "idempotent"
 		IDEMPOTENT_RFC2616_VERBS = %w[OPTIONS GET HEAD PUT DELETE TRACE]
 
-		# A registry of HTTP status codes that don't allow an entity body 
-		# in the response.
-		BODILESS_HTTP_RESPONSE_CODES = [
-			CONTINUE,
-			SWITCHING_PROTOCOLS,
-			PROCESSING,
-			NO_CONTENT,
-			RESET_CONTENT,
-			NOT_MODIFIED,
-			USE_PROXY,
-		]
-
 	end # module HTTP
 
 end # module Strelka::Constants

data/lib/strelka/exceptions.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/ruby
+#encoding: utf-8
+
+# Exception types used by Strelka classes.
+
+#--
+module Strelka
+
+	# A base exception class.
+	class Error < ::RuntimeError; end
+
+	# An exception that's raised when there's a problem with a Request.
+	class RequestError < Error
+		### Create a new RequestError for the specified +request+ object.
+		def initialize( request, message, *args )
+			@request = request
+			super( message, *args )
+		end
+
+		# The request that caused the exception
+		attr_reader :request
+
+	end # class RequestError
+
+	# An exception raised when there is a problem with an application plugin.
+	class PluginError < Error; end
+
+end # module Strelka
+