Basic HTTP module

To handle HTTP requests a module adds a HTTP provider. A minimal example would be:

-- Ensure that mod_http is loaded:
module:depends("http");
 
-- Now publish our HTTP 'app':
module:provides("http", {
    route = {
        ["GET"] = function () return "Hello world!"; end;
    };
});

Each module's paths are automatically based at http(s)://prosody/<app-name>. The app name defaults to the module's name with the mod_ or mod_http_ prefix automatically removed. You can override this by specifying a 'name' field in your provider object, but this is not recommended.

Therefore if the above code were in mod_http_hello.lua, we would be able to see "Hello world!" at http://prosody:5280/hello and https://prosody:5281/hello.

Note that by default the unencrypted http:// port (5280) is only accessible on localhost, and Prosody will prefer the https:// URL by default. The precise URL used by any given module can be altered by Prosody’s HTTP server configuration. Taking all this into account, a module can discover its own URL by calling module:http_url():

module:depends("http");
module:log("info", "Hello! You can reach me at: %s", module:http_url());

Routes

The keys of the 'route' table specify the HTTP method to handle, and optionally a path relative to the module's base path. If no path is specified then it is equal to the module's base path (e.g. /hello).

Some examples:

    route = {
        -- /hello
        ["GET"] = function () return "Hello world!"; end;
        ["POST"] = function () return "Thank you for your data!"; end;
        -- /hello/goodbye
        ["GET /goodbye"] = function () return "You say goodbye, and I say hello."; end;
    }

It is also possible to set wildcard routes, these will be discussed a little later after we have looking at how handlers work. We'll also see how to handle the received data (e.g. from the POST above) next.

Handler functions

The handler function by default receives an event object, with at least two fields, 'request' and 'response'.

event.request = {
    headers = {
        host = "example.com";
        <...>
    };
    path = "/hello"; -- Full path, including base path
    url = {
        path = "/hello"; -- Same as above
        query = "foo=bar"; -- For /hello?foo=bar
    };
    method = "POST"; -- The HTTP method used, GET/POST/HEAD/etc.
    body = "raw-body";
    conn = <net.server connection object>;
    secure = false; -- true if connection encrypted
}

event.response = {
    status_code = 200;
    headers = {
        content_type = "text/html; charset=utf-8";
    };
}

Wildcard routes

It is possible for a single handler to receive not just a single path, but all paths below it. This is done with a wildcard route:

    route = {
        ["GET /data/*"] = function (event, path) return "Hello from "..path.."!"; end;
        ["POST /data/submit"] = function (event) return "Thank you for your data!"; end;
    };

You'll notice in the example above that handlers for wildcard routes receive an extra parameter. This is the part of the path that matched the wildcard. This is useful, because it already has the module's arbitrary base path stripped from it (unlike request.path).

Another thing to note is that if a non-wildcard route is given for a path, it will take priority over wildcard routes that might otherwise match the path. As above, you can choose not to handle a request and the next handler (such as a wildcard handler) answer it by returning nothing from your handler function.

Serving files

If your module needs to serve static resources, you can use net.http.files. It exposes a serve() function that returns a handler you can use in routes.

local serve = require"net.http.files".serve;
module:provides("http", {
    route = {
        ["GET /"] = function() return "Hello" end;
        ["GET /a_file.txt"] = serve(module:get_directory().."/my_file.txt");
        ["GET /static/*"] = serve{
          path ="/path/to/some/stuff";
          directory_index = true; -- Allow listing files
          index_files = { "index.html" };
        };
    };
});

It automatically handles both plain and wildcard routes. Note that net.http.files does not generate a file listings by itself, but depends on another module handling that, such as mod_http_dir_listing from prosody-modules.