arrow 1.0.7

data/lib/arrow/session.rb

@@ -0,0 +1,289 @@
+#!/usr/bin/env ruby
+
+require 'uri'
+require 'pluginfactory'
+require 'configurability'
+
+require 'arrow/object'
+require 'arrow/exceptions'
+require 'arrow/mixins'
+require 'arrow/logger'
+require 'arrow/config'
+
+
+# The Arrow::Session class, a container for maintaining state across multiple 
+# transactions.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Session < Arrow::Object
+	include PluginFactory,
+	        Enumerable
+	extend Configurability
+
+	config_key :session
+
+	require 'arrow/session/store'
+	require 'arrow/session/lock'
+	require 'arrow/session/id'
+
+
+	
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	require 'arrow/config'
+	@config = Arrow::Config.new.session
+	class << self
+		attr_reader :config
+	end
+
+	### Parse the given string into a URI object, appending the path part if
+	### it doesn't exist.
+	def self::parse_uri( str )
+		return str if str.is_a?( URI::Generic )
+		str += ":." if /^\w+$/ =~ str
+		URI.parse( str )
+	end
+
+
+	### Configure the session class's factory with the given Arrow::Config
+	### object.
+	def self::configure( config )
+		@config = config.dup
+		Arrow::Logger[self].debug "Done. Session config is: %p" % @config
+	end
+
+
+	### Create a new session for the specified +request+.
+	def self::create( txn, configHash={} )
+		# Merge the incoming config with the factory's
+		sconfig = @config.merge( configHash )
+		Arrow::Logger[self].debug "Merged config is: %p" % sconfig
+
+		# Create a new id and backing store object
+        idobj = self.create_id( sconfig, txn )
+        store = self.create_store( sconfig, idobj )
+        lock = self.create_lock( sconfig, store, idobj )
+
+		# Create the session cookie
+        scookie = self.create_session_cookie( txn, sconfig, idobj, store, lock )
+
+		return new( idobj, lock, store, txn, scookie )
+	end
+
+
+    ### Set the session cookie if we're really running under Apache.
+    def self::create_session_cookie( txn, config, id, store, lock )
+		scookie = Arrow::Cookie.new(
+				config.idName,
+				id.to_s,
+				:expires => config.expires,
+				:path => '/'
+			)
+
+		Arrow::Logger[self].debug "Created cookie: %p" % scookie.to_s
+        return scookie
+    end
+
+
+    ### Create an Arrow::Session::Id object for the given +txn+, with the 
+    ### particulars dictated by the specified +config+.
+    def self::create_id( config, txn )
+		cookie_name = config.idName
+	
+        # Fetch the id from the request, either from the session cookie or
+		# as a parameter if the cookie doesn't exist.
+		if txn.request_cookies.include?( cookie_name )
+			Arrow::Logger[self].debug "Found an existing session cookie (%s)" %
+				[ cookie_name ]
+			idstring = txn.request_cookies[ cookie_name ].value
+		else
+			Arrow::Logger[self].debug \
+				"No existing session cookie (%s); looking for one in a request parameter" %
+				[ cookie_name]
+			idstring = txn.param( cookie_name )
+		end
+
+		Arrow::Logger[self].debug "Creating a session id object: %p" % config.idType
+		return Arrow::Session::Id.create( config.idType, txn.request, idstring )
+	end
+	
+
+	### Create an Arrow::Session::Store object with the given +id+. The type 
+	### and configuration of the store will be dictated by the specified 
+	### +config+ object.
+    def self::create_store( config,  id )
+        Arrow::Logger[self].debug "Creating a session store: %p" % config.storeType
+		return Arrow::Session::Store.create( config.storeType, id )
+    end
+    
+
+	### Create an Arrow::Session::Lock object for the specified +store+ and +id+.
+	def self::create_lock( config, store, id )
+	    
+		lockuri = Arrow::Session.parse_uri( config.lockType )
+        lock = nil
+
+		# If the configuration says to use the recommended locker, ask the
+		# backing store for a lock object.
+		if lockuri.scheme == 'recommended'
+			Arrow::Logger[self].debug "Creating recommended lock"
+			lock = store.create_recommended_lock( id ) or
+				raise Arrow::SessionError, "No recommended locker for %s" %
+					store.class.name
+		else
+			Arrow::Logger[self].debug "Creating a session lock: %p" % lockuri
+			lock = Arrow::Session::Lock.create( lockuri, id )
+		end
+
+	   return lock
+	end
+	
+	
+	### Return the configured name of the session cookie.
+	def self::session_cookie_name
+		return @config.idName
+	end
+	
+	
+
+	#########
+	protected
+	#########
+
+	### Create delegators that readlock the session store before accessing
+	### it.
+	def self::def_delegated_readers( *syms )
+		syms.each do |sym|
+			define_method( sym ) do |*args|
+				@lock.read_lock
+				@store.send( sym, *args )
+			end
+		end
+	end
+
+
+	### Create delegators that writelock the session store before accessing
+	### it.
+	def self::def_delegated_writers( *syms )
+		syms.each do |sym|
+			define_method( sym ) do |*args|
+				@lock.write_lock
+				@store.send( sym, *args )
+			end
+		end
+	end
+
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+
+	### Create a new Arrow::Session object for the given +idobj+ (an
+	### Arrow::Session::Id object), using the given +lock+ (an
+	### Arrow::Session::Locker object) for serializing access. 
+	def initialize( idobj, lock, store, txn, cookie=nil )
+		raise ArgumentError, "No id object" unless idobj
+		raise ArgumentError, "No lock object" unless lock
+		raise ArgumentError, "No store object" unless store
+
+		self.log.debug "Initializing session with id: %p, lock: %p, store: %p" %
+			[ idobj, lock, store ]
+
+		@id = idobj
+		@lock = lock
+		@store = store
+		@txn = txn
+		@cookie = cookie
+
+		@store[ :_session_id ] = id.to_s
+	end
+
+
+	######
+	public
+	######
+
+	# The session's unique identifier, an Apache::Session::Id object.
+	attr_reader :id
+
+	# The session's backing store; an Apache::Session::Store object.
+	attr_reader :store
+
+	# The session's lock object; an Apache::Session::Lock.
+	attr_reader :lock
+
+	# The Apache::Cookie object used to manipulate the session cookie.
+	attr_reader :cookie
+
+
+	### Delete the session
+	def remove
+		@lock.with_write_lock do
+			@store.remove
+		end
+		@lock.release_all_locks
+		@cookie.expires = Time.at(0)
+	end
+
+
+	### Clear all data from the session object.
+	def clear
+		@lock.with_write_lock do
+    		@store.clear
+    		@store[ :_session_id ] = @id.to_s
+		end
+	end
+
+
+	### Enumerable iterface: iterate over the session's key/value pairs,
+	### calling the given block once for each pair.
+	def each( &block )
+		raise LocalJumpError, "no block given" unless block
+		@lock.read_lock
+		@store.each( &block )
+	end
+
+
+	### Save the session to fixed storage and set the session cookie in the
+	### creating transaction's outgoing headers.
+	def save
+		begin
+			self.log.debug "Saving session data"
+			@store.save
+			self.log.debug "Writing session cookie (%p)" % [ @cookie ]
+			@txn.cookies[ self.class.session_cookie_name ] = @cookie
+		ensure
+			self.log.debug "Releasing all locks"
+			@lock.release_all_locks
+		end
+	end
+
+
+	### Tell the session that it will not be used again in the current
+	### session.
+	def finish
+		@lock.release_all_locks
+	end
+
+
+	### Delegate the common hash methods to the session store, which
+	### re-delegates them to its data.
+	def_delegated_readers :[], :default, :default=, :each, :each_key,
+		:each_pair, :each_value, :empty?, :fetch, :has_key?, :has_value?,
+		:include?, :index, :invert, :key?, :keys, :length, :member?, :merge,
+		:rehash, :reject, :select, :size, :sort, :to_a, :value?, :values
+
+	def_delegated_writers :[]=, :delete, :clear, :merge!, :replace,
+		:delete_if, :reject!
+
+end # class Arrow::Session
+
+

