src/modules/xhttp/doc/xhttp_admin.xml
bdba8801
 <?xml version="1.0" encoding='ISO-8859-1'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!-- Include general documentation entities -->
6deb5fcf
 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
bdba8801
 %docentities;
 
 ]>
 <!-- Module User's Guide -->
 
 <chapter>
06ba0b3c
 
bdba8801
 	<title>&adminguide;</title>
06ba0b3c
 
bdba8801
 	<section>
 	<title>Overview</title>
 	<para>
06ba0b3c
 		This module provides basic HTTP/1.0 server functionality inside
ad94c568
 		&kamailio;. SIP and HTTP are very similar protocols, so, practically, the
b5205012
 		SIP parser can easily handle HTTP requests just by adding a fake
bdba8801
 		Via header.
 	</para>
 	<para>
ad94c568
 		The <module>xmlrpc</module> module uses the same concept.
 		The xHTTP module offers a generic way of handling the <acronym>HTTP</acronym>
 		protocol, by calling <emphasis>event_route[xhttp:request]</emphasis>
 		in your config. You can check the HTTP URL via the config variable
 		<acronym>$hu</acronym>. Note that use of <acronym>$ru</acronym> will
 		raise errors since the structure of an HTTP URL is not compatible with
 		that of a SIP URI.
bdba8801
 	</para>
 	</section>
6bd9d264
 
 	<section>
 	<title>Note on Latency</title>
 	<para>
 		Because HTTP requests in <emphasis>xhttp</emphasis> are handled
06ba0b3c
 		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
6bd9d264
 		<emphasis>event_route[xhttp:request]</emphasis> as in any other
06ba0b3c
 		part of the route script.
6bd9d264
 	</para>
 	<para>
 		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
06ba0b3c
 		the request is handled will be blocked for that time and unable to
6bd9d264
 		process other SIP messages.  In most typical installations, there are
06ba0b3c
 		only a few of these worker processes running.
6bd9d264
 	</para>
 	<para>
 		Therefore, it is highly inadvisable to execute particularly slow things in the
06ba0b3c
 		<emphasis>event_route[xhttp:request]</emphasis>, 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.
6bd9d264
 	</para>
ad94c568
 	<para>
06ba0b3c
 		This is no more or less true for <emphasis>xhttp</emphasis> 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
6bd9d264
 		separate threads or by some other asynchronous handling.  That is not the
 		case with <emphasis>xhttp</emphasis>.
 	</para>
 	</section>
 
bdba8801
 	<section>
 	<title>Dependencies</title>
 	<section>
 		<title>&kamailio; Modules</title>
 		<para>
 		The following modules must be loaded before this module:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>sl</emphasis> - stateless reply.
 			</para>
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
c386968d
 	<section>
 		<title>&kamailio; Core Settings</title>
 		<para>
 		SIP requires a 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:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>tcp_accept_no_cl=yes</emphasis>
 			</para>
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
bdba8801
 	<section>
 		<title>External Libraries or Applications</title>
 		<para>
 		The following libraries or applications must be installed before running
 		&kamailio; with this module loaded:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>None</emphasis>
 			</para>
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
 	</section>
 	<section>
9114eebc
 	<title>Parameters</title>
06ba0b3c
 	<section id="xhttp.p.url_skip">
666c83e9
 		<title><varname>url_skip</varname> (str)</title>
 		<para>
b5205012
 			Regular expression to match the HTTP URL. If there is a match,
ad94c568
 			the event route is not executed.
666c83e9
 		</para>
 		<para>
 		<emphasis>
 			Default value is null (don't skip).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>url_skip</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("xhttp", "url_skip", "^/RPC2")
 ...
 </programlisting>
 		</example>
 	</section>
06ba0b3c
 	<section id="xhttp.p.url_match">
bdba8801
 		<title><varname>url_match</varname> (str)</title>
 		<para>
b5205012
 			Regular expression to match the HTTP URL. If there is no match,
ad94c568
 			the event route is not executed. This check is done after
666c83e9
 			url_skip, so if both url_skip and url_match would match then
 			the event route is not executed (url_skip has higher priority).
bdba8801
 		</para>
 		<para>
 		<emphasis>
 			Default value is null (match everything).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>url_match</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("xhttp", "url_match", "^/sip/")
 ...
 </programlisting>
 		</example>
 	</section>
450c9eb2
 	<section id="xhttp.p.event_callback">
 		<title><varname>event_callback</varname> (str)</title>
 		<para>
 			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.
 		</para>
 		<para>
 			The function has one string parameter with the value "xhttp:request".
 		</para>
 		<para>
 		<emphasis>
 			Default value is 'empty' (no function is executed for events).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>event_callback</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 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
 ...
1abb2fb0
 </programlisting>
 	    </example>
 	</section>
bdba8801
 	</section>
 
 	<section>
9114eebc
 	<title>Functions</title>
06ba0b3c
 	<section id="xhttp.f.xhttp_reply">
bdba8801
 	    <title>
 		<function moreinfo="none">xhttp_reply(code, reason, ctype, body)</function>
 	    </title>
 	    <para>
 		Send back a reply with content-type and body.
 	    </para>
 		<example>
 		<title><function>xhttp_reply</function> usage</title>
 		<programlisting format="linespecific">
 ...
 event_route[xhttp:request] {
     xhttp_reply("200", "OK", "text/html",
         "&lt;html&gt;&lt;body&gt;OK - [$si:$sp]&lt;/body&gt;&lt;/html&gt;");
 }
 ...
 </programlisting>
 	    </example>
 	</section>
 	</section>
bec6357b
 
     <section>
     <title>Event Routes</title>
     <section id="xhttp.evr.request">
         <title>
         <function moreinfo="none">xhttp:request</function>
         </title>
         <para>
 			The event route is executed when a new HTTP request is received.
         </para>
         <programlisting  format="linespecific">
 ...
195de260
 tcp_accept_no_cl=yes
 ...
 loadmodule "sl.so"
 loadmodule "xhttp.so
 ...
bec6357b
 event_route[xhttp:request] {
     xhttp_reply("200", "OK", "text/html",
         "&lt;html&gt;&lt;body&gt;OK - [$si:$sp]&lt;/body&gt;&lt;/html&gt;");
 }
 ...
         </programlisting>
 	</section>
 	</section>
bdba8801
 </chapter>