mongrel2 0.0.1

data/lib/mongrel2/constants.rb

@@ -0,0 +1,159 @@
+#!/usr/bin/ruby
+#encoding: utf-8
+
+require 'pathname'
+require 'mongrel2' unless defined?( Mongrel2 )
+
+
+# A collection of constants that are shared across the library
+module Mongrel2::Constants
+
+	# The path to the default Sqlite configuration database
+	DEFAULT_CONFIG_URI = 'config.sqlite'
+
+	# Maximum number of identifiers that can be included in a broadcast response
+	MAX_BROADCAST_IDENTS = 100
+
+
+	# HTTP status and result constants
+	module HTTP
+		SWITCHING_PROTOCOLS 		  = 101
+		PROCESSING          		  = 102
+
+		OK                			  = 200
+		CREATED           			  = 201
+		ACCEPTED          			  = 202
+		NON_AUTHORITATIVE 			  = 203
+		NO_CONTENT        			  = 204
+		RESET_CONTENT     			  = 205
+		PARTIAL_CONTENT   			  = 206
+		MULTI_STATUS      			  = 207
+
+		MULTIPLE_CHOICES   			  = 300
+		MOVED_PERMANENTLY  			  = 301
+		MOVED              			  = 301
+		MOVED_TEMPORARILY  			  = 302
+		REDIRECT           			  = 302
+		SEE_OTHER          			  = 303
+		NOT_MODIFIED       			  = 304
+		USE_PROXY          			  = 305
+		TEMPORARY_REDIRECT 			  = 307
+
+		BAD_REQUEST                   = 400
+		AUTH_REQUIRED                 = 401
+		UNAUTHORIZED                  = 401
+		PAYMENT_REQUIRED              = 402
+		FORBIDDEN                     = 403
+		NOT_FOUND                     = 404
+		METHOD_NOT_ALLOWED            = 405
+		NOT_ACCEPTABLE                = 406
+		PROXY_AUTHENTICATION_REQUIRED = 407
+		REQUEST_TIME_OUT              = 408
+		CONFLICT                      = 409
+		GONE                          = 410
+		LENGTH_REQUIRED               = 411
+		PRECONDITION_FAILED           = 412
+		REQUEST_ENTITY_TOO_LARGE      = 413
+		REQUEST_URI_TOO_LARGE         = 414
+		UNSUPPORTED_MEDIA_TYPE        = 415
+		RANGE_NOT_SATISFIABLE         = 416
+		EXPECTATION_FAILED            = 417
+		UNPROCESSABLE_ENTITY          = 422
+		LOCKED                        = 423
+		FAILED_DEPENDENCY             = 424
+
+		SERVER_ERROR          		  = 500
+		NOT_IMPLEMENTED       		  = 501
+		BAD_GATEWAY           		  = 502
+		SERVICE_UNAVAILABLE   		  = 503
+		GATEWAY_TIME_OUT      		  = 504
+		VERSION_NOT_SUPPORTED 		  = 505
+		VARIANT_ALSO_VARIES   		  = 506
+		INSUFFICIENT_STORAGE  		  = 507
+		NOT_EXTENDED          		  = 510
+
+		# Stolen from Apache 2.2.6's modules/http/http_protocol.c
+		STATUS_NAME = {
+		    100 => "Continue",
+		    101 => "Switching Protocols",
+		    102 => "Processing",
+		    200 => "OK",
+		    201 => "Created",
+		    202 => "Accepted",
+		    203 => "Non-Authoritative Information",
+		    204 => "No Content",
+		    205 => "Reset Content",
+		    206 => "Partial Content",
+		    207 => "Multi-Status",
+		    300 => "Multiple Choices",
+		    301 => "Moved Permanently",
+		    302 => "Found",
+		    303 => "See Other",
+		    304 => "Not Modified",
+		    305 => "Use Proxy",
+		    306 => "Undefined HTTP Status",
+		    307 => "Temporary Redirect",
+		    400 => "Bad Request",
+		    401 => "Authorization Required",
+		    402 => "Payment Required",
+		    403 => "Forbidden",
+		    404 => "Not Found",
+		    405 => "Method Not Allowed",
+		    406 => "Not Acceptable",
+		    407 => "Proxy Authentication Required",
+		    408 => "Request Time-out",
+		    409 => "Conflict",
+		    410 => "Gone",
+		    411 => "Length Required",
+		    412 => "Precondition Failed",
+		    413 => "Request Entity Too Large",
+		    414 => "Request-URI Too Large",
+		    415 => "Unsupported Media Type",
+		    416 => "Requested Range Not Satisfiable",
+		    417 => "Expectation Failed",
+		    418 => "Undefined HTTP Status",
+		    419 => "Undefined HTTP Status",
+		    420 => "Undefined HTTP Status",
+		    421 => "Undefined HTTP Status",
+		    406 => "Not Acceptable",
+		    407 => "Proxy Authentication Required",
+		    408 => "Request Time-out",
+		    409 => "Conflict",
+		    410 => "Gone",
+		    411 => "Length Required",
+		    412 => "Precondition Failed",
+		    413 => "Request Entity Too Large",
+		    414 => "Request-URI Too Large",
+		    415 => "Unsupported Media Type",
+		    416 => "Requested Range Not Satisfiable",
+		    417 => "Expectation Failed",
+		    418 => "Undefined HTTP Status",
+		    419 => "Undefined HTTP Status",
+		    420 => "Undefined HTTP Status",
+		    421 => "Undefined HTTP Status",
+		    422 => "Unprocessable Entity",
+		    423 => "Locked",
+		    424 => "Failed Dependency",
+		    425 => "No code",
+		    426 => "Upgrade Required",
+		    500 => "Internal Server Error",
+		    501 => "Method Not Implemented",
+		    502 => "Bad Gateway",
+		    503 => "Service Temporarily Unavailable",
+		    504 => "Gateway Time-out",
+		    505 => "HTTP Version Not Supported",
+		    506 => "Variant Also Negotiates",
+		    507 => "Insufficient Storage",
+		    508 => "Undefined HTTP Status",
+		    509 => "Undefined HTTP Status",
+		    510 => "Not Extended"
+		}
+
+
+		# Methods which aren't allowed to have an entity-body
+		SHALLOW_METHODS = [ :GET, :HEAD, :DELETE ]
+	end
+
+
+end # module Mongrel2::Constants
+

