arrow 1.0.7

data/lib/arrow/session/filestore.rb

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+
+require 'arrow/exceptions'
+require 'arrow/session/store'
+
+# The Arrow::Session::FileStore class, a derivative of Arrow::Session::Store. 
+# Instances of this class store a session object as a marshalled hash on disk.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Session::FileStore < Arrow::Session::Store
+
+	# The default flags to use when opening the backing store file
+	DefaultIoFlags = File::RDWR|File::CREAT
+
+	
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new Arrow::Session::FileStore object.
+	def initialize( uri, idobj )
+		path = (uri.path || uri.opaque).dup
+		path.untaint
+
+		@dir = File.expand_path( path )
+		@io = nil
+
+		super
+	end
+
+
+	######
+	public
+	######
+
+	# The fully-qualified directory in which session files will be written.
+	attr_reader :dir
+
+
+	### Return the fully-qualified path to the session file for this
+	### store.
+	def session_file
+		return File.join( @dir, @id.to_s )
+	end
+
+
+	### Close the file after saving to make sure it's synched.
+	def save
+		super
+		@io = nil
+	end
+
+
+	### Get the output filehandle for the session backing store
+	### file. Open it with the specified +ioflags+ if it's not
+	### already open.
+	def open( ioflags=DefaultIoFlags )
+		if @io.nil? || @io.closed?
+			file = self.session_file
+			self.log.debug "Opening session file %s" % file
+			@io = File.open( file, File::RDWR|File::CREAT )
+			@io.sync = true
+		end
+
+		return @io
+	end
+
+
+	### Close the output filehandle if it is opened.
+	def close
+		@io.close unless @io.nil? || @io.closed?
+	end
+
+
+	### 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 file"
+			self.open( DefaultIoFlags|File::EXCL ).print( data )
+		}
+	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::FileStore
+
+

data/lib/arrow/session/id.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+require 'pluginfactory'
+
+require 'arrow/object'
+require 'arrow/mixins'
+require 'arrow/session'
+
+# The Arrow::Session::Id class, a derivative of Arrow::Object. Instances of 
+# concrete derivatives of this class are used as session IDs in Arrow::Session 
+# objects.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Session::Id < Arrow::Object
+	include PluginFactory
+
+
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	### Returns the Array of directories to search for derivatives; part of
+	### the PluginFactory interface.
+	def self::derivativeDirs
+		[ 'arrow/session', 'arrow/session/id' ]
+	end
+
+
+	### Create a new Arrow::Session::Id object for the given +request+ (an
+	### Apache::Request) of the type specified by +uri+.
+	def self::create( uri, request, idstring=nil )
+		uri = Arrow::Session.parse_uri( uri ) if uri.is_a?( String )
+		super( uri.scheme.dup, uri, request, idstring )
+	end
+
+
+	### Generate a new id string for the given +request+.
+	def self::generate( uri, request )
+		raise NotImplementedError, "%s does not implement #generate" %
+			self.name
+	end
+
+
+	### Validate the given +idstring+, returning an untainted copy of it if
+	### it's valid, or +nil+ if it's not.
+	def self::validate( uri, idstring )
+		raise NotImplementedError, "%s does not implement #validate" %
+			self.name
+	end
+
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+	
+	### Create a new Arrow::Session::Id object. If the +idstring+ is given, it
+	### will be used as the unique key for this session. If it is not
+	### specified, a new one will be generated.
+	def initialize( uri, request, idstring=nil )
+		@new = true
+
+		if idstring
+			self.log.debug "Validating id %p" % [ idstring ]
+			@str = self.class.validate( uri, idstring )
+			self.log.debug "  validation %s" % [ @str ? "succeeded" : "failed" ]
+			@new = false
+		end
+		
+		@str ||= self.class.generate( uri, request )
+		super()
+	end
+
+
+	######
+	public
+	######
+
+
+	### Return the id as a String.
+	def to_s
+		return @str
+	end
+
+
+	### Returns +true+ if the id was generated for this request as opposed
+	### to being fetched from a cookie or the URL.
+	def new?
+		@new ? true : false
+	end
+
+end # class Arrow::Session::Id
+

