arrow 1.0.7

data/lib/arrow/broker.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+
+require 'arrow/mixins'
+require 'arrow/exceptions'
+require 'arrow/object'
+require 'arrow/cache'
+require 'arrow/templatefactory'
+require 'arrow/appletregistry'
+
+
+# The broker is the applet manager. It maintains a registry of applets, and delegates 
+# transactions based on the request's URI.
+# 
+# == Authors
+# 
+# * Michael Granger <mgranger@RubyCrafters.com>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Broker < Arrow::Object
+
+	### Class constants/methods
+
+	# A regular expression that matches the file separator on this system
+	FILE_SEPARATOR = Regexp.new( Regexp.compile(File::SEPARATOR) )
+
+
+	### Create a new Arrow::Broker object from the specified +config+ (an
+	### Arrow::Config object).
+	def initialize( config )
+		@config = config
+		@registry = Arrow::AppletRegistry.new( config )
+		@start_time = Time.now
+	end
+
+
+	######
+	public
+	######
+
+	# The Hash of RegistryEntry structs keyed by uri
+	attr_accessor :registry
+
+	# The Time when the Broker was started
+	attr_reader :start_time
+
+
+
+	### Dispatch the specified transaction +txn+ to the appropriate handler
+	### based on the request's path_info.
+	def delegate( txn )
+		rval = appletchain = nil
+		self.log.debug "Start of delegation (%s)" % [ txn.unparsed_uri ]
+
+		# Fetch the path and trim the leading '/'
+		path = txn.path
+		path.sub!( %r{^/}, '' )
+		self.log.debug "Request's path is %p" % path
+
+		# Check for updated/deleted/added applets
+		@registry.check_for_updates
+
+		# Get the chain of applets to execute for the request
+		appletchain = @registry.find_applet_chain( path )
+
+		# If the pathinfo doesn't correspond to at least one applet, run
+		# the no-such-applet handler.
+		if appletchain.empty?
+			rval = self.run_missing_applet_handler( txn, path )
+		else
+			rval = self.run_applet_chain( txn, appletchain )
+		end
+
+		# Set the request status to declined if it hasn't been set yet and
+		# the return value is false.
+		if !rval
+			self.log.error "Applet returned false value. " +
+				"Setting status to DECLINED"
+			txn.status = Apache::DECLINED
+		end
+
+		# self.log.debug "Returning %p" % [ rval ]
+		return rval
+	end
+
+
+	### Run the specified +applet+ with the given +txn+ (an Arrow::Transaction) 
+	### and the +rest+ of the path_info split on '/'.
+	def run_applet( applet, txn, rest )
+		self.log.debug "Running '%s' with args: %p" %
+			[ applet.signature.name, rest ]
+		return applet.run( txn, *rest )
+	rescue ::Exception => err
+		self.log.error "[%s]: Error running %s (%s): %s:\n\t%s" % [
+		    txn.serial,
+			applet.signature.name,
+			applet.class.filename,
+			err.message,
+			err.backtrace.join("\n\t"),
+		]
+		return self.run_error_handler( applet, txn, err )
+	end
+
+
+	### Handle requests that target an applet that doesn't exist.
+	def run_missing_applet_handler( txn, uri )
+		rval = appletchain = nil
+		handlerUri = @config.applets.missingApplet
+		args = uri.split( %r{/} )
+
+		# Build an applet chain for user-configured handlers
+		if handlerUri != "(builtin)"
+			appletchain = @registry.find_applet_chain( handlerUri )
+			self.log.error "Configured MissingApplet handler (%s) doesn't exist" %
+				handlerUri if appletchain.empty?
+		end
+
+		# If the user-configured handler maps to one or more handlers, run
+		# them. Otherwise, run the build-in handler.
+		unless appletchain.nil? || appletchain.empty?
+			rval = self.run_applet_chain( txn, appletchain )
+		else
+			rval = self.builtin_missing_handler( txn, *args )
+		end
+
+		return rval
+	end
+
+
+	### Handle the given applet error +err+ for the specified +applet+, using 
+	### the given transaction +txn+. This will attempt to run whatever applet 
+	### is configured as the error-handler, or run a builtin handler applet 
+	### if none is configured or the configured one isn't loaded.
+	def run_error_handler( applet, txn, err )
+		rval = nil
+		handlerName = @config.applets.errorApplet.sub( %r{^/}, '' )
+
+		unless handlerName == "(builtin)" or !@registry.key?( handlerName )
+			handler = @registry[handlerName]
+			self.log.notice "Running error handler applet '%s' (%s)" %
+				[ handler.signature.name, handlerName ]
+
+			begin
+				rval = handler.run( txn, "report_error", applet, err )
+			rescue ::Exception => err2
+				self.log.error "Error while attempting to use custom error "\
+				"handler '%s': %s\n\t%s" % [
+					handler.signature.name,
+					err2.message,
+					err2.backtrace.join("\n\t"),
+				]
+
+				rval = self.builtin_error_handler( applet, txn, err )
+			end
+		else
+			rval = self.builtin_error_handler( applet, txn, err )
+		end
+
+		return rval
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Given a chain of applets built from a URI, run the +index+th one with
+	### the specified transaction (+txn+). Applets before the last get called
+	### via their #delegate method, while the last one is called via #run.
+	def run_applet_chain( txn, chain )
+		self.log.debug "Running applet chain: #{chain.inspect}"
+		raise Arrow::AppletError, "Malformed applet chain" if
+			chain.empty? || !chain.first.respond_to?( :applet )
+
+		res = nil
+		applet, txn.applet_path, args = self.unwrap_chain_link( chain.first )
+
+		# If there's only one item left, run it
+		if chain.nitems == 1
+			self.log.debug "Running final applet in chain"
+			res = self.run_applet( applet, txn, args )
+
+		# Otherwise, delegate the transaction to the next applet with the
+		# remainder of the chain.
+		else
+			dchain = chain[ 1..-1 ]
+			self.log.debug "Running applet %s in chain of %d; chain = %p" %
+				[ applet.signature.name, chain.nitems, dchain ]
+
+			begin
+				res = applet.delegate( txn, dchain, *args ) do |subchain|
+					subchain = dchain if subchain.nil?
+					self.log.debug "Delegated call to appletchain %p" % [ subchain ]
+					self.run_applet_chain( txn, subchain )
+				end
+			rescue ::Exception => err
+				self.log.error "Error while executing applet chain: %p (/%s): %s:\n\t%s" % [
+					applet,
+					chain.first[1],
+					err.message,
+					err.backtrace.join("\n\t"),
+				]
+				res = self.run_error_handler( applet, txn, err )
+			end
+		end
+
+		return res
+	end
+
+
+	### Check the specified +link+ of an applet chain for sanity and return
+	### its constituent bits for assignment. This is necessary to provide
+	### sensible errors if a delegating app screws up a chain somehow.
+	def unwrap_chain_link( link )
+		applet = link.applet or raise Arrow::AppletChainError, "Null applet"
+		path = link.path or raise Arrow::AppletChainError, "Null path"
+		args = link.args or raise Arrow::AppletChainError, "Null argument list"
+		unless args.is_a?( Array )
+			emsg = "Argument list is a %s: expected an Array" %
+				args.class.name
+			raise Arrow::AppletChainError, emsg
+		end
+
+		return applet, path, args
+	end
+
+
+	### The builtin missing-applet handler routine. Returns +false+, which 
+	### causes the dispatcher to decline the request.
+	def builtin_missing_handler( txn, *args )
+		self.log.notice "Using builtin missing-applet handler."
+		return false
+	end
+
+
+	### The builtin error handler routine. Outputs a plain-text backtrace
+	### for the given exception +err+ and +applet+ to the given
+	### transaction +txn+.
+	def builtin_error_handler( applet, txn, err )
+		self.log.notice "Using builtin error handler."
+		txn.request.content_type = "text/plain"
+		txn.status = Apache::OK
+
+		return "Arrow Applet Error in '%s': %s\n\t%s" %
+			[ applet.class.signature.name, err.message, err.backtrace.join("\n\t") ]
+	end
+
+
+
+end # class Arrow::Broker
+
+
+__END__
+
+

