strelka 0.0.1.pre129 → 0.0.1.pre148

data/lib/strelka/cookie.rb

@@ -0,0 +1,357 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'date'
+require 'time'
+require 'uri'
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/mixins'
+
+# The Strelka::Cookie class, a class for parsing and generating HTTP cookies.
+#
+# Large parts of this code were copied from the Webrick::Cookie class
+# in the Ruby standard library. The copyright statements for that module
+# are:
+#
+#   Author: IPR -- Internet Programming with Ruby -- writers
+#   Copyright (c) 2000, 2001 TAKAHASHI Masayoshi, GOTOU Yuuzou
+#   Copyright (c) 2002 Internet Programming with Ruby writers. All rights
+#   reserved.
+#
+class Strelka::Cookie
+	include Strelka::Loggable
+
+	# The format of the date field
+	COOKIE_DATE_FORMAT = '%a, %d-%b-%Y %H:%M:%S GMT'
+
+	### RFC 2109: HTTP State Management Mechanism
+	# When it sends a request to an origin server, the user agent sends a
+	# Cookie request header to the origin server if it has cookies that are
+	# applicable to the request, based on
+	#
+	#   * the request-host;
+	#   * the request-URI;
+	#   * the cookie's age.
+	#
+	# The syntax for the header is:
+	#
+	# cookie          =       "Cookie:" cookie-version
+	#                            1*((";" | ",") cookie-value)
+	# cookie-value    =       NAME "=" VALUE [";" path] [";" domain]
+	# cookie-version  =       "$Version" "=" value
+	# NAME            =       attr
+	# VALUE           =       value
+	# path            =       "$Path" "=" value
+	# domain          =       "$Domain" "=" value
+
+	# Parser constants
+	COOKIE_VERSION = /\$Version\s*=\s*(.+)\s*[,;]/
+	COOKIE_PATH    = /\$Path/i
+	COOKIE_DOMAIN  = /\$Domain/i
+
+	### RFC2068: Hypertext Transfer Protocol -- HTTP/1.1
+	# CTL            = <any US-ASCII control character
+	#                  (octets 0 - 31) and DEL (127)>
+	# token          = 1*<any CHAR except CTLs or tspecials>
+	#
+	# tspecials      = "(" | ")" | "<" | ">" | "@"
+	#                | "," | ";" | ":" | "\" | <">
+	#                | "/" | "[" | "]" | "?" | "="
+	#                | "{" | "}" | SP | HT
+
+	# Cookie-value parser constants
+	CTLs           = "[:cntrl:]"
+	TSPECIALS      = Regexp.quote( ' "(),/:;<=>?@[\\]{}' )
+	NON_TOKEN_CHAR = /[#{CTLs}#{TSPECIALS}]/s
+	HTTP_TOKEN     = /\A[^#{CTLs}#{TSPECIALS}]+\z/s
+
+	# Number of seconds in the various offset types
+	UNIT_SECONDS = {
+		's' => 1,
+		'm' => 60,
+		'h' => 60*60,
+		'd' => 60*60*24,
+		'M' => 60*60*24*30,
+		'y' => 60*60*24*365,
+	}
+
+
+	### Strip surrounding double quotes from a copy of the specified string
+	### and return it.
+	def self::dequote( string )
+		/^"((?:[^"]+|\\.)*)"/.match( string ) ? $1 : string.dup
+	end
+
+
+	### Parse a cookie value string, returning an Array of Strings
+	def self::parse_valuestring( valstr )
+		return [] unless valstr
+		valstr = dequote( valstr )
+
+		return valstr.split('&').collect{|str| URI.decode_www_form_component(str) }
+	end
+
+
+	### Parse the specified 'Cookie:' +header+ value and return a Hash of
+	### one or more new Strelka::Cookie objects, keyed by name.
+	def self::parse( header )
+		return {} if header.nil? or header.empty?
+		Strelka.log.debug "Parsing cookie header: %p" % [ header ]
+		cookies = []
+		version = 0
+		header = header.strip
+
+		# "$Version" = value
+		if COOKIE_VERSION.match( header )
+			Strelka.log.debug "  Found cookie version %p" % [ $1 ]
+			version = Integer( dequote($1) )
+			header.slice!( COOKIE_VERSION )
+		end
+
+		# 1*((";" | ",") NAME "=" VALUE [";" path] [";" domain])
+		header.split( /[,;]\s*/ ).each do |pair|
+			Strelka.log.debug "  Found pair %p" % [ pair ]
+			key, valstr = pair.split( /=/, 2 ).collect {|s| s.strip }
+
+			case key
+			when COOKIE_PATH
+				Strelka.log.debug "    -> cookie-path %p" % [ valstr ]
+				cookies.last.path = dequote( valstr ) unless cookies.empty?
+
+			when COOKIE_DOMAIN
+				Strelka.log.debug "    -> cookie-domain %p" % [ valstr ]
+				cookies.last.domain = dequote( valstr ) unless cookies.empty?
+
+			when HTTP_TOKEN
+				values = parse_valuestring( valstr )
+				Strelka.log.debug "    -> cookie-values %p" % [ values ]
+				cookies << new( key, values, :version => version )
+
+			else
+				Strelka.log.warn \
+					"Malformed cookie header %p: %p is not a valid token; ignoring" %
+					[ header, key ]
+			end
+		end
+
+		# Turn the array into a Hash, ignoring all but the first instance of
+		# a cookie with the same name
+		return cookies.inject({}) do |hash,cookie|
+			hash[cookie.name] = cookie unless hash.key?( cookie.name )
+			hash
+		end
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new Strelka::Cookie object with the specified +name+ and
+	### +values+.
+	def initialize( name, values, options={} )
+		values   = [ values ] unless values.is_a?( Array )
+		@name    = name
+		@values  = values
+
+		@domain  = nil
+		@path    = nil
+		@secure  = false
+		@comment = nil
+		@max_age = nil
+		@expires = nil
+		@version = 0
+
+		options.each do |meth, val|
+			self.__send__( "#{meth}=", val )
+		end
+	end
+
+
+
+	######
+	public
+	######
+
+	# The name of the cookie
+	attr_accessor :name
+
+	# The Array of cookie values
+	attr_accessor :values
+
+	# The cookie version. 0 (the default) is fine for most uses
+	attr_accessor :version
+
+	# The domain the cookie belongs to
+	attr_reader :domain
+
+	# The path the cookie applies to
+	attr_accessor :path
+
+	# The cookie's 'secure' flag.
+	attr_writer :secure
+
+	# The cookie's expiration (a Time object)
+	attr_reader :expires
+
+	# The lifetime of the cookie, in seconds.
+	attr_reader :max_age
+
+	# Because cookies can contain private information about a
+	# user, the Cookie attribute allows an origin server to document its
+	# intended use of a cookie.  The user can inspect the information to
+	# decide whether to initiate or continue a session with this cookie.
+	attr_accessor :comment
+
+
+	### Return the first value stored in the cookie as a String.
+	def value
+		return @values.first
+	end
+
+
+	### Returns +true+ if the secure flag is set
+	def secure?
+		return @secure ? true : false
+	end
+
+	# Set the lifetime of the cookie. The value is a decimal non-negative
+	# integer.  After +delta_seconds+ seconds elapse, the client should
+	# discard the cookie.  A value of zero means the cookie should be
+	# discarded immediately.
+	def max_age=( delta_seconds )
+		@max_age = Integer( delta_seconds )
+	end
+
+
+	### Set the domain for which the cookie is valid.
+	def domain=( newdomain )
+		newdomain = ".#{newdomain}" unless newdomain[0] == ?.
+		@domain = newdomain.dup
+	end
+
+
+	### Set the cookie's expires field. The value can be either a Time object
+	### or a String in any of the following formats:
+	### +30s::
+	###   30 seconds from now
+	### +10m::
+	###   ten minutes from now
+	### +1h::
+	###   one hour from now
+	### -1d::
+	###   yesterday (i.e. "ASAP!")
+	### now::
+	###   immediately
+	### +3M::
+	###   in three months
+	### +10y::
+	###   in ten years time
+	### Thursday, 25-Apr-1999 00:40:33 GMT::
+	###   at the indicated time & date
+	def expires=( time )
+		case time
+		when NilClass
+			@expires = nil
+
+		when Date
+			@expires = Time.parse( time.ctime )
+
+		when Time
+			@expires = time
+
+		else
+			@expires = parse_time_delta( time )
+		end
+	end
+
+
+	### Set the cookie expiration to a time in the past
+	def expire!
+		self.expires = Time.at(0)
+	end
+
+
+	### Return the cookie as a String
+	def to_s
+		rval = "%s=%s" % [ self.name, make_valuestring(self.values) ]
+
+		rval << make_field( "Version", self.version ) if self.version.nonzero?
+		rval << make_field( "Domain", self.domain )
+		rval << make_field( "Expires", make_cookiedate(self.expires) ) if self.expires
+		rval << make_field( "Max-Age", self.max_age )
+		rval << make_field( "Comment", self.comment )
+		rval << make_field( "Path", self.path )
+
+		rval << "; " << "Secure" if self.secure?
+
+		return rval
+	end
+
+
+	### Return +true+ if other_cookie has the same name as the receiver.
+	def eql?( other_cookie )
+		self.log.debug "Comparing %p with other cookie: %p" % [ self, other_cookie ]
+		return (self.name == other_cookie.name) ? true : false
+	end
+
+
+	### Generate a Fixnum hash value for this object. Uses the hash of the cookie's name.
+	def hash
+		return self.name.to_s.hash
+	end
+
+
+
+	#######
+	private
+	#######
+
+	### Make a cookie field for appending to the outgoing header for the
+	### specified +value+ and +field_name+. If +value+ is nil, an empty
+	### string will be returned.
+	def make_field( field_name, value )
+		return '' if value.nil? || (value.is_a?(String) && value.empty?)
+
+		return "; %s=%s" % [
+			field_name.capitalize,
+			value
+		]
+	end
+
+
+	### Parse a time delta like those accepted by #expires= into a Time
+	### object.
+	def parse_time_delta( time )
+		return Time.now if time.nil? || time == 'now'
+		return Time.at( Integer(time) ) if /^\d+$/.match( time )
+
+		if /^([+-]?(?:\d+|\d*\.\d*))([mhdMy]?)/.match( time )
+			offset = (UNIT_SECONDS[$2] || 1) * Integer($1)
+			return Time.now + offset
+		end
+
+		return Time.parse( time )
+	end
+
+
+	### Make a uri-escaped value string for the given +values+
+	def make_valuestring( values )
+		return values.collect {|val| URI.encode_www_form_component(val) }.join('&')
+	end
+
+
+	### Make an RFC2109-formatted date out of +date+.
+	def make_cookiedate( date )
+		return date.gmtime.strftime( COOKIE_DATE_FORMAT )
+	end
+
+
+	### Quote a copy of the given string and return it.
+	def quote( val )
+		return %q{"%s"} % [ val.to_s.gsub(/"/, '\\"') ]
+	end
+
+end # class Strelka::Cookie

data/lib/strelka/cookieset.rb

@@ -0,0 +1,117 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/cookie'
+require 'set'
+require 'forwardable'
+
+
+# An object class which provides a convenient way of accessing a set of Strelka::Cookies.
+#
+# == Synopsis
+#
+#   cset = Strelka::CookieSet.new()
+#   cset = Strelka::CookieSet.new( cookies )
+#
+#   cset['cookiename']  # => Strelka::Cookie
+#
+#   cset['cookiename'] = cookie_object
+#   cset['cookiename'] = 'cookievalue'
+#   cset[:cookiename] = 'cookievalue'
+#   cset << Strelka::Cookie.new( *args )
+#
+#   cset.include?( 'cookiename' )
+#   cset.include?( cookie_object )
+#
+#   cset.each do |cookie|
+#      ...
+#   end
+#
+# == Authors
+#
+# * Michael Granger <ged@FaerieMUD.org>
+# * Jeremiah Jordan <phaedrus@FaerieMUD.org>
+#
+class Strelka::CookieSet
+	extend Forwardable
+	include Enumerable
+
+
+	### Parse the Cookie header of the specified +request+ into Strelka::Cookie objects
+	### and return them in a new CookieSet.
+	def self::parse( request )
+		Strelka.log.debug "Parsing cookies from header: %p" % [ request.header.cookie ]
+		cookies = Strelka::Cookie.parse( request.header.cookie )
+		Strelka.log.debug "  found %d cookies: %p" % [ cookies.length, cookies ]
+		return new( cookies.values )
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new CookieSet prepopulated with the given cookies
+	def initialize( *cookies )
+		@cookie_set = Set.new( cookies.flatten )
+	end
+
+
+	######
+	public
+	######
+
+	def_delegators :@cookie_set, :each
+
+
+	### Returns the number of cookies in the cookieset
+	def length
+		return @cookie_set.length
+	end
+	alias_method :size, :length
+
+
+	### Index operator method: returns the Strelka::Cookie with the given +name+ if it
+	### exists in the cookieset.
+	def []( name )
+		name = name.to_s
+		return @cookie_set.find {|cookie| cookie.name == name }
+	end
+
+
+	### Index set operator method: set the cookie that corresponds to the given +name+
+	### to +value+. If +value+ is not an Strelka::Cookie, one with be created and its
+	### value set to +value+.
+	def []=( name, value )
+		value = Strelka::Cookie.new( name.to_s, value ) unless value.is_a?( Strelka::Cookie )
+		raise ArgumentError, "cannot set a cookie named '%s' with a key of '%s'" %
+			[ value.name, name ] if value.name.to_s != name.to_s
+
+		self << value
+	end
+
+
+	### Returns +true+ if the CookieSet includes either a cookie with the given name or
+	### an Strelka::Cookie object.
+	def include?( name_or_cookie )
+		return true if @cookie_set.include?( name_or_cookie )
+		name = name_or_cookie.to_s
+		return self[name] ? true : false
+	end
+	alias_method :key?, :include?
+
+
+	### Append operator: Add the given +cookie+ to the set, replacing an existing
+	### cookie with the same name if one exists.
+	def <<( cookie )
+		@cookie_set.delete( cookie )
+		@cookie_set.add( cookie )
+
+		return self
+	end
+
+
+end # class Strelka::CookieSet
+

data/lib/strelka/httprequest/acceptparams.rb

@@ -1,12 +1,14 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka/mixins'
 require 'strelka/httprequest'
 
 class Strelka::HTTPRequest
 
-	# A parser for request Accept, Accept-encoding, Accept-charset, and Accept-language 
-	# header values. They provide weighted and wildcard comparisions between two values 
+	# A parser for request Accept, Accept-encoding, Accept-charset, and Accept-language
+	# header values. They provide weighted and wildcard comparisions between two values
 	# of the same field.
 	#
 	#   require 'strelka/httprequest/acceptparam'
@@ -200,7 +202,7 @@ class Strelka::HTTPRequest
 	# A mediatype parameter such as one you'd find in an Accept header.
 	class MediaType < Strelka::HTTPRequest::AcceptParam
 
-		### Parse the given +accept_param+ as a mediatype and return a 
+		### Parse the given +accept_param+ as a mediatype and return a
 		### Strelka::HTTPRequest::MediaType object for it.
 		def self::parse( accept_param )
 			raise ArgumentError, "Bad Accept param: no media-range in %p" % [accept_param] unless
@@ -239,7 +241,7 @@ class Strelka::HTTPRequest
 	# Accept-Language header.
 	class Language < Strelka::HTTPRequest::AcceptParam
 
-		### Parse the given +accept_param+ as a language range and return a 
+		### Parse the given +accept_param+ as a language range and return a
 		### Strelka::HTTPRequest::Language object for it.
 		def self::parse( accept_param )
 			language_range, *stuff = accept_param.split( /\s*;\s*/ )
@@ -262,7 +264,7 @@ class Strelka::HTTPRequest
 			return [ self.primary_tag, self.subtag ].compact.join( '-' )
 		end
 
-		### Return the parameter as a String suitable for inclusion in an 
+		### Return the parameter as a String suitable for inclusion in an
 		### Accept-language header.
 		def to_s
 			return [
@@ -278,7 +280,7 @@ class Strelka::HTTPRequest
 	# A content encoding parameter, such as one you'd find in an Accept-Encoding header.
 	class Encoding < Strelka::HTTPRequest::AcceptParam
 
-		### Parse the given +accept_param+ as a content coding and return a 
+		### Parse the given +accept_param+ as a content coding and return a
 		### Strelka::HTTPRequest::Encoding object for it.
 		def self::parse( accept_param )
 			content_coding, *stuff = accept_param.split( /\s*;\s*/ )
@@ -295,7 +297,7 @@ class Strelka::HTTPRequest
 		alias_method :content_coding, :type
 
 
-		### Return the parameter as a String suitable for inclusion in an 
+		### Return the parameter as a String suitable for inclusion in an
 		### Accept-language header.
 		def to_s
 			return [
@@ -311,7 +313,7 @@ class Strelka::HTTPRequest
 	# A content character-set parameter, such as one you'd find in an Accept-Charset header.
 	class Charset < Strelka::HTTPRequest::AcceptParam
 
-		### Parse the given +accept_param+ as a charset and return a 
+		### Parse the given +accept_param+ as a charset and return a
 		### Strelka::HTTPRequest::Charset object for it.
 		def self::parse( accept_param )
 			charset, *stuff = accept_param.split( /\s*;\s*/ )
@@ -328,7 +330,7 @@ class Strelka::HTTPRequest
 		alias_method :name, :type
 
 
-		### Return the parameter as a String suitable for inclusion in an 
+		### Return the parameter as a String suitable for inclusion in an
 		### Accept-language header.
 		def to_s
 			return [

data/lib/strelka/httprequest/negotiation.rb

@@ -1,4 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka/constants'
 require 'strelka/httprequest' unless defined?( Strelka::HTTPRequest )
@@ -19,7 +21,7 @@ require 'strelka/httprequest/acceptparams'
 module Strelka::HTTPRequest::Negotiation
 	include Strelka::Constants
 
-	### Extension callback -- add instance variables to extended objects. 
+	### Extension callback -- add instance variables to extended objects.
 	def initialize( * )
 		super
 		@accepted_mediatypes = nil

data/lib/strelka/httprequest/session.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'configurability'
+
+require 'strelka/constants'
+require 'strelka/session' unless defined?( Strelka::Session )
+require 'strelka/httprequest' unless defined?( Strelka::HTTPRequest )
+
+
+# The mixin that adds methods to Strelka::HTTPRequest for session management.
+#
+#   request.session?
+#   request.session
+#
+module Strelka::HTTPRequest::Session
+	extend Configurability
+	include Strelka::Constants
+
+
+	### Extension callback -- add instance variables to extended objects.
+	def initialize( * )
+		super
+		@session_namespace = nil
+		@session = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The current session namespace
+	attr_reader :session_namespace
+
+
+	### The namespace that will be used when creating a session for this request
+	def session_namespace=( namespace )
+		self.log.debug "Setting session namespace to %p" % [ namespace ]
+		@session_namespace = namespace
+
+		# If the session has already been created, switch its current namespace
+		@session.namespace = namespace if @session
+	end
+
+
+	### Returns +true+ if the request already has an associated session object.
+	def session?
+		return !@session.nil?
+	end
+
+
+	### Return the session associated with the request, creating it if necessary.
+	def session
+		unless @session
+			@session = Strelka::App::Sessions.session_class.load_or_create( self )
+			@session.namespace = self.session_namespace
+		end
+
+		return @session
+	end
+
+
+	### Set the request's session object.
+	def session=( new_session )
+		new_session.namespace = self.session_namespace
+		@session = new_session
+	end
+
+end # module Strelka::HTTPRequest::Session
+
+

data/lib/strelka/httprequest.rb

@@ -1,4 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'yajl'
 require 'yaml'
@@ -7,6 +9,7 @@ require 'uri'
 require 'mongrel2/httprequest'
 require 'strelka' unless defined?( Strelka )
 require 'strelka/httpresponse'
+require 'strelka/cookieset'
 
 # An HTTP request class.
 class Strelka::HTTPRequest < Mongrel2::HTTPRequest
@@ -30,10 +33,11 @@ class Strelka::HTTPRequest < Mongrel2::HTTPRequest
 	### Initialize some additional stuff for Strelka requests.
 	def initialize( * ) # :notnew:
 		super
-		@uri    = nil
-		@verb   = self.headers[:method].to_sym
-		@params = nil
-		@notes  = Hash.new( &method(:autovivify) )
+		@uri     = nil
+		@verb    = self.headers[:method].to_sym
+		@params  = nil
+		@notes   = Hash.new( &method(:autovivify) )
+		@cookies = nil
 	end
 
 
@@ -114,7 +118,7 @@ class Strelka::HTTPRequest < Mongrel2::HTTPRequest
 
 
 	### Parse the request parameters and return them as a Hash. For GET requests, these are
-	### take from the query arguments, and for POST requests, from the 
+	### take from the query arguments, and for POST requests, from the
 	###
 	###   # For a handler with a route of '/user', for the request:
 	###   # "GET /user/1/profile?checkbox=1&checkbox=2&text=foo HTTP/1.1"
@@ -136,11 +140,19 @@ class Strelka::HTTPRequest < Mongrel2::HTTPRequest
 	end
 
 
+	### Fetch any cookies that accompanied the request as a Strelka::CookieSet, creating
+	### it if necessary.
+	def cookies
+		@cookies = Strelka::CookieSet.parse( self ) unless @cookies
+		return @cookies
+	end
+
+
 	#########
 	protected
 	#########
 
-	### Return a Hash of request query arguments.  
+	### Return a Hash of request query arguments.
 	### ?arg1=yes&arg2=no&arg3  #=> {'arg1' => 'yes', 'arg2' => 'no', 'arg3' => nil}
 	def parse_query_args
 		return {} if self.uri.query.nil?