data/lib/arrow/session/lock.rb

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+
+require 'uri'
+require 'pluginfactory'
+
+require 'arrow/object'
+require 'arrow/exceptions'
+require 'arrow/mixins'
+require 'arrow/session'
+
+
+# The Arrow::Session::Lock class, which is the abstract
+# superclass for session lock object classes. Locks are objects which fulfill
+# the locking interface of Arrow::Session, providing a way of serializing
+# access to session data.
+# 
+# To derive your own lock manager classes from this class, you'll need to 
+# follow the following interface:
+#
+# === Derivative Interface ===
+# 
+# Locking is achieved via four methods: #acquire_read_lock, #acquire_write_lock,
+# #release_read_lock, and #release_write_lock. These methods provide the
+# #concurrency for sessions shared between multiple servers. You will probably
+# #also want to provide your own initializer to capture the session's ID.
+# 
+# #initialize( uri=string, id=Arrow::Session::Id )
+#
+# #acquire_read_lock::
+#   Acquire a shared lock on the session data.
+#
+# #acquire_write_lock::
+#   Acquire an exclusive lock on the session data.
+# 
+# #release_read_lock
+#   Release a shared lock on the session data.
+#
+# #release_write_lock::
+#   Release an exclusive lock on the session data.
+# 
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# Please see the file LICENSE in the top-level directory for licensing details.
+#
+class Arrow::Session::Lock < Arrow::Object
+	include PluginFactory
+
+	# Lock status flags
+	UNLOCKED	= 0b00
+	READ		= 0b01
+	WRITE		= 0b10
+
+
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	### Returns the Array of directories to search for derivatives; part of
+	### the PluginFactory interface.
+	def self::derivativeDirs
+		[ 'arrow/session', 'arrow/session/lock' ]
+	end
+
+
+	### Create a new Arrow::Session::Lock object for the given +id+ of the
+	### type specified by +uri+.
+	def self::create( uri, id )
+		uri = Arrow::Session.parse_uri( uri ) if
+			uri.is_a?( String )
+		super( uri.scheme.dup, uri, id )
+	end
+
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+
+	### Create a new Arrow::Session::Lock object.
+	def initialize( uri, id )
+		super()
+		@status = UNLOCKED
+	end
+
+
+	######
+	public
+	######
+
+	### Acquire a read (shared) lock. If +blocking+ is false, will return
+	### +false+ if the lock was not able to be acquired.
+	def read_lock( blocking=true )
+		return true if self.read_locked?
+		self.log.debug "Acquiring read lock"
+		self.acquire_read_lock( blocking ) or return false
+		@status |= READ
+		self.log.debug "Got read lock"
+		return true
+	end
+
+
+	### Acquire a write (exclusive) lock. If +blocking+ is false, will
+	### return +false+ if the lock was not able to be acquired.
+	def write_lock( blocking=true )
+		return true if self.write_locked?
+		self.log.debug "Acquiring write lock"
+		self.acquire_write_lock( blocking ) or return false
+		@status |= WRITE
+		self.log.debug "Got write lock"
+		return true
+	end
+
+
+	### Execute the given block after obtaining a read lock, and give up the
+	### lock when the block returns. If +blocking+ is false, will raise an
+	### Errno::EAGAIN error without calling the block if the lock cannot be
+	### immediately established.
+	def with_read_lock( blocking=true )
+		begin
+			self.read_lock( blocking ) or raise Errno::EAGAIN
+			yield
+		ensure
+			self.release_read_lock
+		end
+	end
+
+
+	### Execute the given block after obtaining a write lock, and give up
+	### the lock when the block returns. If +blocking+ is false, will raise
+	### an Errno::EAGAIN error without calling the block if the lock cannot
+	### be immediately established.
+	def with_write_lock( blocking=true )
+		begin
+			self.write_lock( blocking ) or raise Errno::EAGAIN
+			yield
+		ensure
+			self.release_write_lock
+		end
+	end
+
+
+	### Returns +true+ if the lock object currently holds either a read or
+	### write lock.
+	def locked?
+		(@status & (READ|WRITE)).nonzero?
+	end
+
+
+	### Returns +true+ if the lock object has acquired a read lock.
+	def read_locked?
+		(@status & READ).nonzero?
+	end
+
+
+	### Returns +true+ if the lock object has acquired a write lock.
+	def write_locked?
+		(@status & WRITE).nonzero?
+	end
+
+
+	### Give up a read (shared) lock. Raises an exception if no read lock
+	### has been acquired.
+	def read_unlock
+		raise Arrow::LockingError, "No read lock to release" unless
+			self.read_locked?
+		self.log.debug "Releasing read lock"
+		self.release_read_lock
+		@status &= ( @status ^ READ )
+	end
+
+
+	### Release a write (exclusive) lock. Raises an exception if no write
+	### lock has been acquired.
+	def write_unlock
+		raise Arrow::LockingError, "No write lock to release" unless
+			self.write_locked?
+		self.log.debug "Releasing write lock"
+		self.release_write_lock
+		@status &= ( @status ^ WRITE )
+	end
+
+
+	### Release any locks acquired by this lock object.
+	def release_all_locks
+		return false unless self.locked?
+		self.write_unlock if self.write_locked?
+		self.read_unlock if self.read_locked?
+	end
+
+
+	### 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
+		self.release_all_locks
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Interface method for concrete derivatives: acquire a read lock
+	### through whatever mechanism is being implemented. If +blocking+ is
+	### +true+, the method should only return if the lock was successfully
+	### acquired. If +blocking+ is +false+, this method should attempt the
+	### lock and return +false+ immediately if the lock was not able to the
+	### acquired. Concrete implementations should *not* call +super+ for
+	### this method.
+	def acquire_read_lock( blocking )
+		raise UnimplementedError,
+			"%s does not provide an implementation of #acquire_read_lock." %
+			self.class.name
+	end
+
+
+	### Interface method for concrete derivatives: acquire a write lock
+	### through whatever mechanism is being implemented. If +blocking+ is
+	### +true+, the method should only return if the lock was successfully
+	### acquired. If +blocking+ is +false+, this method should attempt the
+	### lock and return +false+ immediately if the lock was not able to the
+	### acquired. Concrete implementations should *not* call +super+ for
+	### this method.
+	def acquire_write_lock( blocking )
+		raise UnimplementedError,
+			"%s does not provide an implementation of #acquire_write_lock." %
+			self.class.name
+	end
+
+
+	### Interface method for concrete derivatives: release a read lock
+	### through whatever mechanism is being implemented. Concrete
+	### implementations should *not* call +super+ for this method.
+	def release_read_lock
+		raise UnimplementedError,
+			"%s does not provide an implementation of #release_read_lock." %
+			self.class.name
+	end
+
+
+	### Interface method for concrete derivatives: release a write lock
+	### through whatever mechanism is being implemented. Concrete
+	### implementations should *not* call +super+ for this method.
+	def release_write_lock
+		raise UnimplementedError,
+			"%s does not provide an implementation of #release_write_lock." %
+			self.class.name
+	end
+
+end # class Arrow::Session::Lock
+
+