Labs/Bespin/DesignDocs/Collaboration/Mobwrite

From MozillaWiki
Jump to: navigation, search

Mozilla changes to the Mobwrite Protocol

The mobwrite protocol defines the following 'header names':

  • u/U: User, more correctly known as page identifier
  • f/F: File, identifier for the file to be synchronized
  • d/D: Request an edit by posting a diff
  • r/R: Request a raw file dump
  • n/N: Request deleting the file
  • b/B: Buffer ID to allow request splitting

Added Headers

h/H: Handle

A username:ip-addr combination, 'client' header but added by the server, so it can be trusted. Needed to handle non world-write access.

C: Collaborators

Server added header informing the client of handles of other clients collaborating on the file.

x: Close view

The client may be able to tell the server to close a view, reducing memory consumption, and allowing more accurate display of collaborators.

When a single view is being closed, the request will look like this:

u:<username>
x:<filename>

To close all views owned by a window (as would be called by mobwrite.unload_) the request will look like this:

u:<username>
x:all

E: Error

Server added header informing the client of a failure condition. If the error relates to a single file then the format is:

E:<filename>:<message>

If the error relates to the parsing of the input message or some other server error, the format is:

E:all:<message>

There are internationalization issues with this layout. In the future perhaps a system of error codes should be adopted.

O: Read Only

Server added to inform the client that access to the given file is read-only. Attempts to alter it will be ignored.

S: Save state

The mobwrite version of the file is not considered 'final' until saved. This server added header informs clients if the file has changed since editing. (Planned, not implemented)

m: Metadata

For transmitting cursor type information

ShareHandler Additions

Mozilla has also added a number of extra events to allow mobwrite to inform a shareHandler of the state of a file:

  • reportCollaborators(userEntriesArray) Called by mobwrite to update the list of collaborators working on a given file
  • raiseError(message, isRecoverable) Called when mobwrite detects an error condition
  • setReadOnly(boolean) Called when access to the given file changes
  • syncWithoutChange() mobwrite does not call setClientText() or patchClientText() if it believes that no changes are needed. This allows an editor to know that an initial synchronization has taken place even when no changes are needed.
  • setDirty(boolean) Called whenever a collaborator saves the file (Planned, not implemented)

All of our work on these additions is focussed primarily on Mozilla requirements rather than trying to solve all generic problems, however I'm keen to evolve our alterations into more generic solutions.

The latest versions are always available in the bespin repo:

And I keep a version of the mobwrite repo with our changes copied in as time allows. This is currently a bit behind.