mongrel2 0.26.0 → 0.27.0

data/ChangeLog

@@ -1,5 +1,40 @@
+2012-06-30  Michael Granger  <ged@FaerieMUD.org>
+
+	* Manifest.txt, README.rdoc, bin/m2sh.rb, data/mongrel2/config.rb.in,
+	lib/mongrel2/config.rb, lib/mongrel2/constants.rb:
+	Adding 'bootstrap' and 'quickstart' commands to m2sh.rb.
+
+	Also adding documentation for them to the README, and moved the
+	DATA_DIR constants into mongrel2/constants.
+	[2f2b9b4bc86f] [tip]
+
+2012-06-27  Michael Granger  <ged@FaerieMUD.org>
+
+	* examples/.env, examples/Procfile, examples/config.rb, examples/ws-
+	echo.rb, lib/mongrel2/handler.rb, lib/mongrel2/httpresponse.rb,
+	lib/mongrel2/testing.rb, lib/mongrel2/websocket.rb,
+	spec/lib/constants.rb, spec/lib/helpers.rb,
+	spec/mongrel2/handler_spec.rb, spec/mongrel2/httpresponse_spec.rb,
+	spec/mongrel2/websocket_spec.rb:
+	Updating websocket support for recent Mongrel2 changes
+	[c17bbae10985]
+
 2012-06-26  Michael Granger  <ged@FaerieMUD.org>
 
+	* .hgtags:
+	Added tag v0.26.0 for changeset 7fb25e6e09bc
+	[1cf11a8e5402]
+
+	* .hgsigs:
+	Added signature for changeset c2eac469ca66
+	[7fb25e6e09bc] [v0.26.0]
+
+	* History.rdoc, lib/mongrel2.rb, spec/lib/helpers.rb,
+	spec/mongrel2/handler_spec.rb, spec/mongrel2/request_spec.rb:
+	Fix the specs broken by the async upload changes, bump minor
+	version, update history.
+	[c2eac469ca66]
+
 	* lib/mongrel2/config/handler.rb, lib/mongrel2/config/host.rb,
 	lib/mongrel2/config/route.rb, lib/mongrel2/config/server.rb,
 	lib/mongrel2/connection.rb, lib/mongrel2/handler.rb,
@@ -7,7 +42,7 @@
 	spec/mongrel2/handler_spec.rb, spec/mongrel2/httprequest_spec.rb,
 	spec/mongrel2/request_spec.rb:
 	Fix the async upload body path
-	[782174dcba2e] [tip]
+	[782174dcba2e]
 
 2012-06-21  Michael Granger  <ged@FaerieMUD.org>
 

data/History.rdoc

@@ -1,3 +1,9 @@
+== v0.27.0 [2012-07-02] Michael Granger <ged@FaerieMUD.org>
+
+- Adds support for websocket handshake in 'develop' branch.
+- Adds 'bootstrap' and 'quickstart' commands to m2sh.rb.
+
+
 == v0.26.0 [2012-06-26] Michael Granger <ged@FaerieMUD.org>
 
 - Fix the derived path to the async upload body

data/Manifest.txt

@@ -8,6 +8,7 @@ README.rdoc
 Rakefile
 bin/m2sh.rb
 data/mongrel2/bootstrap.html
+data/mongrel2/config.rb.in
 data/mongrel2/config.sql
 data/mongrel2/css/master.css
 data/mongrel2/js/websock-test.js

data/README.rdoc

@@ -17,29 +17,36 @@ databases in pure Ruby, a Control port interface object, and handler classes
 for creating applications or higher-level frameworks.
 
 
-== Installation
+== Installation and Setup
 
-    gem install mongrel2
+Install mongrel2:
 
+  $ {brew,port,portmaster,apt-get install,etc} mongrel2
 
-This library uses Jeremy Hinegardner's 'amalgalite' library for the config ORM
-classes, but it will also fall back to using the sqlite3 library instead:
+Install the mongrel2 gem:
 
-    # Loading the sqlite3 library explicitly
-    $ rspec -rsqlite3 -cfp spec
-    >>> Using SQLite3 1.3.4 for DB access.
-    .....[...]
+  $ gem install mongrel2
 
-    Finished in 5.53 seconds
-    102 examples, 0 failures
+Dump a config database generation script into the current working directory:
 
-    # No -rsqlite3 means amalgalite loads first.
-    $ rspec -cfp spec
-    >>> Using Amalgalite 1.1.2 for DB access.
-    .....[...]
+  $ m2sh.rb bootstrap
 
-    Finished in 3.67 seconds
-    102 examples, 0 failures
+Edit the generated file:
+
+  $ $EDITOR config.rb
+
+Create a config database from the Ruby config:
+
+  $ m2sh.rb load config.rb
+
+Start the server:
+
+  $ m2sh.rb start
+
+Or combine <tt>bootstrap</tt>, <tt>load</tt>, and <tt>start</tt> all into one
+command:
+
+  $ m2sh.rb quickstart
 
 
 == Usage
@@ -54,6 +61,26 @@ for adding the Ruby configuration DSL to your namespace, and the top-level
 Mongrel2::Config class, which manages the database connection, installs the
 schema, etc.
 