data/lib/arrow/session/dbstore.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+require 'sequel'
+
+require 'arrow/exceptions'
+require 'arrow/session/store'
+
+# The Arrow::Session::DbStore class, a derivative of Arrow::Session::Store.
+# Instances of this class store a session object in a database.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# :include: LICENSE
+#
+#--
+#
+# Please see the file LICENSE in the BASE directory for licensing details.
+#
+class Arrow::Session::DbStore < Arrow::Session::Store
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new Arrow::Session::DbStore object.
+	def initialize( uri, idobj )
+		
+		db = Sequel.connect( uri )
+		dataset = db[]
+		@id = idobj
+		super
+	end
+
+
+	######
+	public
+	######
+
+	# The database handle
+	attr_reader :db
+
+	# The session ID this store was created for
+	attr_reader :id
+
+
+	### Insert the specified +data+ hash into whatever permanent storage the
+	### Store object is acting as an interface to.
+	def insert
+		super {|data|
+			self.log.debug "Inserting data into session table for session %s" % [ self.id ]
+			self.
+		}
+	end
+
+
+	### Update the current data hash stored in permanent storage with the
+	### values contained in +data+.
+	def update
+		super {|data|
+			self.log.debug "Updating data in session file"
+			ofh = self.open
+			ofh.seek( 0, File::SEEK_SET )
+			ofh.print( data )
+		}
+	end
+
+
+	### Retrieve the data hash stored in permanent storage associated with
+	### the id the object was created with.
+	def retrieve
+		super {
+			self.log.debug "Reading data in session file"
+			ofh = self.open( File::RDWR )
+			ofh.seek( 0, File::SEEK_SET )
+			ofh.read
+		}
+	end
+
+
+	### Permanently remove the data hash associated with the id used in the
+	### receiver's creation from permanent storage.
+	def remove
+		super
+		self.close
+		file = self.session_file
+		if File.exists?( file )
+			File.delete( file )
+		else
+			raise Arrow::SessionError,
+				"Session file #{file} does not exist in the data store"
+		end
+	end
+
+
+end # class Arrow::Session::DbStore
+
+

