BSD-3-Clause licensed and maintained by Robbie McMichael
This version can be pinned in stack with:http-client-overrides-0.1.1.0@sha256:de2e92a10c39af2fcc598e6d90cbf6136b7fc2b2819fe2d63cf664c36d0ee868,1840

Module documentation for 0.1.1.0

http-client-overrides

A library for applying overrides to ManagerSettings when using the http-client Haskell library.

Usage

You probably have some IO do notation hidden somewhere which looks like this:

manager <- newManager tlsManagerSettings

Replace it with this:

settings <- withHttpClientOverridesThrow tlsManagerSettings
manager  <- newManager settings

Set the HTTP_CLIENT_OVERRIDES environment variable to the location of your configuration file. When this environment variable is not set there is no additional overhead for HTTP requests as the ManagerSettings will not be modified. Refer to the example directory for a sample Haskell program and configuration file.

Features

Log HTTP requests and responses

The following fields can be used to print log messages for all HTTP responses, requests and request overrides:

version: v1
logOptions:
  responses: simple
  requests: simple
  requestOverrides: simple

The currently supported log formats are simple and detailed. Sample output for the simple log format is shown below:

Overriding request: https://unreachable.domain/ -> https://github.com/
Request: GET https://github.com/ HTTP/1.1
Response: HTTP/1.1 200 OK

Override HTTP requests

Match HTTP requests corresponding to a match URL and transform the request according to an override URL:

version: v1
requestOverrides:
- match: unreachable.domain
  override: github.com

Match semantics

Matches the first HTTP request which:

  • has the same scheme, host and port as the match URL
  • has a path which is a suffix of the path in the match URL

Any URL segments ommitted from the match URL are not required for matching.

Override semantics

Overrides an HTTP request with:

  • the scheme, host and port specified in the override URL
  • replaces the prefix of a matched path with the path in the override URL

Any URL segments ommitted from the override URL will not be applied to the HTTP request.

Examples

Override all HTTP requests on port 80 to use HTTPS on port 443 (note: the port is never automatically interpreted from the scheme):

version: v1
requestOverrides:
- match: http://:80
  override: https://:443

Override all requests to the host github.com which have a path prefix of /dhall-lang/dhall-lang/ to use a path prefix of /robbiemcmichael/dhall-lang/ instead.

version: v1
requestOverrides:
- match: https://github.com/dhall-lang/dhall-lang/
  override: https://github.com/robbiemcmichael/dhall-lang/

Debugging

Set logOptions.requestOverrides to detailed to see how the URLs have been parsed and how any matched HTTP requests are being overridden.