# &adminguide;

## 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

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none .

### External Libraries or Applications

The following libraries or applications must be installed

- libuv

- nats.c - https://github.com/nats-io/nats.c/releases

## Parameters

### `nats_url` (str)

The nats url.

Usage: nats related.

Default value is nats://127.0.0.1:4222

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

### `num_publish_workers` (int)

The number of worker threads for publishing messages.

Usage: nats related.

Default value is 2.

#### Set `num_publish_workers` parameter

    ...
    modparam("nats", "num_publish_workers", 4)
    ...

### `subject_queue_group` (str)

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

Usage: nats related.

Default value is not set.

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

### `event_callback` (str)

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

Default value is not set.

#### 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
    ...

## Functions

### `nats_publish(subject, payload, reply)`

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

#### `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");
    ...

## Pseudo Variables

- $natsData Contains the payload of a consumed message

### Example usage of $natsData pseudo variable

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

## 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.

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