iodine 0.0.1 → 0.0.2

data/lib/iodine/io.rb

@@ -2,19 +2,25 @@ module Iodine
 
 	public
 
-	# Gets the last time at which the IO Reactor was last active (last "tick").
+	# @return [Time] Gets the last time at which the IO Reactor was last active (last "tick").
 	def time
 		@time
 	end
-
-	# replaces an IO's protocol object.
+	# Replaces (or creates) an IO's protocol object.
+	#
+	# Accepts 2 arguments, in the following order:
 	#
-	# accepts:
 	# io:: the raw IO object.
-	# protocol:: a protocol instance - should be a Protocol or SSLProtocol (subclass) instance. type will NOT be checked - but Iodine could break if there is a type mismatch.
-	# 
+	# protocol:: a protocol instance - should be an instance of a class inheriting from {Iodine::Protocol}. type will NOT be checked - but Iodine could break if there is a type mismatch.
+	# @return [Protocol]
 	def switch_protocol *args
 		@io_in << args
+		args[1]
+	end
+
+	# @return [Array] Returns an Array with all the currently active connection's Protocol instances.
+	def to_a
+		@ios.values
 	end
 
 
@@ -22,14 +28,16 @@ module Iodine
 
 	@port = (ARGV.index('-p') && ARGV[ARGV.index('-p') + 1]) || ENV['PORT'] || 3000
 	@bind = (ARGV.index('-ip') && ARGV[ARGV.index('-ip') + 1]) || ENV['IP'] || "0.0.0.0"
+	@ssl = (ARGV.index('ssl') && true) || (@port == 443)
 	@protocol = nil
 	@ssl_context = nil
+	@ssl_protocols = {}
 	@time = Time.now
 
 	@timeout_proc = Proc.new {|prot| prot.timeout?(@time) }
 	@status_loop = Proc.new {|io|  @io_out << io if io.closed? || !(io.stat.readable? rescue false) }
 	@close_callback = Proc.new {|prot| prot.on_close if prot }
-	REACTOR = Proc.new do
+	REACTOR = [ (Proc.new do
 		if @queue.empty?
 			#clear any closed IO objects.
 			@time = Time.now
@@ -42,43 +50,41 @@ module Iodine
 			until @io_out.empty?
 				o_io = @io_out.pop
 				o_io.close unless o_io.closed?
-				queue @close_callback, @ios.delete(o_io)
+				run @ios.delete(o_io), &@close_callback
 			end
 			# react to IO events
 			begin
 				r = IO.select(@ios.keys, nil, nil, 0.15)
-				r[0].each {|io| queue @ios[io] } if r
+				r[0].each {|io| @queue << [@ios[io]] } if r
 			rescue => e
 				
 			end
 			unless @stop && @queue.empty?
 				# @ios.values.each &@timeout_loop
-				@check_timers && queue(@check_timers)
-				queue REACTOR
+				@check_timers && (@queue << @check_timers)
+				@queue << REACTOR
 			end
 		else
-			queue REACTOR
+			@queue << REACTOR
 		end
-	end
+	end )]
 	# internal helper methods and classes.
 	module Base
 		# the server listener Protocol.
 		class Listener < ::Iodine::Protocol
 			def on_open
 				@protocol = Iodine.protocol
+				@ssl = Iodine.ssl
 			end
 			def call
 				begin
 					n_io = nil
 					loop do
 						n_io = @io.accept_nonblock
-						@protocol.accept(n_io)
+						@protocol.accept(n_io, @ssl)
 					end
 				rescue Errno::EWOULDBLOCK => e
 
-				rescue OpenSSL::SSL::SSLError => e
-					warn "SSL Error - Self-signed Certificate?".freeze
-					n_io.close if n_io && !n_io.closed?
 				rescue => e
 					n_io.close if n_io && !n_io.closed?
 					@stop = true
@@ -92,19 +98,56 @@ module Iodine
 	## remember to set traps (once) when 'listen' is called.
 	run do
 		next unless @protocol
