jarn.xmpp.collaboration 0.1b3

Initialization

In order to initiate a collaborative editing session, the party sends a presence stanza to the server component indicating on which node he wishes to work on. The party MUST specify the node attribute in the query element:

<presence from='foo@example.com/work' to='collaboration.example.com'>
    <query xmlns='http://jarn.com/ns/collaborative-editing' node='collab-node'/>
</presence>

Upon receipt a message stanza is sent to anyone else who might be editing the same node notifying them of the new participant:

<message from='collaboration.example.com' to='bar@example.com/home'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item action='user-joined' node='collab-node' user='foo@example.com/work'/>
    </x>
</message>

The newly joined user also receives a similar notification about existing users

<message from='collaboration.example.com' to='foo@example.com/home'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item action='user-joined' node='collab-node' user='bar@example.com/work'/>
    </x>
</message>

To complete the initialization the new party MUST request the current version of the node from the server:

<iq id='123' from='foo@example.com/work' to='collaboration.example.com' type='get'>
    <shadowcopy xmlns='http://jarn.com/ns/collaborative-editing' node='collab-node'/>
</iq>

To which the server replies providing his current copy of the text:

<iq id='123' from='collaboration.example.com' to='foo@example.com/work'  type='result'>
     <shadowcopy xmlns='http://jarn.com/ns/collaborative-editing' node='collab-node'>Hello world</shadowcopy>
 </iq>

In case the node does not exist, or the user has no privileges granting him access, the server MUST reply with an error, for instance:

<iq id='123' from='collaboration.example.com' to='foo@example.com/work' type='error'>
    <error xmlns='http://jarn.com/ns/collaborative-editing'>Unauthorized</error>
</iq>

Editing cycle

When a party edits the text, it notifies the server by sending an iq stanza of type set. The stanza contains one patch element which MUST specify the node they apply to, and in their body contain the patch created by the Diff-Match-Patch algorithm in text format. For instance if the text changed from “Hello world” to “Hello world, have a nice day!” the message would be:

<iq id='234' from='foo@example.com/work' to='collaboration.example.com' type='set'>
    <patch xmlns='http://jarn.com/ns/collaborative-editing' node='collab-node' digest='b9e8241b3cc82c43af870641078ee03f'>
        @@ -4,8 +4,26 @@\n lo world\n+, have a nice day!\n
    </patch>
</iq>

If the server succeeds to apply the patch to its shadow copy, it replies with a success result:

<iq id='234' from='collaboration.example.com' to='foo@example.com/work' type='result'>
    <success xmlns='http://jarn.com/ns/collaborative-editing'/>
</iq>

Additionally the server MUST broadcast the patch to all other parties who are present on the node:

<iq id='345' from='collaboration.example.com' to='bar@example.com/home' type='set'>
    <patch xmlns='http://jarn.com/ns/collaborative-editing' node='collab-node'>
        @@ -4,8 +4,26 @@\n lo world\n+, have a nice day!\n
    </patch>
</iq>

The parties MUST apply it to their text. If applying the patch fails, the server (or client) MUST reply with an iq stanza of type error. For instance if a patch was sent to the server and for some reason it was not possible to apply it to the shadow copy, the server would reply:

<iq id='234' from='collaboration.example.com' to='foo@example.com/work' type='error'>
    <error xmlns='http://jarn.com/ns/collaborative-editing'>
        Patch @@ -4,8 +4,26 @@\n lo world\n+, have a nice day!\n could not be applied.
    </error>
</iq>

In that case the client SHOULD sync again the current copy by sending an iq stanza of type get`requesting the shadow copy, see the `Initialization section above.

Finally, a patch element MAY have the digest attribute. In that case, the server SHOULD check the checksum and if there is a mismatch, reply with an error stanza if appropriate. Note that currently the checksum algorithm is not negotiated and is assumed to be MD5 hex digest.

Focusing

In an environment where multiple nodes are edited in the same time (for instance in a context where the content has more than one collaboratively editable field) the client CAN send a notification specifying which particular node he is currently editing:

<message from='foo@example.com/work' to='collaboration.example.com'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item node='collab-node' action='focus' user='foo@example.com/work'/>
    </x>
</message>

The server MUST propagate the message to all other users that are currently collaborating on the node:

<message from='collaboration.example.com' to='bar@example.com/home'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item node='collab-node' action='focus' user='foo@example.com/work'/>
    </x>
</message>

Saving

At any point a party can request a save. This is done by sending a message whose item MUST indicate the node and its action must be set to save:

<message from='foo@example.com/work' to='collaboration.example.com'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item node='collab-node' action='save'></item>
    </x>
</message>

It is up to the server component to enforce any security considerations on saving.

Termination

The session is terminated when the party sends an unavailable presence:

<presence from='foo@example.com/work' type='unavailable' />

Upon receipt, the server notifies any party that might still be editing the node:

<message from='collaboration.example.com' to='bar@example.com/home'>
    <x xmlns='http://jarn.com/ns/collaborative-editing'>
        <item action='user-left' node='collab-node' user='foo@example.com/work'/>
    </x>
</message>

0.1b3 - 2011-11-26

• Fix checksum bug preventing the shadow text to be applied if an error ever occured. [ggozad]

0.1b2 - 2011-10-01

• Perform checksum checks on every patch. Deal with potential errors due to network lag. [ggozad]

• Use TinyMCE’s raw instead of processed text. Improved reliability. [ggozad]

0.1b1 - 2011-09-18

• Major protocol update. Instead of sending message stanzas around, now iq stanzas are used. This makes it possible to check for errors and synchronize in certain edge cases. It also makes the protocol more in line with XMPP conventions. [ggozad]

• Reorganized and cleaned js code. The client protocol implementation is now separate from the plone-specific parts allowing code reuse and improving readability. [ggozad]

• Notify user when others are joining/leaving the node. [ggozad]

0.1a4 - 2011-09-07

• Documentation updates. [ggozad]

• Fix js error when user has left collaborative editing. [ggozad]

0.1a3 - 2011-09-01

• Simplified configuration and fixed confusing typos in the registry [ggozad]

0.1a2 - 2011-06-06

• Configure the component/server password and connection port in p.a.registry. [ggozad]

• Dexterity content type support. [davisagli, ggozad]

• Generalized ATContentTypes support. [ggozad]

• Provide visual feedback when a user updates a node. [ggozad]

• JS cleanup. [ggozad]

• Test coverage. [ggozad]

0.1a1 2011-05-09

• Initial release [ggozad]