Mercurial > hg > waaad

changeset 29:48cd40f27f3f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added more information about routing, still incomplete
author Sebastien Decugis <sdecugis@nict.go.jp>
date Thu, 19 Jun 2008 12:17:13 +0900
parents fce953f1439d
children 5b4d7c388d70
files include/waaad/dictionary-api.h include/waaad/message-api.h include/waaad/peer-api.h include/waaad/routing-api.h include/waaad/waaad.h waaad/Makefile.am waaad/extensions.c waaad/main.c waaad/routing.c waaad/routing.h waaad/waaad-internal.h
diffstat 11 files changed, 319 insertions(+), 11 deletions(-) [+]
line wrap: on
line diff
--- a/include/waaad/dictionary-api.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/include/waaad/dictionary-api.h	Thu Jun 19 12:17:13 2008 +0900
@@ -83,7 +83,6 @@
  * RETURN VALUE:
  *  0      	: The object is created in the dictionary.
  *  EINVAL 	: A parameter is invalid.
- *  EPERM  	: The dictionary has not been initialized yet (must call dict_init () -- only for daemon)
  *  EEXIST 	: This object is already defined in the dictionary. 
  *                If "ref" is not NULL, it points to the existing element on return.
  *  (other standard errors may be returned, too, with their standard meaning. Example:
--- a/include/waaad/message-api.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/include/waaad/message-api.h	Thu Jun 19 12:17:13 2008 +0900
@@ -195,7 +195,6 @@
  * RETURN VALUE:
  *  0      	: The message is created.
  *  EINVAL 	: A parameter is invalid.
- *  EPERM  	: The message module has not been initialized yet (must call msg_init () -- only for daemon)
  *  (other standard errors may be returned, too, with their standard meaning. Example:
  *    ENOMEM 	: Memory allocation for the new message failed.)
  */
@@ -215,7 +214,6 @@
  * RETURN VALUE:
  *  0      	: The AVP is created.
  *  EINVAL 	: A parameter is invalid.
- *  EPERM  	: The message module has not been initialized yet (must call msg_init () -- only for daemon)
  *  (other standard errors may be returned, too, with their standard meaning. Example:
  *    ENOMEM 	: Memory allocation for the new avp failed.)
  */
@@ -352,7 +350,7 @@
 
 #endif /* ! IN_EXTENSION */
 
-/* The version of this API, to check binary compatibility -- increment each time a change is made in api_peer_t */
+/* The version of this API, to check binary compatibility -- increment each time a change is made in api_msg_t */
 #define WAAAD_API_MSG_VER	1
 
 /* Now define the type of the structure that contains the callback to pass to extensions */
--- a/include/waaad/peer-api.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/include/waaad/peer-api.h	Thu Jun 19 12:17:13 2008 +0900
@@ -108,7 +108,6 @@
  * RETURN VALUE:
  *  0      	: The peer is added.
  *  EINVAL 	: A parameter is invalid.
- *  EPERM  	: The peer module has not been initialized yet (must call peer_init () -- only for daemon)
  *  EEXIST 	: A peer with the same Diameter-Id is already in the list.
  *  (other standard errors may be returned, too, with their standard meaning. Example:
  *    ENOMEM 	: Memory allocation for the new object element failed.)
@@ -131,7 +130,6 @@
  * RETURN VALUE:
  *  0      	: The peer is added.
  *  EINVAL 	: A parameter is invalid.
- *  EPERM  	: The peer module has not been initialized yet (must call peer_init () -- only for daemon)
  *  EEXIST 	: A peer with the same Diameter-Id is already in the list.
  *  (other standard errors may be returned, too, with their standard meaning. Example:
  *    ENOMEM 	: Memory allocation for the new object element failed.)
--- a/include/waaad/routing-api.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/include/waaad/routing-api.h	Thu Jun 19 12:17:13 2008 +0900
@@ -34,7 +34,47 @@
 *********************************************************************************************************/
 
 /* This file contains the definitions of types and functions involved in the routing decisions in waaad,
- and that can be called by extensions. */
+ * and that can be called by extensions. 
+ *
+ * Three different processing can be distinguished:
+ *  - Messages received, and the peer is final recipient (IN messages)
+ *  - Messages received, and the peer is not final recipient (FWD messages)
+ *  - Message is locally generated (OUT messages)
+ *
+ * There are three global message queues (declared in queues.h) and peers-specific queues (in peer.h).
+ *
+ * (*) IN messages processing details:
+ *   - the message is received in a peer.
+ *   - after some checks, the message is put in the global "incoming" queue, with associated metadata.
+ *   - a daemon thread (routing-in) makes the decision if the message is handled locally or forwarded, 
+ *     based on local capabilities (registered by extensions).
+ *   - If the message is handled locally, it is put in the global "local" queue.
+ *   - Another thread (dispatch) will handle this message and pass it to registered callbacks (see handle-api.h).
+ *
+ * (*) FWD messages details:
+ *   - The process is the same as for IN messages, until the routing-in threads makes its decision.
+ *   - If the message is to be forwarded, rt_fwd_cb_t callbacks are called.
+ *     - these callbacks will do the proxying work. Note that adding the route-record is handled by the daemon.
+ *   - Once processed, the message is put in the global "outgoing" queue.
+ *   - The remaining process is the same as for OUT messages, as described bellow.
+ *
+ * (*) OUT messages details:
+ *   - Once created, the message is put in the global "outgoing" queue (or is a forwarded message).
+ *   - a thread will pick the message, and build a list of possible destinations for it.
+ *     The logic to build this list is as follow:
+ *      - create a list of all peers in the "OPEN" state.
+ *      - remove all peers that are already in a Route-Record of the message, to avoid routing loops.
+ *   - If the list has zero peer remaining, create an error UNABLE_TO_DELIVER.
+ *   - If the list has only one peer, send the message to this peer.
+ *   - Otherwise, call all registered rt_out_cb_t callbacks (registered by daemon and extensions) with the list of peers.
+ *   - Order the resulting list of peers by score, and sent the message to the peer with highest score.
+ *    - in case the peer is no longer in the "OPEN" state, send the message to the second peer in the list.
+ *      - if no peer is in OPEN state anymore, restart the process of creating the list.
+ *   - The peer thread will handle the creation of the Hop-by-hop ID and sending the message.
+ *
+ * This part of the API (routing-api.h) provides the definitions of the rt_out_cb_t and rt_fwd_cb_t callbacks, and the
+ * functions to register and deregister these callbacks.
+ */
  
 
 
@@ -43,6 +83,11 @@
 
 #include <waaad/message-api.h>
 
+/******************************************************************
+ *   The following part is dedicated to the OUT messages handling *
+ * (see introduction at the top of this file)                     *
+ ******************************************************************/
+
 /* The following values are typical "scores" that extensions should use in routing decisions */
 #define	PEER_SCORE_FINALDEST		100	/* If the peer is the final recipient of the message, it receives a big score. */
 #define PEER_SCORE_REDIR_SESSION	 50	/* If there is a redirect rule with ALL_SESSION for these message and peer */
@@ -65,16 +110,17 @@
 
 /* The following is the prototype of a function that handles routing decisions for outgoing messages */
 /*
- * FUNCTION:	rt_out_cb_t
+ * CALLBACK:	rt_out_cb_t
  *
  * PARAMETERS:
+ *  data	: pointer to some data that was passed when the callback was registered.
  *  msg 	: The message that must be sent.
  *  list        : The list of peers to which the message may be sent (peers in active state and no routing loop)
  *
  * DESCRIPTION: 
  *   This callback will attribute a score (preferably from PEER_SCORE_*) to each peer in the list.
  *  When all registered callbacks have terminated, the message is sent to the peer with the highest score.
- *  Note that each callback must ADD its locally-attributed score to the "score" parameter, not replace it!
+ *  Note that each callback must *add* its locally-attributed score to the "score" parameter, not replace it!
  *  Note also that this callback must be re-entrant since it may be called by several threads at the same time 
  *  (on different messages)
  *
@@ -82,12 +128,95 @@
  *  0      	: Operation complete.
  *  !0 		: An error occurred.
  */
-typedef int (*rt_out_cb_t) (msg_t * msg, rt_dpl_t * list);
+typedef int (*rt_out_cb_t) (void * data, msg_t * msg, rt_dpl_t * list);
+
+/* The following enum represents the position in which this callback should be registered */
+typedef enum {
+	RT_OUT_NORMAL,	/* This callback can be called at any time */
+	RT_OUT_LATE	/* This callback should be called as late as possible in the callback list */
+} rt_out_pos_t;
+
+/* The following opaque type represents a handler to a registered callback */
+typedef void rt_out_hdl_t;
+
+#ifndef IN_EXTENSION
+
+/*
+ * FUNCTION:	rt_out_register
+ *
+ * PARAMETERS:
+ *  cb 		  : The callback function to register.
+ *  data	  : Pointer to pass to the callback when it is called.
+ *  pos           : When this callback must be called.
+ *  handler       : On success, a handler to the registered callback is stored here. 
+ *		   This handler will be used to unregister the cb.
+ *
+ * DESCRIPTION: 
+ *   Register a new callback to handle OUT routing decisions.
+ *
+ * RETURN VALUE:
+ *  0      	: The callback is registered.
+ *  EINVAL 	: A parameter is invalid.
+ *  ENOMEM	: Not enough memory to complete the operation
+ *  
+ */
+int rt_out_register ( rt_out_cb_t cb, void * data, rt_out_pos_t pos, rt_out_hdl_t ** handler );
+
+#endif /* ! IN_EXTENSION */
+
+
+/******************************************************************
+ *   The following part is dedicated to the FWD messages handling *
+ * (see introduction at the top of this file)                     *
+ ******************************************************************/
 
 
 
 
 
+/******************************************************************/
 
 
+/* The version of this API, to check binary compatibility -- increment each time a change is made in api_rt_t */
+#define WAAAD_API_RT_VER	1
+
+/* Now define the type of the structure that contains the callback to pass to extensions */
+typedef struct {
+	/* The header is common to all sub-API pieces */
+	size_t	length;		/* The size of this structure, may be useful for extensions not using the facility */
+	int	version;	/* The version of this API/ABI, must be WAAAD_API_RT_VER */
+	
+	/* the remaining is routing-specific */
+	int (*rt_out_register)    ( rt_out_cb_t cb, void * data, rt_out_pos_t pos, rt_out_hdl_t ** handler );
+} api_rt_t;
+
+#ifdef IN_EXTENSION
+
+/* From within the extensions, we register callbacks in the following global structure */
+#ifdef DECLARE_API_POINTERS
+api_rt_t * g_api_rt;
+#else /* DECLARE_API_POINTERS */
+extern api_rt_t * g_api_rt;
+#endif /* DECLARE_API_POINTERS */
+
+/* These defines allow to call functions from extension in the same way as in waaad */
+#define rt_out_register		g_api_rt->rt_out_register
+
+#else /* IN_EXTENSION */
+
+/* From the daemon, we must initialize the API object, in extension.c */
+# define MY_WAAAD_API_RT_VER 1
+# if MY_WAAAD_API_RT_VER != WAAAD_API_RT_VER
+#  error "You must update API_INIT_RT also"
+# endif
+
+#define API_INIT_RT( api_rt ) 				\
+{							\
+	(api_rt).length             = sizeof(api_rt_t);	\
+	(api_rt).version            = WAAAD_API_RT_VER;	\
+	(api_rt).rt_out_register    = rt_out_register;	\
+}							
+
+#endif /* IN_EXTENSION */
+
 #endif /* _ROUTING_API_H */
--- a/include/waaad/waaad.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/include/waaad/waaad.h	Thu Jun 19 12:17:13 2008 +0900
@@ -72,6 +72,7 @@
 #include <waaad/conf-api.h>
 #include <waaad/peer-api.h>
 #include <waaad/message-api.h>
+#include <waaad/routing-api.h>
 
 
 
@@ -88,6 +89,7 @@
 	api_conf_t	conf;	
 	api_peer_t	peer;
 	api_msg_t	msg;
+	api_rt_t	rt;
 } waaad_api_t;
 
 /* ********************************** */
