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'}, ...}.

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
  

Global metatables

In addition to the arguments above, the following (non-iterable) global metatables will be populated with fields that may be retrieved by the request_translation_function:

• Note that metatables may only be accessed by already known keys:

Metatable request

• request.method
  • Description: HTTP request method.
  • Type: string
  • Example: 'GET', 'POST'
• request.body
  • Description: HTTP request body string.
  • Type: string or nil
  • Example: '{"foo": "bar"}'
• request.major_version
  • Description: Major HTTP version such as x in HTTP/x.1.
  • Type: integer
  • Example: 1
• request.minor_version
  • Description: Minor HTTP version such as x in HTTP/1.x.
  • Type: integer
  • Example: 1
• request.protocol
  • Description: Transfer protocol variant.
  • Type: string
  • Example: 'HTTP', 'HTTPS'
• request.client_ip
  • Description: IP address of the client issuing the request.
  • Type: string
  • Example: '172.16.238.128'
• request.path_with_query_params
  • Description: Full request path including query parameters.
  • Type: string
  • Example: '/mycontent/superman.m3u8?b=y&c=z&a=x'
• request.path
  • Description: Request path without query parameters.
  • Type: string
  • Example: '/mycontent/superman.m3u8'
• request.query_params
  • Description: The query parameter string.
  • Type: string
  • Example: 'b=y&c=z&a=x'
• request.filename
  • Description: The part of the path following the final slash, if any.
  • Type: string
  • Example: 'superman.m3u8'
• request.subnet
  • Description: Subnet of client_ip.
  • Type: string or nil
  • Example: 'all'

Metatable request_query_params

Contains the query parameters keyed by name.

Example:

print(request_query_params.a)

Metatable request_headers

Contains the request headers keyed by name.

Example:

print(request_headers.a)

Multiple values are separated with a comma.

Global tables

In addition to the (non-iterable) metatables and (iterable) arguments above, the following global iterable tables are available from all Lua functions:

Table selection_input

Contains arbitrary, custom fields fed into the router by clients. Be careful to document any dependencies between the translation functions and selection inputs.

Example usage:

if selection_input then
    for k, v in pairs(selection_input) do
        print('here is '..'selection_input!')
        print(k..'='..v)
    end
else
    print('selection_input is nil')
end

Upon returning from request_translation_function, values in the request, request_query_params and request_headers metatables will reflect the new current status of the updated HTTP Request.