hoverfly

Happy Friday! We are thrilled to announce an RC release of v1.0.0!

The v5 simulation schema introduced since v0.17.0 is stable and easy to extend for more powerful request matchers. It lays a good foundation for us to implement matcher chaining to solve XML/JSON matching issues without introducing breaking changes. That's when we start considering a Hoverfly v1 release.

Thank you for all your contributions, we are hoping to work with you again on more exciting features in the coming months, and make Hoverfly shines!

Adding delay based on Log-normal Distribution

Thanks to @podtserkovskiy's contribution, you can now enable random delay in a simulation based on log-normal distribution. Here is an example:

"globalActions": {
         "delaysLogNormal": [
            {
               "urlPattern": ".",
               "httpMethod": "",
               "min": 100,
               "max": 10000,
               "mean": 5000,
               "median": 500
            }
         ]
      }

where mean and median values could be calculated from your actual server response times, and Hoverfly generate random latencies that are lognormally distributed based on these parameters.

Controlling log level

Default log level of Hoverfly is info, but if you prefer less noise or a bit concern about the performance overheads of info logging, you can control the log level with this release:

$ hoverfly -log-level warn 

Which logs warning level or above (error, fatal and panic)

Bug fixes

Some long-standing bugs have been addressed in this release, such as bugs that affect multi-value query capture, config.yaml loading and plain HTTP tunnelling.

https://github.com/SpectoLabs/hoverfly/issues/704
https://github.com/SpectoLabs/hoverfly/issues/752
https://github.com/SpectoLabs/hoverfly/issues/786
https://github.com/SpectoLabs/hoverfly/issues/792

This is a pure bugfix release to address the following issues:

Hoverfly crashed under heavy load in webserver mode

While we helped the community with load testing issues using hoverfly, we fixed a few bugs causing hoverfly to crash under load. This includes transistive bugs from an old version of logrus, concurrent read/write access to map, and usage counter failed to update in webserver mode(https://github.com/SpectoLabs/hoverfly/issues/776)

Query parameters were duplicated in the journal

This bug can be confusing when you need to debug an unmatched request. As reported by hoverfly-java users https://github.com/SpectoLabs/hoverfly-java/issues/187, the query parameters are duplicated in the closest-match debug message.

Two-way SSL authentication support

A huge thanks to @xiang-zhu's PR, Hoverfly finally has support for two-way SSL authentication. This new feature lets you capture or spy an HTTPS server that requires this authentication method. You can provide certificate key, client certificate and CA certificate with the following flags when starting hoverfly:

--client-authentication-client-key
--client-authentication-client-cert
--client-authentication-ca-cert

You must also provide a host pattern using --client-authentication-destination flag to tell Hoverfly which request hosts should be called using this authentication method.

Bug fix to capturing concurrent requests with state

Thanks again to @john4744 for fixing a concurrency issue when doing stateful capture. Hoverfly should now generate the correct state values when capturing concurrent requests.

Bug fix to simulating concurrent requests with state

Thanks again to @john4744 for spotting and fixing a bug in the state part of Hoverfly. Hoverfly did not use any locks on the state, meaning there could be concurrency issues with multiple requests and responses using and modifying state.

Bug fix to simulation import warnings

A bug was noticed regarding warnings when importing simulations with Content-Length headers on the responses with encoded bodies. This has now been fixed.

PAC file configuration

We have added support for configuring Hoverfly with a PAC file which now allows users to dynamically change upstream proxies. Our support of PAC files is fairly primitive for now, offering support for DIRECT and PROXY commands. We currently do not support fallback upstream proxies such as PROXY proxy1.org.corp; PROXY proxy1.org.corp.

The PAC file can be imported to Hoverfly through a PUT request to /api/v2/hoverfly/pac or through the use of hoverctl.

hoverctl start --pac-file path/to/file.pac

For more information on Using Hoverfly behind a proxy

Bug fix to stateful capture

Thanks to @john4744 for spotting and fixing a bug in stateful capture. This should now be resolved.

Request body templating

We have updated templating again! This time, we've the ability to use parts of the request body in your response. This is done using jsonpath and xpath.

{{ Request.Body “jsonpath” “$.test” }}
{{ Request.Body “xpath” “/root/id” }}

These templating functions will retrieve parts of the document from the request based off of the query provided.

For more information on Template helpers

Empty queries

With the introduction of the v5 schema, we temporarily lost the ability to define a request with zero query parameters, forcing users to have to remain using the deprecated query field from v4. This was captured is in issue #750. This version should now support zero query parameters correctly.

Filter out headers in diff mode

From user feedback, we found some users were struggling to make sense of the changes being outputted in diff mode due to the constantly changing headers, often headers that the user did not care had changed.

We have updated diff mode to now support the ability to filter out headers. These are defined simiarly to how you would define capturing headers when setting the mode to capture.

hoverctl mode diff --headers Content-Type,Authorization
hoverctl mode diff --all-headers

More helpers for templating

We have introduced a few new template helper methods. These helpers allow you to generate date times that can be offset from the time the response is served and can also be formatted using Golang date time formats.

For more information on Template helpers

Content-Length and Transfer-Encoding bug

There was regression in Hoverfly regarding the Content-Length and Transfer-Encoding headers being sent when using Hoverfly with HTTPs. This is against the HTTP specification, resulting in some clients throwing errors, such as in issue https://github.com/SpectoLabs/hoverfly/issues/727. This should now be resolved.

New helpers for templating

We have introduced some new template helper methods. These helpers allow you to generate random data and support several different data formats. If you have any ideas for additional template helper methods, feel free to raise an issue against Hoverfly and suggest them.

For more information on Template helpers)

