#Bouncer Bouncer is a simple router that uses MDNS and substack's bouncy to magically discover your apps and services to hit and fallback when neccessary.

##Install ###Prereqs For bouncy to be useful, you need to redirect a wildcard subdomain to localhost (*.dev.local for example). There are lots of methods to do this, but here is one way for OSX.

(shamelessly borrowed from http://onemoredigit.com/post/2155404559/wildcard-etc-hosts-an-alternative)

1. install dnsmasq

brew install dnsmasq

2. copy the example config

cp /usr/local/Cellar/dnsmasq/2.55/dnsmasq.conf.example /usr/local/etc/dnsmasq.conf

3. edit dnsmasq.conf to include the following

address=/com.local/127.0.0.1
listen-address=127.0.0.1

where "com.local" is the domain you want to redirect on, I use dev.local 4. (optional) Add the dnsmasq launchd config (provided by homebrew) to your system. Homebrew tells you how to do this.

###Installation

1. install it

npm install -g bouncer

2. Advertise your services (see below)
3. run bouncer

bouncer -c /path/to/conf.json

NOTE: defaults to ~/.bouncer.json if no config is passed

See below for config info

##Advertising services Bouncer relies on MDNS (aka. Bounjour, ZeroConf) to discover your services, in order for this to work however, you must create and advertisement for that service

app.js

var advertise = require('bouncer').advertise
...
var options = {secret: "cheesecake"}
app.listen(PORT, advertise("service_name", PORT, options))

See below for list of options

##Config Bouncer uses a json config file to define a secret, a list of services with fallbacks, and other options

sample_config.json (obvs without the comments!)

  // port to listen on
  "port" : 8000,
  // secret to use (match with your advertisement)
  "secret" : "mysecret",
  // OPTIONAL - key used to encrypt
  "key": "123456789123",
  // OPTIONAL - a fallback if no corresponding service is found
  "globalFallback" : "http://mydomain.com",
  // only bind with local instances of the service, default to false
  "localOnly": false,
  // a hash of service names and the fallback url to use
  "services" : {
    "service1" : "service1.mydomain.com",
    "service2" : "service2.mydomain.com",
  }

###Advertise the advertise options hash taskes a secret and a key, match to above

##API If you want to use Bouncer programatically, you can.

var Bouncer = require('bouncer').Bouncer
var bouncer = new Bouncer(opts)
bouncer.start()

opts takes all the same options as the json config and also a few functions

onServiceUp(mdnsRecord) - fired when a service is registered

onServiceDown(mdnsRecord) - fired when a service is removed

onGlobalFault(request, bouncyInstance, serviceName) - handle global faults

onServiceFault(request, bouncyInstance, serverObj) - handle faults for an individual services, serverObj is {name: "service_name", hosts; [mdnsRecord]}

verifyHost(mdnsRecrd) - return true if you want to accept the service