Lua Features

• 1: Health Check Functions
• 2: Request Translation Function
• 3: Response Translation Function
• 4: Session Translation Function

1 - Health Check Functions

This section details built in Lua functions that are meant to be used for host health checks. Note that these functions rely on data supplied by metric agents detailed in Cache hardware metrics: monitoring and routing. Make sure cache hardware metrics are supplied to the router before using any of these functions.

cpu_load_ok()

Parameters

The function accepts an optional argument table with the following keys:

• Optional hostname: The name of the host. Defaults to the hostname of the selected host if not provided.
• Optional cpu_load5_limit: The acceptable limit for the 5-minute CPU load. Defaults to 0.9 if not provided.

Returns

The function returns 1 if the five minute CPU load average is below their respective limits, and 0 otherwise.

Usage examples

cpu_load_ok()
cpu_load_ok({hostname = "custom_host"})
cpu_load_ok({cpu_load5_limit = 0.8})
cpu_load_ok({hostname = "custom_host", cpu_load5_limit = 0.8})

memory_usage_ok()

Parameters

The function accepts an optional argument table with the following keys:

• Optional hostname: The name of the host. Defaults to the hostname of the selected host if not provided.
• Optional memory_usage_limit: The acceptable limit for the memory usage. Defaults to 0.9 if not provided.

Returns

The function returns 1 if the memory usage is below the limit, and 0 otherwise.

Usage examples

memory_usage_ok()
memory_usage_ok({hostname = "custom_host"})
memory_usage_ok({memory_usage_limit = 0.7})
memory_usage_ok({hostname = "custom_host", memory_usage_limit = 0.7})

interfaces_online()

Parameters

The function accepts an argument table with the following keys:

• Required interfaces: A string or a table of strings representing the network interfaces to check.
• Optional hostname: The name of the host. Defaults to the hostname of the selected host if not provided.

Returns

The function returns 1 if all the specified interfaces are online, and 0 otherwise.

Usage examples

interfaces_online({interfaces = "eth0"})
interfaces_online({interfaces = {"eth0", "eth1"}})
interfaces_online({hostname = "custom_host", interfaces = "eth0"})
interfaces_online({hostname = "custom_host", interfaces = {"eth0", "eth1"}})

health_check()

Parameters

The function accepts an optional argument table with the following keys:

• Required interfaces: A string or a table of strings representing the network interfaces to check.
• Optional hostname: The name of the host. Defaults to the hostname of the selected host if not provided.
• Optional cpu_load5_limit: The acceptable limit for the 5-minute CPU load. Defaults to 0.9 if not provided.
• Optional memory_usage_limit: The acceptable limit for the memory usage. Defaults to 0.9 if not provided.

Returns

The function returns 1 if all the specified interfaces are online, and 0 otherwise.

Usage examples

health_check({interfaces = "eths0"})
health_check({hostname = "custom_host", interfaces = "eths0"})
health_check({cpu_load5_limit = 0.7, memory_usage_limit = 0.8, interfaces = "eth0"})
health_check({hostname = "custom_host", cpu_load5_limit = 0.7, memory_usage_limit = 0.8, interfaces = {"eth0", "eth1"}})

2 - 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.

3 - 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.

4 - Session Translation Function

Specifies the body of a Lua function that inspects a newly created session and may override its suggested type from “initial” to “instream” or vice versa.

Returns nil when the session type is to remain unchanged, or Session(t) where t is a table with a single field:

• Type
  • Description: New type of the session.
  • Type: string
  • Example: 'instream', 'initial'

Example of a session_translation_function body that unconditionally makes all sessions 'instream':

-- Statements go here
print('Modifying session type')
return Session({['Type'] = 'instream'})

Arguments

The following (iterable) arguments are passed to the function:

Type

• Description: The suggested type of the session.
• Type: string
• Example: 'instream', 'initial'

Example usage:

-- Flip session type
local newType = 'initial'
if Type == 'initial' then
    newType = 'instream'
end
print('Changing session type from ' .. Type .. ' to ' .. newType)
return Session({['Type'] = newType})

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.

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 session

• session.client_ip
  • Description: Alias for request.client_ip. See documentation for request_translation_function.
• session.path_with_query_params
  • Description: Alias for request.path_with_query_params. See documentation for request_translation_function.
• session.path
  • Description: Alias for request.path. See documentation for request_translation_function.
• session.query_params
  • Description: Alias for request.query_params. See documentation for request_translation_function.
• session.filename
  • Description: Alias for request.filename. See documentation for request_translation_function.
• session.subnet
  • Description: Alias for request.subnet. See documentation for request_translation_function.
• session.host
  • Description: ID of the currently selected host for the session.
  • Type: string or nil
  • Example: 'host1'
• session.id
  • Description: ID of the session.
  • Type: string
  • Example: '8eb2c1bdc106-17d2ff-00000000'
• session.session_type
  • Description: Type of the session.
  • Type: string
  • Example: 'initial' or 'instream'. Identical to the value of the Type argument of the session translation function.
• session.is_managed
  • Description: Identifies managed sessions.
  • Type: boolean
  • Example: true if Type/session.session_type is 'instream'

Metatable session_groups

Defines a mapping from session group name to boolean, indicating whether the session belongs to the session group or not.

Example usage:

if session_groups.vod then print('vod') else print('not vod') end

or

if session_groups['vod'] then print('vod') else print('not vod') end

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 See documentation for request_translation_function. Values in the selection_input metatable will remain unchanged since a prior call to a request_translation_function.