Request Translation Function

Specifies the body of a Lua function that inspects every incoming HTTP request and overwrites individual fields before further processing by the router.

Returns nil when nothing is to be changed, or HTTPRequest(t) where t is a table with any of the following optional fields:

• Method
  • Description: Replaces the HTTP request method in the request being processed.
  • Type: string
  • Example: 'GET', 'POST'
• Path
  • Description: Replaces the request path in the request being processed.
  • Type: string
  • Example: '/mycontent/superman.m3u8'
• ClientIp
  • Description: Replaces client IP address in the request being processed.
  • Type: string
  • Example: '172.16.238.128'
• Body
  • Description: Replaces body in the request being processed.
  • Type: string or nil
  • Example: '{"foo": "bar"}'
• QueryParameters
  • Description: Adds, removes or replaces individual query parameters in the request being processed.
  • Type: nested 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
  • Description: Adds, removes or replaces individual headers in the request being processed.
  • Type: nested 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'}, ...}.
• OutgoingRequest: See Sending HTTP requests from translation functions for more information.

Example of a 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'}
  }
})

Arguments

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 were present in the query string of the request. 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 were present in the request. 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 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
  

Additional Data

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:

• selection_input
• request
• request_query_params
• request_headers

If the request translation function modifies the request, the request, request_query_params and request_headers tables will be updated with the modified request and made available to the routing rules.