mongrel2 0.15.1 → 0.16.0

data/lib/mongrel2/request.rb

@@ -58,7 +58,7 @@ class Mongrel2::Request
 	###
 	###   class MyFramework::JSONRequest < Mongrel2::JSONRequest
 	###       register_request_type self, 'JSON'
-	###       
+	###
 	###       # Override #initialize to do any stuff specific to your
 	###       # request type, but you'll likely want to super() to
 	###       # Mongrel2::JSONRequest.
@@ -69,9 +69,10 @@ class Mongrel2::Request
 	###
 	###   end # class MyFramework::JSONRequest
 	###
-	### If you wish one of your subclasses to be used instead of Mongrel2::Request 
+	### If you wish one of your subclasses to be used instead of Mongrel2::Request
 	### for the default request class, register it with a METHOD of :__default.
 	def self::register_request_type( subclass, *req_methods )
+		Mongrel2.log.debug "Registering %p for %p requests" % [ subclass, req_methods ]
 		req_methods.each do |methname|
 			if methname == :__default
 				# Clear cached lookups
@@ -103,7 +104,7 @@ class Mongrel2::Request
 	###	I N S T A N C E   M E T H O D S
 	#################################################################
 
-	### Create a new Request object with the given +sender_id+, +conn_id+, +path+, +headers+, 
+	### Create a new Request object with the given +sender_id+, +conn_id+, +path+, +headers+,
 	### and +body+. The optional +nil+ is for the raw request content, which can be useful
 	### later for debugging.
 	def initialize( sender_id, conn_id, path, headers, body='', raw=nil )

data/lib/mongrel2/testing.rb

@@ -67,11 +67,27 @@ module Mongrel2
 		end
 
 
+		### Return the default testing headers hash for the receiving class.
+		def self::default_headers
+			return const_get( :DEFAULT_TESTING_HEADERS )
+		end
+
+
+		### Return the default configuration for the receiving factory class.
+		def self::default_factory_config
+			return const_get( :DEFAULT_FACTORY_CONFIG )
+		end
+
+
+		#############################################################
+		###	I N S T A N C E   M E T H O D S
+		#############################################################
+
 		### Create a new RequestFactory with the given +config+, which will be merged with
 		### DEFAULT_FACTORY_CONFIG.
 		def initialize( config={} )
-			config[:headers] = DEFAULT_TESTING_HEADERS.merge( config[:headers] ) if config[:headers]
-			config = DEFAULT_FACTORY_CONFIG.merge( config )
+			config[:headers] = self.class.default_headers.merge( config[:headers] ) if config[:headers]
+			config = self.class.default_factory_config.merge( config )
 
 			@sender_id = config[:sender_id]
 			@host      = config[:host]
@@ -198,5 +214,188 @@ module Mongrel2
 
 	end # RequestFactory
 