+The ORM classes use Jeremy Hinegardner's 'amalgalite' library, but it will
+also fall back to using the sqlite3 library instead:
+
+    # Loading the sqlite3 library explicitly
+    $ rspec -rsqlite3 -cfp spec
+    >>> Using SQLite3 1.3.4 for DB access.
+    .....[...]
+
+    Finished in 5.53 seconds
+    102 examples, 0 failures
+
+    # No -rsqlite3 means amalgalite loads first.
+    $ rspec -cfp spec
+    >>> Using Amalgalite 1.1.2 for DB access.
+    .....[...]
+
+    Finished in 3.67 seconds
+    102 examples, 0 failures
+
+
 * Mongrel2::Config
   * Mongrel2::Config::DSL
   * Mongrel2::Config::Server
@@ -82,6 +109,7 @@ Mongrel2 sends:
 * Mongrel2::HTTPRequest
 * Mongrel2::JSONRequest
 * Mongrel2::XMLRequest
+* Mongrel2::WebSocket::ClientHandshake
 * Mongrel2::WebSocket::Frame
 
 These are all {overridable}[rdoc-ref:Mongrel2::Request.register_request_type]
@@ -94,17 +122,20 @@ handlers.
 === The Control Class
 
 The Mongrel2::Control class is an object interface to {the Mongrel2 control
-port}[http://mongrel2.org/static/mongrel2-manual.html#x1-390003.8]. It can be
+port}[http://mongrel2.org/static/book-finalch4.html#x6-390003.8]. It can be
 used to stop and restart the server, check its status, etc.
 
 
 === Other Classes
 
-There are a few other classes and modules work checking out, too:
+There are a few other classes and modules worth checking out, too:
 
-* Mongrel2::Table
-* Mongrel2::Constants
-* Mongrel2::Loggable
+Mongrel2::Table::
+  A hash-like data structure for headers, etc.
+Mongrel2::Constants::
+  A collection of convenience constants for Mongrel2 handlers.
+Mongrel2::RequestFactory::
+  A factory for generating fixtured requests of various types for testing.
 
 
 == Contributing

data/bin/m2sh.rb

@@ -186,7 +186,7 @@ class Mongrel2::M2SHCommand
 				text ''
 
 				text 'Global Options'
-				opt :config, "Specify the configfile to use.",
+				opt :config, "Specify the config database to use.",
 					:default => DEFAULT_CONFIG_URI
 				opt :sudo, "Use 'sudo' to run the mongrel2 server."
 				opt :port, "Reset the server port to <i> before starting it.",
@@ -588,6 +588,43 @@ class Mongrel2::M2SHCommand
 	usage :running, "[server]"
 
 
+	### The 'bootstrap' command.
+	def bootstrap_command( *args )
+		scriptname = args.shift || DEFAULT_CONFIG_SCRIPT
+		template   = Mongrel2::DATA_DIR + 'config.rb.in'
+		data       = template.read
+
+		data.gsub!( /%% PWD %%/, Dir.pwd )
+
+		header "Writing a config-generation script to %s" % [ scriptname ]
+		File.open( scriptname, File::WRONLY|File::EXCL|File::CREAT, 0755, encoding: 'utf-8' ) do |fh|
+			fh.print( data )
+		end
+		message "Done."
+	end
+	help :bootstrap, "Generate a basic config-generation script."
+	usage :boostrap, "[scriptname]"
+
+
+	### The 'quickstart' command.
+	def quickstart_command( *args )
+		configfile = 'config.rb'
+
+		header "Quickstart!"
+		self.bootstrap_command( configfile )
+		edit( configfile )
+		self.load_command( configfile )
+
+		message '---'
+		header "Point a browser at: "
+		message '---'
+
+		self.start_command()
+	end
+	help :quickstart, "Set up a basic mongrel2 server and run it."
+	usage :quickstart
+
+
 	### The 'version' command
 	def version_command( *args )
 		message( "<%= color 'Version:', :header %> " + Mongrel2.version_string(true) )
@@ -599,6 +636,10 @@ class Mongrel2::M2SHCommand
 	# Utility methods
 	#
 
+	#######
+	private
+	#######
+
 	### Output normal output
 	def message( *parts )
 		self.prompt.say( parts.map(&:to_s).join($/) )
@@ -676,6 +717,19 @@ class Mongrel2::M2SHCommand
 		return server
 	end
 
+
+	### Invoke the user's editor on the given +filename+ and return the exit code
+	### from doing so.
+	def edit( filename )
+		editor = ENV['EDITOR'] || ENV['VISUAL'] || DEFAULT_EDITOR
+		system editor, filename.to_s
+		unless $?.success? || editor =~ /vim/i
+			raise "Editor exited with an error status (%d)" % [ $?.exitstatus ]
+		end
+	end
+
+
+
 end # class Mongrel2::M2SHCommand
 
 

data/data/mongrel2/config.rb.in

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+#encoding: utf-8
+
+require 'pathname'
+require 'tmpdir'
+
+# This is a Ruby script that will *generate* the SQLite database
+# that Mongrel2 uses for its configuration. You can just as easily
+# use Mongrel2's 'm2sh' and the Pythonish config syntax described
+# in the manual if you prefer that.
+#
+# See the "Mongrel2 Config DSL" section of the API docs, and the "How A
+# Config Is Structured" section of the manual for details
+# on specific items:
+#
+# Mongrel2 Config DSL::
+#   http://deveiate.org/code/mongrel2/DSL_rdoc.html
+#
+# How A Config Is Structured::
+#   http://mongrel2.org/static/book-finalch4.html#x6-260003.4
+#
+# You can load this via the 'm2sh.rb' tool that comes with the 'mongrel2'
+# gem:
+#
+#   m2sh.rb -c config.sqlite load config.rb
+
+# Establish some directories
+base_dir   = Pathname( '%% PWD %%' )
+upload_dir = Pathname( Dir.tmpdir ) + 'm2spool'
+
+# Main Mongrel2 server config
+main = server 'main' do
+
+	name         'Main'
+	default_host 'localhost'
+	chroot       base_dir
+
+	# All of these values are relative to the 'chroot' value if Mongrel2
+	# is started as root. If it's not, they're relative to the directory
+	# it's started in.
+	access_log   '/logs/access.log'
+	error_log    '/logs/error.log'
+	pid_file     '/var/run/mongrel2.pid'
+
+	# This the address and port the server will listen on. You can
+	# use '0.0.0.0' as the bind_addr to listen on all interfaces/IPs.
+	bind_addr    '127.0.0.1'
+	port         8113
+
+	host 'localhost' do
+
+		# Serve static content out of a 'public' subdirectory
+		route '/', directory( "public/", 'index.html', 'text/html' )
+
+		# Dynamic content is served via handler routes
+		route '/hello', handler( 'tcp://127.0.0.1:9999',  'helloworld' )
+
+	end
+
+end
+
+setting 'limits.content_length', 512 * 1024
+setting 'control_port', 'ipc://var/run/mongrel2.sock'
+setting 'upload.temp_store', upload_dir + 'mongrel2.upload.XXXXXX'
+
+# Make relative directories so that starting as a regular user works
+(base_dir + "./#{main.access_log}").dirname.mkpath
+(base_dir + "./#{main.error_log}").dirname.mkpath
+(base_dir + "./#{main.pid_file}").dirname.mkpath
+mkdir_p( upload_dir )
+

data/examples/.env

@@ -1 +1,2 @@
 RUBYOPT=-I../lib
+MONGREL2=/Users/mgranger/source/C/mongrel2/bin/mongrel2

data/examples/Procfile

@@ -3,4 +3,4 @@ mongrel2: ruby ../bin/m2sh.rb -c examples.sqlite start
 helloworld: ruby helloworld-handler.rb
 async_upload: ruby async-upload.rb
 request_dumper: ruby request-dumper.rb
-ws: ruby ws-echo.rb
+ws: ruby -w ws-echo.rb

data/examples/config.rb

@@ -23,7 +23,7 @@ server 'examples' do
 	chroot       '/var/mongrel2'
 	pid_file     '/var/run/mongrel2.pid'
 
-	bind_addr    '127.0.0.1'
+	bind_addr    '0.0.0.0'
 	port         8113
 
 	# your main host

data/examples/ws-echo.rb

@@ -86,6 +86,18 @@ class WebSocketEchoServer < Mongrel2::Handler
 	end
 
 
+	# Handle the initial handshake. Assumes no sub-protocols or protocol version
+	# checks are necessary.
+	def handle_websocket_handshake( handshake )
+		self.log.info "Handshake from %s" % [ handshake.remote_ip ]
+
+		response = handshake.response( handshake.protocols.first )
+		@connections[ [handshake.sender_id, handshake.conn_id] ] = Time.now
+
+		return response
+	end
+
+
 	# This is the main handler for WebSocket requests. Each frame comes in as a
 	# Mongrel::WebSocket::Frame object, and then is dispatched according to what
 	# opcode it has.

data/lib/mongrel2.rb

@@ -20,10 +20,10 @@ module Mongrel2
 	abort "\n\n>>> Mongrel2 requires Ruby 1.9.2 or later. <<<\n\n" if RUBY_VERSION < '1.9.2'
 
 	# Library version constant
-	VERSION = '0.26.0'
+	VERSION = '0.27.0'
 
 	# Version-control revision constant
-	REVISION = %q$Revision: c2eac469ca66 $
+	REVISION = %q$Revision: 6de3cbe2409c $
 
 
 	require 'mongrel2/constants'

data/lib/mongrel2/config.rb

@@ -28,6 +28,7 @@ end
 
 require 'mongrel2' unless defined?( Mongrel2 )
 require 'mongrel2/table'
+require 'mongrel2/constants'
 
 module Mongrel2
 
@@ -42,10 +43,11 @@ module Mongrel2
 	# plugins.
 	#
 	# == References
-	# * http://mongrel2.org/static/mongrel2-manual.html#x1-250003.4
+	# * http://mongrel2.org/static/book-finalch4.html#x6-260003.4
 	#
 	class Config < Sequel::Model
 		extend Loggability
+		include Mongrel2::Constants
 
 		# Loggability API -- set up logging under the 'mongrel2' log host
 		log_to :mongrel2
@@ -63,13 +65,6 @@ module Mongrel2
 		}
 		DEFAULTS = CONFIG_DEFAULTS
 
