protobuf 1.0.0 → 1.0.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    protobuf (1.0.0)
+    protobuf (1.0.1)
       eventmachine (~> 0.12.10)
 
 GEM

data/README.md

@@ -1,5 +1,4 @@
-protobuf
-========
+# protobuf
 
 Protobuf is an implementation of [Google's protocol buffers][google-pb] in ruby. It's a gem for managing 3 things:
 
@@ -9,85 +8,93 @@ Protobuf is an implementation of [Google's protocol buffers][google-pb] in ruby.
 
 So let's dive in and see how to work with all three.
 
-1. Compile `.proto` definitions to ruby
-=======================================
+## 1. Compile `.proto` definitions to ruby
 
 Protocol Buffers are great because they allow you to clearly define data storage or data transfer packets. Google officially supports Java, C++, and Python for compilation and usage. Let's make it ruby aware!
 
 Let's say you have a `defs.proto` file that defines a User message.
 
-    package mycompany;
-    message User {
-      required string first_name = 1;
-      required string last_name = 1;
-    }
+```
+package mycompany;
+message User {
+  required string first_name = 1;
+  required string last_name = 1;
+}
 
 Now let's compile that definition to ruby:
 
-    $ rprotoc defs.proto -o ./lib
+$ rprotoc defs.proto -o ./lib
+```
 
 The previous line will take whatever is defined in defs.proto and output ruby classes to the `./lib` directory, obeying the package directive. Assuming that's all defs.proto had defined, `./lib` should now look like this:
 
-    - lib
-      |- mycompany
-          |- defs.pb.rb
+```
+- lib
+  |- mycompany
+      |- defs.pb.rb
+```
 
 And `defs.pb.rb` should look like this:
 
-    module Mycompany
-      class User
-        optional :string, :first_name, 1
-        optional :string, :last_name, 2
-      end
-    end
+```ruby
+module Mycompany
+  class User
+    optional :string, :first_name, 1
+    optional :string, :last_name, 2
+  end
+end
+```
 
 You can then use that class just like normal:
 
-    require 'lib/mycompany/user.pb'
-    
-    # dot notation reading/writing fields
-    user = Mycompany::User.new
-    user.first_name = "Lloyd"
-    user.last_name = "Christmas"
-    user.first_name     # => "Lloyd"
-    
-    # or pass in the fields as a hash to the initializer
-    user = Mycompany::User.new :first_name => "Lloyd", :last_name => "Christmas"
-    user.first_name     # => Lloyd
-    user.last_name     # => Christmas
+```ruby
+require 'lib/mycompany/user.pb'
 
-------------------
+# dot notation reading/writing fields
+user = Mycompany::User.new
+user.first_name = "Lloyd"
+user.last_name = "Christmas"
+user.first_name     # => "Lloyd"
 
-2. RPC
-======
+# or pass in the fields as a hash to the initializer
+user = Mycompany::User.new :first_name => "Lloyd", :last_name => "Christmas"
+user.first_name     # => Lloyd
+user.last_name     # => Christmas
+```
+
+## 2. RPC
 
 RPC is one of many technologies that tries to solve the problem of getting smaller pieces of data from one place to another. Many will argue for or against RPC and its usefulness, but I'm not going to do that here. Google's Protocol Buffers relies on RPC and that's why you're here.
 
 Any discussion about RPC leads to a discussion about clients and servers and the remote procedures themselves. For our purposes, we'll talk about a `Client` (process that is calling the server/service), a `Service` (the remote procedure), and a `Server` (the process that manages one or more services). We'll start with the Service first.
 
-**Services**
+### Services
 
 Services are simply classes that have endpoint methods defined. Here's what one looks like in protobuf:
 
-    message UserRequest {
-      optional string email = 1;
-    }
-    message UserList {
-      repeated User users = 1;
-    }
-    service UserService {
-      rpc Find (UserRequest) returns (UserList);
-    }
+```
+message UserRequest {
+  optional string email = 1;
+}
+message UserList {
+  repeated User users = 1;
+}
+service UserService {
+  rpc Find (UserRequest) returns (UserList);
+}
+```
 
 And the equivalent ruby stub for the service (generated with `rprotoc`):
 
-    # lib/mycompany/user_service.rb
-    module Mycompany
-      class UserService < Protobuf::Rpc::Service
-        rpc :find, UserRequest, UserList
-      end
-    end
-    
+```ruby
+# lib/mycompany/user_service.rb
+module Mycompany
+  class UserService < Protobuf::Rpc::Service
+    rpc :find, UserRequest, UserList
+  end
+end
+```
+
 Recognize that the extra messages would actually have gone into the `defs.pb.rb` file while the service stub would receive it's own file at `user_service.rb`.
 
 **Important Note: The *stubbed* class here is a *stub*. You should not alter it directly in any way as it will break your definition. Read on to learn how to use this stub.**
@@ -96,23 +103,25 @@ Did you read the note above? Go read it. I'll wait.
 
 Ok, now that you have a compiled service stub, you'll want to require it from `lib` and implement the methods. You'll notice when you compile the stub there is a large comment at the top of the file. You can use this code comment to start your real implementation. Go ahead and copy it to your services directory (probably `app/services` if we're in rails).
 
-    # app/services/user_service.rb
-    require 'lib/mycompany/user_service'
-    module Mycompany
-      class UserService
-      
-        # request -> Mycompany::UserRequest
-        # response -> Mycompany::UserResponse
-        def find
-          # request.email will be the unpacked string that was sent by the client request
-          User.find_by_email(request.email).each do |user|
-            # must only use a proto instance of Mycompany::User when appending to the `users` field
-            response.users << user.to_proto
-          end
-        end
-        
+```ruby
+# app/services/user_service.rb
+require 'lib/mycompany/user_service'
+module Mycompany
+  class UserService
+  
+    # request -> Mycompany::UserRequest
+    # response -> Mycompany::UserResponse
+    def find
+      # request.email will be the unpacked string that was sent by the client request
+      User.find_by_email(request.email).each do |user|
+        # must only use a proto instance of Mycompany::User when appending to the `users` field
+        response.users << user.to_proto
       end
     end
+    
+  end
+end
+```
 
 Simply implement the instance method for the defined rpc. No other methods will be allowed in the class (even helpers or private methods). An implicit `request` and `response` object are provided for you, pre-instantiated, and in the case of the request, already are populated with the data that was sent by the client.
 
@@ -120,24 +129,29 @@ If you need to create your own response object (a valid case), be sure to assign
 
 Triggering an error from the service is simple:
 
-    #...
-    def find
-      if request.email.blank?
-        rpc_failed 'Unable to find user without an email'
-      else
-        # query/populate response
-      end
-    end
-    
+```ruby
+#...
+def find
+  if request.email.blank?
+    rpc_failed 'Unable to find user without an email'
+  else
+    # query/populate response
+  end
+end
+#...
+```
+
 This means that the client's `on_failure` callback will be invoked instead of the `on_success` callback. Read more below on client callbacks.
 
 I find it very convenient to use a CRUD-style interface when defining certain data services, though this is certainly not always the case.
 
-**Servers**
+### Servers
 
 A service is nothing without being hooked up to a socket. It's the nerdy kid waiting by the telephone for someone to call without knowing that the phone company disconnected their house. Sad and pathetic. So hook the phone lines!
 
-    $ rpc_server -o myserver.com -p 9939 -e production -l ./log/protobuf.log config/environment.rb
+```
+$ rpc_server -o myserver.com -p 9939 -e production -l ./log/protobuf.log config/environment.rb
+```
 
 The previous call will start an EventMachine server running on the given host and port which will load your application into memory. You certainly don't have to run rails or any other framework, just make sure you have some kind of file that will load your services all into memory. The server doesn't know where you put your code, so tell it.
 
@@ -145,63 +159,61 @@ Be aware that server needs to be able to translate the socket stream of bytes in
 
 Once the server starts, you should see it as a running process with `ps`. Sending a KILL, QUIT, or TERM signal to the pid will result in shutting the server down gracefully.
 
-    $ ps aux | grep rpc_server
-    1234 ... rpc_server myservice.com:9939
-    
-    $ kill -QUIT 1234
-    rpc_server shutdown
+```
+$ ps aux | grep rpc_server
+1234 ... rpc_server myservice.com:9939
 
-**Clients**
+$ kill -QUIT 1234
+rpc_server shutdown
+```
+
+### Clients
 
 A lot of work has gone into making the client calls simple and easy to use yet still powerful. Clients have a DSL that feels very ajax-ish, mostly because of the nature of EventMachine, but I also think it works quite well.
 
-    # require the defs from the shared gem/repo
-    require 'sharedgem/mycompany/user.pb'
-    require 'sharedgem/mycompany/user_service'
-    
-    # Create a request object for the method we are invoking
-    req = Mycompany::UserRequest.new(:email => 'jeff@gmail.com')
-    
-    # Use the UserService class to generate a client, invoke the rpc method
-    # while passing the request object
-    Mycompany::UserService.client.find(req) do |c|
-      # This block will be executed (registering the callbacks)
-      # before the request actualy occurs.
-      # the `c` param in this block is the `.client` object
-      # that is generated from the call above
-      
-      # Register a block for execution when the response
-      # is deemed successful from the service. Accepts
-      # the unpacked response as its only parameter
-      c.on_success do |response|
-        response.users.each do |u|
-          puts u.inspect
-        end
-      end
-      
-      # Register a block for execution when the response
-      # is deemed a failure. This can be either a client-side
-      # or server-side failure. The object passed the to the
-      # block has a `message` and a `code` attribute
-      # to aid in logging/diagnosing the failure.
-      c.on_failure do |err|
-        puts 'It failed: ' + err.message
-      end
+```ruby
+# require the defs from the shared gem/repo
+require 'sharedgem/mycompany/user.pb'
+require 'sharedgem/mycompany/user_service'
+
+# Create a request object for the method we are invoking
+req = Mycompany::UserRequest.new(:email => 'jeff@gmail.com')
+
+# Use the UserService class to generate a client, invoke the rpc method
+# while passing the request object
+Mycompany::UserService.client.find(req) do |c|
+  # This block will be executed (registering the callbacks)
+  # before the request actualy occurs.
+  # the `c` param in this block is the `.client` object
+  # that is generated from the call above
+  
+  # Register a block for execution when the response
+  # is deemed successful from the service. Accepts
+  # the unpacked response as its only parameter
+  c.on_success do |response|
+    response.users.each do |u|
+      puts u.inspect
     end
-
-Many different options can be passed to the `.client` call above (such as `:async => true` or `:timeout => 600`). See the `lib/protobuf/rpc/client.rb` and `lib/protobuf/rpc/service.rb` files for more documentation. It hsould be noted that the default behavior of `UserService.client` is to return a blocking client. The nature of using Client calls within an framework like Rails demands a blocking call if the response of a web request is dependent on data returned from the service.
-
----
-
-3. RPC Interop
-==============
+  end
+  
+  # Register a block for execution when the response
+  # is deemed a failure. This can be either a client-side
+  # or server-side failure. The object passed the to the
+  # block has a `message` and a `code` attribute
+  # to aid in logging/diagnosing the failure.
+  c.on_failure do |err|
+    puts 'It failed: ' + err.message
+  end
+end
+```
+
+Many different options can be passed to the `.client` call above (such as `:async => true` or `:timeout => 600`). See the `lib/protobuf/rpc/client.rb` and `lib/protobuf/rpc/service.rb` files for more documentation. It should be noted that the default behavior of `UserService.client` is to return a blocking client. The nature of using Client calls within a framework like Rails demands a blocking call if the response of a web request is dependent on data returned from the service.
+
+## 3. RPC Interop
 
 The main reason I wrote this gem was to provide a ruby implementation to google's protobuf that worked on the RPC layer with a Java Service layer that was already running [protobuf-socket-rpc][], the supported socket rpc library for protobuf from Google. The [old gem][] did not provide a very robust RPC implementation and it most certainly did not work with the Java stack.
 
----
-
-Accreditation & Caveats
-=======================
+## Accreditation & Caveats
 
 It must be noted a large amount of the code in this library was taken from the [ruby-protobuf][old gem] gem. Its authors and I were unable to reach a communication point to be able to merge all of my RPC updates in with their master. Unfortunately I just simply couldn't use their RPC code and so I've decided to diverge from their codeset. I take no credit whatsoever for the (de)serialization and `rprotoc` code generation original work, though I have modified it slightly to be more compliant with my understanding of the pb spec. I want to say thanks to the original devs for the good work they did to get me most of the way there. The code was initially diverged at their 0.4.0 version.
 

data/bin/rpc_server

@@ -95,8 +95,8 @@ begin
   end
   
   # Set the name of the process
-  $0 = 'rpc_server %s:%d' % [server.host, server.port]
-
+  $0 = 'rpc_server %s:%d %s' % [server.host, server.port, server.app]
+  
   # Require the given application file
   require server.app
   

data/bin/rprotoc

@@ -9,8 +9,10 @@ else
   gem 'protobuf'
 end
 require 'protobuf'
+require 'protobuf/version'
 require 'protobuf/compiler/compiler'
 
+::Version = Protobuf::VERSION
 
 options = {
   :proto_path => '.',
@@ -22,8 +24,6 @@ opts.on('-o', '--out <OUT_DIR>', 'Specify the directory in which Ruby source fil
 opts.on_tail('-v', '--version', 'Show version.'){ puts(opts.ver); exit }
 opts.on_tail('-h', '--help', 'Show this message.'){ puts(opts.help); exit }
 
-::Version = Protobuf::VERSION
-
 begin
   opts.order!
 rescue OptionParser::ParseError

data/examples/reading_a_message.rb

@@ -9,11 +9,11 @@ def list_people(address_book)
     puts "  E-mail: #{person.email}" unless person.email.empty?
     person.phone.each do |phone_number|
       print(case phone_number.type
-            when Tutorial::Person::PhoneType::MOBILE
+            when Tutorial::Person::PhoneType::MOBILE then
               '  Mobile phone #: '
-            when Tutorial::Person::PhoneType::HOME
+            when Tutorial::Person::PhoneType::HOME then
               '  Home phone #: '
-            when Tutorial::Person::PhoneType::WORK
+            when Tutorial::Person::PhoneType::WORK then
               '  Work phone #: '
             end)
       puts phone_number.number

data/examples/writing_a_message.rb

@@ -21,11 +21,11 @@ def prompt_for_address(person)
     print 'Is this a mobile, home, or work phone? '
     person.phone.last.type = 
       case type = STDIN.gets.strip
-      when 'mobile'
+      when 'mobile' then
         Tutorial::Person::PhoneType::MOBILE
-      when 'home'
+      when 'home' then
         Tutorial::Person::PhoneType::HOME
-      when 'work'
+      when 'work' then
         Tutorial::Person::PhoneType::WORK
       else
         puts 'Unknown phone type; leaving as default value.'

data/lib/protobuf.rb

@@ -1,3 +1,6 @@
+require 'eventmachine'
+require 'protobuf/ext/eventmachine'
+
 module Protobuf
 end
 

data/lib/protobuf/compiler/nodes.rb

@@ -264,7 +264,7 @@ require 'protobuf/message/extend'
         descriptor.type_name = @type.is_a?(Array) ? @type.join : @type.to_s
         @opts.each do |key, val|
           case key.to_sym
-          when :default
+          when :default then
             descriptor.default_value = val.to_s
           end
         end

data/lib/protobuf/compiler/proto_parser.rb

@@ -256,10 +256,10 @@ module Racc
         }
         if code
           case code
-          when 1 # yyerror
+          when 1 then # yyerror
             @racc_user_yyerror = true   # user_yyerror
             return -reduce_n
-          when 2 # yyaccept
+          when 2 then # yyaccept
             return shift_n
           else
             raise '[Racc Bug] unknown jump code'
@@ -278,12 +278,12 @@ module Racc
         # error
         #
         case @racc_error_status
-        when 0
+        when 0 then
           unless arg[21]    # user_yyerror
             nerr += 1
             on_error @racc_t, @racc_val, @racc_vstack
           end
-        when 3
+        when 3 then
           if @racc_t == 0   # is $
             throw :racc_end_parse, nil
           end
@@ -482,30 +482,30 @@ module_eval <<'..end lib/protobuf/compiler/proto.y modeval..id110d2bf917', 'lib/
   def scan
     until @scanner.eos?
       case
-      when match(/\s+/, /\/\/.*/)
+      when match(/\s+/, /\/\/.*/) then
         # skip
-      when match(/\/\*/)
+      when match(/\/\*/) then
         # C-like comment
         raise 'EOF inside block comment' until @scanner.scan_until(/\*\//)
-      when match(/(?:required|optional|repeated|import|package|option|message|extend|enum|service|rpc|returns|group|default|extensions|to|max|double|float|int32|int64|uint32|uint64|sint32|sint64|fixed32|fixed64|sfixed32|sfixed64|bool|string|bytes)\b/)
+      when match(/(?:required|optional|repeated|import|package|option|message|extend|enum|service|rpc|returns|group|default|extensions|to|max|double|float|int32|int64|uint32|uint64|sint32|sint64|fixed32|fixed64|sfixed32|sfixed64|bool|string|bytes)\b/) then
         yield [@token, @token.to_sym]
-      when match(/[+-]?\d*\.\d+([Ee][\+-]?\d+)?/)
+      when match(/[+-]?\d*\.\d+([Ee][\+-]?\d+)?/) then
         yield [:FLOAT_LITERAL, @token.to_f]
-      when match(/[+-]?[1-9]\d*(?!\.)/, /0(?![.xX0-9])/)
+      when match(/[+-]?[1-9]\d*(?!\.)/, /0(?![.xX0-9])/) then
         yield [:DEC_INTEGER, @token.to_i]
-      when match(/0[xX]([A-Fa-f0-9])+/)
+      when match(/0[xX]([A-Fa-f0-9])+/) then
         yield [:HEX_INTEGER, @token.to_i(0)]
-      when match(/0[0-7]+/)
+      when match(/0[0-7]+/) then
         yield [:OCT_INTEGER, @token.to_i(0)]
-      when match(/(true|false)\b/)
+      when match(/(true|false)\b/) then
         yield [:BOOLEAN_LITERAL, @token == 'true']
-      when match(/"(?:[^"\\]+|\\.)*"/, /'(?:[^'\\]+|\\.)*'/)
+      when match(/"(?:[^"\\]+|\\.)*"/, /'(?:[^'\\]+|\\.)*'/) then
         yield [:STRING_LITERAL, eval(@token)]
-      when match(/[a-zA-Z_]\w*/)
+      when match(/[a-zA-Z_]\w*/) then
         yield [:IDENT, @token.to_sym]
-      when match(/[A-Z]\w*/)
+      when match(/[A-Z]\w*/) then
         yield [:CAMEL_IDENT, @token.to_sym]
-      when match(/./)
+      when match(/./) then
         yield [@token, @token]
       else
         raise "parse error around #{@scanner.string[@scanner.pos, 32].inspect}"