-
-		shut_down_proc = Proc.new {|protocol| protocol.on_shutdown ; protocol.close }
-		on_shutdown do
-			@logger << "Stopping to listen on port #{@port} and shutting down.\n"
-			@server.close unless @server.closed?
-			@ios.values.each {|p| queue shut_down_proc, p }
+		if @protocol.is_a?( ::Class ) && @protocol.ancestors.include?( ::Iodine::Protocol )
+			begin
+				@server = ::TCPServer.new(@bind, @port)
+			rescue => e
+				Iodine.fatal e.message
+				Iodine.fatal "Running existing tasks and exiting."
+				@stop = true
+				next
+			end
+			shut_down_proc = Proc.new {|protocol| protocol.on_shutdown ; protocol.close }
+			on_shutdown do
+				@logger << "Stopping to listen on port #{@port} and shutting down.\n"
+				@server.close unless @server.closed?
+				@ios.values.each {|p| run p, &shut_down_proc }
+			end
+			::Iodine::Base::Listener.accept(@server, false)
+			@logger << "Iodine #{VERSION} is listening on port #{@port}#{ ' to SSL/TLS connections.' if @ssl}\n"
+			if @spawn_count && @spawn_count.to_i > 1 && Process.respond_to?(:fork)
+				@logger << "Server will run using #{@spawn_count.to_i} processes - Spawning #{@spawn_count.to_i - 1 } more processes.\n"
+				(@spawn_count.to_i - 1).times do
+					Process.fork do
+						@logger << "Spawned process: #{Process.pid}.\n"
+						on_shutdown { @logger << "Shutting down process #{Process.pid}.\n" }
+						threads = []
+						@queue.clear
+						@queue << REACTOR
+						@thread_count.times { threads << Thread.new {  cycle } }
+						unless @stop
+							old_int_trap = trap('INT') { throw :stop; trap('INT', old_int_trap) if old_int_trap }
+							old_term_trap = trap('TERM') { throw :stop; trap('TERM', old_term_trap) if old_term_trap }
+							catch(:stop) { sleep }
+							@stop = true
+							# setup exit timeout.
+							threads.each {|t| Thread.new {sleep 25; t.kill; t.kill } }
+						end
+						threads.each {|t| t.join rescue true }
+					end
+				end
+				
+			end
+			@logger << "Press ^C to stop the server.\n"
+		else
+			@logger << "Iodine #{VERSION} is running.\n"
+			on_shutdown do
+				@logger << "Iodine says goodbye.\n"
+			end
+			@logger << "Press ^C to stop the cycling.\n"			
 		end
-		@server = ::TCPServer.new(@bind, @port)
-		::Iodine::Base::Listener.accept(@server)
-		@logger << "Iodine #{VERSION} is listening on port #{@port}\n"
 		old_int_trap = trap('INT') { throw :stop; trap('INT', old_int_trap) if old_int_trap }
 		old_term_trap = trap('TERM') { throw :stop; trap('TERM', old_term_trap) if old_term_trap }
-		@logger << "Press ^C to stop the server.\n"
-		queue REACTOR
+		@queue << REACTOR
 	end
 end

data/lib/iodine/protocol.rb

@@ -4,12 +4,12 @@ module Iodine
 	#
 	# A new protocol instance will be created for every network connection.
 	#
-	# The recommended use is to inherit this class (or {SSLProtocol}) and override any of the following:
+	# The recommended use is to inherit this class and override any of the following:
 	# on_open:: called whenever the Protocol is initialized. Override this to initialize the Protocol object.
 	# on_message(data):: called whenever data is received from the IO. Override this to implement the actual network protocol.
 	# on_close:: called AFTER the Protocol's IO is closed.
 	# on_shutdown:: called when the server's shutdown process had started and BEFORE the Protocol's IO is closed. It allows graceful shutdown for network protocols.
-	# ping::
+	# ping:: called when timeout was reached. see {#set_timeout}
 	#
 	# Once the network protocol class was created, remember to tell Iodine about it:
 	#       class MyProtocol << Iodine::Protocol
@@ -20,12 +20,14 @@ module Iodine
 	#
 	class Protocol
 
-		# returns the raw IO object. Using one of the Protocol methods {#write}, {#read}, {#close} is prefered over direct access.
+		# returns the IO object. If the connection uses SSL/TLS, this will return the SSLSocket (not a native IO object).
+		#
+		# Using one of the Protocol methods {#write}, {#read}, {#close} is prefered over direct access.
 		attr_reader :io
 
 		# Sets the timeout in seconds for IO activity (set timeout within {#on_open}).
 		#
-		# After timeout is reached, {#ping} will be closed. The connection will be closed if {#ping} returns `false` or `nil`.
+		# After timeout is reached, {#ping} will be called. The connection will be closed if {#ping} returns `false` or `nil`.
 		def set_timeout seconds
 			@timeout = seconds
 		end
@@ -46,11 +48,19 @@ module Iodine
 		def on_shutdown
 		end
 
-		# This method is called whenever a timeout has occurred. Either implement a ping or return `false` to disconnect.
-		#
-		# A `false` or `nil` return value will cause disconnection
+		# This method is called whenever a timeout has occurred. Either implement a ping or close the connection.
+		# The default implementation closes the connection.
 		def ping
-			false
+			close
+		end
+
+		#############
+		## functionality and helpers
+
+
+		# returns true id the protocol is using an encrypted connection (the IO is an OpenSSL::SSL::SSLSocket).
+		def ssl?
+			@io.is_a?(OpenSSL::SSL::SSLSocket) # io.npn_protocol
 		end
 
 
