대문 최근에 바뀐 글 새소식 찾기 하우투 문제 제안

SubEthaEditProtocol

Meta Information

The purpose of this page is to describe the protocol used by the SubEthaEdit? collaborative editor. This information can then be used to interface other editors with SubEthaEdit?, for example Emacs.

For projects working on interfacing Emacs and SubEthaEdit? see:

Reverse Engineering Requirements

Before getting on to the meat of this page: Please do not add any information of questionable source. This means that information gleaned from examination of the binary you got from http://codingmonkeys.de is right out, including simply running strings on it. What’s in is information gleaned by any of the methods described in http://samba.org/ftp/tridge/misc/french_cafe.txt -- specifically, anything that only involves running the program, and examining the information it sends across the wire. While it is my belief that reverse engineering for the purpose of interoperability is a protected right, it’s not 100% clear, esp as you go from jurisdiction to jurisdiction. I figure that if Andrew Tridgel feels OK saying in open court that he did these things against Microsoft, we’re probably safe from the presumably less litigious codingmonkeys.

Introduction

The SubEthaEdit? protocol has a fair number of parts. You’ve probably heard that it uses Bonjour (AKA ZeroConf, Rendezvous). While this is true, its use of Bonjour isn’t interesting; it’s only useful when you have multiple users on the same subnet. In any case, it simply advertises <username>@<computername>._see, with no additional data that I can see. I have no particular interest in supporting this part of the protocol: sessions will be initiated by giving the hostname or IP and optionally port. (The default port is 6942, which codingmonkeys says can be remembered because 6*9=42 – it’s a Hitchhiker's Guide to the Galaxy reference.)

The BEEP Protocol

The actual conversations between SubEthaEdit? client and server are done on top of the BlocksExtensibleExchangeProtocol? (RFC 3080 and RFC 3081), which is a generic, channel multiplexed, transport protocol that uses XML and MIME. (Very simple versions of both in case of the SubEthaEdit? protocol – the only MIME header used is Content-Type.)

The BEEP protocol manages multiple virtual channels for independent data streams over a single connection. Messages in the special channel 0 are fully specified in RFC 3080, all other channels are freely usable by application protocols. Each channel has an associated profile, identified by an URI, that defines the protocol for messages exchanged on that channel.

The authors of SubEthaEdit? decided to ignore the recommendation of the RFC authors to use MIME. Instead, the payloads exchanged on the application channels consist of three-letter major command codes, mostly followed by three-letter minor command codes, often followed by bencoded data.

Note by a SEE author: we did this for the obvious reason that: a) having our own profiles means that doesn’t worry anybody else and b) since we use a lot of very small messages, the redundant MIME headers would just add up and use unnecessary bandwidth).

Messages generally look similar to the following example:

MSG 1 0 . 0 97
GRTd3:url27:see://codingmonkeys.de:67423:uid36:770da15c-0cb0-10da-a8ba-4a773bbddd094:vers3:200e
END

Here, the bencoded data starts immediately after ‘GRT’. Bencoding is the data format used by bittorent; it is specified (very briefly) at http://www.bittorrent.com/protocol.html. The dialect that SubEthaEdit? uses has a small extension: Strings may have a ‘.’ (ASCII 0x2e) after the length instead of a ‘:’. These dot-strings are used for user-identifiers, and other such things that are not human-readable strings, but rather a bunch of random bytes. I suspect the correct interpretation is that ‘.’ strings contain binary data without semantics, whereas ‘:’ strings are always UTF-8. (Note that the length for strings of both types is in bytes, not logical characters.)

Structure of a Typical Session

