ruxc_admin.xml

<?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 -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		The module exports utility functions based on libruxc.
	</para>
	<para>
		Among them are function to perform HTTP GET and POST queries.
	</para>
	<para>
		The ruxc project is available at:
		<ulink url="https://github.com/miconda/ruxc">https://github.com/miconda/ruxc</ulink>.
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be installed (but not loaded) to use this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<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>libruxc</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="ruxc.p.http_timeout">
		<title><varname>http_timeout</varname> (int)</title>
		<para>
		The interval in miliseconds after which the HTTP GET or POST query
		times out. It is the overall timeout, including DNS resolution, connecting
		time, redirects, and reading the response body. Slow DNS resolution
		may cause a request to exceed the timeout, because the DNS request
		cannot be interrupted with the available APIs. It takes precedence over
		http_timeout_read() and http_timeout_write(), but not http_timeout_connect.
		See also the comments in 'https://github.com/algesten/ureq/blob/main/src/agent.rs'.
		</para>
		<para>
		Use 0 to disable setting it in the library.
		</para>
		<para>
		<emphasis>
			Default value is 5000 (5 secs).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_timeout", 2000)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_timeout_connect">
		<title><varname>http_timeout_connect</varname> (int)</title>
		<para>
		The interval in miliseconds after which to give up on connecting to the
		HTTP/S server. If http_timeout is set, this one takes precedence. The
		library beneath has a default 30 seconds connect timeout.
		</para>
		<para>
		Use 0 to disable setting it in the library.
		</para>
		<para>
		<emphasis>
			Default value is 5000 (5 secs).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_timeout_connect</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_timeout_connect", 2000)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_timeout_read">
		<title><varname>http_timeout_read</varname> (int)</title>
		<para>
		The interval in miliseconds after which the read on HTTP/S connection
		socket timeouts. If http_timeout is set, it takes precedence.
		</para>
		<para>
		Use 0 to disable setting it in the library.
		</para>
		<para>
		<emphasis>
			Default value is 5000 (5 secs).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_timeout_read</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_timeout_read", 2000)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_timeout_write">
		<title><varname>http_timeout_write</varname> (int)</title>
		<para>
		The interval in miliseconds after which the write on HTTP/S connection
		socket timeouts. If http_timeout is set, it takes precedence.
		</para>
		<para>
		Use 0 to disable setting it in the library.
		</para>
		<para>
		<emphasis>
			Default value is 5000 (5 secs).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_timeout_write</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_timeout_write", 2000)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_tlsmode">
		<title><varname>http_tlsmode</varname> (int)</title>
		<para>
		The mode to connect over TLS to HTTPS sites: 0 accept all certificates;
		1 - accept trusted certificates.
		</para>
		<para>
		<emphasis>
			Default value is 0 (accept all certificates).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_tlsmode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_tlsmode", 1)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_reuse">
		<title><varname>http_reuse</varname> (int)</title>
		<para>
		Set to 1 in order to reuse the connection for all requests (each &kamailio;
		process has its own connection). Useful to avoid TCP connect (and TLS
		handshake) when all requests are performed against the same HTTP/S server.
		</para>
		<para>
		Set to 2 in order to keep connections per base URL (scheme://host:port)
		indexed in a hash map. Useful when doing HTTP/S requests to many
		servers.
		</para>
		<para>
		<emphasis>
			Default value is 0 (new connection for each request).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_reuse</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_reuse", 1)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_retry">
		<title><varname>http_retry</varname> (int)</title>
		<para>
		How many times to retry if the HTTP request does not get a 200 OK response.
		</para>
		<para>
		<emphasis>
			Default value is 0 (no retry).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_retry</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_retry", 2)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_logtype">
		<title><varname>http_logtype</varname> (int)</title>
		<para>
		Set the log type for libruxc http functions: 0 - stdout; 1 - syslog.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_logtype</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_logtype", 1)
...
</programlisting>
		</example>
	</section>
	<section id="ruxc.p.http_debug">
		<title><varname>http_debug</varname> (int)</title>
		<para>
		Set the debug mode for libruxc http functions: 0 - no debug; 1 - errors;
		2 - debug.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>http_debug</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("ruxc", "http_debug", 1)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
		<section id="ruxc.f.ruxc_http_get">
			<title>
				<function moreinfo="none">ruxc_http_get(url, hdrs, respv)</function>
			</title>
			<para>
				Perform a HTTP GET request to "url", storing the response body
				in the "respv" variable. The "hdrs" can be empty string
				to skip setting them. The first two parameters can contain
				variables that are evaluated at runtime. The "respv" has to be
				the name of a writable variable.
			</para>
			<para>
			The function returns response code of HTTP reply or negative value
			if something went wrong.
			</para>
			<para>
			This function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>ruxc_http_get()</function> usage</title>
				<programlisting format="linespecific">
...
ruxc_http_get("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
	   "", "X-Token: abc", "$var(result)");
switch ($rc) {
    ...
}
...
				</programlisting>
			</example>
		</section>
		<section id="ruxc.f.ruxc_http_post">
			<title>
				<function moreinfo="none">ruxc_http_post(url, body, hdrs, respv)</function>
			</title>
			<para>
				Perform a HTTP POST request to "url", storing the response body
				in the "respv" variable. The "body" and "hdrs" can be empty strings
				to skip setting them. The first three parameters can contain
				variables that are evaluated at runtime. The "respv" has to be
				the name of a writable variable.
			</para>
			<para>
			The function returns response code of HTTP reply or negative value
			if something went wrong.
			</para>
			<para>
			This function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>ruxc_http_post()</function> usage</title>
				<programlisting format="linespecific">
...
ruxc_http_post("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
	   "", "X-Token: abc", "$var(result)");
switch ($rc) {
    ...
}
...
				</programlisting>
			</example>
		</section>
		<section id="ruxc.f.ruxc_http_delete">
			<title>
				<function moreinfo="none">ruxc_http_delete(url, body, hdrs, respv)</function>
			</title>
			<para>
				Perform a HTTP DELETE request to "url", storing the response body
				in the "respv" variable. The "body" and "hdrs" can be empty strings
				to skip setting them. The first three parameters can contain
				variables that are evaluated at runtime. The "respv" has to be
				the name of a writable variable.
			</para>
			<para>
			The function returns response code of HTTP reply or negative value
			if something went wrong.
			</para>
			<para>
			This function can be used from ANY_ROUTE.
			</para>
			<example>
				<title><function>ruxc_http_delete()</function> usage</title>
				<programlisting format="linespecific">
...
ruxc_http_delete("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
	   "", "X-Token: abc", "$var(result)");
switch ($rc) {
    ...
}
...
				</programlisting>
			</example>
		</section>
	</section>
	<section id="ruxc.s.installation">
	<title>Installation</title>
	<para>
		The module needs "libruxc" library, which is provided by "ruxc" project
		from https://github.com/miconda/ruxc/. The library is
		implemented in Rust language, with generated C API and library. Until the
		libruxc is going to be packaged in OS distributions, the ruxc
		module can be compiled by copying ruxc.h and libruxc.a
		files in the folder of the module.
	</para>
	<para>
		To generate the libruxc.a file, it requires to have Rust language
		installed and its environment configured, then run the following commands:
	</para>
		<example>
		<title>Libruxc Usage</title>
		<programlisting format="linespecific">
...
git clone https://github.com/miconda/ruxc
cd ruxc
cargo build --release
cp include/ruxc.h target/release/libruxc.a \
    /path/to/kamailio/src/modules/ruxc/

cd /path/to/kamailio/
make include_modules="ruxc ..." cfg
make all
make install

## or compiling individual module for use inside source tree
# make modules modules=src/modules/ruxc
...
</programlisting>
		</example>
	<para>
		For more details about compilation and installation of libruxc, see:
		<ulink url="https://github.com/miconda/ruxc">https://github.com/miconda/ruxc</ulink>.
	</para>
	</section>

</chapter>