Configuring wiretap

Using flags

The following flags exist for configuring wiretap:

Using a configuration file

wiretap will automatically look for a file named wiretap.yaml in the current working directory. Then wiretap will look for a file named wiretap.yaml in the user’s home directory.

To use a custom location for the config file, use the -c or --config flag.

The above list can only be configured via a config file. All the flag options can be also configured via a config file.

Here’s an example config file that sets all the above flags to a value other than default.

redirectURL: http://some.api-host-outhere.some-domain.com
port: 5728
monitorPort: 5729
webSocketPort: 5730
contract: ./some-openapi-spec.yaml
staticDir: ./some-static-files
staticIndex: index.html
globalAPIDelay: 1000
certificate: config/sample_cert.crt
certificateKey: config/sample_key.pem
hardValidation: true
hardValidationCode: 422
hardValidationReturnCode: 500
mockMode: true

Available configuration properties

Variables

Variables can be used to replace values across path configurations, to make it easier to change values in one place, vs having to copy/paste values across multiple places, and it makes it easier to automate the configuration of wiretap.

The variables section of the config file is a simple key/value map of variables to values.

To use a variable in a path configuration, wrap the variable name in a dollar symbol with braces, like this: ${myVariableName}.

This syntax is the same used by JavaScript templating engines.

variables:
  myVariableName: my-variable-value
  somethingElse: 1234

Path configuration

Paths can be individually configured to rewrite sections of that path, inject or drop headers, use basic authentication and set a unique target for each path configuration.

To configure paths we need to create a paths section in our config file.

This configuration format was lifted directly from http-proxy-middleware.

A path configuration can also support a header configuration (see more below)

Path rewriting

When developing an application locally, paths often need to be re-written to allow local API calls to be re-routed to another live endpoint, so that applications can be testing against live data.

These paths can be complex and strange and often need to be rewritten in a specific way.

To configure a path rewrite, we need to specify the path to match on, the target to rewrite to, and optionally a pathRewrite section to further rewrite the path.

For example, this rule will match all paths that match the following glob pattern: /en-US/pb33f/__raw/* and rewrite and paths that match the following regex pattern: /en-US/pb33f/__raw/(\w+)/nobody/ to $1/-/.

So the path /en-US/pb33f/__raw/123abc/nobody/ will be rewritten to https://localhost:80/123abc/-/ when making the API call under the covers.

paths:
  /en-US/pb33f/__raw/*:
    target: localhost:80
    secure: true
    pathRewrite:
      '^/en-US/pb33f/__raw/(\w+)/nobody/': '$1/-/'

When using pathRewrite, these are regular expressions, so we can use capture groups to capture parts of the path by using dollar prefixed numbers ($1, $2, etc).

Path delay configuration

The globalAPIDelay configuration property can be used to set a global delay for all API requests, but sometimes we need to set different delays for different paths. We need finer grain control over the delay.

To configure path delays we need to create a pathDelays section in our config file.

This section takes a map of path glob patterns to delay values in milliseconds.

pathDelays:
  "/very/slow/path/*": 7000
  "/not/so/slow/*/path": 2000
  "/faster/path": 300

Basic authentication

To apply basic authentication to a path, we can use the auth section. This section takes a string in the format of username:password and will apply the Authorization header to the request.

The username and password support variables, and the entire string is base64 encoded, when being auto-injected as a header.

paths:
  /some/auth:
    target: ${someHost}/some/auth
    secure: true
    auth: "${someUser}:${somePass}"

Ignoring and allowing redirects

To ignore or allow redirects on specific paths, we can use the ignoreRedirects and allowRedirects sections. These sections take an array of glob patterns to match on.

By default wiretap will follow all redirects, but if we want to ignore or allow redirects on specific paths, we can use these.