v5 Schema

We have introduced a new version of the schema. This new version changes both request queries and request headers.

New matcher format

We have updated the format of matchers. The reasoning behind this was to make them more flexible and easier to extend in the future.

{
  "matcher": "exact",
  "value": "new-matcher"
}

Request header changes

We have updated Headers to now allow for the user of matchers, previously, header values were defined as strings.

"headers": {
  "Content-Type": [
    "application/json"
  ]
}

In v5, you now use matchers, bringing it more inline with the other fields of a request.

"headers": {			
  "Content-Type": [
    {
      "matcher": "exact",
      "value": "application/json"
    }
  ]
}

Request query changes

We have also updated the request query field to match headers. Previously, queries were represented as strings, which didn't make much sense considering how we represented headers.

"query": [
  {
    "matcher": "exact",
    "value": "testQuery=testValue"
  }
]

Now, they follow the same structure as request headers. This should allow for easier matching using different matchers.

"query": {			
  "testQuery": [
    {
      "matcher": "exact",
      "value": "testValue"
    }
  ]
}

A downside to this that existing queries from older simulations will now get moved to a new query field called deprecatedQuery. We intend to remove this field at some point in time, but we hope everyone will be able to update their simulations to adopt this new query structure before we remove it.

Hoverctl warnings

With the introduction of a temporary field that is marked as deprecated, we have also updated the simulation import API and hoverctl to now warn users if their simulations contain deprecated fields. This warning is just a warning and does not interfere with the importing process, so it is possible to ignore this until a time that suits you best.

For more information on Deprecated Queries

Record sequences of requests

We have updated capture mode to now support the capturing of multiple request response pairs using the same request. This now means you can record stateful services and iterate through the recorded responses. This behaviour is not default and you will need to enable it when going into capture mode.

hoverctl mode capture --stateful

For more information on Sequences
For a tutorial on Sequences

Diff Mode

Thanks to @MatousJobanek for adding a new mode to Hoverfly. By switching Hoverfly into diff mode, you can now execute requests against Hoverfly and it will work out the difference between the original service's response and the response stored in the simulation.

