From SynchroEdit

Jump to: navigation, search


Interface specification "SessionProtocol"

Revision 10 (October 31, 2006)


       Revision    Date            Description
       1           Aug 25, 2005    Specification initiated.
       2           Aug 25, 2005    Renamed to "SessionProtocol" as it has nothing to do with DOM.
       3           Apr 10, 2006    Revamped specification completely.
       4           Apr 11, 2006    Added "QUERY", "STATUS" p.c.
       5           Apr 12, 2006    Updated "QUERY" to list document on separate line to avoid ambiguity.
                                   Added "ABORT" p.c.
       6           Apr 13, 2006    Added "RESTORE" p.c. Using "p.c." in place of "function" for 
                                   terminology accuracy.
       7           Apr 13, 2006    Added "QUIT" p.c. Also added "END".
       8           Apr 20, 2006    Added "INFO" p.c.
       9           May 16, 2006    Basic response service authentication support.
       10          Oct 31, 2006    Removed "ACCESS", "KICK", "UNKICK" p.c., included reference to ESPI,
                                   and updated Implementation status.
(p.c. = protocol command)


The purpose of the SessionProtocol is to provide a communication protocol between an application and SynchroEdit, and is used to instantiate new or manipulate existing SynchroEdit sessions. The session protocol is complemented by the ExternalServicePOSTInterface which somewhat takes control beyond the document instantiation. The applications which will communicate with SynchroEdit are here referred to as "request servers". The protocol covers the actions of setting sessions up using existing XHTML-formatted data, and leaves the conversion to and from whatever native format there may be to the request servers and their relatives. SynchroEdit has an internal interface called SedExport which may or may not be used to ease this process, however there are many tools out there which do a good job of converting e.g. HTML to XHTML and vice versa, already. This specification describes the "service protocol" of SynchroEdit.

Note regarding revision 10 of this specification: Prior to this point, the role of the response service was much broader than it is now. The response service was meant to handle some form of internal authentication system, with sophisticated access control and similar, but with the introduction of [ExternalServicesPOSTInterface|ESPI] we concluded that this was no longer necessary. The two services (response service and ESPI) complement each other.


     "native system"  - the system, e.g. a wiki that holds the original data
     "SynchroEdit"    - the simultaneous editing session server
     "request server" - the server which acts as a layer between the native system and SynchroEdit
     "user"           - one or several users
     "native:content" - the content being edited in its native form
     "XHTML:content"  - the content being edited in XHTML form
     "session"        - a string identifier for a particular session

Implementation status

The SessionProtocol will be implemented into SynchroEdit in full in version 0.5.

  • The protocol commands PASS, HANDSHAKE, QUERY, GET, INIT, ABORT, OPEN, STATUS, STORE, QUIT and SETTING have been fully implemented.
  • The protocol command SHUTDOWN has been partially implemented.

Session flow

Parenthesized entries in the session flow are suggestive, while non-parenthesized entries are required.

  • (<User> accesses <native system>.)
  • (<User> requests from <native system> an edit on <native:content>.)
  • (<Native system> authenticates to, and requests from <request server> a session for <native:content>, allowing <user> from <IP> editing privileges.)
  • <Request server> requests <session> from <SynchroEdit> for <native:content>.
  • If not found,
    • (<Request server> converts <native:content> into <XHTML:content>)
    • <Request server> requests a unique, new session identifier <session> from <SynchroEdit>.
    • <Request server> stores <XHTML:content> as <session>.xhtml.
    • <Request server> requests from <SynchroEdit> that <session> is initiated and is given back <authport>. (<authport>+1 is the <commport>)
    • (<Request server> informs <SynchroEdit> that <user> from <IP> has editing privileges on <session>.)
    • (<Request server> responds to <native system> with the <authport> for the simultaneous edit of <session>.)
  • If found,
    • (<Request server> informs <SynchroEdit> that <user> from <IP> has editing privileges on <session>.)
    • (<Request server> responds to <native system> with the <authport> for the simultaneous edit of <session>.)
  • (<Native system> forwards <user> to the session in whatever manner.)
  • (<User> enters and participates in the editing session.)
  • (<SynchroEdit> sends updated <XHTML:content> to <request server> at specified interval, if specified.)
  • (<User> leaves editing session.)
  • A number of conditions exist which determine when <SynchroEdit> should end a session. When the specific condition(s) are met, <SynchroEdit> ends.
  • (The <SynchroEdit> on!SessionTerminate setting determines what happens next, which should most likely be a connection back to <request server> to let it know the session is over.)
  • (<Request server> converts updated <XHTML:content> into <native:content>)
  • (<Request server> requests from native system an update of <native:content>.)

Protocol specification

