joonty/chain-reactor

= Chain Reactor

{<img src="https://travis-ci.org/joonty/chain-reactor.png?branch=master" alt="Build Status" />}[https://travis-ci.org/joonty/chain-reactor]
{<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/joonty/chain-reactor]

Chain Reactor is a simple server that waits for incoming connections, then kicks off some code when one is made. Clients are locked down by IP address, so you will only recieve connections from known clients. Also, data can be passed via JSON, XML, or anything you like.

The "reactions" are written in ruby code, like this:

    react_to '192.168.0.1' do |data|
      puts "Hello, 192.168.0.1, I'm going to do something now!"
      puts data.inspect  #=> Prints a hash
    end

It really is that easy. Also, you can respond to multiple clients with the same code block:

    react_to ['192.168.0.1','192.168.0.2'] do |data|
      puts "Hello, I'm going to do something now!"
    end

It can be run as a daemon, multithreaded (each client connection in a new thread), and bind to different addresses and ports.

== Why?

This project started as a way of notifying other machines about builds happening on Jenkins, our continuous integration server. A chain reactor server would be sitting, listening for connections. When a build fails or passes on Jenkins, it lets the chain reactor server(s) know, pushing the build data. The chain reactor server then does what it likes, and the Jenkins server doesn't need to know.

I'm sure this has plenty of other uses, but it works great with continuous integration set-ups.

== Installation

This can be installed through ruby gems:

    $ gem install chain-reactor

== Usage

Chain reactor comes with two command line tools, <tt>chain-reactor</tt> (the server) and <tt>chain-reactor-client</tt> (I think you can guess).

A chain file is required to run the server, as this specifies which clients to accept and what to do. Fortunately, it's easy to create a template:

    $ chain-reactor template > Chainfile.rb

Open it up and edit it to your liking. You might want to test it locally first, i.e. only react to 127.0.0.1 addresses. In one terminal, run:

    $ chain-reactor start Chainfile.rb --ontop

The --ontop option stops it from running as a daemon, making it easier to see what's happening. By default, the chain reactor server runs on port 1987, but that's configurable if you want to change it. In another terminal, run the client with:

    $ chain-reactor-client --address 127.0.0.1

Follow the instructions by adding key/value pair data to send to the server, then watch it react!

For more information on configuration, take a look at the wiki.

== Contributing

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