From fac0ebe4b1e145898b2f54a692039b5d69a67e0e Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Wed, 27 Apr 2016 10:28:42 +0200 Subject: [PATCH] nsg: added link to nsq.io in the docs - reformated the docbook --- modules/nsq/README | 72 ++-- modules/nsq/doc/nsq_admin.xml | 755 +++++++++++++++++----------------- 2 files changed, 414 insertions(+), 413 deletions(-) diff --git a/modules/nsq/README b/modules/nsq/README index 86f4cda4e05..40c7c03983e 100644 --- a/modules/nsq/README +++ b/modules/nsq/README @@ -43,14 +43,14 @@ Emmanuel Schmidbauer 4.1.9. consumer_workers(int) 4.1.10. topic_channel(str) - 4.2. presence related + 4.2. Presence Related 4.2.1. db_url(str) 4.2.2. presentity_table(str) 5. Functions - 5.1. presence related + 5.1. Presence Pelated 5.1.1. nsq_pua_publish(json_payload) @@ -105,14 +105,14 @@ Chapter 1. Admin Guide 4.1.9. consumer_workers(int) 4.1.10. topic_channel(str) - 4.2. presence related + 4.2. Presence Related 4.2.1. db_url(str) 4.2.2. presentity_table(str) 5. Functions - 5.1. presence related + 5.1. Presence Pelated 5.1.1. nsq_pua_publish(json_payload) @@ -121,10 +121,10 @@ Chapter 1. Admin Guide 1. Overview - The NSQ module an NSQ consumer. It exposes only consume capabilities - into Kamailio. + The module provides an NSQ consumer for Kamailio configuration file. + You can read more about NSQ at nsq.io. - From a high-level, the purpose of the module might be for things like: + From a high-level perspective, the module may be used for: * Provide a real-time integration into your program, instead of your database, so you can overlay additional logic in your preferred language while also utilizing a message bus @@ -170,39 +170,41 @@ modparam("nsq", "consumer_event_sub_key", "Event-Name") event_route[nsq:consumer-event-presence-update] { -# presence is the value extracted from Event-Category field in json payload -# update is the value extracted from Event-Name field in json payload -xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{kznsq -json,From})"); -... + # presence is the value extracted from Event-Category field in json payl +oad + # update is the value extracted from Event-Name field in json payload + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(ns +qE{kznsqjson,From})"); + ... } event_route[nsq:consumer-event-presence] { -# presence is the value extracted from Event-Category field in json payload -xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.j -son,From})"); -... + # presence is the value extracted from Event-Category field in json payl +oad + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(ns +qE{nsq.json,From})"); + ... } event_route[nsq:consumer-event-event-category-event-name] { -# event-category is the name of the consumer_event_key parameter -# event-name is the name of the consumer_event_sub_key parameter -# this event route is executed if we can't find the previous -... + # event-category is the name of the consumer_event_key parameter + # event-name is the name of the consumer_event_sub_key parameter + # this event route is executed if we can't find the previous + ... } event_route[nsq:consumer-event-event-category] { -# event-category is the name of the consumer_event_key parameter -# this event route is executed if we can't find the previous -... + # event-category is the name of the consumer_event_key parameter + # this event route is executed if we can't find the previous + ... } event_route[nsq:consumer-event] { -# this event route is executed if we can't find the previous + # this event route is executed if we can't find the previous } 2.2. aknowledge messages @@ -243,7 +245,7 @@ event_route[nsq:consumer-event] 4.1.9. consumer_workers(int) 4.1.10. topic_channel(str) - 4.2. presence related + 4.2. Presence Related 4.2.1. db_url(str) 4.2.2. presentity_table(str) @@ -367,7 +369,7 @@ modparam("nsq", "topic_channel", "My-NSQ-Topic:My-NSQ-Channel") modparam("nsq", "topic_channel", "My-NSQ-Topic-2:My-NSQ-Channel-2") ... -4.2. presence related +4.2. Presence Related 4.2.1. db_url(str) @@ -396,11 +398,11 @@ modparam("nsq", "presentity_table", "my_presentity_table") 5. Functions - 5.1. presence related + 5.1. Presence Pelated 5.1.1. nsq_pua_publish(json_payload) -5.1. presence related +5.1. Presence Pelated 5.1.1. nsq_pua_publish(json_payload) @@ -413,11 +415,11 @@ modparam("nsq", "presentity_table", "my_presentity_table") ... event_route[nsq:consumer-event-presence-update] { - xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{n -sq.json,From})"); - nsq_pua_publish($nsqE); - pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Packa -ge})", 1); + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(ns +qE{nsq.json,From})"); + nsq_pua_publish($nsqE); + pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-P +ackage})", 1); } ... @@ -434,7 +436,7 @@ ge})", 1); #nsq_json("$var(amqp_result)", "Channels[0].switch_url", "$du"); $du = $nsqE{nsq.json,Channels[0].switch_url}; if($du != $null) { - xlog("L_INFO", "$ci|log|user channels found redirecting call to $du"); - return; + xlog("L_INFO", "$ci|log|user channels found redirecting call to $du"); + return; } ... diff --git a/modules/nsq/doc/nsq_admin.xml b/modules/nsq/doc/nsq_admin.xml index 980c79a523b..0116c75d861 100644 --- a/modules/nsq/doc/nsq_admin.xml +++ b/modules/nsq/doc/nsq_admin.xml @@ -13,62 +13,63 @@ &adminguide; -
- Overview - The NSQ module an NSQ consumer. It exposes only consume capabilities into Kamailio. - - -From a high-level, the purpose of the module might be for things like: - - - -Provide a real-time integration into your program, instead of your database, so you can overlay additional logic in your preferred language while also utilizing a message bus - - - - -Utilize messaging to have a distributed messaging layer, such that machines processing requests/responses/events can go up/down or share the workload and your Kamailio node will still be happy - - - - - - - -supported operations are: - - - -subscribe to a Topic and Channel - - - - - -The NSQ module also has support to publish updates to presence module through the nsq_pua_publish function - - -
-
- How it works - -The module works with a main forked process that does the communication with NSQ for consuming messages. When it consumes a message it defers the process to a worker process so that it doesn't block this main process. - -
- event routes - -The worker process issues an event-route where we can act on the received payload. The name of the event-route is composed by values extracted from the payload. - - - NSQ module will try to execute the event route from most significant to less significant. - define the event route like event_route[nsq:consumer-event[-payload_key_value[-payload_subkey_value]]] - - - we can set the key/subkey pair on a subscription base. check the payload on subscribe. - - - define the event route - +
+ Overview + The module provides an NSQ consumer for &kamailio; configuration file. + You can read more about NSQ at nsq.io. + + + From a high-level perspective, the module may be used for: + + + + Provide a real-time integration into your program, instead of your database, so you can overlay additional logic in your preferred language while also utilizing a message bus + + + + + Utilize messaging to have a distributed messaging layer, such that machines processing requests/responses/events can go up/down or share the workload and your Kamailio node will still be happy + + + + + + + + supported operations are: + + + + subscribe to a Topic and Channel + + + + + + The NSQ module also has support to publish updates to presence module through the nsq_pua_publish function + + +
+
+ How it works + + The module works with a main forked process that does the communication with NSQ for consuming messages. When it consumes a message it defers the process to a worker process so that it doesn't block this main process. + +
+ event routes + + The worker process issues an event-route where we can act on the received payload. The name of the event-route is composed by values extracted from the payload. + + + NSQ module will try to execute the event route from most significant to less significant. + define the event route like event_route[nsq:consumer-event[-payload_key_value[-payload_subkey_value]]] + + + we can set the key/subkey pair on a subscription base. check the payload on subscribe. + + + define the event route + ... modparam("nsq", "consumer_event_key", "Event-Category") modparam("nsq", "consumer_event_sub_key", "Event-Name") @@ -76,416 +77,414 @@ modparam("nsq", "consumer_event_sub_key", "Event-Name") event_route[nsq:consumer-event-presence-update] { -# presence is the value extracted from Event-Category field in json payload -# update is the value extracted from Event-Name field in json payload -xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{kznsqjson,From})"); -... + # presence is the value extracted from Event-Category field in json payload + # update is the value extracted from Event-Name field in json payload + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{kznsqjson,From})"); + ... } event_route[nsq:consumer-event-presence] { -# presence is the value extracted from Event-Category field in json payload -xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})"); -... + # presence is the value extracted from Event-Category field in json payload + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})"); + ... } event_route[nsq:consumer-event-event-category-event-name] { -# event-category is the name of the consumer_event_key parameter -# event-name is the name of the consumer_event_sub_key parameter -# this event route is executed if we can't find the previous -... + # event-category is the name of the consumer_event_key parameter + # event-name is the name of the consumer_event_sub_key parameter + # this event route is executed if we can't find the previous + ... } event_route[nsq:consumer-event-event-category] { -# event-category is the name of the consumer_event_key parameter -# this event route is executed if we can't find the previous -... + # event-category is the name of the consumer_event_key parameter + # this event route is executed if we can't find the previous + ... } event_route[nsq:consumer-event] { -# this event route is executed if we can't find the previous + # this event route is executed if we can't find the previous } - -
-
- aknowledge messages - -Consumed messages have the option of being acknowledge in two ways: - - - -immediately when received - - - - -after processing by the worker - - - - - - -
-
- -
- Dependencies -
- &kamailio; Modules - - The following modules must be loaded before this module: - - - - none. - - - - -
-
- External Libraries or Applications - - - - libev. - - - - - libjson. - - - - - libevbuffsock. - - - - - libnsq. - - - - -
-
- - -
- Parameters -
- NSQ related -
- <varname>lookupd_address</varname>(str) - - The nsqlookupd address. - - - Default value is 127.0.0.1 - - - Set <varname>lookupd_address</varname> parameter - + +
+
+ aknowledge messages + + Consumed messages have the option of being acknowledge in two ways: + + + + immediately when received + + + + + after processing by the worker + + + + + + +
+
+ +
+ Dependencies +
+ &kamailio; Modules + + The following modules must be loaded before this module: + + + + none. + + + + +
+
+ External Libraries or Applications + + + + libev. + + + + + libjson. + + + + + libevbuffsock. + + + + + libnsq. + + + + +
+
+ + +
+ Parameters +
+ NSQ related +
+ <varname>lookupd_address</varname>(str) + + The nsqlookupd address. + + + Default value is 127.0.0.1 + + + Set <varname>lookupd_address</varname> parameter + ... modparam("nsq", "lookupd_address", "nsqlookupd.mydomain.com") ... - -
-
- <varname>lookupd_port</varname>(int) - - The nsqlookupd TCP port. - - - Default value is 4161. - - - Set <varname>lookupd_port</varname> parameter - + +
+
+ <varname>lookupd_port</varname>(int) + + The nsqlookupd TCP port. + + + Default value is 4161. + + + Set <varname>lookupd_port</varname> parameter + ... modparam("nsq", "lookupd_port", 4161) ... - - -
- -
- <varname>nsqd_address</varname>(str) - - The nsqd address. You can specify connecting directly to nsqd instead of using nsqlookupd. - - - Default value is 127.0.0.1 - - - Set <varname>nsqd_address</varname> parameter - + + +
+ +
+ <varname>nsqd_address</varname>(str) + + The nsqd address. You can specify connecting directly to nsqd instead of using nsqlookupd. + + + Default value is 127.0.0.1 + + + Set <varname>nsqd_address</varname> parameter + ... modparam("nsq", "nsqd_address", "nsqd.mydomain.com") ... - -
-
- <varname>nsqd_port</varname>(int) - - The nsqd TCP port. - - - Default value is 4150. - - - Set <varname>nsqd_port</varname> parameter - + +
+
+ <varname>nsqd_port</varname>(int) + + The nsqd TCP port. + + + Default value is 4150. + + + Set <varname>nsqd_port</varname> parameter + ... modparam("nsq", "nsqd_port", 4150) ... - -
- -
- <varname>consumer_use_nsqd</varname>(int) - - Set to 1 if you'd like to connect to nsqd instead of nsqlookupd. - - - Default value is 0. - - - Set <varname>consumer_use_nsqd</varname> parameter - + +
+ +
+ <varname>consumer_use_nsqd</varname>(int) + + Set to 1 if you'd like to connect to nsqd instead of nsqlookupd. + + + Default value is 0. + + + Set <varname>consumer_use_nsqd</varname> parameter + ... modparam("nsq", "consumer_use_nsqd", 1) ... - -
- -
- <varname>consumer_event_key</varname>(str) - - The default name of the field in json payload to compose the event name 1st part - - - Default value is Event-Category. - - - Set <varname>consumer_event_key</varname> parameter - + +
+ +
+ <varname>consumer_event_key</varname>(str) + + The default name of the field in json payload to compose the event name 1st part + + + Default value is Event-Category. + + + Set <varname>consumer_event_key</varname> parameter + ... modparam("nsq", "consumer_event_key", "My-JSON-Field-Name") ... - -
- -
- <varname>consumer_event_sub_key</varname>(str) - - The default name of the field in json payload to compose the event name 2nd part - - - Default value is Event-Name. - - - Set <varname>consumer_event_sub_key</varname> parameter - + +
+ +
+ <varname>consumer_event_sub_key</varname>(str) + + The default name of the field in json payload to compose the event name 2nd part + + + Default value is Event-Name. + + + Set <varname>consumer_event_sub_key</varname> parameter + ... modparam("nsq", "consumer_event_sub_key", "My-JSON-SubField-Name") ... - -
- -
- <varname>max_in_flight</varname>(int) - - The number of messages the consumer can receive before nsqd expects a response. - - - Default value is 1. - - - Set <varname>max_in_flight</varname> parameter - + +
+ +
+ <varname>max_in_flight</varname>(int) + + The number of messages the consumer can receive before nsqd expects a response. + + + Default value is 1. + + + Set <varname>max_in_flight</varname> parameter + ... modparam("nsq", "max_in_flight", 2) ... - -
- -
- <varname>consumer_workers</varname>(int) - - Number of consumer connections to NSQ per topic_channel. - - - Default value is 4. - - - Set <varname>consumer_workers</varname> parameter - + +
+ +
+ <varname>consumer_workers</varname>(int) + + Number of consumer connections to NSQ per topic_channel. + + + Default value is 4. + + + Set <varname>consumer_workers</varname> parameter + ... modparam("nsq", "consumer_workers", 2) ... - -
- -
- <varname>topic_channel</varname>(str) - - The NSQ Topic and Channel. Delimiter-separated by :. It be set multiple times to subscribe to multiple topics and channels. The value of consumer_workers is allocated per topic_channel. - - - Default value is Kamailio-Topic:Kamailio-Channel. - - - Set <varname>topic_channel</varname> parameter - + +
+ +
+ <varname>topic_channel</varname>(str) + + The NSQ Topic and Channel. Delimiter-separated by :. It be set multiple times to subscribe to multiple topics and channels. The value of consumer_workers is allocated per topic_channel. + + + Default value is Kamailio-Topic:Kamailio-Channel. + + + Set <varname>topic_channel</varname> parameter + ... modparam("nsq", "topic_channel", "My-NSQ-Topic:My-NSQ-Channel") modparam("nsq", "topic_channel", "My-NSQ-Topic-2:My-NSQ-Channel-2") ... - - -
- -
- - - -
- presence related -
- <varname>db_url</varname>(str) - - The database for the presentity table. - - If set, the nsq_pua_publish function will update the presentity status in the database. - - - Default value is NULL. - - - Set <varname>db_url</varname> parameter - + + +
+ +
+ +
+ Presence Related +
+ <varname>db_url</varname>(str) + + The database for the presentity table. + + If set, the nsq_pua_publish function will update the presentity status in the database. + + + Default value is NULL. + + + Set <varname>db_url</varname> parameter + ... modparam("nsq", "db_url", "&defaultdb;") ... - -
- -
- <varname>presentity_table</varname>(str) - - The name of the presentity table in the database. - - - Default value is presentity. - - - Set <varname>presentity_table</varname> parameter - + +
+ +
+ <varname>presentity_table</varname>(str) + + The name of the presentity table in the database. + + + Default value is presentity. + + + Set <varname>presentity_table</varname> parameter + ... modparam("nsq", "presentity_table", "my_presentity_table") ... - -
+ +
-
+
-
-
- Functions - -
- presence related -
- - <function moreinfo="none">nsq_pua_publish(json_payload)</function> - - - The function build presentity state from json_payload and updates presentity table. - - - This function can be used from ANY ROUTE. - - - - <function>nsq_pua_publish</function> usage - +
+
+ Functions + +
+ Presence Pelated +
+ + <function moreinfo="none">nsq_pua_publish(json_payload)</function> + + + The function build presentity state from json_payload and updates presentity table. + + + This function can be used from ANY ROUTE. + + + + <function>nsq_pua_publish</function> usage + ... event_route[nsq:consumer-event-presence-update] { - xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})"); - nsq_pua_publish($nsqE); - pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Package})", 1); + xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})"); + nsq_pua_publish($nsqE); + pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Package})", 1); } ... - -
- - -
- -
- -
- Exported pseudo-variables - - - - $nsqE - Contains the payload of a consumed message - - - -
- -
- Transformations - The prefix for nsq transformations is nsq. - - - json - - - <function>nsq.json</function> usage - + +
+ + +
+ +
+ +
+ Exported pseudo-variables + + + + $nsqE + Contains the payload of a consumed message + + + +
+ +
+ Transformations + The prefix for nsq transformations is nsq. + + + json + + + <function>nsq.json</function> usage + ... #nsq_json("$var(amqp_result)", "Channels[0].switch_url", "$du"); $du = $nsqE{nsq.json,Channels[0].switch_url}; if($du != $null) { - xlog("L_INFO", "$ci|log|user channels found redirecting call to $du"); - return; + xlog("L_INFO", "$ci|log|user channels found redirecting call to $du"); + return; } ... - + - + - -
+ +