strelka 0.0.1pre4 → 0.0.1.pre129

data/lib/strelka/app/defaultrouter.rb

@@ -2,26 +2,24 @@
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
+require 'strelka/app/router'
 
 # Simple (dumb?) request router for Strelka::App-based applications.
-class Strelka::App::DefaultRouter
+class Strelka::App::DefaultRouter < Strelka::App::Router
 	include Strelka::Loggable
 
-	### Create a new router that will route requests according to the specified 
+	### Create a new router that will route requests according to the specified
 	### +routes+. Each route is a tuple of the form:
 	###
 	###   [
 	###     <http_verb>,    # The HTTP verb as a Symbol (e.g., :GET, :POST, etc.)
 	###     <path_array>,   # An Array of the parts of the path, as Strings and Regexps.
-	###     <action>,       # A #to_proc-able object to invoke when the route is matched
-	###     <options_hash>, # The hash of route config options
+	###     <route>,        # A hash of routing data built by the Routing plugin
 	###   ]
-	def initialize( routes=[] )
-		@routes = Hash.new {|routes, verb| routes[verb] = {} }
-		routes.each do |tuple|
-			self.log.debug "  adding route: %p" % [ tuple ]
-			self.add_route( *tuple )
-		end 
+	def initialize( routes=[], options={} )
+		@routes = Hash.new {|hash, verb| hash[verb] = {} }
+
+		super
 	end
 
 
@@ -35,27 +33,57 @@ class Strelka::App::DefaultRouter
 
 	### Add a route for the specified +verb+, +path+, and +options+ that will return
 	### +action+ when a request matches them.
-	def add_route( verb, path, action, options={} )
-		re = Regexp.compile( path.join('/') )
+	def add_route( verb, path, route )
+		re = Regexp.compile( '^' + path.join('/') )
 
-		# Make the Hash for the specified HTTP verb if it hasn't been 
-		self.routes[ verb ][ re ] = { :options => options, :action => action }
+		# Add the route keyed by HTTP verb and the path regex
+		self.routes[ verb ][ re ] = route
 	end
 
 
 	### Determine the most-specific route for the specified +request+ and return
-	### the #to_proc-able object that handles it.
+	### the UnboundMethod object of the App that should handle it.
 	def route_request( request )
+		route = nil
 		verb = request.verb
 		path = request.app_path || ''
-		route = nil
-
-		# Strip the leading '/'
-		path.slice!( 0, 1 ) if path.start_with?( '/' )
+		path.slice!( 0, 1 ) if path.start_with?( '/' ) # Strip the leading '/'
 
+		self.log.debug "Looking for a route for: %p %p" % [ verb, path ]
 		verbroutes = @routes[ verb ] or return nil
-		longestmatch = verbroutes.keys.inject( nil ) do |longestmatch, pattern|
-			self.log.debug "Matching pattern %p; longest match so far: %p" %
+		match = self.find_longest_match( verbroutes.keys, path ) or return nil
+		self.log.debug "  longest match result: %p" % [ match ]
+
+		# The best route is the one with the key of the regexp of the
+		# longest match
+		route = verbroutes[ match.regexp ].merge( :match => match )
+
+		# Inject the parameters that are part of the route path (/foo/:id) into
+		# the parameters hash. They'll be the named match-groups in the matching
+		# Regex.
+		route_params = match.names.inject({}) do |hash,name|
+			hash[ name ] = match[ name ]
+			hash
+		end
+
+		# Add routing information to the request, and merge parameters if there are any
+		request.params.merge!( route_params ) unless route_params.empty?
+
+		# Return the routing data that should be used
+		return route
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Find the longest match in +patterns+ for the given +path+ and return the MatchData
+	### object for it. Returns +nil+ if no match was found.
+	def find_longest_match( patterns, path )
+
+		return patterns.inject( nil ) do |longestmatch, pattern|
+			self.log.debug "  trying pattern %p; longest match so far: %p" %
 				[ pattern, longestmatch ]
 
 			# If the pattern doesn't match, keep the longest match and move on to the next
@@ -71,15 +99,6 @@ class Strelka::App::DefaultRouter
 			longestmatch
 		end
 
-		# If there wasn't a match, abort
-		return nil unless longestmatch
-
-		# The best route is the one with the key of the regexp of the 
-		# longest match
-		route = verbroutes[ longestmatch.regexp ]
-
-		# Bind the method to the app and 
-		return route[:action]
 	end
 
 end # class Strelka::App::DefaultRouter