hoverctl mode capture
curl http://time.jsontest.com --proxy http://localhost:8500
hoverctl mode diff
curl http://time.jsontest.com --proxy http://localhost:8500
hoverctl diff get

New JSON Path Matching

We have switched all JSON path matching in Hoverfly to now use k8s.io/client-go/util/jsonpath. The end result should be better JSON path matching that should support more queries.

Fixes

• Fixed a bug where responses over HTTPS would lose their Content-Length header
• Added listen-on-host flag to hoverctl, thanks @fuyivara
• Fixed a bug with scored matching where exactMatch scored the same as a loose matcher
• Improved error logging around JSON Path and XPath matching
• Updated build to use golang 1.10
• Now using dep instead of godeps to manage vendored dependencies

Capture all then selectively export

hoverctl now lets you selectively export simulations, instead of exporting everything into one big JSON file. You can use —url-pattern flag with a plain text string or regex string to do the filtering. It can filter on hostname(destination) and path.

$ hoverctl export echo.json --url-pattern "echo.jsontest.com"     // export simulations for echo.jsontest.com only
$ hoverctl export api.json --url-pattern "(.+).jsontest.com"      // export simulations for all jsontest.com subdomains

GetJournal API paging and filtering

The Get Journal API is default to return the last 25 journal logs only, and you can control the paging using offset and limit query parameters. You can also query the requests made within a time window using from and to query parameters. The time queries support Unix timestamp.

Bug fix and improvements

