protobuf 2.0.0 → 2.0.1

data/README.md

@@ -1,21 +1,23 @@
 # protobuf
 
-Protobuf is an implementation of [Google's protocol buffers][google-pb] in ruby. It's a gem for managing 3 things:
+***IMPORTANT: Those upgrading from version 1.4.2 to 2.0 should read the [UPGRADING.md](https://github.com/localshred/protobuf/blob/master/UPGRADING.md) notes***
 
-1. Compiling `.proto` definitions to ruby
-2. Provide a Socket-RPC mechanism for calling services
-3. Provide RPC interop between ruby and other protobuf-rpc aware implementations for different languages (e.g. [protobuf-socket-rpc][])
+Protobuf is an implementation of [Google's protocol buffers][google-pb] in ruby. We currently support version 2.4.0. It's a gem for managing 3 things:
+
+1. Generating ruby classes from `.proto` files.
+2. Provide an RPC mechanism for calling remote services.
+3. Provide RPC interop between ruby and other protobuf-rpc aware implementations for different languages (e.g. [protobuf-socket-rpc][]).
 
 So let's dive in and see how to work with all three.
 
-## 1. Compile `.proto` definitions to ruby
+## 1. Generating ruby classes from `.proto` files
 
 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;
+package foo;
 message User {
   required string first_name = 1;
   required string last_name = 1;
@@ -23,21 +25,23 @@ message User {
 
 Now let's compile that definition to ruby:
 
-$ rprotoc defs.proto -o ./lib
+$ rprotoc defs.proto --ruby_out ./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:
+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
+  |- foo
       |- defs.pb.rb
 ```
 
-And `defs.pb.rb` should look like this:
+The generated file `defs.pb.rb` should look something like this:
 
 ```ruby
-module Mycompany
+module Foo
+  class User < ::Protobuf::Message; end
+
   class User
     required :string, :first_name, 1
     required :string, :last_name, 2
@@ -45,26 +49,41 @@ module Mycompany
 end
 ```
 
-You can then use that class just like normal:
+_Note: The generator will pre-define all the classes empty and then re-open to apply the defined fields. This is an optomization to prevent recursive field errors._
+
+The generated class is now just a plain old ruby object and you can use it however you wish.
 
 ```ruby
-require 'lib/mycompany/user.pb'
+require 'lib/foo/user.pb'
 
 # dot notation reading/writing fields
-user = Mycompany::User.new
+user = Foo::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 = Foo::User.new :first_name => "Lloyd", :last_name => "Christmas"
 user.first_name     # => Lloyd
 user.last_name     # => Christmas
 ```
 
+### Message (de)serialization
+
+Every message object comes ready for serialization or deserialization. Use `serialize_to_string` to write out the byte-string for the message. Use `parse_from_string` on a new message instance to inflate the byte-string back to a message in ruby.
+
+```ruby
+user = Foo::User.new(:first_name => 'Bob')
+bytes = user.serialize_to_string
+puts bytes #=> binary representation of this message object
+
+inflated_user = Foo::User.new.parse_from_string(bytes)
+inflated_user == user #=> true
+```
+
 ## 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.
+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 provides support for Services with 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.
 
@@ -73,6 +92,7 @@ Any discussion about RPC leads to a discussion about clients and servers and the
 Services are simply classes that have endpoint methods defined. Here's what one looks like in protobuf:
 
 ```
+package foo;
 message UserRequest {
   optional string email = 1;
 }
@@ -87,47 +107,53 @@ service UserService {
 And the equivalent ruby stub for the service (generated with `rprotoc`):
 
 ```ruby
-# lib/mycompany/user_service.rb
-module Mycompany
-  class UserService < Protobuf::Rpc::Service
+# lib/foo/user.pb.rb
+module Foo
+  # UserRequest and UserList Class definitions not shown (see above for generated output of classes).
+
+  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.**
+**Important Note: The UserService class here is a *stub*. You should not provide your implementation in this generated file as subsequent generations will wipe out your implmentation. Read on to learn how to use this stub.**
 
 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).
+Ok, now that you have a generated service stub, you'll want to require it from `lib` and implement the methods. Create a service implementation file in your project. In rails I'd put this in `app/services/user_service.rb`.
 
 ```ruby
 # app/services/user_service.rb
-require 'lib/mycompany/user_service'
-module Mycompany
+require 'lib/foo/user.pb'
+
+# Reopen the class and provide the implementation for each rpc method defined.
+module Foo
   class UserService
-  
-    # request -> Mycompany::UserRequest
-    # response -> Mycompany::UserResponse
+
+    # request -> Foo::UserRequest
+    # response -> Foo::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
+        # must only use a proto instance of Foo::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.
+Simply implement the instance method for the defined rpc. You can provide any other methods in this class as helpers, but only those defined in the proto file will be callable by remote clients. Every request made by a client will provide a non-empty request of the defined type. The server creates a new service instance based on the request, so you should not be constrained to just the endpoint method. This is similar to rails controllers where only methods defined by the routes file are hooked up to HTTP requests, but it's very common to implement private methods the aid in code quality and simpilicity.
 
-If you need to create your own response object (a valid case), be sure to assign it back to the instance by using `self.response = your_response_obj`. The object you assign **MUST** be of the defined return type, in this case `Mycompany::UserList`. Any other type will result in an error.
+Every instance has a `request` and `response` object used for fulfilling the call, again, similar to a rails controller action. You should never attempt to modify the `request` object. The `response` object however should be modified or replaced entirely.  If you need to create your own response object (a valid case), simply use `respond_with(new_response)`. The returned object should conform to one of three properties:
 
-Triggering an error from the service is simple:
+1. Response should be of same type as defined by the rpc definition (in this case, `Foo::UserList`), or
+2. Response should be a hash. This hash will be used to construct an instance of the defined type and should therefore conform to the appropriate fields for that type.
+3. Response should respond to the `to_proto` method. The object returned by `to_proto` should be an instance of the defined response type.
+
+If at any time the implementation encounters an error, the client can be instructed of the error using `rpc_failed`:
 
 ```ruby
 #...
@@ -141,21 +167,19 @@ 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.
+This means that the client's `on_failure` callback will be invoked instead of the `on_success` callback. Read more below on client callbacks. One drawback to the `rpc_failed` approach is that it does not short-circuit the rest of the method. This means that you must explicitly return from the method if you do not wish the remainder to be executed.
 
 ### 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 -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.
+The previous call will start an Socket 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.
 
-Be aware that server needs to be able to translate the socket stream of bytes into an actual protobuf request object. If the definition for that request object aren't known to the server, you're going to have a long day getting this going. It's necessary to store all your definitions and their generated classes in a shared repository (read: gem) that both client and server have access to in their respective load paths.
+Be aware that the server needs to be able to translate the socket stream of bytes into an actual protobuf request object. If the definition for that request object aren't known to the server, you're going to have a long day getting this going. It's necessary to store all your definitions and their generated classes in a shared repository (read: gem) so that both client and server have access to the ruby classes in their respective load paths.
 
 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.
 
@@ -169,24 +193,24 @@ 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.
+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 ajaxy.
 
 ```ruby
 # require the defs from the shared gem/repo
-require 'sharedgem/mycompany/user.pb'
-require 'sharedgem/mycompany/user_service'
+require 'sharedgem/foo/user.pb'
 
 # Create a request object for the method we are invoking
-req = Mycompany::UserRequest.new(:email => 'jeff@gmail.com')
+req = Foo::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|
+# while passing the request object.
+# We could also simply pass a hash to find.
+Foo::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
@@ -195,7 +219,7 @@ Mycompany::UserService.client.find(req) do |c|
       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
@@ -207,22 +231,21 @@ Mycompany::UserService.client.find(req) do |c|
 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.
+Many different options can be passed to the `.client` call above (such as `:timeout => 600`). See the `lib/protobuf/rpc/client.rb` and `lib/protobuf/rpc/service.rb` files for more documentation.
 
 ## 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.
+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. Other ruby protobuf implementations I've used did not provide this kind of support.
 
 ## 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.
+It must be noted that this gem was started originally as a fork of 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 forked the code. Myself and others have significantly changed the internals of the gem, including the rpc implementation, the message/field implementation, and the compiler implementation. These changes were made to address glaring performance and quality issues in the code. The code was initially diverged at their 0.4.0 version.
 
 It should also be noted that there are many more features I haven't really shown here, so please let me know if you have any questions on usage or support for various features. Happy protobufing.
 
--- BJ Neilsen, [@localshred][], [rand9.com][]
+-- BJ Neilsen, [@localshred][]
 
   [google-pb]: http://code.google.com/p/protobuf "Google Protocol Buffers"
   [protobuf-socket-rpc]: http://code.google.com/p/protobuf-socket-rpc/ "Google's official Socket-RPC library for protobuf"
   [old gem]: https://github.com/macks/ruby-protobuf "Macks ruby-protobuf on github"
   [@localshred]: http://twitter.com/localshred "Follow on twitter @localshred"
-  [rand9.com]: http://rand9.com "Blog"

data/UPGRADING.md

@@ -0,0 +1,60 @@
+# Upgrading from 1.X to 2.0
+
+I'm sure I'm missing quite a few of the smaller changes that have been made, but here is a list of changes that should affect any external programs or applications using `protobuf`.
+
+## `rprotoc` changes
+
+* New option `--ruby_out` to specify the output directory to place generated ruby files. If not provided, ruby code will not be generated.
+* Extends `libprotoc` to hook in directly to google's provided compiler mechanism.
+* Removed all previous compiler code including the racc parser, node visitors, etc.
+* See `protoc --help` for default options.
+
+## `rprotoc` generated files changes
+
+* Import `require`s now occur outside of any module or class declaration which solves ruby vm warnings previously seen.
+* Empty inherited Message and Enum classes are pre-defined in the file, then reopened and their fields applied. This solves the issue of recursive field dependencies of two or more types in the same file.
+* Generated DSL lines for message fields include the fully qualified name of the type (e.g. optional `::Protobuf::Field::StringField`, :name, 1)
+* Support for any combination of `packed`, `deprecated`, and `default` as options to pass to a field definition.
+* Services are now generated in the corresponding `.pb.rb` file instead of their own `*_service.rb` files as before.
+
+## `rpc_server` changes
+
+* Removed `--env` option. The running application or program is solely in charge of ensuring it's environment is properly loaded.
+* Removed reading of `PB_CLIENT_TYPE`, `PB_SERVER_TYPE` environment variables. Should use mode switches or custom requires (see below) instead.
+* Removed `--client_socket` in favor of using mode switches. This also means client calls made by the `rpc_server` will run as the same connector type as the given mode (socket, zmq, or evented).
+* Removed `--pre-cache-definitions` switch in favor of always pre-caching for performance.
+* Removed `--gc-pause-serialization` since using `--gc-pause-request` in conjunction was redundant.
+* Removed `--client-type` in favor of mode switches.
+* Removed `--server-type` in favor of mode switches.
+* Added mode switch `--evented`.
+* Added `--threads` to specify number of ZMQ Worker threads to use. Ignored if mode is not zmq.
+* Added `--print-deprecation-warnings` switch to tell the server whether or not to print deprecation warnings on field usage. Enabled by default.
+* See `rpc_server help start` for all options and usage. Note: the `start` task is the default and not necessary when running the `rpc_server`.
+
+## Message changes
+
+* `Message#get_field` usage should now specify either `Message#get_field_by_name` or `Message#get_field_by_tag`, depending on your lookup criteria.
+* Support for STDERR output when accessing a message field which has been defined as `[deprecated=true]`. Deprecated warnings can be skipped by running your application or program with `PB_IGNORE_DEPRECATIONS=1`.
+* Significant internal refactoring which provides huge boosts in speed and efficiency both in accessing/writing Message field values, as well as serialization and deserialization routines.
+* Refactor `Message#to_hash` to delegate hash representations to the field values, simply collecting the display values and returning a hash of fields that are set. This also affects `to_json` output.
+
+## Enum changes
+
+* Add `Enum.fetch` class method to polymorphically retrieve an `EnumValue` object.
+* Add `Enum.value_by_name` to retrieve the corresponding `EnumValue` to the given symbol name.
+* Add `Enum.enum_by_value` to retrieve the corresponding `EnumValue` to the given integer value.
+
+## RPC Service changes
+
+* `async_responder` paradigm is no longer supported.
+* `self.response=` paradigm should be converted to using `respond_with(object)`.
+* Significant internal changes that should not bleed beyond the API but which make maintaining the code much easier.
+
+## RPC Client changes
+
+* In the absence of `PB_CLIENT_TYPE` environment var, you should be requiring the specific connector type specifically. For instance, if you wish to run in zmq mode for client requests, update your Gemfile: `gem 'protobuf', :require => 'protobuf/zmq'`.
+* `:async` option on client calls is no longer recognized.
+
+##  Other changes
+
+* Moved files out of `lib/protobuf/common` folder into `lib/protobuf`. Files affected are logger, wire_type, util. The only update would need to be the require path to these files since the modules were always `Protobuf::{TYPE}`.

data/lib/protobuf/enum.rb

@@ -32,7 +32,7 @@ module Protobuf
     end
 
     def self.name_by_value(value)
-      @names[value]
+      value.nil? ? nil : @names[value]
     end
 
     def self.valid_tag?(tag)

data/lib/protobuf/field.rb

@@ -24,25 +24,25 @@ require 'protobuf/field/extension_fields'
 module Protobuf
   module Field
     PREDEFINED_TYPES = [
-      ::Protobuf::Field::DoubleField,   
+      ::Protobuf::Field::DoubleField,
       ::Protobuf::Field::FloatField,
-      ::Protobuf::Field::Int32Field,    
+      ::Protobuf::Field::Int32Field,
       ::Protobuf::Field::Int64Field,
-      ::Protobuf::Field::Uint32Field,   
+      ::Protobuf::Field::Uint32Field,
       ::Protobuf::Field::Uint64Field,
-      ::Protobuf::Field::Sint32Field,   
+      ::Protobuf::Field::Sint32Field,
       ::Protobuf::Field::Sint64Field,
       ::Protobuf::Field::Fixed32Field,
       ::Protobuf::Field::Fixed64Field,
-      ::Protobuf::Field::Sfixed32Field, 
+      ::Protobuf::Field::Sfixed32Field,
       ::Protobuf::Field::Sfixed64Field,
-      ::Protobuf::Field::StringField,   
+      ::Protobuf::Field::StringField,
       ::Protobuf::Field::BytesField,
       ::Protobuf::Field::BoolField
     ].freeze
 
     def self.build(message_class, rule, type, name, tag, options={})
-      field_class = type_message_or_enum(type) 
+      field_class = type_message_or_enum(type)
       field_class.new(message_class, rule, type, name, tag, options)
     end
 

data/lib/protobuf/field/base_field.rb

@@ -184,6 +184,7 @@ module Protobuf
         field = self
         @message_class.class_eval do
           define_method(field.getter_method_name) do
+            field.warn_if_deprecated
             @values[field.name] ||= ::Protobuf::Field::FieldArray.new(field)
           end
         end

data/lib/protobuf/message.rb

@@ -6,6 +6,9 @@ require 'protobuf/message/encoder'
 
 module Protobuf
   class Message
+
+    class FieldNotDefinedError < StandardError; end
+
     STRING_ENCODING = "ASCII-8BIT".freeze
 
     def self.all_fields
@@ -80,16 +83,25 @@ module Protobuf
     def self.get_field_by_name(name)
       # Check if the name has been used before, if not then set it to the sym value
       fields[field_name_to_tag[name]]
+    rescue TypeError => e
+      name = 'nil' if name.nil?
+      raise FieldNotDefinedError.new("Field '#{name}' is not defined on message '#{self.name}'")
     end
 
     # Find a field object by +tag+ number.
     def self.get_field_by_tag(tag)
       fields[tag]
+    rescue TypeError => e
+      tag = tag.nil? ? 'nil' : tag.to_s
+      raise FieldNotDefinedError.new("Tag '#{tag}' does not reference a message field for '#{self.name}'")
     end
 
     def self.get_ext_field_by_name(name)
       # Check if the name has been used before, if not then set it to the sym value
       extension_fields[extension_field_name_to_tag[name]]
+    rescue TypeError => e
+      name = 'nil' if name.nil?
+      raise FieldNotDefinedError.new("Field '#{name}' is not defined on message '#{self.name}'")
     end
 
     def self.get_ext_field_by_tag(tag)

data/lib/protobuf/rpc/server.rb

@@ -78,8 +78,9 @@ module Protobuf
       def send_response
         log_debug { sign_message("Sending response to client: #{@response.inspect}") }
         send_data
-        @stats.stop && log_info { @stats.to_s }
       ensure
+        @stats.stop
+        log_info { @stats.to_s }
         enable_gc!
       end
     end

data/lib/protobuf/rpc/service_dispatcher.rb

@@ -53,12 +53,15 @@ module Protobuf
       def coerced_response
         candidate = service.response
 
-        if candidate.is_a?(Hash)
-          candidate = definition.response_type.new(candidate)
-        elsif candidate.respond_to?(:to_hash)
-          candidate = definition.response_type.new(candidate.to_hash)
-        elsif candidate.respond_to?(:to_proto)
+        case
+        when candidate.is_a?(::Protobuf::Message) then
+          # no-op
+        when candidate.respond_to?(:to_proto) then
           candidate = candidate.to_proto
+        when candidate.respond_to?(:to_proto_hash) then
+          candidate = definition.response_type.new(candidate.to_proto_hash)
+        when candidate.respond_to?(:to_hash) then
+          candidate = definition.response_type.new(candidate.to_hash)
         end
 
         candidate

data/lib/protobuf/rpc/stat.rb

@@ -69,7 +69,7 @@ module Protobuf
 
       def to_s
         [
-          server? ? "[SRV-#{self.class}]" : "[CLT-#{self.class}]",
+          server? ? "[SRV]" : "[CLT]",
           rpc,
           elapsed_time,
           sizes,

data/lib/protobuf/version.rb

@@ -1,4 +1,4 @@
 module Protobuf
-  VERSION = '2.0.0'
+  VERSION = '2.0.1'
   PROTOC_VERSION = '2.4.1'
 end

data/spec/lib/protobuf/enum_spec.rb

@@ -51,6 +51,12 @@ describe Protobuf::Enum do
     it 'gets the name of the enum corresponding to the given value (tag)' do
       Test::EnumTestType.name_by_value(tag).should eq name
     end
+
+    context 'when given name is nil' do
+      it 'returns a nil' do
+        Test::EnumTestType.name_by_value(nil).should be_nil
+      end
+    end
   end
 
   describe '.valid_tag?' do

data/spec/lib/protobuf/message_spec.rb

@@ -47,4 +47,72 @@ describe Protobuf::Message do
     its(:to_json) { should eq '{"name":"Test Name","active":false}' }
   end
 
+  describe '#get_field_by_name' do
+    subject do
+      ::Test::Resource.new({ :name => 'Test Name', :date_created => Time.now.to_i })
+    end
+
+    context 'when name is a valid field' do
+      let(:valid_field) { subject.get_field_by_name(:name) }
+      specify { valid_field.should be_a ::Protobuf::Field::StringField }
+      specify { valid_field.name.should eq :name }
+    end
+
+    context 'when name is not a valid field' do
+      specify do
+        expect {
+          subject.get_field_by_name(1)
+        }.to raise_error(::Protobuf::Message::FieldNotDefinedError, /.*1.*#{subject.class.name}/)
+      end
+
+      specify do
+        expect {
+          subject.get_field_by_name(:nothere)
+        }.to raise_error(::Protobuf::Message::FieldNotDefinedError, /.*nothere.*#{subject.class.name}/)
+      end
+
+      specify do
+        expect {
+          subject.get_field_by_name(nil)
+        }.to raise_error(::Protobuf::Message::FieldNotDefinedError, /.*nil.*#{subject.class.name}/)
+      end
+    end
+  end
+
+  describe '#get_ext_field_by_name' do
+    pending 'Need to get a proto compiled with extensions first'
+  end
+
+  describe '#get_field_by_tag' do
+    subject do
+      ::Test::Resource.new({ :name => 'Test Name', :date_created => Time.now.to_i })
+    end
+
+    context 'when tag references a valid field' do
+      let(:valid_field) { subject.get_field_by_tag(1) }
+      specify { valid_field.should be_a ::Protobuf::Field::StringField }
+      specify { valid_field.name.should eq :name }
+    end
+
+    context 'when tag does not reference a field' do
+      it 'returns nil' do
+        subject.get_field_by_tag(-1).should be_nil
+      end
+    end
+
+    context 'when tag is not numeric' do
+      specify do
+        expect {
+          subject.get_field_by_tag("not a number")
+        }.to raise_error(::Protobuf::Message::FieldNotDefinedError, /.*not a number.*#{subject.class.name}/)
+      end
+
+      specify do
+        expect {
+          subject.get_field_by_tag(nil)
+        }.to raise_error(::Protobuf::Message::FieldNotDefinedError, /.*nil.*#{subject.class.name}/)
+      end
+    end
+  end
+
 end

data/spec/spec_helper.rb

@@ -26,7 +26,9 @@ end
     unless ENV['NO_COMPILE_TEST_PROTOS']
       $stdout.puts 'Compiling test protos (use NO_COMPILE_TEST_PROTOS=1 to skip)'
       proto_path = File.expand_path("../support/", __FILE__)
-      %x{ rprotoc --proto_path=#{proto_path} --ruby_out=#{proto_path} #{File.join(proto_path, '**', '*.proto')} }
+      cmd = %Q{ rprotoc --proto_path=#{proto_path} --ruby_out=#{proto_path} #{File.join(proto_path, '**', '*.proto')} }
+      puts cmd
+      %x{#{cmd}}
     end
   end
 end

data/spec/support/test/enum.pb.rb

@@ -17,16 +17,18 @@ module Test
   ##
   # Enum Values
   #
-  ::Test::EnumTestType.define :ONE, 1
-  ::Test::EnumTestType.define :TWO, 2
-  
+  class EnumTestType
+    define :ONE, 1
+    define :TWO, 2
+  end
   
   ##
   # Message Fields
   #
-  ::Test::EnumTestMessage.optional(::Test::EnumTestType, :non_default_enum, 1)
-  ::Test::EnumTestMessage.optional(::Test::EnumTestType, :default_enum, 2, :default => ::Test::EnumTestType::ONE)
-  ::Test::EnumTestMessage.repeated(::Test::EnumTestType, :repeated_enums, 3)
-  
+  class EnumTestMessage
+    optional ::Test::EnumTestType, :non_default_enum, 1
+    optional ::Test::EnumTestType, :default_enum, 2, :default => ::Test::EnumTestType::ONE
+    repeated ::Test::EnumTestType, :repeated_enums, 3
+  end
   
 end

data/spec/support/test/resource.pb.rb

@@ -15,33 +15,40 @@ module Test
   #
   class ResourceFindRequest < ::Protobuf::Message; end
   class Resource < ::Protobuf::Message; end
+  class Extended < ::Protobuf::Message; end
   class Nested < ::Protobuf::Message; end
   
   ##
   # Enum Values
   #
-  ::Test::StatusType.define :PENDING, 0
-  ::Test::StatusType.define :ENABLED, 1
-  ::Test::StatusType.define :DISABLED, 2
-  ::Test::StatusType.define :DELETED, 3
-  
+  class StatusType
+    define :PENDING, 0
+    define :ENABLED, 1
+    define :DISABLED, 2
+    define :DELETED, 3
+  end
   
   ##
   # Message Fields
   #
-  ::Test::ResourceFindRequest.required(::Protobuf::Field::StringField, :name, 1)
-  ::Test::ResourceFindRequest.optional(::Protobuf::Field::BoolField, :active, 2)
-  
-  ::Test::Resource.required(::Protobuf::Field::StringField, :name, 1)
-  ::Test::Resource.optional(::Protobuf::Field::Int64Field, :date_created, 2)
-  ::Test::Resource.optional(::Test::StatusType, :status, 3)
-  ::Test::Resource.repeated(::Test::StatusType, :repeated_enum, 4)
+  class ResourceFindRequest
+    required ::Protobuf::Field::StringField, :name, 1
+    optional ::Protobuf::Field::BoolField, :active, 2
+  end
   
-  ::Test::Nested.optional(::Protobuf::Field::StringField, :name, 1)
-  ::Test::Nested.optional(::Test::Resource, :resource, 2)
-  ::Test::Nested.repeated(::Test::Resource, :multiple_resources, 3)
-  ::Test::Nested.optional(::Test::StatusType, :status, 4)
+  class Resource
+    required ::Protobuf::Field::StringField, :name, 1
+    optional ::Protobuf::Field::Int64Field, :date_created, 2
+    optional ::Test::StatusType, :status, 3
+    repeated ::Test::StatusType, :repeated_enum, 4
+  end
   
+  class Nested
+    optional ::Protobuf::Field::StringField, :name, 1
+    optional ::Test::Resource, :resource, 2
+    repeated ::Test::Resource, :multiple_resources, 3
+    optional ::Test::StatusType, :status, 4
+  end
   
   ##
   # Services

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protobuf
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-23 00:00:00.000000000Z
+date: 2012-10-29 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &2152084280 !ruby/object:Gem::Requirement
+  requirement: &2152132920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152084280
+  version_requirements: *2152132920
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &2152082200 !ruby/object:Gem::Requirement
+  requirement: &2152129180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152082200
+  version_requirements: *2152129180
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &2152079980 !ruby/object:Gem::Requirement
+  requirement: &2152127660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152079980
+  version_requirements: *2152127660
 - !ruby/object:Gem::Dependency
   name: thor
-  requirement: &2152079060 !ruby/object:Gem::Requirement
+  requirement: &2152126820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152079060
+  version_requirements: *2152126820
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &2152077380 !ruby/object:Gem::Requirement
+  requirement: &2152125000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152077380
+  version_requirements: *2152125000
 - !ruby/object:Gem::Dependency
   name: ffi-rzmq
-  requirement: &2152076200 !ruby/object:Gem::Requirement
+  requirement: &2152121980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +77,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152076200
+  version_requirements: *2152121980
 - !ruby/object:Gem::Dependency
   name: perftools.rb
-  requirement: &2152074580 !ruby/object:Gem::Requirement
+  requirement: &2152112840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,10 +88,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152074580
+  version_requirements: *2152112840
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &2152073400 !ruby/object:Gem::Requirement
+  requirement: &2152111420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -99,10 +99,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152073400
+  version_requirements: *2152111420
 - !ruby/object:Gem::Dependency
   name: pry-nav
-  requirement: &2152067360 !ruby/object:Gem::Requirement
+  requirement: &2152110580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -110,10 +110,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152067360
+  version_requirements: *2152110580
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2152066440 !ruby/object:Gem::Requirement
+  requirement: &2152109440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -121,10 +121,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152066440
+  version_requirements: *2152109440
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &2152065680 !ruby/object:Gem::Requirement
+  requirement: &2152108860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -132,10 +132,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152065680
+  version_requirements: *2152108860
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2152064960 !ruby/object:Gem::Requirement
+  requirement: &2152101880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -143,10 +143,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152064960
+  version_requirements: *2152101880
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2152063940 !ruby/object:Gem::Requirement
+  requirement: &2152101000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -154,10 +154,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152063940
+  version_requirements: *2152101000
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &2152062660 !ruby/object:Gem::Requirement
+  requirement: &2152100220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -165,7 +165,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152062660
+  version_requirements: *2152100220
 description: Google Protocol Buffers v2.4.1 Serialization and RPC implementation for
   Ruby.
 email:
@@ -183,6 +183,7 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- UPGRADING.md
 - bin/rpc_server
 - bin/rprotoc
 - examples/addressbook.pb.rb
@@ -443,7 +444,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1241353488378730897
+      hash: -2086976779931604579
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -452,7 +453,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1241353488378730897
+      hash: -2086976779931604579
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.15