Module jls.net.http.HttpHandler

Provides HTTP handler class and utility functions.

An HTTP handler provides a way to deal with an HTTP request. Basicaly it consists in a function that will be called when an HTTP request has been received but before the request body was consumed.

Usage:

    local handler = HttpHandler:new(function(self, exchange)
  local response = exchange:getResponse()
  response:setBody('It works !')
end)

Class HttpHandler

HttpHandler:new ([fn]) Creates an HTTP handler.
httpHandler:handle (exchange) Handles the request for the specified exchange.
httpHandler:close () Closes this request handler.
HttpHandler.file (dir[, permissions[, filename]]) Exposes a file system directory.
HttpHandler.htmlFile (dir[, permissions[, filename]]) Exposes a file system directory.
HttpHandler.proxy () Proxies HTTP requests and responses.
HttpHandler.router (handlers) Creates a router HTTP handler.
HttpHandler.table (table[, path[, editable]]) Exposes a table content throught HTTP APIs.


Class HttpHandler

A HttpHandler class. The handler is called when the request headers are available.
HttpHandler:new ([fn])
Creates an HTTP handler.

Parameters:

  • fn function a function that will handle the HTTP exchange (optional)
httpHandler:handle (exchange)
Handles the request for the specified exchange.

Parameters:

  • exchange HttpExchange the HTTP exchange to handle

Returns:

    jls.lang.Promise a optional promise that resolves once the response is completed.
httpHandler:close ()
Closes this request handler. Do nothing by default. Must support to be called multiple times.
HttpHandler.file (dir[, permissions[, filename]])
Exposes a file system directory.

Parameters:

  • dir File the base directory or a ZIP file.
  • permissions string a string containing the granted permissions, 'rwxlcud' default is 'r'. (optional)
  • filename string the name of the file to use in case of GET request on a directory, default is 'index.html'. (optional)

Returns:

    HttpHandler a HttpHandler.
HttpHandler.htmlFile (dir[, permissions[, filename]])
Exposes a file system directory.

Parameters:

  • dir File the base directory or a ZIP file.
  • permissions string a string containing the granted permissions, 'rwxlcud' default is 'r'. (optional)
  • filename string the name of the file to use in case of GET request on a directory, default is 'index.html'. (optional)

Returns:

    HttpHandler a HttpHandler.
HttpHandler.proxy ()
Proxies HTTP requests and responses.

Returns:

    HttpHandler a HttpHandler.
HttpHandler.router (handlers)
Creates a router HTTP handler. This handler helps to expose REST APIs.

The handlers consists in a deep table of functions representing the resource paths, each table key represents a path component. The remainging path is available with the attribute path.
The function returned value is used for the HTTP response. A table will be returned as a JSON value. The returned value could also be the result of a jls.lang.Promise.
By default the request body is processed, a JSON value is available with the attribute requestJson, an XML value is available with the attribute requestXml.

Path component details:
An empty string is used as path component for the root resource.
The path component {abc} is used to match any value and to provide it in the attribute abc.
The path component {+} is used to process any value without resolving the path.
The path component could be followed by parenthesis to pass the corresponding exchange attributes as function arguments.
The path component could be followed by a question mark '?' to filter by the request method or header values.

Parameters:

  • handlers table the path handlers as a Lua table.

Returns:

    HttpHandler a HttpHandler.

Usage:

    local users = {}
httpServer:createContext('/(.*)', HttpHandler.router({
  users = {
    [''] = function(exchange)
      return users
    end,
    -- additional handler
    ['{+}?method=GET'] = function(exchange, userId)
      exchange:setAttribute('user', users[userId])
    end,
    ['{userId}'] = {
      ['(user)?method=GET'] = function(exchange, user)
        return user
      end,
      ['(userId, requestJson)?method=POST,PUT'] = function(exchange, userId, requestJson)
        users[userId] = requestJson
      end,
      -- will be available at /rest/users/{userId}/greetings
      ['greetings(user)?method=GET'] = function(exchange, user)
        return 'Hello '..user.firstname
      end
    },
  }
}))
HttpHandler.table (table[, path[, editable]])
Exposes a table content throught HTTP APIs. This handler allows to access and maintain a deep Lua table. The GET response is a JSON with a 'value' key containing the table path value.

Parameters:

  • table table the table.
  • path string the table base path. (optional)
  • editable boolean true to indicate that the table can be modified. (optional)

Returns:

    HttpHandler a HttpHandler.
generated by LDoc 1.5.0