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. subject_queue_group (str)
5. Pseudo Variables
6. Event Routes

List of Examples

1.1. Set nats_url parameter
1.2. Set subject_queue_group parameter
1.3. Example usage of $natsData pseudo variable
1.4. 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.  subject_queue_group (str)

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

Usage: nats related.

Default value is not set.

Example 1.2.  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")
...

5. Pseudo Variables

Example 1.3. Example usage of $natsData pseudo variable

	...
	xlog("L_INFO", "received payload $natsData");
}

  • $natsData Contains the payload of a consumed message

6. 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.4. 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})");
	...
}