Skip to content

The HTTP Request Object

This object is returned from client:get(), client:post() and client:put() and represents a request that has yet to be sent to the remote server.

You can use the methods of this object to further configure the request, and then send the request.

The following methods are supported:

request:header(name, value)

Sets an HTTP header. name and value are both strings and correspond to the header name and value respectively.

request:header('Content-Type', 'application/json')

request:headers({HEADERS})

Sets multiple HTTP headers. HEADERS is an object-style table holding name/value pairs for the headers and values that should be set.

request:headers {
  ['Content-Type'] = 'application/json',
  ['X-Something'] = 'value',
}

request:basic_auth(username [, password])

Configures the username and optional password that should be used to perform HTTP Basic authentication.

Consider using a keysource with kumo.secrets.load to retrieve credentials.

request:bearer_auth(token)

Configures the token to be used for HTTP Bearer authentication

Consider using a keysource with kumo.secrets.load to retrieve credentials.

request:body(body)

Sets the body of the request. Body must be a string.

local request = kumo.http.build_client({}):post 'https://example.com'
request:header('Content-Type', 'application/json')
request:body(kumo.json_encode {
  key = 'value',
})

request:form_url_encoded({PARAMS})

Sets the body of the request to the provided parameters, using the application/x-www-form-urlencoded encoding scheme. The Content-Type header is implicitly set to application/x-www-form-urlencoded.

PARAMS is an object-style table whose values must be UTF-8 strings.

local request = kumo.http.build_client({}):post 'https://example.com'
request:form_url_encoded {
  key = 'value',
  other_key = 'other_value',
}

request:form_multipart_data({PARAMS})

Sets the body of the request to the provided parameters, using the multipart/form-data encoding scheme. The Content-Type header is implicitly set to multipart/form-data with the automatically determined boundary field.

PARAMS is an object-style table whose values should be either UTF-8 strings or lua binary strings. Binary strings are encoded as application/octet-stream in the generated form data.

local request = kumo.http.build_client({}):post 'https://example.com'
request:form_multipart_data {
  key = 'value',
  other_key = 'other_value',
}

request:send()

Sends the request and returns Response object representing the result of the request.

request:timeout(duration)

Since: Version 2024.06.10-84e84b89

The functionality described in this outlined box requires version 2024.06.10-84e84b89 of KumoMTA, or a more recent version.

Sets the timeout duration for the request. If no response is received within the specified duration, the request will raise an error.

The default timeout is "1 minute".

You may pass a number specifying the number of seconds (fractional numbers like 1.5 are accepted), or a string like "1 minute".