rxio 0.11.4 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58ba254c8b92e99fce1f72e3e98f490f112ffbba
-  data.tar.gz: 64794413e4927e4b7380d5f87d20b7e3dbfe72fa
+  metadata.gz: a192fa9381b7872090a16feb90e28fe3fe6c1994
+  data.tar.gz: 582612082630571b7ef3bd855620bedddd488e17
 SHA512:
-  metadata.gz: 3539209f39086919b411bf01ef6c5cb5acb8cf07afacdcc4e771509a996bd5421fafaf941ea3a07557f735a32d498132b4f05113d06338304963612ebc4b4703
-  data.tar.gz: 5906ac469b314c200ff95810c75073bf74be8c194e9acbd49ebd3270d62283301ddcc4d4ba612191a9c29ea90ab8e16ca749c20478a63779feb82733e1d2d1a4
+  metadata.gz: 934b55278bcd8237d83d79c94374b2cb4e0ecc01eb6321a91388e22fb73fecbb94db2abd122ad2b743cc9986dd85c5a6c25b5af23d1875c6c6a388b93a4294b4
+  data.tar.gz: 16939703ed1cc130e9f5b5be682a951890c67c12f1f3952d7f98ab0f698e80d3a45a75045b4390fe2c4360b5ac4a133d9fc7579ab3cc4ff10d5dc3e41ffa132e

data/README.md

@@ -23,26 +23,27 @@ gem install -V rxio
 
 A simple service is created by spawning an instance of the *RxIO::Service* class, passing a *Handler Module* as argument to its constructor and calling its _run_ method.
 
-This will execute the service's main loop. The handler module provides the specific protocol implementation through a set of methods.
+A simple client is created by spawning an instance of the *RxIO::Client* class, passing a *Handler Module* as argument to its constructor and calling its _run_ method.
 
-The _run_ method is blocking and will only return after the service has terminated.
+This will execute the service / client main loop. The handler module provides the specific protocol implementation through a set of methods.
 
-A _stop_ method is also provided to request the service to terminate.
+The _run_ method on both *Service* & *Client* is blocking and will only return after the main loop has terminated.
+A _stop_ method is also provided to request the main loop to terminate.
 
 ### Running in the background
 
-While the _run_ / _stop_ methods offer a simple way to implement a single service within the current thread, some situations may require the wrapping of the service in a separate thread.
+While the _run_ / _stop_ methods offer a simple way to implement a single service/client within the current thread, some situations may require wrapping in a separate thread.
 
