iodine 0.1.21 → 0.2.0

data/lib/iodine.rb

@@ -1,71 +1,70 @@
-require 'logger'
 require 'socket'
-require 'openssl'
 
-require "iodine/version"
-require "iodine/settings"
-require "iodine/logging"
-require "iodine/core"
-require "iodine/timers"
-require "iodine/protocol"
-require "iodine/ssl_connector"
-require "iodine/io"
-require "iodine/core_init"
+require 'iodine/version'
+require 'iodine/iodine'
 
-
-
-# Iodine is an easy Object-Oriented library for writing network applications (servers) with your own
-# network protocol.
-#
-# Please read the {file:README.md} file for an introduction to Iodine.
+# Iodine is both a Rack server and a platform for writing evented network services on Ruby.
 #
-# Here's a quick and easy echo server,
-# notice how Iodine will automatically start running once you finish setting everything up:
+# Here is a sample Echo server using Iodine:
 #
-#       require 'iodine'
 #
-#       class MyProtocol < Iodine::Protocol
-#          # Iodine will call this whenever a new connection is opened.
-#          def on_open
-#             # Iodine includes logging as well as unique assigned instance ID's.
-#             Iodine.info "New connection id: #{id}"
-#             # Iodine includes timeout support with automatic pinging or connection termination.
-#             set_timeout 5
-#          end
-#          def on_message data
-#             write("-- Closing connection, goodbye.\n") && close if data =~ /^(bye|close|exit)/i
-#             write(">> #{data.chomp}\n")
-#          end
-#          # Iodine will call this whenever a new connection is closed.
-#          def on_close
-#             Iodine.info "Closing connection id: #{id}"
-#          end
-#          # Iodine will call this whenever a a timeout is reached.
-#          def ping
-#             # If `write` fails, it automatically closes the connection.
-#             write("-- Are you still there?\n")
-#          end
+#       # define the protocol for our service
+#       class EchoProtocol
+#         @timeout = 10
+#         # this is just one possible callback with a recyclable buffer
+#         def on_message buffer
+#           # write the data we received
+#           write "echo: #{buffer}"
+#           # close the connection when the time comes
+#           close if buffer =~ /^bye[\n\r]/
+#         end
 #       end
+#       # create the service instance
+#       Iodine.listen 3000, EchoProtocol
+#       # start the service
+#       Iodine.start
 #
-#       # setting up the server is as easy as plugging in your Protocol class:
-#       Iodine.protocol = MyProtocol
-#
-#       # setting up cuncurrency can be done with threads - the default is a single thread):
-#       Iodine.threads = 8
-#
-#       # setting up cuncurrency can also be done with processes (forking) - the default is a single process:
-#       Iodine.processes = 4
-#       
-#       # if you are excecuting this script from IRB, exit IRB to start Iodine.
-#       exit
-#
-# You can test the example using `telnet`
 #
-# Before you write your own protocol, make sure you learn more about the {Iodine::Protocol} and all it's got to offer.
+# Please read the {file:README.md} file for an introduction to Iodine and an overview of it's API.
 module Iodine
-  extend self
-end
+  @threads = (ARGV.index('-t') && ARGV[ARGV.index('-t') + 1]) || ENV['MAX_THREADS']
+  @processes = (ARGV.index('-w') && ARGV[ARGV.index('-w') + 1]) || ENV['MAX_WORKERS']
+  @threads = @threads.to_i if @threads
+  @processes = @processes.to_i if @processes
+
+  # Get/Set the number of threads used in the thread pool (a static thread pool). Can be 1 (single working thread, the main thread will sleep) and can be 0 (the main thread will be used as the only active thread).
+  def self.threads
+    @threads
+  end
+
+  # Get/Set the number of threads used in the thread pool (a static thread pool). Can be 1 (single working thread, the main thread will sleep) and can be 0 (the main thread will be used as the only active thread).
+  def self.threads=(count)
+    @threads = count.to_i
+  end
 