data/lib/strelka/app/errors.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+
+# Custom error-handling plugin for Strelka::App.
+#
+# == Examples
+#
+# Handle statuses via a callback:
+#
+#    class MyApp < Strelka::App
+#        plugins :errors
+#
+#        on_status HTTP::NOT_FOUND do |res|
+#        end
+#
+#    end # class MyApp
+#
+# With the templating plugin, you can also handle it via a custom template.
+#
+#    class MyApp < Strelka::App
+#        plugins :errors, :templating
+#
+#        layout 'layout.tmpl'
+#        templates :missing => 'errors/missing.tmpl'
+#
+#        on_status HTTP::NOT_FOUND, :missing
+#
+#    end # class MyApp
+#
+module Strelka::App::Errors
+	extend Strelka::App::Plugin
+
+	DEFAULT_HANDLER_STATUS_RANGE = 400..599
+
+	run_before :routing
+
+
+	# Class-level functionality
+	module ClassMethods # :nodoc:
+
+		@status_handlers = {}
+
+		# The registered status handler callbacks, keyed by numeric HTTP status code
+		attr_reader :status_handlers
+
+
+		### Register a callback for responses that have the specified +status_code+.
+		### :TODO: Document all the stuff.
+		def on_status( range=DEFAULT_HANDLER_STATUS_RANGE, template=nil, &block )
+			range = Range.new( range, range ) unless range.is_a?( Range )
+			methodname = "for_status_%s" % [ range.begin, range.end ].uniq.join('_to_')
+
+			if template
+				raise ArgumentError, "template-style callbacks don't take a block" if block
+				raise ScriptError, "template-style callbacks require the :templating plugin" unless
+					self.respond_to?( :templates )
+
+				block = Proc.new {|*| template }
+			end
+
+			define_method( methodname, &block )
+
+			self.status_handlers[ range ] = instance_method( methodname )
+		end
+
+	end # module ClassMethods
+
+
+	### Check for a status response that is hooked, and run the hook if one is found.
+	def handle_request( request )
+		response = nil
+
+		# Catch a finish_with; the status_response will only be non-nil
+		status_response = catch( :finish ) do
+			response = super
+			nil
+		end
+
+		# If the app or any plugins threw a finish, look for a handler for the status code
+		# and call it if one is found.
+		if status_response
+			response = request.response
+			status = status_response[:status]
+			self.log.info "Handling a status response: %d" % [ status ]
+
+			# If we can't find a custom handler for this status, re-throw
+			# to the default handler instead
+			handler = self.status_handler_for( status ) or
+				throw( :finish, status_response )
+
+			# The handler is an UnboundMethod, so bind it to the app instance
+			# and call it
+			response.status = status
+			response = handler.bind( self ).call( response, status_response )
+		end
+
+		return response
+	end
+
+
+	### Find a status handler for the given +status_code+ and return it as an UnboundMethod.
+	def status_handler_for( status_code )
+		self.log.debug "Looking for a status handler for %d responses" % [ status_code ]
+		handlers = self.class.status_handlers
+		ranges = handlers.keys
+
+		ranges.each do |range|
+			return handlers[ range ] if range.include?( status_code )
+		end
+
+		return nil
+	end
+
+
+end # module Strelka::App::Errors
+
+
+

data/lib/strelka/app/exclusiverouter.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strela/app' unless defined?( Strelka::App )
+
+require 'strelka/app/defaultrouter'
+
+# Alternative (stricter) router strategy for Strelka::App::Routing plugin.
+#
+# == Examples
+#
+#     class MyApp < Strelka::App
+#         plugins :routing
+#         router :exclusive
+#
+#         # Unlike the default router, this route will *only* respond to
+#         # a request that matches the app's route with no additional path.
+#         get '' do
+#             # ...
+#         end
+#
+#     end # class MyApp
+#
+class Strelka::App::ExclusiveRouter < Strelka::App::DefaultRouter
+	include Strelka::Loggable
+
+	######
+	public
+	######
+
+	### Add a route for the specified +verb+, +path+, and +options+ that will return
+	### +action+ when a request matches them.
+	def add_route( verb, path, route )
+		re = Regexp.compile( '^' + path.join('/') + '$' )
+
+		# Make the Hash for the specified HTTP verb if it hasn't been created already
+		self.routes[ verb ][ re ] = route
+	end
+
+end # class Strelka::App::DefaultRouter

data/lib/strelka/app/filters.rb

