Clients

The client request DSL is AJAX-like and quite flexible, but also more verbose.

If you prefer an ActiveRecord-like DSL I highly recommend using ActiveRemote which was developed in conjunction with this library to make interacting with a remote service feel identical to using an ActiveRecord model. Seriously, it's wicked cool.

# require the defs from the shared gem/repo
require 'sharedgem/foo/user.pb'

# Create a request object for the method we are invoking
request = Foo::UserRequest.new(:email => 'jeff@gmail.com')

# Use the UserService class to generate a client, invoke the rpc method
# while passing the request object.
# We could also simply pass a hash to find.
#
Foo::UserService.client.find(request) do |c|
  # This block will be executed (registering the callbacks)
  # before the request actually occurs.
  # the `client` param in this block is the object
  # that is created by `Foo::UserService.client`.

  # Register a block for execution when the response
  # is deemed successful from the service. Accepts
  # the decoded response as its only parameter.
  #
  c.on_success do |response|
    # response is an instance of Foo::UserList
    response.users.each do |user|
      puts user.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 to the
  # block has a `message` and a `code` attribute
  # to aid in logging/diagnosing the failure.
  #
  c.on_failure do |error|
    puts 'It failed: ' + error.message
  end
end

Many different options can be passed to the .client call above (such as :host, :port, :timeout, etc). See the lib/protobuf/rpc/client.rbandlib/protobuf/rpc/service.rb` files for more documentation.