-		# The Pathname of the data directory
-		DATA_DIR = if Gem.datadir( 'mongrel2' )
-				Pathname( Gem.datadir('mongrel2') )
-			else
-				Pathname( __FILE__ ).dirname.parent.parent + 'data/mongrel2'
-			end
-
 		# The Pathname of the SQL file used to create the config database
 		CONFIG_SQL    = DATA_DIR + 'config.sql'
 

data/lib/mongrel2/connection.rb

@@ -15,7 +15,7 @@ require 'mongrel2' unless defined?( Mongrel2 )
 # then encodes and sends Mongrel2::Response objects back to the server.
 #
 # == References
-# * http://mongrel2.org/static/mongrel2-manual.html#x1-700005.3
+# * http://mongrel2.org/static/book-finalch6.html#x8-710005.3
 class Mongrel2::Connection
 	extend Loggability
 

data/lib/mongrel2/constants.rb

@@ -8,9 +8,21 @@ require 'mongrel2' unless defined?( Mongrel2 )
 # A collection of constants that are shared across the library
 module Mongrel2::Constants
 
+	# The Pathname of the data directory
+	DATA_DIR = if ENV['MONGREL2_DATADIR']
+			Pathname( ENV['MONGREL2_DATADIR'] )
+		elsif Gem.datadir( 'mongrel2' )
+			Pathname( Gem.datadir('mongrel2') )
+		else
+			Pathname( __FILE__ ).dirname.parent.parent + 'data/mongrel2'
+		end
+
 	# The path to the default Sqlite configuration database
 	DEFAULT_CONFIG_URI = 'config.sqlite'
 
