[sr-dev] git:master: xmlrpc(s) doc: note about xmlrpclib bug

Andrei Pelinescu-Onciul andrei at iptel.org
Thu Jul 16 10:47:04 CEST 2009


Module: sip-router
Branch: master
Commit: b15f37fc1eb2fceaf8ea04e35e94850164f06cf5
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=b15f37fc1eb2fceaf8ea04e35e94850164f06cf5

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date:   Thu Jul 16 10:39:36 2009 +0200

xmlrpc(s) doc: note about xmlrpclib bug

- added note about xmlrpclib bug (waiting for connection closing)
  and workarounds (use a different transport class or make ser
  close the tcp connection after each answer).
- list examples/xmlrpc_test.{pl,py} among the client examples
- updated & fixed some links
- README re-generated

---

 modules_s/xmlrpc/README         |   67 ++++++++++++++++++++++++++++++-----
 modules_s/xmlrpc/doc/xmlrpc.xml |   75 ++++++++++++++++++++++++++++++++++-----
 2 files changed, 124 insertions(+), 18 deletions(-)

diff --git a/modules_s/xmlrpc/README b/modules_s/xmlrpc/README
index 1961252..b497e66 100644
--- a/modules_s/xmlrpc/README
+++ b/modules_s/xmlrpc/README
@@ -15,11 +15,13 @@ Jan Janak
         1.3.2. Replies
         1.3.3. Type Conversion
         1.3.4. Limitations
+        1.3.5. Interoperability Problems
 
    1.4. Client Examples
    1.5. Parameters
 
         1.5.1. route (string)
+        1.5.2. autoconversion (string)
 
    1.6. Functions
 
@@ -217,10 +219,10 @@ if (method == "POST" || method == "GET") {
    SER receives GET or POST requests. These two method names indicate
    HTTP.
 
-   Step 4. Function dispatch_rpc scans through the list of all exported
-   RPC functions searching for statistics function of usrloc module. The
-   SER RPC Module API describes in detail how modules export RPC
-   functions.
+   Step 4. The function dispatch_rpc scans through the list of all
+   exported RPC functions searching for the statistics function of the
+   usrloc module. The SER RPC Module API describes in detail how modules
+   export RPC functions.
 
    Step 5. As the RPC function from usrloc module is running and gathering
    statistics, it calls functions of RPC interface to prepare the result
@@ -366,7 +368,7 @@ Content-Length: 150
    If an RPC function adds just a single item (it calls add once with just
    one character in the formatting string) then the data will be converted
    to XML-RPC representation according to the rules described in SER RPC
-   Type Converion and the reply will contain just the single value:
+   Type Conversion and the reply will contain just the single value:
 HTTP/1.0 200 OK
 Via: SIP/2.0/TCP 127.0.0.1:3793
 Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
@@ -438,9 +440,39 @@ Content-Length: 276
    need all the bells and whistles of XML-RPC. Parsing and interpreting
    nested structures is complex and we try to avoid it.
 
+1.3.5. Interoperability Problems
+
+   Due to a bug in Python xmlrpclib there is an interoperability problem
+   with basic clients using it: by default an xmlrpclib client expects the
+   server to immediately close the connection after answering and if the
+   server does not close the connections the xmlrpclib client will wait
+   forever.
+
+   There are 2 ways to work around this problem: write a "fixed" Transport
+   class and initialize xmlpclib using it (recommended) or make ser close
+   the tcp connection after each request.
+
+   The examples/xmlrpc_test.py provides a very simple example of using
+   xmlrpclib with a Transport class that works.
+
+   For the second solution (force closing tcp connections after answering)
+   the XMLRPC route should end with a return -1, exit -1 or drop -1.
+
+   Example 1.
+route[XMLRPC]{
+        dispatch_rpc();
+        # close connection only for xmlrpclib user agents
+        if search("^User-Agent:.*xmlrpclib"))
+                return -1 ;
+}
+
 1.4. Client Examples
 
