8.7 Lua backends

Lua extensions can also be used to define new backends. Similarly to conditions, a function implementing a backend can have an arbitrary number of arguments. It is not supposed to return any values, though. Instead, before returning, it should define the response to be returned to the client. It does so by initializing fields of the internal variable http.resp:

code

This field must be assigned the HTTP status code (an integer value in the range 100 to 599). If it is not initialized after the backend function returns, pound will respond with the default ‘internal server error’ page.

reason

This is a textual reason corresponding to the status code. This value is optional. If not initialized, pound will use the default value for the returned status code, if it is one of the codes supported internally (see Error definitions). Otherwise the reason field will remain empty.

headers

A table of response HTTP headers.

body

Response body as a string.

Here is an example of Lua backend function. The function below can be used to return meaningful error status if the JWT authorization implemented in previous sections fails. It supposes that function bearer.ok, before returning on error, initializes stash fields ‘error’ and ‘error_description’ to the error code and textual description, correspondingly.

function bearer.error_backend()
   local text = 'Bearer realm="Restricted access"'
   if stash.bearer.error ~= nil then
      text = text .. ', error="' .. stash.bearer.error .. '"'
      if stash.bearer.error_description ~= nil then
         text = text .. ', error_description="' .. stash.bearer.error_description .. '"'
      end
   end

   http.resp.headers['WWW-Authenticate'] = text

   http.resp.code = 401
end

To use this backend, we modify the ‘auth’ service as follows:

Service "auth"
    Not LuaMatch "bearer.ok" "secret"
    LuaBackend "bearer.error_backend"
End