DOCSEARCHbyAlgolia
Submit Docs

killgrave

repository·main·Indexed 20 days ago

https://github.com/friendsofgo/killgrave

A lightweight, Go-based HTTP API simulator (mock server) that uses JSON and YAML for configuration. It allows developers to simulate complex API behaviors using 'imposters' to define request matching (headers, URLs, regex), response bodies, status codes, network delays, and JSON Schema validation. It supports proxy modes (none, missing, all) to redirect traffic to real servers and provides a CLI for configuration, including hot-reloading via a watcher flag.

Tokens
4.3K
Snippets
17
Records
24
Agent score
69%

What's inside killgrave

  1. Use regex in Killgrave imposters

    main

    Killgrave supports regex for matching endpoints, query parameters, and headers.

    • Endpoints: Uses gorilla/mux regex format. Example: /gophers/{_id:[\w]{26}}.
    • Query Parameters: Uses gorilla/mux regex format within the params object. Example: "apiKey": "{_apiKey:[\w]+}".
    • Headers: Uses standard regex (no gorilla/mux syntax required). Example: "Authorization": "\\w+".

    Note: Remember to escape special characters in JSON strings.

    // Regex in endpoint
{
  "request": {
    "method": "GET",
    "endpoint": "/gophers/{_id:[\\w]{26}}"
  }
}

// Regex in query params
{
  "request": {
    "method": "GET",
    "endpoint": "/gophers/{_id:[\\w]{26}}",
    "params": {
      "apiKey": "{_apiKey:[\\w]+}"
    }
  }
}

// Regex in headers
{
  "request": {
    "method": "GET",
    "endpoint": "/gophers/{id:[\\w]{26}}",
    "headers": {
      "Authorization": "\\w+"
    }
  }
}

  2. What are Imposters in Killgrave

    main
    Imposters are the core abstraction in Killgrave. They are configuration files that define the rules for how the mock server should respond to specific HTTP requests. An imposter file is identified by its .imp.json extension. They allow you to define request matching (headers, URLs, regex), response bodies (JSON, HTML, plain text, etc.), status codes, delays, and validation rules (JSON Schema).

  3. Use Killgrave in Proxy Mode

    main

    Killgrave can act as a proxy to a real server using the proxy-mode and proxy-url settings. The proxy-url must be the root path of the proxied server (e.g., http://example.com for an API at http://example.com/things).

    Available modes:

    • none: (Default) Killgrave only uses configured imposters.
    • missing: Killgrave tries to match the request with an imposter. If no match is found, it calls the real server defined in proxy-url.
    • all: Killgrave always calls the real server defined in proxy-url.

    Use the proxy-mode flag or the equivalent field in your configuration file.

  4. Install Killgrave via Docker

    main

    You can run Killgrave using a Docker container. Use the --host 0.0.0.0 flag to ensure the server can accept requests from outside the container.

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

  6. Compile Killgrave from source

    main

    To build the executable yourself, clone the repository and use make build. This is recommended as it embeds version information necessary for bug reporting. The resulting binary will be located in bin/killgrave.

    $ git clone git@github.com:friendsofgo/killgrave.git
$ make build

  7. Simulate network delay in responses

    main

    To simulate network issues or high server load, use the delay property in the response object.

    • Fixed delay: Use Go ParseDuration format (e.g., "500ms", "2s").
    • Random delay: Provide a range of two durations separated by a colon (e.g., "1s:5s"). Killgrave will pick a random duration within that range.
    {
  "response": {
    "status": 201,
    "delay": "1s:5s"
  }
}

  8. Create an Imposter

    main

    An imposter is a rule that tells Killgrave how to respond to specific requests. At least one imposter must be configured. Killgrave looks for files with the .imp.json extension in the imposters folder (defaulting to imposters).

    Important: Killgrave uses a rule-based system. You must organize your imposter files from most restrictive to least restrictive. Killgrave matches requests in sequence and stops at the first match.

    Example of a basic imposter:

    [
    {
        "request": {
            "method": "GET",
            "endpoint": "/gophers/01D8EMQ185CA8PRGE20DKZTGSR"            
        },
        "response": {
            "status": 200,
            "headers": {
                "Content-Type": "application/json"
            },
            "body": "{\"data\":{\"type\":\"gophers\",\"id\":\"01D8EMQ185CA8PRGE20DKZTGSR\",\"attributes\":{\"name\":\"Zebediah\",\"color\":\"Purples\",\"age\":55}}"`
        }
    }
]

  10. Validate requests with JSON Schema

    main

    You can use the schemaFile property in a request object to validate incoming request bodies against a JSON schema. The path to the schema file is relative to the imposters directory.

    Example workflow:

    1. Define a schema in imposters/schemas/my_schema.json.
    2. Reference it in your imposter file:
    {
  "request": {
    "method": "POST",
    "endpoint": "/resource",
    "schemaFile": "schemas/my_schema.json"
  },
  "response": {
    "status": 201
  }
}
    {
  "request": {
      "method": "POST",
      "endpoint": "/gophers",
      "schemaFile": "schemas/create_gopher_request.json",
      "headers": {
          "Content-Type": "application/json"
      }
  },
  "response": {
    "status": 201,
    "headers": {
        "Content-Type": "application/json"
    }
  }
}

  11. Configure Killgrave using a YAML config file

    main

    For permanent configurations, use a YAML file with the -c or --config flag. The imposters_path is relative to the location of the config file. You can configure proxy settings, CORS, the watcher (for hot-reloads), and TLS (secure mode) here.

    #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