Esanuka NPM | npm.io

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
authorizerskey.type	String	Yes	Authorizer Type. Currentry support `lamba` only
authorizerskey.function	String	Yes	Lambda function name
authorizerskey.sourceHeader	String	No	Authorize identity source from header name. Either sourceHeader or sourceQuery is required
authorizerskey.sourceQuery	String	No	Authorize identity source from querystring. Either sourceHeader or sourceQuery is required
authorizerskey.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[].methodsmethod.integrationType	String	Yes	Backend integration type. Value must be one of `lambda`, `http`, and `vpc`
resources[].methodsmethod.function	String	No	Lambda function name. This is required if `integrationType` is `lambda`
resources[].methodsmethod.url	String	No	HTTP proxy URL. This is required if `integrationType` is `http`
resources[].methodsmethod.vpcLinkId	String	No	VPC Link Id. This is required if `integrationType` is `vpc`
resources[].methodsmethod.serviceName	String	No	Backend service name. This is used for VPC link to host
resources[].methodsmethod.paths	Object	No	Endpoint path paramter specifications. e.g If endpoint is `/path/to/{id}`, paths must specify as `id: true`
resources[].methodsmethod.queryStrings	Object	No	Endpoint query string specifications. e.g If endpoint accepts `/path/to?id=[id]`, queryStrings must specify as `id: true`
resources[].methodsmethod.authorizerType	String	No	Authorizer type. Value is one of `CUSTOM` of `AWS_IAM`
resources[].methodsmethod.authorizer	String	No	Authorizer name. This is required if `authorizerType` is `CUSTOM`
resources[].methodsmethod.responses	Object	Yes	Method/Integration response specifications
resources[].methodsmethod.responsesstatus.headers	Object	No	Sending HTTP headers to client
resources[].methodsmethod.responsesstatus.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