xkoon 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ee2734e060d87cfe173b074e2149710a13d3317c
+  data.tar.gz: 742b227a140dbb54c9cdbb934c36032b0e01f8c3
+SHA512:
+  metadata.gz: a10dbd184d2cad958795d3451274fc7741ed5d4f13b2168d318ab8692adbdcafc0ae468033ec75d638f947a3b788b13670fc2592180ac0ab9a617095e4c5ca9c
+  data.tar.gz: 8ab2806562fdf8b3a4a3fcaf2bac368693372c0fded34a08de17860f4be3b307e3a4c5ee3d3203bd097405278f96cbee87a688816d36bc1c5c27a229d8524e93

data/.gitignore

@@ -0,0 +1,3 @@
+.idea
+Gemfile.lock
+pkg

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Paul Duncan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,217 @@
+# xKoon
+
+JSON-based Reactive Service Framework
+
+## Presentation
+
+This library provides a simple framework to build network services (servers & clients) around a very simple JSON message format, using [RxIO](https://rubygems.org/gems/rxio).
+
+## Installation
+
+### Gemfile
+```ruby
+gem 'xkoon'
+```
+
+### Terminal
+```bash
+gem install -V xkoon
+```
+
+## Usage
+
+Building a service endpoint (whether client or server) with xKoon requires the following:
+1. define a *Processor* module (for your business logic) providing a bunch of _process_XXX_ methods'
+2. instantiate an *XKoon::Service* or *XKoon::Client* object around your processor
+3. run it
+
+### The Processor
+
+The _processor_ is at the heart of xKoon - it provides all the necessary abstractions for building simple services.
+
+#### How to use
+
+To build a processor, simply include *XKoon::Processor* into any module. Then, any method in your module that starts with _process__ will be made available to remote peers.
+
+```ruby
+module ExampleProcessor
+	include XKoon::Processor
+	
+	def process_foobar p, h, m
+		puts "Got a 'foobar' request: peer=#{p} handler=#{h} message=#{m}"
+	end
+end
+```
+
+#### Sending requests
+
+The *send_request* method in *XKoon::Processor* allows sending requests to remote peers.
+
+```ruby
+Processor.send_request p, h, m, :some_request_method, data: { foo: :bar }
+```
+
+#### Sending responses
+
+While processing a request, a response can be sent back using the *send_response* method in *XKoon::Processor*.
+
+```ruby
+# Success
+send_response p, h, m, 'Everything was processed correctly!'
+```
+
+Errors should be sent using the *send_error* method.
+
+```ruby
+# Failure
+send_error p, h, m, 'Something went wrong :('
+```
+
+#### Error Wrapper
+
+An error wrapper is provided within *XKoon::Processor*, allowing for a more transparent implementation of business logic.
+
+The *error_wrapper* method will yield any block passed to it, rescuing any exception and immediately throwing it back to the remote peer.
+
+```ruby
+error_wrapper p, h, m do
+	raise "This will get thrown back to remote peer"
+end
+```
+
+#### Dealing with responses
+
+Any response to a request will be handed to the _handle_response_ method of the processor. By default the method is empty. You may override it to implement any custom behavior.
+
+```ruby
+module ExampleProcessor
+	include XKoon::Processor
+	
+	def handle_response p, h, m
+		puts "Got a response from peer [#{p}]: #{m}"
+	end
+end
+```
+
+#### Client / Server Processors
+
+The processor does not care about being the client or server. This means you can implement a single processor serving as a two-way module for both client & server.
+
+### Request Format
+
+xKoon Requests contain the following information:
+
+```ruby
+{
+	# Requested Method
+	req: :some_request_method,
+	
+	# Timestamp marking the time at which the remote peer sent the request
+	sent: 1495623525
+}
+```
+
+### Method Proxying (Make everything transparent)
+
+xKoon injects a _to_proxy_ method into every Peer Hash.
+This method simply creates a *Proxy* around the peer and returns it.
+
+The proxy object serves as a remote method interface: any method called on it will be forwarded to the remote peer.
+
+```ruby
+# Create Proxy around Peer
+pxy = peer_hash.to_proxy
+
+# Send a 'foobar' request to the remote peer
+pxy.foobar hello: :world
+```
+
+### Response Format
+
+xKoon Responses contain the following information:
+
+```ruby
+{
+	# Success (true / false)
+	success: true,
+	
+	# Original Request
+	req: { req: :some_request_method, sent: 1495623525 },
+	
+	# Whatever the remote peer responded (can be any object - will be converted to JSON)
+	res: 'Got your message!',
+	
+	# Timestamp marking the time at which the remote peer sent the response
+	sent: 1495623525
+}
+```
+
+### Example
+
+Below is a simple but complete example presenting an 'echo' service, replying back anything that was answered.
+
+```ruby
+require 'xkoon'
+
+# Proxy objects
+PXY = {}
+
+# Response Objects
+RES = {}
+
+# Two-Way Processor (used by both the client & server)
+module EchoProcessor
+	include XKoon::Processor
+	
+	# On Join (Attach the Proxy Objects as soon as we're online)
+	def self.on_join peer, handler
+		PXY[:server] = peer.to_proxy if peer.has_key? :serv
+		PXY[:client] = peer.to_proxy if peer.has_key? :client
+	end
+	
+	# On Drop (Release the Proxy Objects whenever we lose the connection)
+	def self.on_drop peer, handler
+		PXY[:server] = nil if peer.has_key? :serv
+		PXY[:client] = nil if peer.has_key? :client
+	end
+	
+	# Process 'echo' Request
+	def self.process_echo p, h, m
+		puts "Got echo request: #{m[:data]}"
+		send_response p, h, m, m[:data]
+	end
+	
+	# Handle Response
+	def self.handle_response p, h, m
+		RES[:server] = m if p.has_key? :serv
+		RES[:client] = m if p.has_key? :client
+		puts "Got response from peer #{p[:peer][:name]}:#{p[:peer][:port]}: #{m[:res]}"
+	end
+end
+
+# Create Endpoints
+srv = XKoon::Service.new EchoProcessor
+cli = XKoon::Client.new EchoProcessor
+
+# Start Server & Client
+srv.startup
+cli.startup
+
+# Wait for client and echo something
+sleep 0.1 until PXY[:client]
+PXY[:client].echo data: { str: 'hello world!' }
+
+# Wait for Response to come back
+sleep 0.1 until RES[:client]
+
+# Drop Client and wait for drop
+cli.shutdown
+sleep 0.1 while PXY[:server]
+
+# Drop Server
+srv.shutdown
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+	t.libs << 'test'
+	t.pattern = 'test/**/test*.rb'
+end
+
+task :default => :test

data/lib/xkoon.rb

@@ -0,0 +1,15 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# Internal Includes
+require 'xkoon/version'
+require 'xkoon/service'
+require 'xkoon/client'
+require 'xkoon/handler'
+require 'xkoon/processor'
+require 'xkoon/proxy'
+
+# xKoon Module:
+# Root Module for xKoon.
+module XKoon
+end

data/lib/xkoon/client.rb

@@ -0,0 +1,40 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'json'
+require 'aromat'
+require 'rxio'
+
+# Internal Includes
+require 'xkoon/handler'
+
+# xKoon Module
+module XKoon
+
+	# Client Class
+	class Client < RxIO::Client
+
+		# Attribute Accessors
+		attr_reader :processor
+
+		# Defaults
+		DEFAULT_ADDR = 'localhost'
+		DEFAULT_PORT = 23255
+
+		# Construct:
+		# Builds a *Client* around a given _processor_ implementation, set to connect to _addr_ on _port_.
+		# @param [Module] processor
+		# @param [String] addr
+		# @param [Fixnum] port
+		# @param [Hash] ssl_params
+		def initialize processor, addr = DEFAULT_ADDR, port = DEFAULT_PORT, ssl_params = nil
+
+			# Super
+			super addr, port, Handler, ssl_params
+
+			# Set Processor
+			@processor = processor
+		end
+	end
+end

data/lib/xkoon/handler.rb

@@ -0,0 +1,92 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'json'
+require 'aromat'
+require 'rxio'
+
+# Internal Includes
+require 'xkoon/processor'
+require 'xkoon/proxy'
+
+# xKoon Module
+module XKoon
+
+	# Handler Module:
+	# Provides a generic two-way implementation of the xKoon Protocol.
+	module Handler
+
+		# Split messages on New Lines (Extend BinDelim I/O Filter & Set message delimiter to "\n")
+		extend RxIO::IOFilters::BinDelim
+		msg_delim "\n"
+
+		# Send Request:
+		# Sends a request to the Peer.
+		# @param [Hash] peer RxIO Peer (Client / Server) Hash
+		# @param [Symbol] req Request method
+		# @param [Hash] msg Message Hash
+		def self.send_request peer, req, msg
+			send_msg peer, msg.merge(req: req, sent: Time.now.to_i).to_json
+		end
+
+		# On Join:
+		# RxIO Service Interface Callback - Triggered each time a peer is connected. Forwards notifications to Processor.
+		# @param [Hash] peer An RxIO Peer (Client / Server) Hash
+		def self.on_join peer
+
+			# Acquire Local Endpoint's Processor
+			proc = peer[:local].processor
+
+			# Inject Proxy Generator Method into Peer
+			peer.define_singleton_method(:to_proxy) { Proxy.for_peer peer }
+
+			# Forward Join Notification to Processor
+			proc.on_join peer, self if proc.respond_to? :on_join
+		end
+
+		# On Drop:
+		# RxIO Service Interface Callback - Triggered each time a peer is dropped. Forwards notifications to Processor.
+		# @param [Hash] peer An RxIO Peer (Client / Server) Hash
+		def self.on_drop peer
+
+			# Acquire Local Endpoint's Processor
+			proc = peer[:local].processor
+
+			# Forward Drop Notification to Processor
+			proc.on_drop peer, self if proc.respond_to? :on_drop
+		end
+
+		# Handle Message:
+		# Parses incomning messages and forwards them to the processor.
+		# @param [Hash] peer An RxIO Peer (Client / Server) Hash
+		# @param [String] msg A message
+		def self.handle_msg peer, msg
+
+			# Process Chomped Message as JSON and Deep-Symbolize Keys
+			process_msg peer, JSON.parse(msg.chomp).try(:sym_keys)
+		end
+
+		# Process Message:
+		# Verifies message structure and forwards to processor.
+		# @param [Hash] peer An RxIO Peer (Client / Server) Hash
+		# @param [Hash] msg A message
+		def self.process_msg peer, m
+
+			# Acquire Local Endpoint's Processor
+			proc = peer[:local].processor
+
+			# Check Request Present in Message
+			raise "Missing method in request" unless m[:req].try(:to_s).try :nstr
+
+			# Handle Responses
+			return proc.handle_response peer, self, m if m[:req].is_a? Hash
+
+			# Check Request Valid in Message
+			raise "Invalid method [#{m[:req]}] in request" unless proc.respond_to? "process_#{m[:req]}".to_sym
+
+			# Forward Message to Local Endpoint's Processor
+			proc.send "process_#{m[:req]}".to_sym, peer, self, m
+		end
+	end
+end

data/lib/xkoon/processor.rb

@@ -0,0 +1,85 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'json'
+require 'aromat'
+
+# xKoon Module
+module XKoon
+
+	# Generic Processor Module:
+	# Provides base methods for implementing xKoon Service Processors.
+	module Processor
+
+		# Included:
+		# Inject stuff when included.
+		def self.included base
+			base.extend ClassMethods
+		end
+
+		# Class Methods:
+		# These are injected into the user's processor implementation when this module is included.
+		module ClassMethods
+
+			# Send Request:
+			# Sends a request to the Peer.
+			# @param [Hash] p RxIO Peer (Client / Server) Hash
+			# @param [Module] h Handler Module
+			# @param [Symbol] r Request method
+			# @param [Hash] m Message Hash
+			def send_request p, h, r, m
+				h.send_request p, r, m
+			end
+
+			# Handle Response:
+			# Called whenever a response is sent back from the remote peer.
+			# @param [Hash] p RxIO Peer (Client / Server) Hash
+			# @param [Module] h Handler Module
+			# @param [Hash] m Message Hash
+			def handle_response p, h, m
+				# NoOp - Provide your implementation
+			end
+
+			# Wrap in Error:
+			# Yields the given block, rescuing exceptions and throwing them back to the peer.
+			# @param [Hash] p RxIO Peer (Client / Server) Hash
+			# @param [Module] h Handler Module
+			# @param [Hash] m Message Hash
+			# @return [Array] An two-element Array containing a boolean representing success and the block's result [failed, output]
+			def error_wrapper p, h, m
+				failed = false
+				out = nil
+				begin
+					out = yield
+				rescue Exception => e
+					send_error p, h, m, e
+					failed = true
+				end
+
+				[failed, out]
+			end
+
+			# Respond with Error:
+			# Sends an error message to the Peer.
+			# @param [Hash] p RxIO Peer (Client / Server) Hash
+			# @param [Module] h Handler Module
+			# @param [Hash] req Original request from Peer
+			# @param [Object] error Anything representing an error
+			def send_error p, h, req, error
+				send_response p, h, req, { error: error }, false
+			end
+
+			# Send Generic Response Message:
+			# Sends a response message to the Peer.
+			# @param [Hash] p RxIO Peer (Client / Server) Hash
+			# @param [Module] h Handler Module
+			# @param [Hash] req Original request from Peer
+			# @param [Object] res Anything representing the result of the Peer's request
+			# @param [Object] success Boolean indicating success for the Peer's request
+			def send_response p, h, req, res = {}, success = true
+				h.send_msg p, { success: success, req: req, res: res, sent: Time.now.to_i }.to_json
+			end
+		end
+	end
+end

data/lib/xkoon/proxy.rb

@@ -0,0 +1,69 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'aromat'
+
+# Internal Includes
+require 'xkoon/handler'
+require 'xkoon/processor'
+
+# xKoon Module
+module XKoon
+
+	# Proxy Module:
+	# Provides transparent proxying of methods to a Peer.
+	module Proxy
+
+		# Create Proxy for Peer:
+		# Creates a new *Base* proxy object around a given _peer_ and optional _handler_.
+		# @param [Hash] peer RxIO Peer (Client / Server) Hash
+		# @param [Module] handler Handler module
+		def self.for_peer peer, handler = XKoon::Handler
+			Base.new peer, handler
+		end
+
+		# Method Missing:
+		# Proxy all method calls into requests to the Service Peer.
+		def self.method_missing name, *args
+
+			# Ensure we have at least a peer, handler and message
+			raise "Missing arguments in call to [#{name}] (peer, handler, msg)" unless args.size >= 3
+
+			# Get Peer & Handler from Args
+			peer = args.slice! 0
+			handler = args.slice! 0
+
+			# Acquire Payload
+			msg = args.slice! 0
+
+			# Send Request
+			handler.send_request peer, name, msg
+		end
+
+		# Object Proxy Base Class:
+		# Inherit this class to build proxy objects, routing all method calls to the remote peer.
+		class Base
+
+			# Construct:
+			# Creates a new *Base* proxy object around a given _peer_ and optional _handler_.
+			# @param [Hash] peer RxIO Peer (Client / Server) Hash
+			# @param [Module] handler Handler module
+			def initialize peer, handler = XKoon::Handler
+				@proxy_peer = peer
+				@proxy_handler = handler
+			end
+
+			# Method Missing:
+			# Proxy all method calls into requests to the remote peer.
+			def method_missing name, *args
+
+				# Ensure we have at least a message
+				raise "Missing argument in call to [#{name}] (msg)" unless args.size >= 1
+
+				# Forward request through Proxy Module
+				Proxy.send name, @proxy_peer, @proxy_handler, *args
+			end
+		end
+	end
+end

data/lib/xkoon/service.rb

@@ -0,0 +1,40 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'json'
+require 'aromat'
+require 'rxio'
+
+# Internal Includes
+require 'xkoon/handler'
+
+# xKoon Module
+module XKoon
+
+	# Service Class
+	class Service < RxIO::Service
+
+		# Attribute Accessors
+		attr_reader :processor
+
+		# Defaults
+		DEFAULT_ADDR = 'localhost'
+		DEFAULT_PORT = 23255
+
+		# Construct:
+		# Builds a *Service* around a given _processor_ implementation, set to listen for incoming connections @ _addr_ on _port_.
+		# @param [Module] processor
+		# @param [String] addr
+		# @param [Fixnum] port
+		# @param [Hash] ssl_params
+		def initialize processor, addr = DEFAULT_ADDR, port = DEFAULT_PORT, ssl_params = nil
+
+			# Super
+			super addr, port, Handler, ssl_params
+
+			# Set Processor
+			@processor = processor
+		end
+	end
+end

data/lib/xkoon/version.rb

@@ -0,0 +1,9 @@
+# xKoon
+# by Eresse <eresse@eresse.net>
+
+# xKoon Module
+module XKoon
+
+	# Version
+	VERSION = '1.0.0'
+end

data/xkoon.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'xkoon/version'
+
+Gem::Specification.new do |spec|
+	spec.name = 'xkoon'
+	spec.version = XKoon::VERSION
+	spec.authors = ['Eresse']
+	spec.email = ['eresse@eresse.net']
+
+	spec.summary = 'JSON-based Reactive Service Framework'
+	spec.description = 'Provides a simple framework to build network services.'
+	spec.homepage = 'http://redmine.eresse.net/projects/xkoon'
+	spec.license = 'MIT'
+
+	spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+	spec.require_paths = ['lib']
+
+	spec.add_development_dependency 'bundler'
+	spec.add_development_dependency 'rake'
+	spec.add_runtime_dependency 'minitest'
+	spec.add_runtime_dependency 'aromat'
+	spec.add_runtime_dependency 'rxio'
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: xkoon
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Eresse
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-05-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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'
+- !ruby/object:Gem::Dependency
+  name: aromat
+  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'
+- !ruby/object:Gem::Dependency
+  name: rxio
+  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 a simple framework to build network services.
+email:
+- eresse@eresse.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xkoon.rb
+- lib/xkoon/client.rb
+- lib/xkoon/handler.rb
+- lib/xkoon/processor.rb
+- lib/xkoon/proxy.rb
+- lib/xkoon/service.rb
+- lib/xkoon/version.rb
+- xkoon.gemspec
+homepage: http://redmine.eresse.net/projects/xkoon
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: JSON-based Reactive Service Framework
+test_files: []