data/lib/arrow/cache.rb

@@ -0,0 +1,176 @@
+#!/usr/bin/env ruby
+
+require 'cache'
+require 'forwardable'
+
+require 'arrow/logger'
+require 'arrow/mixins'
+
+
+# 
+# A derivative of the Cache class from the ruby-cache module. It adds a few 
+# convenience and introspection methods to its parent.
+# 
+# Instances of this class are LRU caches for disk-based objects which keep
+# track of the cached object's modification time, expiring the cached
+# version when the disk-based version changes (e.g., for template caching).
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Cache < ::Cache
+	extend Forwardable
+	include Arrow::Loggable
+
+	# Default configuration values
+	DefaultConfig = {
+		:maxNum			=> 10,
+		:maxObjSize		=> nil,
+		:maxSize		=> nil,
+		:expiration		=> 3600,
+	}
+
+	
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	@extent = []
+	class << self
+		attr_reader :extent
+	end
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+
+	### Create a new cache. This merges the DefaultConfig with the specified
+	### values and transforms camelCased keys into under_barred ones.
+	def initialize( name, config={}, &cleanup )
+		@name = name
+
+		# Merge defaults and specified values
+		merged = DefaultConfig.merge( config )
+
+		# Transform the config hash into the form the superclass expects
+		merged.each_key do |key|
+			lckey = key.to_s.gsub( /(.)([A-Z])/ ) {|match|
+				match[0,1] + "_" + match[1,1].downcase
+			}.to_sym
+
+			next if key == lckey
+			merged[ lckey ] = merged.delete( key )
+		end
+
+		# Register this instance with the class for introspection (costs
+		# much less than ObjectSpace.each_object).
+		obj = super( merged, &cleanup )
+		self.class.extent << obj
+
+		return obj
+	end
+
+
+	######
+	public
+	######
+	
+	# Delegate some methods to the underlying hash
+	def_delegators :@objs, :length, :keys, :values
+	
+
+	# The name of the cache; used in introspection
+	attr_reader :name
+	
+	# Total count of cache hits
+	attr_reader :hits
+	
+	# Total count of cache misses
+	attr_reader :misses
+	
+	# Cache size in bytes
+	attr_reader :size
+	
+	# The list of cached objects
+	attr_reader :list
+
+
+	### Overridden to provide logging of invalidated keys.
+	def invalidate( key )
+		self.log.debug "invalidating cache key '%p' for %s" % [key, self.name]
+		super
+	end
+
+
+	### Overridden for logging.
+	def invalidate_all
+		self.log.debug "invalidating all cached objects for %s" % [self.name]
+		super
+	end
+	
+
+	### Overridden to provide logging of expire phase.
+	def expire
+		self.log.debug "looking for expired entries in %s" % [self.name]
+		super
+	end
+
+
+	### Overridden from the superclass to prevent .to_s from being called on
+	### objects to determine their size if the object supports a #memsize
+	### method. This is mostly to stop templates from being rendered every
+	### time they're cached.
+	def []=( key, obj )
+		self.expire
+		
+		self.invalidate( key ) if self.cached?( key )
+
+		if obj.respond_to?( :memsize )
+			size = obj.memsize
+		else
+			size = obj.to_s.size
+		end
+
+		# Test against size threshold
+		if @max_obj_size && size > @max_obj_size
+			Arrow::Logger[self.class].debug \
+				"%p not cached: size exceeds maxObjSize: %d" %
+				[ obj, @max_obj_size ]
+			return obj
+		end
+		if @max_obj_size.nil? && @max_size && size > @max_size
+			Arrow::Logger[self.class].debug \
+				"%p not cached: size exceeds maxSize: %d" %
+				[ obj, @max_size ]
+			return obj
+		end
+		
+		if @max_num && @list.size >= @max_num
+			Arrow::Logger[self.class].debug \
+				"Dropping %p from the cache: count exceeds maxNum: %d" %
+				[ @list.first, @max_num ]
+			self.invalidate( @list.first )
+		end
+
+		@size += size
+		if @max_size
+			while @size > @max_size
+				Arrow::Logger[self.class].debug \
+					"Dropping %p from the cache: size exceeds maxSize: %d" %
+					[ @list.first, @max_size ]
+				self.invalidate( @list.first )
+			end
+		end
+
+		@objs[ key ] = Cache::CACHE_OBJECT.new( obj, size, Time.now.to_i )
+		@list.push( key )
+
+		return obj
+	end
+
+
+end # class Arrow::Cache