+	# The default name of the config-generation script
+	DEFAULT_CONFIG_SCRIPT = 'config.rb'
+
 	# The default URI of the control socket
 	DEFAULT_CONTROL_SOCKET = 'ipc://run/control'
 

data/lib/mongrel2/control.rb

@@ -11,7 +11,7 @@ require 'mongrel2' unless defined?( Mongrel2 )
 # An interface to the Mongrel2 control port.
 #
 # == References
-# (http://mongrel2.org/static/mongrel2-manual.html#x1-380003.8)
+# (http://mongrel2.org/static/book-finalch4.html#x6-390003.8)
 class Mongrel2::Control
 	extend Loggability
 

data/lib/mongrel2/handler.rb

@@ -207,19 +207,18 @@ class Mongrel2::Handler
 			return self.handle_async_upload_start( request )
 
 		else
+			self.log.debug "%s request." % [ request.headers['METHOD'] ]
 			case request
+			when Mongrel2::WebSocket::ClientHandshake
+				return self.handle_websocket_handshake( request )
+			when Mongrel2::WebSocket::Frame
+				return self.handle_websocket( request )
 			when Mongrel2::HTTPRequest
-				self.log.debug "HTTP request."
 				return self.handle( request )
 			when Mongrel2::JSONRequest
-				self.log.debug "JSON message request."
 				return self.handle_json( request )
 			when Mongrel2::XMLRequest
-				self.log.debug "XML message request."
 				return self.handle_xml( request )
-			when Mongrel2::WebSocket::Frame
-				self.log.debug "WEBSOCKET message request."
-				return self.handle_websocket( request )
 			else
 				self.log.error "Unhandled request type %s (%p)" %
 					[ request.headers['METHOD'], request.class ]
@@ -279,10 +278,24 @@ class Mongrel2::Handler
 	### Handle a WebSocket frame in +request+. If not overridden, WebSocket connections are
 	### closed with a policy error status.
 	def handle_websocket( request )
-		self.log.warn "Unhandled WEBSOCKET message request (%p)" % [ request.headers.path ]
+		self.log.warn "Unhandled WEBSOCKET frame (%p)" % [ request.headers.path ]
 		res = request.response
 		res.make_close_frame( WebSocket::CLOSE_POLICY_VIOLATION )
-		return res
+		self.conn.reply( res)
+
+		self.conn.reply_close( request )
+
+		return nil
+	end
+
+
+	### Handle a WebSocket handshake HTTP +request+. If not overridden, this method drops
+	### the connection.
+	def handle_websocket_handshake( handshake )
+		self.log.warn "Unhandled WEBSOCKET_HANDSHAKE request (%p)" % [ request.headers.path ]
+		self.conn.reply_close( request )
+
+		return nil
 	end
 
 

data/lib/mongrel2/httpresponse.rb

@@ -169,12 +169,13 @@ class Mongrel2::HTTPResponse < Mongrel2::Response
 		headers = self.headers.dup
 
 		headers[:date] ||= Time.now.httpdate
-		headers[:content_length] ||= self.get_content_length
 
 		if self.bodiless?
+			headers.delete( :content_length )
 			headers.delete( :content_type )
 		else
-			headers[:content_type] ||= DEFAULT_CONTENT_TYPE.dup
+			headers[:content_length] ||= self.get_content_length
+			headers[:content_type]   ||= DEFAULT_CONTENT_TYPE.dup
 		end
 
 		return headers
@@ -184,11 +185,11 @@ class Mongrel2::HTTPResponse < Mongrel2::Response
 	### Get the length of the body IO. If the IO's offset is somewhere other than
 	### the beginning or end, the size of the remainder is used.
 	def get_content_length
