strelka 0.0.1pre4

data/lib/strelka/app.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+
+require 'mongrel2/handler'
+require 'strelka' unless defined?( Strelka )
+
+
+# The application base class.
+class Strelka::App < Mongrel2::Handler
+	include Strelka::Loggable,
+	        Strelka::Constants
+
+	# Load the plugin system
+	require 'strelka/app/plugins'
+	include Strelka::App::Plugins
+
+
+	@default_content_type = nil
+
+	### 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
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	######
+	public
+	######
+
+	### 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
+			response = self.handle_request( request )
+			nil # rvalue for the catch
+		end
+
+		# Status response
+		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
+
+	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 }
+		return self.prepare_status_response( request, status_info )
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Make any changes to the +request+ that are necessary before handling it and 
+	### return it. This is an alternate extension-point for plugins that 
+	### wish to modify or replace the request before the request cycle is
+	### started.
+	def fixup_request( request )
+		self.log.debug "Fixing up request: %p" % [ request ]
+		request = super
+		self.log.debug "  after fixup: %p" % [ request ]
+
+		return request
+	end
+
+
+	### Handle the request and return a +response+. This is the main extension-point
+	### for the plugin system. Without being overridden or extended by plugins, this
+	### method just returns the default Mongrel2::HTTPRequest#response.
+	def handle_request( request, &block )
+		self.log.debug "Strelka::App#handle_request"
+		if block
+			return super( request, &block )
+		else
+			return super( request ) {|r| r.response }
+		end
+	end
+
+
+	### Make any changes to the +response+ that are necessary before handing it to 
+	### 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 )
+		self.log.debug "Fixing up response: %p" % [ response ]
+		self.fixup_response_content_type( response )
+		self.fixup_head_response( response ) if request.verb == :HEAD
+		self.log.debug "  after fixup: %p" % [ response ]
+
+		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.
+	def fixup_response_content_type( response )
+		restype = response.content_type
+
+		if !restype
+			if (( default = self.class.default_content_type ))
+				self.log.debug "Setting default content type"
+				response.content_type = default
+			else
+				self.log.debug "No default content type"
+			end
+		else
+			self.log.debug "Content type already set: %p" % [ restype ]
+		end
+	end
+
+
+	### Remove the entity body of responses to HEAD requests.
+	def fixup_head_response( response )
+		self.log.debug "Truncating entity body of HEAD response."
+		response.headers.content_length = response.get_content_length
+		response.body = ''
+	end
+
+
+	### Abort the current execution and return a response with the specified
+	### http_status code immediately. The specified +message+ will be logged,
+	### and will be included in any message that is returned as part of the
+	### response. The +otherstuff+ hash can be used to pass headers, etc.
+	def finish_with( http_status, message, otherstuff={} )
+		status_info = otherstuff.merge( :status => http_status, :message => message )
+		throw :finish, status_info
+	end
+
+
+	### Create a response to specified +request+ based on the specified +status_code+ 
+	### and +message+.
+	def prepare_status_response( request, status_info )
+		status_code, message = status_info.values_at( :status, :message )
+		self.log.info "Non-OK response: %d (%s)" % [ status_code, message ]
+
+		response = request.response
+		response.reset
+		response.status = status_code
+
+		# 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.puts( message )
+		end
+
+		return response
+	end
+
+end # class Strelka::App
+

data/lib/strelka/behavior/plugin.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require 'rspec'
+
+require 'strelka'
+require 'strelka/app'
+require 'strelka/app/plugins'
+
+
+# This is a shared behavior for specs which different Strelka::App
+# plugins share in common. If you're creating a Strelka::App plugin,
+# you can test its conformity to the expectations placed on them by
+# adding this to your spec:
+# 
+#    require 'strelka/behavior/plugin'
+#
+#    describe YourPlugin do
+#
+#      it_should_behave_like "A Strelka::App Plugin"
+#
+#    end
+
+shared_examples_for "A Strelka::App Plugin" do
+
+	let( :plugin ) do
+		described_class
+	end
+
+
+	it "extends Strelka::App::Plugin" do
+		plugin.should be_a( Strelka::App::Plugin )
+	end
+
+end
+
+

