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 .

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://

Example 1.1.  Set nats_url parameter

modparam("nats", "nats_url", "nats://")
modparam("nats", "nats_url", "nats://user1:pass1127.0.1.2:4222") // with auth
modparam("nats", "nats_url", "nats://")

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)"===== nats module received event: " .. evname ..
		", data:" .. KSR.pv.gete('$natsData') .. "\n");
	return 1;

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

	if ($(natsData{json.parse,Event-Package}) == "dialog") {
		xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update for $(natsData{json.parse,From})");

	xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update for $(natsData{json.parse,From})");