Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/redding/and-son
Sanford client for Ruby
https://github.com/redding/and-son
ruby sanford tcp tcp-client
Last synced: about 9 hours ago
JSON representation
Sanford client for Ruby
- Host: GitHub
- URL: https://github.com/redding/and-son
- Owner: redding
- License: mit
- Created: 2012-11-15T14:49:39.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2021-01-09T05:20:14.000Z (almost 4 years ago)
- Last Synced: 2024-03-15T09:22:32.412Z (8 months ago)
- Topics: ruby, sanford, tcp, tcp-client
- Language: Ruby
- Homepage: https://github.com/redding/sanford-protocol
- Size: 94.7 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AndSon
AndSon is a simple Sanford client for Ruby. It provides an API for calling services and handling responses. It uses [Sanford::Protocol](https://github.com/redding/sanford-protocol) to communicate with Sanford servers.
## Usage
```ruby
# 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'})
```
## Calling Services
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.
### Timeouts
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.
```ruby
# 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:
```ruby
begin
client.timeout(10).call('get_user', {:user_name => 'joetest'})
rescue Sanford::Protocol::TimeoutError => err
puts "timeout - so sad :("
end
```
### Default Params
Similarly to timeouts, all requests default their params to an empty `Hash` (`{}`). This can be overriden using the `params` method.
```ruby
# 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:
```ruby
# 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.
### Exception Handling
AndSon raises exceptions when a call responds with a `4xx` or `5xx` response code (see [Sanford Status Codes](https://github.com/redding/sanford-protocol#status-codes) for more on response codes):
* `400`: `BadRequestError < ClientError`
* `404`: `NotFoundError < ClientError`
* `4xx`: `ClientError < RequestError`
* `5xx`: `ServerError < RequestError`
```ruby
client.call('some_unknown_service') #=> NotFoundError...
```
Each exception knows about the response that raised it:
```ruby
begin
client.call('some_unknown_service')
rescue AndSon::NotFoundError => err
err.response #=> AndSon::Response ...
err.response.code #=> 404
end
```
### Response Handling
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.
```ruby
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](https://github.com/redding/sanford-protocol#response).
## Contributing
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