NATS Module

Emmanuel Schmidbauer

Joe Mordica

Edited by

Emmanuel Schmidbauer


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

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

The following modules must be loaded before this module:

  • none .

3.2. External Libraries or Applications

The following libraries or applications must be installed

4. Parameters

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:pass1127.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 create 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)

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 "mysubject"

# 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}) update for $(natsData{json.parse,From})");
		pua_json_publish($natsData);
	}
}

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