protoplasm-client 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in protoplasm.gemspec
+gemspec :name => 'protoplasm-server'
+gemspec :name => 'protoplasm-client'

data/README.md

@@ -0,0 +1,103 @@
+# Protoplasm
+
+Protoplasm makes is easy to define an RPC server/client which is backed by protobuf through Beefcake.
+
+## Defining your service endpoints
+
+The current service model is very simple. You can send one protobuf object (the request object). This object must have an enum and a series of optional command fields to allow it to send commands. From the tests, this is a valid request object definition:
+
+```ruby
+class Command
+  include Beefcake::Message
+  module Type
+    PING   = 1
+    UPCASE = 2
+    EVEN   = 3
+  end
+  required :type,           Type,          1
+  optional :ping_command,   PingCommand,   2
+  optional :upcase_command, UpcaseCommand, 3
+  optional :even_command,   EvenCommand,   4
+end
+```
+
+In this case, your request object would be able to accept one, and only one subcommand object. Those types are `PingCommand`, `UpcaseCommand` and `EvenCommand`.
+
+So, in order to mark this `Command` class as your request class, you'd do the following:
+
+```ruby
+module Types
+  include Protoplasm::Types
+  
+  # .. your actual classes would go here
+
+  request_class Command
+  request_type_field :type
+end
+```
+
+## Defining your response objects
+
+Every subcommand can choose to relay back no objects, one object, or stream any number of objects. Those objects must all be of the same type.
+
+To define which objects you expect back, you must add the following.
+
+```ruby
+module Types
+  rpc_map Command::Type::PING,   :ping_command,   nil
+  rpc_map Command::Type::UPCASE, :upcase_command, UpcaseResponse
+  rpc_map Command::Type::EVEN,   :even_command,   EvenResponse,  :streaming => true
+```
+
+In this case, this would define the ping command as returning no object, the upcase command returns a single object, of type `UpcaseResponse`, and the even command return any number of `EvenResponse` objects.
+
+## Server implementation
+
+Currently there is a single server implementation `EMServer`, which defines a non-blocking EventMachine based server. To create an `EMServer`, you subclass `Protoplasm::EMServer` and setup handlers for each of your command types. For example, a worker server could look like this:
+
+```ruby
+class Server < Protoplasm::EMServer
+  def process_ping_command(ping_command)
+    # do nothing
+  end
+
+  def process_upcase_command(upcase_command)
+    send_response(:response => cmd.word.upcase)
+  end
+
+  def process_even_command(even_command)
+    (1..even_command.top).each do |num|
+      send_response(:num => num) if num % 2 == 0
+    end
+    finish_streaming
+  end
+end
+```
+
+This server then could be started with `Server.start(3000)` which would start on port 3000 and process requests.
+
+## Client
+
+Currently there is a single client implementation: `BlockingClient`. It defines a blocking `TCPSocket` based client. To create a client for this example, you would do the following.
+
+```ruby
+class Client < Protoplasm::BlockingClient
+  def initialize(host, port)
+    super(Types, host, port)
+  end
+
+  def ping
+    send_request(:ping_command)
+  end
+
+  def upcase(word)
+    send_request(:upcase_command, :word => word).response
+  end
+
+  def evens(top)
+    send_request(:even_command, :top => top) { |resp| yield resp.num }
+  end
+end
+```
+
+Look at the full example under `test/test_helper.rb`.

data/Rakefile

@@ -0,0 +1,74 @@
+require 'bundler'
+require 'rake/testtask'
+require './lib/protoplasm/version'
+
+task :test do
+  Rake::TestTask.new do |t|
+    Dir['test/*_test.rb'].each{|f| require File.expand_path(f)}
+  end
+end
+
+def version
+  Protoplasm::VERSION
+end
+
+def version_tag
+  "v#{version}"
+end
+
+def tag_version
+  system("git tag -a -m \"Version #{version}\" #{version_tag}") or raise("Cannot tag version")
+  Bundler.ui.confirm "Tagged #{version_tag}"
+  yield
+rescue
+  Bundler.ui.error "Untagged #{version_tag} due to error"
+  system("git tag -d #{version_tag}") or raise("Cannot untag version")
+  raise
+end
+
+
+desc "Release client & server (#{version})"
+task :release do
+  tag_version do
+    Rake::Task["server:release_without_tagging"].invoke
+    Rake::Task["client:release_without_tagging"].invoke
+  end
+end
+
+desc "Install client & server (#{version})"
+task :install do
+  Rake::Task["server:install"].invoke
+  Rake::Task["client:install"].invoke
+end
+
+desc "Build client & server (#{version})"
+task :build do
+  Rake::Task["server:build"].invoke
+  Rake::Task["client:build"].invoke
+end
+
+namespace :server do
+  helper = Bundler::GemHelper.new(File.dirname(__FILE__), "protoplasm-server")
+  helper.install
+  helper.instance_eval do
+    task :release_without_tagging do
+      guard_clean
+      built_gem_path = build_gem
+      git_push
+      rubygem_push(built_gem_path)
+    end
+  end
+end
+
+namespace :client do
+  helper = Bundler::GemHelper.new(File.dirname(__FILE__), "protoplasm-client")
+  helper.install
+  helper.instance_eval do
+    task :release_without_tagging do
+      guard_clean
+      built_gem_path = build_gem
+      git_push
+      rubygem_push(built_gem_path)
+    end
+  end
+end