@@ -107,6 +109,7 @@
 #define API_MODULE_CONF		0x00000004	/* Load the configuration API in the extension */
 #define API_MODULE_PEER		0x00000008	/* Load the peer API in the extension */
 #define API_MODULE_MSG		0x00000010	/* Load the message API in the extension */
+#define API_MODULE_RT		0x00000020	/* Load the routing API in the extension */
 
 
 #define EXTENSION_API_INIT(flags, function, name) 								\
@@ -200,6 +203,21 @@
 	hdr = (sub_api_header_t *) &buffer[index];								\
 	index += hdr->length;											\
 														\
+	if ( flags & API_MODULE_RT) {										\
+		g_api_rt = (api_rt_t *)hdr;									\
+		if (g_api_rt->version != WAAAD_API_RT_VER) {							\
+			/* Unable to parse this API, do not continue */						\
+			fprintf(stderr, 									\
+				"[%s] Incompatible routing API version, please recompile the extension"		\
+				" or update the initialization in extensions.c.\n",				\
+				name);										\
+			return EINVAL;										\
+		}												\
+	}													\
+														\
+	hdr = (sub_api_header_t *) &buffer[index];								\
+	index += hdr->length;											\
+														\
 	/* next module... */											\
 														\
 	return function(conffile);										\