@@ -8,10 +8,11 @@ require 'strelka/app' unless defined?( Strelka::App )
 module Strelka::App::Filters
 	extend Strelka::App::Plugin
 
-	run_before :routing
+	run_before :routing, :templating
 
-	### Class methods to add to classes with routing.
-	module ClassMethods
+
+	# Class methods to add to classes with routing.
+	module ClassMethods # :nodoc:
 
 		# Default filters hash
 		@filters = { :request => [], :response => [], :both => [] }
@@ -38,7 +39,7 @@ module Strelka::App::Filters
 
 		### Return filters which should be applied to responses, i.e., those with a +which+ of
 		### :response or :both.
-		def request_filters
+		def response_filters
 			return self.filters[ :both ] + self.filters[ :response ]
 		end
 
@@ -47,22 +48,32 @@ module Strelka::App::Filters
 
 	### Apply filters to the given +request+ before yielding back to the App, then apply
 	### filters to the response that comes back.
-	def handler( request )
+	def handle_request( request )
 		self.apply_request_filters( request )
 		response = super
 		self.apply_response_filters( response )
+
+		return response
 	end
 
 
 	### Apply :request and :both filters to +request+.
 	def apply_request_filters( request )
-		self.class.request_filters.each {|filter| filter.call(request) }
+		self.log.debug "Applying request filters:"
+		self.class.request_filters.each do |filter|
+			self.log.debug "  filter: %p" % [ filter ]
+			filter.call( request )
+		end
 	end
 
 
 	### Apply :both and :response filters to +response+.
 	def apply_response_filters( response )
-		self.class.response_filters.each {|filter| filter.call(response) }
+		self.log.debug "Applying response filters:"
+		self.class.response_filters.each do |filter|
+			self.log.debug "  filter: %p" % [ filter ]
+			filter.call( response )
+		end
 	end
 
 end # module Strelka::App::Filters

data/lib/strelka/app/negotiation.rb

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/app' unless defined?( Strelka::App )
+
+require 'strelka/constants'
+require 'strelka/httprequest/negotiation'
+require 'strelka/httpresponse/negotiation'
+
+
+# HTTP Content negotiation for Strelka applications.
+#
+# The application can test the request for which types are accepted, set
+# different response blocks for different acceptable content types, provides 
+# tranformations for entity bodies and set transformations for new content
+# types.
+#
+#   class UserService < Strelka::App
+#
+#       plugins :routing, :negotiation
+#
+#       add_content_type :tnetstring, 'text/x-tnetstring' do |response|
+#           tnetstr = nil
+#           begin
+#               tnetstr = TNetString.dump( response.body )
+#           rescue => err
+#               self.log.error "%p while transforming entity body to a TNetString: %s" %
+#                   [ err.class, err.message ]
+#               return false
+#           else
+#               response.body = tnetstr
+#               response.content_type = 'text/x-tnetstring'
+#               return true
+#           end
+#       end
+#
+#   end # class UserService
+#
+module Strelka::App::Negotiation
+	include Strelka::Constants
+	extend Strelka::App::Plugin
+
+	run_before :routing
+	run_after  :filters, :templating, :parameters
+
+
+	# Class methods to add to classes with content-negotiation.
+	module ClassMethods # :nodoc:
+
+		# Content-type tranform registry, keyed by name
+		@content_type_transforms = {}
+		attr_reader :content_type_transforms
+
+		# Content-type transform names, keyed by mimetype
+		@transform_names = {}
+		attr_reader :transform_names
+
+
+		### Define a new media-type associated with the specified +name+ and +mimetype+. Responses
+		### whose requests accept content of the given +mimetype+ will pass their response to the
+		### specified +transform_block+, which should re-write the response's entity body if it can
+		### transform it to its mimetype. If it successfully does so, it should return +true+, else
+		### the next-best mimetype's transform will be called, etc.
+		def add_content_type( name, mimetype, &transform_block )
+			self.transform_names[ mimetype ] = name
+			self.content_type_transforms[ name ] = transform_block
+		end
+
+	end # module ClassMethods
+
+
+	### Extension callback -- extend the HTTPRequest and HTTPResponse classes with Negotiation 
+	### support when this plugin is loaded.
+	def self::included( object )
+		Strelka.log.debug "Extending Request and Response with Negotiation mixins"
+		Strelka::HTTPRequest.class_eval { include Strelka::HTTPRequest::Negotiation }
+		Strelka::HTTPResponse.class_eval { include Strelka::HTTPResponse::Negotiation }
+		super
+	end
+
+
+	### Start content-negotiation when the response has returned.
+	def handle_request( request )
+		response = super
+		response.negotiate
+
+		return response
+	end
+
+
+	### Check to be sure the response is acceptable after the request is handled.
+	def fixup_response( response )
+		response = super
+
+		# Ensure the response is acceptable; if it isn't respond with the appropriate
+		# status.
+		unless response.acceptable?
+			body = self.make_not_acceptable_body( response )
+			finish_with( HTTP::NOT_ACCEPTABLE, body ) # throw
+		end
+
+		return response
+	end
+
+
+	### Create an HTTP entity body describing the variants of the given response.
+	def make_not_acceptable_body( response )
+		# :TODO: Unless it was a HEAD request, the response SHOULD include
+		# an entity containing a list of available entity characteristics and
+		# location(s) from which the user or user agent can choose the one
+		# most appropriate. The entity format is specified by the media type
+		# given in the Content-Type header field. Depending upon the format
+		# and the capabilities of the user agent, selection of the most
+		# appropriate choice MAY be performed automatically. However, this
+		# specification does not define any standard for such automatic
+		# selection. [RFC2616]
+		return "No way to respond given the requested acceptance criteria."
+	end
+
+end # module Strelka::App::Negotiation
+
+

