strelka 0.0.1.pre.308 → 0.0.1.pre.309

data/ChangeLog

@@ -1,10 +1,17 @@
+2012-09-25  Michael Granger  <ged@FaerieMUD.org>
+
+	* lib/strelka/constants.rb, lib/strelka/cookie.rb,
+	lib/strelka/exceptions.rb, spec/strelka/cookie_spec.rb:
+	Updating Strelka::Cookie to adhere to rfc6265
+	[04568539aa83] [tip]
+
 2012-09-21  Michael Granger  <ged@FaerieMUD.org>
 
 	* Manifest.txt, lib/strelka/testing.rb, spec/lib/helpers.rb:
 	Split out some testing helper functions and RSpec matchers.
 
 	Put them into 'strelka/testing' ala 'mongrel2/testing'.
-	[c58b05ad837b] [tip]
+	[c58b05ad837b]
 
 	* lib/strelka/constants.rb:
 	Header fix
@@ -58,7 +65,7 @@
 
 	Got most of the default plugins covered at least minimally. Split
 	out the rest of the manual into RDoc pages.
-	[41ef7a20e7cb] [github/master]
+	[41ef7a20e7cb]
 
 2012-08-24  Mahlon E. Smith  <mahlon@martini.nu>
 
@@ -1065,7 +1072,7 @@
 
 	* lib/strelka/app/errors.rb, spec/strelka/app/errors_spec.rb:
 	Add documentation for the Errors plugin, improve test coverage.
-	[ff3ef6e5a7a1] [github/master@default]
+	[ff3ef6e5a7a1]
 
 	* Manifest.txt:
 	Add session files to the manifest

data/lib/strelka/constants.rb

@@ -2,6 +2,7 @@
 # vim: set nosta noet ts=4 sw=4:
 # encoding: utf-8
 
+require 'uri'
 require 'mongrel2/constants'
 require 'strelka' unless defined?( Strelka )
 
@@ -30,5 +31,70 @@ module Strelka::Constants
 
 	end # module HTTP
 
