src/modules/ruxc/README
81de7878
 RUXC Module
 
 Daniel-Constantin Mierla
 
    asipto.com
    <miconda@gmail.com>
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
126f89e7
    Copyright © 2021 http://www.asipto.com
81de7878
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Parameters
 
               3.1. http_timeout (int)
a5821343
               3.2. http_tlsmode (int)
6ec588a7
               3.3. http_reuse (int)
81de7878
 
         4. Functions
 
               4.1. ruxc_http_get(url, hdrs, respv)
               4.2. ruxc_http_post(url, body, hdrs, respv)
 
         5. Installation
 
    List of Examples
 
    1.1. Set http_timeout parameter
a5821343
    1.2. Set http_tlsmode parameter
6ec588a7
    1.3. Set http_reuse parameter
    1.4. ruxc_http_get() usage
    1.5. ruxc_http_post() usage
    1.6. Libruxc Usage
81de7878
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Parameters
 
         3.1. http_timeout (int)
a5821343
         3.2. http_tlsmode (int)
6ec588a7
         3.3. http_reuse (int)
81de7878
 
    4. Functions
 
         4.1. ruxc_http_get(url, hdrs, respv)
         4.2. ruxc_http_post(url, body, hdrs, respv)
 
    5. Installation
 
 1. Overview
 
    The module exports utility functions based on libruxc.
 
    Among them are function to perform HTTP GET and POST queries.
 
    The ruxc project is available at: https://github.com/miconda/ruxc.
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
    The following modules must be installed (but not loaded) to use this
    module:
      * none.
 
 2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * libruxc.
 
 3. Parameters
 
    3.1. http_timeout (int)
a5821343
    3.2. http_tlsmode (int)
6ec588a7
    3.3. http_reuse (int)
81de7878
 
 3.1. http_timeout (int)
 
    The interval in miliseconds after which the HTTP GET or POST query
    times out.
 
    Default value is 5000 (5 secs).
 
    Example 1.1. Set http_timeout parameter
 ...
 modparam("ruxc", "http_timeout", 2000)
 ...
 
a5821343
 3.2. http_tlsmode (int)
 
    The mode to connect over TLS to HTTPS sites: 0 accept all certificates;
    1 - accept trusted certificates.
 
    Default value is 0 (accept all certificates).
 
    Example 1.2. Set http_tlsmode parameter
 ...
 modparam("ruxc", "http_tlsmode", 1)
 ...
 
6ec588a7
 3.3. http_reuse (int)
 
    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.
 
    Default value is 0 (new connection for each request).
 
    Example 1.3. Set http_reuse parameter
 ...
 modparam("ruxc", "http_reuse", 1)
 ...
 
81de7878
 4. Functions
 
    4.1. ruxc_http_get(url, hdrs, respv)
    4.2. ruxc_http_post(url, body, hdrs, respv)
 
126f89e7
 4.1.  ruxc_http_get(url, hdrs, respv)
81de7878
 
    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.
 
    The function returns response code of HTTP reply or negative value if
    something went wrong.
 
    This function can be used from ANY_ROUTE.
 
6ec588a7
    Example 1.4. ruxc_http_get() usage
81de7878
 ...
126f89e7
 ruxc_http_get("http://api.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(fu{s
 .escape.param})",
81de7878
            "", "X-Token: abc", "$var(result)");
 switch ($rc) {
     ...
 }
 ...
 
126f89e7
 4.2.  ruxc_http_post(url, body, hdrs, respv)
81de7878
 
    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.
 
    The function returns response code of HTTP reply or negative value if
    something went wrong.
 
    This function can be used from ANY_ROUTE.
 
6ec588a7
    Example 1.5. ruxc_http_post() usage
81de7878
 ...
 ruxc_http_post("http://api.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(fu{
 s.escape.param})",
            "", "X-Token: abc", "$var(result)");
 switch ($rc) {
     ...
 }
 ...
 
 5. Installation
 
    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.
 
    To generate the libruxc.a file, it requires to have Rust language
    installed and its environment configured, then run the following
    commands:
 
6ec588a7
    Example 1.6. Libruxc Usage
81de7878
 ...
 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
 ...
 
    For more details about compilation and installation of libruxc, see:
    https://github.com/miconda/ruxc.