@lifeomic/alpha

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 (v1) 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, either set the LAMBDA_ENDPOINT environment variable, or use the lambdaEndpoint config option:

const alpha = new Alpha('lambda:my-lambda', { 
  lambdaEndpoint: 'http://localstack:4566'
});

The value of this option 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.