modules_k/dispatcher: removed recently added modparams and added event_routes

- As per Daniel's suggestion, the module now uses libkcore/faked_msg and
  instead of parameters to specify routes when a destination goes up/down
  the module now calls the event_route[dispatcher:dst-up] and
  event_route[dispatcher:dst-down].

modules_k/dispatcher/Makefile

@@ -17,4 +17,5 @@ DEFS+=-DOPENSER_MOD_INTERFACE
 SERLIBPATH=../../lib
 SER_LIBS+=$(SERLIBPATH)/kmi/kmi
 SER_LIBS+=$(SERLIBPATH)/srdb1/srdb1
+SER_LIBS+=$(SERLIBPATH)/kcore/kcore
 include ../../Makefile.modules

modules_k/dispatcher/README

@@ -62,8 +62,6 @@ Carsten Bock
               3.25. ds_hash_expire (int)
               3.26. ds_hash_initexpire (int)
               3.27. ds_hash_check_interval (int)
-              3.28. ds_dst_unavailable_route (string)
-              3.29. ds_dst_available_route (string)
 
         4. Exported Functions
 
@@ -95,6 +93,11 @@ Carsten Bock
               7.1. Destination List File
               7.2. Kamailio config file
 
+        8. Event routes
+
+              8.1. dispatcher:dst-down
+              8.2. dispatcher:dst-up
+
    2. Frequently Asked Questions
 
    List of Examples
@@ -127,12 +130,10 @@ Carsten Bock
    1.26. Set the “ds_hash_expire” parameter
    1.27. Set the “ds_hash_initexpire” parameter
    1.28. Set the “ds_hash_check_interval” parameter
-   1.29. Set the “ds_dst_unavailable_route” parameter
-   1.30. Set the “ds_dst_available_route” parameter
-   1.31. ds_select_dst usage
-   1.32. ds_load_unset usage
-   1.33. dispatcher list file
-   1.34. Kamailio config script - sample dispatcher usage
+   1.29. ds_select_dst usage
+   1.30. ds_load_unset usage
+   1.31. dispatcher list file
+   1.32. Kamailio config script - sample dispatcher usage
 
 Chapter 1. Admin Guide
 
@@ -173,8 +174,6 @@ Chapter 1. Admin Guide
         3.25. ds_hash_expire (int)
         3.26. ds_hash_initexpire (int)
         3.27. ds_hash_check_interval (int)
-        3.28. ds_dst_unavailable_route (string)
-        3.29. ds_dst_available_route (string)
 
    4. Exported Functions
 
@@ -206,6 +205,11 @@ Chapter 1. Admin Guide
         7.1. Destination List File
         7.2. Kamailio config file
 
+   8. Event routes
+
+        8.1. dispatcher:dst-down
+        8.2. dispatcher:dst-up
+
 1. Overview
 
    This module offers SIP load balancer functionality and it can be used
@@ -269,8 +273,6 @@ Chapter 1. Admin Guide
    3.25. ds_hash_expire (int)
    3.26. ds_hash_initexpire (int)
    3.27. ds_hash_check_interval (int)
-   3.28. ds_dst_unavailable_route (string)
-   3.29. ds_dst_available_route (string)
 
 3.1. list_file (string)
 
@@ -654,48 +656,6 @@ Note
  modparam("dispatcher", "ds_hash_check_interval", 60)
  ...
 
-3.28. ds_dst_unavailable_route (string)
-
-   Optional parameter that specifies a route to run when a destination is
-   marked as PROBING. Destinations are marked PROBING after threshhold
-   number of OPTIONS ping failures or calls to ds_mark_dst("p").
-
-   This setting can be used to log desination failures. It may be used (in
-   conjunction with other modules like exec) to run external commands to
-   update NMC equipment, generate SNMP traps, and so on.
-
-   Default value is “null”.
-
-   Example 1.29. Set the “ds_dst_unavailable_route” parameter
- ...
- modparam("dispatcher", "ds_dst_unavailable_route", "DST_FAILED")
- ...
- route[DST_FAILED] {
-     xlog("L_ERR", "Destination failed: $rm $ru ($du)\n");
- }
- ...
-
-3.29. ds_dst_available_route (string)
-
-   Optional parameter that specifies a route to run when a destination
-   leaves the PROBING state. Destinations leave the PROBING state after an
-   OPTIONS ping succeeds.
-
-   This setting can be used to log desination recoveries. It may be used
-   (in conjunction with other modules like exec) to run external commands
-   to update NMC equipment, generate SNMP traps, and so on.
-
-   Default value is “null”.
-
-   Example 1.30. Set the “ds_dst_available_route” parameter
- ...
- modparam("dispatcher", "ds_dst_available_route", "DST_RESTORED")
- ...
- route[DST_RESTORED] {
-     xlog("L_ERR", "Destination restored: $rm $ru ($du)\n");
- }
- ...
-
 4. Exported Functions
 
    4.1. ds_select_dst(set, alg)
