habrok

Promises/A+, request-powered, boom-enabled, JSON-first HTTP API client with automatic retry

Quick start

Prerequisites

• Node.js LTS (8+)
• npm

Installing

Install with npm:

npm install habrok --save

Example

const Habrok = require('habrok');

const habrok = new Habrok();

habrok.request({
  method: 'GET',
  uri: 'https://api.github.com/repositories'
})
.then(console.log);

{
  "statusCode": 200,
  "headers": {
    "content-length": "4477",
    "content-type": "application/json; charset=utf-8",
    "etag": "6ffc6a0dbbe2613e4d8b3f7444e5c604",
    ...
  },
  "body": [
    {
      "id": 1296269,
      "private": false,
      "owner": {
        "id": 1,
        "login": "octocat",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        ...
      },
      "name": "hello-World",
      "full_name": "octocat/hello-world",
      "description": "Octocat's first repo!",
      "url": "https://api.github.com/repos/octocat/hello-world",
      ...
    },
    ...
  ]
}

API

Habrok (Constructor)

Definition

Habrok([configuration])

Required arguments

None

Optional arguments

• configuration: Object with one or more of the below properties:

| Property | Type | Description | Default | | :------- | :--- | :---------- | :------ | | disableAutomaticJson | Boolean | Disable JSON headers and request/response bodies | false | | disableCustomHeaders | Boolean | Disable request headers added by Habrok | false | | disableRetryEconnreset | Boolean | Disable retry for connection reset errors | false | | retries | Number | Number of times to retry a failed request | 5 | | retryMinDelay | Number | Minimum milliseconds to wait before retrying a request | 100 | | retryMaxDelay | Number | Maximum milliseconds to wait before retrying a request | None | | retryCodes | Array<Number> | HTTP status codes that trigger a retry | [429, 502, 503, 504] |

By default, each request includes the following headers (which can be prevented with disableCustomHeaders):

• User-Agent: habrok/[MAJOR.MINOR.PATCH], versioned according to package.json (e.g. habrok/1.0.0)
• X-Node-Platform: Directly from process.platform (e.g. linux)
• X-Node-Version: Derived from process.version (e.g. 6.11.1)

The retry logic follows exponential backoff, summarized as:

MINIMUM(retryMaxDelay, retryMinDelay * (attempt ** 2))

With the default configuration, a failing request observes a delay sequence of 100, 400, 900, and 1600 milliseconds before rejecting with an error.

Returns

A Habrok HTTP API Client instance.

Examples

Construct a default client:

const Habrok = require('habrok');

const habrok = new Habrok();

Construct a client with a minimum retry delay of 250 milliseconds:

const Habrok = require('habrok');

const habrok = new Habrok({ retryMinDelay: 250 });

Construct a client that does not send Habrok-generated headers:

const Habrok = require('habrok');

const habrok = new Habrok({ disableCustomHeaders: true });

Habrok#request

Definition

habrok.request(req[, options])

Required arguments

• req: Object, a request-compatible object

Optional arguments

• options: Object with one or more of the below properties:

| Property | Type | Description | Default | | :------- | :--- | :---------- | :------ | | attempt | Number | Integer indicating current request sequence number | None |

Generally, attempt is not needed. The internal retry engine will pass the current attempt count into the next request. Override only as necessary – e.g. in cases where the retry logic should be bypassed.

Returns

A Promise that resolves to an Object with the following properties:

• statusCode: Number, the HTTP status code provided in the response
• headers: Object, HTTP headers (lower-cased) and their values provided in the response
• body: Any, the JSON-parsed response body (or the raw body if disableAutomaticJson was set)

The Promise is rejected with a Boom-wrapped error if an HTTP error occurs. The Promise is rejected with a generic Error if an error is returned by the underlying request library (usually from http.ClientRequest).

Examples

Send a GET request:

habrok.request({
  method: 'GET',
  uri: 'https://api.viki.ng/longships'
})

Send a POST request:

habrok.request({
  method: 'POST',
  uri: 'https://api.viki.ng/longships',
  json: {
    name: 'Oseberg'
  }
})

Development

Debug

The debug module is used for runtime logging. Omit the DEBUG environment variable to squelch all logging. Set DEBUG to the desired level (e.g. DEBUG=habrok) to restrict logging to a desired service. Or, use DEBUG=* to get all debug output from everywhere, including dependencies.

DEBUG=habrok* node index

Tests

To run the unit tests:

npm test

This project maintains ~100% coverage of statements, branches, and functions. To determine unit test coverage:

npm run coverage

Contribute

PRs are welcome! PRs must pass unit tests and linting prior to merge. PRs must not reduce unit coverage. For bugs, please include a failing test which passes when your PR is applied. To enable a git hook that runs npm test prior to pushing, cd into your repo and run:

touch .git/hooks/pre-push
chmod +x .git/hooks/pre-push
echo "npm test" > .git/hooks/pre-push

Versioning

This project follows semantic versioning. See the changelog for release information.

License

• This module is licensed under the ISC License
• The underlying boom module is licensed under the BSD 3-Clause License
• The underlying debug module is licensed under the MIT License
• The underlying has module is licensed under the MIT License
• The underlying request module is licensed under the Apache 2.0

Etymology

From Grímnismál, Stanza 44:

The best of trees must Yggdrasil be, Skithblathnir best of boats; Of all the gods is Odin the greatest, And Sleipnir the best of steeds; Bifrost of bridges, Bragi of skalds, Habrok of hawks, and Garm of hounds.

Habrok, data-in-flight at its best.