+
+	### A factory for generating WebSocket request objects for testing.
+	class WebSocketFrameFactory < Mongrel2::RequestFactory
+		include Mongrel2::Constants
+
+		# The default host
+		DEFAULT_TESTING_HOST  = 'localhost'
+		DEFAULT_TESTING_PORT  = '8113'
+		DEFAULT_TESTING_ROUTE = '/ws'
+
+		# The default WebSocket opcode
+		DEFAULT_OPCODE = :text
+
+		# Default headers
+		DEFAULT_TESTING_HEADERS = {
+			'METHOD'                => 'WEBSOCKET',
+			'PATTERN'               => '/ws',
+			'URI'                   => '/ws',
+			'VERSION'               => 'HTTP/1.1',
+			'PATH'                  => '/ws',
+			'upgrade'               => 'websocket',
+			'host'                  => DEFAULT_TESTING_HOST,
+			'sec-websocket-key'     => 'rBP9u8uxVvIYrH/8bNOPwQ==',
+			'sec-websocket-version' => '13',
+			'connection'            => 'Upgrade',
+			'origin'                => "http://#{DEFAULT_TESTING_HOST}",
+			'FLAGS'                 => '0x89', # FIN + PING
+			'x-forwarded-for'       => '127.0.0.1'
+		}
+
+		# The defaults used by the websocket request factory
+		DEFAULT_FACTORY_CONFIG = {
+			:sender_id     => DEFAULT_TEST_UUID,
+			:conn_id       => DEFAULT_CONN_ID,
+			:host          => DEFAULT_TESTING_HOST,
+			:port          => DEFAULT_TESTING_PORT,
+			:route         => DEFAULT_TESTING_ROUTE,
+			:headers       => DEFAULT_TESTING_HEADERS,
+		}
+
+		# Freeze all testing constants
+		constants.each do |cname|
+			const_get(cname).freeze
+		end
+
+
+		### Create a new factory using the specified +config+.
+		def initialize( config={} )
+			config[:headers] = DEFAULT_TESTING_HEADERS.merge( config[:headers] ) if config[:headers]
+			config = DEFAULT_FACTORY_CONFIG.merge( config )
+
+			@sender_id = config[:sender_id]
+			@host      = config[:host]
+			@port      = config[:port]
+			@route     = config[:route]
+			@headers   = Mongrel2::Table.new( config[:headers] )
+
+			@conn_id   = 0
+		end
+
+		######
+		public
+		######
+
+		### Create a new request with the specified +uri+, +data+, and +flags+.
+		def create( uri, data, *flags )
+			raise "Request doesn't route through %p" % [ self.route ] unless
+				uri.start_with?( self.route )
+
+			headers = if flags.last.is_a?( Hash ) then flags.pop else {} end
+			flagheader = make_flags_header( flags )
+			headers = self.make_merged_headers( uri, flagheader, headers )
+			rclass = Mongrel2::Request.subclass_for_method( :WEBSOCKET )
+
+			return rclass.new( self.sender_id, self.conn_id.to_s, self.route, headers, data )
+		end
+
+
+		### Create a continuation frame.
+		def continuation( uri, payload='', *flags )
+			flags << :continuation
+			return self.create( uri, payload, flags )
+		end
+
+
+		### Create a text frame.
+		def text( uri, payload='', *flags )
+			flags << :text
+			return self.create( uri, payload, flags )
+		end
+
+
+		### Create a binary frame.
+		def binary( uri, payload='', *flags )
+			flags << :binary
+			return self.create( uri, payload, flags )
+		end
+
+
+		### Create a close frame.
+		def close( uri, payload='', *flags )
+			flags << :close << :fin
+			return self.create( uri, payload, flags )
+		end
+
+
+		### Create a ping frame.
+		def ping( uri, payload='', *flags )
+			flags << :ping << :fin
+			return self.create( uri, payload, flags )
+		end
+
+
+		### Create a pong frame.
+		def pong( uri, payload='', *flags )
+			flags << :pong << :fin
+			return self.create( uri, payload, flags )
+		end
+
+
+
+		#########
+		protected
+		#########
+
+		### Merge the factory's headers with +userheaders+, and then merge in the
+		### special headers that Mongrel2 adds that are based on the +uri+ and other
+		### server attributes.
+		def make_merged_headers( uri, flags, userheaders )
+			headers = self.headers.merge( userheaders )
+			uri = URI( uri )
+
+			# Add mongrel headers
+			headers.uri       = uri.to_s
+			headers.path      = uri.path
+			headers.host      = "%s:%d" % [ self.host, self.port ]
+			headers.query     = uri.query if uri.query
+			headers.pattern   = self.route
+			headers.origin    = "http://#{headers.host}"
+			headers.flags     = "0x%02x" % [ flags ]
+
+			return headers
+		end
+
+
+		#######
+		private
+		#######
+
+		### Make a flags value out of flag Symbols that correspond to the flag
+		### bits and opcodes: [ :fin, :rsv1, :rsv2, :rsv3, :continuation,
+		### :text, :binary, :close, :ping, :pong ]. If the flags contain
+		### Integers instead, they are ORed with the result.
+		def make_flags_header( *flag_symbols )
+			flag_symbols.flatten!
+			flag_symbols.compact!
+
+			Mongrel2.log.debug "Making a flags header for symbols: %p" % [ flag_symbols ]
+
+			return flag_symbols.inject( 0x00 ) do |flags, flag|
+				case flag
+				when :fin
+					flags | WebSocket::FIN_FLAG
+				when :rsv1
+					flags | WebSocket::RSV1_FLAG
+				when :rsv2
+					flags | WebSocket::RSV2_FLAG
+				when :rsv3
+					flags | WebSocket::RSV3_FLAG
+				when :continuation, :text, :binary, :close, :ping, :pong
+					# Opcodes clear any other opcodes present
+					flags ^= ( flags & WebSocket::OPCODE_BITMASK )
+					flags | WebSocket::OPCODE[ flag ]
+				when Integer
+					flags | flag
+				else
+					raise ArgumentError, "Don't know what the %p flag is." % [ flag ]
+				end
+			end
+		end
+
+	end # class WebSocketFrameFactory
+
 end # module Mongrel2
 

