RFC: AbiTalk communication protocol suggestion

I have got really quite excited about this collaborative stuff, and
since the proposal did not suggest the transport mechanism, here comes a
suggestion for a basic protocol for communication between two AbiWord
processes. Please note (a) this is only a top level protocol, which
could be implemented on top of dbus or just a straigh TCP/IP, or some
other protocol; (b) I might be up to no good, and it almost certainly
not complete, hence RFC.

The proposed protocol is xml-based, so that we would use an xml listener
for parsing the messages as we do with AW importer; it means that our
change records and similar items would be easy to translate into the
protocol messages and vice versa.

A message passed between two processes has the following format
    <abitalk version="1.0" [uid="xxxxx"] [token="xxxxx"]>
      <%cmd%>[content]</%cmd%>[<%cmd%>[content]</%cmd%>]
    </abitalk>

    version: identifies the protocol version

    uid: the uuid of the document which is the subject of conversation;
          if not provided, the commands to follow will carry operations
          only on the application, not documents.

    token: authorisation token. The token is a standard uuid with time
           stamp ajusted to indicate when the authoristation token
           expires. Tokens are connected to a specific document uid.
           If no token is provided the only legitimate commands to follow
           are <token> and <getdoc> (see below).

Single message can contain one or more commands:

    %cmd%: specific command name, which can be followed by set of
           attributes

    [content]: content specific to given command (optional)

Predefined commands
-------------------
The following commands are predefined by the protocol:

    <getdoc name="xxxx"/>
       Request for the entire document identified by name

    <document name="xxxx">[doc]</document>
       Sent in response to <getdoc> request. The content of this element
       is raw document as contained in the document file and should be
       passed directly to the AW importer chain.

    <token [uid="xxxx"]/>
       uid: the token in standard uuid format. The token is specific to
       the document uid, and has a limited lifespan; the expiry time is
       indicated by the uid time stamp.

       If no uid is specified, the command is interpreted as request for
       authorisation token.

       If uid is specified, this command is a response to request for
       authorisation token; uid is the token.

    <release uid="xxxx"/>
       uid: authorisation token.

       This command is sent to release the token; as soon soon as this
       command send, the token becomes invalid. This command is required
       for the entire transation to be valid (see below notes on token
       handling).

    <error id="errno">[Verbose msg]</error>
       id: UT_AbiTalk::Result
       Verbose msg: optional verbose, human readable, error message.

All other commands are handled by command handlers registered via
UT_AbiTalk::registerHandler(); their number and meaning has not direct
impact on the protocol itself (i.e., the protocol can be easily expanded
as new features are added).

Token handling
--------------
A and B are communicating Abi processes. If A wishes to send commands to
B, A requests an authorisitation token. B issues the token and until
either the token expires or is released by A, B does not carry any other
operations on the document/process than those that are requested by A
using the authorisation token. At the same time, while A is in
possession of the token, it will turn down any request for authorisation
tokens from other parties, including B.

When finished with the whole command sequence, A has to release the
token by sending <release> command.

B keeps an eye on the life of the issued token; if the token expires
before the <release> cmd is received for the token, B reverses all
operation carried on the document by A using that token and dispatches
<error>Token expired</error> cmd to A. In response to the error A has to
request a new token and resend all commands.

Example command
---------------
A sample command (after the intial hanshake and token retrieval) could
look like:

<abitalk version="1.0" uuui="xxxxxx" token="yyyyyy">
<insertspan start=5 end=7 props="font-size:12pt">my span</insertspan>
</abitalk>

On receipt of the message, the AW process would translate it to an
insert Span change record and pass it to the document identified by the
uuid.

Enough for one night.

Tomas
Received on Tue May 17 23:11:22 2005