data/lib/arrow/config-loaders/yaml.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+
+require 'yaml'
+
+require 'arrow/config'
+require 'arrow/path'
+require 'arrow/constants'
+
+
+# The Arrow::Config::YamlLoader class, a derivative of Arrow::Config::Loader. It 
+# is used to load configuration files written in YAML for the Arrow web 
+# application framework.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Config::YamlLoader < Arrow::Config::Loader
+	include Arrow::Constants
+
+
+	# Add YAML domain types for Arrow classes
+
+	YAML.add_domain_type( YAML_DOMAIN, "arrowPath" ) do |type, val|
+		obj = nil
+		case val
+		when Array
+			Arrow::Logger.debug "Adding %p to loaded Arrow::Path" % [ val ]
+			obj = Arrow::Path.new( val )
+		else
+			raise "Invalid #{type}: %p" % val
+		end
+
+		obj
+	end
+
+
+
+	######
+	public
+	######
+
+	### Load and return configuration values from the YAML +file+
+	### specified.
+	def load( filename )
+		self.log.info "Loading YAML-format configuration from '%s'" % filename
+		return YAML.load_file( filename )
+	end
+
+
+	### Save configuration values to the YAML +file+ specified.
+	def save( confighash, filename )
+		self.log.info "Saving YAML-format configuration to '%s'" % filename
+		File.open( filename, File::WRONLY|File::CREAT|File::TRUNC ) {|ofh|
+			ofh.print( confighash.to_yaml )
+		}
+	end
+
+
+	### Return +true+ if the specified +file+ is newer than the given
+	### +time+.
+	def is_newer?( file, time )
+		return false unless File.exists?( file )
+		st = File.stat( file )
+		self.log.debug "File mtime is: %s, comparison time is: %s" %
+			[ st.mtime, time ]
+		return st.mtime > time
+	end
+
+
+end # class Arrow::Config::YamlLoader
+
+