Alpha is a module that provides a single client interface for interacting with HTTP micro-services regardless of whether they are implemented as Lambda functions or real HTTP servers.
Alpha
instances are axios
clients at their core. This means that they
support the full axios
API. The difference is how Alpha
instances are
instantiated. Regardless of how an Alpha
instance is instantiated, requests
to fully qualified HTTP URLs will always perform a real HTTP request. Requests
made to Lambda functions with a Buffer
payload will automatically encode the
request body using the base64 encoding.
Creates a new Alpha
instances. All Alpha
instances support the full
axios
API.
When an Alpha
instance is created with an HTTP(S) base URL target, requests to
unqualified URLs will be relative to the base URL. For example, the following
code will dispatch the request to http://example.com/some/path
.
const alpha = new Alpha('http://example.com');
const response = await alpha.get('/some/path');
When an Alpha
instance is created with a base URL using the lambda
scheme,
requests to unqualified URLs will cause the specified Lambda function
to be invoked with a synthetic API Gateway event using the
optional Lambda alias. For example, the following code will
invoke the test-function
Lambda function with the named-alias
.
const alpha = new Alpha('lambda://test-function:named-alias');
const response = await alpha.get('/some/path');
The lambda
URL scheme is interpreted according to the following pattern:
lambda://<function-name>:<named-alias>
When an Alpha
instance is created with a handler function target, requests to
unqualified URLs will be transformed into synthetic API Gateway
events that will be passed directly to the handler function. This is primarily
used for unit testing Lambda handlers.
const alpha = new Alpha(handlerFunction);
const response = await alpha.get('/some/path');
An Alpha
client can be configured to retry a failed attempt. A retryable failure
currently means a request that failed from a network error or had a 5xx
status
code.
// Retry failed requests using default settings
const alpha = new Alpha('http://example.com', { retry: true });
// Retry failed requests using custom settings
const alpha = new Alpha('http://example.com', { retry: {
attempts: 3, // The number of attempts to make (default 3)
factor: 2, // The factor to use for the exponential backoff delay (default 2)
maxTimeout: 10000, // The max timeout in milliseconds to delay before the next attempt (default 10000)
retryCondition: function (error) { } // If function result is truthy, the error will be retried (default is retry network and 5xx errors)
});
To redirect the Lambda requests to a mocked implementation, set the
LAMBDA_ENDPOINT
environment variable. The value of this environment variable
will be used when creating the AWS Lambda client.
Creates an Alpha
client instance that dispatches requests to
docker-lambda
. This facilitates testing Lambda services in a
full mock Lambda environment running in a docker container. The options
are
passed to the docker-lambda
library and the clientOptions
configure the Alpha
client instance that is created.