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

Module: sip-router Branch: master Commit: b15f37fc1eb2fceaf8ea04e35e94850164f06cf5 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=b15f37f… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; 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… + 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… 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… - SER RPC Type Converion</ulink> and + <ulink url='http://sip-router.org/docbook/sip-router/branch/master/rpc/ser_rpc… + 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… + 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… + <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… + <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_ct… + <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>