elaios 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 20887b1b251d6324dc684b0e87a99339dea9e37a
+  data.tar.gz: 64dfcd192b76ce0c41370943e780b51dc0db21e3
+SHA512:
+  metadata.gz: dda0d362a80747fda46f2f37639e5e06ac0c88523eb866b8820c615ad6dcf952efedda4527d92b151ed118c51efaa86e68a7417ba6ba901cff857a2064503370
+  data.tar.gz: 8601b34a70f2bb4523073e22fc847b60ae0bb58a92ecd74ac08badb14b7074f3466d2b078560053f110854a543c4c1346caab462f0e9af52e999351a47a34320

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.12.5

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in elaios.gemspec
+gemspec

data/README.md

@@ -0,0 +1,263 @@
+# Elaios
+
+Elaios is a protocol-agnostic library for writing JSON-RPC clients and servers.
+It can be used over TCP, HTTP, STOMP, and other protocols, and can be used with
+threaded-, evented-, or fiber-based code.
+
+Furthermore, it is thread-safe, has a very simple API, and well-tested.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elaios'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install elaios
+
+## Usage
+
+Look in the `spec/integation` directory for more usage examples.
+
+### Including Elaios in your code
+
+From your Ruby code:
+
+```ruby
+require 'elaios'
+```
+
+### Basic client usage
+
+```ruby
+elaios_client = Elaios::Client.new
+
+# Call a JSON-RPC method and don't expect a response.
+elaios_client.foo(['some', 'args'])
+
+# Call a JSON-RPC method and expect a response.
+elaios_client.bar(['some', 'other', 'args']) do |data|
+  # Do something with the response from the server...
+end
+
+request_1 = elaios_client.pop
+request_2 = elaios_client.pop
+# Send the requests to the server somehow (they will be JSON strings)...
+
+# Get a response from the server somehow (it will be a JSON string). This will
+# trigger the callback above to be called.
+elaios_client << response
+```
+
+### Basic server usage
+
+```ruby
+elaios_server = Elaios::Server.new
+
+elaios_server.foo do |data|
+  # Do some processing here...
+end
+
+elaios_server.bar do |data|
+  # To send a success response...
+  res(data['method'], data['id'], ['some', 'response'])
+
+  # Or, to send an error response...
+  err(data['method'], data['id'], 'Sorry, an error occurred.')
+end
+
+# Get JSON string requests from the client somehow. These will trigger the above
+# callbacks to be called.
+elaios_server << request_1
+elaios_server << request_2
+
+response = elaios_server.pop
+# Send the response to the client somehow (it will be a JSON string).
+```
+
+### API
+
+```
+# --------------
+# Elaios::Server
+# --------------
+
+# Create a new Elaios server object.
+Elaios::Server#new(options={})
+
+`options` may consist of:
+
+* `:name` - An optional name for a server.
+* `:logger` - An optional logger object.
+
+# Push an object onto the server for processing.
+Elaios::Server#push(obj)
+Elaios::Server#<<(obj)
+Elaios::Server#enq(obj)
+
+# Pop a response off of the server.
+Elaios::Server#pop
+Elaios::Server#deq
+Elaios::Server#shift
+
+# Push an object onto the server, update, and then pop a response off.
+Elaios::Server#process(obj)
+Elaios::Server#pushpop(obj)
+Elaios::Server#push_pop(obj)
+
+# Register a handler.
+Elaios::Server#method_missing(name, &block)
+
+# Generate a success response for sending to the client.
+Elaios::Server#res(method, id, data)
+Elaios::Server#response(method, id, data)
+
+# Generate an error response for sending to the client.
+Elaios::Server#err(method, id, data)
+Elaios::Server#error(method, id, data)
+
+# --------------
+# Elaios::Client
+# --------------
+
+# Create a new Elaios client object.
+Elaios::Client.new(options={})
+
+`options` may consist of:
+
+* `:name` - An optional name for a server.
+* `:logger` - An optional logger object.
+
+# Push an object onto the client for processing.
+Elaios::Client.push(obj)
+Elaios::Client.<<(obj)
+Elaios::Client.enq(obj)
+
+# Pop a response off of the client.
+Elaios::Client#pop
+Elaios::Client#deq
+Elaios::Client#shift
+
+# Call a JSON-RPC method.
+Elaios::Client#method_missing(name, args=nil, &block)
+```
+
+### Threaded TCP client usage
+
+```ruby
+# TCP client.
+socket = TCPSocket.open('0.0.0.0', 5000)
+elaios_client = Elaios::Client.new
+
+# Incoming socket data.
+Thread.new do
+  loop do
+    elaios_client << socket.gets.chomp
+  end
+end
+
+# Outgoing socket data.
+Thread.new do
+  loop do
+    result = elaios_client.pop
+    socket.puts(result) if result
+  end
+end
+
+# Make a service call and expect no response.
+elaios_client.ping('foo')
+
+# Make a service call and expect a response.
+elaios_client.ping('foo') do |response|
+  # Do something with the response...
+end
+```
+
+### Threaded TCP server usage
+
+```ruby
+# TCP server.
+server = TCPServer.open(5000)
+loop do
+  # New incoming socket connection.
+  Thread.fork(server.accept) do |socket|
+    # We need a new Elaios instance for every incoming connection.
+    elaios_server = Elaios::Server.new
+
+    # Create a server handler.
+    elaios_server.ping do |data|
+      # Generate some sort of response. Note that we grab the method name and id
+      # from the `data` hash.
+      #
+      # Also note that within this block, `self` is the `elaios_server` object.
+      #
+      res(data['method'], data['id'], { foo: 'bar' })
+    end
+
+    # Incoming socket data.
+    Thread.new do
+      loop do
+        elaios_server << socket.gets.chomp
+      end
+    end
+
+    # Outgoing socket data.
+    Thread.new do
+      loop do
+        result = elaios_server.pop
+        socket.puts(result) if result
+      end
+    end
+  end
+end
+```
+
+### Evented TCP client usage
+
+**TODO:** Fill this in.
+
+### Evented TCP server usage
+
+**TODO:** Fill this in.
+
+### HTTP client usage
+
+**NOTE:** This is only one way to use Elaios with an HTTP client. You can use
+any HTTP client library with Elaios.
+
+**TODO:** Fill this in.
+
+### HTTP server usage
+
+**NOTE:** This is only one way to use Elaios with an HTTP server. You can use
+any HTTP server library with Elaios.
+
+**TODO:** Fill this in.
+
+### STOMP usage
+
+**TODO:** Fill this in.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/rjungemann/elaios.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "elaios"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/elaios.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'elaios/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'elaios'
+  spec.version       = Elaios::VERSION
+  spec.authors       = ['Roger Jungemann']
+  spec.email         = ['roger@thefifthcircuit.com']
+
+  spec.summary       = %q{A protocol-agnostic JSON-RPC client-server library.}
+  spec.homepage      = 'https://github.com/rjungemann/elaios'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'simple-queue', '~> 0.1.0'
+  spec.add_dependency 'eventmachine', '1.2.0.1'
+  spec.add_dependency 'sinatra', '1.4.7'
+  spec.add_development_dependency 'bundler', '~> 1.12'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/lib/elaios.rb