data/lib/strelka/app/parameters.rb

@@ -2,13 +2,53 @@
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
-
-# Parameter declaration for Strelka::Apps
+require 'strelka/app/plugins'
+require 'strelka/app/paramvalidator'
+
+
+# Parameter validation and untainting for Strelka apps.
+#
+# The application can declare parameters globally, and then override them on a
+# per-route basis:
+# 
+# 	class UserManager < Strelka::App
+# 
+#       plugins :routing, :parameters
+# 
+# 		param :username, /\w+/, "User login", :required
+#       param :email
+# 		param :id, /\d+/, "The user's numeric ID"
+#       param :mode, ['add', 'remove']
+# 
+# 		# :username gets validated and merged into query args; URI parameters
+# 		# clobber query params
+# 		get '/info/:username', :params => { :id => /[XRT]\d{4}-\d{8}/ } do |req|
+# 			req.params.okay?
+# 			req.params[:username]
+# 			req.params.values_at( :id, :username )
+# 			req.params.username
+# 
+# 			req.params.error_messages
+# 		end
+# 
+# 	end # class UserManager
+# 
+#
+# == To-Do
+# 
+# _We may add support for other ways of passing parameters later,
+# e.g., via structured entity bodies like JSON, XML, YAML, etc_.
+# 
+# 
 module Strelka::App::Parameters
 	extend Strelka::App::Plugin
 
-	### Class methods to add to classes with routing.
-	module ClassMethods
+	run_before :routing
+	run_after :filters
+
+
+	# Class methods to add to classes with routing.
+	module ClassMethods # :nodoc:
 
 		# Pattern for matching route parameters
 		PARAMETER_PATTERN = %r{/:(?<paramname>[a-z]\w*)}i
@@ -17,38 +57,110 @@ module Strelka::App::Parameters
 		PARAMETER_DEFAULT_OPTIONS = {
 			:constraint  => //,
 			:required    => false,
-			:untaint     => false,
 			:description => nil,
 		}
 
+		# Pattern to use to strip binding operators from parameter patterns so they
+		# can be used in the middle of routing Regexps.
+		PARAMETER_PATTERN_STRIP_RE = Regexp.union( '^', '$', '\\A', '\\z', '\\Z' )
+
+		# Options that are passed as Symbols to .param
+		FLAGS = [ :required, :untaint ]
+
 
 		# Default parameters hash
 		@parameters = {}
+		@untaint_all_constraints = false
 
 		# The hash of declared parameters
 		attr_reader :parameters
 
+		# The flag for untainting constrained parameters that match their constraints
+		attr_writer :untaint_all_constraints
+
 
 		### Declare a parameter with the specified +name+ that will be validated using the given
-		### +regexp+.
-		def param( name, regexp=nil, *flags )
+		### +constraint+. The +constraint+ can be any of the types supported by 
+		### Strelka::App::ParamValidator.
+		### :call-seq:
+		#   param( name, *flags )
+		#   param( name, constraint, *flags )
+		#   param( name, description, *flags )
+		#   param( name, constraint, description, *flags )
+		def param( name, *args )
 			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 ]
-
+			# Consume the arguments
+			constraint = args.shift unless args.first.is_a?( String ) || FLAGS.include?( args.first )
+			constraint ||= name
+			description = args.shift if args.first.is_a?( String )
+			# description ||= name.to_s.capitalize
+			flags = args
+
+			# Give a regexp constraint a named capture group for the constraint name if it 
+			# doesn't already have one
+			if constraint.is_a?( Regexp )
+				constraint = Regexp.compile( "(?<#{name}>" + constraint.to_s + ")" ) unless
+					constraint.names.include?( name.to_s )
+				Strelka.log.debug "  regex constraint is: %p" % [ constraint ]
+			end
+
+			# Merge the param into the parameters hash
 			options = PARAMETER_DEFAULT_OPTIONS.dup
-			options[ :constraint ] = regexp
-			options[ :required ]   = true if flags.include?( :required )
-			options[ :untaint ]    = true if flags.include?( :untaint )
+			options[ :constraint ]  = constraint
+			options[ :description ] = description
+			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
 
 
+		### Get/set the untainting flag. If set, all parameters which match their constraints
+		### will also be untainted.
+		def untaint_all_constraints( newval=nil )
+			Strelka.log.debug "Untaint all constraints: %p:%p" % [ newval, @untaint_all_constraints ]
+			@untaint_all_constraints = newval unless newval.nil?
+			return @untaint_all_constraints
+		end
+
+
+		### Turn the constraint associated with +name+ into a routing component.
+		def extract_route_from_constraint( name )
+			name.slice!( 0, 1 ) if name.start_with?( ':' )
+			Strelka.log.debug "  searching for a param for %p" % [ name ]
+			param = self.parameters[ name.to_sym ] or
+				raise ScriptError, "no parameter %p defined" % [ name ]
+
+			# Munge the constraint into a Regexp
+			constraint = param[ :constraint ]
+			re = case constraint
+				when Regexp
+					constraint
+				when Array
+					sub_res = constraint.map( &self.method(:extract_route_from_constraint) )
+					Regexp.union( sub_res )
+				when Symbol
+					re = Strelka::App::ParamValidator.pattern_for_constraint( constraint ) or
+						raise ScriptError, "no pattern for %p constraint" % [ constraint ]
+					/(?<#{name}>#{re})/
+				else
+					raise ScriptError,
+						"can't route on a parameter with a %p constraint %p" % [ constraint.class ]
+				end
+
+			# Unbind the pattern from beginning or end of line.
+			# :TODO: This is pretty ugly. Find a better way of modifying the regex.
+			re_str = re.to_s.
+				sub( %r{\(\?[\-mix]+:(.*)\)}, '\\1' ).
+				gsub( PARAMETER_PATTERN_STRIP_RE, '' )
+
+			return Regexp.new( re_str, re.options )
+		end
+
+
 		### Inheritance hook -- inheriting classes inherit their parents' parameter
 		### declarations, too.
 		def inherited( subclass )
@@ -59,6 +171,51 @@ module Strelka::App::Parameters
 	end # module ClassMethods
 
 
+
+	### Add a ParamValidator to the given +request+ before passing it on.
+	def handle_request( request, &block )
+		profile = self.make_validator_profile( request )
+		self.log.debug "Applying validator profile: %p" % [ profile ]
+		validator = Strelka::App::ParamValidator.new( profile, request.params )
+		self.log.debug "  validator: %p" % [ validator ]
+
+		request.params = validator
+		super
+	end
+
+
+
+	### Make a validator profile for Strelka::App::ParamValidator for the specified
+	### +request+ using the declared parameters in the App, returning it as a Hash.
+	def make_validator_profile( request )
+		profile = {
+			:required     => [],
+			:optional     => [],
+			:descriptions => {},
+			:constraints  => {},
+			:untaint_constraint_fields => [],
+			:untaint_all_constraints => self.class.untaint_all_constraints,
+		}
+
+		self.log.debug "Validator profile is: %p" % [ profile ]
+
+		return self.class.parameters.inject( profile ) do |accum, (name, opts)|
+			self.log.debug "  adding parameter: %p: %p" % [ name, opts ]
+			if opts[:required]
+				accum[:required] << name
+			else
+				accum[:optional] << name
+			end
+
+			accum[:untaint_constraint_fields] << name if opts[:untaint]
+			accum[:descriptions][ name ] = opts[:description] if opts[:description]
+			accum[:constraints][ name ] = opts[:constraint]
+
+			accum
+		end
+	end
+
+
 end # module Strelka::App::Parameters