data/lib/mongrel2/websocket.rb

@@ -0,0 +1,561 @@
+#!/usr/bin/ruby
+
+require 'mongrel2/request' unless defined?( Mongrel2::Request )
+require 'mongrel2/mixins'
+require 'mongrel2/constants'
+
+
+# The Mongrel2 WebSocket namespace module. Contains constants and classes for
+# building WebSocket services.
+#
+#   class WebSocketEchoServer
+#
+#       def handle_websocket( frame )
+#
+#           # Close connections that send invalid frames
+#           if !frame.valid?
+#               res = frame.response( :close )
+#               res.set_close_status( WebSocket::CLOSE_PROTOCOL_ERROR )
+#               return res
+#           end
+#
+#           # Do something with the frame
+#           ...
+#       end
+#   end
+module Mongrel2::WebSocket
+
+	# WebSocket-related header and status constants
+	module Constants
+		# WebSocket frame header
+		#    0                   1                   2                   3
+		#    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+		#   +-+-+-+-+-------+-+-------------+-------------------------------+
+		#   |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
+		#   |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
+		#   |N|V|V|V|       |S|             |   (if payload len==126/127)   |
+		#   | |1|2|3|       |K|             |                               |
+		#   +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
+		#   |     Extended payload length continued, if payload len == 127  |
+		#   + - - - - - - - - - - - - - - - +-------------------------------+
+		#   |                               |Masking-key, if MASK set to 1  |
+		#   +-------------------------------+-------------------------------+
+		#   | Masking-key (continued)       |          Payload Data         |
+		#   +-------------------------------- - - - - - - - - - - - - - - - +
+		#   :                     Payload Data continued ...                :
+		#   + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+		#   |                     Payload Data continued ...                |
+		#   +---------------------------------------------------------------+
+
+		# Masks of the bits of the FLAGS header that corresponds to the FIN and RSV1-3 flags
+		FIN_FLAG  = 0b10000000
+		RSV1_FLAG = 0b01000000
+		RSV2_FLAG = 0b00100000
+		RSV3_FLAG = 0b00010000
+
+		# Mask for checking for one or more of the RSV[1-3] flags
+		RSV_FLAG_MASK = 0b01110000
+
+		# Mask for picking the opcode out of the flags header
+		OPCODE_BITMASK = 0b00001111
+
+		# Mask for testing to see if the frame is a control frame
+		OPCODE_CONTROL_MASK = 0b00001000
+
+		# %x0 denotes a continuation frame
+		# %x1 denotes a text frame
+		# %x2 denotes a binary frame
+		# %x3-7 are reserved for further non-control frames
+		# %x8 denotes a connection close
+		# %x9 denotes a ping
+		# %xA denotes a pong
+		# %xB-F are reserved for further control frames
+
+		# Opcodes from the flags header
+		OPCODE_NAME = Hash.new do |codes,bit|
+			raise RangeError, "invalid opcode %d!" % [ bit ] unless bit.between?( 0x0, 0xf )
+			codes[ bit ] = :reserved
+		end
+		OPCODE_NAME[ 0x0 ] = :continuation
+		OPCODE_NAME[ 0x1 ] = :text
+		OPCODE_NAME[ 0x2 ] = :binary
+		OPCODE_NAME[ 0x8 ] = :close
+		OPCODE_NAME[ 0x9 ] = :ping
+		OPCODE_NAME[ 0xA ] = :pong
+
+		# Opcode bits keyed by name
+		OPCODE = OPCODE_NAME.invert
+
+		# Closing status codes (http://tools.ietf.org/html/rfc6455#section-7.4.1)
+
+		# 1000 indicates a normal closure, meaning that the purpose for
+		# which the connection was established has been fulfilled.
+		CLOSE_NORMAL = 1000
+
+		# 1001 indicates that an endpoint is "going away", such as a server
+		# going down or a browser having navigated away from a page.
+		CLOSE_GOING_AWAY = 1001
+
+		# 1002 indicates that an endpoint is terminating the connection due
+		# to a protocol error.
+		CLOSE_PROTOCOL_ERROR = 1002
+
+		# 1003 indicates that an endpoint is terminating the connection
+		# because it has received a type of data it cannot accept (e.g., an
+		# endpoint that understands only text data MAY send this if it
+		# receives a binary message).
+		CLOSE_BAD_DATA_TYPE = 1003
+
+		# Reserved.  The specific meaning might be defined in the future.
+		CLOSE_RESERVED = 1004
+
+		# 1005 is a reserved value and MUST NOT be set as a status code in a
+		# Close control frame by an endpoint.  It is designated for use in
+		# applications expecting a status code to indicate that no status
+		# code was actually present.
+		CLOSE_MISSING_STATUS = 1005
+
+		# 1006 is a reserved value and MUST NOT be set as a status code in a
+		# Close control frame by an endpoint.  It is designated for use in
+		# applications expecting a status code to indicate that the
+		# connection was closed abnormally, e.g., without sending or
+		# receiving a Close control frame.
+		CLOSE_ABNORMAL_STATUS = 1006
+
+		# 1007 indicates that an endpoint is terminating the connection
+		# because it has received data within a message that was not
+		# consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
+		# data within a text message).
+		CLOSE_BAD_DATA = 1007
+
+		# 1008 indicates that an endpoint is terminating the connection
+		# because it has received a message that violates its policy.  This
+		# is a generic status code that can be returned when there is no
+		# other more suitable status code (e.g., 1003 or 1009) or if there
+		# is a need to hide specific details about the policy.
+		CLOSE_POLICY_VIOLATION = 1008
+
+		# 1009 indicates that an endpoint is terminating the connection
+		# because it has received a message that is too big for it to
+		# process.
+		CLOSE_MESSAGE_TOO_LARGE = 1009
+
+		# 1010 indicates that an endpoint (client) is terminating the
+		# connection because it has expected the server to negotiate one or
+		# more extension, but the server didn't return them in the response
+		# message of the WebSocket handshake.  The list of extensions that
+		# are needed SHOULD appear in the /reason/ part of the Close frame.
+		# Note that this status code is not used by the server, because it
+		# can fail the WebSocket handshake instead.
+		CLOSE_MISSING_EXTENSION = 1010
+
+		# 1011 indicates that a server is terminating the connection because
+		# it encountered an unexpected condition that prevented it from
+		# fulfilling the request.
+		CLOSE_EXCEPTION = 1011
+
+		# 1015 is a reserved value and MUST NOT be set as a status code in a
+		# Close control frame by an endpoint.  It is designated for use in
+		# applications expecting a status code to indicate that the
+		# connection was closed due to a failure to perform a TLS handshake
+		# (e.g., the server certificate can't be verified).
+		CLOSE_TLS_ERROR = 1015
+
+		# Human-readable messages for each closing status code.
+		CLOSING_STATUS_DESC = {
+			CLOSE_NORMAL            => 'Session closed normally.',
+			CLOSE_GOING_AWAY        => 'Endpoint going away.',
+			CLOSE_PROTOCOL_ERROR    => 'Protocol error.',
+			CLOSE_BAD_DATA_TYPE     => 'Unhandled data type.',
+			CLOSE_RESERVED          => 'Reserved for future use.',
+			CLOSE_MISSING_STATUS    => 'No status code was present.',
+			CLOSE_ABNORMAL_STATUS   => 'Abnormal close.',
+			CLOSE_BAD_DATA          => 'Bad or malformed data.',
+			CLOSE_POLICY_VIOLATION  => 'Policy violation.',
+			CLOSE_MESSAGE_TOO_LARGE => 'Message too large for endpoint.',
+			CLOSE_MISSING_EXTENSION => 'Missing extension.',
+			CLOSE_EXCEPTION         => 'Unexpected condition/exception.',
+			CLOSE_TLS_ERROR         => 'TLS handshake failure.',
+		}
+
+	end # module WebSocket
+	include Constants
+
+	# Base exception class for WebSocket-related errors
+	class Error < ::RuntimeError; end
+
+	# Exception raised when a frame is malformed, doesn't parse, or is otherwise invalid.
+	class FrameError < Mongrel2::WebSocket::Error; end
+
+
+	# WebSocket frame class; this is used for both requests and responses in
+	# WebSocket services.
+	class Frame < Mongrel2::Request
+		include Mongrel2::WebSocket::Constants
+
+		# The default frame header flags: FIN + CLOSE
+		DEFAULT_FLAGS = FIN_FLAG | OPCODE[:close]
+
+
+		# Set this class as the one that will handle WEBSOCKET requests
+		register_request_type( self, :WEBSOCKET )
+
+
+		### Override the type of response returned by this request type. Since
+		### WebSocket connections are symmetrical, responses are just new
+		### WebSocketFrames with the same Mongrel2 sender and connection IDs.
+		def self::response_class
+			return self
+		end
+
+
+		### Create a response frame from the given request +frame+.
+		def self::from_request( frame )
+			Mongrel2.log.debug "Creating a %p response to request %p" % [ self, frame ]
+			response = new( frame.sender_id, frame.conn_id, frame.path )
+			response.request_frame = frame
+
+			return response
+		end
+
+
+		### Define accessors for the flag of the specified +name+ and +bit+.
+		def self::attr_flag( name, bitmask )
+			define_method( "#{name}?" ) do
+				(self.flags & bitmask).nonzero?
+			end
+			define_method( "#{name}=" ) do |newvalue|
+				if newvalue
+					self.flags |= bitmask
+				else
+					self.flags ^= ( self.flags & bitmask )
+				end
+			end
+		end
+
+
+
+		#################################################################
+		###	I N S T A N C E   M E T H O D S
+		#################################################################
+
+		### Override the constructor to add Integer flags extracted from the FLAGS header.
+		def initialize( sender_id, conn_id, path, headers={}, payload='', raw=nil )
+			payload.force_encoding( Encoding::UTF_8 ) if
+				payload.encoding == Encoding::ASCII_8BIT
+
+			super
+
+			@flags = Integer( self.headers.flags || DEFAULT_FLAGS )
+			@request_frame = nil
+			@errors = []
+		end
+
+
+		######
+		public
+		######
+
+		# The payload data
+		attr_accessor :body
+		alias_method :payload, :body
+		alias_method :payload=, :body=
+
+
+		# The frame's header flags as an Integer
+		attr_accessor :flags
+
+		# The frame that this one is a response to
+		attr_accessor :request_frame
+
+		# The Array of validation errors
+		attr_reader :errors
+
+
+		### Returns +true+ if the request's FIN flag is set. This flag indicates that
+		### this is the final fragment in a message.  The first fragment MAY also be
+		### the final fragment.
+		attr_flag :fin, FIN_FLAG
+
+		### Returns +true+ if the request's RSV1 flag is set. RSV1-3 MUST be 0 unless
+		### an extension is negotiated that defines meanings for non-zero values.  If
+		### a nonzero value is received and none of the negotiated extensions defines
+		### the meaning of such a nonzero value, the receiving endpoint MUST _fail the
+		### WebSocket connection_.
+		attr_flag :rsv1, RSV1_FLAG
+		attr_flag :rsv2, RSV2_FLAG
+		attr_flag :rsv3, RSV3_FLAG
+
+
+		### Returns true if one or more of the RSV1-3 bits is set.
+		def has_rsv_flags?
+			return ( self.flags & RSV_FLAG_MASK ).nonzero?
+		end
+
+
+		### Returns the name of the frame's opcode as a Symbol. The #numeric_opcode method
+		### returns the numeric one.
+		def opcode
+			return OPCODE_NAME[ self.numeric_opcode ]
+		end
+
+
+		### Return the numeric opcode of the frame.
+		def numeric_opcode
+			return self.flags & OPCODE_BITMASK
+		end
+
+
+		### Set the frame's opcode to +code+, which should be either a numeric opcode or
+		### its equivalent name (i.e., :continuation, :text, :binary, :close, :ping, :pong)
+		def opcode=( code )
+			opcode = OPCODE[ code.to_sym ] or
+				raise ArgumentError, "unknown opcode %p" % [ code ]
+
+			self.flags ^= ( self.flags & OPCODE_BITMASK )
+			self.flags |= opcode
+		end
+
+
+		### Returns +true+ if the request is a WebSocket control frame.
+		def control?
+			return ( self.flags & OPCODE_CONTROL_MASK ).nonzero?
+		end
+
+
+		### Append the given +object+ to the payload. Returns the Frame for
+		### chaining.
+		def <<( object )
+			self.payload << object
+			return self
+		end
+
+
+		### Write the given +objects+ to the payload, calling #to_s on each one.
+		def puts( *objects )
+			objects.each do |obj|
+				self << obj.to_s.chomp << $/
+			end
+		end
+
+
+		### Overwrite the frame's payload with a status message based on
+		### +statuscode+.
+		def set_status( statuscode )
+			self.log.warn "Unknown status code %d" unless CLOSING_STATUS_DESC.key?( statuscode )
+			status_msg = "%d %s" % [ statuscode, CLOSING_STATUS_DESC[statuscode] ]
+
+			self.payload.replace( status_msg )
+		end
+
+
+		### Check the frame for problems, appending descriptions of any issues to
+		### the #errors array.
+		def validate
+			self.errors.clear
+
+			self.validate_payload_encoding
+			self.validate_control_frame
+			self.validate_opcode
+			self.validate_reserved_flags
+		end
+
+
+		### Sanity-checks the frame and returns +false+ if any problems are found.
+		### Error messages will be in #errors.
+		def valid?
+			self.validate
+			return self.errors.empty?
+		end
+
+
+		### Stringify into a response suitable for sending to the client.
+		def to_s
+			data = self.payload.to_s
+
+			# Make sure the outgoing payload is UTF-8, except in the case of a
+			# binary frame.
+			if self.opcode != :binary && data.encoding != Encoding::UTF_8
+				self.log.debug "Transcoding %s payload data to UTF-8" % [ data.encoding.name ]
+				data.encode!( Encoding::UTF_8 )
+			end
+
+			# Make sure everything's in order
+			unless self.valid?
+				self.log.error "Validation failed."
+				raise Mongrel2::WebSocket::FrameError, "invalid frame: %s" %
+					[ self.errors.join( ', ' ) ]
+			end
+
+			# Now force everything into binary so it can be catenated
+			data.force_encoding( Encoding::ASCII_8BIT )
+			return [
+				self.make_header( data ),
+				data
+			].join
+		end
+
+
+		### Return an Enumerator for the bytes of the raw frame as it appears
+		### on the wire.
+		def bytes
+			return self.to_s.bytes
+		end
+
+
+		### Create a Mongrel2::Response that will respond to the same server/connection as
+		### the receiver. If you wish your specialized Request class to have a corresponding
+		### response type, you can override the Mongrel2::Request.response_class method
+		### to achieve that.
+		def response( *flags )
+			unless @response
+				@response = super()
+
+				# Set the opcode
+				self.log.debug "Setting up response %p with symmetrical flags" % [ @response ]
+				if self.opcode == :ping
+					@response.opcode = :pong
+					@response.payload = self.payload
+				else
+					@response.opcode = self.opcode
+				end
+
+				# Set flags in the response
+				unless flags.empty?
+					self.log.debug "  applying custom flags: %p" % [ flags ]
+					@response.set_flags( *flags )
+				end
+
+			end
+
+			return @response
+		end
+
+
+		### Apply flag bits and opcodes: (:fin, :rsv1, :rsv2, :rsv3, :continuation,
+		### :text, :binary, :close, :ping, :pong) to the frame.
+		###
+		###   # Transform the frame into a CLOSE frame and set its FIN flag
+		###   frame.set_flags( :fin, :close )
+		###
+		def set_flags( *flag_symbols )
+			flag_symbols.flatten!
+			flag_symbols.compact!
+
+			self.log.debug "Setting flags for symbols: %p" % [ flag_symbols ]
+
+			flag_symbols.each do |flag|
+				case flag
+				when :fin, :rsv1, :rsv2, :rsv3
+					self.__send__( "#{flag}=", true )
+				when :continuation, :text, :binary, :close, :ping, :pong
+					self.opcode = flag
+				when Integer
+					self.log.debug "  setting Integer flags directly: 0b%08b" % [ integer ]
+					self.flags |= flag
+				else
+					raise ArgumentError, "Don't know what the %p flag is." % [ flag ]
+				end
+			end
+		end
+
+
+		#########
+		protected
+		#########
+
+		### Return the details to include in the contents of the #inspected object.
+		def inspect_details
+			return %Q{FIN:%d RSV1:%d RSV2:%d RSV3:%d OPCODE:%s (0x%x) -- %0.2fK body} % [
+				self.fin?  ? 1 : 0,
+				self.rsv1? ? 1 : 0,
+				self.rsv2? ? 1 : 0,
+				self.rsv3? ? 1 : 0,
+				self.opcode,
+				self.numeric_opcode,
+				(self.payload.bytesize / 1024.0),
+			]
+		end
+
+
+		### Make a WebSocket header for the receiving frame and return it.
+		def make_header( data )
+			header = ''.force_encoding( Encoding::ASCII_8BIT )
+			length = data.bytesize
+			self.log.debug "Making wire protocol header for payload of %d bytes" % [ length ]
+
+			# Pack the frame according to its size
+			if length >= 2**16
+				self.log.debug "  giant size, using 8-byte (64-bit int) length field"
+				header = [ self.flags, 127, length ].pack( 'c2q>' )
+			elsif length > 125
+				self.log.debug "  big size, using 2-byte (16-bit int) length field"
+				header = [ self.flags, 126, length ].pack( 'c2n' )
+			else
+				self.log.debug "  small size, using payload length field"
+				header = [ self.flags, length ].pack( 'c2' )
+			end
+
+			self.log.debug "  header is: 0: %02x %02x" % header.unpack('C*')
+			return header
+		end
+
+
+		### Validate that the payload encoding is correct for its opcode, attempting
+		### to transcode it if it's not. If the transcoding fails, adds an error to
+		### #errors.
+		def validate_payload_encoding
+			if self.opcode == :binary
+				self.log.debug "Binary payload: forcing to ASCII-8BIT"
+				self.payload.force_encoding( Encoding::ASCII_8BIT )
+			else
+				self.log.debug "Non-binary payload: forcing to UTF-8"
+				self.payload.force_encoding( Encoding::UTF_8 )
+				self.errors << "Invalid UTF8 in payload" unless self.payload.valid_encoding?
+			end
+		end
+
+
+		### Sanity-check control frame +data+, raising a Mongrel2::WebSocket::FrameError
+		### if there's a problem.
+		def validate_control_frame
+			return unless self.control?
+
+			if self.payload.bytesize > 125
+				self.log.error "Payload of control frame exceeds 125 bytes (%d)" % [ self.payload.bytesize ]
+				self.errors << "payload of control frame cannot exceed 125 bytes"
+			end
+
+			unless self.fin?
+				self.log.error "Control frame fragmented (FIN is unset)"
+				self.errors << "control frame is fragmented (no FIN flag set)"
+			end
+		end
+
+
+		### Ensure that the frame has a valid opcode in its header. If you're using reserved
+		### opcodes, you'll want to override this.
+		def validate_opcode
+			if self.opcode == :reserved
+				self.log.error "Frame uses reserved opcode 0x%x" % [ self.numeric_opcode ] 
+				self.errors << "Frame uses reserved opcode"
+			end
+		end
+
+
+		### Ensure that the frame doesn't have any of the reserved flags set (RSV1-3). If your
+		### subprotocol uses one or more of these, you'll want to override this method.
+		def validate_reserved_flags
+			if self.has_rsv_flags?
+				self.log.error "Frame has one or more reserved flags set."
+				self.errors << "Frame has one or more reserved flags set."
+			end
+		end
+
+
+	end # class Frame
+
+end # module Mongrel2::WebSocket
+
+# vim: set nosta noet ts=4 sw=4:
+