data/lib/protoplasm.rb

@@ -0,0 +1,7 @@
+require "protoplasm/version"
+
+module Protoplasm
+  autoload :BlockingClient, "protoplasm/client/blocking_client"
+  autoload :EMServer,       "protoplasm/server/em_server"
+  autoload :Types,          "protoplasm/types/types"
+end

data/lib/protoplasm/client/blocking_client.rb

@@ -0,0 +1,63 @@
+require 'socket'
+
+module Protoplasm
+  class BlockingClient
+    attr_reader :_types
+
+    def initialize(_types, host, port)
+      @_types, @host, @port = _types, host, port
+    end
+
+    private
+    def _socket(force_new = false)
+      if force_new
+        TCPSocket.open(@host, @port)
+      else
+        @_socket ||= TCPSocket.open(@host, @port)
+      end
+    end
+
+    def _master_socket
+      @_master_socket ||= _socket
+    end
+
+    def send_request(field, *args, &blk)
+      s = ''
+      type = _types.request_type_for_field(field)
+      cmd_class = type.command_class.fields.values.find{|f| f.name == field}
+      cmd = _types.request_class.new(_types.request_type_field => type.type, type.field => cmd_class.type.new(*args))
+      cmd.encode(s)
+      socket = _socket(type.streaming?)
+      socket.write([0, s.size].pack("CQ"))
+      socket.write s
+      socket.flush
+      unless type.void?
+        if type.streaming?
+          begin
+            until socket.eof?
+              len = socket.read(8).unpack("Q").first
+              buf = ''
+              while buf.size < len
+                socket.read(len - buf.size, buf)
+              end
+              yield type.response_class.decode(buf)
+            end
+          ensure
+            socket.close
+          end
+        else
+          len_buf = socket.readpartial(8)
+          while len_buf.size < 8
+            socket.readpartial(8 - len_buf.size, len_buf)
+          end
+          len = len_buf.unpack("Q").first
+          buf = ''
+          until buf.size == len or socket.eof?
+            socket.readpartial(len - buf.size, buf) 
+          end
+          type.response_class.decode(buf)
+        end
+      end
+    end
+  end
+end

data/lib/protoplasm/server/em_server.rb

@@ -0,0 +1,71 @@
+require 'eventmachine'
+
+module Protoplasm
+  class EMServer < EventMachine::Connection
+    CONTROL_REQUEST     = 0
+
+    def self.start(types, port)
+      if EM.reactor_running?
+        EM::start_server("0.0.0.0", port, self) do |srv|
+          srv._types = types
+          yield srv if block_given?
+        end
+      else
+        begin
+          EM.run do
+            start(types, port)
+          end
+        rescue Interrupt
+        end
+      end
+    end
+
+    attr_accessor :_types
+
+    def post_init
+      @_response_types = []
+      @data = ''
+    end
+
+    def receive_data(data)
+      @data << data
+      data_ready
+    end
+
+    def finish_streaming
+      close_connection_after_writing
+    end
+
+    def data_ready
+      @control = @data.slice!(0, 1).unpack("C").first unless @control
+      case @control
+      when CONTROL_REQUEST
+        @size = @data.slice!(0, 8).unpack("Q").first unless @size
+
+        if @data.size >= @size
+          buf = @data.slice!(0, @size)
+          @size, @control = nil, nil
+          obj = _types.request_class.decode(buf)
+          type = _types.request_type_for_request(obj)
+          @_response_types << type unless type.void?
+          EM.next_tick { send(:"process_#{type.field}", obj.send(type.field)) }
+          data_ready unless @data.empty?
+          #EM.next_tick { data_ready } #todo left over data needs to be processed still
+        end
+      else
+        # illegal char
+        close_connection
+      end
+    end
+
+    def send_response(*args)
+      type = @_response_types.first
+      @_response_types.shift unless type.streaming?
+      obj = type.response_class.new(*args)
+      s = ''
+      obj.encode(s)
+      send_data [s.size].pack("Q")
+      send_data s
+    end
+  end
+end