ignoreRedirects:
  - /en-US/pb33f/__raw/*
  - /some/auth
allowRedirects:
  - /bouncy/path/*

This usecase exists because some APIs are poorly architected and tend to stuff requests full of cookies and then bounce around multiple redirects before finally landing on the correct endpoint.

If you have ever used corporate authentication systems, you’ll know what we’re talking about.

Configuring path headers

Each path configuration can also support a header configuration (see more below).

Headers

When developing an application locally, headers often need to be dropped or injected to allow local API calls to be parsed correctly by the target API.

To configure path headers we need to create a headers section in our config file for global headers, or we can also create a headers section under a specific path configuration.

Dropping headers

To drop specific output requests, we can use the drop section. This section takes an array of header names to drop.

Header values support variables as well.

headers:
  drop:
    - Origin
    - X-Some-Header

Injecting headers

To inject specific headers for each request we can use the inject section. This section takes a key/value map of header names to values.

The values support variables as well.

headers:
  inject:
    X-My-Header: ${someVar}
    Authorization: Bearer ${someToken}

Static paths

If our application is a Single Page Application (SPA), we’re going to need to serve static files from our application, and potentially configure a catch-all rule to serve the index.html file for all paths that don’t come off the index or root of the application. (/)

To configure static path catch-all rules we need to create a staticPaths section in our config file.

This section takes an array of glob patterns to match on. All matching paths will be routed to the value set by the static-index flag or staticIndex config value.

staticPaths:
  - /en-US/app/* 
  - /some-other-app-path/*/something/*

Enabling TLS/HTTP2

A certificate and certificate private key can be provided to enable TLS/HTTPS and HTTP/2. Use the flags --cert and --key to set the location of the certificate and certificate private key respectively.

The same settings can be applied via the config file.

certificate: config/sample_cert.crt
certificateKey: config/sample_key.pem

Everything will now run over TLS/HTTPS and HTTP/2. All the ports are the same, but the http scheme will be https:// instead of http://.

Hard validation mode

wiretap can be configured to override the return code for non-compliant requests and responses. Any request or response that does not match the OpenAPI specification will return an HTTP error code.

Enabling this mode can work wonders for a CI/CD pipeline and integration tests, where you want to fail a build if the API is not compliant with an OpenAPI contract.

To enable hard validation mode, use the --hard-validation / -q flag.

Or use the hardValidation config property and set the value to true

certificate: config/sample_cert.crt
hardValidation: true

The default HTTP error code for failed requests is 400, but this can be configured via the --hard-validation-code / -q flag.

The default HTTP error code for failed requests is 502, but this can be configured via the --hard-validation-return-code / -y flag.

Mock mode

wiretap can be configured to return mocked responses for all requests. This is useful for testing and development, when you don’t want to make real API calls, but you want to test your application against a real API.

Mock mode is a true test of your OpenAPI contract, because it will generate responses based on the contract.

To enable mock mode, use the --mock-mode / -x flag.

Example config file

Here is an example of a wiretap configuration file that sets all available values.

variables:
  someVar: some-value
  someUser: some-user
  somePass: some-pass
  someToken: aabbcc1234
  someHost: some.api-host-outhere.some-domain.com
redirectURL: http://my.api-host-outhere.some.domain
port: 9090
monitorPort: 9091
webSocketPort: 9092
contract: ./some-openapi-spec.yaml
staticDir: ./some-static-files
staticIndex: index.html
globalAPIDelay: 1000
headers:
  drop:
    - Origin
    - X-Some-Header
staticPaths:
  - /en-US/app/*
  - /some-other-app-path/*/something/*
paths:
  /en-US/pb33f/__raw/*:
    target: ${someHost}:8080
    secure: true
    pathRewrite:
      '^/en-US/pb33f/__raw/(\w+)/nobody/': '$1/-/'
    headers:
      inject:
        X-My-Header: ${someVar}
        Authorization: Bearer ${someToken}
      drop:
        - X-Some-Header
  /basic/auth:
    target: ${someHost}/some/auth
    secure: true
    auth: "${someUser}:${somePass}"
certificate: config/sample_cert.crt
certificateKey: config/sample_key.pem
hardValidation: true
hardValidationCode: 422
hardValidationReturnCode: 500
pathDelays:
  "/very/slow/path/*": 7000
  "/not/so/slow/*/path": 2000
  "/faster/path": 300
ignoreRedirects:
  - /en-US/pb33f/__raw/*
  - /some/auth
allowRedirects:
  - /bouncy/path/*