NATS Module

Emmanuel Schmidbauer

   <eschmidbauer@gmail.com>

Joe Mordica

   <joe@voxo.co>

Edited by

Emmanuel Schmidbauer

   <eschmidbauer@gmail.com>

   Copyright © 2021 Voxcom Inc

   Copyright © 2021 VOXO
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. How it works
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. nats_url (str)
              4.2. num_publish_workers (int)
              4.3. subject_queue_group (str)
              4.4. event_callback (str)

        5. Functions

              5.1. nats_publish(subject, payload, reply)

        6. Pseudo Variables
        7. Event Routes

   List of Examples

   1.1. Set nats_url parameter
   1.2. Set num_publish_workers parameter
   1.3. Set subject_queue_group parameter
   1.4. Set event_callback parameter
   1.5. nats_publish usage
   1.6. Example usage of $natsData pseudo variable
   1.7. Define the event routes

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. How it works
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. nats_url (str)
        4.2. num_publish_workers (int)
        4.3. subject_queue_group (str)
        4.4. event_callback (str)

   5. Functions

        5.1. nats_publish(subject, payload, reply)

   6. Pseudo Variables
   7. Event Routes

1. Overview

   The module provides an NATS consumer for Kamailio. NATS is a real time
   distributed messaging platform, more details about it can be found at
   nats.io .

   From a high-level perspective, the module may be used for:
     * Provide a real-time distributed messaging layer in Kamailio

   Supported NATS operations are:
     * Subscribe to a Subject and Queue Group

2. How it works

   The module creates invokes a consumer process for each defined
   `subject_queue_group`. The messages are visible in event routes
   matching the "subject" name.

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none .

3.2. External Libraries or Applications

   The following libraries or applications must be installed
     * libuv
     * nats.c - https://github.com/nats-io/nats.c/releases

4. Parameters

   4.1. nats_url (str)
   4.2. num_publish_workers (int)
   4.3. subject_queue_group (str)
   4.4. event_callback (str)

4.1.  nats_url (str)

   The nats url.

   Usage: nats related.

   Default value is nats://127.0.0.1:4222

   Example 1.1.  Set nats_url parameter
...
modparam("nats", "nats_url", "nats://127.0.0.1:4222")
modparam("nats", "nats_url", "nats://user1:pass1@127.0.1.2:4222") // with auth
modparam("nats", "nats_url", "nats://127.1.2.3:4222")
...

4.2.  num_publish_workers (int)

   The number of worker threads for publishing messages.

   Usage: nats related.

   Default value is “2”.

   Example 1.2.  Set num_publish_workers parameter
...
modparam("nats", "num_publish_workers", 4)
...

4.3.  subject_queue_group (str)

   The NATS Subject and Queue Group. Separated by ":"

   Usage: nats related.

   Default value is not set.

   Example 1.3.  Set subject_queue_group parameter
...
modparam("nats", "subject_queue_group", "Kamailio-World:2020")
modparam("nats", "subject_queue_group", "Kamailio-World:2021") // this will crea
te two processes for the Kamailio-World subject
modparam("nats", "subject_queue_group", "MyQueue1:2021")
modparam("nats", "subject_queue_group", "MyQueue2:2021")
...

4.4.  event_callback (str)

   Name of the KEMI function to be executed instead of the event route.

   Default value is not set.

   Example 1.4.  Set event_callback parameter
...
modparam("nats", "event_callback", "ksr_nats_event")

-- event callback function implemented in Lua
function ksr_nats_event(evname)
        KSR.info("===== nats module received event: " .. evname ..
                ", data:" .. KSR.pv.gete('$natsData') .. "\n");
        return 1;
end
...

5. Functions

   5.1. nats_publish(subject, payload, reply)

5.1.  nats_publish(subject, payload, reply)

   Publishes the payload to subject, with an optional reply subject.

   Example 1.5.  nats_publish usage
...
$var(my_info) = "$ci=" + $ci + " $fU=" + $fU;
nats_publish("mysubject", "$var(my_info)"); # publish $var(my_info) to "mysubjec
t"

# publish $var(my_info) to "mysubject" with a reply.topic topic, so a response
# can be published back from the other side, like the NATS Request-Reply mode.
nats_publish("mysubject", "$var(my_info)", "reply.topic");
...

6. Pseudo Variables

   Example 1.6. Example usage of $natsData pseudo variable
        ...
        xlog("L_INFO", "received payload $natsData");
}

     * $natsData Contains the payload of a consumed message

7. Event Routes

   The worker process issues an event-route where we can act on the
   received payload. The name of the event-route name must match the
   subject of the message.

   Example 1.7. Define the event routes
...
modparam("nats", "subject_queue_group", "Kamailio-World:2021")
modparam("nats", "subject_queue_group", "MyQueue1:2021")
...

event_route[nats:Kamailio-World]
{
        if ($(natsData{json.parse,Event-Package}) == "dialog") {
                xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) u
pdate for $(natsData{json.parse,From})");
                pua_json_publish($natsData);
        }
}

event_route[nats:MyQueue1]
{
        xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update fo
r $(natsData{json.parse,From})");
        ...
}
