# esanuka > esanuka is manage idempotency tool for AWS API Gateway. Latest version **0.9.0** (published 2022-07-04) · MIT license · 0 weekly downloads ## Install ```sh npm install esanuka pnpm add esanuka yarn add esanuka bun add esanuka ``` Provides the command `esanuka`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.9.0 | | Published | 2022-07-04 | | First published | 2019-06-03 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 4 | | Unpacked size | 58 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Author | Yoshiaki Sugimoto | | Maintainers | ysugimoto | ## Links - npm: https://www.npmjs.com/package/esanuka - npm.io page: https://npm.io/package/esanuka ## Dependencies (4) - [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.460.0 - [js-yaml](https://npm.io/package/js-yaml.md) ^3.13.1 - [minimist](https://npm.io/package/minimist.md) ^1.2.0 - [deep-object-diff](https://npm.io/package/deep-object-diff.md) ^1.1.0 ## Recent versions - 0.9.0 (latest) — 2022-07-04 - 0.8.5 — 2021-01-25 - 0.8.4 — 2020-10-20 - 0.8.3 — 2019-12-25 - 0.8.2 — 2019-12-20 - 0.8.1 — 2019-12-20 - 0.8.0 — 2019-12-20 - 0.7.9 — 2019-09-25 - 0.7.8 — 2019-09-25 - 0.7.7 — 2019-06-11 - 0.7.6 — 2019-06-11 - 0.7.5 — 2019-06-11 - 0.7.4 — 2019-06-11 - 0.7.3 — 2019-06-10 - 0.7.2 — 2019-06-10 - … 19 more at https://npm.io/package/esanuka/versions ## README # esanuka esanuka is manage idempotency tool for AWS API Gateway. ## Installation You can install via `npm`: ```shell npm install esanuka -D ``` Or `yarn`: ```shell 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: ```yaml 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** ```yaml 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. ```yaml 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: ```yaml 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. ```yaml 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: ```yaml 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: ```shell easnuka -f [defitnition YAML file] -s prod --rest-api-id=[rest api id] ``` With dry-run: ```shell easnuka -f [defitnition YAML file] -s prod --rest-api-id=[rest api id] --dry-run ``` ## Deployment with programable `esanuka` also can deploy with programably. ```js const esanuka = require('easnuka'); const defitnitions = esanuka.factory('/path/to/definition.yml', {}); esanuka(definitions, { restApiId: '[rest api id]', deploymentStage: 'prod' }); ``` With dry-run: ```js 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: ```js const esanuka = require('easnuka'); const defitnitions = esanuka.factory('/path/to/definition.yml', {}); esanuka.dryRun(definitions, { onIntegrationParameters: Function, onMethodRequestParameters: Function, useLambdaWithStage: Boolean, lambdaAliases: Array, 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 --- _Source: https://npm.io/package/esanuka · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._