--- a/waaad/Makefile.am	Wed Jun 18 18:25:49 2008 +0900
+++ b/waaad/Makefile.am	Thu Jun 19 12:17:13 2008 +0900
@@ -25,6 +25,7 @@
 		dictionary.h dictionary.c \
 		peer.h peer.c \
 		message.h message.c \
-		queues.h queues.c
+		queues.h queues.c \
+		routing.h routing.c
 
 
--- a/waaad/extensions.c	Wed Jun 18 18:25:49 2008 +0900
+++ b/waaad/extensions.c	Thu Jun 19 12:17:13 2008 +0900
@@ -76,6 +76,7 @@
 	API_INIT_CONF       ( exported_api.conf       );
 	API_INIT_PEER       ( exported_api.peer       );
 	API_INIT_MSG        ( exported_api.msg        );
+	API_INIT_RT         ( exported_api.rt         );
 }
 
 /* Initialize the extensions module */
--- a/waaad/main.c	Wed Jun 18 18:25:49 2008 +0900
+++ b/waaad/main.c	Thu Jun 19 12:17:13 2008 +0900
@@ -188,6 +188,11 @@
 		log_error("An internal error occurred during initialization.\n");
 		goto end;
 	}
+	ret = rt_init();
+	if (ret != 0) {
+		log_error("An internal error occurred during initialization.\n");
+		goto end;
+	}
 	
 	/* Parse the command-line options */
 	ret = main_cmdline(argc, argv);
