Browse code

nats: new nats message consumer module

Emmanuel Schmidbauer authored on 27/06/2021 11:58:58
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,207 @@
1
+<?xml version="1.0" encoding='ISO-8859-1'?>
2
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
3
+	<!-- Include general documentation entities -->
4
+	<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
5
+	%docentities;
6
+]>
7
+<!-- Module User's Guide -->
8
+
9
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
10
+	<title>&adminguide;</title>
11
+
12
+
13
+	<section>
14
+		<title>Overview</title>
15
+		<para>
16
+			The module provides an NATS consumer for &kamailio;.
17
+			NATS is a real time distributed messaging platform, more details about it
18
+			can be found at
19
+			<ulink url="https://nats.io">nats.io</ulink>
20
+			.
21
+		</para>
22
+		<para>
23
+			From a high-level perspective, the module may be used for:
24
+			<itemizedlist>
25
+				<listitem>
26
+					<para>
27
+						Provide a real-time distributed messaging layer in &kamailio;
28
+					</para>
29
+				</listitem>
30
+			</itemizedlist>
31
+		</para>
32
+
33
+
34
+		<para>
35
+			Supported NATS operations are:
36
+			<itemizedlist>
37
+				<listitem>
38
+					<para>
39
+						Subscribe to a Subject and Queue Group
40
+					</para>
41
+				</listitem>
42
+			</itemizedlist>
43
+		</para>
44
+
45
+	</section>
46
+	<section>
47
+		<title>How it works</title>
48
+		<para>
49
+			The module creates invokes a consumer process for each defined `subject_queue_group`. The messages are visible in event routes matching the "subject" name.
50
+		</para>
51
+	</section>
52
+
53
+	<section>
54
+		<title>Dependencies</title>
55
+		<section>
56
+			<title>&kamailio; Modules</title>
57
+			<para>
58
+				The following modules must be loaded before this module:
59
+				<itemizedlist>
60
+					<listitem>
61
+						<para>
62
+							<emphasis>none</emphasis>
63
+							.
64
+						</para>
65
+					</listitem>
66
+				</itemizedlist>
67
+			</para>
68
+		</section>
69
+		<section>
70
+			<title>External Libraries or Applications</title>
71
+			<para>
72
+				The following libraries or applications must be installed
73
+				<itemizedlist>
74
+					<listitem>
75
+						<para>
76
+							<emphasis>libuv</emphasis>
77
+						</para>
78
+					</listitem>
79
+					<listitem>
80
+						<para>
81
+							<emphasis>nats.c</emphasis>
82
+							-
83
+							<ulink url="https://github.com/nats-io/nats.c/releases">https://github.com/nats-io/nats.c/releases</ulink>
84
+						</para>
85
+					</listitem>
86
+				</itemizedlist>
87
+			</para>
88
+		</section>
89
+	</section>
90
+
91
+
92
+	<section>
93
+		<title>Parameters</title>
94
+		<section>
95
+			<title>
96
+				<varname>nats_url</varname>
97
+				(str)
98
+			</title>
99
+			<para>
100
+				The nats url.
101
+			</para>
102
+			<para>
103
+				Usage: nats related.
104
+			</para>
105
+			<para>
106
+				<emphasis>Default value is nats://127.0.0.1:4222</emphasis>
107
+			</para>
108
+			<example>
109
+				<title>
110
+					Set
111
+					<varname>nats_url</varname>
112
+					parameter
113
+				</title>
114
+				<programlisting format="linespecific">
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
+</programlisting>
121
+			</example>
122
+		</section>
123
+		<section>
124
+			<title>
125
+				<varname>subject_queue_group</varname>
126
+				(str)
127
+			</title>
128
+			<para>
129
+				The NATS Subject and Queue Group. Separated by ":"
130
+			</para>
131
+			<para>
132
+				Usage: nats related.
133
+			</para>
134
+			<para>
135
+				<emphasis>Default value is not set.</emphasis>
136
+			</para>
137
+			<example>
138
+				<title>
139
+					Set
140
+					<varname>subject_queue_group</varname>
141
+					parameter
142
+				</title>
143
+				<programlisting format="linespecific">
144
+...
145
+modparam("nats", "subject_queue_group", "Kamailio-World:2020")
146
+modparam("nats", "subject_queue_group", "Kamailio-World:2021") // this will create two processes for the Kamailio-World subject
147
+modparam("nats", "subject_queue_group", "MyQueue1:2021")
148
+modparam("nats", "subject_queue_group", "MyQueue2:2021")
149
+...
150
+				</programlisting>
151
+			</example>
152
+		</section>
153
+	</section>
154
+	<section>
155
+		<title>Pseudo Variables</title>
156
+		<itemizedlist>
157
+			<listitem>
158
+				<para>
159
+					<emphasis>$natsData</emphasis>
160
+					Contains the payload of a consumed message
161
+				</para>
162
+			</listitem>
163
+			<example>
164
+				<title>Example usage of $natsData pseudo variable</title>
165
+				<programlisting format="linespecific">
166
+	...
167
+	xlog("L_INFO", "received payload $natsData");
168
+}
169
+
170
+</programlisting>
171
+			</example>
172
+		</itemizedlist>
173
+	</section>
174
+
175
+	<section>
176
+		<title>Event Routes</title>
177
+		<para>
178
+				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.
179
+			</para>
180
+		<example>
181
+			<title>Define the event routes</title>
182
+			<programlisting format="linespecific">
183
+...
184
+modparam("nats", "subject_queue_group", "Kamailio-World:2021")
185
+modparam("nats", "subject_queue_group", "MyQueue1:2021")
186
+...
187
+
188
+event_route[nats:Kamailio-World]
189
+{
190
+	if ($(natsData{json.parse,Event-Package}) == "dialog") {
191
+		xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update for $(natsData{json.parse,From})");
192
+		pua_json_publish($natsData);
193
+	}
194
+}
195
+
196
+event_route[nats:MyQueue1]
197
+{
198
+	xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update for $(natsData{json.parse,From})");
199
+	...
200
+}
201
+
202
+</programlisting>
203
+		</example>
204
+	</section>
205
+
206
+
207
+</chapter>
0 208
\ No newline at end of file