Response Translation Function

Specifies the body of a Lua function that inspects every outgoing HTTP response and overwrites individual fields before being sent to the client.

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

• Code
  • Description: Replaces status code in the response being sent.
  • Type: integer
  • Example: 200, 404
• Text
  • Description: Replaces status text in the response being sent.
  • Type: string
  • Example: 'OK', 'Not found'
• MajorVersion
  • Description: Replaces major HTTP version such as x in HTTP/x.1 in the response being sent.
  • Type: integer
  • Example: 1
• MinorVersion
  • Description: Replaces minor HTTP version such as x in HTTP/1.x in the response being sent.
  • Type: integer
  • Example: 1
• Protocol
  • Description: Replaces protocol in the response being sent.
  • Type: string
  • Example: 'HTTP', 'HTTPS'
• Body
  • Description: Replaces body in the response being sent.
  • Type: string or nil
  • Example: '{"foo": "bar"}'
• Headers
  • Description: Adds, removes or replaces individual headers in the response being sent.
  • Type: nested table (indexed by number) representing an array of response headers as {[1]='Name',[2]='Value'} pairs that are added to the response being sent, or overwriting existing request headers with colliding names. To remove a header from the response, 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 response_translation_function body that sets the Location header to a hardcoded value:

-- Statements go here
print('Setting hardcoded Location')
return HTTPResponse({
  Headers = {
    {'Location', 'cdn1.com/content.mpd?a=b'}
  }
})

Arguments

The following (iterable) arguments will be known by the function:

Headers

• Type: nested table (indexed by number).

• Description: Array of response headers as {[1]='Name',[2]='Value'} pairs that are present in the response being sent. Format identical to the HTTPResponse.Headers-field specified for the return value above. A multi-value header such as Foo: bar1,bar2 is seen in response_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 response_translation_function:

Note that metatables may only be accessed by already known keys.

Metatable request

See documentation for request_translation_function. If the request translation function has modified the incoming request, the request metatable will contain those changes.

Metatable request_query_params

See documentation for request_translation_function. If the request translation function has modified the incoming request, the request_query_params metatable will contain those changes.

Metatable session_query_params

Alias for metatable request_query_params.

Metatable request_headers

See documentation for request_translation_function. If the request translation function has modified the incoming request, the request_headers metatable will contain those changes.

Metatable response

Contains all the parts of the outgoing response apart from the headers.

• response.body
  • Description: HTTP response body string.
  • Type: string or nil
  • Example: '{"foo": "bar"}'
• response.code
  • Description: HTTP response status code.
  • Type: integer
  • Example: 200, 404
• response.text
  • Description: HTTP response status text.
  • Type: string
  • Example: 'OK', 'Not found'
• response.major_version
  • Description: Major HTTP version such as x in HTTP/x.1.
  • Type: integer
  • Example: 1
• response.minor_version
  • Description: Minor HTTP version such as x in HTTP/1.x.
  • Type: integer
  • Example: 1
• response.protocol
  • Description: Transfer protocol variant.
  • Type: string
  • Example: 'HTTP', 'HTTPS'

Metatable response_headers

Contains the response headers keyed by name. Example:

print(response_headers.a)

Multiple values are separated with a comma.

Metatable session

See documentation for session_translation_function. If the session translation function has modified the incoming request, the session metatable will contain those changes.

Metatable session_groups

See documentation for session_translation_function.

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

See documentation for request_translation_function. Values in the selection_input metatable will remain unchanged since a prior call to a request_translation_function.