KAG - Koa API Gateway

Unstable - Under development

Installation

$ npm install -g kag

CLI

$ kag init|start|inspect [options]

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

Command: init

Create sample config as directory or file.

$ 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

$ kag init -d
kag.config created!
# Sample config directory is available in ./kag.config

$ kag init -f
kag.config.yml created!
# Sample config file is available in ./kag.config.yml

Command: start

Start a KAG.

$ 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

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

$ kag start -c ./config.yml
# Start KAG using config path as ./config.yml

$ KAG_CONFIG=./cfg.yml kag start
# Start KAG using config path as ./cfg.yml

Command: inspect

Inspect the compiled config for debug.

$ 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

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

$ kag inspect -c ./config.yml
# Inspect compiled config using config path as ./config.yml

$ KAG_CONFIG=./cfg.yml kag inspect
# Inspect compiled config using config path as ./cfg.yml

Configuration Structure

Directory or Files

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

File Types

• .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.

Environment Variables Expansion

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

host / port

• 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.

host: localhost
port: 9000

env

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

env:
  VAR1: VALUE
  VAR2: VALUE

endpoints

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

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

services

Define external services used by proxy policy.

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

Service Options

• 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)

pipelines

TODO

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

policies

Define predefined policies options or your own policies configuration.

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