alpha¶
Source location - lifeomic/alpha
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.
API¶
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.
new Alpha(target)
¶
Creates a new Alpha
instances. All Alpha
instances support the full axios
API.
HTTP Targets¶
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');
Lambda Function Targets¶
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>
Lambda Handler Targets¶
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');
Request Retries¶
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)
});
Mocking Lambda¶
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.
Alpha.dockerLambda(options, clientOptions)
¶
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.