data/lib/strelka/constants.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/ruby
+#encoding: utf-8
+
+require 'mongrel2/constants'
+require 'strelka' unless defined?( Strelka )
+
+
+# A collection of constants that are shared across the library
+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
+
+		# The list of valid verbs for regular HTTP
+		RFC2616_VERBS = %w[OPTIONS GET HEAD POST PUT DELETE TRACE CONNECT]
+
+		# A regex for matching RFC2616 verbs
+		RFC2616_VERB_REGEX = Regexp.union( RFC2616_VERBS )
+
+		# The list of HTTP verbs considered "safe"
+		SAFE_RFC2616_VERBS = %w[GET HEAD]
+
+		# 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/httprequest.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require 'uri'
+
+require 'mongrel2/httprequest'
+require 'strelka' unless defined?( Strelka )
+
+# An HTTP request class.
+class Strelka::HTTPRequest < Mongrel2::HTTPRequest
+	include Strelka::Loggable,
+	        Strelka::Constants
+
+	# Set Mongrel2 to use Strelka's request class for HTTP requests
+	register_request_type( self, *HTTP::RFC2616_VERBS )
+
+
+	### Initialize some additional stuff for Strelka requests.
+	def initialize( * ) # :notnew:
+		super
+		@uri = nil
+		@verb = self.headers[:method].to_sym
+	end
+
+
+	######
+	public
+	######
+
+	# The HTTP verb of the request (as a Symbol)
+	attr_accessor :verb
+
+
+	### Return a URI object parsed from the URI of the request.
+	def uri
+		return @uri ||= URI( self.headers.uri )
+	end
+
+
+	### Return the portion of the Request's path that was routed by Mongrel2. This and the
+	### #app_path make up the #path.
+	def pattern
+		return self.headers.pattern
+	end
+
+
+	### Return the portion of the Request's path relative to the application's
+	### Mongrel2 route.
+	def app_path
+		return self.path[ self.pattern.length .. -1 ]
+	end
+
+end # class Strelka::HTTPRequest

data/lib/strelka/logging.rb