+
+	# Constants for parsing Cookie headers, mostly taken from
+	# RFC6265 - HTTP State Management Mechanism
+	#
+	#    http://tools.ietf.org/html/rfc6265
+	#
+	module CookieHeader
+
+		# Literals
+		CRLF     = "\r\n"
+		WSP      = '[\\x20\\t]'
+
+		# OWS            = *( [ obs-fold ] WSP )
+		#                     ; "optional" whitespace
+		# obs-fold       = CRLF
+		OBS_FOLD = CRLF
+		OWS      = /(#{OBS_FOLD}#{WSP})*/
+
+		# CTL            = <any US-ASCII control character
+		#                   (octets 0 - 31) and DEL (127)>
+		CTL = '[:cntrl:]'
+
+		# separators     = "(" | ")" | "<" | ">" | "@"
+		#               | "," | ";" | ":" | "\" | <">
+		#               | "/" | "[" | "]" | "?" | "="
+		#               | "{" | "}" | SP | HT
+		SEPARATORS = '\\x28\\x29\\x3c\\x3e\\x40' +
+		             '\\x2c\\x3b\\x3a\\x5c\\x22' +
+		             '\\x2f\\x5b\\x5d\\x3f\\x3d' +
+		             '\\x7b\\x7d\x20\x09'
+
+		# Double-quote
+		DQUOTE = '"'
+
+		# token          = 1*<any CHAR except CTLs or separators>
+		TOKEN = %r{ [^#{CTL}#{SEPARATORS}]+ }x
+
+		# cookie-name       = token
+		COOKIE_NAME = /(?<cookie_name>#{TOKEN})/
+
+		# cookie-octet      = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+		#                    ; US-ASCII characters excluding CTLs,
+		#                    ; whitespace DQUOTE, comma, semicolon,
+		#                    ; and backslash
+		COOKIE_OCTET = '[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]'
+
+		# cookie-value      = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
+		COOKIE_VALUE = %r{(?<cookie_value>
+			#{COOKIE_OCTET}*
+			|
+			#{DQUOTE} #{COOKIE_OCTET}*? #{DQUOTE}
+		)}x
+
+		# cookie-pair       = cookie-name "=" cookie-value
+		COOKIE_PAIR = %r{(?<cookie_pair>
+			#{COOKIE_NAME}
+			=
+			#{COOKIE_VALUE}
+		)}x
+
+		# Version option (not part of RFC6265)
+		COOKIE_VERSION = /;\s*Version=(?<version>\d+)/i
+
+	end # module Cookie
+
 end # module Strelka::Constants
 

data/lib/strelka/cookie.rb

@@ -4,10 +4,11 @@
 
 require 'date'
 require 'time'
-require 'uri'
 require 'loggability'
 
 require 'strelka' unless defined?( Strelka )
+require 'strelka/exceptions'
+require 'strelka/constants'
 require 'strelka/mixins'
 
 # The Strelka::Cookie class, a class for parsing and generating HTTP cookies.
@@ -26,6 +27,7 @@ require 'strelka/mixins'
 # * http://tools.ietf.org/html/rfc6265
 #
 class Strelka::Cookie
+	include Strelka::Constants::CookieHeader
 	extend Loggability
 
 	# Loggability API -- set up logging under the 'strelka' log host
@@ -35,47 +37,6 @@ class Strelka::Cookie
 	# 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,
@@ -90,16 +51,7 @@ class Strelka::Cookie
 	### 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) }
+		return string.gsub( /^"|"$/, '' )
 	end
 
 
@@ -108,49 +60,33 @@ class Strelka::Cookie
 	def self::parse( header )
 		return {} if header.nil? or header.empty?
 		self.log.debug "Parsing cookie header: %p" % [ header ]
-		cookies = []
+		cookies = {}
 		version = 0
 		header = header.strip
 
 		# "$Version" = value
-		if COOKIE_VERSION.match( header )
-			self.log.debug "  Found cookie version %p" % [ $1 ]
-			version = Integer( dequote($1) )
+		if m = COOKIE_VERSION.match( header )
+			self.log.debug "  Found cookie version %p" % [ m[:version] ]
+			version = Integer( dequote(m[:version]) )
 			header.slice!( COOKIE_VERSION )
 		end
 
-		# 1*((";" | ",") NAME "=" VALUE [";" path] [";" domain])
-		header.split( /[,;]\s*/ ).each do |pair|
-			self.log.debug "  Found pair %p" % [ pair ]
-			key, valstr = pair.split( /=/, 2 ).collect {|s| s.strip }
-
-			case key
-			when COOKIE_PATH
-				self.log.debug "    -> cookie-path %p" % [ valstr ]
-				cookies.last.path = dequote( valstr ) unless cookies.empty?
-
-			when COOKIE_DOMAIN
-				self.log.debug "    -> cookie-domain %p" % [ valstr ]
-				cookies.last.domain = dequote( valstr ) unless cookies.empty?
-
-			when HTTP_TOKEN
-				values = parse_valuestring( valstr )
-				self.log.debug "    -> cookie-values %p" % [ values ]
-				cookies << new( key, values, :version => version )
-
-			else
-				self.log.warn \
-					"Malformed cookie header %p: %p is not a valid token; ignoring" %
-					[ header, key ]
-			end
-		end
+		# cookie-header = "Cookie:" OWS cookie-string OWS
+		# cookie-string = cookie-pair *( ";" SP cookie-pair )
+		header.split( /;\x20/ ).each do |cookie_pair|
+			self.log.debug "  parsing cookie-pair: %p" % [ cookie_pair ]
+			next unless match = cookie_pair.match( COOKIE_PAIR )
 
-		# 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
+			self.log.debug "  matched cookie: %p" % [ match ]
+			name = match[:cookie_name].untaint
+			value = match[:cookie_value]
+			value = self.dequote( value ) if value.start_with?( DQUOTE )
+			value = nil if value.empty?
+
+			cookies[ name.to_sym ] = new( name, value, :version => version )
 		end
+
+		return cookies
 	end
 
 
@@ -161,33 +97,33 @@ class Strelka::Cookie
 	### Create a new Strelka::Cookie object with the specified +name+ and
 	### +values+. Valid options are:
 	###
-	### [\version]
+	### \version::
 	###   The cookie version. 0 (the default) is fine for most uses
-	### [\domain]
+	### \domain::
 	###   The domain the cookie belongs to.
-	### [\path]
+	### \path::
 	###   The path the cookie applies to.
-	### [\secure]
+	### \secure::
 	###   The cookie's 'secure' flag.
-	### [\expires]
+	### \expires::
 	###   The cookie's expiration (a Time object). See expires= for valid
 	###   values.
-	### [\max_age]
+	### \max_age::
 	###   The lifetime of the cookie, in seconds.
-	### [\comment]
-	###   Cookie comment; see #comment= for details.
-	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
+	### \httponly::
+	###   HttpOnly flag.
+	def initialize( name, value, options={} )
+		self.log.debug "New cookie: %p = %p (%p)" % [ name, value, options ]
+		@name     = name
+		@value    = value
+
+		@domain   = nil
+		@path     = nil
+		@secure   = false
+		@httponly = false
+		@max_age  = nil
+		@expires  = nil
+		@version  = 0
 
 		options.each do |meth, val|
 			self.__send__( "#{meth}=", val )
@@ -203,8 +139,8 @@ class Strelka::Cookie
 	# The name of the cookie
 	attr_accessor :name
 
-	# The Array of cookie values
-	attr_accessor :values
+	# The string value of the cookie
+	attr_reader :value
 
 	# The cookie version. 0 (the default) is fine for most uses
 	attr_accessor :version
@@ -218,30 +154,66 @@ class Strelka::Cookie
 	# The cookie's 'secure' flag.
 	attr_writer :secure
 
+	# The cookie's HttpOnly flag
+	attr_accessor :httponly
+
 	# 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
 
+	### Set the new value of the cookie to +cookie_octets+. This raises an exception
+	### if +cookie_octets+ contains any invalid characters. If your value contains
+	### non-US-ASCII characters; control characters; or comma, semicolon, or backslash.
+	def value=( cookie_octets )
+		self.log.debug "Setting cookie value to: %p" % [ cookie_octets ]
+		raise Strelka::CookieError,
+			"invalid cookie value; value must be composed of non-control us-ascii characters " +
+			"other than SPACE, double-quote, comma, semi-colon, and backslash. " +
+			"Use #base64_value= for storing arbitrary data." unless
+			cookie_octets =~ /^#{COOKIE_VALUE}$/
 
-	### Return the first value stored in the cookie as a String.
-	def value
-		return @values.first
+		@value = cookie_octets
 	end
 
 
+	### Store the base64'ed +data+ as the cookie value. This is just a convenience
+	### method for:
+	###
+	###     cookie.value = [data].pack('m').strip
+	###
+	def binary_value=( data )
+		self.log.debug "Setting cookie value to base64ed %p" % [ data ]
+		self.value = [ data ].pack( 'm' ).strip
+	end
+	alias_method :wrapped_value=, :binary_value=
+
+
+	### Fetch the cookie's data after un-base64ing it. This is just a convenience
+	### method for:
+	###
+	###     cookie.value.unpack( 'm' ).first
+	###
+	def binary_value
+		return self.value.unpack( 'm' ).first
+	end
+	alias_method :wrapped_value, :binary_value
+
+
 	### Returns +true+ if the secure flag is set
 	def secure?
 		return @secure ? true : false
 	end
 
+
+	### Returns +true+ if the 'httponly' flag is set
+	def httponly?
+		return @httponly ? 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
@@ -307,10 +279,10 @@ class Strelka::Cookie
 		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?
+		rval << '; ' << 'HttpOnly' if self.httponly?
+		rval << '; ' << 'Secure' if self.secure?
 
 		return rval
 	end
@@ -335,7 +307,7 @@ class Strelka::Cookie
 
 	### Make a uri-escaped value string for the cookie's current +values+.
 	def make_valuestring
-		return self.values.collect {|val| URI.encode_www_form_component(val) }.join('&')
+		return self.value
 	end
 
 

data/lib/strelka/exceptions.rb

@@ -28,5 +28,8 @@ module Strelka
 	# An exception raised when there is a problem with an application plugin.
 	class PluginError < Error; end
 
+	# An exception raised when there is a problem parsing or creating a cookie
+	class CookieError < Error; end
+
 end # module Strelka
 

data/spec/strelka/cookie_spec.rb

@@ -42,89 +42,18 @@ describe Strelka::Cookie do
 
 		result.should be_a( Hash )
 		result.should have(1).member
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b']
-	end
-
-	it "parses a cookie header field with a cookie with multiple values as a cookie with multiple values" do
-		result = Strelka::Cookie.parse( 'a=b&c' )
-
-		result.should be_a( Hash )
-		result.should have(1).member
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b', 'c']
-	end
-
-	it "parses a cookie header field with multiple cookies and multiple values correctly" do
-		result = Strelka::Cookie.parse( 'a=b&c; f=o&o' )
-
-		result.should be_a( Hash )
-		result.should have(2).members
-
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b', 'c']
-
-		result['f'].should be_a( Strelka::Cookie )
-		result['f'].name.should == 'f'
-		result['f'].value.should == 'o'
-		result['f'].values.should == ['o', 'o']
+		result[:a].should be_a( Strelka::Cookie )
+		result[:a].name.should == 'a'
+		result[:a].value.should == 'b'
 	end
 
 	it "parses a cookie header field with an empty value as a cookie with a nil value" do
 		result = Strelka::Cookie.parse( 'a=' )
 
 		result.should have( 1 ).member
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should be_nil()
-		result['a'].values.should == []
-	end
-
-	it "parses a cookie header field with a version as a cookie with a version" do
-		result = Strelka::Cookie.parse( %{$Version=1; a="b"} )
-
-		result.should be_a( Hash )
-		result.should have( 1 ).member
-
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b']
-		result['a'].version.should == 1
-	end
-
-	it "parses a cookie header field with a path as a cookie with a path" do
-		result = Strelka::Cookie.parse( %{a=b; $Path=/Strelka} )
-
-		result.should be_a( Hash )
-		result.should have( 1 ).member
-
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b']
-
-		result['a'].path.should == "/Strelka"
-	end
-
-	it "parses a cookie header field with a domain as a cookie with a domain" do
-		result = Strelka::Cookie.parse( %{a=b; $domain=rubycrafters.com} )
-
-		result.should be_a( Hash )
-		result.should have( 1 ).member
-
-		result['a'].should be_a( Strelka::Cookie )
-		result['a'].name.should == 'a'
-		result['a'].value.should == 'b'
-		result['a'].values.should == ['b']
-
-		result['a'].domain.should == '.rubycrafters.com'
+		result[:a].should be_a( Strelka::Cookie )
+		result[:a].name.should == 'a'
+		result[:a].value.should be_nil()
 	end
 
 	it "doesn't raise an error if asked to parse an invalid cookie header" do
@@ -143,30 +72,31 @@ describe Strelka::Cookie do
 			@cookie.to_s.should == 'by_rickirac=9917eb'
 		end
 
-		it "still stringifies correctly with two values" do
-			@cookie.values += ['brer lapin']
-			@cookie.to_s.should == "by_rickirac=9917eb&brer+lapin"
-		end
-
 		it "stringifies with a version number if its version is set to something other than 0" do
 			@cookie.version = 1
-			@cookie.to_s.should == %{by_rickirac=9917eb; Version=1}
+			@cookie.to_s.should =~ /; Version=1/i
 		end
 
 		it "stringifies with a domain if one is set" do
 			@cookie.domain = '.example.com'
-			@cookie.to_s.should == %{by_rickirac=9917eb; Domain=.example.com}
+			@cookie.to_s.should =~ /; Domain=.example.com/
 		end
 
 		it "stringifies with a dot prepended to the domain if the set doesn't have one" do
 			@cookie.domain = 'example.com'
-			@cookie.to_s.should == %{by_rickirac=9917eb; Domain=.example.com}
+			@cookie.to_s.should =~ /; Domain=.example.com/i
 		end
 
-		it "stringifies correctly even if one of its values contains a semicolon" do
-			@cookie.values += [%{"modern technology"; ain't it a paradox?}]
-			@cookie.to_s.should ==
-				"by_rickirac=9917eb&%22modern+technology%22%3B+ain%27t+it+a+paradox%3F"
+		it "raises an exception if the cookie value would be invalid when serialized" do
+			expect {
+				@cookie.value = %{"modern technology"; ain't it a paradox?}
+			}.to raise_error( Strelka::CookieError, /invalid cookie value/i )
+		end
+
+		it "provides a convenience mechanism for setting the value to binary data" do
+			@cookie.binary_value = %{"modern technology"; ain't it a paradox?}
+			@cookie.to_s.should == 'by_rickirac=Im1vZGVybiB0ZWNobm9sb2d5IjsgYWluJ3Qg' +
+				'aXQgYSBwYXJhZG94Pw=='
 		end
 
 		it "stringifies with an expires date if one is set" do
@@ -174,6 +104,28 @@ describe Strelka::Cookie do
 			@cookie.to_s.should == 'by_rickirac=9917eb; Expires=Wed, 14 Mar 2012 21:39:44 GMT'
 		end
 
+		it "stringifies with a max age if the 'max age' is set" do
+			@cookie.max_age = 3600
+			@cookie.to_s.should == 'by_rickirac=9917eb; Max-age=3600'
+		end
+
+		it "stringifies with a Secure flag if secure is set" do
+			@cookie.secure = true
+			@cookie.to_s.should =~ /; Secure/i
+		end
+
+		it "stringifies with an HttpOnly flag if httponly is set" do
+			@cookie.httponly = true
+			@cookie.to_s.should =~ /; HttpOnly/i
+		end
+
+		it "stringifies with both Secure and HttpOnly flags if they're both set" do
+			@cookie.httponly = true
+			@cookie.secure = true
+			@cookie.to_s.should =~ /; HttpOnly/i
+			@cookie.to_s.should =~ /; Secure/i
+		end
+
 		it "hashes the same as another cookie with the same name, regardless of value" do
 			@cookie.hash.should == Strelka::Cookie.new('by_rickirac', 'something_else').hash
 		end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strelka
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre.308
+  version: 0.0.1.pre.309
   prerelease: 
 platform: ruby
 authors:
@@ -36,7 +36,7 @@ cert_chain:
   YUhDS0xaZFNLai9SSHVUT3QrZ2JsUmV4OEZBaDhOZUEKY21saFhlNDZwWk5K
   Z1dLYnhaYWg4NWpJang5NWhSOHZPSStOQU01aUg5a09xSzEzRHJ4YWNUS1Bo
   cWo1UGp3RgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
-date: 2012-09-22 00:00:00.000000000 Z
+date: 2012-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configurability