@@ -65,9 +75,15 @@ module Iodine
 		# reads from the IO up to the specified number of bytes (defaults to ~2Mb).
 		def read size = 2_097_152
 			touch
-			@io.recv_nonblock( size  )
-		rescue => e
+			ssl? ? read_ssl(size) : @io.recv_nonblock( size  )
+			# @io.read_nonblock( size  ) # this one is a bit slower...
+		rescue OpenSSL::SSL::SSLErrorWaitReadable, IO::WaitReadable, IO::WaitWritable
 			nil
+		rescue IOError, Errno::ECONNRESET
+			close
+		rescue => e
+			Iodine.warn "Protocol read error: #{e.class.name} #{e.message} (closing connection)"
+			close
 		end
 
 		# this method, writes data to the socket / io object.
@@ -79,36 +95,48 @@ module Iodine
 					r
 				end
 			rescue => e
-				# GReactor.warn e
 				close
 			end
 		end
 
+		# returns the connection's unique local ID as a Hex string.
+		#
+		# This can be used locally but not across processes.
+		def id
+			@id ||= @io.to_io.to_s(16)
+		end
 
-		# This method allows switiching the IO's protocol that will be used the NEXT time
-		# Iodine receives data using this protocol's IO.
+		# returns an [Enumerable](http://ruby-doc.org/core-2.2.3/Enumerable.html) with all the active connections.
 		#
-		# Switing protocols bypasses the {#on_close} method. Override this method for any cleanup needed (if at any),
-		# but remember to call `super` for the actual protocol switching implementation.
-		def switch_protocol new_protocol
-			Iodine.switch_protocol @io, new_protocol
+		# if a block is passed, than this method exceutes the block.
+		def self.each
+			if block_given?
+				Iodine.to_a.each {|p| yield(p) if p.is_a?(self) }
+			else
+				( Iodine.to_a.select {|p| p.is_a?(self) } ).each
+			end
 		end
 
+
 		#################
 		## the following are Iodine's "system" methods, used internally. Don't override.
 
 
 		# This method is used by Iodine to initialized the Protocol.
 		#
+		# A new Protocol instance set itself up as the IO's protocol (replacing any previous protocol).
+		#
 		# Normally you won't need to override this method. Override {#on_open} instead.
 		def initialize io
 			@timeout ||= nil
 			@send_locker = Mutex.new
 			@locker = Mutex.new
 			@io = io
-			switch_protocol self
 			touch
-			on_open
+			@locker.synchronize do
+				Iodine.switch_protocol @io.to_io, self
+				on_open
+			end
 		end
 
 		# Called by Iodine whenever there is data in the IO's read buffer.
@@ -132,24 +160,45 @@ module Iodine
 		#
 		# Normally you won't need to override this method. See {#ping}
 		def timeout? time
-			(ping || close) if @timeout && !@send_locker.locked? && ( (time - @last_active) > @timeout )
+			ping if @timeout && !@send_locker.locked? && ( (time - @last_active) > @timeout )
 		end
 
 
 
+
+		protected
 		# This method is used by Iodine to create the IO handler whenever a new connection is established.
 		#
 		# Normally you won't need to override this method.
-		def self.accept io
-			self.new(io)
+		def self.accept io, ssl
+			ssl ? SSLConnector.new(io, self) :  self.new(io)
 		end
-
-		protected
-
 		# This methos updates the timeout "watch", signifying the IO was active.
 		def touch
 			@last_active = Iodine.time
 		end
+
+		# reads from the IO up to the specified number of bytes (defaults to ~1Mb).
+		def read_ssl size
+			@send_locker.synchronize do
+				data = ''
+				begin
+					 (data << @io.read_nonblock(size).to_s) until data.bytesize >= size
+				rescue OpenSSL::SSL::SSLErrorWaitReadable, IO::WaitReadable, IO::WaitWritable
+
+				rescue IOError
+					close
+				rescue => e
+					Iodine.warn "SSL Protocol read error: #{e.class.name} #{e.message} (closing connection)"
+					close
+				end
+				return false if data.to_s.empty?
+				touch
+				data
+			end
+		end
+
+
 	end
 
 end

data/lib/iodine/settings.rb

@@ -14,6 +14,15 @@ module Iodine
 		@thread_count = count
 	end
 
+	# Sets the number of processes that should be spawned in Server mode. Defaults to 1 (no processes spawned).
+	#
+	# * Forking (spwaning processes) might NOT work on all systems (forking is supported by Ruby on Unix systems).
+	# * Please make sure your code is safe to fork into different processes. For instance, Websocket broadcasting and unicasting won't work across different processes unless synced using an external Pub/Sub service/database such as Redis.
+	# * Forking might cause some tasks (such as time based tasks) to be performed twice (once for each process). This is a feature. To avoid duplicated task performance, use a task (delayed execution) to initialize any tasks you want to perform only once. While the initial time based tasks and the server are shared across processes, the initial task stack will only run on the main process.
+	def processes= count
+		@spawn_count = count
+	end
+
 	# Sets the server port. Defaults to the runtime `-p` argument, or the ENV['PORT'] or 3000 (in this order).
 	def port= port
 		@port = port
