# &adminguide;

## Overview

This module provides basic HTTP/1.0 server functionality inside &kamailio;. SIP and HTTP are very similar protocols, so, practically, the SIP parser can easily handle HTTP requests just by adding a fake Via header.

The xmlrpc module uses the same concept. The xHTTP module offers a generic way of handling the HTTP protocol, by calling event_route[xhttp:request] in your config. You can check the HTTP URL via the config variable $hu. Note that use of $ru will raise errors since the structure of an HTTP URL is not compatible with that of a SIP URI.

## Note on Latency

Because HTTP requests in xhttp are handled by the same, finite number of SIP worker processes that operate on SIP messages, the same general principles regarding script execution speed and throughput should be observed by the writer in event_route[xhttp:request] as in any other part of the route script.

For example, if you initiate a database query in the HTTP request route that takes a long time to return rows, the SIP worker process in which the request is handled will be blocked for that time and unable to process other SIP messages. In most typical installations, there are only a few of these worker processes running.

Therefore, it is highly inadvisable to execute particularly slow things in the event_route[xhttp:request], because the request is not handled in an asynchronous manner or otherwise peripherally to general SIP processing. SIP worker threads will block, pending the outcome of the event route just like any other config script route.

This is no more or less true for xhttp than it is for any other block of script in any other scenario, and does not warrant any extraordinary concern. It nevertheless bears mention here because some processes with embedded HTTP servers have the request processing take place "outside" of the main synchronous event sequence, whether by creating separate threads or by some other asynchronous handling. That is not the case with xhttp.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- sl - stateless reply.

### &kamailio; Core Settings

Related core settings:

- tcp_accept_no_cl=yes - SIP requires the Content-Length header for TCP transport. But most HTTP clients do not set the content length for normal GET requests. Therefore, the core must be configured to allow incoming requests without content length header.

- http_reply_parse=yes - various Kamailio modules may parse what it is sent out (e.g., for replication, topology management). In such case errors are printed if the outgoing message is not SIP and this parameter is not set.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None

## Parameters

### `url_skip` (str)

Regular expression to match the HTTP URL. If there is a match, the event route is not executed.

Default value is null (don't skip).

#### Set `url_skip` parameter

    ...
    modparam("xhttp", "url_skip", "^/RPC2")
    ...

### `url_match` (str)

Regular expression to match the HTTP URL. If there is no match, the event route is not executed. This check is done after url_skip, so if both url_skip and url_match would match then the event route is not executed (url_skip has higher priority).

Default value is null (match everything).

#### Set `url_match` parameter

    ...
    modparam("xhttp", "url_match", "^/sip/")
    ...

### `event_callback` (str)

The name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, ...) to be executed instead of event_route[xhttp:request] block.

The function has one string parameter with the value "xhttp:request".

Default value is 'empty' (no function is executed for events).

#### Set `event_callback` parameter

    ...
    modparam("xhttp", "event_callback", "ksr_xhttp_event")
    ...
    -- event callback function implemented in Lua
    function ksr_xhttp_event(evname)
    	KSR.info("===== xhttp module triggered event: " .. evname .. "\n");
    	return 1;
    end
    ...

## Functions

### `xhttp_reply(code, reason, ctype, body)`

Send back a reply with content-type and body.

#### `xhttp_reply` usage

    ...
    event_route[xhttp:request] {
        xhttp_reply("200", "OK", "text/html",
            "<html><body>OK - [$si:$sp]</body></html>");
    }
    ...

## Event Routes

### `xhttp:request`

The event route is executed when a new HTTP request is received. Most of the variables related to a SIP request can be used inside this event route to get HTTP request attributes (e.g., $si - source IP, $hdr(X) - body of header X, $rm - request method, $rb - request body, ...).

    ...
    tcp_accept_no_cl=yes
    ...
    loadmodule "sl.so"
    loadmodule "xhttp.so
    ...
    event_route[xhttp:request] {
        xhttp_reply("200", "OK", "text/html",
            "<html><body>OK - [$si:$sp]</body></html>");
    }
    ...