<p align="center"> <img src="https://res.cloudinary.com/fogo/image/upload/c_scale,w_350/v1555701634/fogo/projects/gopher-killgrave.png" alt="Golang Killgrave"/> </p>

Killgrave

Killgrave is a simulator for HTTP-based APIs, in simple words a Mock Server, very easy to use, made in Go.

Table of Content

• Overview
• Concepts
  • Imposters
• Installing
  • Homebrew
  • Docker
  • Compile by yourself
  • Other
• Getting Started
  • Using Killgrave by command line
  • Using Killgrave by config file
  • Configure CORS
  • Preparing Killgrave for Proxy Mode
  • Creating an Imposter
  • Imposters structure
  • Using regex in imposters
  • Creating an imposter using JSON Schema
  • Creating an imposter with delay
  • Creating an imposter with dynamic responses
• Contributing
• License

Overview

Killgrave is a tool that provides a simple way to create a powerful simulator for HTTP-based APIs.

The Killgrave's philosophy is to provide an easy way to configure your mock server, ensuring that you don't need to learn another tooling language. For that reason we use json and yaml to generate all necessary configurations.

Killgrave provides:

• An easy way to create imposters files, using json
• The possibility to validate requests against json schemas.
• Validation of request headers.
• Using regex to allow different parameters in headers and urls.
• Custom body and dynamic body responses.
• Using all content-types bodies, (application/json, text/html, text/plain, image/jpeg, etc. )
• Configure response headers.
• Configure CORS.
• Simulate network issues and server high loads with imposter responses delay.
• Using configurable proxy server to call to the original server.
• Run the tool using flags or using a config file.
• Run your mock server using a watcher to reload on configuration changes.

Concepts

Imposters

Imposters are the most important concept of the Killgrave tool. They define the rules that determine how the server should respond to a request.

You can identify a Killgrave imposter file by its extension: .imp.json.

You can learn more about how to configure imposters in the Imposter Configuration Section.

Installing

:warning: Even though Killgrave is a very robust tool and is being used by some companies in production environments, it's still in initial development. Therefore, 'minor' version numbers are used to signify breaking changes and 'patch' version numbers are used for non-breaking changes or bugfixing. As soon as v1.0.0 is released, Killgrave will start to use SemVer as usual.

You can install Killgrave in different ways, but all of them are very simple:

Homebrew

If you are a Mac user, you can install Killgrave using Homebrew:

$ brew install friendsofgo/tap/killgrave

:warning: If you are installing via Homebrew, you always get the latest Killgrave version, we hope to fix this soon.

Docker

The application is also available through Docker.

docker run -it --rm -p 3000:3000 -v $PWD/:/home -w /home friendsofgo/killgrave --host 0.0.0.0

-p 3000:3000 publishes port 3000 (Killgrave's default port) inside the container to port 3000 on the host machine.

--host 0.0.0.0 is necessary to allow Killgrave to listen and respond to requests from outside the container (the default, localhost, will not capture requests from the host network).

Compile by yourself

If you want to use Killgrave from the source code, first you will need to clone the repository:

git clone git@github.com:friendsofgo/killgrave.git

Select the branch you want to use (main by default), and then compile Killgrave:

make build

This command will create an executable into the path bin/killgrave. We highly recommended the usage of this command to compile the software because parameters such as version are added to the compilation, which are necessary when reporting a bug.

Other

Windows and Linux users can download binaries from the Github Releases page.

Getting Started

To start Killgrave, you simply run the following.

$ killgrave

While you are welcome to provide your own configuration, Killgrave will default to the following configuration:

• imposters path: imposters
• host: localhost
• port: 3000
• CORS: []
• proxy: none
• watcher: false

Using Killgrave from the command line

Killgrave takes the following command line options. Killgrave is almost fully configurable through the command line, except for CORS, which can only be configured using the config file.

$ killgrave -h

Simple way to generate mock servers

Usage:
  killgrave [flags]

Flags:
  -c, --config string       Path to your configuration file
  -h, --help                Help for Killgrave
  -H, --host string         Set a different host than localhost (default "localhost")
  -i, --imposters string    Directory where your imposters are located (default "imposters")
  -P, --port int            Port to run the server (default 3000)
  -m, --proxy-mode string   Proxy mode, the options are all, missing or none (default "none")
  -u, --proxy-url string    The url where the proxy will redirect to
  -s, --secure              Run mock server using TLS (https)
  -v, --version             Version of Killgrave
  -w, --watcher             File watcher will reload the server on each file change

Using Killgrave by config file

If we want a more permanent configuration, we could use the option -config to specify the location of a configuration file.

The config file must be a YAML file with the following structure.

#config.yml

imposters_path: "imposters"
port: 3000
host: "localhost"
proxy:
  url: https://example.com
  mode: missing
watcher: true
cors:
  methods: ["GET"]
  headers: ["Content-Type"]
  exposed_headers: ["Cache-Control"]
  origins: ["*"]
  allow_credentials: true
watcher: true
secure: true

As you can see, you can configure all the options in a very easy way. For the above example, the file tree looks as follows, with the current working directory being mymock.

mymock/
    imposters/
        config.yml
        swapi_people.imp.json
        swapi_planets.imp.json
    Dockerfile
    MakeFile

Then in your config file, you will need to set the -imposters flag to . because the imposters folder is located in the same folder.

Historically, the options imposters_path, port, host were mandatory when using a configuration file. However, since the last version, they are no longer needed, so you can simply override those options if you want to. Furthermore, in previous versions, the imposters_path option refered to the path where the app was launched, but in the last version this is relative to the location of the config file.

The option cors is still optional and its options can be an empty array. If you want more information about the CORS options, visit the CORS section.

The watcher configuration field is optional. With this setting you can enable hot-reloads on imposter changes. Disabled by default.

The secure configuration field is optional. With this setting you can run your server using TLS options with a dummy certificate, so as to make it work with the HTTPS protocol. Disabled by default.

The option proxy-mode allows you to configure the mock in proxy mode. When this mode is enabled, Killgrave will forward any unconfigured requests to another server. More information: Proxy Section

How to use

Configure CORS

If you want to use killgrave from a client application you should consider configuring CORS.

In the CORS section of the file you can find the following options:

• methods (string array)

  Represents the Access-Control-Request-Method header, if you don't specify it or if you leave it as an empty array, the default values will be:

  "GET", "HEAD", "POST", "PUT", "OPTIONS", "DELETE", "PATCH", "TRACE", "CONNECT"

• headers (string array)

  Represents the Access-Control-Request-Headers header, if you don't specify it or if you leave it as an empty array, the default values will be:

  "X-Requested-With", "Content-Type", "Authorization"

• exposed_headers (string array)

  Represents the Access-Control-Expose-Headers header, if you don't specify it or if you leave it as an empty array, the default values will be:

  "Cache-Control", "Content-Language", "Content-Type", "Expires", "Last-Modified", "Pragma"

• origins (string array)