-		if self.bodiless?
-			return 0
-		elsif self.body.pos.nonzero? && !self.body.eof?
+		if self.body.pos.nonzero? && !self.body.eof?
+			self.log.info "Calculating content length based on an offset of %d" % [ self.body.pos ]
 			return self.body.size - self.body.pos
 		else
+			self.log.debug "Calculating body size via %p" % [ self.body.method(:size) ]
 			return self.body.size
 		end
 	end

data/lib/mongrel2/testing.rb

@@ -12,13 +12,38 @@ require 'mongrel2/request'
 
 module Mongrel2
 
-	### A collection of helper functions that are generally useful
-	### for testing Mongrel2::Handlers.
+	# A collection of helper functions that are generally useful
+	# for testing Mongrel2::Handlers.
 	module SpecHelpers
 	end # module SpecHelpers
 
 
-	### A factory for generating Mongrel2::Request objects for testing.
+	# A factory for generating Mongrel2::Request objects for testing.
+	#
+	# Usage:
+	#
+	#   require 'mongrel2/testing'
+	#
+	#   describe "MyHandler" do
+	#       before( :all ) do
+	#           @factory = Mongrel2::RequestFactory.
+	#               new( sender_id: 'my-handler',
+	#                    route: '/api/v1',
+	#                    headers: {accept: 'application/json'} )
+	#       end
+	#
+	#       before( :each ) do
+	#           @app = MyHandler.new( 'my-handler', 'tcp://0.0.0.0:5556',
+	#                                 'tcp://0.0.0.0:5555' )
+	#       end
+	#
+	#       it "handles a JSON request for GET /" do
+	#           request = @factory.get( '/api/v1' )
+	#           response = @app.dispatch_request( request )
+	#           #...
+	#       end
+	#   end
+	#
 	class RequestFactory
 		extend Loggability
 
@@ -218,14 +243,11 @@ module Mongrel2
 	end # RequestFactory
 
 
-	### A factory for generating WebSocket request objects for testing.
+	# A factory for generating WebSocket request objects for testing.
+	#
 	class WebSocketFrameFactory < Mongrel2::RequestFactory
-		extend Loggability
 		include Mongrel2::Constants
 
-		# Loggability API -- set up logging under the 'mongrel2' log host
-		log_to :mongrel2
-
 		# The default host
 		DEFAULT_TESTING_HOST  = 'localhost'
 		DEFAULT_TESTING_PORT  = '8113'
@@ -261,6 +283,8 @@ module Mongrel2
 			:headers       => DEFAULT_TESTING_HEADERS,
 		}
 
+		DEFAULT_HANDSHAKE_BODY = 'GR7M5bFPiY2GvVc5a7CIMErQ18Q='
+
 		# Freeze all testing constants
 		constants.each do |cname|
 			const_get(cname).freeze
@@ -285,6 +309,26 @@ module Mongrel2
 		public
 		######
 
+		### Create an initial websocket handshake request and return it.
+		def handshake( uri, *subprotocols )
+			raise "Request doesn't route through %p" % [ self.route ] unless
+				uri.start_with?( self.route )
+
+			headers = if subprotocols.last.is_a?( Hash ) then subprotocols.pop else {} end
+			headers = self.make_merged_headers( uri, 0, headers )
+			headers.delete( :flags )
+
+			unless subprotocols.empty?
+				protos = subprotocols.map( &:to_s ).join( ', ' )
+				headers.sec_websocket_protocol = protos
+			end
+
+			rclass = Mongrel2::Request.subclass_for_method( :WEBSOCKET_HANDSHAKE )
+
+			return rclass.new( self.sender_id, self.conn_id.to_s, self.route, headers, DEFAULT_HANDSHAKE_BODY.dup )
+		end
+
+
 		### 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

data/lib/mongrel2/websocket.rb

@@ -9,6 +9,11 @@ require 'mongrel2/constants'
 #
 #   class WebSocketEchoServer
 #
+#       def handle_websocket_handshake( handshake )
+#           # :TODO: Sub-protocol/protocol version checks?
+#           return handshake.response
+#       end
+#
 #       def handle_websocket( frame )
 #
 #           # Close connections that send invalid frames
@@ -191,6 +196,93 @@ module Mongrel2::WebSocket
 	# Exception raised when a frame is malformed, doesn't parse, or is otherwise invalid.
 	class FrameError < Mongrel2::WebSocket::Error; end
 
