Re: [Demexp-dev] Client Web

[David MENTRE]

Hello Lyu,

I prefer that one speaks English on this mailing list, we have
non-French speaking readers. ;-)

One day, I'll write a real doc on all of this. This email is a first start.

Le 12/10/07, Lyu ABE<address@hidden> a écrit :
> J'ai vaguement compris que par exemple pour se logger, il faut utiliser
> un protocole XML-RPC. Apres, c'est le flou total pour moi: comment faire
> pour passer un login et un pwd au serveur, et quelles sont les retours
> du serveur (y'a une histoire de cookie en retour si j'ai bien compris).

All communications to the server is done using a Remote Procedure Call
(RPC) to the server. An RPC is much like a regular function call,
except that call parameters might be sent at the other side of the
planet. ;-)

The demexp server currently supports two RPC protocols: ONC-RPC and
XML-RPC (through a dedicated proxy).

ONC-RPC is more efficient and safe but only available for few
languages: OCaml, C, C++ and Python (thanks to developments of Thomas
Petazzoni). ONC-RPC is a binary encoding over a TCP socket. ONC-RPC
has the big advantage that client and server stubs can be generated
from ONC-RPC message description.

Most programming languages (including above ones) support XML-RPC.
XML-RPC is an XML text encoding over HTTP protocol over a TCP socket.
The XML-RPC interface is just a transposition into the XML-RPC data
types of the ONC-RPC interface.

In regular programming languages (Javascript, OCaml, C, Python, ...),
RPC calls are made either through an API (to construct and unconstruct
RPC calls, marshalling/unmarshalling data in the process) or through
stubs (a simple function in the programming language that directly
calls the RPC, doing all data marshalling/unmarshalling for you).
ONC-RPC implementations are using stubs. Most of the time, XML-RPC
calls are used through an API: build an XML-RPC object within your
language of choice, add parameters, marshall and send it to the
server, wait for the response, unmarshall the server's response and
convert it to language's objects[3].

I assume that you use XML-RPC for the remaining of this email.

All the client/server API (Application Programming Interface)
communication is done through RPC: a client sends an RPC to the
server, the server process it and replies back an answer. The whole
ONC-RPC API (and thus the derived XML-RPC one) is described in Part I
of the demexp book ([1], starting at p. 13). There is no real
documentation for XML-RPC, I might also do that one day. :-) In case
this is an issue, just ask questions here. I'm going to answer them.

As a summary, to make a demexp client, you need a programming language
where you can (i) send a set of XML-RPC calls to a demexp server and
(ii) process the values returned by the server.


Now, for the cookie part. The "cookie"[2], in demexp parlance, is a
unique token, assigned by the server to uniquely identify a client.
Nearly all RPC calls of the demexp API have as first parameter this
"cookie". The cookie is also used by the server to determine access
right of the clients. Access rights are used to determine allowed API
access (user creation is only allowed to administrators for example).

The cookie is obtained through the login() RPC call. The login() RPC
call succeeds only if you have a valid login/password account on the
server. So the usual client<->server interaction is:

 1. login() -> my-cookie

 2. question_info(my_cookie, ...) -> ...

 3. vote(my_cookie, ...)

 4. ....

 n. goodbye(my_cookie)

It is strongly advised to associate a goodbye() call for each login()
call. The reason: the server keeps some states about the client which
are freed only after the goodbye() call. Yes, this is a bug in the
server. :-)

demexp Tips & Tricks:
 * if you don't want to authenticate to the server, you might use a
dummy value (e.g. 0 (zero)) as cookie. Most calls (question browsing,
tag browsing, ...) don't check the cookie before being processed by
the server;

 * the API allows to open several client context at once on a server
over the same XML-RPC connection, you just need to do several login()
calls and use the returned cookies.

> Par exemple (dites moi si je me trompe), est-ce que j'ai besoin de code
> comme ca:...?
> http://jsolait.net/
>
> qui possede un module javascript xmlrpc (dont je n'ai pas reussi a
> comprendre comment l'utiliser precisement).

Yes, an XML-RPC module in Javascript is needed if you want to write a
client in Javascript.

I haven't look at the jsolait's API itself right now. Its
documentation is, errr, short. :-/ I don't know much Javascript so I
can't help a lot on that side, sorry.

> Si quelqu'un a d'autres commentaires (utiliser ou pas javascript pour le
> client, etc)...

Well, it's a hot debate. :-) I would much prefer people to use the
ONC-RPC interface to access the demexp server, but it is often more
easy to use the XML-RPC one. Moreover, it might be easier in the short
future to secure XML-RPC calls (by using HTTPS instead of HTTP).

Regarding the programming language, I know Python, OCaml, C and some
bits of C++ and PHP. If you use those languages, I might help.
Otherwise, you are one your own (well, I might also help but it would
be much more costly for me :-).

But you'd better use the language you are more comfortable with.

Another design criterion is where do you want to put your client? Is
it a real client one, where the client might need to install some
software (a Python client with the Python runtime) or download it (a
Javascript client running into a web browser's Javascript runtime)? Or
is it a server-side demexp client (programmed in PHP or Python for
example) accessed through a web browser?

There are pros and cons for all choices: easiness to install the
software, easiness to use it through a well known interface (web
browser), speed, easiness to maintain compatibility across a wide
range of runtime environments, ...

After years of thinking about those issues (and some lines of code
;-), it seems to us (the demexp core team) that a demexp-client in a
web server accessible through a web browser and using only simple web
technology (only HTML, no Javascript) would be the easiest to deploy,
secure and use. Such a demexp-client in a web server could be written
in Python, PHP or OCaml. But you are free to choose another path (e.g.
language and kind of client) that suits more your needs or wills. :-)

I hope I'm clear. Don't hesitate to ask further questions.

Yours,
d.

[1] http://www.linux-france.org/~dmentre/demexp/latest-src/demexp-book-0.8.2.pdf

[2] "cookie" was a very bad choice of name. "client-side identifier"
would have been better. I might change this one day.

[3] You can see an example of this in the archive of this list, where
Diogene used XML-RPC in PHP:
http://lists.gnu.org/archive/html/demexp-dev/2007-09/msg00017.html