node-intlb

• index.js - dispatcher implementation
• lib/registry - registry implementations
• lib/balancers - balancer implementations

intlb is a business driven dispatcher/loadbalancer. Image you have many backends which have different states or data. You want to proxy the request on base of this data, finding just the backends in your pool which have a certain data-state, version etc.

##Features

• proxies requests on base of tags
• endpoints provide these tags via registry (different implementations possible)
• statsd-support for profiling and endpoint-utilization

###How does dispatching work in detail Endpoints are checked for status by one of the service registry implementations. The list of possible endpoints is then passed to one of the balancer implementations (ootb roundrobin and failover - second is default), which are responsible for choosing one final endpoint the request is dispatched to. Balancers send a HEAD request to verify the endpoint compatibility, providing the tag in the x-lb-match request header. Endpoints have to send a HTTP 200 if compatible, or pass HTTP 412 precondition failed if the endpoint does not accept the provided tag. This additional "endpoint verification" can be enabled/disabled in configuration.

###How does intlb know which tag to use? Tags can be provided statically via configuration, provided via REST or even set per request (providing the tag as http header x-lb-match)

###Usage Just instantiate Dispatcher and pass the configuration.

var d = new Dispatcher({
  //id (intlb if not specified)
  id:"mydispatcher",
  //used balancer implementation - roundrobin is default when not specified
  balancer:balancer, 
  //endpoint registry - default implementation is static, but your implementation can be zookeeper, redis etc.
  registry:registry,  statis-registry needs it)
  //node-statsd client instance to log utilization
  statsdclient:self.statsdclient, 
  //winston logging implementation (useful when you run intlb embedded in your application), if not specified will create its own winston instance
  logger: self.logger
});
d.run(3000,'0.0.0.0');

##Dispatcher Events and Statsd-Metrics intlb fires two events - one when a request is dispatched to an endpoint, one when the response comes back. When you provide a statsd-instance intlb will automatically provide metrics about the overall utilization as well as the utilization of each endpoint

###Events

   dispatcher.on('lb-enq',function(data /* endpoint, requestid */) {
     logger.info('request %s was dispatched to %s',requestid,endpoint.id);
   });
   dispatcher.on('lb-deq',function(data /* endpoint, requestid */) {
     logger.info('request %s finished',requestid);        
   });

###Statsd-Series intlb will provide some series telling about the overall and the endpoint utilization

• mydispatcher.currentrequests (using the dispatcher-id and telling about overall utilization) Its quite easy to implement per-request count/duration etc. yourself using the events above

##Additional Features ###lbtrace Providing a request-parameter lbtrace to get information about which endpoint was used

curl  -v localhost:3000/test/someurl?foo=bar&lbtrace=true

will set the following response-header (telling about that endpoint 1 got its first request)

x-lb-forwarded: endpoint1#1

###Dynamically balancer implementation In this case we use the failover balancer just for this request

curl  -v localhost:3000/test/someurl?foo=bar -H 'x-lb-balancer:failover'