The following section describes the structure of a typical session (with encryption disabled). The roles “Initiating” and “Listening” peer refer to the network connection. Although the description here distinguishes these roles, the protocol seems to be symmetrical.

  1. BEEP Protocol Setup Sequence TODO
  2. Handshake Protocol
      1. Initiating peer requests channel (profile: http://www.codingmonkeys.de/BEEP/SubEthaEditHandshake)
      2. Initiating peer sends SubEthaEditHandshake GRT message
      3. Listening peer replies with SubEthaEditHandshake ACK message
      4. Initiating peer closes the channel
  1. Status Protocol
      1. Initiating peer requests status channel (profile: http://www.codingmonkeys.de/BEEP/TCMMMStatus)
      2. Initiating peer sends TCMMMStatus USRCHG, FCAYES, STAVIS and USRRCH messages
      3. Listening peer acknowledges all messages with empty replies
      1. Listening peer requests status channel (profile: http://www.codingmonkeys.de/BEEP/TCMMMStatus)
      2. Listening peer sends TCMMMStatus USRCHG, FCAYES, STAVIS, USRRCH messages
      3. Listening peer sends DOCANN messages for its documents
      4. Initiating peer acknowledges all messages with empty replies
  1. Session Protocol This exchange happens each time one of the peers wishes to participate in an actual editing session. The content and structure depends on the nature of the document, the number of participants and possibly other parameters. Note that the roles "Requesting" and "Serving" do not correspond to the "Listening" and "Initiating" roles above.
      1. Requesting peer requests channel (profile http://www.codingmonkeys.de/BEEP/SubEthaEditSession)
      2. Requesting peer sends SubEthaEditSession JONJON message
      3. Serving peer sends empty reply
      4. Serving peer replies with SubEthaEditSession JONACK message
      5. Requesting peer sends empty reply
      6. Serving peer sends SubEthaEditSession SESINF message
      7. Requesting peer sends SubEthaEditSession USRREQ reply
      8. to be continued

BEEP Profiles used by SubEthaEdit

As soon as an initiating SEE instance has an open socket, it sends

<greeting>
  <profile uri="http://www.codingmonkeys.de/BEEP/SubEthaEditHandshake"/>
  <profile uri="http://www.codingmonkeys.de/BEEP/TCMMMStatus"/>
  <profile uri="http://www.codingmonkeys.de/BEEP/SubEthaEditSession"/>
</greeting>

on BEEP channel 0, advertising support for three BEEP profiles:

The listening instance replies with an almost identical message, the difference being one additional profile:

Upon receiving this message from the listening end, the initiating client can request a SubEthaEditHandshake channel from the server:

MSG 0 1 . 301 136
Content-Type: application/beep+xml

<start number="1"><profile uri="http://www.codingmonkeys.de/BEEP/SubEthaEditHandshake"/></start>
END

or request TLS encryption:

MSG 0 1 . 263 135
Content-Type: application/beep+xml

<start number='1'><profile uri='http://iana.org/beep/TLS'><![CDATA[<ready />]]></profile></start>END

The Handshake Profile (SubEthaEditHandshake)

GRT Message
This is sent immediately upon initiation of the channel. The listening peer answers with a GRT message that is identically structured but can have different dictionary values. Takes a dictionary with the following values:
ACK Message
Acknowledges a message from the other end of the connection. Possibly the simplest payload, it takes no extra data of any sort. FIXME: what packet is this acking? This seems to be send by the initiating peer after it received the ‘GRT’ response from the listening peer.
empty Message
It seems like the listening peer replies to the ACK message of the initiating peer by sending a BEEP message that has no payload. This message seems to conclude the handshake.

…more later.

The Status Profile (TCMMMStatus)

A TCMMMStatus channel is created by both sides of the connection. The listening peer requests a TCMMMStatus channel after receiving the ‘ACK’ message on the handshake channel.

STAVIS Message
Status Visible - Probably changes status of the sending peer to visible
STAINV Message
Status Invisible - Probably changes status of the sending peer to invisible
FCAYES Message
FCA (?) Yes - No idea
USRCHG Message
User Change (?) - Gives a short description of a user, a dictionary with the following entries:
USRRCH Message
User Reachability - Probably transmitting a SubEthaEdit? URL that can be used to reach the sending peer on the Internet.
USRREQ Message
User Request (?) - Probably a list of users that the receiving peer should send full information for. List of dictionaries of the following form
USRFUL Message
User Full (?) - A longer user description, including:
DOCANN Message
Document Announce (?) - Announces each document that the peer has to offer. A list of dictionaries of the following form

The Session Profile (SubEthaEditSession)

Started by the client (either side?) to join a particular document.

JONJON Message
Join request - sent by the client
JONACK Message
Join Acknowledge - Empty acknowledge command
SESINF Message
Session Information - Information about the session, from the document owning peer
USRREQ Message
Probably identical to USRREQ in TCMMMStatus profile above.
SESCON Message
Session Connection (?) - Original document status ?
DOCMSG Message
Document Message - Sent when document string or the text range selected by one of the editors changes.

CategoryInterface