Mozilla changes to the mobwrite protocol
Joe Walker
I thought it would be worth documenting the changes that we've made to
mobwrite as part of bespin development:
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 clearing file to 0 bytes
b/B: Buffer ID to allow request splitting
The Mozilla version of mobwrite adds the following:
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/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.
E: Error: Server added header informing the client of a failure
condition.
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)
q: Debug. This is a temporary fix to allow additional debug to be
displayed on the server console.
We have 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:
- http://hg.mozilla.org/labs/bespin/file/tip/frontend/js/bespin/mobwrite
- http://hg.mozilla.org/labs/bespin/file/tip/backend/python/bespin/mobwrite
And I keep a version of the mobwrite repo with our changes copied in
as time allows. This is currently a bit behind.
- http://bitbucket.org/joewalker/bespin-mobwrite/overview
Keen to hear of better ways of doing any of the above.
Joe.
Neil Fraser
> n/N: Request clearing file to 0 bytes
Quick check that this has been interpreted properly. n/N does not
zero the file. That could be done with "R:" The purpose of n/N is to
destroy the file completely from the server side.
The distinction is that when a client first syncs with a file, it says:
r:Hello world
Which means I have 'Hello World', but I don't consider this to be the
latest. If the server has a copy of the file, it will reply with:
R:Goodbye World (or the equivalent less-readable diff to that effect).
Which means your initial copy is out of date, here's what we have now.
However if the server has never seen the file before, it will reply
with:
d:=11
Which means, fine, I'll take what you have, I've got no changes, keep going.
Setting the file to 0 bytes would mean editors joining in the future
would have any existing text cleared. Deleting all trace of the file
fro the server would mean the server will take whatever the next
editor has.
Hope this clears things up.
--
Neil Fraser, Programmer & Wizard
http://neil.fraser.name
Joe Walker
Ahh - makes sense. Thanks.
Joe.
Alexandre Martani
will be done?
--
Alexandre Martani - amartani em gmail com
Sent from Sao Jose Dos Campos, SP, Brazil
Joe Walker
I think it's 70% likely to be done in the next month. There is a chance that the feature could get lost in the rush to the next feature, but it's hard to predict.
Joe.
Joe Walker
Neil - This list changes over time - I'd like to document the changes more permanently. The obvious places would be the mobwrite wiki or a page in this group. What do you think is best?
The latest addition is some logic to handle the case where the server is restarted. The net effect is that it ends up reverting clients to the last persisted version. We can do better than this, but I think it needs a way for the server to say "start again".
Joe.