@@ -219,6 +224,8 @@
 end:
 	TRACE_DEBUG(INFO, "Entering 'end' section of main function.");
 	
+	(void)rt_fini();
+	
 	(void)peer_fini();
 	
 	(void)msg_fini();
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/waaad/routing.c	Thu Jun 19 12:17:13 2008 +0900
@@ -0,0 +1,69 @@
+/*********************************************************************************************************
+* Software License Agreement (BSD License)                                                               *
+* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
+*													 *
+* Copyright (c) 2008, WIDE Project and NICT								 *
+* All rights reserved.											 *
+* 													 *
+* Redistribution and use of this software in source and binary forms, with or without modification, are  *
+* permitted provided that the following conditions are met:						 *
+* 													 *
+* * Redistributions of source code must retain the above 						 *
+*   copyright notice, this list of conditions and the 							 *
+*   following disclaimer.										 *
+*    													 *
+* * Redistributions in binary form must reproduce the above 						 *
+*   copyright notice, this list of conditions and the 							 *
+*   following disclaimer in the documentation and/or other						 *
+*   materials provided with the distribution.								 *
+* 													 *
+* * Neither the name of the WIDE Project or NICT nor the 						 *
+*   names of its contributors may be used to endorse or 						 *
+*   promote products derived from this software without 						 *
+*   specific prior written permission of WIDE Project and 						 *
+*   NICT.												 *
+* 													 *
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
+* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
+* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
+* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
+* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
+* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
+* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
+* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
+*********************************************************************************************************/
+
+/* Routing module.
+ * 
+ * See routing.h and routing-api.h for more information on the functions and types involved.
+ */
+
+#include <errno.h>
+
+#include "waaad-internal.h"
+
+/* Initialize the module */
+int rt_init ( void )
+{
+	TRACE_DEBUG (INFO, "Routing module initialized");
+	TRACE_DEBUG (FULL, "@@@ Not implemented yet." );
+	return 0;
+}
+
+/* End of the module */
+int rt_fini ( void )
+{
+	TRACE_DEBUG (FULL, "Unloading routing module...");
+	TRACE_DEBUG (FULL, "@@@ Not implemented yet." );
+	return 0;
+}
+
+/* Register a callback for routing-out. */
+int rt_out_register ( rt_out_cb_t cb, void * data, rt_out_pos_t pos, rt_out_hdl_t ** handler )
+{
+	TRACE_DEBUG (FULL, "@@@ %s: not implemented yet.", __FUNCTION__ );
+	return ENOTSUP;
+}
+
+
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/waaad/routing.h	Thu Jun 19 12:17:13 2008 +0900
@@ -0,0 +1,82 @@
+/*********************************************************************************************************
+* Software License Agreement (BSD License)                                                               *
+* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
+*													 *
+* Copyright (c) 2008, WIDE Project and NICT								 *
+* All rights reserved.											 *
+* 													 *
+* Redistribution and use of this software in source and binary forms, with or without modification, are  *
+* permitted provided that the following conditions are met:						 *
+* 													 *
+* * Redistributions of source code must retain the above 						 *
+*   copyright notice, this list of conditions and the 							 *
+*   following disclaimer.										 *
+*    													 *
+* * Redistributions in binary form must reproduce the above 						 *
+*   copyright notice, this list of conditions and the 							 *
+*   following disclaimer in the documentation and/or other						 *
+*   materials provided with the distribution.								 *
+* 													 *
+* * Neither the name of the WIDE Project or NICT nor the 						 *
+*   names of its contributors may be used to endorse or 						 *
+*   promote products derived from this software without 						 *
+*   specific prior written permission of WIDE Project and 						 *
+*   NICT.												 *
+* 													 *
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
+* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
+* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
+* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
+* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
+* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
+* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
+* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
+*********************************************************************************************************/
+
+/* Routing module.
+ * 
+ * This module handles the routing (IN, OUT and FWD) of Diameter messages.
+ * See <waaad/routing-api.h> for more information on the process, and details on how extensions can
+ * take part in the routing decisions.
+ */
+ 
+#ifndef _ROUTING_H
+#define _ROUTING_H
+
+/* Include the API definitions for the routing */
+#include <waaad/routing-api.h>
+
+/* The following functions are called only from the daemon */
+
+/*
+ * FUNCTION:	rt_init
+ *
+ * PARAMETERS:
+ *  -
+ *
+ * DESCRIPTION: 
+ *  Initialize the routing module. 
+ *
+ * RETURN VALUE:
+ *   0	: Application is now ready to use the module.
+ *  !0  : An error occurred. 
+ */
+int rt_init ( void );
+
+/*
+ * FUNCTION:	rt_fini
+ *
+ * PARAMETERS:
+ *  -
+ *
+ * DESCRIPTION: 
+ *  Terminates the module. No rt_* function must be called after this one.
+ *
+ * RETURN VALUE:
+ *   0 : module closed properly.
+ *  !0 : an error occurred (we may ignore it)
+ */
+int rt_fini ( void );
+
+
+#endif /* _ROUTING_H */
--- a/waaad/waaad-internal.h	Wed Jun 18 18:25:49 2008 +0900
+++ b/waaad/waaad-internal.h	Thu Jun 19 12:17:13 2008 +0900
@@ -88,4 +88,10 @@
 */
 #include "queues.h"
 
+/* The routing module.
+Provides functions and threads to route the messages between the global queues and peers queues.
+rt_* functions.
+*/
+#include "routing.h"
+
 #endif /* _WAAAD_INTERNAL_H */
"Welcome to our mercurial repository"