Kag NPM | npm.io

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