Nervion

A minimalistic Ruby client for the Public Streams of Twitter Streaming API.

Add this line to your application's Gemfile:

gem 'nervion'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nervion

Nervion's API has a static look. Given that Twitter only allows one connection per client to the Public Streams there is no need for you to build and handle a Nervion::Client. Nervion does that for you. You only need to set up the authentication and call the endpoint you are interested in.

Nervion mimics the endpoints provided by the Twitter Stream API through the following methods:

• follow
• sample
• firehose notice that the firehose support hasn't been tested against the actual API since it requires a level of access I don't have. If you were able to verify that it works, please, let me know

Checkout the docs of the endpoints to know what tweets you can query the Streaming API for and what parameters you have to provide to do so. You can specify any of the parameters supported by the endpoints by passing them as named parameters to the provided methods:

# This is tracking every tweet that includes the string "madrid" OR any tweet
# that is geo-located in Madrid.
Nervion.filter(track: 'madrid', locations: '40.364,-3.760,40.365,-3.609') do |message|
  # do something with the message
end

If the API adds support for more parameters in the future they will be supported straight away since Nervion does no work on them: they are just submitted to Twitter.

Since Twitter plans to remove support for basic auth eventually, Nervion only supports OAuth authentication.

You can provide the tokens and secrets in a configuration flavour:

Nervion.configure do |config|
  config.consumer_key        = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  config.consumer_secret     = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  config.access_token        = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  config.access_token_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
end

Nervion will parse the JSON returned by twitter for you. It uses Yajl as JSON parser for its out of the box support for JSON streams.

The hash keys are symbolized in the process of parsing. You will always have to use symbols to fetch data in the callbacks.

Nervion provides three callbacks:

• Message callback: called when message is received and parsed
• HTTP error callback: called when Twitter responds with a status above 200
• Network error callback: called when the connection to the stream is lost

You must setup a callback that acts on all the received messages by simply passing in a block to the API call you are making:

Nervion.sample { |message| puts message[:text] if message.has_key? :text }

Be aware that every message type will trigger this callback. Keep this in mind when querying the hash.

The callback receives only one parameter: the hash with the symbolized keys resultant of the JSON parsing. You get to choose what to do with the hash: mash it before working with it or even wrap it in some object that specializes on querying the information that is relevant to you.

To know what keys to expect you should browse the Platform Objects Documentation and know the different message types .

This callback will be executed when the Streaming API sends a response with a status code above 200. After the callback has been executed a retry will be scheduled adhering to the connection Guidelines provided by twitter.

You can setup the callback like this:

Nervion.on_http_error do |status, body|
  puts "the status of the response was: #{status}"
  puts "the body of the response body was: #{body}"
end

Given that most of the HTTP errors are due to client configuration, if no callback is set, Nervion's default behaviour will be to output an error message to STDERR that contains both the status and the body of Twitter Streaming API's response.

This callback will be executed when the connection with the Twitter Stream API is unexpectedly closed.

Nervion.on_network_error do
  puts 'There was a connection error but Nervion will automatically reconnect'
end

Nervion will do nothing by default when network errors occur because it is unlikely that they are provoked by the client itself.

Callback setup can be chained like this:

Nervion.on_network_error do
  #do something about the error
end.on_http_error do |status, body|
  #do something about the error
end.sample do |status|
  #do something with the status
end

Nervion runs on the top of EventMachine. This means that you can take advantage of any of the features of the EventMachine ecosystem in your Nervion callbacks.

Nervion can be run insinde an instance of EventMachine that is already running or you can let Nervion handle the event loop for you.

With that purpose in mind Nervion provides a few handy methods:

The stop method will stop both the streaming and EventMachine.

  Nervion.stop

You can use close_stream to close the connection to the streaming API but keep EventMachine's event loop running.

  Nervion.close_stream

The running? method will allow you to check whether Nervion is already running or not, what, in the asyncronous land that EventMachine lives in, you may not be sure about.

  Nervion.running?

And remember do not block the event loop.

There are some features that are needed and that will be developed before the first release of the gem:

• Provide an HTTP error callback done!
• Provide a network error callback done!
• Adhere to the Twitter Connection guidelines done!
• Improve the DSL provided to setup Nervion to validate the client setup done!

Future features will be:

• Use a gzip compressed stream
• Be able to configure the client to skip parsing and yield bare Strings with the JSON of the streamed messages. The objective is to improve performance by parsing in other process.