Synchronization Protocol

This protocol is derived from the original mobwrite protocol by Neil Fraser.

Messages

The protocol uses json messages to communicate between peers. This section describes these messages.

Synchronization Session

A synchronization session is a message that allows people to work on files for a given paper identifier. It is composed of the name of the peer sending the message, the paper identifier on which we are working and a list of synchronization commands to apply to files in this paper

For example:

{
  "peerId": "toto",
  "paperId": "v987fed987da70987f",
  "commands": [
  {
    "filename": "file1.tex",
    "revision": 432767,
    "action": <command>
  },
  {
    "filename": "file2.tex",
    "revision": 87432,
    "action": <command>
  }]
}

The synchronization commands work on a specific file of the paper at a specific revision. Thus they all are associated to a filename and a revision. The commands are described below.

Synchronization Command

The following commands are available:

• send delta to the peer

{
  "name": "delta",
  "revision": 4324523,
  "data": [ "=100", "-2", "+test", "=34" ],
  "overwrite": false
}

• send raw text to the peer

{
  "name": "raw",
  "revision": 4324523,
  "data": "Complete raw text",
  "overwrite": false
}

• send paper deletion request to the peer

{
  "name": "nullify"
}

• send some use message to broadcast to all connected peers. If retrieve is set to true, all messages from other clients are included in the answer.

{
  "name": "message",
  "json": <json value>,
  "retrieve": false
}

Compatibility with legacy Mobwrite protocol

This section will deal with compatibility issues between the synchronization protocol used in \BlueLaTeX and the initial mobwrite version.

\BlueLaTeX -> mobwrite

{
  "peerId": "toto",
  "paperId": "v987fed987da70987f",
  "commands": [
  {
    "filename": "file1.tex",
    "revision": 432767,
    "action": {
      "name": "delta",
      "revision": 4324523,
      "data": [ "=100", "-2", "+test", "=34" ],
      "overwrite": false
    }
  },
  {
    "filename": "file2.tex",
    "revision": 87432,
    "action": {
      "name": "raw",
      "revision": 4324523,
      "data": "Complete raw text",
      "overwrite": false
    }
  }]
}

converts to

U:toto
F:432767:v987fed987da70987f/file1.tex
d:4324523:=100-2+test=34
<blank>

U:toto
F:87432:v987fed987da70987f/file2.tex
r:Complete raw text
<blank>

and may be optimized to:

U:toto
F:432767:v987fed987da70987f/file1.tex
d:4324523:=100-2+test=34
F:87432:v987fed987da70987f/file2.tex
r:Complete raw text
<blank>

mobwrite -> \BlueLaTeX

u:fraser
F:34:v987fed987da70987f/file1.tex
d:41:=200 -7 +Hello =100
F:53:v987fed987da70987f/file2.tex
d:90:=123 +Fool =296
<blank>

{
  "peerId": "fraser",
  "paperId": "v987fed987da70987f",
  "commands": [
  {
    "filename": "file1.tex",
    "revision": 34,
    "action": {
      "name": "delta",
      "revision": 41,
      "data": [ "=200", "-7", "+Hello", "=100" ],
      "overwrite": false
     }
  },
  {
    "filename": "file2.tex",
    "revision": 53,
    "action": {
      "name": "delta",
      "revision": 90,
      "data": [ "=123", "+Fool", "=296" ],
      "overwrite": false
    }
  }]
}