• Includes the latest Hoverfly Dashboard, with Spy mode toggle and some optimisation and security fix.
• Hoverfly running in Docker is now set to listen on all interface by default, solving the issue (eg. https://github.com/SpectoLabs/hoverfly/issues/686) some users experienced since the release of v0.15.0

Spy mode

Thanks to @3sunnysideup, Hoverfly has a new spy mode. When it is set, Hoverfly will only simulate the APIs that you have defined, and call real APIs for anything else. It is deemed useful if the service under test has different external dependencies, and you want to spy on particular endpoints only. To use this new feature, simply set:

$ hoverctl mode spy

Plain HTTP tunneling

This setting allows Hoverfly to handle CONNECT requests for non-TLS tunnelling, making it possible to use Hoverly with Netty-based HTTP client such as reactor-netty.

$ hoverfly -plain-http-tunneling

Network interface binding

Hoverfly now binds to loopback interface by default and prevents firewall alerts being triggered when running on Windows machine. If you still need Hoverfly to listen on all the network interfaces, you can do so by setting:

$ hoverfly -listen-on-host 0.0.0.0

Other minor improvements

• hoverctl statusis now showing if Hoverfly is running on proxy or webserver mode
• You can now pass command line arguments when running Hoverfly Docker image, eg. $ docker run -d -p 8888:8888 -p 8500:8500 spectolabs/hoverfly -webserver

Templating

• Added helper methods to use current data time for templating.
• State keys can now be used in the template.
  More information on templating is available here.

Hoverctl auto completion

Thanks to @joostvanwollingen, you can now add bash completion file for hoverctl by running:
hoverctl completion

In this minor release, we fixed a few bugs:

• Fix escaping bug in query params
• Fix hoverctl middleware bug, thanks for the PR from @ooktay
• Always sending original query to the target server in CAPTURE mode

There are some improvements including:

• A new hoverctl status command which prints the status of Hoverfly
• Support for TLS renegotiation

State

The big addition to v0.14.0 is the introduction of state. Hoverfly stores state as a key value map, allowing for multiple states to be stored at any given time. This state can then be used as a matching requirement for requests and can be modified with successful responses served.

More information on state is available here.

Bug fixes

• Journal latency is now recorded as a float
• Journal startTime is now formatted to include milliseconds
• Requests with encoded characters in the path will now be respected and proxied on in their intended format

Response templates

Hoverfly finally has the ability to produce dynamic responses with the new templating feature. This feature allows for values from the original request being included in the response body through the use of template tags.

For more information on Templating

v3 Simulation

With the introduction of templating, we have bumped the simulation schema version up to v3. The two changes between v2 and v3 are that the request query field no longer requires character escaping and a new boolean template field on the response to enable templating on a per request response pair basis.

Webserver journal bugfix

It was noticed that the journal was no working when using Hoverfly as a webserver. This has been fixed and should now behave the same regardless if using Hoverfly as a webserver or a proxy.

requestType field in journal API responses

In the last release, we added the journal API. This API could be used for seeing the requests and responses being served by Hoverfly. There was an old, unused field being used in the request object. This field has now been removed.

Error when importing unrecognised version

In preparation for the next big release of Hoverfly, we noticed a bug. When importing simulations, Hoverfly did not provide a useful error when importing a simulation using an unsupported schema version. This has now been fixed.

Journal

To give more visibility as to what Hoverfly is up to, we have introduced a record of all requests and responses being served by Hoverfly. This can be found via the new admin API endpoint /api/v2/journal. Along with the requests and responses, metadata for each request is also recorded. This includes latency observed by Hoverfly and the mode it was in. By default, the journal will store the last 1000 requests and responses. The size of the journal is modifiable via a new -journal-size flag.

Hoverctl log files

With the introduction of the logs API several releases ago, and then the updating of the hoverctl logs command to use the API, we have now stopped hoverctl from writing logs to disk. If there are any .log files left you in your .hoverfly/ directory, they can now be deleted as they are no longer used by hoverctl.

Caching bug

We have fixed an issue involving caching. Hoverfly will cache each request/response it serves in an attempt to speed up matching, including failures to match. This bug occurred when
trying to match using specific header values, something that the cache cannot do due to how we hash each request.

Plaintext logs from Hoverfly

With this small release of Hoverfly, we have updated the logs. Previously, Hoverfly would log out to standard out using JSON formatting. This has been updated to now use the plaintext format. If you depend on JSON formatted logs in standard out, there is now a -logs flag to set the format back to json. The logs API which can be found at /api/v2/logs will still output JSON formatted logs by default.

hoverfly -logs=json

Logs API date filter

We have expanded the logs API to now allow the ability to filter logs based on a UNIX timestamp. This can now be done by providing the from query parameter with a UNIX timestamp value. All logs returned will be after this point in time, making it easier to follow logs and only request new log entries.

Content-Type bug in Hoverfly API

With the introduction of plaintext log formatting to the logs API, a bug was noticed regarding the Content-Type header on responses from the Hoverfly API. Regardless of content, this header was always set to application/json. This has now been fixed so that the header is now correctly set regardless of response body content.

After several releases of bug fixes, we are finally ready to release the next big update to Hoverfly.

Strongest match

Before v0.12.0, when matching a request in simulate mode, the first match would be returned. This could often be a problem if looser request response pairs were defined at the top of a simulation.

To get around this, we have implemented a scoring system. Each match within a request will be scored and every request response pair from a simulation will now be checked. This should result in more accurate and reliable simulations.

It is still possible to use the previous matching strategy by using the --matching-strategy=first flag when setting the mode with hoverctl.

For more information on Matching strategies

Closest match

With the introduction of scoring request response pairs to determine the most accurate match, Hoverfly can now report the closest request response pair when a request is unmatched. When this happens, an informative report of what happening during matching is now printed both to the logs as well as the HTTP error response body. This should make it much easier now to debug failing requests going through Hoverfly.

Hoverfly UI

The second update to Hoverfly comes in the form of the UI. The UI part of Hoverfly has been neglected for a long time and as a result, we have rebuilt using Angular. This new dashboard is now separate from the Hoverfly codebase in its own codebase.

For more information on Hoverfly UI

hoverfly -dev

With the change to Hoverfly UI being an external project for development, the -dev flag on Hoverfly has been updated to now enable CORS headers.

For more information on Hoverfly flags