+	# Exception raised when a handshake is created with an unrequested sub-protocol.
+	class HandshakeError < Mongrel2::WebSocket::Error; end
+
+
+	# The client (request) handshake for a WebSocket opening handshake.
+	class ClientHandshake < Mongrel2::HTTPRequest
+		include Mongrel2::WebSocket::Constants
+
+		# Set this class as the one that will handle WEBSOCKET_HANDSHAKE requests
+		register_request_type( self, :WEBSOCKET_HANDSHAKE )
+
+
+		### Override the type of response returned by this request type. Since
+		### websocket handshakes are symmetrical, responses are just new
+		### Mongrel2::WebSocket::Handshakes with the same Mongrel2 sender
+		### and connection IDs.
+		def self::response_class
+			return Mongrel2::WebSocket::ServerHandshake
+		end
+
+
+		######
+		public
+		######
+
+		### The list of protocols in the handshake's Sec-WebSocket-Protocol header
+		### as an Array of Strings.
+		def protocols
+			return ( self.headers.sec_websocket_protocol || '' ).split( /\s*,\s*/ )
+		end
+
+
+		### Create a Mongrel2::WebSocket::Handshake that will respond to the same server/connection as
+		### the receiver.
+		def response( protocol=nil )
+			@response = super() unless @response
+			if protocol
+				raise Mongrel2::WebSocket::HandshakeError,
+					"attempt to create a %s handshake which isn't supported by the client." %
+					[ protocol ] unless self.protocols.include?( protocol.to_s )
+				@response.protocols = protocol
+			end
+
+			return @response
+		end
+
+	end # class ClientHandshake
+
+
+	# The server (response) handshake for a WebSocket opening handshake.
+	class ServerHandshake < Mongrel2::HTTPResponse
+		include Mongrel2::WebSocket::Constants
+
+		### Create a server handshake frame from the given client +handshake+.
+		def self::from_request( handshake )
+			self.log.debug "Creating the server handshake for client handshake %p" % [ handshake ]
+			response = super
+			response.body.truncate( 0 )
+
+			# Mongrel2 puts the negotiated key in the body of the request
+			response.headers.sec_websocket_accept = handshake.body.read
+
+			# Set up the other typical server handshake values
+			response.status = HTTP::SWITCHING_PROTOCOLS
+			response.header.upgrade = 'websocket'
+			response.header.connection = 'Upgrade'
+
+			return response
+		end
+
+
+		### The list of protocols in the handshake's Sec-WebSocket-Protocol header
+		### as an Array of Strings.
+		def protocols
+			return ( self.headers.sec_websocket_protocol || '' ).split( /\s*,\s*/ )
+		end
+
+
+		### Set the list of protocols in the handshake's Sec-WebSocket-Protocol header.
+		def protocols=( new_protocols )
+			value = Array( new_protocols ).join( ', ' )
+			self.headers.sec_websocket_protocol = value
+		end
+
+
+	end # class ServerHandshake
+
 
 	# WebSocket frame class; this is used for both requests and responses in
 	# WebSocket services.
@@ -207,7 +299,8 @@ module Mongrel2::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.
+		### Mongrel2::WebSocket::Frames with the same Mongrel2 sender and
+		### connection IDs.
 		def self::response_class
 			return self
 		end
@@ -448,10 +541,13 @@ module Mongrel2::WebSocket
 		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.
+		### Create a frame in response to the receiving Frame (i.e., with the same
+		### Mongrel2 connection ID and sender). This automatically sets up the correct
+		### status, Sec-WebSocket-Accept:, Connection, and Upgrade: headers based on the
+		### receiver. If +protocol+ is non-nil, and it matches one of the
+		### values listed in 'Sec-WebSocket-Protocol', it will be set as the
+		### Handshake's Sec-WebSocket-Protocol header. If it is non-nil, but doesn't
+		### match one of the request's values, a Mongrel2::WebSocket::Error is raised.
 		def response( *flags )
 			unless @response
 				@response = super()

data/spec/lib/constants.rb

@@ -109,6 +109,54 @@ module Mongrel2::TestConstants # :nodoc:all
 		}
 
 
+		#
+		# WebSocket frame constants
+		#
+
+		TEST_WEBSOCKET_PATH = '/ws'
+
+		TEST_WEBSOCKET_HEADERS = {
+			 'connection'               => 'Upgrade',
+			 'FLAGS'                    => '0x8A',
+			 'host'                     => 'host.example.com:80',
+			 'METHOD'                   => 'WEBSOCKET',
+			 'origin'                   => 'http://host.example.com:80',
+			 'PATH'                     => TEST_WEBSOCKET_PATH,
+			 'PATTERN'                  => TEST_WEBSOCKET_PATH,
+			 'sec-websocket-extensions' => 'x-webkit-deflate-frame',
+			 'sec-websocket-key'        => 'SQvDVdT2SbgTg6P/lSZo7Q==',
+			 'sec-websocket-protocol'   => 'echo',
+			 'sec-websocket-version'    => '13',
+			 'upgrade'                  => 'websocket',
+			 'URI'                      => TEST_WEBSOCKET_PATH,
+			 'VERSION'                  => 'HTTP/1.1',
+			 'x-forwarded-for'          => '127.0.0.2',
+		}
+		TEST_WEBSOCKET_HANDSHAKE_HEADERS = {
+			'connection'               => 'Upgrade',
+			'host'                     => 'host.example.com:80',
+			'METHOD'                   => 'WEBSOCKET_HANDSHAKE',
+			'origin'                   => 'http://host.example.com:80',
+			'PATH'                     => TEST_WEBSOCKET_PATH,
+			'PATTERN'                  => TEST_WEBSOCKET_PATH,
+			'sec-websocket-extensions' => 'x-webkit-deflate-frame',
+			'sec-websocket-key'        => 'SQvDVdT2SbgTg6P/lSZo7Q==',
+			'sec-websocket-protocol'   => 'echo',
+			'sec-websocket-version'    => '13',
+			'upgrade'                  => 'websocket',
+			'URI'                      => TEST_WEBSOCKET_PATH,
+			'VERSION'                  => 'HTTP/1.1',
+			'x-forwarded-for'          => '127.0.0.2',
+		}
+		TEST_WEBSOCKET_BODY = 'GR7M5bFPiY2GvVc5a7CIMErQ18Q='
+		TEST_WEBSOCKET_REQUEST_OPTS = {
+			:uuid    => TEST_UUID,
+			:id      => TEST_ID,
+			:path    => TEST_WEBSOCKET_PATH,
+			:body    => '',
+		}
+
+
 		#
 		# HTTP constants
 		#

