strelka 0.15.0 → 0.16.0

data/lib/strelka/websocketserver.rb

@@ -1,6 +1,8 @@
 # -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen-string-literal: true
+
+require 'set'
 
 require 'mongrel2/handler'
 require 'mongrel2/websocket'
@@ -27,15 +29,17 @@ require 'strelka/discovery'
 #       idle_timeout 15.0
 #
 #       # When a websocket is set up, add a new user to the table, but without a nick.
-#       on_handshake do |frame|
-#           @users[ frame.socket_id ] = nil
-#           return frame.response # accept the connection
+#       def handle_websocket_handshake( request )
+#           @users[ request.socket_id ] = nil
+#           return request.response # accept the connection
 #       end
 #
+#       plugin :routing
+#
 #       # Handle incoming commands, which should be text frames
-#       on_text do |frame|
-#           senderid = frame.socket_id
-#           data = frame.payload.read
+#       on_text do |request|
+#           senderid = request.socket_id
+#           data = request.payload.read
 #
 #           # If the input starts with '/', it's a command (e.g., /quit, /nick, etc.)
 #           output = nil
@@ -45,7 +49,7 @@ require 'strelka/discovery'
 #               output = self.say( senderid, data )
 #           end
 #
-#           response = frame.response
+#           response = request.response
 #           response.puts( output )
 #           return response
 #       end
@@ -62,15 +66,92 @@ class Strelka::WebSocketServer < Mongrel2::Handler
 	log_to :strelka
 
 
+	### Overridden from Mongrel2::Handler -- use the value returned from .default_appid if
+	### one is not specified.
+	def self::run( appid=nil )
+		appid ||= self.default_appid
+		self.log.info "Starting up with appid %p." % [ appid ]
+		super( appid )
+	end
+
+
+	### Calculate a default application ID for the class based on either its ID
+	### constant or its name and return it.
+	def self::default_appid
+		self.log.info "Looking up appid for %p" % [ self.class ]
+		appid = nil
+
+		if self.const_defined?( :ID )
+			appid = self.const_get( :ID )
+			self.log.info "  app has an ID: %p" % [ appid ]
+		else
+			appid = ( self.name || "anonymous#{self.object_id}" ).downcase
+			appid.gsub!( /[^[:alnum:]]+/, '-' )
+			self.log.info "  deriving one from the class name: %p" % [ appid ]
+		end
+
+		return appid
+	end
+
+
+	### Return an instance of the App configured for the handler in the currently-loaded
+	### Mongrel2 config that corresponds to the #default_appid.
+	def self::default_app_instance
+		appid = self.default_appid
+		return self.app_instance_for( appid )
+	end
+
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Dump the application stack when a new instance is created.
+	def initialize( * )
+		self.class.dump_application_stack
+
+		@connections = Hash.new {|h, k| h[k] = Set.new }
+		@connection_times = Hash.new {|h, k| h[k] = Hash.new }
+
+		super
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# A Hash of sender ID => Set of connection IDs.
+	attr_reader :connections
+
+	##
+	# A Hash of [sender ID, connection ID] keys => connection Times
+	attr_reader :connection_times
+
+
+
+	### Run the app -- overriden to set the process name to something interesting.
+	def run
+		procname = "%s %s: %p %s" % [ RUBY_ENGINE, RUBY_VERSION, self.class, self.conn ]
+		$0 = procname
+
+		super
+	end
+
+
 	### Handle a WebSocket frame in +request+. If not overridden, WebSocket connections are
 	### closed with a policy error status.
-	def handle_websocket( frame )
+	def handle_websocket( request )
 		response = nil
 
-		# Dispatch the frame
+		self.connection_times[ request.sender_id ][ request.conn_id ] = Time.now
+
+		# Dispatch the request
 		response = catch( :close_websocket ) do
-			self.log.debug "Incoming WEBSOCKET frame (%p):%s" % [ frame, frame.headers.path ]
-			self.handle_frame( frame )
+			self.log.debug "Incoming WEBSOCKET request (%p):%s" % [ request, request.headers.path ]
+			self.handle_websocket_request( request )
 		end
 
 		return response
@@ -78,8 +159,13 @@ class Strelka::WebSocketServer < Mongrel2::Handler
 
 
 	### Handle a WebSocket handshake HTTP +request+.
+	### :TODO: Register/check for supported Sec-WebSocket-Protocol.
 	def handle_websocket_handshake( handshake )
