protoplasm-blocking-client 0.1.0

data/.gitignore

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

data/Gemfile

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

data/README.md

@@ -0,0 +1,101 @@
+# 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 only one type of protobuf object (the request object). This object must have an enum and a series of optional command fields to allow it to send commands. Here is an example of how to create a request object type:
+
+```ruby
+class Command
+  include Beefcake::Message
+  module Type
+    PING   = 1
+    UPCASE = 2
+  end
+  required :type,           Type,          1
+  optional :ping_command,   PingCommand,   2
+  optional :upcase_command, UpcaseCommand, 3
+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,73 @@
+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["em_server:release_without_tagging"].invoke
+    Rake::Task["blocking_client:release_without_tagging"].invoke
+  end
+end
+
+desc "Install client & server (#{version})"
+task :install do
+  Rake::Task["em_server:install"].invoke
+  Rake::Task["blocking_client:install"].invoke
+end
+
+desc "Build client & server (#{version})"
+task :build do
+  Rake::Task["em_server:build"].invoke
+  Rake::Task["blocking_client:build"].invoke
+end
+
+namespace :em_server do
+  helper = Bundler::GemHelper.new(File.dirname(__FILE__), "protoplasm-em-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 :blocking_client do
+  helper = Bundler::GemHelper.new(File.dirname(__FILE__), "protoplasm-blocking-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,9 @@
+require "protoplasm/version"
+
+# Protoplasm 
+# This defines BlockingClient and EMServer.
+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,57 @@
+require 'socket'
+
+module Protoplasm
+  class BlockingClient
+    def self.for_types(types)
+      cls = Class.new(self)
+      cls.class_eval do
+        (class << self; self; end).send(:define_method, :_types) { types }
+      end
+      cls
+    end
+
+    private
+    def host_port
+      raise "Must be implemented by the client class"
+    end
+
+    def _socket
+      host, port = host_port
+      @_socket ||= TCPSocket.open(host, port)
+    end
+
+    def send_request(field, *args, &blk)
+      s = ''
+      type = self.class._types.request_type_for_field(field)
+      cmd_class = type.command_class.fields.values.find{|f| f.name == field}
+      cmd = self.class._types.request_class.new(self.class._types.request_type_field => type.type, type.field => cmd_class.type.new(*args))
+      cmd.encode(s)
+      socket = _socket
+      socket.write([0, s.size].pack("CQ"))
+      socket.write s
+      socket.flush
+      fetch_objects = true
+      obj = nil
+      while fetch_objects
+        response_code = socket.readpartial(1).unpack("C").first
+        case response_code
+        when Types::Response::NORMAL
+          fetch_objects = !type.void?
+          if fetch_objects
+            len_buf = ''
+            socket.readpartial(8 - len_buf.size, len_buf) while len_buf.size != 8
+            len = len_buf.unpack("Q").first
+            buf = ''
+            socket.readpartial(len - buf.size, buf) until buf.size == len
+            obj = type.response_class.decode(buf)
+            yield obj if block_given?
+          end
+          fetch_objects = false unless type.streaming?
+        when Types::Response::STOP_STREAMING
+          fetch_objects = false
+        end
+      end
+      obj
+    end
+  end
+end

data/lib/protoplasm/server/em_server.rb

@@ -0,0 +1,81 @@
+require 'eventmachine'
+
+module Protoplasm
+  class EMServer < EventMachine::Connection
+    def self.for_types(types)
+      cls = Class.new(self)
+      cls.class_eval do
+        (class << self; self; end).send(:define_method, :_types) { types }
+      end
+      cls
+    end
+
+
+    def self.start(port)
+      if EM.reactor_running?
+        EM::start_server("0.0.0.0", port, self) do |srv|
+          yield srv if block_given?
+        end
+      else
+        begin
+          EM.run do
+            start(port)
+          end
+        rescue Interrupt
+        end
+      end
+    end
+
+    def post_init
+      @_response_types = []
+      @data = ''
+    end
+
+    def receive_data(data)
+      @data << data
+      data_ready
+    end
+
+    def finish_streaming
+      @_response_types.shift
+      send_data [Types::Response::STOP_STREAMING].pack("C")
+    end
+
+    def send_void
+      @_response_types.shift
+      send_data [Types::Response::NORMAL].pack("C")
+    end
+
+    def data_ready
+      @control = @data.slice!(0, 1).unpack("C").first unless @control
+      case @control
+      when Types::Request::NORMAL
+        @size = @data.slice!(0, 8).unpack("Q").first unless @size
+        if @data.size >= @size
+          buf = @data.slice!(0, @size)
+          @size, @control = nil, nil
+          obj = self.class._types.request_class.decode(buf)
+          type = self.class._types.request_type_for_request(obj)
+          @_response_types << type
+          EM.next_tick do
+            send(:"process_#{type.field}", obj.send(type.field))
+          end
+          data_ready unless @data.empty?
+        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 [Types::Response::NORMAL, s.size].pack("CQ")
+      send_data s
+    end
+  end
+end

data/lib/protoplasm/types/types.rb

@@ -0,0 +1,62 @@
+require 'beefcake'
+
+module Protoplasm
+  module Types
+    module Request
+      NORMAL = 0
+    end
+
+    module Response
+      NORMAL         = 0
+      STOP_STREAMING = 10
+    end
+
+    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

data/lib/protoplasm/version.rb

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

data/protoplasm-blocking-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-blocking-client"
+  s.version     = Protoplasm::VERSION
+  s.authors     = ["Josh Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = "https://github.com/bazaarlabs/protoplasm"
+  s.summary     = %q{A blocking client for a Protoplasm server}
+  s.description = %q{A blocking client for a Protoplasm server.}
+
+  s.rubyforge_project = "protoplasm-blocking-client"
+
+  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-em-server.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "protoplasm/version"
+
+Gem::Specification.new do |s|
+  s.name        = "protoplasm-em-server"
+  s.version     = Protoplasm::VERSION
+  s.authors     = ["Josh Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = "https://github.com/bazaarlabs/protoplasm"
+  s.summary     = %q{A protoplasm server backed by EventMachine}
+  s.description = %q{A protoplasm server backed by EventMachine.}
+
+  s.rubyforge_project = "protoplasm-em-server"
+
+  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,122 @@
+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.for_types(Types)
+    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)
+      send_void
+    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.for_types(Types)
+    def initialize(host, port)
+      @host, @port = 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
+
+    def host_port
+      [@host, @port]
+    end
+  end
+end
+
+class MiniTest::Spec
+  def with_proto_server(cls)
+    port = 19866
+    pid = fork { cls.start(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-blocking-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Josh Hull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-29 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: beefcake
+  requirement: &70238713002280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.7
+  type: :runtime
+  prerelease: false
+  version_requirements: *70238713002280
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70238713001380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70238713001380
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70238713000320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.6.1
+  type: :development
+  prerelease: false
+  version_requirements: *70238713000320
+description: A blocking client for a Protoplasm server.
+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-blocking-client.gemspec
+- protoplasm-em-server.gemspec
+- test/protoplasm_test.rb
+- test/test_helper.rb
+homepage: https://github.com/bazaarlabs/protoplasm
+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: 380352482441046279
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 380352482441046279
+requirements: []
+rubyforge_project: protoplasm-blocking-client
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A blocking client for a Protoplasm server
+test_files:
+- test/protoplasm_test.rb
+- test/test_helper.rb