data/spec/lib/helpers.rb

@@ -114,13 +114,14 @@ module Mongrel2::SpecHelpers
 		bodystring = TNetstring.dump( opts[:body] || '' )
 
 		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
-		return "%s %d %s %s%s" % [
+		data = "%s %d %s %s%s" % [
 			opts[:uuid],
 			opts[:id],
 			opts[:path],
 			headerstring,
 			bodystring,
 		]
+		return data.encode( 'binary' )
 	end
 
 
@@ -134,13 +135,14 @@ module Mongrel2::SpecHelpers
 		bodystring = TNetstring.dump( opts[:body] || '' )
 
 		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
-		return "%s %d %s %s%s" % [
+		data = "%s %d %s %s%s" % [
 			opts[:uuid],
 			opts[:id],
 			opts[:path],
 			headerstring,
 			bodystring,
 		]
+		return data.encode( 'binary' )
 	end
 
 
@@ -156,13 +158,14 @@ module Mongrel2::SpecHelpers
 		bodystring = TNetstring.dump( Yajl::Encoder.encode(opts[:body] || []) )
 
 		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
-		return "%s %d %s %s%s" % [
+		data = "%s %d %s %s%s" % [
 			opts[:uuid],
 			opts[:id],
 			opts[:path],
 			headerstring,
 			bodystring,
 		]
+		return data.encode( 'binary' )
 	end
 
 
@@ -178,13 +181,56 @@ module Mongrel2::SpecHelpers
 		bodystring = TNetstring.dump( opts[:body] || "#{TEST_XML_PATH} />" )
 
 		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
-		return "%s %d %s %s%s" % [
+		data = "%s %d %s %s%s" % [
 			opts[:uuid],
 			opts[:id],
 			opts[:path],
 			headerstring,
 			bodystring,
 		]
+		return data.encode( 'binary' )
+	end
+
+	### Make a Mongrel2 handshake request for a WebSocket route.
+	def make_websocket_handshake( opts={} )
+		opts = TEST_WEBSOCKET_REQUEST_OPTS.merge( opts )
+		headers = normalize_headers( opts, TEST_WEBSOCKET_HANDSHAKE_HEADERS )
+
+		Mongrel2.log.debug "WebSocket start handshake, headers = %p, opts = %p" % [ headers, opts ]
+
+		headerstring = TNetstring.dump( Yajl::Encoder.encode(headers) )
+		bodystring = TNetstring.dump( opts[:body] || TEST_WEBSOCKET_BODY )
+
+		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
+		data = "%s %d %s %s%s" % [
+			opts[:uuid],
+			opts[:id],
+			opts[:path],
+			headerstring,
+			bodystring,
+		]
+		return data.encode( 'binary' )
+	end
+
+	### Make a Mongrel2 frame for a WebSocket route.
+	def make_websocket_frame( opts={} )
+		opts = TEST_WEBSOCKET_REQUEST_OPTS.merge( opts )
+		headers = normalize_headers( opts, TEST_WEBSOCKET_HEADERS )
+
+		Mongrel2.log.debug "WebSocket frame, headers = %p, opts = %p" % [ headers, opts ]
+
+		headerstring = TNetstring.dump( Yajl::Encoder.encode(headers) )
+		bodystring = TNetstring.dump( opts[:body] )
+
+		# UUID ID PATH SIZE:HEADERS,SIZE:BODY,
+		data = "%s %d %s %s%s" % [
+			opts[:uuid],
+			opts[:id],
+			opts[:path],
+			headerstring,
+			bodystring,
+		]
+		return data.encode( 'binary' )
 	end
 
 end

data/spec/mongrel2/handler_spec.rb

@@ -209,6 +209,42 @@ describe Mongrel2::Handler do
 		response.should be_a( Mongrel2::Response )
 	end
 
+	it "dispatches WebSocket opening handshakes to the #handle_websocket_handshake method" do
+		ws_handler = Class.new( OneShotHandler ) do
+			def handle_websocket_handshake( handshake )
+				return handshake.response
+			end
+		end
+
+		req = make_websocket_handshake()
+		@request_sock.should_receive( :recv ).and_return( req )
+
+		res = ws_handler.new( TEST_UUID, TEST_SEND_SPEC, TEST_RECV_SPEC ).run
+
+		res.transactions.should have( 1 ).member
+		request, response = res.transactions.first
+		request.should be_a( Mongrel2::WebSocket::ClientHandshake )
+		response.should be_a( Mongrel2::WebSocket::ServerHandshake )
+	end
+
+	it "dispatches WebSocket protocol frames to the #handle_websocket method" do
+		ws_handler = Class.new( OneShotHandler ) do
+			def handle_websocket( frame )
+				return frame.response
+			end
+		end
+
+		req = make_websocket_frame()
+		@request_sock.should_receive( :recv ).and_return( req )
+
+		res = ws_handler.new( TEST_UUID, TEST_SEND_SPEC, TEST_RECV_SPEC ).run
+
+		res.transactions.should have( 1 ).member
+		request, response = res.transactions.first
+		request.should be_a( Mongrel2::WebSocket::Frame )
+		response.should be_a( Mongrel2::WebSocket::Frame )
+	end
+
 	it "continues when a ZMQ::Error is received but the connection remains open" do
 		req = make_request()
 

data/spec/mongrel2/httpresponse_spec.rb

@@ -55,7 +55,7 @@ describe Mongrel2::HTTPResponse do
 	it "returns an empty response if its status is set to NO_CONTENT" do
 		@response.puts "The response body"
 		@response.status = HTTP::NO_CONTENT
-		@response.header_data.should =~ /Content-length: 0/i
+		@response.header_data.should_not =~ /Content-length/i
 		@response.header_data.should_not =~ /Content-type/i
 		@response.to_s.should_not =~ /The response body/i
 	end
@@ -69,9 +69,10 @@ describe Mongrel2::HTTPResponse do
 	end
 
 	it "re-calculates the automatically-added headers when re-rendered" do
-		@response.header_data.should =~ /Content-length: 0/i
+		@response.header_data.should =~ /Content-length: 0\b/i
+		@response.status = HTTP::OK
 		@response << "More data!"
-		@response.header_data.should =~ /Content-length: 10/i
+		@response.header_data.should =~ /Content-length: 10\b/i
 	end
 
 	it "doesn't have a body" do

data/spec/mongrel2/websocket_spec.rb

@@ -53,6 +53,69 @@ describe Mongrel2::WebSocket do
 	BINARY_DATA.force_encoding( Encoding::ASCII_8BIT )
 
 
+	describe 'ClientHandshake' do
+
+		it "is the registered request type for WEBSOCKET_HANDSHAKE requests" do
+			Mongrel2::Request.request_types[:WEBSOCKET_HANDSHAKE].should == Mongrel2::WebSocket::ClientHandshake
+		end
+
+		it "knows what subprotocols were requested" do
+			handshake = @factory.handshake( '/websock', 'echo', 'superecho' )
+			handshake.protocols.should == ['echo', 'superecho']
+		end
+
+		it "doesn't error if no subprotocols were requested" do
+			handshake = @factory.handshake( '/websock' )
+			handshake.protocols.should == []
+		end
+
+		it "can create a response WebSocket::ServerHandshake for itself" do
+			handshake = @factory.handshake( '/websock' )
+			result = handshake.response
+			handshake.body.rewind
+
+			result.should be_a( Mongrel2::WebSocket::ServerHandshake )
+			result.sender_id.should == handshake.sender_id
+			result.conn_id.should == handshake.conn_id
+			result.header.sec_websocket_accept.should == handshake.body.string
+			result.status.should == HTTP::SWITCHING_PROTOCOLS
+			result.header.connection.should =~ /upgrade/i
+			result.header.upgrade.should =~ /websocket/i
+
+			result.body.rewind
+			result.body.read.should == ''
+		end
+
+		it "can create a response WebSocket::ServerHandshake with a valid sub-protocol for itself" do
+			handshake = @factory.handshake( '/websock', 'echo', 'superecho' )
+			result = handshake.response( :superecho )
+			handshake.body.rewind
+
+			result.should be_a( Mongrel2::WebSocket::ServerHandshake )
+			result.sender_id.should == handshake.sender_id
+			result.conn_id.should == handshake.conn_id
+			result.header.sec_websocket_accept.should == handshake.body.string
+			result.status.should == HTTP::SWITCHING_PROTOCOLS
+			result.header.connection.should =~ /upgrade/i
+			result.header.upgrade.should =~ /websocket/i
+			result.protocols.should == ['superecho']
+
+			result.body.rewind
+			result.body.read.should == ''
+		end
+
+		it "raises an exception if the specified protocol is not one of the client's advertised ones" do
+			handshake = @factory.handshake( '/websock', 'echo', 'superecho' )
+
+			expect {
+				handshake.response( :map_updates )
+			}.to raise_error( Mongrel2::WebSocket::HandshakeError, /map_updates/i )
+		end
+
+	end
+
+
+
 	describe 'Frame' do
 
 		it "is the registered request type for WEBSOCKET requests" do
@@ -310,5 +373,6 @@ describe Mongrel2::WebSocket do
 
 	end
 
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongrel2
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
   prerelease: 
 platform: ruby
 authors:
@@ -36,7 +36,7 @@ cert_chain:
   YUhDS0xaZFNLai9SSHVUT3QrZ2JsUmV4OEZBaDhOZUEKY21saFhlNDZwWk5K
   Z1dLYnhaYWg4NWpJang5NWhSOHZPSStOQU01aUg5a09xSzEzRHJ4YWNUS1Bo
   cWo1UGp3RgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
-date: 2012-06-26 00:00:00.000000000 Z
+date: 2012-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -328,6 +328,7 @@ files:
 - Rakefile
 - bin/m2sh.rb
 - data/mongrel2/bootstrap.html
+- data/mongrel2/config.rb.in
 - data/mongrel2/config.sql
 - data/mongrel2/css/master.css
 - data/mongrel2/js/websock-test.js