The generic success response is for non-informative (i.e. active) protocol commands is "ACK" (acknowledged command). The generic failure response is "NAK" (not acknowledged) except in the cases where the generic failure is deemed ambiguous, in which case specific error responses are in place -- such as ISOPEN, UNINITIALIZED, and FAILED. All responses are concluded, using the "END" response.

<Request server> to <SynchroEdit> specification

  Command:               USER [name]
     string [name]       A username.
  Success response:      No response.
  Description:           Username statement. The USER command should be issued directly after establishing a
                         connection with a SynchroEdit response service. (See HANDSHAKE command below)
  Command:               PASS [word]
     string [word]       Plaintext password.
  Success response:      No response.
  Failure response:      Access denied.
  Description:           Provide password to response service. This command should be the second line, directly 
                         following the USER statement.
  Command:               HANDSHAKE
  Success response:      See GET below.
  Description:           Perform an unauthenticated GET on a specific document. This command is
                         used by handshake.cgi to get info about a session.
  Command:               QUERY
  Success response:      DOCUMENT [document]
                         IS [session] [authport] [sessargs]
     string [document]   The document name.
     string [session]    The identifier for an existing SynchroEdit session.
     int [authport]      The port on which the session is running.
     string [servargs]   A colon-separated list of session arguments.
        [...]            (Repeated for each existing session.)
  Description:           Query the service for existing (public) sessions.
  Command:               INFO
  Success response:      LOCALPATH [directory]
                         SERVERMODEL [model]
                         UPTIME [millis]
     string [directory]  The server-side directory where SE sessions are stored.
     string [model]      "PROD" or "DEV", depending on the server layout.
     long   [millis]     Milliseconds the server has been running.
  Description:           Request information about the SynchroEdit server.
  Command:               QUIT
  Description:           Close connection.
  Command:               GET [document]
     string [document]   The native name of a particular document.
  Success response:      HAVE [session] [authport] [sessargs]
  Failure responses:     UNINITIALIZED, NAK
  Description:           Determine if [document] is currently being edited. If
                         UNINITIALIZED is returned, it means the document is
                         about to be set up, but hasn't gotten there yet. NAK means
                         the document is not being edited at all.
  Command:               INIT [document]
     string [document]   The native name of a particular document.
  Success response:      SESSION [session]
  Failure response:      NAK
  Description:           Set SynchroEdit up with a new session for [document].
                         If SynchroEdit is already editing [document], "NAK" 
                         is returned.
  Command:               ABORT [document]
  Success response:      ACK
  Failure response:      ISOPEN, NAK
  Description:           Abort an initialized (but not opened) session. This is used if
                         e.g. a document failed for some reason to be stored as the session
                         file by a response server. ISOPEN is returned if the document is
                         already opened. In this case, SHUTDOWN should be used instead.
                         NAK is returned if the document was not found in the active sessions.
                         Unopened, initialized documents are purged after a certain amount of
  Command:               OPEN [document]
  Success response:      HAVE [session] [authport] [sessargs]
  Failure response(s):   ISOPEN, NAK, FAILED
  Description:           Instantiate a particular session and allow clients to connect.
                         ISOPEN means the session is already opened. NAK means the
                         session does not exist. FAILED means the SynchroEdit session
                         failed to instantiate.
  Command:               STATUS [session]
  Success response:      STATUS [session]
                         DOCUMENT [document]
                         AGE [timestamp]
                         USERS [userlist]
                         CONTRIBUTORS [userlist]
                         DOCSIZE [bytes]
  Description:           Request information about a particular running session,
                         acquiring its age, users, contributors, etc.
  Command:               SETTING [session] [setting] [value]
     string [setting]    The name of a setting.
     string [value]      The value -'-.
  Success response:      ACK
  Failure response:      NAK
  Description:           Modify a SynchroEdit setting run-time. Some settings may not
                         be altered run-time, such as local_path.
  Command:               SHUTDOWN [session] [time]
     int [time]          Minutes before [session] is forcibly shutdown.
  Success response:      ACK
  Failure response:      NAK
  Description:           Terminate a SynchroEdit session.
  Command:               STORE [session]
  Success response:      ACK
  Failure response:      NAK
  Description:           Save the current session to disk but continue editing.

Example connection sequence

  1. Server→Client> SynchroEdit 0.3.9 running on

The welcome message is displayed when a user connects to a response service, and is in the format "[APP] [VERSION] running on [HOSTNAME]".

  1. Client→Server> USER root

At this point the client has two options. Supply USER and PASS for authentication and extended access to the response service, or supply a HANDSHAKE command on a specified document and retrieve its data only. The latter requires no authentication.

  1. Client→Server> PASS secret

The response service will remain quiet unless a USER/PASS combination is invalid. If it is invalid the server will print "Access denied." and terminate the connection. Otherwise, the server will expect commands directly following the PASS statement.

Personal tools