@@ -0,0 +1,241 @@
+#!/usr/bin/ruby
+
+require 'logger'
+require 'date'
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/mixins'
+
+
+# A mixin that provides a top-level logging subsystem based on Logger.
+module Strelka::Logging
+
+	### Logging
+	# Log levels
+	LOG_LEVELS = {
+		'debug' => Logger::DEBUG,
+		'info'  => Logger::INFO,
+		'warn'  => Logger::WARN,
+		'error' => Logger::ERROR,
+		'fatal' => Logger::FATAL,
+	}.freeze
+	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
+
+
+	### Inclusion hook
+	def self::extended( mod )
+		super
+
+		class << mod
+			# the log formatter that will be used when the logging subsystem is reset
+			attr_accessor :default_log_formatter
+
+			# the logger that will be used when the logging subsystem is reset
+			attr_accessor :default_logger
+
+			# the logger that's currently in effect
+			attr_accessor :logger
+			alias_method :log, :logger
+			alias_method :log=, :logger=
+		end
+
+		mod.default_logger = mod.logger = Logger.new( $stderr )
+		mod.default_logger.level = $DEBUG ? Logger::DEBUG : Logger::WARN
+		mod.default_log_formatter = Strelka::Logging::Formatter.new( mod.default_logger )
+	end
+
+
+	### Reset the global logger object to the default
+	def reset_logger
+		self.logger = self.default_logger
+		self.logger.level = $DEBUG ? Logger::DEBUG : Logger::WARN
+		self.logger.formatter = self.default_log_formatter
+	end
+
+
+	### Returns +true+ if the global logger has not been set to something other than
+	### the default one.
+	def using_default_logger?
+		return self.logger == self.default_logger
+	end
+
+
+	# A alternate formatter for Logger instances.
+	class Formatter < Logger::Formatter
+
+		# The format to output unless debugging is turned on
+		DEFAULT_FORMAT = "[%1$s.%2$06d %3$d/%4$s] %5$5s -- %7$s\n"
+
+		# The format to output if debugging is turned on
+		DEFAULT_DEBUG_FORMAT = "[%1$s.%2$06d %3$d/%4$s] %5$5s {%6$s} -- %7$s\n"
+
+
+		### Initialize the formatter with a reference to the logger so it can check for log level.
+		def initialize( logger, format=DEFAULT_FORMAT, debug=DEFAULT_DEBUG_FORMAT ) # :notnew:
+			@logger       = logger
+			@format       = format
+			@debug_format = debug
+
+			super()
+		end
+
+		######
+		public
+		######
+
+		# The Logger object associated with the formatter
+		attr_accessor :logger
+
+		# The logging format string
+		attr_accessor :format
+
+		# The logging format string that's used when outputting in debug mode
+		attr_accessor :debug_format
+
+
+		### Log using either the DEBUG_FORMAT if the associated logger is at ::DEBUG level or
+		### using FORMAT if it's anything less verbose.
+		def call( severity, time, progname, msg )
+			args = [
+				time.strftime( '%Y-%m-%d %H:%M:%S' ),                         # %1$s
+				time.usec,                                                    # %2$d
+				Process.pid,                                                  # %3$d
+				Thread.current == Thread.main ? 'main' : Thread.object_id,    # %4$s
+				severity,                                                     # %5$s
+				progname,                                                     # %6$s
+				msg                                                           # %7$s
+			]
+
+			if @logger.level == Logger::DEBUG
+				return self.debug_format % args
+			else
+				return self.format % args
+			end
+		end
+	end # class LogFormatter
+
+
+	# A ANSI-colorized formatter for Logger instances.
+	class ColorFormatter < Logger::Formatter
+		extend Strelka::ANSIColorUtilities
+
+		# Color settings
+		LEVEL_FORMATS = {
+			:debug => colorize( :bold, :black ) {"[%1$s.%2$06d %3$d/%4$s] %5$5s {%6$s} -- %7$s\n"},
+			:info  => colorize( :normal ) {"[%1$s.%2$06d %3$d/%4$s] %5$5s -- %7$s\n"},
+			:warn  => colorize( :bold, :yellow ) {"[%1$s.%2$06d %3$d/%4$s] %5$5s -- %7$s\n"},
+			:error => colorize( :red ) {"[%1$s.%2$06d %3$d/%4$s] %5$5s -- %7$s\n"},
+			:fatal => colorize( :bold, :red, :on_white ) {"[%1$s.%2$06d %3$d/%4$s] %5$5s -- %7$s\n"},
+		}
+
+
+		### Initialize the formatter with a reference to the logger so it can check for log level.
+		def initialize( logger, settings={} ) # :notnew:
+			settings = LEVEL_FORMATS.merge( settings )
+
+			@logger   = logger
+			@settings = settings
+
+			super()
+		end
+
+		######
+		public
+		######
+
+		# The Logger object associated with the formatter
+		attr_accessor :logger
+
+		# The formats, by level
+		attr_accessor :settings
+
+
+		### Log using the format associated with the severity
+		def call( severity, time, progname, msg )
+			args = [
+				time.strftime( '%Y-%m-%d %H:%M:%S' ),                         # %1$s
+				time.usec,                                                    # %2$d
+				Process.pid,                                                  # %3$d
+				Thread.current == Thread.main ? 'main' : Thread.object_id,    # %4$s
+				severity,                                                     # %5$s
+				progname,                                                     # %6$s
+				msg                                                           # %7$s
+			]
+
+			return self.settings[ severity.downcase.to_sym ] % args
+		end
+	end # class LogFormatter
+
+
+	# An alternate formatter for Logger instances that outputs +div+ HTML
+	# fragments.
+	class HtmlFormatter < Logger::Formatter
+
+		# The default HTML fragment that'll be used as the template for each log message.
+		HTML_LOG_FORMAT = %q{
+		<div class="log-message %5$s">
+			<span class="log-time">%1$s.%2$06d</span>
+			[
+				<span class="log-pid">%3$d</span>
+				/
+				<span class="log-tid">%4$s</span>
+			]
+			<span class="log-level">%5$s</span>
+			:
+			<span class="log-name">%6$s</span>
+			<span class="log-message-text">%7$s</span>
+		</div>
+		}
+
+		### Override the logging formats with ones that generate HTML fragments
+		def initialize( logger, format=HTML_LOG_FORMAT ) # :notnew:
+			@logger = logger
+			@format = format
+			super()
+		end
+
+
+		######
+		public
+		######
+
+		# The HTML fragment that will be used as a format() string for the log
+		attr_accessor :format
+
+
+		### Return a log message composed out of the arguments formatted using the
+		### formatter's format string
+		def call( severity, time, progname, msg )
+			args = [
+				time.strftime( '%Y-%m-%d %H:%M:%S' ),                         # %1$s
+				time.usec,                                                    # %2$d
+				Process.pid,                                                  # %3$d
+				Thread.current == Thread.main ? 'main' : Thread.object_id,    # %4$s
+				severity.downcase,                                            # %5$s
+				progname,                                                     # %6$s
+				html_escape( msg ).gsub(/\n/, '<br />')                       # %7$s
+			]
+
+			return self.format % args
+		end
+
+
+		#######
+		private
+		#######
+
+		### Return a copy of the specified +string+ with HTML special characters escaped as
+		### HTML entities.
+		def html_escape( string )
+			return string.
+				gsub( /&/, '&amp;' ).
+				gsub( /</, '&lt;' ).
+				gsub( />/, '&gt;' )
+		end
+
+	end # class HtmlLogFormatter
+
+end # module Strelka
+
+# vim: set nosta noet ts=4 sw=4:
+

