LuaFilter

The LuaFilter can be used for advanced rewriting of body data and/or headers of request and/or response.

A sample Lua script should visualize the idea:

function output(request, response, chunk)
    if chunk == nil then
        return "hello world"
    end
end

The Script.OutputFunctionName parameter must be "output". For every chunk of data from the backend, the script is called. The nil chunk marks the end of the stream. The sample script replaces the response body with "hello world". Beside the body data there are two objects "request" and "response" (of course you can name this different). With these two objects, you access headers, environment variables and attributes.

The LuaFilter can call a Lua function that is defined in the init parameter Script.OutputHeaderFunctionName. This function will be called once for every response before the body data, and can be used to add/set header attributes.

Example Lua script:

function outputHeader(req, resp)
    resp:setHeader("outputHeader","called")
end

More information

This chapter provides an introduction to the LuaFilter. For a detailed description of the nevisProxy LuaFilter, see the [LuaFilter Developer Guide]. For more details about Lua itself, see http://www.lua.org/manual/5.4/.

The LuaFilter currently supports version 5.3.

Classname

ch::nevis::isiweb4::filter::lua::LuaFilter

Library

libLuaFilter.so.1

Configuration

Script

Type: string
Usage Constraints: optional, basic

Lua script with implemented hook function. Be aware that every <, > and & must be HTML-encoded like <, >, &.

Script.Path

Type: string
Usage Constraints: optional, basic

Path to a Lua script file with implemented hook function(s).

Script.InputFunctionName

Type: string
Usage Constraints: optional, basic

Defines the Lua function name which is called on input. If the function name is not defined, nothing is called. The method's syntax expects three arguments:

• the request object
• the response object
• the request body chunk object

Script.InputHeaderFunctionName

Type: string
Usage Constraints: optional, basic

Defines the Lua function name which is called on input headers. This function does not need to deal with a possible request body. It is called once on every request. The method's syntax expects two arguments:

• the request object
• the response object

Script.OutputFunctionName

Type: string
Usage Constraints: optional, basic

Defines the Lua function name which is called on output. If the function name is not defined, nothing is called. The method's syntax expects three arguments:

• the request object
• the response object
• the response body chunk object

Script.OutputHeaderFunctionName

Type: string
Usage Constraints: optional, basic

Defines the Lua function name which is called on output headers. If it is not defined nothing is called. It is called once for every response. The method's syntax expects two arguments:

• the request object
• the response object.

Script.NotifySessionInvalidateFunctionName

Type: string
Usage Constraints: optional, advanced

Defines the function name which is called if a session is invalidated. For this function to be called, the LuaFilter has to be mapped to the same path as the filter which creates the session, e.g., the IdentityCreationFilter or AuthenticationFilter. The function has an input parameter of type session.

This feature is only supported when using the Dynamic Session Management Engine.

Script.GlobalStoreAttributeTimeoutFunctionName

Type: string
Usage Constraints: optional, advanced

Defines the function that will be called if an attribute in the global store expires. The called function has three input-parameters:

• the name of the expired attribute
• the value of the expired attribute
• the name of the servlet used for the global store

Script.Namespace

Type: string
Usage Constraints: optional, advanced

Define a namespace for filter attributes which will be propagated to the Lua script. The attributes are accessible in the Lua script with the prefixing namespace as global variables. Currently, dots are not allowed in the variable names.

Remarks about the content-length header

If the parameter Script.OutputFunctionName is set, then the content-length header coming from the backend will be removed. This happens because the LuaFilter does not know whether the body will remain unchanged.

If the parameter Script.InputFunctionName is set, the content-length header will NOT be removed because of security issues: The body coming from the frontend (usually from the user) must not be modified, because it may contain an amount to transfer, etc. If you want to modify the body anyway, then either remove the content-length header in the script or adapt the header to the new length.

The following code block illustrates the use of script namespacing:

Example for using script namespacing:

<filter>
    <filter-name>LuaFilterTest</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::lua::LuaFilter</filter-class>

    <init-param>
        <param-name>Script.Namespace</param-name>
        <param-value>My</param-value>
    </init-param>
    <init-param>
        <param-name>MyParameter</param-name>
        <param-value>my stuff</param-value>
    </init-param>
    <init-param>
        <param-name>Script.OutputFunctionName</param-name>
        <param-value>outputStream</param-value>
    </init-param>
    <init-param>
        <param-name>Script</param-name>
        <param-value>
            firstHit = false
            function outputStream(req, resp, chunk)
                trace = req:getTracer()
                if not firstHit then
                    firstHit = true
                    -- this should trace "This is my
                    -- parameter: my stuff"
                    trace:info("This is my parameter: "..MyParameter)
                end
                return chunk
            end
       </param-value>
    </init-param>
</filter>