-		self.log.warn "Incoming WEBSOCKET_HANDSHAKE request (%p)" % [ request.headers.path ]
+		self.log.info "Incoming WEBSOCKET_HANDSHAKE request (%p)" % [ handshake.headers.path ]
+		self.connections[ handshake.sender_id ].add( handshake.conn_id )
+		self.connection_times[ handshake.sender_id ][ handshake.conn_id ] = Time.now
+		self.log.debug "  connections: %p" % [ self.connections ]
+
 		return handshake.response( handshake.protocols.first )
 	end
 
@@ -87,59 +173,87 @@ class Strelka::WebSocketServer < Mongrel2::Handler
 	### Handle a disconnect notice from Mongrel2 via the given +request+. Its return value
 	### is ignored.
 	def handle_disconnect( request )
-		self.log.info "Unhandled disconnect notice."
+		self.log.info "Connection %d closed." % [ request.conn_id ]
+		self.connection_times[ request.sender_id ].delete( request.conn_id )
+		self.connections.delete( request.sender_id )
+		self.log.debug "  connections remaining: %p" % [ self.connections ]
+
 		return nil
 	end
 
 
+	### Return the Time of the last frame from the client associated with the given
+	### +request+.
+	def last_connection_time( request )
+		table = self.connection_times[ request.sender_id ] or return nil
+		return table[ request.conn_id ]
+	end
+
+
+	### Send the specified +frame+ to all current connections, except those listed in
+	### +except+. The +except+ argument is a single [sender_id, conn_id] tuple.
+	def broadcast( frame, except: nil )
+		self.connections.each do |sender_id, conn_ids|
+			id_list = conn_ids.to_a.
+				reject {|cid| except&.first == sender_id && except&.last == cid }
+
+			self.log.debug "Broadcasting to %d connections for sender %s" %
+				[ conn_ids.length, sender_id ]
+
+			self.conn.broadcast( sender_id, id_list, frame.to_s )
+		end
+	end
+
+
 	#########
 	protected
 	#########
 
-	### Default frame handler.
-	def handle_frame( frame )
-		if frame.control?
-			self.handle_control_frame( frame )
+	### Default request handler.
+	def handle_websocket_request( request )
+		if request.control?
+			self.handle_control_request( request )
 		else
-			self.handle_content_frame( frame )
+			self.handle_content_request( request )
 		end
 	end
 
 
-	### Throw a :close_websocket frame that will close the current connection.
-	def close_with( frame, reason )
+	### Throw a response with a 'close' frame that will close the current
+	### connection.
+	def close_with( request, reason )
 		self.log.debug "Closing the connection: %p" % [ reason ]
 
-		# Make a CLOSE frame
-		frame = frame.response( :close )
-		frame.set_status( reason )
+		# Make a CLOSE response
+		response = request.response( :close )
+		response.set_status( reason )
 
-		throw :close_websocket, frame
+		throw :close_websocket, response
 	end
 
 
-	### Handle an incoming control frame.
-	def handle_control_frame( frame )
-		self.log.debug "Handling control frame: %p" % [ frame ]
+	### Handle an incoming request with a control frame.
+	def handle_control_request( request )
+		self.log.debug "Handling control request: %p" % [ request ]
 
-		case frame.opcode
+		case request.opcode
 		when :ping
-			return frame.response
+			return request.response
 		when :pong
 			return nil
 		when :close
-			self.conn.reply_close( frame )
+			self.conn.reply_close( request )
 			return nil
 		else
-			self.close_with( frame, CLOSE_BAD_DATA_TYPE )
+			self.close_with( request, CLOSE_BAD_DATA_TYPE )
 		end
 	end
 
 
-	### Handle an incoming content frame.
-	def handle_content_frame( frame )
-		self.log.warn "Unhandled frame type %p" % [ frame.opcode ]
-		self.close_with( frame, CLOSE_BAD_DATA_TYPE )
+	### Handle an incoming request with a content frame.
+	def handle_content_request( request )
+		self.log.warn "Unhandled request type %p" % [ request.opcode ]
+		self.close_with( request, CLOSE_BAD_DATA_TYPE )
 	end
 
 

data/lib/strelka/websocketserver/heartbeat.rb