data/lib/strelka/mixins.rb

@@ -0,0 +1,143 @@
+#!/usr/bin/ruby
+
+require 'logger'
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/constants'
+
+
+module Strelka
+
+	# Add logging to a Strelka class. Including classes get #log and #log_debug methods.
+	module Loggable
+
+		# A logging proxy class that wraps calls to the logger into calls that include
+		# the name of the calling class.
+		class ClassNameProxy
+
+			### Create a new proxy for the given +klass+.
+			def initialize( klass, force_debug=false )
+				@classname   = klass.name
+				@force_debug = force_debug
+			end
+
+			### Delegate debug messages to the global logger with the appropriate class name.
+			def debug( msg=nil, &block )
+				Strelka.logger.add( Logger::DEBUG, msg, @classname, &block )
+			end
+
+			### Delegate info messages to the global logger with the appropriate class name.
+			def info( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Strelka.logger.add( Logger::INFO, msg, @classname, &block )
+			end
+
+			### Delegate warn messages to the global logger with the appropriate class name.
+			def warn( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Strelka.logger.add( Logger::WARN, msg, @classname, &block )
+			end
+
+			### Delegate error messages to the global logger with the appropriate class name.
+			def error( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Strelka.logger.add( Logger::ERROR, msg, @classname, &block )
+			end
+
+			### Delegate fatal messages to the global logger with the appropriate class name.
+			def fatal( msg=nil, &block )
+				Strelka.logger.add( Logger::FATAL, msg, @classname, &block )
+			end
+
+		end # ClassNameProxy
+
+		#########
+		protected
+		#########
+
+		### Copy constructor -- clear the original's log proxy.
+		def initialize_copy( original )
+			@log_proxy = @log_debug_proxy = nil
+			super
+		end
+
+		### Return the proxied logger.
+		def log
+			@log_proxy ||= ClassNameProxy.new( self.class )
+		end
+
+		### Return a proxied "debug" logger that ignores other level specification.
+		def log_debug
+			@log_debug_proxy ||= ClassNameProxy.new( self.class, true )
+		end
+
+	end # module Loggable
+
+	# A collection of ANSI color utility functions
+	module ANSIColorUtilities
+
+		# Set some ANSI escape code constants (Shamelessly stolen from Perl's
+		# Term::ANSIColor by Russ Allbery <rra@stanford.edu> and Zenin <zenin@best.com>
+		ANSI_ATTRIBUTES = {
+			'clear'      => 0,
+			'reset'      => 0,
+			'bold'       => 1,
+			'dark'       => 2,
+			'underline'  => 4,
+			'underscore' => 4,
+			'blink'      => 5,
+			'reverse'    => 7,
+			'concealed'  => 8,
+
+			'black'      => 30,   'on_black'   => 40,
+			'red'        => 31,   'on_red'     => 41,
+			'green'      => 32,   'on_green'   => 42,
+			'yellow'     => 33,   'on_yellow'  => 43,
+			'blue'       => 34,   'on_blue'    => 44,
+			'magenta'    => 35,   'on_magenta' => 45,
+			'cyan'       => 36,   'on_cyan'    => 46,
+			'white'      => 37,   'on_white'   => 47
+		}
+
+		###############
+		module_function
+		###############
+
+		### Create a string that contains the ANSI codes specified and return it
+		def ansi_code( *attributes )
+			attributes.flatten!
+			attributes.collect! {|at| at.to_s }
+			return '' unless /(?:vt10[03]|xterm(?:-color)?|linux|screen)/i =~ ENV['TERM']
+			attributes = ANSI_ATTRIBUTES.values_at( *attributes ).compact.join(';')
+
+			if attributes.empty?
+				return ''
+			else
+				return "\e[%sm" % attributes
+			end
+		end
+
+
+		### Colorize the given +string+ with the specified +attributes+ and return it, handling 
+		### line-endings, color reset, etc.
+		def colorize( *args )
+			string = ''
+
+			if block_given?
+				string = yield
+			else
+				string = args.shift
+			end
+
+			ending = string[/(\s)$/] || ''
+			string = string.rstrip
+
+			return ansi_code( args.flatten ) + string + ansi_code( 'reset' ) + ending
+		end
+
+	end # module ANSIColorUtilities
+
+end # module Strelka
+
+# vim: set nosta noet ts=4 sw=4:
+