The host request translation function defines a Lua function that modifies
HTTP requests sent to a host. These hosts are configured in
services.routing.hostGroups
.
Hosts can receive requests for a manifest. A regular host will respond with the manifest itself, while a redirecting host and a DNS host will respond with a redirection to a streamer. This function can modify all these types of requests.
The function returns nil
when nothing is to be changed, or HTTPRequest(t)
where t
is a table with any of the following optional fields:
Method
string
'GET'
, 'POST'
Path
string
'/mycontent/superman.m3u8'
Body
string
or nil
'{"foo": "bar"}'
QueryParameters
table
(indexed by number) representing an array of query
parameters as {[1]='Name',[2]='Value'}
pairs that are added to the request
being processed, or overwriting existing query parameters with colliding
names. To remove a query parameter from the request, specify nil
as value,
i.e. QueryParameters={..., {[1]='foo',[2]=nil} ...}
.
Returning a query parameter with a name but no value, such as a
in the
request '/index.m3u8?a&b=22'
is currently not supported.Headers
table
(indexed by number) representing an array of request
headers as {[1]='Name',[2]='Value'}
pairs that are added to the request
being processed, or overwriting existing request headers with colliding
names.
To remove a header from the request, specify nil
as value, i.e.
Headers={..., {[1]='foo',[2]=nil} ...}
. Duplicate names are supported.
A multi-value header such as Foo: bar1,bar2
is defined by specifying
Headers={..., {[1]='foo',[2]='bar1'}, {[1]='foo',[2]='bar2'}, ...}
.Host
string
'new-host.example.com'
, '192.0.2.7'
Port
number
8081
Protocol
'HTTP'
and 'HTTPS'
.string
'HTTP'
, 'HTTPS'
OutgoingRequest
: See Sending HTTP requests from translation functions for more information.Example of a host_request_translation_function
body that sets the request path
to a hardcoded value and adds the hardcoded query parameter a=b
:
-- Statements go here
print('Setting hardcoded Path and QueryParameters')
return HTTPRequest({
Path = '/content.mpd',
QueryParameters = {
{'a','b'}
}
})
The following (iterable) arguments will be known by the function:
QueryParameters
Type: nested table
(indexed by number).
Description: Array of query parameters as {[1]='Name',[2]='Value'}
pairs
that are present in the query string of the request from the client to the
router. Format identical to the HTTPRequest.QueryParameters
-field specified
for the return value above.
Example usage:
for _, queryParam in pairs(QueryParameters) do
print(queryParam[1]..'='..queryParam[2])
end
Headers
Type: nested table
(indexed by number).
Description: Array of request headers as {[1]='Name',[2]='Value'}
pairs
that are present in the request from the client to the router. Format identical
to the HTTPRequest.Headers
-field specified for the return value above. A
multi-value header such as Foo: bar1,bar2
is seen in
host_request_translation_function
as Headers={..., {[1]='foo',[2]='bar1'}, {[1]='foo',[2]='bar1'}, ...}
.
Example usage:
for _, header in pairs(Headers) do
print(header[1]..'='..header[2])
end
The following non-iterable global tables are available for use by the
host_request_translation_function
.
outgoing_request
The outgoing_request
table contains the request that is to be sent to the
host.
outgoing_request.method
string
'GET'
, 'POST'
outgoing_request.body
string
or nil
'{"foo": "bar"}'
outgoing_request.major_version
x
in HTTP/x.1
.integer
1
outgoing_request.minor_version
x
in HTTP/1.x
.integer
1
outgoing_request.protocol
string
'HTTP'
, 'HTTPS'
outgoing_request_headers
Contains the request headers from the request that is to be sent to the host, keyed by name.
Example:
print(outgoing_request_headers['X-Forwarded-For'])
Multiple values are separated with a comma.
In addition to the arguments above, the following Lua tables, documented in Global Lua Tables, provide additional data that is available when executing the request translation function: