mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-25 21:58:18 +00:00
Wez Furlong
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# kumo.http.build_client
|
|
|
|
```lua
|
|
kumo.http.build_client { PARAMS }
|
|
```
|
|
|
|
Constructs an HTTP client object.
|
|
|
|
The client maintains state, including a connection pool, that can be used
|
|
across multiple HTTP requests.
|
|
|
|
`PARAMS` is an object-style table with the following keys:
|
|
|
|
* `user_agent` - optional string that will be used to set the `User-Agent` header
|
|
for all requests made by the client
|
|
* `connection_verbose` - optional boolean. If true, additional diagnostics
|
|
around the connection attempt will be logged and can be seen by setting the
|
|
diagnostic filter to include `reqwest=trace`. {{since('2024.06.10-84e84b89', inline=True)}}
|
|
* `pool_idle_timeout` - optional duration. Sets the maximum time that an idle
|
|
connection remains in the connection pool. The default is `90 seconds`.
|
|
{{since('2024.06.10-84e84b89', inline=True)}}.
|
|
* `timeout` - optional duration. Sets the default timeout to use for each
|
|
request made by the client. Can be overridden using the Request object.
|
|
The default is `60 seconds`. {{since('2024.06.10-84e84b89', inline=True)}}.
|
|
* `accept_invalid_certs` - optional boolean. If true, disables SSL/TLS
|
|
certificate verification for all requests made by the client.
|
|
{{since('2026.05.12-a6845223', inline=True)}}
|
|
|
|
!!! danger
|
|
Disabling certificate verification removes protection against
|
|
man-in-the-middle attacks: any party on the network path can present
|
|
a forged certificate and intercept or modify the traffic without
|
|
detection. Only enable this in development or testing environments,
|
|
never in production.
|
|
|
|
```lua
|
|
local response = kumo.http.build_client({}):get('https://example.com/'):send()
|
|
print(response:status_code(), response:status_reason())
|
|
for k, v in pairs(response:headers()) do
|
|
print('Header', k, v)
|
|
end
|
|
print(response:text())
|
|
```
|
|
|
|
## Client Methods
|
|
|
|
The returned client object has the following methods:
|
|
|
|
### client:get(URL)
|
|
|
|
Returns a [Request](Request.md) object that has been configured to make a GET
|
|
request to the specified URL. The URL is a string.
|
|
|
|
### client:post(URL)
|
|
|
|
Returns a [Request](Request.md) object that has been configured to make a POST
|
|
request to the specified URL. The URL is a string.
|
|
|
|
### client:put(URL)
|
|
|
|
Returns a [Request](Request.md) object that has been configured to make a PUT
|
|
request to the specified URL. The URL is a string.
|
|
|
|
### client:close()
|
|
|
|
{{since('2024.09.02-c5476b89')}}
|
|
|
|
Explicitly destroy the client, closing any connections in its cache.
|