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. By default the request body is processed and the JSON value is available with the attribute requestJson.

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 a jls.lang.Promise.

An empty string is used as table key for the root resource. The special table key {name} is used to match any key and provide the value in the attribue name.

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