@@ -23,7 +32,9 @@ module Iodine
 		@bind = address
 	end
 
-	# Sets the Protocol the Iodine Server will use. Should be a child of Protocol or SSLProtocol. Defaults to nil (no server).
+	# Sets the Protocol the Iodine Server will use. Should be a child of {Iodine::Protocol}. Defaults to nil (no server).
+	#
+	# If the protocol passed does NOT inherit from {Iodine::Protocol}, Iodine will cycle without initiating a server until stopped (TimedEvent mode).
 	def protocol= protocol
 		@stop = protocol ? false : true
 		@protocol = protocol
@@ -33,15 +44,45 @@ module Iodine
 		@protocol
 	end
 
-	# Sets the SSL Context to be used when using an SSLProtocol. Defaults to a self signed certificate.
+	# Sets the SSL flag, so that Iodine will require that new connection be encrypted.
+	def ssl= required
+		@ssl = required && true
+	end
+	# Returns true if Iodine will require that new connection be encrypted.
+	def ssl
+		@ssl
+	end
+
+	# Sets the SSL Context to be used when using an encrypted connection. Defaults to a self signed certificate and no verification.
+	#
+	# Manually setting the context will automatically set the SSL flag,
+	# so that Iodine will require encryption for new incoming connections.
 	def ssl_context= context
+		@ssl = true
 		@ssl_context = context
 	end
-	# Gets the SSL Context to be used when using an SSLProtocol.
+
+	# Gets the SSL Context to be used when using an encrypted connection.
 	def ssl_context
 		@ssl_context ||= init_ssl_context
 	end
 
+	# Sets the an SSL Protocol Hash (`'name' => Protocol`), allowing dynamic Protocol Negotiation.
+	# At the moment only NPN is supported. ALPN support should be established in a future release.
+	#
+	# * please notice that using allowing dynamic Protocol Negotiation could cause unexpected protocol choices when attempting to implement Opportunistic Encryption with {Iodine::SSLConnector}.
+	def ssl_protocols= protocol_hash
+		raise TypeError, "Iodine.ssl_protocols should be a Hash with Strings for keys (protocol identifiers) and Classes as values (Protocol classes)." unless protocol_hash.is_a?(Hash)
+		@ssl = true
+		ssl_context.npn_protocols = protocol_hash.keys
+		@ssl_protocols = protocol_hash
+	end
+
+	# Gets the SSL Protocol Hash used for 
+	def ssl_protocols
+		@ssl_protocols
+	end
+
 
 	protected
 

data/lib/iodine/ssl_connector.rb

@@ -0,0 +1,47 @@
+module Iodine
+
+	# This is a mini-protocol used only to implement the SSL Handshake in a non-blocking manner,
+	# allowing for a hardcoded timeout (which you can monkey patch) of 3 seconds.
+	class SSLConnector < Protocol
+		def initialize io, protocol
+			@protocol = protocol
+			super(io)		
+		end
+		TIMEOUT = 3 # hardcoded SSL/TLS handshake timeout
+		def on_open
+			timeout = TIMEOUT
+			@ssl_socket = ::OpenSSL::SSL::SSLSocket.new(@io, ::Iodine.ssl_context)
+			@ssl_socket.sync_close = true
+		end
+
+		# atempt an SSL Handshale
+		def call
+			return if @locker.locked?
+			return unless @locker.try_lock
+			begin
+				@ssl_socket.accept_nonblock
+			rescue ::IO::WaitReadable, ::IO::WaitWritable
+				return
+			rescue ::OpenSSL::SSL::SSLError
+				@e = ::OpenSSL::SSL::SSLError.new "Self-signed Certificate?".freeze
+				close
+				return
+			rescue => e
+				::Iodine.warn "SSL Handshake failed with: #{e.message}".freeze
+				@e = e
+				close
+				return
+			ensure
+				@locker.unlock
+			end
+			( (@ssl_socket.npn_protocol && ::Iodine.ssl_protocols[@ssl_socket.npn_protocol]) || @protocol).new @ssl_socket
+		end
+		def on_close
+			# inform
+			::Iodine.warn "SSL Handshake #{@e ? "failed with: #{@e.message} (#{@e.class.name})" : 'timed-out.'}".freeze
+			# the core @io is already closed, but let's make sure the SSL object is closed as well.
+			@ssl_socket.close unless @ssl_socket.closed?
+		end
+	end
+
+end