Annotated Obby Session

Below is the traffic generated by a simple session between Ebby and Gobby. I've annotated it so that others who may try to implement Obby support in other editors will have an easy starting point and hints on the protocol. Lines in italics are sent by Ebby, plain lines are sent by Gobby.

Everything the server sends consists of a command and parameters. Some commands also have subcommands, such as obby_document having subcommands like subscribe, sync_line, and record. The record subcommand is further divided up into ins and del.

All numbers given are in hexadecimal.

Note that this pertains to version 0.3 of the protocol. (Gobby 0.3 is rather temperamental in a few areas. Sending incorrect operation counts (see below) or positions beyond the end of the document will cause crashes. This has been fixed in 0.4.)

Sample Session

net6_client_login:phil:88ff44

The client logs on by sending a net6_client_login command, followed by their username and a hexadecimal representation of the color they want to be represented with.

obby_welcome:5:2q3zg3il03:pm6vo8c81hi8a28j6ifqfhwmnwhsku7meo7gl2lyjg81ep0qwqojc6i6lygfb2el5lxr8smhg2lufjxxgd0iyno9vn88naikemz:4d

The server responds with an obby_welcome command, the version of the protocol it supports, and (I believe) an RSA authentication.

obby_sync_init:5

The server begins the initial sync by specifying how many lines of data the sync will include.

net6_client_join:8:phil:2:88ff44

This is the client's own user information, in the format net6_user_id:username:obby_user_id:color

net6_client_join:1:puyo:1:ccccff

Any other users will be listed here with the same format. This information is necessary to get proper coloring support in the client.

obby_sync_usertable_user:3:philh:88ff44

I believe this represents other users who may have edited existing documents, but are no longer connected.

obby_sync_doclist_document:1:1:a:1

obby_sync_doclist_document:1:2:b:1

The server then sends a list of every open document. Each document is identified by a pair of numbers: one for the obby user id of the creator, and one for the per-user index of the document. (User 2's first document would be "2 1", their second "2 2", etc.) The fields here are creator's user id, creator document index, document name, and a list of users currently subscribed to the document. The server may also notify the client of new documents created by sending obby_document_create with the same parameters.

obby_sync_final

This simply indicates that the server is finished syncing with the client.

obby_document:1 1:subscribe:2

The client sends this to subscribe to one of the documents listed in obby_sync_doclist_document above using the document ID made up of the creator's ID and the document index.

obby_document:1 1:sync_init:3

The server tells the client how many lines there are in the document.

obby_document:1 1:sync_line:jibbery jabbery:0:1

obby_document:1 1:sync_line: this is also cool. :0:3:7:1

obby_document:1 1:sync_line:another line here.:0:1

Each line is sent. The numbers after the line indicate who authored it. On the second line, it says :0:3:7:1. This indicates that the first chunk of the line (starting at position 0) was authored by user 3, while the second chunk of the line (starting at position 7) was authored by user 1.

obby_document:1 1:subscribe:2

The server is done sending lines, and the client is considered subscribed.

obby_document:1 1:record:0:0:ins:37:s

obby_document:1 1:record:1:0:ins:38:e

obby_document:1 1:record:2:0:ins:39:n

obby_document:1 1:record:3:0:ins:3a:t

obby_document:1 1:record:4:0:ins:3b:

Here is an instance of the record subcommand. Our client has just entered the word 'sent ' and transmitted it to the server. The numbers in between record and ins are the local and remote operation counts. Every time the client makes a modification to the document, the local operation count should increase. Every time the server transmits a change, the client should increase its remote operation count. The number right after ins is the position at which the character should be inserted.

obby_document:1 1:record:1:0:5:ins:3c:r

obby_document:1 1:record:1:1:5:ins:3d:e

obby_document:1 1:record:1:2:5:ins:3e:c

obby_document:1 1:record:1:3:5:ins:3f:e

obby_document:1 1:record:1:4:5:ins:40:i

obby_document:1 1:record:1:5:5:ins:41:v

obby_document:1 1:record:1:6:5:ins:42:e

obby_document:1 1:record:1:7:5:ins:43:d

Note that when the server sends insertions, the position of the local operation count and remote operation count is reversed. Here a remote user just typed the word 'received' at a position right after our client typed 'sent '. Note that if the client were to transmit something at this point, it should sent 8 as the remote operation count, not 7. This is because every received modification should increase the remote operation count to one greater than what the message indicating the change shows.

obby_document:1 1:record:1:8:15:del:23:1

Here the server informs the client that a deletion has occurred with a del. Apart from the operation count information directly proceeding the record subcommand, the final two parameters indicate the position the deletion began as well as the length of the deletion.

obby_document:1 1:record:1:9:15:del:3c:8

Here a whole 8 characters have been deleted, from 0x3c to 0x44.

obby_document:1 1:unsubscribe

When you're done with a document, send an unsubscribe message to the server.

obby_document:1 1:unsubscribe:2

The server confirms you have unsubscribed. The same type of message will be used to inform you if other users unsubscribe from a document you have subscribed to.

To disconnect from the Obby session, simply close the socket.