strelka 0.0.1pre4 → 0.0.1.pre129

data/lib/strelka/httprequest/acceptparams.rb

@@ -0,0 +1,377 @@
+#!/usr/bin/env ruby
+
+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 
+	# of the same field.
+	#
+	#   require 'strelka/httprequest/acceptparam'
+	#   mediatype = Strelka::HTTPRequest::AcceptParam.parse_mediatype( "text/html;q=0.9;level=2" )
+	#
+	#   ap.type         #=> 'text'
+	#   ap.subtype      #=> 'html'
+	#   ap.qvalue       #=> 0.9
+	#   ap =~ 'text/*'  #=> true
+	#
+	#   language = Strelka::HTTPRequest::AcceptParam.parse_language( "en-gb" )
+	#
+	#   ap.type         #=> :en
+	#   ap.subtype      #=> :gb
+	#   ap.qvalue       #=> 1.0
+	#   ap =~ 'en'      #=> true
+	#
+	#   encoding = Strelka::HTTPRequest::AcceptParam.parse_encoding( "compress; q=0.7" )
+	#
+	#   ap.type          #=> :compress
+	#   ap.subtype       #=> nil
+	#   ap.qvalue        #=> 0.7
+	#   ap =~ 'compress' #=> true
+	#
+	#   charset = Strelka::HTTPRequest::AcceptParam.parse_charset( "koi8-r" )
+	#
+	#   ap.type          #=> 'koi8-r'
+	#   ap.subtype       #=> nil
+	#   ap.qvalue        #=> 1.0
+	#   ap =~ 'koi8-r'   #=> true
+	#
+	# == Authors
+	#
+	# * Michael Granger <ged@FaerieMUD.org>
+	# * Mahlon E. Smith <mahlon@martini.nu>
+	#
+	class AcceptParam
+		include Comparable,
+		        Strelka::Loggable,
+		        Strelka::AbstractClass
+
+
+		# The default quality value (weight) if none is specified
+		Q_DEFAULT = 1.0
+
+		# The maximum quality value
+		Q_MAX = Q_DEFAULT
+
+
+		#################################################################
+		###	I N S T A N C E   M E T H O D S
+		#################################################################
+
+		### Create a new Strelka::HTTPRequest::AcceptParam with the given media
+		### +range+, quality value (+qval+), and extensions
+		def initialize( type, subtype='*', qval=Q_DEFAULT, *extensions )
+			type    = nil if type == '*'
+			subtype = nil if subtype == '*'
+
+			@type       = type
+			@subtype    = subtype
+			@qvalue     = normalize_qvalue( qval )
+			@extensions = extensions.flatten
+		end
+
+
+		######
+		public
+		######
+
+		pure_virtual :to_s
+
+
+		# The 'type' part of the media range
+		attr_reader :type
+
+		# The 'subtype' part of the media range
+		attr_reader :subtype
+
+		# The weight of the param
+		attr_reader :qvalue
+
+		# An array of any accept-extensions specified with the parameter
+		attr_reader :extensions
+
+
+		### Match operator -- returns true if +other+ matches the receiving
+		### AcceptParam.
+		def =~( other )
+			unless other.is_a?( self.class )
+				other = self.class.parse( other.to_s ) rescue nil
+				return false unless other
+			end
+
+			# */* returns true in either side of the comparison.
+			# ASSUMPTION: There will never be a case when a type is wildcarded
+			#             and the subtype is specific. (e.g., */xml)
+			#             We gave up trying to read RFC 2045.
+			return true if other.type.nil? || self.type.nil?
+
+			# text/html =~ text/html
+			# text/* =~ text/html
+			# text/html =~ text/*
+			if other.type == self.type
+				return true if other.subtype.nil? || self.subtype.nil?
+				return true if other.subtype == self.subtype
+			end
+
+			return false
+		end
+
+
+		### Return a human-readable version of the object
+		def inspect
+			return "#<%s:0x%07x '%s/%s' q=%0.3f %p>" % [
+				self.class.name,
+				self.object_id * 2,
+				self.type || '*',
+				self.subtype || '*',
+				self.qvalue,
+				self.extensions,
+			]
+		end
+
+
+		### The weighting or "qvalue" of the parameter in the form "q=<value>"
+		def qvaluestring
+			# 3 digit precision, trim excess zeros
+			return sprintf( "q=%0.3f", self.qvalue ).gsub(/0{1,2}$/, '')
+		end
+
+
+		### Return a String containing any extensions for this parameter, joined
+		### with ';'
+		def extension_strings
+			return nil if self.extensions.empty?
+			return self.extensions.compact.join('; ')
+		end
+
+
+		### Comparable interface. Sort parameters by weight: Returns -1 if +other+
+		### is less specific than the receiver, 0 if +other+ is as specific as
+		### the receiver, and +1 if +other+ is more specific than the receiver.
+		def <=>( other )
+
+			if rval = (other.qvalue <=> @qvalue).nonzero?
+				return rval
+			end
+
+			if self.type.nil?
+				return 1 if ! other.type.nil?
+			elsif other.type.nil?
+				return -1
+			end
+
+			if self.subtype.nil?
+				return 1 if ! other.subtype.nil?
+			elsif other.subtype.nil?
+				return -1
+			end
+
+			if rval = (self.extensions.length <=> other.extensions.length).nonzero?
+				return rval
+			end
+
+			return self.to_s <=> other.to_s
+		end
+
+
+		#######
+		private
+		#######
+
+		### Given an input +qvalue+, return the Float equivalent.
+		def normalize_qvalue( qvalue )
+			return Q_DEFAULT unless qvalue
+			qvalue = Float( qvalue.to_s.sub(/q=/, '') ) unless qvalue.is_a?( Float )
+
+			if qvalue > Q_MAX
+				self.log.warn "Squishing invalid qvalue %p to %0.1f" %
+					[ qvalue, Q_DEFAULT ]
+				return Q_DEFAULT
+			end
+
+			return qvalue
+		end
+
+	end # class AcceptParam
+
+
+	# 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 
+		### Strelka::HTTPRequest::MediaType object for it.
+		def self::parse( accept_param )
+			raise ArgumentError, "Bad Accept param: no media-range in %p" % [accept_param] unless
+				accept_param.include?( '/' )
+			media_range, *stuff = accept_param.split( /\s*;\s*/ )
+			type, subtype = media_range.downcase.split( '/', 2 )
+			qval, opts = stuff.partition {|par| par =~ /^q\s*=/ }
+
+			return new( type, subtype, qval.first, *opts )
+		end
+
+
+		### The mediatype of the parameter, consisting of the type and subtype
+		### separated by '/'.
+		def mediatype
+			return "%s/%s" % [ self.type || '*', self.subtype || '*' ]
+		end
+		alias_method :mimetype, :mediatype
+		alias_method :content_type, :mediatype
+
+
+		### Return the parameter as a String suitable for inclusion in an Accept
+		### HTTP header
+		def to_s
+			return [
+				self.mediatype,
+				self.qvaluestring,
+				self.extension_strings
+			].compact.join(';')
+		end
+
+	end # class MediaType
+
+
+	# A natural language specification parameter, such as one you'd find in an
+	# Accept-Language header.
+	class Language < Strelka::HTTPRequest::AcceptParam
+
+		### 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*/ )
+			type, subtype = language_range.downcase.split( '-', 2 )
+			qval, opts = stuff.partition {|par| par =~ /^q\s*=/ }
+
+			return new( type, subtype, qval.first, *opts )
+		end
+
+
+		######
+		public
+		######
+
+		alias_method :primary_tag, :type
+		alias_method :subtag, :subtype
+
+		### Return the language range of the parameter as a String.
+		def language_range
+			return [ self.primary_tag, self.subtag ].compact.join( '-' )
+		end
+
+		### Return the parameter as a String suitable for inclusion in an 
+		### Accept-language header.
+		def to_s
+			return [
+				self.language_range,
+				self.qvaluestring,
+				self.extension_strings,
+			].compact.join( ';' )
+		end
+
+	end # class Language
+
+
+	# 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 
+		### Strelka::HTTPRequest::Encoding object for it.
+		def self::parse( accept_param )
+			content_coding, *stuff = accept_param.split( /\s*;\s*/ )
+			qval, opts = stuff.partition {|par| par =~ /^q\s*=/ }
+
+			return new( content_coding, nil, qval.first, *opts )
+		end
+
+
+		######
+		public
+		######
+
+		alias_method :content_coding, :type
+
+
+		### Return the parameter as a String suitable for inclusion in an 
+		### Accept-language header.
+		def to_s
+			return [
+				self.content_coding,
+				self.qvaluestring,
+				self.extension_strings,
+			].compact.join( ';' )
+		end
+
+	end # class Encoding
+
+
+	# 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 
+		### Strelka::HTTPRequest::Charset object for it.
+		def self::parse( accept_param )
+			charset, *stuff = accept_param.split( /\s*;\s*/ )
+			qval, opts = stuff.partition {|par| par =~ /^q\s*=/ }
+
+			return new( charset, nil, qval.first, *opts )
+		end
+
+
+		######
+		public
+		######
+
+		alias_method :name, :type
+
+
+		### Return the parameter as a String suitable for inclusion in an 
+		### Accept-language header.
+		def to_s
+			return [
+				self.name,
+				self.qvaluestring,
+				self.extension_strings,
+			].compact.join( ';' )
+		end
+
+
+		### Return the Ruby Encoding object that is associated with the parameter's charset.
+		def encoding_object
+			return ::Encoding.find( self.name )
+		rescue ArgumentError => err
+			self.log.warn( err.message )
+			# self.log.debug( err.backtrace.join($/) )
+			return nil
+		end
+
+
+		### Match operator -- returns true if +other+ matches the receiving
+		### AcceptParam.
+		def =~( other )
+			unless other.is_a?( self.class )
+				other = self.class.parse( other.to_s ) rescue nil
+				return false unless other
+			end
+
+			# The special value "*", if present in the Accept-Charset field,
+			# matches every character set (including ISO-8859-1) which is not
+			# mentioned elsewhere in the Accept-Charset field.
+			return true if other.name.nil? || self.name.nil?
+
+			# Same downcased names or different names for the same encoding should match
+			return true if other.name.downcase == self.name.downcase ||
+			               other.encoding_object == self.encoding_object
+
+			return false
+		end
+
+	end # class Charset
+
+
+end # class Strelka::HTTPRequest
+
+# vim: set nosta noet ts=4 sw=4:

data/lib/strelka/httprequest/negotiation.rb

@@ -0,0 +1,257 @@
+#!/usr/bin/env ruby
+
+require 'strelka/constants'
+require 'strelka/httprequest' unless defined?( Strelka::HTTPRequest )
+require 'strelka/httprequest/acceptparams'
+
+
+# The mixin that adds methods to Strelka::HTTPRequest for content-negotiation.
+#
+#   request.accepts?( 'application/json' )
+#   request.explicitly_accepts?( 'application/xml+rdf' )
+#   request.accepts_charset?( Encoding::UTF_8 )
+#   request.accepts_charset?( 'iso-8859-15' )
+#   request.accepts_encoding?( 'compress' )
+#   request.accepts_language?( 'en' )
+#   request.explicitly_accepts_language?( 'en' )
+#   request.explicitly_accepts_language?( 'en-gb' )
+#
+module Strelka::HTTPRequest::Negotiation
+	include Strelka::Constants
+
+	### Extension callback -- add instance variables to extended objects. 
+	def initialize( * )
+		super
+		@accepted_mediatypes = nil
+		@accepted_charsets   = nil
+		@accepted_encodings  = nil
+		@accepted_languages  = nil
+	end
+
+
+	### Fetch the value of the given +header+, split apart the values, and parse
+	### each one using the specified +paramclass+. If no values are parsed from
+	### the header, and a block is given, the block is called and its return value
+	### is appended to the empty Array before returning it.
+	def parse_negotiation_header( header, paramclass )
+		self.log.debug "Parsing %s header into %p objects" % [ header, paramclass ]
+		rval = []
+		headerval = self.headers[ header ]
+		self.log.debug "  raw header value: %p" % [ headerval ]
+
+		# Handle the case where there's more than one of the header in question by
+		# forcing everything to an Array
+		Array( headerval ).compact.flatten.each do |paramstr|
+			paramstr.split( /\s*,\s*/ ).each do |param|
+				self.log.debug "    parsing param: %p" % [ param ]
+				rval << paramclass.parse( param )
+			end
+		end
+
+		if rval.empty? && block_given?
+			self.log.debug "  no parsed values; calling the fallback block"
+			rval << yield
+		end
+
+		return rval.flatten
+	end
+
+
+	#
+	# :section: Mediatype negotiation
+	#
+
+	### Return an Array of Strelka::HTTPRequest::MediaType objects for each
+	### type in the 'Accept' header.
+	def accepted_mediatypes
+		@accepted_mediatypes ||= self.parse_accept_header
+		return @accepted_mediatypes
+	end
+	alias_method :accepted_types, :accepted_mediatypes
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +content_type+.
+	def accepts?( content_type )
+		self.log.debug "Checking to see if request accepts %p" % [ content_type ]
+		atype = self.accepted_types.find {|type| type =~ content_type }
+		self.log.debug "  find returned: %p" % [ atype ]
+		return atype ? true : false
+	end
+	alias_method :accept?, :accepts?
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +content_type+, not including mime wildcards.
+	def explicitly_accepts?( content_type )
+		non_wildcard_types = self.accepted_types.reject {|param| param.subtype.nil? }
+		return non_wildcard_types.find {|type| type =~ content_type } ? true : false
+	end
+	alias_method :explicitly_accept?, :explicitly_accepts?
+
+
+	### Parse the receiver's 'Accept' header and return it as an Array of
+	### Strelka::HTTPRequest::MediaType objects.
+	def parse_accept_header
+		return self.parse_negotiation_header( :accept, Strelka::HTTPRequest::MediaType ) do
+			Strelka::HTTPRequest::MediaType.new( '*', '*' )
+		end
+	end
+
+
+	#
+	# :section: Charset negotiation
+	#
+
+	### Return an Array of Strelka::HTTPRequest::Charset objects for each
+	### type in the 'Accept-Charset' header.
+	def accepted_charsets
+		@accepted_charsets ||= self.parse_accept_charset_header
+		return @accepted_charsets
+	end
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +charset+.
+	def accepts_charset?( charset )
+		self.log.debug "Checking to see if request accepts charset: %p" % [ charset ]
+		aset = self.accepted_charsets.find {|cs| cs =~ charset }
+		self.log.debug "  find returned: %p" % [ aset ]
+		return aset ? true : false
+	end
+	alias_method :accept_charset?, :accepts_charset?
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +charset+, not including the wildcard tag if present.
+	def explicitly_accepts_charset?( charset )
+		non_wildcard_charsets = self.accepted_charsets.reject {|param| param.charset.nil? }
+		return non_wildcard_charsets.find {|cs| cs =~ charset } ? true : false
+	end
+	alias_method :explicitly_accept_charset?, :explicitly_accepts_charset?
+
+
+	### Parse the receiver's 'Accept-Charset' header and return it as an Array of
+	### Strelka::HTTPRequest::Charset objects.
+	def parse_accept_charset_header
+		return self.parse_negotiation_header( :accept_charset, Strelka::HTTPRequest::Charset ) do
+			Strelka::HTTPRequest::Charset.new( '*' )
+		end
+	end
+
+
+	#
+	# :section: Encoding negotiation
+	#
+
+	### Return an Array of Strelka::HTTPRequest::Encoding objects for each
+	### type in the 'Accept-Encoding' header.
+	def accepted_encodings
+		@accepted_encodings ||= self.parse_accept_encoding_header
+		return @accepted_encodings
+	end
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +encoding+.
+	def accepts_encoding?( encoding )
+		self.log.debug "Checking to see if request accepts encoding: %p" % [ encoding ]
+		return true if self.accepted_encodings.empty?
+		found_encoding = self.accepted_encodings.find {|enc| enc =~ encoding }
+		self.log.debug "  find returned: %p" % [ found_encoding ]
+
+		# If there was no match, then it's not accepted, unless it's the 'identity'
+		# encoding, which is accepted unless it's disabled.
+		return encoding == 'identity' if !found_encoding
+
+		return found_encoding.qvalue.nonzero?
+	end
+	alias_method :accept_encoding?, :accepts_encoding?
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +encoding+, not including the wildcard encoding if present.
+	def explicitly_accepts_encoding?( encoding )
+		non_wildcard_encodings = self.accepted_encodings.reject {|enc| enc.content_coding.nil? }
+		found_encoding = non_wildcard_encodings.find {|enc| enc =~ encoding } or
+			return false
+		return found_encoding.qvalue.nonzero?
+	end
+	alias_method :explicitly_accept_encoding?, :explicitly_accepts_encoding?
+
+
+	### Parse the receiver's 'Accept-Encoding' header and return it as an Array of
+	### Strelka::HTTPRequest::Encoding objects.
+	def parse_accept_encoding_header
+		return self.parse_negotiation_header( :accept_encoding, Strelka::HTTPRequest::Encoding ) do
+			# If the Accept-Encoding field-value is empty, then only the "identity"
+			# encoding is acceptable.
+			if self.headers.include?( :accept_encoding )
+				self.log.debug "Empty accept-encoding header: identity-only"
+				[ Strelka::HTTPRequest::Encoding.new('identity') ]
+
+			# I have no idea how this is different than an empty accept-encoding header
+			# for any practical case, but RFC2616 says:
+			#   If no Accept-Encoding field is present in a request, the server MAY
+			#   assume that the client will accept any content coding.  In this
+			#   case, if "identity" is one of the available content-codings, then
+			#   the server SHOULD use the "identity" content-coding, unless it has
+			#   additional information that a different content-coding is meaningful
+			#   to the client.
+			else
+				self.log.debug "No accept-encoding header: identity + any encoding"
+				[
+					Strelka::HTTPRequest::Encoding.new( 'identity' ),
+					Strelka::HTTPRequest::Encoding.new( '*', nil, 0.9 )
+				]
+			end
+		end
+	end
+
+
+
+	#
+	# :section: Language negotiation
+	#
+
+	### Return an Array of Strelka::HTTPRequest::Language objects for each
+	### type in the 'Accept-Language' header.
+	def accepted_languages
+		@accepted_languages ||= self.parse_accept_language_header
+		return @accepted_languages
+	end
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +language+.
+	def accepts_language?( language )
+		self.log.debug "Checking to see if request accepts language: %p" % [ language ]
+		found_language = self.accepted_languages.find {|langcode| langcode =~ language }
+		self.log.debug "  find returned: %p" % [ found_language ]
+		return found_language && found_language.qvalue.nonzero?
+	end
+	alias_method :accept_language?, :accepts_language?
+
+
+	### Returns boolean true/false if the requestor can handle the given
+	### +language+, not including the wildcard language if present.
+	def explicitly_accepts_language?( language )
+		non_wildcard_languages = self.accepted_languages.reject {|enc| enc.content_coding.nil? }
+		found_language = non_wildcard_languages.find {|enc| enc =~ language }
+		return found_language.qvalue.nonzero?
+	end
+	alias_method :explicitly_accept_language?, :explicitly_accepts_language?
+
+
+	### Parse the receiver's 'Accept-Language' header and return it as an Array of
+	### Strelka::HTTPRequest::Language objects.
+	def parse_accept_language_header
+		return self.parse_negotiation_header( :accept_language, Strelka::HTTPRequest::Language ) do
+			Strelka::HTTPRequest::Language.new( '*' )
+		end
+	end
+
+
+end # module RequestMethods
+
+