+  # Get/Set the number of worker processes. A value greater then 1 will cause the Iodine to "fork" any extra worker processes needed.
+  def self.processes
+    @processes
+  end
 
+  # Get/Set the number of worker processes. A value greater then 1 will cause the Iodine to "fork" any extra worker processes needed.
+  def self.processes=(count)
+    @processes = count.to_i
+  end
+
+  # Runs the warmup sequence. {warmup} attempts to get every "autoloaded" (lazy loaded)
+  # file to load now instead of waiting for "first access". This allows multi-threaded safety and better memory utilization during forking.
+  #
+  # Use {warmup} when either {processes} or {threads} are set to more then 1.
+  def self.warmup
+    # load anything marked with `autoload`, since autoload isn't thread safe nor fork friendly.
+    Module.constants.each do |n|
+      begin
+        Object.const_get(n)
+      rescue Exception => _e
+      end
+    end
+  end
+end
 
-# require 'iodine/http'
+require 'rack/handler/iodine' unless defined? ::Iodine::Rack::IODINE_RACK_LOADED

data/lib/iodine/http.rb

@@ -1,193 +1,4 @@
 require 'iodine'
-require 'stringio'
-require 'time'
-require 'json'
-require 'yaml'
-require 'uri'
-require 'tmpdir'
-require 'zlib'
-require 'securerandom'
-require 'tempfile.rb'
-
-require 'iodine/http/request'
-require 'iodine/http/response'
-require 'iodine/http/session'
-
-require 'iodine/http/http1'
-
-require 'iodine/http/hpack'
-require 'iodine/http/http2'
-
-require 'iodine/http/websockets'
-require 'iodine/http/websocket_handler'
-require 'iodine/http/websocket_client'
-
-require 'iodine/http/rack_support'
-
 
 module Iodine
