KAG - Koa API Gateway

Unstable - Under development

Installation

``sh
$ npm install -g kag
`

CLI

`sh
$ kag init|start|inspect [options]
`

- -h, --help: Show help.
- -v, --version: Show kag version.

$3

Create sample config as directory or file.

`sh
$ kag init [-h | --help] [-d | --dir] [-f | --file]
`

- -d, --dir: Create config as a directory: kag.config.
- -f, --file: Create config as a file: kag.config.yml.

#### Examples

`sh
$ kag init -d
kag.config created!


Sample config directory is available in ./kag.config


`

`sh
$ kag init -f
kag.config.yml created!


Sample config file is available in ./kag.config.yml


`

$3

Start a KAG.

`sh
$ kag start [-h | --help] [-c CONFIG_PATH | --config CONFIG_PATH]
`

- -c CONFIG_PATH, --file CONFIG_PATH: Config path.
- Defaults:
- process.env.KAG_CONFIG
- or ./kag.config/
- or ./kag.config.yml

#### Environment Variables

- KAG_CONFIG: Config path.
- LOG_LEVEL (default: info): Log level used by winston.

#### Examples

`sh
$ kag start


Start KAG using config path as KAG_CONFIG env var, or ./kag.config, or ./kag.config.yml


`

`sh
$ kag start -c ./config.yml


Start KAG using config path as ./config.yml


`

`sh
$ KAG_CONFIG=./cfg.yml kag start


Start KAG using config path as ./cfg.yml


`

$3

Inspect the compiled config for debug.

`sh
$ kag inspect [-h | --help] [-c CONFIG_PATH | --config CONFIG_PATH]
`

- -c CONFIG_PATH, --file CONFIG_PATH: Config path.
- Defaults:
- process.env.KAG_CONFIG
- or ./kag.config/
- or ./kag.config.yml

#### Examples

`sh
$ kag inspect


Inspect compiled config using config path as KAG_CONFIG env var, or ./kag.config, or ./kag.config.yml


`

`sh
$ kag inspect -c ./config.yml


Inspect compiled config using config path as ./config.yml


`

`sh
$ KAG_CONFIG=./cfg.yml kag inspect


Inspect compiled config using config path as ./cfg.yml


`

Configuration Structure

$3

Config path accepts directory or file. For directories, all files are processed and merged, recursively, with deep-extend module.

$3

- .yml, .yaml: parsed with js-yaml module.
- .json, .json5: parsed with json5 module.
- .js: parsed with require() and should export a function that exports a object.

$3

Environment variables are replaced using:

- ${VAR_NAME}: replace with VAR_NAME value, or throws an error if VAR_NAME is undefined.
- ${VAR_NAME:-DEFAULT_VALUE}: replace with VAR_NAME value if is defined, otherwise replace with DEFAULT_VALUE.

Configuration Concepts

$3

- host (optional): Define tcp host to listen for http requests. Default to HOST environment variable or 0.0.0.0.
- port (optional): Define tcp port to listen for http requests. Default to PORT environment variable or 8000.

`yaml
host: localhost
port: 9000
`

$3

Configure default values of environment variables. All variables in this section can be overwrite using environment variables setted by system.

`yaml
env:
VAR1: VALUE
VAR2: VALUE
`

$3

Define routes in the api gateway scope. The keys of the object are used as reference in others sections.

`yaml
endpoints:
endpoint-name-1: /endpoint-1
endpoint-name-2:
path: /endpoint-2 # required
host: '' # optional, default =
methods: # optional, default = all methods
- post
`

$3

Define external services used by proxy policy.

`yaml
services:
api-1: http://api1.com
api-2:
target:
- http://api2a.com
- http://api2b.com
api-3:
target: http://api3.com
options:
- # see service options above
`

$3

- httpProxyOptions: Options that are passed to http-proxy module.
- Type: object
- Default: {}
- loadBalanceType: Set load balance strategy when target is array.
- Type: string
- Default: round-robin
- Values: round-robin, random
- prependLocation: If true, rewrite the location header received from the external service.
- Type: boolean
- Default: true
- removeHeaders: Array of header names that will be removed in the response of external service.
- Type: array
- Default: []
- rewritePath: Function to rewrite the url received in the api gateway. Only can be used when the config file is a js file.
- Type: function
- Default: undefined
- Params: (urlPath)

$3

TODO

`yaml
pipelines:
pipeline-1:
endpoints:
- endpoint-name-1
- endpoint-name-2
policies:
- policy-name-1
- name: policy-name-2
options:
service: api-1
options:
option1: value
option2: value
pipeline-2:
endpoints:
- endpoint-name-1
policies:
- name: policy-name-2
options:
service: api-2
`

$3

Define predefined policies options or your own policies configuration.

`yaml
policies:
policy-name-1:
options:
option1: value
option2: value
policy-name-2:
source: ./policy-name-2.js
options:
option1: value
option2: value
``

#### Predefined Policies

##### cors

TODO

##### header

TODO

##### health-check

TODO

##### jwt-verify

TODO

##### logger

TODO

##### proxy

TODO

##### rate-limit

TODO

##### request-id

TODO

##### response-time

TODO

##### service-info

TODO

##### terminate

TODO

#### Using Your Own Policies

TODO