data/lib/arrow/session/filelock.rb

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+
+require 'ftools'
+
+require 'arrow/session/lock'
+
+# The Arrow::Session::FileLock class, a derivative of Arrow::Session::Lock. 
+# Instances of this class provide file-based locking for Arrow sessions 
+# using the flock(2) system call.  It (obviously) won't work on platforms 
+# which don't support flock(2), or on filesystems which don't provide
+# flock-based locking semantics (e.g., NFS).
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Session::FileLock < Arrow::Session::Lock
+
+	# The path to the default lockdir
+	DefaultLockDir = '/tmp'
+
+	# The format string that will be used for the name of the lock file. The
+	# first '%s' will be replaced with a sanitized version of the session
+	# id.
+	LockfileFormat = "arrow-session-%s.lock"
+
+	# The mode to open the lockfile in
+	FileMode = File::RDWR|File::CREAT
+
+
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	### Clean the specified +directory+ of lock files older than +threshold+
+	### seconds.
+	def self::clean( directory=DefaultLockDir, threshold=3600 )
+		pat = File.join( directory, LockfileFormat.gsub(/%s/, '*') )
+		threshold = Time.now - threshold
+		Dir[ pat ].each do |file|
+			if File.mtime( file ) < threshold
+				Arrow::Logger[self].info \
+					"Removing stale lockfile '%s'" % file
+				begin
+					fh = File.open( file, FileMode )
+					fh.flock( File::LOCK_EX|File::LOCK_NB )
+					File.delete( file )
+					fh.flock( File::LOCK_UN )
+					fh.close
+				rescue => err
+					Arrow::Logger[self].warning \
+						"Could not clean up '%s': %s" %
+						[ file, err.message ]
+					next
+				end
+			end
+		end
+	end
+
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+
+	### Create a new Arrow::Session::FileLock object.
+	def initialize( uri, id )
+		@lockDir = uri.path || DefaultLockDir
+		super
+
+		# 'foo de barg blag 0x1f2eca'.gsub( /\W/, '_' ) 
+		#  => foo_de_barg_blag_0x1f2eca
+		lockfilename = LockfileFormat % id.to_s.gsub( /\W/, '_' )
+		File.mkpath( @lockDir )
+		@filename = File.join( @lockDir, lockfilename ).untaint
+		@lockfile = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The path to the directory where session lockfiles are kept.
+	attr_accessor :lockDir
+
+
+	### Indicate to the lock that the caller will no longer be using it, and
+	### it may free any resources it had been using.
+	def finish
+		super
+		self.close_lock_file
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Get the File object for the lockfile belonging to this lock,
+	### creating it if necessary.
+	def lockfile
+		@lockfile ||= File.open( @filename, FileMode )
+	end
+
+
+	### Close the lockfile and destroy the File object belonging to this
+	### lock.
+	def close_lock_file
+		if @lockfile
+			path = @lockfile.path
+			@lockfile.close
+			@lockfile = nil
+			File.delete( path.untaint ) if File.exist?( path.untaint )
+		end
+	end
+
+
+	### Acquire a read (shared) lock on the lockfile.
+	def acquire_read_lock( blocking )
+		flags = File::LOCK_SH
+		flags |= File::LOCK_NB if !blocking
+
+		self.lockfile.flock( flags )
+	end
+
+
+	### Acquire a write (exclusive) lock on the lockfile.
+	def acquire_write_lock( blocking )
+		flags = File::LOCK_EX
+		flags |= File::LOCK_NB if !blocking
+
+		self.lockfile.flock( flags )
+	end
+
+
+	### Release a previously-acquired read lock.
+	def release_read_lock
+		if !self.write_locked?
+			self.lockfile.flock( File::LOCK_UN )
+			self.close_lock_file
+		end
+	end
+
+
+	### Release a previously-acquired write lock.
+	def release_write_lock
+		if self.read_locked?
+			self.lockfile.flock( File::LOCK_SH )
+		else
+			self.lockfile.flock( File::LOCK_UN )
+			self.close_lock_file
+		end
+	end
+
+end # class Arrow::Session::FileLock
+
+