-
-	# The {Iodine::Http} class allows the creation of Http and Websocket servers using Iodine.
-	#
-	# To start an Http server, simply require `iodine/http` (which isn't required by default) and set up
-	# your Http callback. i.e.:
-	#
-	#       require 'iodine/http'
-	#       Iodine::Http.on_http { |request, response| 'Hello World!' }
-	#       exit # only if running from irb
-	#
-	# To start a Websocket server, require `iodine/http` (which isn't required by default), create a Websocket handling Class and set up
-	# your Websocket callback. i.e.:
-	#
-	#       require 'iodine/http'
-	#       class WSChatServer
-	#          def initialize nickname, response
-	#              @nickname = nickname || "unknown"
-	#              @response = response
-	#              # @response.io # => Http Protocol
-	#          end
-	#          def on_open
-	#              # only now is the response.io pointing at the Websocket Protocol
-	#              @io = @response.io
-	#              @io.broadcast "#{@nickname} has joined the chat!"
-	#              @io << "Welcome #{@nickname}, you have joined the chat!"
-	#          end
-	#          def on_message data
-	#              @io.broadcast "#{@nickname} >> #{data}"
-	#              @io << ">> #{data}"
-	#          end
-	#          def on_broadcast data
-	#              # the http response can also be used to send websocket data.
-	#              @response << data
-	#          end
-	#          def on_close
-	#              @io.broadcast "#{@nickname} has left the chat!"
-	#          end
-	#       end
-	#
-	#       Iodine::Http.on_websocket { |request, response| WSChatServer.new request.params[:name], response}
-	#
-	# See {Iodine::Http::WebsocketHandler} for a good starting point or inherit {Iodine::Http::WebsocketHandler} in your handler.
-	#
-	module Http
-		public
-		# Sets or gets the Http callback.
-		#
-		# An Http callback is a Proc like object that answers to `call(request, response)` and returns either:
-		# `true`:: the response has been set by the callback and can be managed (including any streaming) by the server.
-		# `false`:: the request shouldn't be answered or resource not found (error 404 will be sent as a response).
-		# String:: the String will be appended to the response and the response sent.
-		def on_http handler = nil, &block
-			@http_app = handler || block if handler || block
-			@http_app
-		end
-		# Sets or gets the Websockets callback.
-		#
-		# A Websockets callback is a Proc like object that answers to `call(request)` and returns either:
-		# `false`:: the request shouldn't be answered or resource not found (error 404 will be sent as a response).
-		# Websocket Handler:: a Websocket handler is an object that is expected to answer `on_message(data)` and `on_close`. See {} for more data.
-		def on_websocket handler = nil, &block
-			@websocket_app = handler || block if handler || block
-			@websocket_app
-		end
-
-		# Sets the session token for the Http server (String). Defaults to the name of the script + '_id'.
-		def session_token= token
-			@session_token = token
-		end
-		# Gets the session token for the Http server (String). Defaults to the name of the script.
-		def session_token
-			@session_token
-		end
-
-		# `max_http_buffer` is deprecated. Use `max_body_size` instead.
-		def max_http_buffer= size
-			Iodine.warn "`max_http_buffer` is deprecated. Use `max_body_size` instead."
-			max_body_size = size
-		end
-		# `max_http_buffer` is deprecated. Use `max_body_size` instead.
-		def max_http_buffer
-			Iodine.warn "`max_http_buffer` is deprecated. Use `max_body_size` instead."
-			@max_body_size
-		end
-		# Sets the maximum bytes allowed for an HTTP's body request (file upload data). Defaults to the command line `-limit` argument, or ~0.5GB.
-		def max_body_size= size
-			@max_body_size = size
-		end
-		# Gets the maximum bytes allowed for an HTTP's body request (file upload data). Defaults to the command line `-limit` argument, or ~0.5GB.
-		def max_body_size
-			@max_body_size
-		end
-
-		# Sets whether Iodine will allow connections to the experiemntal Http2 protocol. Defaults to false unless the `http2` command line flag is present.
-		def http2= allow
-			@http2 = allow && true
-		end
-		# Returns true if Iodine will require that new connection be encrypted.
-		def http2
-			@http2
-		end
-
-		# # Sets whether Iodine will allow connections to the experiemntal Http2 protocol. Defaults to false unless the `http2` command line flag is present.
-		# def self.message_buffer_size= size
-		# 	@message_buffer_size = size
-		# end
-		# # Returns true if Iodine will require that new connection be encrypted.
-		# def self.message_buffer_size
-		# 	@message_buffer_size
-		# end
-
-		# Creates a websocket client within a new task (non-blocking).
-		# 
-		# Make sure to setup all the callbacks (as needed) prior to starting the connection. See {::Iodine::Http::WebsocketClient.connect}
-		#
-		# i.e.:
-		#
-		#       require 'iodine/http'
-		#       # don't start the server
-		#       Iodine.protocol = :timer
-		#       options = {}
-		#       options[:on_open] = Proc.new { write "Hello there!"}
-		#       options[:on_message] = Proc.new do |data|
-		#           puts ">> #{data}";
-		#           write "Bye!";
-		#           # It's possible to update the callback midstream.
-		#           on_message {|data| puts "-- Goodbye message: #{data}"; close;}
-		#       end
-		#       # After closing we will call `Iodine.signal_exit` to signal Iodine to finish up.
-		#       options[:on_close] = Proc.new { puts "disconnected"; Iodine.signal_exit }
-		#       
-		#       Iodine::Http.ws_connect "ws://echo.websocket.org", options
-		#
-		#       #if running from irb:
-		#       exit
-		#     
-		def ws_connect url, options={}, &block
-			::Iodine.run { ::Iodine::Http::WebsocketClient.connect url, options, &block }
-		end
-
-		protected
-
-		@http2 = (ARGV.index('http2') && true)
-		@max_body_size = ((ARGV.index('-limit') && ARGV[ARGV.index('-limit') + 1]) || 536_870_912).to_i
-
-		@websocket_app = @http_app = NOT_IMPLEMENTED = Proc.new { |i,o| false }
-		@session_token = "#{File.basename($0, '.*')}_uuid"
-		extend self
-	end
-
-	@queue.tap do |q|
-		arr =[];
-		arr << q.pop until q.empty?;
-		run { ::Iodine.ssl_protocols = { 'h2' => ::Iodine::Http::Http2, 'http/1.1' => ::Iodine::Http::Http1 } if @ssl && @ssl_protocols.empty? && ::Iodine::Http.http2 }
-		run do
-			if Iodine.protocol == ::Iodine::Http::Http1 && ::Iodine::Http.on_http == ::Iodine::Http::NOT_IMPLEMENTED && ::Iodine::Http.on_websocket == ::Iodine::Http::NOT_IMPLEMENTED
-				::Iodine.protocol = :http_not_initialized
-				q << arr.shift until arr.empty?
-				run { Process.kill("INT", 0) }
-			end
-		end
-		q << arr.shift until arr.empty?
-	end
 end
-Iodine.protocol = ::Iodine::Http::Http1 unless Iodine.protocol

data/lib/iodine/protocol.rb

@@ -1,247 +1,38 @@
 module Iodine
-
-	# This is the Basic Iodine server unit - a network protocol.
-	#
-	# A new protocol instance will be created for every network connection.
-	#
-	# A new protocol might be initialized also when switching between protocols. In this use-case, the
-	# protocol can be initialized with an optional second `options` parameter (the first parameter MUST be the IO object used),
-	# allowing this data to be accessed within the {#on_open} method using the `@options` instance variable or the `options` accessor.
-	#
-	# For example, when switching protocols midstream (i.e. for implementing an Http Upgrade to another protocol such as Websockets):
-	# 
-	#      class MyNextProtocol
-	#         def on_open
-	#            @secret = options[:secret]
-	#         end
-	#      end
-	#
-	#      # in the old protocol:
-	#
-	#      class MyOriginalProtocol
-	#         def switch_to_next_protocol
-	#            MyNextProtocol.new @io, secret: "my secret data"
-	#         end
-	#      end
-	#
-	# 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:: 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
-	#           # your code here
-	#       end
-	#       # tell Iodine
-	#       Iodine.protocol = MyProtocol
-	#
-	class Protocol
-
-		# 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
-		# the argument or options Hash passed to the initializer as a second argument (the first argument MUST be the IO object).
-		# the value is usually `nil` unless the protocol instance was created by a different protocol while "upgrading" from one protocol to the next.
-		attr_reader :options
-		# The protocol's Mutex locker. It should be locked whenever your code is runing, unless you are
-		# writing asynchronous code.
-		#
-		# Use with care (or, better yet, don't use).
-		attr_reader :locker
-
-		# Sets the timeout in seconds for IO activity (set timeout within {#on_open}).
-		#
-		# 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
-
-		# This method is called whenever the Protocol is initialized - i.e.:
-		# a new connection is established or an old connection switches to this protocol.
-		def on_open
-		end
-		# This method is called whenever data is received from the IO.
-		#
-		# The `data` received is a reference to the socket's buffer and it will be cleared and replaced whenever `read`
-		# is called or when new IO data comes in (after `on_message` had completed). To presist
-		# the data, make sure to duplicate the data String using `data.dup`.
-		def on_message data
-		end
-
-		# This method is called AFTER the Protocol's IO is closed - it will only be called once.
-		def on_close
-		end
-
-		# This method is called when the server's shutdown process had started and BEFORE the Protocol's IO is closed. It allows graceful shutdown for network protocols.
-		def on_shutdown
-		end
-
-		# This method is called whenever a timeout has occurred. Either implement a ping or close the connection.
-		# The default implementation closes the connection unless the protocol is still processing information received before timeout occurred.
-		def ping
-			close unless @locker.locked?
-		end
-
-		#############
-		## functionality and helpers
-
-
-		# returns true if 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
-
-
-		# Closes the IO object.
-		# @return [nil]
-		def close
-			@io.close unless @io.closed?
-			nil
-		end
-		alias :disconnect :close
-		def closed?
-			@io.closed?
-		end
-
-		# reads from the IO up to the specified number of bytes (defaults to ~2Mb).
-		def read size = 2_097_152
-			touch
-			ssl? ? read_ssl(size) : @io.read_nonblock( size , Thread.current[:buffer] )
-			# @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.
-		def write data
-			begin
-				@send_locker.synchronize do
-					r = @io.write data
-					touch
-					r
-				end
-			rescue # => e
-				# Iodine.info e.message
-				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.object_id.to_s(16)
-		end
-
-		# @return [Enumerable] returns an Enumerable with all the active connections (instances of THIS Protocol or it's children).
-		#
-		# 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, options = nil
-			@timeout ||= nil
-			@send_locker = Mutex.new
-			@ping_locker = Mutex.new
-			@locker = Mutex.new
-			@io = io
-			@options = options
-			touch
-			@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.
-		#
-		# Normally you won't need to override this method. Override {#on_message} instead.
-		def call
-			return unless @locker.try_lock
-			begin
-				data = read
-				if data
-					on_message(data)
-					# data.clear
-				end
-			ensure
-				@locker.unlock
-			end
-		end
-
-
-		# This method is used by Iodine invoke a timeout review.
-		#
-		# Normally you won't need to override this method. See {#ping}
-		def timeout? time
-			return unless @ping_locker.try_lock
-			begin
-				touch && ping if @timeout && !@send_locker.locked? && ( (time - @last_active) > @timeout )
-			ensure
-				@ping_locker.unlock	
-			end
-		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, ssl
-			ssl ? SSLConnector.new(io, self) :  self.new(io)
-		rescue
-			io.close unless io.closed?
-			raise
-		end
-		# 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 = String.new
-				begin
-					 (data << @io.read_nonblock(size, Thread.current[:buffer]).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
-
+  # The Protocol class is used only for documenting the Protocol API, it will not be included when requiring `iodine`.
+  #
+  # A dynamic (stateful) protocol is defined as a Ruby class instance which is in control of one single connection.
+  #
+  # It is called dynamic because it is dynamically allocated for each connection and then discarded,
+  # also it sounded better then calling it "the stateful protocol", even though that's what it actually is.
+  #
+  # It is (mostly) thread-safe as long as it's operations are limited to the scope
+  # of the object.
+  #
+  # <b>The Callbacks</b>
+  #
+  # A protocol class <b>MUST</b> contain ONE of the following callbacks:
+  #
+  # on_data:: called whened there's data available to be read, but no data was read just yet. `on_data` will not be called again untill all the existing network buffer was read (edge triggered event).
+  # on_message(buffer):: the default `on_data` implementation creates a 1Kb buffer and reads data while recycling the same String memory space. The buffer is forwarded to the `on_message` callback before being recycled. The buffer object will be over-written once `on_message` returns, so creating a persistent copy requires `buffer.dup`.
+  #
+  # A protocol class <b>MAY</b> contain any of the following optional callbacks:
+  #
+  # on_open:: called after a new connection was accepted and the protocol was linked with Iodine's Protocol API. Initialization should be performed here.
+  # ping:: called whenever timeout was reached. The default implementation will close the connection unless a protocol task ({Protocol#defer}, `on_data` or `on_message`) are busy in the background.
+  # on_shutdown:: called if the connection is still open while the server is shutting down. This allows the protocol to send a "going away" frame before the connection is closed and `on_close` is called.
+  # on_close:: called after a connection was closed, for any cleanup (if any).
+  #
+  # WARNING: for thread safety and connection management, `on_open`, `on_shutdown`, `on_close` and `ping` will all be performed within the reactor's main thread.
+  # Do not run long running tasks within these callbacks, or the server might block while you do.
+  # Use {#defer} to run protocol related tasks (this locks the connection, preventing it from running more then one task at a time and offering thread safety),
+  # or {#run} to run asynchronous tasks that aren't protocol related.
+  #
+  # <b>The API:</b>
+  #
+  # After a new connection is accepted and a new protocol object is created, the protocol will be linked with Iodine's Protocol API.
+  # Only the main protocol will be able to access the API within `initialize`, so it's best to use `on_open` for any Initialization required.
+  #
+  module Protocol
+  end
 end