skinnyJAX – an XHR wrapper

Need to send some AJAX requests without the help of a framework? Have no fear, skinnyJAX can help you out. In addition to the normal stuff, skinnyJAX requests can be configured with a pool of hosts for failover. Sweet!

I wrote skinnyJAX while working on Tapl.io – take it for a spin to see it in action! Let me know if it’s useful =)

Simple Usage

Setup Resource
Initialize skinnyJAX with target host. If your app calls to several different hosts you should init a unique skinnyJAX object for each one.

var jax = new skinnyJAX('http://domain.com/');

Submit A Request
A complete listing of request config options and callbacks is in the Advanced Usage section below.

jax.req({ endpoint: 'v1/something.json',			// endpoint path
	  params: { param1: value1, param2: value2 },		// [optional] request parameters
	  success: function(response) {				// success callback
		// success callback
	  }
	});

Response Object Attributes:
This object is passed to the request callbacks

response = {
	attempt: 1,						// number of retries
	data: {},						// if request is successful (null if not successful)
	http_code: 200,						// http status code
	method: 'get',						// request method
	time: 232,						// response time
	timed_out: false,					// boolean
	uri: 'http://domain.com/v1/something?param1...',	// complete request URI
}

Other Resource Init Options

var jax = new skinnyJAX({ host: 'http://domain.com/',
			  host_sleep: 25000,					// for use with failover - see below
			  default_timeout: 1200,				// default request timeout
			  headers: { 'Content-Type': 'application/json'}	// default request headers
			});

Advanced Usage (with Failover)

Setup Resource
To ‘enable’ failover, initialize skinnyJAX with multiple target hosts (redundant servers)
Note: ‘hosts’ is plural for this setup

var jax = new skinnyJAX({ hosts: ['http://srv1.domain.com/', 'http://srv2.domain.com/', 'http://srv3.domain.com/'] });

Submit A Request
All of the request config options:

jax.req({ endpoint: 'v1/something',				// endpoint path
	  method: 'get',					// [optional] http method - uses GET if not defined
	  params: { param1: value1, param2: value2 },		// [optional] request parameters
	  timeout: 1500,					// [optional] timeout can be boolean or a time in ms
	  retries: 2,						// [optional] retries can be boolean or a number
	  success: function(response) {				// success callback
		// success callback
	  },
	  time_out: function(response) {			// [optional] time out callback
		// time out callback
	  },
	  error: function(response) {				// [optional] error callback
		// error callback
	  }
	});

Now if a request times out or errors out skinnyJAX will disable the offending host for [host_sleep] milliseconds and will failover to a new one. The default value for host_sleep is 15000. The new host will be randomly selected from the remaining pool of active hosts. Some things to note:

1) request will be retried as configured (retries option) before a failover is triggered
2) hosts will be re-enabled 15 seconds (default host_sleep) after causing a failover
3) if all hosts in pool are disabled, request will exit false

Warnings

This was written for a specific application and hasn’t been thoroughly tested outside of its intended use. If you find a bug please let me know and I’ll check it out. If this is useful at all I’m happy to maintain it and make it better but at this point it’s immature.

Also be aware that…
it currently assumes all requests have JSON responses and parses them as such. Other responses will probably cause errors.
only requests that respond 200 trigger the success callback

TODO