AndSon

AndSon is a simple Sanford client for Ruby. It provides an API for calling services and handling responses. It uses Sanford::Protocol to communicate with Sanford servers.

# create a client
client = AndSon.new('127.0.0.1', 8000)

# call a service and get its response data:
user_data = client.call('get_user_v1', {:user_name => 'joetest'})

To call a service, you first need a client to make the calls. You define clients by specifying the host's ip address and port.

Once you have your client defined, make service calls using the call method. It will return any response data and raise an exception if anything goes wrong.

By default, all requests timeout after 60s. You can override this globally using the ANDSON_TIMEOUT env var. You can override this global timeout on a per-call basis by chaining in the timeout method.

# timeout this request after 10 seconds
client.timeout(10).call('get_user', {:user_name => 'joetest'})

When a request times out, a Sanford::Protocol::TimeoutError is raised:

begin
  client.timeout(10).call('get_user', {:user_name => 'joetest'})
rescue Sanford::Protocol::TimeoutError => err
  puts "timeout - so sad :("
end

Similarly to timeouts, all requests default their params to an empty Hash ({}). This can be overriden using the params method.

# add an API key to all requests made by this client, to authorize our client
client.params({ 'api_key' => 12345 }).call('get_user', {:user_name => 'joetest'})

One thing to be aware of, AndSon has limited ability to 'merge' or 'append' params. For example:

# raises an exception, can't merge a string on to a hash
client.params({ 'api_key' => 12345 }).call('get_user', 'joetest')

Be aware of this when setting default params and passing additional params with the call method. In general, it's recommended to use ruby's Hash for the best results.

AndSon raises exceptions when a call responds with a 4xx or 5xx response code (see Sanford Status Codes for more on response codes):

• 400: BadRequestError < ClientError
• 404: NotFoundError < ClientError
• 4xx: ClientError < RequestError
• 5xx: ServerError < RequestError

client.call('some_unknown_service')   #=> NotFoundError...

Each exception knows about the response that raised it:

begin
  client.call('some_unknown_service')
rescue AndSon::NotFoundError => err
  err.response       #=> AndSon::Response ...
  err.response.code  #=> 404
end

If you call a service and pass it a block, no exceptions will be raised and the call will yield its response to the block. The call will return the return value of the block.

user = client.call('get_user', { :user_name => 'joetest' }) do |response|
  if response.code == 200
    User.new(response.data)
  else
    NullUser.new
  end
end

For more details about the response object, see sanford-protocol.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request