@@ -0,0 +1,12 @@
+require 'logger'
+require 'json'
+require 'securerandom'
+require 'simple/queue'
+
+require 'elaios/version'
+
+module Elaios
+end
+
+require 'elaios/server'
+require 'elaios/client'

data/lib/elaios/client.rb

@@ -0,0 +1,65 @@
+class Elaios::Client
+  attr_reader :logger
+
+  def initialize(options={})
+    @name = options[:name] || 'elaios_client'
+    @logger = options[:logger] || Logger.new(STDOUT).tap { |l|
+      l.progname = @name
+      l.level = ENV['LOG_LEVEL'] || 'info'
+    }
+    @blocks = {}
+    @in = Simple::Queue.new
+    @out = Simple::Queue.new
+  end
+
+  def push(obj)
+    @in.push(obj)
+    update
+  end
+  alias_method :<<, :push
+  alias_method :enq, :push
+
+  def pop
+    @out.pop
+  end
+  alias_method :deq, :pop
+  alias_method :shift, :pop
+
+  # Call a remote JSON-RPC method. If a block is provided, then we expect a
+  # response from the server.
+  def method_missing(name, args=nil, &block)
+    id = SecureRandom.uuid
+    data = {
+      'jsonrpc' => '2.0',
+      'method' => name,
+      'params' => args
+    }
+    # Only set the id if the client expects a response.
+    data['id'] = id if block
+    payload = JSON.dump(data)
+    @logger.debug(%(method_missing payload: #{payload.inspect}))
+    @out << payload
+    return unless block
+    @logger.debug(%(registered block for id #{id}: #{block.inspect}))
+    @blocks[id] = block if block
+  end
+
+  # Called internally by `push`. Exposed for testing.
+  def update
+    results = @in.pop
+    return unless results
+    results.split("\n").each do |result|
+      @logger.debug(%(result given: #{result}))
+      payload = JSON.load(result) rescue nil
+      next unless payload
+      @logger.debug(%(payload parsed: #{payload.inspect}))
+      block = @blocks[payload['id']]
+      @logger.debug(%(block found: #{block.inspect}))
+      next unless block
+      self.instance_exec(payload, &block)
+      @logger.debug(%(block called: #{block.inspect}))
+      @blocks.delete(payload['id'])
+      @logger.debug(%(block unregistered: #{block.inspect}))
+    end
+  end
+end

data/lib/elaios/server.rb

@@ -0,0 +1,93 @@
+class Elaios::Server
+  attr_reader :logger
+
+  def initialize(options={})
+    @name = options[:name] || 'elaios_server'
+    @logger = options[:logger] || Logger.new(STDOUT).tap { |l|
+      l.progname = @name
+      l.level = ENV['LOG_LEVEL'] || 'info'
+    }
+    @blocks = {}
+    @in = Simple::Queue.new
+    @out = Simple::Queue.new
+    @mutex = Mutex.new
+  end
+
+  def push(obj)
+    @mutex.synchronize { unsafe_push(obj) }
+  end
+  alias_method :<<, :push
+  alias_method :enq, :push
+
+  def pop
+    @mutex.synchronize { unsafe_pop }
+  end
+  alias_method :deq, :pop
+  alias_method :shift, :pop
+
+  def process(obj)
+    @mutex.synchronize { unsafe_push(obj); unsafe_pop }
+  end
+  alias_method :pushpop, :process
+  alias_method :push_pop, :process
+
+  # Set up a handler.
+  def method_missing(name, &block)
+    @blocks[name] = block
+    @logger.debug(%(registered handler for #{name}: #{block.inspect}))
+  end
+
+  # Send a success response to the client.
+  def res(method, id, data)
+    payload = JSON.dump({
+      'jsonrpc' => '2.0',
+      'method' => method,
+      'result' => data,
+      'id' => id
+    })
+    @logger.debug(%(enqueueing success payload for sending: #{payload.inspect}))
+    @out << payload
+  end
+  alias_method :response, :res
+
+  # Send an error response to the client.
+  def err(method, id, data)
+    payload = JSON.dump({
+      'jsonrpc' => '2.0',
+      'method' => method,
+      'error' => data,
+      'id' => id
+    })
+    @logger.debug(%(enqueueing error payload for sending: #{payload.inspect}))
+    @out << payload
+  end
+  alias_method :error, :err
+
+  # Called internally by `push`. Exposed for testing.
+  def update
+    results = @in.pop
+    return unless results
+    results.split("\n").each do |result|
+      @logger.debug(%(result given: #{result}))
+      payload = JSON.load(result) rescue nil
+      next unless payload
+      @logger.debug(%(payload parsed: #{payload.inspect}))
+      block = @blocks[payload['method'].to_sym]
+      @logger.debug(%(block found: #{block.inspect}))
+      next unless block
+      self.instance_exec(payload, &block)
+      @logger.debug(%(block called: #{block.inspect}))
+    end
+  end
+
+  # Called internally by `push` and `process`. Exposed for testing.
+  def unsafe_push(obj)
+    @in.push(obj)
+    update
+  end
+
+  # Called internally by `pop` and `process`. Exposed for testing.
+  def unsafe_pop
+    @out.pop
+  end
+end

data/lib/elaios/version.rb

@@ -0,0 +1,3 @@
+module Elaios
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: elaios
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roger Jungemann
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simple-queue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0.1
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.4.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.4.7
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- roger@thefifthcircuit.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- elaios.gemspec
+- lib/elaios.rb
+- lib/elaios/client.rb
+- lib/elaios/server.rb
+- lib/elaios/version.rb
+homepage: https://github.com/rjungemann/elaios
+licenses: []
+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: A protocol-agnostic JSON-RPC client-server library.
+test_files: []