data/lib/mongrel2/control.rb

@@ -0,0 +1,165 @@
+#!/usr/bin/ruby
+
+require 'zmq'
+require 'yajl'
+require 'tnetstring'
+
+require 'mongrel2' unless defined?( Mongrel2 )
+require 'mongrel2/mixins'
+
+
+# An interface to the Mongrel2 control port.
+#
+# == References
+# (http://mongrel2.org/static/mongrel2-manual.html#x1-380003.8)
+class Mongrel2::Control
+	include Mongrel2::Loggable
+
+	# The default zmq connection spec to use when talking to a mongrel2 server
+	DEFAULT_PORT = 'ipc://run/control'
+
+
+	### Create a new control port object using the current configuration.
+	def initialize( port=DEFAULT_PORT )
+		@ctx = Mongrel2.zmq_context
+		@socket = @ctx.socket( ZMQ::REQ )
+		@socket.connect( port.to_s )
+	end
+
+
+	######
+	public
+	######
+
+	# The control port ZMQ::REQ socket
+	attr_reader :socket
+
+
+	### Stops the server using a SIGINT.
+	def stop
+		self.request( :stop )
+	end
+
+
+	### Reloads the server using a SIGHUP.
+	def reload
+		self.request( :reload )
+	end
+
+
+	### Terminates the server with SIGTERM.
+	def terminate
+		self.request( :terminate )
+	end
+
+
+	### Prints out a simple help message.
+	def help
+		self.request( :help )
+	end
+
+
+	### Returns the server’s UUID as a String.
+	def uuid
+		self.request( :uuid )
+	end
+
+
+	### More information about the server.
+	def info
+		self.request( :info )
+	end
+
+
+	### Returns a Hash of all the currently running tasks and what they’re doing, keyed
+	### by conn_id.
+	def tasklist
+		self.request( :status, :what => 'tasks' )
+	end
+
+
+	### Dumps a JSON dict that matches connections IDs (same ones your handlers 
+	### get) to the seconds since their last ping. In the case of an HTTP 
+	### connection this is how long they’ve been connected. In the case of a 
+	### JSON socket this is the last time a ping message was received.
+	def conn_status
+		self.request( :status, :what => 'net' )
+	end
+
+
+	### Prints the unix time the server thinks it’s using. Useful for synching.
+	def time
+		response = self.request( :time )
+		response.each do |row|
+			row[ :time ] = Time.at( row.delete(:time).to_i ) if row[:time]
+		end
+
+		return response
+	end
+
+
+	### Does a forced close on the socket that is at the specified +conn_id+.
+	def kill( conn_id )
+		self.request( :kill, :id => conn_id )
+	end
+
+
+	### Shuts down the control port permanently in case you want to keep it from 
+	### being accessed for some reason.
+	def control_stop
+		self.request( :control_stop )
+	end
+
+
+	### Send a raw request to the server, asking it to perform the +command+ with the specified
+	### +options+ hash and return the results.
+	def request( command, options={} )
+		msg = TNetstring.dump([ command, options ])
+		self.log.debug "Request: %p" % [ msg ]
+		self.socket.send( msg )
+
+		response = self.socket.recv
+		self.log.debug "Response: %p" % [ response ]
+		return unpack_response( response )
+	end
+
+
+	### Close the control port connection.
+	def close
+		self.socket.close
+	end
+
+
+	#######
+	private
+	#######
+
+	### Unpack a Mongrel2 Control Port response (TNetString encoded table) as an
+	### Array of Hashes.
+	def unpack_response( response )
+		table = TNetstring.parse( response ).first
+		self.log.debug "Unpacking response: %p" % [ table ]
+
+		# Success
+		if table.key?( 'headers' )
+			headers, rows = table.values_at( 'headers', 'rows' )
+			headers.map!( &:to_sym )
+
+			return rows.collect do |row|
+				Hash[ [headers, row].transpose ]
+			end
+
+		# Error
+		elsif table.key?( 'code' )
+			# {"code"=>"INVALID_ARGUMENT", "error"=>"Invalid argument type."}
+			raise Mongrel2::ControlError.new( table['code'], table['error'] )
+
+		else
+			raise ScriptError, "Don't know how to handle response: %p" % [ table ]
+		end
+	end
+
+end # class Mongrel2::Control
+
+# vim: set nosta noet ts=4 sw=4:
+

data/lib/mongrel2/exceptions.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+#--
+module Mongrel2
+
+	# A base exception class.
+	class Exception < ::RuntimeError; end
+
+	# An exception class raised from a Mongrel2::Request when
+	# a problem is encountered while parsing raw request data.
+	class ParseError < Mongrel2::Exception; end
+
+	# An exception class raised from a Mongrel2::Request when
+	# the raw request headers contain an unhandled METHOD.
+	class UnhandledMethodError < Mongrel2::Exception
+
+		### Set the +method_name+ that was unhandled.
+		def initialize( method_name, *args )
+			@method_name = method_name
+			super( "Unhandled method %p" % [ method_name ], *args )
+		end
+
+		# The METHOD that was unhandled
+		attr_reader :method_name
+
+	end # class UnhandledMethodError
+
+	# An exception class raised when an attempt is made to use a
+	# Mongrel2::Connection after it has been closed.
+	class ConnectionError < Mongrel2::Exception; end
+
+	# An exception type raised when an operation requires that a configuration
+	# database be configured but none was; if it's configured but doesn't
+	# exist; or if it doesn't contain the information requested.
+	class ConfigError < Mongrel2::Exception; end
+
+	# An exception type raised by a response if it can't generate a valid response
+	# document
+	class ResponseError < Mongrel2::Exception; end
+
+	# An exception type raised by Mongrel2::Control requests if they result in
+	# an error response.
+	class ControlError < Mongrel2::Exception
+
+		### Set the error +code+ in addition to the +message+.
+		def initialize( code, message )
+			@code = code.to_sym
+			super( message )
+		end
+
+		# The code of the particular kind of control error (a Symbol)
+		attr_reader :code
+
+	end # class ControlError
+
+end # module Mongrel2
+
+
+# vim: set noet nosta sw=4 ts=4 :

data/lib/mongrel2/handler.rb

@@ -0,0 +1,309 @@
+#!/usr/bin/env ruby
+
+require 'mongrel2' unless defined?( Mongrel2 )
+require 'mongrel2/config'
+
+require 'mongrel2/request'
+require 'mongrel2/httprequest'
+require 'mongrel2/jsonrequest'
+
+# Mongrel2 Handler application class. Instances of this class are the applications
+# which connection to one or more Mongrel2 routes and respond to requests.
+#
+# == Example
+#
+# A dumb, dead-simple example that just returns a plaintext 'Hello'
+# document with a timestamp.
+#
+#     #!/usr/bin/env ruby
+#     
+#     require 'mongrel2/handler'
+#     
+#     class HelloWorldHandler < Mongrel2::Handler
+#     
+#       ### The main method to override -- accepts requests and 
+#       ### returns responses.
+#       def handle( request )
+#           response = request.response
+#     
+#           response.status = 200
+#           response.headers.content_type = 'text/plain'
+#           response.puts "Hello, world, it's #{Time.now}!"
+#           
+#           return response
+#       end
+#     
+#     end # class HelloWorldHandler
+#     
+#     HelloWorldHandler.run( 'helloworld-handler' )
+# 
+# This assumes the Mongrel2 SQLite config database is in the current
+# directory, and is named 'config.sqlite' (the Mongrel2 default), but
+# if it's somewhere else, you can point the Mongrel2::Config class
+# to it:
+#
+#     require 'mongrel2/config'
+#     Mongrel2::Config.configure( :configdb => 'mongrel2.db' )
+# 
+# Mongrel2 also includes support for Configurability, so you can
+# configure it along with your database connection, etc. Just add a
+# 'mongrel2' section to the config with a 'configdb' key that points
+# to where the Mongrel2 SQLite config database lives:
+#
+#     # config.yaml
+#     db:
+#       uri: postgres://www@localhost/db01
+#     
+#     mongrel2:
+#       configdb: mongrel2.db
+#     
+#     whatever_else:
+#       ...
+# 
+# Now just loading and installing the config configures Mongrel2 as 
+# well:
+#
+#     require 'configurability/config'
+#
+#     config = Configurability::Config.load( 'config.yml' )
+#     config.install
+#
+# If the Mongrel2 config database isn't accessible, or you need to
+# configure the Handler's two 0mq connections yourself for some
+# reason, you can do that, too:
+#
+#     app = HelloWorldHandler.new( 'helloworld-handler',
+#         'tcp://otherhost:9999', 'tcp://otherhost:9998' )
+#     app.run
+#     
+class Mongrel2::Handler
+	include Mongrel2::Loggable
+
+
+	### Create an instance of the handler using the config from the database with
+	### the given +appid+ and run it.
+	def self::run( appid )
+		Mongrel2.log.info "Running application %p" % [ appid ]
+		send_spec, recv_spec = self.connection_info_for( appid )
+		Mongrel2.log.info "  config specs: %s <-> %s" % [ send_spec, recv_spec ]
+		new( appid, send_spec, recv_spec ).run
+	end
+
+
+	### Return the send_spec and recv_spec for the given +appid+ from the current configuration
+	### database. Returns +nil+ if no Handler is configured with +appid+ as its +sender_id+.
+	def self::connection_info_for( appid )
+		Mongrel2.log.debug "Looking up handler spec for appid %p" % [ appid ]
+		hconfig = Mongrel2::Config::Handler.by_send_ident( appid ).first or
+			raise ArgumentError, "no handler with a send_ident of %p configured" % [ appid ]
+
+		Mongrel2.log.debug "  found: %s" % [ hconfig.values ]
+		return hconfig.send_spec, hconfig.recv_spec
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new instance of the handler with the specified +app_id+, +send_spec+,
+	### and +recv_spec+.
+	def initialize( app_id, send_spec, recv_spec ) # :notnew:
+		@conn = Mongrel2::Connection.new( app_id, send_spec, recv_spec )
+	end
+
+
+	######
+	public
+	######
+
+	# The handler's Mongrel2::Connection object.
+	attr_reader :conn
+
+
+	### Run the handler.
+	def run
+		self.log.info "Starting up %p" % [ self ]
+		self.set_signal_handlers
+		self.start_accepting_requests
+
+		return self # For chaining
+	ensure
+		self.restore_signal_handlers
+		self.log.info "Done: %p" % [ self ]
+	end
+
+
+	### Shut down the handler.
+	def shutdown
+		self.log.info "Shutting down."
+		@conn.close
+	end
+
+
+	### Restart the handler. You should override this if you want to re-establish
+	### database connections, flush caches, or other restart-ey stuff.
+	def restart
+		self.log.info "Restarting"
+		old_conn = @conn
+		@conn = @conn.dup
+		self.log.debug "  conn %p -> %p" % [ old_conn, @conn ]
+		old_conn.close
+	end
+
+
+	### Start a loop, accepting a request and handling it.
+	def start_accepting_requests
+		until @conn.closed?
+			req = @conn.receive
+			self.log.info "%p via %s:%d" % [ req.class, req.sender_id, req.conn_id ]
+
+			res = self.dispatch_request( req )
+
+			if res
+				self.log.debug "  responding with a %p" % [ res.class ]
+				@conn.reply( res ) unless @conn.closed?
+			else
+				self.log.debug "  no response; ignoring."
+			end
+		end
+	rescue ZMQ::Error => err
+		self.log.error "%p while accepting requests: %s" % [ err.class, err.message ]
+		self.log.debug { err.backtrace.join("\n  ") }
+
+		retry unless @conn.closed?
+	end
+
+
+	### Invoke a handler method appropriate for the given +request+.
+	def dispatch_request( request )
+		if request.is_disconnect?
+			self.log.debug "disconnect!"
+			self.handle_disconnect( request )
+			return nil
+
+		else
+			case 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 )
+			else
+				self.log.error "Unhandled request type %p" % [ request.class ]
+				return nil
+			end
+		end
+	end
+
+
+	### Returns a string containing a human-readable representation of the Handler suitable
+	### for debugging.
+	def inspect
+		return "#<%p:0x%08x conn: %p>" % [
+			self.class,
+			self.object_id * 2,
+			self.conn,
+		]
+	end
+
+
+	#
+	# :section: Handler Methods
+	# These methods are the principle mechanism for defining the functionality of
+	# your handler. The logic that dispatches to these methods is all contained in
+	# the #dispatch_request method, so if you want to do something completely different,
+	# you should override that instead.
+	#
+
+	### The main handler function: handle the specified HTTP +request+ (a Mongrel2::Request) and
+	### return a response (Mongrel2::Response). If not overridden, this method returns a
+	### '204 No Content' response.
+	def handle( request )
+		self.log.warn "No default handler; responding with '204 No Content'"
+		response = request.response
+		response.status = HTTP::NO_CONTENT
+
+		return response
+	end
+
+
+	### Handle a JSON message +request+. If not overridden, JSON message ('@route') 
+	### requests are ignored.
+	def handle_json( request )
+		self.log.warn "Unhandled JSON message request (%p)" % [ request.headers[:path] ]
+		return nil
+	end
+
+
+	### Handle an XML message +request+. If not overridden, XML message ('<route') 
+	### requests are ignored.
+	def handle_xml( request )
+		self.log.warn "Unhandled XML message request (%p)" % [ request.headers[:path] ]
+		return nil
+	end
+
+
+	### Handle a disconnect notice from Mongrel2 via the given +request+. Its return value
+	### is ignored.
+	def handle_disconnect( request )
+		self.log.warn "Unhandled disconnect notice."
+		return nil
+	end
+
+
+	#
+	# :section: Signal Handling
+	# These methods set up some behavior for starting, restarting, and stopping
+	# your application when a signal is received. If you don't want signals to
+	# be handled, override #set_signal_handlers with an empty method.
+	#
+
+	### Set up signal handlers for SIGINT, SIGTERM, SIGINT, and SIGUSR1 that will call the
+	### #on_hangup_signal, #on_termination_signal, #on_interrupt_signal, and 
+	### #on_user1_signal methods, respectively.
+	def set_signal_handlers
+		Signal.trap( :HUP,  &self.method(:on_hangup_signal) )
+		Signal.trap( :TERM, &self.method(:on_termination_signal) )
+		Signal.trap( :INT,  &self.method(:on_interrupt_signal) )
+		Signal.trap( :USR1, &self.method(:on_user1_signal) )
+	end
+
+
+	### Restore the default signal handlers
+	def restore_signal_handlers
+		Signal.trap( :HUP,  :DEFAULT )
+		Signal.trap( :TERM, :DEFAULT )
+		Signal.trap( :INT,  :DEFAULT )
+		Signal.trap( :USR1, :DEFAULT )
+	end
+
+
+	### Handle a HUP signal. The default is to restart the handler.
+	def on_hangup_signal( signo )
+		self.log.warn "Hangup: reconnecting."
+		self.restart
+	end
+
+
+	### Handle a TERM signal. Shuts the handler down after handling any current request/s. Also
+	### aliased to #on_interrupt_signal.
+	def on_termination_signal( signo )
+		self.log.warn "Halting on signal #{signo} (Thread: %p vs. main: %p)" %
+			[ Thread.current, Thread.main ]
+		self.shutdown
+	end
+	alias_method :on_interrupt_signal, :on_termination_signal
+
+
+	### Handle a USR1 signal. Writes a message to the log by default.
+	def on_user1_signal( signo )
+		self.log.info "Checkpoint: User signal."
+	end
+
+end # class Mongrel2::Handler
+