Discovery
=========

Discovery protocol used via jabber, TCP and broadcast.

<discovery xmlns="http://obby.0x539.de/schema">
  Top-level discovery node

<query />
  Requests a complete list of sessions the remote site is publishing.

<add id="N" port="P" creator="name" title="title" />
  Tells other that the sender is publishing a new session with the given
  session ID N. creator is just a convenient name of the person/group that
  published this document. title is the document title.

  port is only required if this is discovered via TCP or broadcast. It
  tells the port the publisher listens for incoming TCP connections.

<remove id="N" />
  The session with the ID N has been closed and can no longer be joined.

<remove-all />
  All sessions have been closed.

<update id="N" creator="name" title="title" />
  Updates creator and title of the session with ID N. Both creator and
  title are optional and may be left out if only the other attribute has
  changed.

Transport
=========

SESSION: An obby session containing a document. Has a unique ID.

CONNECTION: A connection between two peers. May be either a jabber connection
            or a TCP connection.

USER: An active participant in a SESSION. Uses a CONNECTION to talk to others.

PUBLISHER: The peer that created a SESSION.

READONLY: A passive participant in a SESSION. Uses a CONNECTION to receive
          requests.

<session id="N" publisher="(ip:port|jid)" xmlns="http://obby.0x539.de/schema">
  Transport messages always relate to a SESSION. To avoid ambiguity, it is
  required to set a publisher attribute that tells the recipient the
  PUBLISHER of the session it refers to. Sessions from different PUBLISHERs
  may have the same ID.

  All the requests below MUST be contained in a <session> tag to be
  associated with a SESSION.

Session join/part
=================

The requests in this section may only be sent/received from/as a PUBLISHER. If
this is not the case, the request MUST be ignored.

<user-join name="arbur" color="#C0FFEE" />
  Requests a USER join to a SESSION from a PUBLISHER. color is optional.
  If not provided, the PUBLISHER chooses one automatically.

<user-join id="N" name="arbur" color="#C0FFEE" address="jid" />
  Broadcast from the PUBLISHER to all CONNECTIONs when a USER joined. When this
  is the first user join from this CONNECTION, sync follows to this CONNECTION
  (see below).

  The PUBLISHER MUST NOT send this message when the requested name is already
  used by another USER. Instead, he has to reply using an error message (see
  below).

  address is only used for jabber transport and contains the Jabber ID of
  the joining user. This MUST be used by other jabber CONNECTIONs to
  send/receive requests to/from this user.

<user-join error-code="N" />
  Sent from the PUBLISHER to a CONNECTION that requested a USER join. error-code
  provides information why the user join did not succeed.

<readonly-join name="arbur" />
  Requests a READONLY join for a SESSION. READONLY users are not allowed to
  change the document but read the ongoing conversion. READONLY user names
  MAY occur twice. Requesting multiple READONLY joins is allowed.

<readonly-join name="arbur" address="jid" />
  Sent from a PUBLISHER to a all CONNECTIONs when it granted a READONLY join.
  sync follows if the CONNECTION had no user joined to this session.

  Again, the address field is only required if the request comes from a
  jabber CONNECTION.

<readonly-join error-code="N" />
  Sent from a PUBLISHER to a CONNECTION that requested a READONLY join.
  error-code contains information, why the join did not succeed.

<user-part id="N" />
  Sent to the PUBLISHER when a USER wants to leave a session. The PUBLISHER
  MUST verify that the given user ID has joined from this CONNECTION.

<user-part id="N" />
  Broadcast by a PUBLISHER to all CONNECTIONs when a USER has left a session.

<readonly-part name="arbur" />
  Sent to the PUBLISHER when a READONLY wants to leave a session. The
  PUBLISHER MUST verify that a READONLY from this CONNECTION has joined
  using this name.

<readonly-part name="arbur" />
  Broadcast by a PUBLISHER to all CONNECTIONs when a READONLY has left
  a session.

Sync
====

These requests are only sent from a PUBLISHER to a joining USER if it is the
first USER or READONLY from this CONNECTION. If there are received from
someone else, they MUST be ignored.

<sync-user id="N" name="arbur" color="C0FFEE" address="jid" status="offline">
 <selection pos="N" len="K" />
 <caret pos="N" />
</sync-user>
  Tells the joining USER what other USERs there are. The address attribute
  SHOULD only be used when the CONNECTION we are syncing to is a jabber
  CONNECTION, when the CONNECTION the user we are currently syncing is also
  a jabber CONNECTION and this user is online. The status attribute specifies
  whether this USER has currently joined the SESSION. It may be set to
  offline when the USER had joined the SESSION, but left prior to this
  sync-user request.

  Only one of selection or caret is allowed to tell the new USER the position
  of this USERs caret position respective selection area.

