esanuka

esanuka is manage idempotency tool for AWS API Gateway.

Installation

You can install via npm:

npm install esanuka -D

Or yarn:

yarn add esanuka -D

Account Specification

Need to set environment variables of AWS account:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_ACCOUNT_ID

Make sure account has APIGateway and Lambda policies.

Resource Definition

esanuka accepts following YAML structure:

authorizers:
  authorizer-function-name:
    type: lambda
    function: authorizer-lambda-function
    sourceHeader: cookie
    ttl: 300

resources:
  - path: /path/to/endpoint
    description: Endpoint description
    methods:
      GET:
        integrationType: lambda
        function: dispatch-lambda-function
  ...

Parameters specifications are:

name	type	required	description
authorizers	Object	No	Authorizer specifications. Key is authorizer name
authorizers[key].type	String	Yes	Authorizer Type. Currentry support lamba only
authorizers[key].function	String	Yes	Lambda function name
authorizers[key].sourceHeader	String	No	Authorize identity source from header name. Either sourceHeader or sourceQuery is required
authorizers[key].sourceQuery	String	No	Authorize identity source from querystring. Either sourceHeader or sourceQuery is required
authorizers[key].ttl	Number	No	TTL of authentication cache
resources	Array	Yes	Resource specifications
resources[].path	String	Yes	Endpoint path
resources[].description	String	Yes	Endpoint description
resources[].methods	Object	Yes	Endpoint method specifications. Key is method name
resources[].methods[method].integrationType	String	Yes	Backend integration type. Value must be one of lambda, http, and vpc
resources[].methods[method].function	String	No	Lambda function name. This is required if integrationType is lambda
resources[].methods[method].url	String	No	HTTP proxy URL. This is required if integrationType is http
resources[].methods[method].vpcLinkId	String	No	VPC Link Id. This is required if integrationType is vpc
resources[].methods[method].serviceName	String	No	Backend service name. This is used for VPC link to host
resources[].methods[method].paths	Object	No	Endpoint path paramter specifications. e.g If endpoint is /path/to/{id}, paths must specify as id: true
resources[].methods[method].queryStrings	Object	No	Endpoint query string specifications. e.g If endpoint accepts /path/to?id=[id], queryStrings must specify as id: true
resources[].methods[method].authorizerType	String	No	Authorizer type. Value is one of CUSTOM of AWS_IAM
resources[].methods[method].authorizer	String	No	Authorizer name. This is required if authorizerType is CUSTOM
resources[].methods[method].responses	Object	Yes	Method/Integration response specifications
resources[].methods[method].responses[status].headers	Object	No	Sending HTTP headers to client
resources[].methods[method].responses[status].pattern	Object	No	Mapping status code pattern

Example is below:

Lambda Integration

Lambda integration always set as Lambda Proxy Integration

resources:
  - path: /path/to/endpoint
    description: Endpoint description
    methods:
      GET:
        integrationType: lambda
        function: dispatch-lambda-function

In Lambda integration, status code and http headers are passthrough between the request/response.

VPC Integration

Request can proxy using VPC Link. The usage of this is backend origins put in private VPC network.

resources:
  - path: /path/to/endpoint/{id}
    description: Endpoint description
    methods:
      GET:
        integrationType: vpc
        vpcLinkId: [vpc link id]
        serviceName: example.ap-northeast-1.elasticbeanstalk.com
        paths:
          id: true
        responses:
          200:
            headers:
              Access-Control-Allow-Origin: false

On above case, API Gateway will proxy to http://example.ap-northeast-1.elasticbeanstalk.com/path/to/endpoint/{id} using with VPC Link. And path contains {id}, bind paramter, so you need to define paths section.

In addition, you can transform dispatch path with backendPath paramter:

resources:
  - path: /path/to/endpoint/{id}
    description: Endpoint description
    methods:
      GET:
        integrationType: vpc
        vpcLinkId: [vpc link id]
        backendPath: /endpoint/{id} ## add this line
        serviceName: example.ap-northeast-1.elasticbeanstalk.com
        paths:
          id: true
        responses:
          200:
            headers:
              Access-Control-Allow-Origin: false

Then API Gateway will proxy to http://example.ap-northeast-1.elasticbeanstalk.com/endpoint/{id} using with VPC Link.

HTTP Integration

Simply HTTP proxy.

resources:
  - path: /proxies/{proxy+}
    description: Endpoint description
    methods:
      GET:
        integrationType: http
        url: https://example.com/proxies/{proxy}

API Gateway simply do proxy under /proxies/* requests to https://example.com/proxies/*.

Dry Run

esanuka supports dry-run, which compares between local and remote definitons, and display resource create/modify/delete plans to output. So you can confirm before deploy resources.

Binding Parameters

You can use binding paramteres in definition YAML file in ${} blaced:

resources:
  - path: /path/to/endpoint/{id}
    description: Endpoint description
    methods:
      GET:
        integrationType: vpc
        vpcLinkId: ${VPC_LINK_ID}
        backendPath: /endpoint/{id} ## add this line
        serviceName: example.ap-northeast-1.elasticbeanstalk.com
        paths:
          id: true
        responses:
          200:
            headers:
              Access-Control-Allow-Origin: false

Then, ${VPC_LINK_ID} will be replaced to environmen t variable.

Deployment with CLI

Easiest way is run from command line:

easnuka -f [defitnition YAML file] -s prod --rest-api-id=[rest api id]

With dry-run:

easnuka -f [defitnition YAML file] -s prod --rest-api-id=[rest api id] --dry-run

Deployment with programable

esanuka also can deploy with programably.

const esanuka = require('easnuka');
const defitnitions = esanuka.factory('/path/to/definition.yml', {});
esanuka(definitions, {
  restApiId: '[rest api id]',
  deploymentStage: 'prod'
});

With dry-run:

const esanuka = require('easnuka');
const defitnitions = esanuka.factory('/path/to/definition.yml', {});
esanuka.dryRun(definitions, {
  restApiId: '[rest api id]',
  deploymentStage: 'prod'
})l;

In addition, progoramable deployment has more garantees using options of second arguments:

const esanuka = require('easnuka');
const defitnitions = esanuka.factory('/path/to/definition.yml', {});
esanuka.dryRun(definitions, {
  onIntegrationParameters: Function,
  onMethodRequestParameters: Function,
  useLambdaWithStage: Boolean,
  lambdaAliases: Array<String>,
  baseDomain: String,
  restApiId: String,
  deploymentStage: String,
  verbose: Boolean,
  skipFunctionExistence: Boolean
});

Describes option fields with following:

name	type	required	description
onIntegrationParameters	Function(obj) => obj	No	Hook on create integration request parameters. You can add more integration headers in this function
onMethodRequestParameters	Function(obj) => obj	No	Hook on create method request parameters. You can add more integration headers in this function
useLambdaWithStage	Boolean	No	If true, create Lambda integration with staging environment as ${environment.stage} function alias
lambdaAliases	Array of aliaes	No	Additional lambda function aliases. esanuka add lambda permissions automatically.
baseDomain	String	No	Additional base domain
restApiId	String	Yes	APIGateway REST API ID
deploymentStage	String	Yes	Deployment target stage name
verbose	Boolean	No	Verbose process logs
skipFunctionExistence	Boolean	No	If true, validation skips check of lambda function existence, it's useful for local development

Author

Yoshiaki Sugimoto

License

MIT