robust-http-fetch

Robust Http Fetch

Robust Http Fetch

This robust-http-fetch is a light-weight and 100%-test-coverage javascript utils helping to make robust http fetch request.

The underlying fetch will be delegated either to window.fetch when use in browser or node-fetch when use in node server.

It makes request to the provided url, if response is not received in timely manner(init.timeout config below) or failed (fragile network etc), it will fire another request to race(up to init.maxRequests requests to fire if none of them are well resolved).

Request waits upto init.timeout milliseconds for response before sending a retry, if more than one request are still in-flight, then they are racing, the earliest good response will be resolved with and returned. Details refer to usage section in this page.

Caveats: only use this utils when your request is idempotent, for example GET, no matter how many times calling GET, should have same result and data integrity still maintained, likewise for DELETE. In case of POST/PUT, make sure your server side to maintain the data integrity, for example backend to perform checking if previous requests have completed then abort duplicated requests etc.

see also in a github page: https://gaoqing.github.io/robust-http-fetch/

Installation

Use the package manager NPM to install robust-http-fetch.

npm install robust-http-fetch

Usage

Usage is as simple as below, can also refer to tests in end2end tests or unit tests)

 const robustHttpFetch = require('robust-http-fetch'); 

 const url = "https://postman-echo.com/post";
 const body = {hello: 'world'};

 /**
 * below input arguments for demonstration only. It use the Promise resolve callback function as the callback to the 3rd parameter, 
 * but you can use your custom callback function which accept a Promise object as its argument.
 * @input url, required, the resource destination
 * @input {timeout}, required, here request will wait 3000ms before firing retry request
 * @input {maxRequests}, required, here upto 3 requests to fire in case previous requests delayed or not well resolved
 * @input {method/body/headers}...and more, on demand properties, usage refer to `window.fetch`(init config)/`node-fetch`(options config)
 * @input resolve, required, any callback function to be invoked with a Promise object later
 * @input console.log,  optional function, any function accept a string argument 
 **/    
const resultAsPromise = new Promise((resolve, reject) => {
     robustHttpFetch(
         url, 
         {
             timeout: 3000,
             maxRequests: 3, 
             method: 'POST',
             body: JSON.stringify(body),
             headers: {'Content-Type': 'application/json'}
         },
         resolve,
         console.log
    );
 });

//do your stuff with this promise as usual, for example
resultAsPromise
    .then(res => res.json())
    .then(data => console.log(data));

Arguments:

const robustHttpFetch = require('robust-http-fetch'), it is a javascript function to use, which accept 4 parameters as followings

Parameter	Required	Type	Description
url	true	string	The resource destination url this request will send to
init	true	object	2 properties are MANDATORY: 'timeout' to time-box a single request and 'maxRequests' to limit the total number of requests to attempt. Besides those 2, it can have on-demand properties from 'init' parameter of window.fetch or 'options' parameter of node-fetch. Please refer to link 'init' of window.fetch or 'options' of node-fetch
callback	true	function	It will be invoked with a resolved promise(if a request is well finished before attempting all the retry requests) or with last request' result(a promise that might be eventually resolved or rejected)
optLogger	false	function	Optional, if any, will get called with a single string parameter to give small hints when making request

Try

To do a quick try, few steps to load up the module and execute a test:

Step 1: git clone https://github.com/gaoqing/robust-http-fetch.git
Step 2: cd robust-http-fetch/test/node-test
Step 3: npm run test

You will see some output in the console log showing some request have been made.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT