@vivocha/request-retry v3.2.0

Vivocha Request-Retry

HTTP requests with configurable retries and API utilities.

Vivocha Request-Retry is a library to call API endpoints / do HTTP calls with configurable, automatic call retries in case of errors. It depends on the nice needle HTTP client module.

Requirements and Notes

• Node.js >= 16
• CommonJS modules, yet.

Changes and Breaking Changes

• Node.js >=16 required
• Dropped dependency on request and request-promise-native modules; needle HTTP client module is used, instead. Thus, request and request-promise-native aren't exported by this lib, anymore.

• Streaming under development, currently not available

Library

This library exposes the following classes.

APIClient

General HTTP client with configurable retry options.

Methods

call(options: APICallOptions)

Quick Examples (TypeScript):

1) Do a GET call to https://my-super-server.test-api.com:8443/api/things with a maximum of 3 retries in case of any error, waiting for 2000ms before each retry

const client = new APIClient('https://my-super-server.test-api.com:8443');
const opts: APICallOptions = {
    method: 'get',
    path: '/api/things',
    json: true,
    retries: 3,
    retryAfter: 2000
};
const result = await client.call(opts);

2) Do an authenticated POST call to https://my-super-server.test-api.com:8443/api/things, with a maximum of 5 retries in case of any error excluding a 401, waiting for 1000ms before each retry

const client = new APIClient('https://my-super-server.test-api.com:8443');
const opts: APICallOptions = {
    method: 'post',
    path: '/api/things',
    authOptions: {
      authorizationType = 'Bearer',
      token: 'abcd-1234'
    },
    json: true,
    body: {
      type: 'lamp'
      model: 'X-100'
    },
    retries: 5,
    retryAfter: 1000,
    doNotRetryOnErrors: [401]
};
const result = await client.call(opts);

3) Do a GET call to https://my-super-server.test-api.com:8443/api/things with a maximum of 3 retries in case of any error, waiting for 2000ms before each retry and getting a full HTTP response

const client = new APIClient('https://my-super-server.test-api.com:8443');
const opts: APICallOptions = {
    method: 'get',
    path: '/api/things',
    json: true
    retries: 3,
    retryAfter: 2000,
    getFullResponse: true
};
const result = await client.call(opts);

APICallOptions is an object with the following properties:

{
  method: 'get' | 'post' | 'put' | 'delete' | 'options' | 'head' | 'patch';
  path: string;
  qs?: any;
  body?: any;
  headers?: any,
  json?: boolean,
  authOptions?: HTTPAuthOptions;
  timeout?: number;
  retries: number;
  retryAfter: number;
  doNotRetryOnErrors?: number[];
  getFullResponse?: boolean;
  follow_max?: number; 
  follow_set_cookies?: boolean; 
  follow_set_referer?: boolean; 
  follow_keep_method?: boolean; 
  follow_if_same_host?: boolean; 
  follow_if_same_protocol?: boolean; 
  follow_if_same_location?: boolean;
}

Properties are listed in the following table (required ones in bold):

where HTTPAuthOptions is an object as follows:

{
  authorizationType?: string;
  token?: string;
  user?: string;
  password?: string;
}

Useful shortcut static methods (get, post, put, patch, head)

The following static, async methods are shortcuts for the call() method to use common HTTP methods. They all return a Promise with the results.

APIClient.get(url: string, options: APICallOptions = { retries: 2, retryAfter: 1000 }, logger?: Logger)

ApiClient.post(url: string, body: any, options: APICallOptions = { retries: 2, retryAfter: 1000 }, logger?: Logger)

APIClient.put(url: string, body: any, options: APICallOptions = { retries: 2, retryAfter: 1000 }, logger?: Logger):

APIClient.delete(url: string, options: APICallOptions = { retries: 2, retryAfter: 1000 }, logger?: Logger)

APIClient.patch(url: string, body: any, options: APICallOptions = { retries: 2, retryAfter: 1000 }, logger?: Logger)

APIClient.head(url: string, options: APICallOptions = { retries: 2, retryAfter: 1000, getFullResponse: true }, logger?: Logger)

Configuring Retries

APIClient.call() method (and all the shortcut static methods) can be configured to automatically retry HTTP calls in case of errors. Call retries configuration can be set using the following APICallOptions specific properties: retries (mandatory), retryAfter (optional), minRetryAfter (optional), and maxRetryAfter (optional). Briefly, the rules applied for retrying calls are the following:

• mandatory retries option is the total number of retries to do in case of errors calling a URL; retrying stops when the total number of retries is reached;
• retryAfter, in milliseconds: if set, before attempting a new call retry, the client will wait for this milliseconds amount.
  • If set and minRetryAfter is NOT SET then the waiting time is constant between retries, and this value is always used.
  • If NOT SET and also minRetryAfter is NOT SET then the constant wait time is set to 1000 ms.
• minRetryAfter, in milliseconds: if set, it is the waiting time before attempting the first retry call; then, if new call retries must be done, the waiting time will be computed using the following formula: 2 * currentWaitingTime + some random millis (between 0 and 50);
  • If also maxRetryAfter param is set, then when this value is reached after applying the formula, the waiting time becomes constant and maxRetryAfter is used, until retries number is reached.
  • If maxRetryAfter param is NOT SET, default is 10 minutes, and waiting time value continues growing, until the number of retries is reached. But, after 10 min is reached, remaining retries will use this constant value.