@@ -0,0 +1,163 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# frozen-string-literal: true
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/websocketserver' unless defined?( Strelka::WebSocketServer )
+require 'strelka/plugin' unless defined?( Strelka::Plugin )
+
+# Heartbeat logic for Strelka WebSocketServers.
+#
+# To ping connected clients, and disconnect them after 3 failed pings:
+#
+#    class ChatServer < Strelka::WebSocketServer
+#        plugin :heartbeat
+#
+#        heartbeat_rate 5.0
+#        idle_timeout 15.0
+#    end
+#
+module Strelka::WebSocketServer::Heartbeat
+	extend Loggability,
+	       Strelka::Plugin
+	include Strelka::Constants,
+	        Mongrel2::WebSocket::Constants
+
+
+	# The default number of seconds between heartbeat events
+	DEFAULT_HEARTBEAT_RATE = 5.0
+
+	# The default number of seconds between events before a client is disconnected
+	DEFAULT_IDLE_TIMEOUT = 15.0
+
+
+	# Loggability API -- set up logging under the 'strelka' log host
+	log_to :strelka
+
+	# Plugins API -- set up load order
+	run_outside :routing
+
+
+	# Class methods to add to servers with a heartbeat.
+	module ClassMethods # :nodoc:
+
+		@heartbeat_rate = DEFAULT_HEARTBEAT_RATE
+		@idle_timeout = DEFAULT_IDLE_TIMEOUT
+
+
+		### Get/set the number of seconds between heartbeat events.
+		def heartbeat_rate( new_rate=nil )
+			@heartbeat_rate = new_rate.to_f if new_rate
+			return @heartbeat_rate
+		end
+
+
+		### Get/set the number of seconds between events before a client is disconnected
+		def idle_timeout( new_timeout=nil )
+			@idle_timeout = new_timeout if new_timeout
+			return @idle_timeout
+		end
+
+
+		### Inheritance hook -- inheriting classes inherit their parents' routes table.
+		def inherited( subclass )
+			super
+			subclass.instance_variable_set( :@idle_timeout, self.idle_timeout.dup )
+			subclass.instance_variable_set( :@heartbeat_rate, self.heartbeat_rate.dup )
+		end
+
+	end # module ClassMethods
+
+
+	######
+	public
+	######
+
+	### Called by Mongrel2::Handler when it starts accepting requests. Overridden
+	### to start up the heartbeat thread.
+	def start_accepting_requests
+		self.start_heartbeat
+		super
+	end
+
+
+	### Called by Mongrel2::Handler when the server is restarted. Overridden to
+	### restart the heartbeat thread.
+	def restart
+		self.stop_heartbeat
+		super
+		self.start_heartbeat
+	end
+
+
+	### Called by Mongrel2::Handler when the server is shut down. Overridden to
+	### stop the heartbeat thread.
+	def shutdown
+		self.stop_heartbeat
+		super
+	end
+
+
+	### Start a thread that will periodically ping connected sockets and remove any
+	### connections that don't reply
+	def start_heartbeat
+		self.log.info "Starting heartbeat timer."
+		@heartbeat_timer = self.reactor.add_periodic_timer( self.class.heartbeat_rate ) do
+			self.cull_idle_sockets
+			self.ping_all_sockets
+		end
+	end
+
+
+	### Tell the heartbeat thread to exit.
+	def stop_heartbeat
+		self.reactor.remove_timer( @heartbeat_timer )
+	end
+
+
+	### Disconnect any sockets that haven't sent any frames for at least
+	### SOCKET_IDLE_TIMEOUT seconds.
+	def cull_idle_sockets
+		self.log.debug "Culling idle sockets."
+
+		earliest = Time.now - self.class.idle_timeout
+
+		self.connection_times.each do |sender_id, times|
+			times.each do |conn_id, lastframe|
+				next unless earliest > lastframe
+
+				self.log.warn "Timing out connection %s:%d: last seen %0.3fs ago." %
+					[ sender_id, conn_id, Time.now - lastframe ]
+
+				# Make a CLOSE frame
+				frame = Mongrel2::WebSocket::Frame.close
+				frame.set_status( CLOSE_EXCEPTION )
+
+				# Use the connection directly so we can send a frame and close the
+				# connection
+				self.conn.send( sender_id, conn_id, frame.to_s )
+				self.conn.send_close( sender_id, conn_id )
+			end
+		end
+	end
+
+
+	### Send a PING frame to all connected sockets.
+	def ping_all_sockets
+		return if self.connections.empty?
+
+		self.log.debug "Pinging %d connected sockets." % [ self.connections.length ]
+		self.connections.each do |sender_id, conn_ids|
+			frame = Mongrel2::WebSocket::Frame.new( sender_id, conn_id, '', {}, 'heartbeat' )
+			frame.opcode = :ping
+			frame.fin = true
+
+			self.log.debug "  %s/%d: PING" % [ sender_id, conn_id ]
+			self.conn.reply( frame )
+		end
+
+		self.log.debug "  done with pings."
+	end
+
+end # module Strelka::WebSocketServer::Heartbeat
+

data/lib/strelka/websocketserver/routing.rb

@@ -1,6 +1,6 @@
 # -*- ruby -*-
 # vim: set nosta noet ts=4 sw=4:
-# encoding: utf-8
+# frozen-string-literal: true
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/websocketserver' unless defined?( Strelka::WebSocketServer )
@@ -10,20 +10,36 @@ require 'strelka/plugin' unless defined?( Strelka::Plugin )
 #
 # For a protocol that defines its own opcodes:
 #
-#    class ChatServer
+#    class ChatServer < Strelka::WebSocketServer
 #        plugin :routing
 #
+#        on_handshake do |request|
+#            # ...
+#        end
+#        on_text do |request|
+#            # ...
+#        end
+#    end
+#
+#    class CustomChatServer < Strelka::WebSocketServer
+#        plugin :routing
 #        opcodes :nick => 7,
 #                :emote => 8
 #
-#        on_text do |frame|
-#            # ...
+#        on_nick do |request|
+#            nick = request.payload.read
+#            self.set_nick( request.socket_id, nick )
+#            return request.response( "Okay, nick set to #{nick}.", :text )
 #        end
 #
-#        on_nick do |frame|
-#            self.set_nick( frame.socket_id, frame.payload.read )
+#        on_emote do |request|
+#            emote = request.payload.read
+#            nick = self.nick_for( request.socket_id )
+#            msg = "%s %s" % [ nick, emote ]
+#            self.broadcast( msg )
+#            return nil
 #        end
-#
+#    end
 #
 module Strelka::WebSocketServer::Routing
 	extend Loggability,
@@ -42,40 +58,51 @@ module Strelka::WebSocketServer::Routing
 	# Class methods to add to classes with routing.
 	module ClassMethods # :nodoc:
 
+		##
 		# The list of routes to pass to the Router when the application is created
 		attr_reader :op_callbacks
 		@op_callbacks = {}
 
-		# The Hash of opcodes that can be hooked
+		##
+		# The Hash of opcode names to numeric opcodes
 		attr_reader :opcode_map
 		@opcode_map = {}
 
+		##
+		# The Hash of numeric opcodes to opcode names
+		attr_reader :opcode_names
+		@opcode_names = {}
+
 
 		### Declare one or more opcodes in the form:
 		###
 		### {
-		###     <bit> => <label>,
+		###     <label> => <bit>,
 		### }
 		def opcodes( hash )
 			@opcode_map ||= {}
 			@opcode_map.merge!( hash )
-			@opcode_map.each do |bit, label|
+
+			@opcode_names = @opcode_map.invert
+
+			@opcode_map.each do |label, bit|
 				self.log.debug "Set opcode %p to %#0x" % [ label, bit ]
 				declarative = "on_#{label}"
 				block = self.make_declarative( label )
 				self.log.debug "  declaring method %p on %p" % [ declarative, self ]
-				self.class.send( :define_method, declarative, &block )
+				self.class.remove_method( declarative ) if self.class.method_defined?( declarative )
+				self.class.define_method( declarative, &block )
 			end
 		end
 
 
-		### Make a declarative method for setting the callback for frames with the specified
-		### +opcode+ (Symbol).
+		### Make a declarative method for setting the callback for requests with frames
+		### with the specified +opcode+ (Symbol).
 		def make_declarative( opcode )
 			self.log.debug "Making a declarative for %p" % [ opcode ]
 			return lambda do |&block|
 				self.log.debug "Setting handler for %p frames to %p" % [ opcode, block ]
-				methodname = "on_#{opcode}_frame"
+				methodname = "on_#{opcode}_request"
 				define_method( methodname, &block )
 				self.op_callbacks[ opcode ] = self.instance_method( methodname )
 			end
@@ -94,7 +121,7 @@ module Strelka::WebSocketServer::Routing
 		### is registered.
 		def self::extended( mod )
 			super
-			mod.opcodes( Mongrel2::WebSocket::Constants::OPCODE_NAME )
+			mod.opcodes( Mongrel2::WebSocket::Constants::OPCODE )
 		end
 
 	end # module ClassMethods
@@ -102,14 +129,14 @@ module Strelka::WebSocketServer::Routing
 
 
 	### Dispatch the incoming frame to its handler based on its opcode
-	def handle_frame( frame )
+	def handle_websocket_request( request )
 		self.log.debug "[:routing] Opcode map is: %p" % [ self.class.opcode_map ]
-		opname = self.class.opcode_map[ frame.numeric_opcode ]
-		self.log.debug "[:routing] Routing frame: %p" % [ opname ]
+		opname = self.class.opcode_names[ request.numeric_opcode ]
+		self.log.debug "[:routing] Routing request: %p" % [ opname ]
 
 		handler = self.class.op_callbacks[ opname ] or return super
 
-		return handler.bind( self ).call( frame )
+		return handler.bind( self ).call( request )
 	end
 
 end # module Strelka::WebSocketServer::Routing