vmod.vcc

# Copyright (c) 2021-2022 Guillaume Quintard Author: Guillaume Quintard

$Module reqwest 3 "HTTP requests"

$Event event_function

$Object client(PRIV_VCL,
	[STRING base_url],
	[BOOL https],
	INT follow = 10,
	[DURATION timeout],
	[DURATION connect_timeout],
	BOOL auto_gzip = 1,
	BOOL auto_deflate = 1,
	BOOL auto_brotli = 1,
	BOOL accept_invalid_certs = 0,
	BOOL accept_invalid_hostnames = 0,
	[STRING http_proxy],
	[STRING https_proxy],
	PROBE probe = 0
	)

Create a `client` object that can be used both for backend requests and in-vcl requests and will pool connections across them all. All arguments are optional.

`base_url` and `https`: dictates how the URL of a backend request is built:
- if `base_url` is specified, the full URL used is `base_url` + `bereq.url`, which means `base_url` nees to specify a scheme (e.g. `http://`) and a host (e.g. `www.example.com).
- otherwise, if `bereq.url`, doesn't start with a `/`, use it as-is
- otherwise, the URL is `http(s)://` + `bereq.http.host` + `bereq.url`, using `https` to decide on the scheme (will fail if there's no bereq.http.host)

`base_url` and `https` are mutually exclusive and can't be specified together.

`follow` dictates whether to follow redirects, and how many hops are allowed before becoming an error. A value of `0` or less will disable redirect folowing, meaning you will actually receive 30X responses if they are sent by the server.

`connect_timeout` and `timeout` dictate how long we give a request to connect, and finish, respectively.

`auto_gzip`, `auto_deflate` and `auto_brotli`, if set, will automatically set the relevant `accept-encoding` values and automatically decompress the response body. Note that this will only work if the `accept-encoding` header isn't already set AND if there's no `range` header. In practice, when contacting a backend, you will need to `unset bereq.http.accept-encoding;`, as Varnish sets it automatically.

`accept_invalid_certs` will avoid erroring on invalid certificates, for example self-signed ones. It's a dangerous option, use at your own risk!

`accept_invalid_hostnames` is even more dangerous and doesn't even require for the certificate hostname to match the server being contacted.

`http_proxy`/`https_proxy` allow you to set an HTTP(S) proxy to send your requests through.

`probe` will work the same way as for regular backends, but there are a few details to be aware of:
- the health will only prevent a fetch for backends (i.e. when using `client.backend()`), not when creating free standing requests (`client.init()`/`client.send()`).
- if the `client` has a `base_url`, the probe will prepend it to its `.url` field to know which URL to probe.
- otherwise, it'll just use the `.url` field as-is (but will immediately error out if `.url` starts with a `/`).
- this means `client`s without`base_url` can actually probe a another server that the one used as a backend.

$Method BACKEND .backend()

Return a VCL backend built upon the `client`.

$Method VOID .init(PRIV_TASK, STRING name, STRING url, STRING method = "GET")

Create an http request, identifying it by its `name`. The request is local to the VCL task it was created in. If a request already existed with the same name, it it simply dropped and replaced, i.e. it is NOT automatically sent.

$Method VOID .set_header(PRIV_TASK, STRING name, STRING key, STRING value)

Add a new header `name: value` to the unsent request named `name`. Calling this on a non-existing, or already sent request will trigger a VCL error.

$Method VOID .set_body(PRIV_TASK, STRING name, STRING body)

Set the body of the unsent request named `name`. As for `set_header()`, the request must exist and not have been sent.

$Method VOID .copy_headers_to_req(PRIV_TASK, STRING name)

Copy the native request headers (i.e. `req` or `bereq`) into the request named `name`.

$Method VOID .send(PRIV_VCL, PRIV_TASK, STRING name)

Actually send request `name`. This is non-blocking, and optional if you access the response. Any call to `status()`, `header()`, `body_as_string()` or `error()` will implicitly call `send()` if necessary and wait for the response to arrive.

`send()` is mainly useful in two cases:
- fire-and-forget: the response won't be checked, but you need the request to be sent away
- early send: you might want to send the request in `vcl_recv` but check the response in `vcl_deliver` to parallelize the VCL processing (backend fetch et al.) with the request.

$Method INT .status(PRIV_VCL, PRIV_TASK, STRING name)

Retrieve the response status (send and wait if necessary), returns 0 if the reponse failed, but will cause a VCL errorif call on a non-existing request.

$Method STRING .header(PRIV_VCL, PRIV_TASK, STRING name, STRING key, [STRING sep])

Retrieve the value of the first header named `key`, or returns NULL if it doesn't exist, or there was a transmission error.

If `sep` is specified, all the headers named `key` are collected into a single string, using `sep` to separate each value.

$Method STRING .body_as_string(PRIV_VCL, PRIV_TASK, STRING name)

Retrieve the response body, returns an empty string in case of error.

$Method STRING .error(PRIV_VCL, PRIV_TASK, STRING name)

Returns the error string if request `name` failed.
# req timeout, export headers, import headers