data/lib/protoplasm/types/types.rb

@@ -0,0 +1,69 @@
+require 'beefcake'
+
+module Protoplasm
+  module Types
+    # the truest thing i know ... the enum pattern matches to a response class
+    # therefore, you need to know the following
+    # where is the request class
+    # where is the field class
+    # how does the field map to response classes
+
+    def self.included(cls)
+      cls.extend(ClassMethods)
+    end
+
+    class RequestResponseType < Struct.new(:request_class, :response_class, :type, :field, :streaming)
+
+      alias_method :streaming?, :streaming
+
+      def command_class
+        request_class
+      end
+
+      def void?
+        response_class.nil?
+      end
+    end
+
+    module ClassMethods
+      def request_class(request_class = nil)
+        request_class ? @request_class = request_class : @request_class
+      end
+
+      def request_type(request_obj)
+        request_obj.send(@request_type_field)
+      end
+
+      def request_type_field(field = nil)
+        field ? @request_type_field = field : @request_type_field
+      end
+
+      def rpc_map(type, field, response_class, opts = nil)
+        @response_map_by_field ||= {}
+        @response_map_by_type ||= {}
+        streaming = opts && opts.key?(:streaming) ? opts[:streaming] : false
+        rrt = RequestResponseType.new(@request_class, response_class, type, field, streaming)
+        @response_map_by_field[field] = rrt
+        @response_map_by_type[type] = rrt
+      end
+
+      def request_type_for_field(field)
+        @response_map_by_field[field]
+      end
+
+      def request_type_for_request(req)
+        @response_map_by_type[req.send(@request_type_field)]
+      end
+    end
+  end
+end
+
+# module Unilogger
+#   module Types
+#     include Protoplasm::Types
+# 
+#     request_class RequestCommand
+#     request_type_field :command_type
+#     response_map LogCommand::CommandType::INSERT, nil
+#   end
+# end

data/lib/protoplasm/version.rb

@@ -0,0 +1,3 @@
+module Protoplasm
+  VERSION = "0.0.1"
+end

