[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