Browse code

nats: added README file

Daniel-Constantin Mierla authored on 03/07/2021 09:15:38
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,173 @@
1
+NATS Module
2
+
3
+Emmanuel Schmidbauer
4
+
5
+   <eschmidbauer@gmail.com>
6
+
7
+Joe Mordica
8
+
9
+   <joe@voxo.co>
10
+
11
+Edited by
12
+
13
+Emmanuel Schmidbauer
14
+
15
+   <eschmidbauer@gmail.com>
16
+
17
+   Copyright � 2021 Voxcom Inc
18
+
19
+   Copyright � 2021 VOXO
20
+     __________________________________________________________________
21
+
22
+   Table of Contents
23
+
24
+   1. Admin Guide
25
+
26
+        1. Overview
27
+        2. How it works
28
+        3. Dependencies
29
+
30
+              3.1. Kamailio Modules
31
+              3.2. External Libraries or Applications
32
+
33
+        4. Parameters
34
+
35
+              4.1. nats_url (str)
36
+              4.2. subject_queue_group (str)
37
+
38
+        5. Pseudo Variables
39
+        6. Event Routes
40
+
41
+   List of Examples
42
+
43
+   1.1. Set nats_url parameter
44
+   1.2. Set subject_queue_group parameter
45
+   1.3. Example usage of $natsData pseudo variable
46
+   1.4. Define the event routes
47
+
48
+Chapter 1. Admin Guide
49
+
50
+   Table of Contents
51
+
52
+   1. Overview
53
+   2. How it works
54
+   3. Dependencies
55
+
56
+        3.1. Kamailio Modules
57
+        3.2. External Libraries or Applications
58
+
59
+   4. Parameters
60
+
61
+        4.1. nats_url (str)
62
+        4.2. subject_queue_group (str)
63
+
64
+   5. Pseudo Variables
65
+   6. Event Routes
66
+
67
+1. Overview
68
+
69
+   The module provides an NATS consumer for Kamailio. NATS is a real time
70
+   distributed messaging platform, more details about it can be found at
71
+   nats.io .
72
+
73
+   From a high-level perspective, the module may be used for:
74
+     * Provide a real-time distributed messaging layer in Kamailio
75
+
76
+   Supported NATS operations are:
77
+     * Subscribe to a Subject and Queue Group
78
+
79
+2. How it works
80
+
81
+   The module creates invokes a consumer process for each defined
82
+   `subject_queue_group`. The messages are visible in event routes
83
+   matching the "subject" name.
84
+
85
+3. Dependencies
86
+
87
+   3.1. Kamailio Modules
88
+   3.2. External Libraries or Applications
89
+
90
+3.1. Kamailio Modules
91
+
92
+   The following modules must be loaded before this module:
93
+     * none .
94
+
95
+3.2. External Libraries or Applications
96
+
97
+   The following libraries or applications must be installed
98
+     * libuv
99
+     * nats.c - https://github.com/nats-io/nats.c/releases
100
+
101
+4. Parameters
102
+
103
+   4.1. nats_url (str)
104
+   4.2. subject_queue_group (str)
105
+
106
+4.1. nats_url (str)
107
+
108
+   The nats url.
109
+
110
+   Usage: nats related.
111
+
112
+   Default value is nats://127.0.0.1:4222
113
+
114
+   Example 1.1. Set nats_url parameter
115
+...
116
+modparam("nats", "nats_url", "nats://127.0.0.1:4222")
117
+modparam("nats", "nats_url", "nats://user1:pass1127.0.1.2:4222") // with auth
118
+modparam("nats", "nats_url", "nats://127.1.2.3:4222")
119
+...
120
+
121
+4.2. subject_queue_group (str)
122
+
123
+   The NATS Subject and Queue Group. Separated by ":"
124
+
125
+   Usage: nats related.
126
+
127
+   Default value is not set.
128
+
129
+   Example 1.2. Set subject_queue_group parameter
130
+...
131
+modparam("nats", "subject_queue_group", "Kamailio-World:2020")
132
+modparam("nats", "subject_queue_group", "Kamailio-World:2021") // this will crea
133
+te two processes for the Kamailio-World subject
134
+modparam("nats", "subject_queue_group", "MyQueue1:2021")
135
+modparam("nats", "subject_queue_group", "MyQueue2:2021")
136
+...
137
+
138
+5. Pseudo Variables
139
+
140
+   Example 1.3. Example usage of $natsData pseudo variable
141
+        ...
142
+        xlog("L_INFO", "received payload $natsData");
143
+}
144
+
145
+     * $natsData Contains the payload of a consumed message
146
+
147
+6. Event Routes
148
+
149
+   The worker process issues an event-route where we can act on the
150
+   received payload. The name of the event-route name must match the
151
+   subject of the message.
152
+
153
+   Example 1.4. Define the event routes
154
+...
155
+modparam("nats", "subject_queue_group", "Kamailio-World:2021")
156
+modparam("nats", "subject_queue_group", "MyQueue1:2021")
157
+...
158
+
159
+event_route[nats:Kamailio-World]
160
+{
161
+        if ($(natsData{json.parse,Event-Package}) == "dialog") {
162
+                xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) u
163
+pdate for $(natsData{json.parse,From})");
164
+                pua_json_publish($natsData);
165
+        }
166
+}
167
+
168
+event_route[nats:MyQueue1]
169
+{
170
+        xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update fo
171
+r $(natsData{json.parse,From})");
172
+        ...
173
+}