@@ -758,7 +718,7 @@ Note
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.31. ds_select_dst usage
+   Example 1.29. ds_select_dst usage
 ...
 ds_select_dst("1", "0");
 ...
@@ -855,7 +815,7 @@ ds_select_dst("1", "$var(a)");
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-   Example 1.32. ds_load_unset usage
+   Example 1.30. ds_load_unset usage
 ...
 route {
     ...
@@ -1019,7 +979,7 @@ setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
    For database, each element of a line resides in a different column.
    Next is a dispatcher.list file example:
 
-   Example 1.33. dispatcher list file
+   Example 1.31. dispatcher list file
 ...
 # $Id$
 # dispatcher destination sets
@@ -1044,7 +1004,7 @@ r,opt)
 
    Next picture displays a sample usage of dispatcher.
 
-   Example 1.34. Kamailio config script - sample dispatcher usage
+   Example 1.32. Kamailio config script - sample dispatcher usage
 ...
 # $Id$
 # sample config file for dispatcher module
@@ -1120,6 +1080,33 @@ failure_route[RTF_DISPATCH] {
 
 ...
 
+8. Event routes
+
+   8.1. dispatcher:dst-down
+   8.2. dispatcher:dst-up
+
+8.1.  dispatcher:dst-down
+
+   When defined, the module calls event_route[dispatcher:ds-down] when a
+   destination goes down (becomes probing). A typical use case is to
+   update NMC equipment as to the status of a destination.
+...
+event_route[dispatcher:dst-down] {
+    xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
+}
+...
+
+8.2.  dispatcher:dst-up
+
+   When defined, the module calls event_route[dispatcher:ds-up] when a
+   destination that was previously down (probing) comes up. A typical use
+   case is to update NMC equipment as to the status of a destination.
+...
+event_route[dispatcher:dst-up] {
+    xlog("L_ERR", "Destination up: $rm $ru\n");
+}
+...
+
 Chapter 2. Frequently Asked Questions
 
    2.1. Does dispatcher provide a fair distribution?

modules_k/dispatcher/dispatch.c

@@ -70,6 +70,7 @@
 #include "../../lib/srdb1/db_res.h"
 #include "../../str.h"
 #include "../../script_cb.h"
+#include "../../lib/kcore/faked_msg.h"
 
 #include "ds_ht.h"
 #include "api.h"
@@ -99,12 +100,10 @@ int *ds_list_nr = NULL;
 int *crt_idx    = NULL;
 int *next_idx   = NULL;
 
-int ds_tmp_msg_no = 1;
-
 #define _ds_list 	(ds_lists[*crt_idx])
 #define _ds_list_nr (*ds_list_nr)
 
-static void ds_run_route(struct sip_msg *msg, int route);
+static void ds_run_route(struct sip_msg *msg, char *route);
 
 void destroy_list(int);
 
@@ -2051,14 +2050,14 @@ int ds_set_state(int group, str *address, int state, int type, struct sip_msg *m
 			if(type)
 			{
 				if (state & DS_PROBING_DST && !(idx->dlist[i].flags & state))
-					ds_run_route(msg, ds_dst_unav_route);
+					ds_run_route(msg, "dispatcher:dst-down");
 
 				idx->dlist[i].flags |= state;
 			}
 			else
 			{
 				if (state & DS_PROBING_DST && idx->dlist[i].flags & state)
-					ds_run_route(msg, ds_dst_av_route);
+					ds_run_route(msg, "dispatcher:dst-up");
 
 				idx->dlist[i].flags &= ~state;
 
@@ -2072,30 +2071,30 @@ int ds_set_state(int group, str *address, int state, int type, struct sip_msg *m
 	return -1;
 }
 
-static void ds_run_route(struct sip_msg *msg, int route)
+static void ds_run_route(struct sip_msg *msg, char *route)
 {
-	int backup_route_type = get_route_type();
+	int rt, backup_rt = get_route_type();
+	struct run_act_ctx ctx;
 
 	LM_DBG("ds_run_route\n");
 
-	if (route == -1)
-		return;
-
-	if (exec_pre_script_cb(msg, LOCAL_CB_TYPE) == 0)
+	if (route == NULL)
 	{
-		LM_ERR("exec_pre_script_cb failed\n");
-		goto error;
+		LM_ERR("bad route\n");
+		return;
 	}
-	set_route_type(LOCAL_ROUTE);
-	if (run_top_route(main_rt.rlist[route], msg, 0) < 0)
+
+	rt = route_get(&event_rt, route);
+	if (rt < 0 || event_rt.rlist[rt] == NULL)
 	{
-		LM_ERR("run_top_route failed\n");
-		goto error;
+		LM_DBG("route does not exist");
+		return;
 	}
-	exec_post_script_cb(msg, LOCAL_CB_TYPE);
 
-error:
-	set_route_type(backup_route_type);
+	set_route_type(REQUEST_ROUTE);
+	init_run_actions_ctx(&ctx);
+	run_top_route(event_rt.rlist[rt], msg, 0);
+	set_route_type(backup_rt);
 }
 
 /**
@@ -2301,6 +2300,8 @@ static void ds_options_callback( struct cell *t, int type,
 {
 	int group = 0;
 	str uri = {0, 0};
+	struct sip_msg *fmsg;
+
 	/* The Param does contain the group, in which the failed host
 	 * can be found.*/
 	if (!*ps->param)
@@ -2324,13 +2325,19 @@ static void ds_options_callback( struct cell *t, int type,
 	 * We accept both a "200 OK" or the configured reply as a valid response */
 	if ((ps->code == 200) || ds_ping_check_rplcode(ps->code))
 	{
-		ds_tmp_msg.new_uri = uri;
-		ds_tmp_msg.id = ds_tmp_msg_no++;
-	
+		if (faked_msg_init() < 0)
+		{
+			LM_ERR("faked_msg_init() failed\n");
+			return;
+		}
+		fmsg = faked_msg_next();
+		fmsg->parsed_orig_ruri_ok = 0;
+		fmsg->new_uri = uri;
+
 		/* Set the according entry back to "Active":
 		 *  remove the Probing/Inactive Flag and reset the failure counter. */
 		if (ds_set_state(group, &uri,
-					DS_INACTIVE_DST|DS_PROBING_DST|DS_RESET_FAIL_DST, 2, &ds_tmp_msg) != 0)
+					DS_INACTIVE_DST|DS_PROBING_DST|DS_RESET_FAIL_DST, 2, fmsg) != 0)
 		{
 			LM_ERR("Setting the state failed (%.*s, group %d)\n", uri.len,
 					uri.s, group);
@@ -2339,9 +2346,16 @@ static void ds_options_callback( struct cell *t, int type,
 	if(ds_probing_mode==1 && ps->code == 408)
 	{
 
-		ds_tmp_msg.new_uri = uri;
-		ds_tmp_msg.id = ds_tmp_msg_no++;
-		if (ds_set_state(group, &uri, DS_PROBING_DST, 1, &ds_tmp_msg) != 0)
+		if (faked_msg_init() < 0)
+		{
+			LM_ERR("faked_msg_init() failed\n");
+			return;
+		}
+		fmsg = faked_msg_next();
+		fmsg->parsed_orig_ruri_ok = 0;
+		fmsg->new_uri = uri;
+
+		if (ds_set_state(group, &uri, DS_PROBING_DST, 1, fmsg) != 0)
 		{
 			LM_ERR("Setting the probing state failed (%.*s, group %d)\n",
 					uri.len, uri.s, group);

modules_k/dispatcher/dispatch.h

@@ -88,9 +88,6 @@ extern str ds_ping_from;
 extern int probing_threshhold; /*!< number of failed requests,
 						before a destination is taken into probing */ 
 extern int ds_probing_mode;
-extern struct sip_msg ds_tmp_msg;
-extern int ds_dst_unav_route;
-extern int ds_dst_av_route;
 
 int init_data(void);
 int init_ds_db(void);

modules_k/dispatcher/dispatcher.c

@@ -119,15 +119,6 @@ int ds_hash_size = 0;
 int ds_hash_expire = 7200;
 int ds_hash_initexpire = 7200;
 int ds_hash_check_interval = 30;
-char *ds_dst_unavailable_route = NULL;
-int ds_dst_unav_route = -1;
-char *ds_dst_available_route = NULL;
-int ds_dst_av_route = -1;
-
-#define DS_TMP_MSG "OPTIONS sip:[email protected] SIP/2.0\r\nVia: SIP/2.0/UDP 127.0.0.1\r\nFrom: <[email protected]>;tag=123\r\nTo: <[email protected]>\r\nCall-ID: 123\r\nCSeq: 1 OPTIONS\r\nContent-Length: 0\r\n\r\n"
-#define DS_TMP_MSG_LEN (sizeof(DS_TMP_MSG)-1)
-struct sip_msg ds_tmp_msg;
-char ds_tmp_msg_buf[DS_TMP_MSG_LEN + 1];
 
 /* tm */
 struct tm_binds tmb;
@@ -228,8 +219,6 @@ static param_export_t params[]={
 	{"ds_hash_expire",     INT_PARAM, &ds_hash_expire},
 	{"ds_hash_initexpire", INT_PARAM, &ds_hash_initexpire},
 	{"ds_hash_check_interval", INT_PARAM, &ds_hash_check_interval},
-	{"ds_dst_unavailable_route", STR_PARAM, &ds_dst_unavailable_route},
-	{"ds_dst_available_route", STR_PARAM, &ds_dst_available_route},
 	{0,0,0}
 };
 
@@ -481,8 +470,6 @@ static int mod_init(void)
 	/* Only, if the Probing-Timer is enabled the TM-API needs to be loaded: */
 	if (ds_ping_interval > 0)
 	{
-		int c;
-
 		/*****************************************************
 		 * TM-Bindings
 	  	 *****************************************************/
@@ -495,87 +482,6 @@ static int mod_init(void)
 		 * Register the PING-Timer
 		 *****************************************************/
 		register_timer(ds_check_timer, NULL, ds_ping_interval);
-
-		/* Build a temporary message for later use */
-		memcpy(ds_tmp_msg_buf, DS_TMP_MSG, DS_TMP_MSG_LEN);
-		ds_tmp_msg_buf[DS_TMP_MSG_LEN] = '\0';
-		memset(&ds_tmp_msg, 0, sizeof(struct sip_msg));
-		ds_tmp_msg.buf = ds_tmp_msg_buf;
-		ds_tmp_msg.len = DS_TMP_MSG_LEN;
-		ds_tmp_msg.set_global_address = default_global_address;
-		ds_tmp_msg.set_global_port = default_global_port;
-		if (parse_msg(ds_tmp_msg.buf, ds_tmp_msg.len, &ds_tmp_msg) != 0)
-		{
-			LM_ERR("parse_msg failed\n");
-			return -1;
-		}
-		ds_tmp_msg.parsed_orig_ruri = ds_tmp_msg.parsed_uri;
-		ds_tmp_msg.parsed_orig_ruri_ok = 0;
-
-		if (ds_dst_unavailable_route != NULL)
-		{
-			int length = strlen(ds_dst_unavailable_route);
-			c = ds_dst_unavailable_route[length];
-			ds_dst_unavailable_route[length] = '\0';
-			ds_dst_unav_route = route_get(&main_rt, ds_dst_unavailable_route);
-			ds_dst_unavailable_route[length] = c;
-
-			if (ds_dst_unav_route == -1)
-			{
-				LM_ERR("failed to determine destination unavailable route\n");
-				return -1;
-			}
-
-			if (main_rt.rlist[ds_dst_unav_route] == 0)
-			{
-				LM_WARN("route[%s] is empty\n", ds_dst_unavailable_route);
-				ds_dst_unav_route = -1;
-			}
-			else
-			{
-				LM_INFO("destination unavailable route: route[%s] (%d)\n",
-					ds_dst_unavailable_route, ds_dst_unav_route);
-			}
-
-		}
-		else
-		{
-			LM_INFO("No destination unavailable route configured\n");
-			ds_dst_unav_route = -1;
-		}
-
-		if (ds_dst_available_route != NULL)
-		{
-			int length = strlen(ds_dst_available_route);
-			c = ds_dst_available_route[length];
-			ds_dst_available_route[length] = '\0';
-			ds_dst_av_route = route_get(&main_rt, ds_dst_available_route);
-			ds_dst_available_route[length] = c;
-
-			if (ds_dst_av_route == -1)
-			{
-				LM_ERR("failed to determine destination available route\n");
-				return -1;
-			}
-
-			if (main_rt.rlist[ds_dst_av_route] == 0)
-			{
-				LM_WARN("route[%s] is empty\n", ds_dst_available_route);
-				ds_dst_av_route = -1;
-			}
-			else
-			{
-				LM_INFO("destination available route: route[%s] (%d)\n",
-					ds_dst_available_route, ds_dst_av_route);
-			}
-
-		}
-		else
-		{
-			LM_INFO("No destination available route configured\n");
-			ds_dst_av_route = -1;
-		}
-
 	}
 
 	return 0;

modules_k/dispatcher/doc/dispatcher_admin.xml

@@ -688,69 +688,7 @@ modparam("dispatcher", "force_dst", 1)
  </programlisting>
  		</example>
 	</section>
- 	<section>
- 		<title><varname>ds_dst_unavailable_route</varname> (string)</title>
- 		<para>
-		Optional parameter that specifies a route to run when a destination
-		is marked as PROBING.  Destinations are marked PROBING after threshhold
-                number of OPTIONS ping failures or calls to
-		<emphasis>ds_mark_dst("p")</emphasis>.
- 		</para>
-		<para>
-		This setting can be used to log desination failures.  It may be used
-		(in conjunction with other modules like <emphasis>exec</emphasis>) to
-		run external commands to update NMC equipment, generate SNMP traps,
-		and so on.
-		</para>
- 		<para>
- 		<emphasis>
- 			Default value is <quote>null</quote>.
- 		</emphasis>
- 		</para>
- 		<example>
- 		<title>Set the <quote>ds_dst_unavailable_route</quote> parameter</title>
- <programlisting format="linespecific">
- ...
- modparam("dispatcher", "ds_dst_unavailable_route", "DST_FAILED")
- ...
- route[DST_FAILED] {
-     xlog("L_ERR", "Destination failed: $rm $ru ($du)\n");
- }
- ...
- </programlisting>
- 		</example>
-	</section>
- 	<section>
- 		<title><varname>ds_dst_available_route</varname> (string)</title>
- 		<para>
-		Optional parameter that specifies a route to run when a destination
-		leaves the PROBING state.  Destinations leave the PROBING state after
-                an OPTIONS ping succeeds.
- 		</para>
-		<para>
-		This setting can be used to log desination recoveries.  It may be used
-		(in conjunction with other modules like <emphasis>exec</emphasis>) to
-		run external commands to update NMC equipment, generate SNMP traps,
-		and so on.
-		</para>
- 		<para>
- 		<emphasis>
- 			Default value is <quote>null</quote>.
- 		</emphasis>
- 		</para>
- 		<example>
- 		<title>Set the <quote>ds_dst_available_route</quote> parameter</title>
- <programlisting format="linespecific">
- ...
- modparam("dispatcher", "ds_dst_available_route", "DST_RESTORED")
- ...
- route[DST_RESTORED] {
-     xlog("L_ERR", "Destination restored: $rm $ru ($du)\n");
- }
- ...
- </programlisting>
- 		</example>
-	</section>
+
 	</section>
 
 	<section>
@@ -1307,5 +1245,45 @@ setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
 		</example>
 	</section>
 	</section>
+
+        <section>
+        <title>Event routes</title>
+        <section>
+                <title>
+                <function moreinfo="none">dispatcher:dst-down</function>
+                </title>
+                <para>
+			When defined, the module calls event_route[dispatcher:ds-down]
+			when a destination goes down (becomes probing). A typical use
+			case is to update NMC equipment as to the status of a destination.
+                </para>
+        <programlisting  format="linespecific">
+...
+event_route[dispatcher:dst-down] {
+    xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
+}
+...
+                </programlisting>
+	</section>
+        <section>
+                <title>
+                <function moreinfo="none">dispatcher:dst-up</function>
+                </title>
+                <para>
+			When defined, the module calls event_route[dispatcher:ds-up]
+			when a destination that was previously down (probing) comes up.
+			A typical use case is to update NMC equipment as to the status
+			of a destination.
+                </para>
+        <programlisting  format="linespecific">
+...
+event_route[dispatcher:dst-up] {
+    xlog("L_ERR", "Destination up: $rm $ru\n");
+}
+...
+                </programlisting>
+    </section>
+    </section>
+
 </chapter>