Mockttp Versions Save

:boom: Breaking changes:

• Mockttp no longer supports Node.js v12, which is now end-of-life. The new minimum version is Node v14.14.0.
• Lots of previously deprecated APIs were removed:
  • All rule definition that didn't start with .for[...](), such as mockServer.get(), mockServer.post() and mockServer.anyRequest() were removed. These were previously deprecated in v2.5.0. These can all be replaced with the equivalent forX method, e.g. mockServer.forGet(), mockServer.forPost() and mockServer.forAnyRequest(). All rule builder methods now consistently start with mockServer.forX().
  • Standalone servers are now admin servers, and all previously-deprecated references to 'standalone' have been replaced with 'admin', for example Mockttp.getStandalone() is now Mockttp.getAdminServer().
  • The admin server's (previously the standalone server's) activeServerPorts method has been removed, and the mock-server-started/stopping events have been replaced with mock-session-started/stopping.
  • The deprecated handlers and MockRuleData root exports have been removed, they should be replaced with requestHandlers and RequestRuleData.
  • The deprecated tlsClientError mockttp instance subscription event has been removed, it should be replaced with tls-client-error instead.
  • The deprecated ignoreHostCertificateErrors passthrough rule option was removed, it should be replaced with the new ignoreHostHttpsErrors instead.
  • The previously deprecated addRules and setRules methods have been removed, they should be replaced with addRequestRules and setRequestRules.
  • The setFallbackRule method has been removed, it should be replaced by setting rules with the new priority: 0 field instead.
  • The deprecated thenJSON request rule builder method has been removed, it should be replaced with thenJson instead.
  • The deprecated synchronous body decoding methods have been removed: body.decodedBuffer, body.text, body.json and body.formData. They should be replaced with the body.getDecodedBuffer(), .getText(), .getJson() and .getFormData() asynchronous methods instead.
  • The body property on aborted request event data has been removed (previously it was present but always empty).
• When returning a result with a body or json field from a callback (thenCallback, beforeRequest or beforeResponse), the request or response body will now be automatically encoded to match its content-encoding header. Previously transformRequest/Response results were automatically encoded but nothing else. To return raw data that should not be encoded automatically, return rawBody instead with a Buffer/Uint8Array, and that will be used as-is with no encoding applied.
• Mockttp is now considerably stricter about preserving raw header data (i.e. header order, duplicate headers and heading name casing) when reporting and proxying requests. Officially this is not semantically meaningful in HTTP, and should not affect any correct server/client implementations, but in practice some tools may behave differently. For Mockttp users, this means:
  • All exposed requests & responses now include both a header object (lowercased header string keys to single-string or array-of-string values) and a rawHeader array (an array of [string name, string value] pairs, with the exact order & casing that they were received).
  • When using passthrough rules, proxied traffic preserves the exact header formatting for upstream requests and returned responses where possible. The one case when this isn't possible is when setting headers with a transformRequest/Response object or beforeRequest/Response callback. In that case, the headers will be normalized before forwarding, lowercasing header names and potentially changing header order.
• All .on(event) subscriptions are now reset when a Mockttp instance resets, either due to mockServer.reset() or .stop() and .start() (previously only rules were reset).
• Incoming websockets that don't match any rule are now rejected with a 503 (previously they were automatically proxied by default). This matches the behaviour for unmatched HTTP requests. To continue proxying websocket traffic, define an explicit rule like mockServer.forAnyWebSocket().thenPassThrough().

Other.changes:

• Added forPort and forHostname matchers, for more precise host matching (in addition to forHost, which matches the host header including some implicit header behaviour)
• Added support for multiple fallback rules with forUnmatchedRequest(), added support for using matchers on fallback rules, and added asPriority(n) to define multiple custom layers of multiple rules at different priorities.
• Added thenRejectConnection to reject websocket connections with a given HTTP response.

:boom: Breaking changes:

• Some unusual content encodings (notably Brotli) are no longer handled automatically when using the (now deprecated) synchronous properties. If you're using body.decodedBuffer, body.text, body.json or body.formData you should switch to the corresponding body.getX() methods instead. These methods decode content asynchronously, improving performance especially with parallel requests, and they support more encodings (including Brotli and Zstandard). Gzip, deflate, and unencoded content all still work both sync or async, so nothing will break in these common cases, but moving to the async functions is recommended regardless.
• Node v10 is no longer officially supported as it's now EOL. It still works right now, but it's no longer tested, and it's likely to stop working without warning in future versions.

Other big changes:

• For common cases, you can now automatically transform proxied content using transformRequest and transformResponse options, instead of providing your own custom beforeRequest and beforeResponse callbacks. These support completely replacing and/or updating most properties of proxied content, they make your code simpler, and in many cases they're significantly faster. The beforeX options still exist and are fully supported, but they're recommended only for advanced use cases.
• Chaining mockttp with upstream proxies is now supported, using the proxyConfig option with passthrough rules.