h1. 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":http://tapl.io - take it for a spin to see it in action! Let "me":http://daveriess.me know if it's useful =)

h1. 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
}

h1. 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
            });

h1. 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

h1. 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

h1. TODO

• compatibility with non-JSON requests (interpret MIME types)
• obvious headers should be applied
• configurable disable/random/sequential failover