data/protoplasm-client.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "protoplasm/version"
+
+Gem::Specification.new do |s|
+  s.name        = "protoplasm-client"
+  s.version     = Protoplasm::VERSION
+  s.authors     = ["Josh Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{The protoplasm client}
+  s.description = %q{The protoplasm client.}
+
+  s.rubyforge_project = "protoplasm"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "beefcake", "~> 0.3.7"
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'minitest', "~> 2.6.1"
+end

data/protoplasm-server.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "protoplasm/version"
+
+Gem::Specification.new do |s|
+  s.name        = "protoplasm-server"
+  s.version     = Protoplasm::VERSION
+  s.authors     = ["Josh Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{The protoplasm server}
+  s.description = %q{The protoplasm server.}
+
+  s.rubyforge_project = "protoplasm"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "eventmachine"
+  s.add_dependency "beefcake", "~> 0.3.7"
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'minitest', "~> 2.6.1"
+  
+end

data/test/protoplasm_test.rb

@@ -0,0 +1,46 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe "Protoplasm test server" do
+  it "should ping" do
+    with_proto_server(ProtoplasmTest::EMServer) do |port|
+      client = ProtoplasmTest::Client.new('127.0.0.1', port)
+      client.ping
+      pass
+    end
+  end
+
+  it "should upcase" do
+    with_proto_server(ProtoplasmTest::EMServer) do |port|
+      client = ProtoplasmTest::Client.new('127.0.0.1', port)
+      assert_equal "LOWER", client.upcase('lower')
+    end
+  end
+
+  it "should give you even numbers" do
+    with_proto_server(ProtoplasmTest::EMServer) do |port|
+      client = ProtoplasmTest::Client.new('127.0.0.1', port)
+      nums = []
+      client.evens(10) do |resp|
+        nums << resp
+      end
+      assert_equal [2, 4, 6, 8], nums
+    end
+  end
+
+  it "should allow multiple calls" do
+    with_proto_server(ProtoplasmTest::EMServer) do |port|
+      client = ProtoplasmTest::Client.new('127.0.0.1', port)
+      client.ping
+      assert_equal "LOWER", client.upcase('lower')
+      assert_equal "UPPER", client.upcase('upper')
+      nums = []
+      client.evens(10) do |resp|
+        nums << resp
+      end
+      assert_equal [2, 4, 6, 8], nums
+      client.ping
+      assert_equal "LOWER", client.upcase('lower')
+    end
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,118 @@
+require 'rubygems'
+require 'minitest/autorun'
+require 'protoplasm'
+require 'timeout'
+
+class ProtoplasmTest
+  module Types
+    include Protoplasm::Types
+
+    class PingCommand
+      include Beefcake::Message
+    end
+
+    class UpcaseCommand
+      include Beefcake::Message
+      required :word, :string, 1
+    end
+
+    class EvenCommand
+      include Beefcake::Message
+      required :top, :uint32, 1
+    end
+
+    class UpcaseResponse
+      include Beefcake::Message
+      required :response, :string, 1
+    end
+
+    class EvenResponse
+      include Beefcake::Message
+      required :num, :uint32, 1
+    end
+
+    class Command
+      include Beefcake::Message
+      module Type
+        PING   = 1
+        UPCASE = 2
+        EVEN   = 3
+      end
+      required :type,           Type,          1
+      optional :ping_command,   PingCommand,   2
+      optional :upcase_command, UpcaseCommand, 3
+      optional :even_command,   EvenCommand,   4
+    end
+
+    request_class Command
+    request_type_field :type
+    rpc_map Command::Type::PING,   :ping_command,   nil
+    rpc_map Command::Type::UPCASE, :upcase_command, UpcaseResponse
+    rpc_map Command::Type::EVEN,   :even_command,   EvenResponse,  :streaming => true
+  end
+
+  class EMServer < Protoplasm::EMServer
+    def process_upcase_command(cmd)
+      send_response(:response => cmd.word.upcase)
+    end
+
+    def process_even_command(cmd)
+      spit_out_even(1, cmd.top)
+    end
+
+    def process_ping_command(cmd)
+      # no op
+    end
+
+    def spit_out_even(cur, top)
+      EM.next_tick do
+        if cur == top
+          finish_streaming
+        else
+          if cur % 2 == 0
+            send_response(:num => cur)
+          end
+          spit_out_even(cur + 1, top)
+        end
+      end
+    end
+  end
+
+  class Client < Protoplasm::BlockingClient
+    def initialize(host, port)
+      super(Types, host, port)
+    end
+
+    def ping
+      send_request(:ping_command)
+    end
+
+    def upcase(word)
+      send_request(:upcase_command, :word => word).response
+    end
+
+    def evens(top)
+      send_request(:even_command, :top => top) { |resp| yield resp.num }
+    end
+  end
+end
+
+class MiniTest::Spec
+  def with_proto_server(cls)
+    port = 19866
+    pid = fork { cls.start(ProtoplasmTest::Types, port) }
+    begin
+      Timeout.timeout(10.0) {
+        begin
+          TCPSocket.open("127.0.0.1", port).close
+        rescue
+          sleep(0.1)
+          retry
+        end
+      }
+      yield port
+    ensure
+      Process.kill("INT", pid) if pid
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: protoplasm-client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Josh Hull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-21 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: beefcake
+  requirement: &70270602546480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.7
+  type: :runtime
+  prerelease: false
+  version_requirements: *70270602546480
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70270602545980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70270602545980
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70270602545400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.6.1
+  type: :development
+  prerelease: false
+  version_requirements: *70270602545400
+description: The protoplasm client.
+email:
+- joshbuddy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/protoplasm.rb
+- lib/protoplasm/client/blocking_client.rb
+- lib/protoplasm/server/em_server.rb
+- lib/protoplasm/types/types.rb
+- lib/protoplasm/version.rb
+- protoplasm-client.gemspec
+- protoplasm-server.gemspec
+- test/protoplasm_test.rb
+- test/test_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3078516638908246795
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3078516638908246795
+requirements: []
+rubyforge_project: protoplasm
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: The protoplasm client
+test_files:
+- test/protoplasm_test.rb
+- test/test_helper.rb