-     * ser_ctl (python application that uses the XML-RPC interface
+     * examples/xmlrpc_test.pl (basic perl application that builds and
+       sends an XMLRPC request from its commandline parameters).
+     * examples/xmlrpc_test.py (basic python application that builds and
+       sends an XMLRPC request from its commandline parameters).
+     * ser_ctl (complex python application that uses the XML-RPC interface
        implemented by the xmlrpc module).
      * serweb (php application that can use the XML-RPC interface to call
        ser functions).
@@ -465,9 +497,26 @@ Content-Length: 276
 
    Default: the main route is used.
 
-   Example 1. Set route parameter
+   Example 2. Set route parameter
 modparam("xmlrpc", "route", "route_for_xmlrpcs")
 
+1.5.2. autoconversion (string)
+
+   Enable or disable automatic parameter type conversion globally, for all
+   the methods parameters. If on, a type mismatch in a method parameter
+   will not cause a fault if it is possible to automatically convert it to
+   the type expected by the method.
+
+   Default: off.
+
+   It is recommended to leave this parameter to its default off value and
+   fix instead the client application (which should use the proper types)
+   or to modify the target rpc to accept any type (see the rpc scan '.'
+   modifier).
+
+   Example 3. Set the autoconversion parameter
+modparam("xmlrpc", "autoconversion", 1)
+
 1.6. Functions
 
    Revision History
@@ -489,7 +538,7 @@ modparam("xmlrpc", "route", "route_for_xmlrpcs")
    function with matching name. If such a function is found then
    dispatch_rpc() will pass control to the function to handle the request.
 
-   Example 2. dispatch_rpc usage
+   Example 4. dispatch_rpc usage
 #...
 modparam("xmlrpc", "route", "XMLRPC");
 #...
@@ -502,7 +551,7 @@ route[XMLRPC]{
    This function can be called from the config script to directly generate
    an XML-RPC reply.
 
-   Example 3. xmlrpc_reply usage
+   Example 5. xmlrpc_reply usage
 #...
 modparam("xmlrpc", "route", "XMLRPC");
 #...
diff --git a/modules_s/xmlrpc/doc/xmlrpc.xml b/modules_s/xmlrpc/doc/xmlrpc.xml
index 4438185..c893e97 100644
--- a/modules_s/xmlrpc/doc/xmlrpc.xml
+++ b/modules_s/xmlrpc/doc/xmlrpc.xml
@@ -302,11 +302,11 @@ if (method == "POST" || method == "GET") {
 	    indicate HTTP.
 	</para>
 	<para>
-	    <emphasis>Step 4.</emphasis> Function
+	    <emphasis>Step 4.</emphasis> The function
 	    <function>dispatch_rpc</function> scans through the list of all
-	    exported RPC functions searching for
-	    <function>statistics</function> function of usrloc module. The
-		<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/rpc/ser_rpc.txt'>
+	    exported RPC functions searching for the
+	    <function>statistics</function> function of the usrloc module. The
+		<ulink url='http://sip-router.org/docbook/sip-router/branch/master/rpc/ser_rpc.html'>
 		SER RPC Module API</ulink>
 		describes in detail how modules export RPC functions.
 	</para>
@@ -491,8 +491,8 @@ Content-Length: 150
 		with just one character in the formatting string) then the data
 		will be converted to XML-RPC representation according to the
 		rules described in
-		<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/rpc/ser_rpc.txt'>
-		SER RPC Type Converion</ulink> and
+		<ulink url='http://sip-router.org/docbook/sip-router/branch/master/rpc/ser_rpc.html#rpc.data_types'>
+		SER RPC Type Conversion</ulink> and
 		the reply will contain just the single value:
 		<programlisting>
 <![CDATA[
@@ -655,6 +655,43 @@ Content-Length: 276
 		complex and we try to avoid it.
 	    </para>
 	</section>
+	<section id="xmlrpc.interoperability_problems">
+	    <title>Interoperability Problems</title>
+	    <para>
+		Due to a bug in Python xmlrpclib there is an interoperability 
+		problem with basic clients using it: by default an xmlrpclib client 
+		expects the server to immediately close the connection after answering
+		and if the server does not close the connections the xmlrpclib client
+		will wait forever.
+		</para>
+		<para>
+		There are 2 ways to work around this problem: write a "fixed"
+		Transport class and initialize xmlpclib using it (recommended) or
+		make ser close the tcp connection after each request.
+		</para>
+		<para>
+		The <ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_s/xmlrpc/examples/xmlrpc_test.py'>
+		examples/xmlrpc_test.py
+		</ulink> provides a very simple example of using xmlrpclib with a
+		Transport class that works.
+		</para>
+		<para>
+		For the second solution (force closing tcp connections after answering)
+		the XMLRPC route should end with a return -1, exit -1 or drop -1.
+		<example>
+		<programlisting>
+<![CDATA[
+route[XMLRPC]{
+	dispatch_rpc();
+	# close connection only for xmlrpclib user agents
+	if search("^User-Agent:.*xmlrpclib"))
+		return -1 ;
+}
+]]>
+		</programlisting>
+		</example>
+		</para>
+	</section>
     </section>
 
 	<section id="xmlrpc.client_examples">
@@ -673,12 +710,32 @@ Content-Length: 276
 	<para>
 	<itemizedlist>
 		<listitem><para>
-			<emphasis>ser_ctl</emphasis> (python application that uses the
-			<emphasis>XML-RPC</emphasis> interface implemented by the
+			<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_s/xmlrpc/examples/xmlrpc_test.pl'>
+			<emphasis>examples/xmlrpc_test.pl</emphasis>
+			</ulink> (basic perl application that builds and sends an
+			<emphasis>XMLRPC</emphasis> request from its commandline
+			parameters).
+		</para></listitem>
+		<listitem><para>
+			<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_s/xmlrpc/examples/xmlrpc_test.py'>
+			<emphasis>examples/xmlrpc_test.py</emphasis>
+			</ulink> (basic python application that builds and sends an
+			<emphasis>XMLRPC</emphasis> request from its commandline
+			parameters).
+		</para></listitem>
+		<listitem><para>
+			<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=ser;a=tree;f=ser_ctl'>
+			<emphasis>ser_ctl</emphasis>
+			</ulink>
+			(complex python application that 
+			uses the <emphasis>XML-RPC</emphasis> interface implemented by the
 			<emphasis>xmlrpc</emphasis> module).
 		</para></listitem>
 		<listitem><para>
-			<emphasis>serweb</emphasis> (php application that can use
+			<ulink uri='http://www.iptel.org/serweb'>
+			<emphasis>serweb</emphasis>
+			</ulink>
+			(php application that can use
 			the <emphasis>XML-RPC</emphasis> interface to call ser 
 			functions).
 		</para></listitem>




More information about the sr-dev mailing list