<sync-readonly name="arbur" address="jid" />
  Tells the joining USER what READONLYs are currently connected. Again, the
  address attribute is only useful if both CONNECTIONs are via jabber.
  READONLYs cannot be in offline state but are just not present at all if
  they leave a SESSION.

<sync-statespace from="N;P;K;[...]" to="N;P;K;[...]">
 <OPERATIONS>
</sync-statespace>

  Synchronizes a part of the state space to allow the new CONNECTION
  to transform incoming older requests. from and to MUST differ in at most
  one component. OPERATIONS are operations as described below. There must
  be exactly as much operations as the difference of the vector time components
  that do not match.

  The PUBLISHER SHOULD transmit exactly one way from the smallest vector time
  he knows of to the vector time of the current document state, but he
  MAY transmit more.

<sync-document time="N;P;K;[...]" />
  Initiates the document synchronization process. The current vector time
  stamp is given in this request.

<sync-chunk author="foo>TEXT</sync-chunk>
  Sends a chunk of the document. The chunk has been written by the user 
  with the given ID and contains TEXT. Between <sync-document> and
  <sync-final>, any number of chunks may be sent.

<sync-final />
  Finalizes the document synchronization process. After a CONNECTION has
  received this request it has a full copy of the document including a vector
  time.

sync-chunk are NOT nested in a sync-document tag to allow them to be sent
through multiple <session>s.

Requests
========

<request time="N;P;K;[...]" from="U">
  Request from the USER U that performed an operation at the given vector time.
  requests are always broadcast to all USERs and READONLY users. The recipient
  MUST check whether user U has joined from the connection the request comes
  in. If not, the request MUST be dropped.

  A request may contain zero or more operations. For each operation, that is
  not "caret" or "selection" the corresponding vector time component MUST
  be increased.

Operations
==========

<insert text="TEXT" pos="N" />
  Operation that inserts the given text at the given position.

<delete pos="N" len="K" text="TEXT" />
  text is optional and for debugging purposes only.

<caret pos="N" />
  sets the caret of this user to the given position.

<selection pos="N" len="K" text="TEXT" />
  again, text is optional. Same as caret for K=0. K may be negative.

<insert-caret text="TEXT" pos="N" />
  Like insert, but also places the user's caret behind the newly-inserted text.

<delete-caret pos="N" len="K" text="TEXT" />
  Like delete, but also places the user's caret at the position where text has
  been deleted.

Policy
======

If a PUBLISHER receives a request, it MUST

 a) forward the request to all CONNECTIONs if the request comes from
    a TCP CONNECTION.
 b) forward the request to all TCP CONNECTIONs if it comes from a jabber
    CONNECTION.
 c) if the request comes from a jabber connection: forward the request to
    jabber CONNECTIONs that the sender of this request was not aware of.
    This affects requests that a CONNECTION is sending between the sync
    to a new CONNECTION and the reception of the corresponding user-join.
    
    A method how to recognize such requests is still required. A possibility
    would be to increase the vector time component of a new user by 1 after
    the join.
 
If a USER generates a request, it MUST

 a) sent the request to the PUBLISHER
 b) if the USER is connected via a jabber CONNECTION send the request to all
    jabber CONNECTIONs (except itself). However, the request must be kept back
    if no USER of the CONNECTION can transform the operation because of the
    initial vector time stamp.

If a CONNECTION receives a request, it MUST:

 a) Pass the request to all USERs using this CONNECTION.

If a USER receives a request, it MUST:

 a) Transform it against newer operations and apply it to the document.
 b) Store the vector time that came in and associate it to the user that
    generated the request. This allows the USER to say which operations
    another USER is guaranteed to be aware of.

Examples
========

<discovery xmlns="http://obby.0x539.de/schema">
 <query />
</discovery>

  Requests a list of documents.

<discovery xmlns="http://obby.0x539.de/schema">
 <add id="1" publisher="arbur" title="Armin's document" port="6523 />
 <add id="2" publisher="arbur" title="Armin's second document" port="6523 />
</discovery>

  This request may be a response to a prior <query /> request or a notification
  when these sessions have just been created.

<session id="3" publisher="localhost:6524" xmlns="http://obby.0x539.de/schema">
 <user-join name="arbur" color="#0000FF" />
</session>

  Assuming this comes from localhost:6523, this requests a user join to
  session 3 that runs on localhost:6524.

<session id="3" publisher="localhost:6524" xmlns="http://obby.0x539.de/schema">
 <user-join id="2" name="arbur" color="#0000FF" />
</session>

  Assuming this comes from localhost:6524, this grants a user join to
  session 3 that runs on localhost:6524.

<session id="3" publisher="localhost:6524" xmlns="http://obby.0x539.de/schema">
 <request time="0:0" from="2">
  <insert-caret text="a" pos="0" />
 </request>
</session>

  Inserts "a" at position 0 and places the caret at position 1.