Melchett

A plugin-based HTTP client for NodeJS.

HttpClient

The REST client, constructed using new HttpClient(config). See below for the structure of the config object.

Configuration

All properties are optional.

Property	Type	Description	Default
name	string	Name of the client	http
timeout	number	Timeout in milliseconds	1500
userAgent	string	Custom user agent for the client	melchett/{VERSION}
successPredicate	(status: number) => boolean	Function to determine if a response is resolved or rejected	(status) => status >= 200 && status < 400
cache	Cache	Object specifying caching options and a reference to a caching engine. If undefined, caching is disabled. See caching for more information	undefined
circuitBreaker	CircuitBreaker	Object specifying circuit breaker options. If undefined, circuit breaker is disabled. See circuit breaker for more information	undefined
timingHeader	string	Response header from which to try to parse the response time	undefined
agentOptions	object	Object containing options that will be used to create a custom https agent. Currently only ca, cert and key are supported	undefined

Middleware

Additional client features are implemented as middleware. These can be opted-into by adding the relevent property for the feature to the client configuration object.

Caching

Cache the responses to idempotent requests that have a max-age directive. Provide an instance of Catbox as the value of cache.store.

store is the only mandatory property.

Property	Type	Description	Default
store	Catbox instance	Cache engine to be used	undefined
cacheTtl	number	Maximum number of seconds to store responses in cache (max-age is preferred if its value is lower)	7200
ignoreErrors	boolean	Do not reject the response if a cache error occurs	true
doNotVary	string[]	Array of header names that should not be varied on	[]

Circuit breaker

If requests begin to fail (status code >= 500) add a circuit breaker to prevent subsequent requests for a predefined time period. Reduced traffic can allow the upstream time to recover. Opossum is used under the hood to provide this functionality. Provide configuration options on the circuitBreaker property of the client configuration object.

Valid configuration options can be found in the Opossum documentation.

Requests

Once the HttpClient has been instantiated, the following methods are available to call

client.get(url [, headers]);
client.post(url, body [, headers]);
client.delete(url [, headers]);

Parameters

• url - a string representing the full URL (including scheme, and any query or fragment parts)
• headers - an object containing key/value pairs representing the request headers
• body - a string or object representing the payload for POST requests

Responses

The request configuration of a given request is always returned (regardless of whether the response is resolved). The following example shows its structure;

{
    request: {
        url: 'https://www.bbc.co.uk',
        client: 'http',
        method: 'get',
        id: '89dce102-2040-40b9-80ae-0a72c5aaa3db'
    }
}

If the response completes successfully, the promise is resolved and the response property will contain the fields shown below:

{
    response: {
        body: 'Here is a response that will inform, educate, and entertain',
        headers: {},
        status: 200,
        duration: 123,
        melchettCached: true
    }
}

Response that are not served from cache and contain a header matching the value provided in timingHeader have the header value added under the duration property.

If no timingHeader is provided or it was absent in the response, melchett will fall back to a less accurate timing calculation for the duration property.

If an error occurs at some point in the request/response chain, the promise is rejected with an additional error field as shown:

{
    error: {
        name: 'ESTATUS500',
        message: 'Status code 500 received',
        details: 'Internal Server Error'
    }
}

Rejections will still include properties under the response field if they are available.

Contributing

To develop melchett as a dependency for another package, when inside the melchett directory run:

npm link

Then, switch into the consuming package directory and run:

npm link melchett

This will symlink melchett into the consumer's node_modules folder and allow you to make changes to melchett without having to commit or reinstall.

Be sure to read the contributing document beforehand.

Copyright © 2021 BBC.