-Thank to [Runify](https://rubygems.org/gems/runify), a dedicated interface is provided for exactly this: _startup_ / _shutdown_ / _restart_
+Thank to [Runify](https://rubygems.org/gems/runify), a dedicated interface is provided for exactly this purpose: _startup_ / _shutdown_ / _restart_
 
 #### *startup*
 
-Calling this method will spawn a new thread around the _run_ method, effectively starting the service in the 'background'.
+Calling this method will spawn a new thread around the _run_ method, effectively starting the service / client in the 'background'.
 
 #### *shutdown*
 
-Calling _shutdown_ will request the service to terminate and wait for the thread to complete (join).
-Once this method returns, the service has completely terminated (thread dead, all clients disconnected).
+Calling _shutdown_ will request the service / client to terminate and wait for the wrapper thread to complete (join).
+Once this method returns, the service / client has completely terminated (thread dead, all sockets closed, all clients disconnected).
 
 #### *restart*
 
@@ -50,52 +51,53 @@ This method is a simple shortcut to _shutdown_ immediately followed by _startup_
 
 ### Handler Interface
 
-The following is a list of methods that should be implemented by the handler module in order to provide a valid interface to the RxIO::Service class that will use it.
+The following is a list of methods that should be implemented by the handler module in order to provide a valid interface to the RxIO::Service and RxIO::Client classes that will use it.
 
-#### *filter_input* _client_, _chunk_
+#### *filter_input* _endpoint_, _chunk_
 
-This method is called any time a chunk of data is received from a client.
+This method is called any time a chunk of data is received on the wire.
 Its purpose is usually to filter protocol data and re-assemble messages.
-Complete messages can be enqueued for processing by pushing them into the *client[:msgs]* array.
+Complete messages can be enqueued for processing by pushing them into the *endpoint[:msgs]* array.
 
-#### *handle_msg* _client_, _msg_
+#### *handle_msg* _endpoint_, _msg_
 
-Messages in the *client[:msgs]* array are regularly de-queued and passed to the *handle_msg* method for handling.
-This is usually the entry point to most of the service logic.
+Messages in the *endpoint[:msgs]* array are regularly de-queued and passed to the *handle_msg* method for handling.
+This is usually the entry point to most of the business logic for services.
 
-#### (OPTIONAL) *on_join* _client_
+#### (OPTIONAL) *on_join* _endpoint_
 
-As soon as a client is registered by the service, it is passed as argument to the _on_join_ method of the handler module (if available).
-This allows the handler module to perform any necessary initialization tasks related to this client.
+As soon as a endpoint is 'online' (Client is registered by the Service / Connection to Server is established by the Client), it is passed as argument to the _on_join_ method of the handler module (if available).
+This allows the handler module to perform any necessary initialization tasks related to this endpoint.
 
-#### (OPTIONAL) *on_drop* _client_
+#### (OPTIONAL) *on_drop* _endpoint_
 
-Called by the service whenever a client is about to be disconnected (if available).
+Called by the service / client whenever the connection to the server / a client has been lost (if available).
 This method should release any resources used by the client.
 
-#### (OPTIONAL) *send_msg* _client_, _msg_
+#### (OPTIONAL) *send_msg* _endpoint_, _msg_
 
-This method should wrap the message supplied as argument according to the desired protocol, and then add the result to the output buffer.
-While not actually required by the service class, this method should be considered a best-practice for users to encapsulate data according to a protocol.
+This method should encapsulate the message supplied as argument according to the desired protocol, and then add the result to the output buffer.
+While not absolutely required by the service or client classes, this method should be considered a best-practice for users to encapsulate data according to a protocol.
+Also, if an implementation for _send_msg_ is provided in the Service Handler, Clients built around it will expose a shortcut 'send_msg' instance method.
 
 ### Handler Base
 
-A base module is provided to facilitate implementation of new services and protocols.
+A base module is provided to facilitate implementation of new protocols.
 The *RxIO::HandlerBase* module should be extended by the service handler module.
 It provides two simple I/O methods:
 
-#### *write* _client_, _*data_
+#### *write* _endpoint_, _*data_
 
-Used to send one or more data chunks to a client.
-This method pushes the chunk(s) to the output buffer, to be later sent to the client.
+Used to send one or more data chunks to an endpoint.
+This method pushes the chunk(s) to the output buffer, to be later sent over the wire.
 
-This method is *thread-safe* - while in most cases it will be called from within the main service loop (generally as a consequence of service logic in _handle_msg_), it is perfectly safe to call from any other thread. This can be useful in situations where a service might generate messages for the client _outside_ of the normal request-response cycle (such as an event-subscription service).
+This method is *thread-safe* - while in most cases it will be called from within the main service / client loop (often as a consequence of service logic in _handle_msg_), it is perfectly safe to call from any other thread. This is how most clients should behave. This can also be useful in situations where a service might generate messages for the client _outside_ of the normal request-response cycle (such as an event-subscription service).
 
 Note: this method does not perform any encoding or transformation on the data. It is the user's responsibility to provide protocol encoding, usually through the _send_msg_ method.
 
-#### *buffer_input*, _client_, _chunk_
+#### *buffer_input*, _endpoint_, _chunk_
 
-Used to add a data chunk to the client's input buffer.
+Used to add a data chunk to the endpoint's input buffer.
 
 ### Provided Filters
 
@@ -217,6 +219,58 @@ es = EchoService.new
 es.run
 ```
 
+### A simple client for the echo service
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rxio'
+
+# Echo Client Class
+class EchoClient < RxIO::Client
+
+	# Defaults
+	DEFAULT_ADDR = '0.0.0.0'
+	DEFAULT_PORT = 4444
+
+	# Construct
+	def initialize
+		super DEFAULT_ADDR, DEFAULT_PORT, EchoHandler
+	end
+
+	# Echo Service Handler Module
+	module EchoHandler
+
+		# Extend BinDelim I/O Filter
+		extend RxIO::IOFilters::BinDelim
+
+		# Set Message Delimiter
+		msg_delim "\n"
+
+		# On Join
+		def self.on_join server
+			puts "Connected to server: #{server[:peer][:name]}:#{server[:peer][:port]}"
+			send_msg server, "Hello World!"
+		end
+
+		# On Drop
+		def self.on_drop server
+			puts "Connection dropped: #{server[:peer][:name]}:#{server[:peer][:port]}"
+		end
+
+		# Handle Message
+		def self.handle_msg server, msg
+			puts "Got response from server: #{server[:peer][:name]}:#{server[:peer][:port]} -> \"#{msg}\""
+			server[:client].stop		# Done - Terminate the Client!
+		end
+	end
+end
+
+# Run the Client
+ec = EchoClient.new
+ec.run
+```
+
 ### Running a service in the background
 
 ```ruby
@@ -235,6 +289,24 @@ es.shutdown
 puts 'Service has terminated!'
 ```
 
+### Running a client in the background
+
+```ruby
+# ...
+
+# Run the client in the background
+puts 'Client is starting up...'
+es = EchoService.new
+es.startup
+puts 'Client is online!'
+
+# Do something while the client is running...
+
+# Shutdown the client
+es.shutdown
+puts 'Client has terminated!'
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/rxio/client.rb

@@ -0,0 +1,160 @@
+# RxIO
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'thread'
+require 'socket'
+require 'runify'
+
+# Internal Includes
+require 'rxio/io_base'
+
+# RxIO Module
+module RxIO
+
+	# Client Class
+	class Client
+
+		# Runify
+		include Runify
+
+		# I/O Base
+		include IOBase
+
+		# Reconnect Delay (seconds)
+		RECONNECT_DELAY = 1
+
+		# Select Timeout (Seconds)
+		SELECT_TIMEOUT = 0.1
+
+		# Construct
+		# Builds a *Client* around a given _service_handler_ module, set to connect to _addr_ on _port_.
+		# @param [String] addr
+		# @param [Fixnum] port
+		# @param [Module] service_handler
+		def initialize addr, port, service_handler
+
+			# Set Address & Port
+			@addr = addr
+			@port = port
+
+			# Set Service Handler Module
+			@service_handler = service_handler
+
+			# Set Socket
+			@sock = nil
+
+			# Client Hash
+			@client = {
+				client: self,
+				ibuf: '',
+				obuf: '',
+				lock: Mutex.new,
+				msgs: []
+			}
+		end
+
+		# Send Message
+		# Enqueues a Message to be sent to the server
+		# @param [String] msg
+		def send_msg msg
+
+			# Verify Implementation
+			raise "Method send_msg is not implemented by Service Handler #{@service_handler.name}" unless @service_handler.respond_to? :send_msg
+
+			# Send Message through Service Handler
+			@service_handler.send_msg @client, msg
+		end
+
+		# Run
+		# Executes the main client loop, taking care of I/O scheduling and message handling.
+		def run
+
+			# Update Loop
+			begin
+
+				# Update Service
+				update until @stop
+			rescue Exception => e
+				puts "[!] ERROR - RxIO Client Update failed - #{e.inspect}"
+				e.backtrace.each { |b| puts "    - #{b}" }
+			end
+
+			# Drop Socket
+			@sock.close if @sock
+			@sock = nil
+		end
+
+		# Stop
+		# Requests the client loop to stop executing.
+		# The _run_ method should return shortly after calling _stop_
+		def stop
+			@stop = true
+		end
+
+		# Privates
+		private
+
+		# Update
+		# Serves as the client loop main method, performing I/O scheduling and message handling.
+		def update
+
+			# Ensure Socket is available
+			return unless ensure_sock
+
+			# Select
+			rd, wr, _er = IO.select [@sock], @client[:obuf].empty? ? [] : [@sock], [], SELECT_TIMEOUT
+
+			# Handle I/O
+			rd.each { |s| read_sock s } if rd
+			wr.each { |s| write_sock s } if wr
+		end
+
+		# Ensure Socket is available
+		# Re-creates the socket in the event of failure
+		def ensure_sock
+
+			# Check
+			return @sock if @sock
+
+			# Reconnect Delay (don't be an asshole...)
+			sleep RECONNECT_DELAY unless @sock
+
+			# Attempt reconnect
+			@sock = TCPSocket.new @addr, @port rescue nil
+
+			# Check Socket
+			return nil unless @sock
+
+			# Acquire Peer Address
+			peer = @sock.peeraddr
+			@client[:peer] = {
+				port: peer[1],
+				name: peer[2],
+				addr: peer[3]
+			}
+
+			# Notify Service Handler on success
+			@service_handler.on_join @client if @service_handler.respond_to? :on_join
+
+			# Return Result
+			@sock
+		end
+
+		# Get Endpoint for Socket - Callback for IOBase
+		# Simply returns the Client Hash
+		# @param [TCPSocket] _s
+		# @return [Hash] The Client Hash
+		def get_endpoint_for_sock _s
+			@client
+		end
+
+		# On Drop - Callback for IOBase
+		# Kills the socket
+		# @param [Hash] _e
+		def on_drop _e
+			@sock.close rescue nil
+			@sock = nil
+		end
+	end
+end

data/lib/rxio/handler_base.rb

@@ -9,23 +9,23 @@ module RxIO
 	module HandlerBase
 
 		# Write
-		# Writes one or more chunks of data to the client's output buffer (:obuf).
-		# @param [Hash] client
+		# Writes one or more chunks of data to the endpoint's output buffer (:obuf).
+		# @param [Hash] endpoint
 		# @param [String] data One or more chunks of data to be written to the ouput buffer
-		def write client, *data
+		def write endpoint, *data
 
 			# Add Data Chunks to Buffer
-			data.each { |c| client[:lock].synchronize { client[:obuf] << c } }
+			data.each { |c| endpoint[:lock].synchronize { endpoint[:obuf] << c } }
 		end
 
 		# Buffer Input Chunk
-		# Writes a chunk of data to the client's input buffer (:ibuf).
-		# @param [Hash] client
+		# Writes a chunk of data to the endpoint's input buffer (:ibuf).
+		# @param [Hash] endpoint
 		# @param [String] chunk
-		def buffer_input client, chunk
+		def buffer_input endpoint, chunk
 
 			# Buffer Chunk
-			client[:ibuf] << chunk
+			endpoint[:ibuf] << chunk
 		end
 	end
 end

data/lib/rxio/io_base.rb

@@ -0,0 +1,79 @@
+# RxIO
+# by Eresse <eresse@eresse.net>
+
+# RxIO Module
+module RxIO
+
+	# I/O Base Module
+	module IOBase
+
+		# Chunk Size
+		CHUNK_SIZE = 1024
+
+		# Process Input
+		# Processes Input for an Endpoint, in the form of a data chunk
+		# @param [Hash] endpoint
+		# @param [String] chunk A chunk of data, as received by the socket
+		def process_input endpoint, chunk
+
+			# Pass through Service Handler Module
+			@service_handler.filter_input endpoint, chunk
+
+			# Process Messages
+			@service_handler.handle_msg endpoint, endpoint[:msgs].shift until endpoint[:msgs].empty?
+		end
+
+		# Read Socket
+		# Attempts to read as many bytes as possible (up to CHUNK_SIZE) from a given socket _s_, passing the data chunks to _process_input_.
+		# @param [TCPSocket] s
+		def read_sock s
+
+			# Acquire Endpoint for Socket
+			e = get_endpoint_for_sock s
+
+			# Check Endpoint
+			return unless e
+
+			# Read Chunk from Socket
+			chunk = s.read_nonblock CHUNK_SIZE rescue nil
+
+			# Drop Endpoint & Abort on Error
+			return drop_endpoint e unless chunk
+
+			# Process Input
+			process_input e, chunk
+		end
+
+		# Write Socket
+		# Attempts to write as many bytes as possible to a given socket _s_ from the associated client's output buffer.
+		# @param [TCPSocket] s
+		def write_sock s
+
+			# Acquire Endpoint
+			e = get_endpoint_for_sock s
+
+			# Check Endpoint
+			return unless e
+
+			# Synchronize Endpoint
+			e[:lock].synchronize do
+
+				# Write as much as possible
+				size = (s.write_nonblock e[:obuf] rescue nil) || 0
+				e[:obuf].slice! 0, size if size > 0
+			end
+		end
+
+		# Drop Endpoint
+		# Notifies the Service Handler and Parent Implementation (in that order) of a dropped endpoint
+		# @param [Hash] endpoint
+		def drop_endpoint endpoint
+
+			# Notify Service Handler
+			@service_handler.on_drop endpoint if @service_handler.respond_to? :on_drop
+
+			# Drop Endpoint
+			on_drop endpoint
+		end
+	end
+end

data/lib/rxio/io_filters/bin_delim.rb

@@ -37,6 +37,7 @@ module RxIO
 				buffer_input client, chunk
 
 				# Ensure Last Position is available
+				client[:bin_delim] ||= {}
 				client[:bin_delim][:last_pos] ||= 0
 
 				# Loop over Messages

data/lib/rxio/service.rb

@@ -4,6 +4,10 @@
 # External Includes
 require 'thread'
 require 'socket'
+require 'runify'
+
+# Internal Includes
+require 'rxio/io_base'
 
 # RxIO Module
 module RxIO
@@ -14,8 +18,11 @@ module RxIO
 		# Runify
 		include Runify
 
-		# Chunk Size
-		CHUNK_SIZE = 1024
+		# I/O Base
+		include IOBase
+
+		# Select Timeout (Seconds)
+		SELECT_TIMEOUT = 0.1
 
 		# Construct
 		# Builds a *Service* around a given _service_handler_ module, set to listen for incoming connections @ _addr_ on _port_.
@@ -61,7 +68,7 @@ module RxIO
 			end
 
 			# Drop all Clients
-			@service_handler.on_drop @clients.pop until @clients.empty?
+			@service_handler.on_drop @clients.shift until @clients.empty? if @service_handler.respond_to? :on_drop
 			@cmap = {}
 
 			# Close all Sockets
@@ -90,24 +97,11 @@ module RxIO
 			ws = @clients.reject { |c| c[:lock].synchronize { c[:obuf].empty? } }.collect { |c| c[:sock] }
 
 			# Select Sockets
-			rd, wr = IO.select @socks, ws
+			rd, wr, _er = IO.select @socks, ws, [], SELECT_TIMEOUT
 
 			# Handle I/O
-			rd.each { |s| s == @serv ? acpt_sock(s) : read_sock(s) }
-			wr.each { |s| write_sock s }
-		end
-
-		# Process Input
-		# Processes Input from a client, in the form of a data chunk
-		# @param [Hash] client
-		# @param [String] chunk A chunk of data, as received by the socket
-		def process_input client, chunk
-
-			# Pass through Service Handler Module
-			@service_handler.filter_input client, chunk
-
-			# Process Messages
-			@service_handler.handle_msg client, client[:msgs].shift until client[:msgs].empty?
+			rd.each { |s| s == @serv ? acpt_sock(s) : read_sock(s) } if rd
+			wr.each { |s| write_sock s } if wr
 		end
 
 		# Register Client
@@ -146,24 +140,6 @@ module RxIO
 			@service_handler.on_join c if @service_handler.respond_to? :on_join
 		end
 
-		# Drop Client
-		# Unregisters a Client and closes the associated socket.
-		# Also, notifies the Handler Module if the _on_drop_ method is available.
-		# @param [Hash] c
-		def drop_client c
-
-			# Notify Service Handler
-			@service_handler.on_drop c if @service_handler.respond_to? :on_drop
-
-			# Drop Client
-			@cmap.delete c[:sock]
-			@socks.delete c[:sock]
-			@clients.delete c
-
-			# Kill Socket
-			c[:sock].close rescue nil
-		end
-
 		# Accept Socket
 		# Tries to accept any queued connection request in a non-blocking manner.
 		# Registers a new Client through _add_client_ around the newly-accepted socket if present.
@@ -177,45 +153,26 @@ module RxIO
 			add_client ns if ns
 		end
 
-		# Read Socket
-		# Attempts to read as many bytes as possible (up to CHUNK_SIZE) from a given socket _s_, passing the data chunks to _process_input_.
+		# Get Endpoint for Socket - Callback for IOBase
+		# Finds the Client associated with a given Socket
 		# @param [TCPSocket] s
-		def read_sock s
-
-			# Acquire Client
-			c = @cmap[s]
-
-			# Check Client
-			return unless c
-
-			# Read Chunk from Socket
-			chunk = s.read_nonblock CHUNK_SIZE rescue nil
-
-			# Drop Client & Abort on Error
-			return drop_client c unless chunk
-
-			# Process Input
-			process_input c, chunk
+		# @return [Hash] The Endpoint associated with Socket _s_, or nil
+		def get_endpoint_for_sock s
+			@cmap[s]
 		end
 
-		# Write Socket
-		# Attempts to write as many bytes as possible to a given socket _s_ from the associated client's output buffer.
-		# @param [TCPSocket] s
-		def write_sock s
-
-			# Acquire Client
-			c = @cmap[s]
-
-			# Check Client
-			return unless c
+		# On Drop - Callback for IOBase
+		# Unregisters a Client and closes the associated socket.
+		# @param [Hash] c
+		def on_drop c
 
-			# Synchronize Client
-			c[:lock].synchronize do
+			# Drop Client
+			@cmap.delete c[:sock]
+			@socks.delete c[:sock]
+			@clients.delete c
 
-				# Write as much as possible
-				size = s.write_nonblock c[:obuf]
-				c[:obuf].slice! 0, size if size > 0
-			end
+			# Kill Socket
+			c[:sock].close rescue nil
 		end
 	end
 end

data/lib/rxio/version.rb

@@ -5,5 +5,5 @@
 module RxIO
 
 	# Version
-	VERSION = '0.11.4'
+	VERSION = '0.12.0'
 end

data/lib/rxio.rb

@@ -3,9 +3,10 @@
 
 # Internal Includes
 require 'rxio/version'
-require 'rxio/service'
 require 'rxio/handler_base'
 require 'rxio/io_filters'
+require 'rxio/service'
+require 'rxio/client'
 
 # RxIO Module
 # Root Module for RxIO

data/rxio.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |spec|
 	spec.add_development_dependency 'bundler'
 	spec.add_development_dependency 'rake'
 	spec.add_runtime_dependency 'minitest'
+	spec.add_runtime_dependency 'runify'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rxio
 version: !ruby/object:Gem::Version
-  version: 0.11.4
+  version: 0.12.0
 platform: ruby
 authors:
 - Eresse
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-28 00:00:00.000000000 Z
+date: 2017-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: runify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides an implementation of the Reactor Pattern for Ruby Sockets.
 email:
 - eresse@eresse.net
@@ -65,7 +79,9 @@ files:
 - README.md
 - Rakefile
 - lib/rxio.rb
+- lib/rxio/client.rb
 - lib/rxio/handler_base.rb
+- lib/rxio/io_base.rb
 - lib/rxio/io_filters.rb
 - lib/rxio/io_filters/bin_delim.rb
 - lib/rxio/io_filters/msg_size.rb