Mirage Mocker

Mirage mocker is a simple yet powerful API mock server. Mirage mocker can mock an HTTP request by:

• Echo the request (returning same body received)
• Returning a fixed payload
• Returning a payload based on a header
• Running a customized response produced by a Go Plugin
• Transform the request (using a Go Plugin) and proxy-pass the HTTP requests to a real server.

Installation

Using go

Once you have go installed and make sure to add $GOPATH/bin to your PATH.

Go version < 1.16

GO111MODULE=on go get github.com/rodrigo-kayala/mirage-mocker@v1.3.0

Go version >= 1.16

go install github.com/rodrigo-kayala/mirage-mocker@v1.3.0

Using binary distribuition file

You can download the pre-build binary file compatible with your system here

Usage

Once you have the configuration file ready, simple run:

mirage-mocker [config-file-path]

If you don't inform a configuration file, mirage-mocker will look for a mocker.yml in current path

Configuration

Configuration example

This configuration is avaliable in here and is the same configuration used on the tests cenarios. It also uses a runnable and a transform plugin

pretty-logs: true
services:
  - parser:
      pattern: /pass/postman.*
      rewrite:
        - source: /pass/postman(/.*)
          target: $1
      methods: [ POST, GET, PUT, DELETE ]
      type: pass
      log: true
      transform-lib: processor/testdata/transform/transform.so
      transform-symbol: AddHeader
      pass-base-uri: "https://postman-echo.com"
  - parser:
      pattern: /.*$
      methods: [ POST,PUT,DELETE ]
      headers:
        content-type: application/json
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          POST: 201
          PUT: 200
          DELETE: 204
        body-type: echo
  - parser:
      pattern: /mock/fixed/value.*
      methods: [ GET ]
      type: mock
      log: true
      response:
        headers:
          content-type: text/plain
        status:
          GET: 200
        body-type: fixed
        body: pong
  - parser:
      pattern: /mock/fixed/delay.*
      methods: [ GET ]
      type: mock
      log: true
      delay:
        min: 2s
        max: 3s
      response:
        headers:
          content-type: text/plain
        status:
          GET: 200
        body-type: fixed
        body: pong
  - parser:
      pattern: /mock/fixed/file.*
      methods: [ GET ]
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          GET: 200
        body-type: fixed
        body-file: processor/testdata/response1.json
  - parser:
      pattern: /mock/magicheader/file.*
      methods: [ GET ]
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          GET: 200
        body-type: fixed
        body-file: processor/testdata/fallback.json
        magic-header-name: X-MAGIC-FILE
        magic-header-folder: processor/testdata
  - parser:
      pattern: /mock/runnable.*
      methods: [ GET ]
      type: mock
      log: true
      response:
        status:
          GET: 200
        body-type: runnable
        response-lib: processor/testdata/runnable/runnable.so
        response-symbol: GetEnv

Base attributes

• pattern (required): regex pattern expression used to match requests URLs (without host)
• methods (required): array of HTTP methods to match
• type (required): mock or pass (proxy-pass)
• headers (optional): map of required headers to match
• log (optional): tells if request/response content should be logged. Defaults to false
• delay (optional): adds a random delay to the request (could be useful to simulate real production cenarios)
  • min: min delay time that should added
  • max: max delay time that should added

Other attributes are specific for some type of request or response. See below.

Mock - Base attributes

All mock type configurations should contains a response configuration

• response (required for type mock)
  • status (required for matched methods)
    • [METHOD]: [HTTP RESPONSE STATUS CODE]
    • ex. GET: 200
  • body-type: fixed, request or runnable
  • headers (optional): map of response headers

Mock - fixed

Produces a fixed response for a given path/method. It can return a fixed string

  - parser: 
      pattern: /mock/fixed/value.*
      methods: [GET]
      type: mock
      log: true
      response:
        headers:
          content-type: text/plain
        status:
          GET: 200
        body-type: fixed
        body: pong

Or the content of a file:

  - parser:
      pattern: /mock/fixed/file.*
      methods: [GET]
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          GET: 200
        body-type: fixed
        body-file: processor/testdata/response1.json

Or the content of a file based on a header (aka magic header):

  - parser:
      pattern: /mock/magicheader/file.*
      methods: [ GET ]
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          GET: 200
        body-type: fixed
        body-file: processor/testdata/fallback.json
        magic-header-name: X-MAGIC-FILE
        magic-header-folder: processor/testdata

In this last configuration the response will be the content of the file name passed on the chosen header (X-MAGIC-FILE in this configuration)

Attributes

• body: response string

or

• body-file: file containing the response string

and

• magic-header-name (optional): name of the magic header (which will contain the name of the file to be read)
• magic-header-folder (optional): folder path where the files for the magic header will store (for security reasons the magic header can only read files from this folder)

Mock - request response

Response will always have same body as the request

  - parser: 
      pattern: /.*$
      methods: [POST,PUT,DELETE]
      content-type: application/json
      type: mock
      log: true
      response:
        headers:
          content-type: application/json
        status:
          POST: 201
          PUT: 200
          DELETE: 204
        body-type: request

Mock - runnable

Run a customized go plugin which should perform the response

  - parser:
      pattern: /mock/runnable.*
      methods: [GET]
      type: mock
      log: true
      response:
        status:
          GET: 200
        body-type: runnable
        response-lib: processor/testdata/runnable/runnable.so
        response-symbol: GetEnv

Attributes

• response-lib: Go plugin (*.so) file - for instructions, se below
• response-symbol: function to produce the response. It must have this signature:

func (w  http.ResponseWriter, r *http.Request, status  int) error

Here is a simple example of a runnable plugin

Pass

Optionally runs a customized go plugin to transform request and then proxy-pass it to a real server.

  - parser:
      pattern: /echo.*
      rewrite:
        - source: /echo(/.*)
          target: $1
      methods: [POST, GET, PUT, DELETE]
      type: pass
      log: true
      transform-lib: processor/testdata/transform/transform.so
      transform-symbol: AddHeader
      pass-base-uri: "https://postman-echo.com"

Attributes

• rewrite: a set of regex replaces to rewrite the URIs
  • source: regular expression
  • target: replace string
• pass-base-uri: base URI to proxy-pass requests
• transform-lib: Go plugin (*.so) file - for instructions, se below
• transform-symbol: function to transform the request. It must have this signature: func (r *http.Request) error

Here is a simple example of a transform plugin

Plugins

Mirage mocker plugins are standard Go plugins (see https://golang.org/pkg/plugin).

Runnable plugins

Function signature

func (w http.ResponseWriter, r *http.Request, status int) error

Example

func GetEnv(w http.ResponseWriter, r *http.Request, status int) error {
	var env string
	vname, ok := r.URL.Query()["vname"]
	if ok && len(vname) > 0 {
		env = os.Getenv(vname[0])
	}

	w.Header().Add("Content-Type", "text/plain")
	w.WriteHeader(status)
	w.Write([]byte(fmt.Sprintf("%s", env)))

	return nil
}

Transform plugins

Function signature

func (r *http.Request) error {

Example

func AddHeader(r *http.Request) error {
	vname, ok := r.URL.Query()["vname"]
	if ok && len(vname) > 0 {
		env := os.Getenv(vname[0])
		r.Header.Add(vname[0], env)
	}

	return nil
}