SessionProtocol

From SynchroEdit

(Difference between revisions)
Jump to: navigation, search
Revision as of 11:36, 16 May 2006 (edit)
Kalle Alm (Talk | contribs)

← Previous diff
Revision as of 14:43, 19 May 2006 (edit)
Kalle Alm (Talk | contribs)

Next diff →
Line 31: Line 31:
=== Implementation status === === Implementation status ===
The SessionProtocol will be implemented into SynchroEdit in full in version 0.5. This version will approximately be released into the development repository in '''the end of June, 2006''' (see [[Milestones]] for details). The SessionProtocol will be implemented into SynchroEdit in full in version 0.5. This version will approximately be released into the development repository in '''the end of June, 2006''' (see [[Milestones]] for details).
-* The protocol commands PASS, HANDSHAKE, QUERY, GET, INIT, ABORT, OPEN, STATUS, STORE and QUIT have been fully implemented.+* The protocol commands PASS, HANDSHAKE, QUERY, GET, INIT, ABORT, OPEN, STATUS, STORE, QUIT and SETTING have been fully implemented.
* The protocol commands USER, SHUTDOWN have been partially implemented. * The protocol commands USER, SHUTDOWN have been partially implemented.
-* The protocol commands ACCESS, SETTING, KICK, UNKICK and RESTORE have not been implemented.+* The protocol commands ACCESS, KICK, UNKICK and RESTORE have not been implemented.
=== Session flow === === Session flow ===

Revision as of 14:43, 19 May 2006

Contents

Interface specification "SessionProtocol"

Revision 9 (May 16, 2006)

Changelog

       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" protocol command.
       5           Apr 12, 2006    Updated "QUERY" to list document on separate line to avoid ambiguity.
                                   Added "ABORT" protocol command.
       6           Apr 13, 2006    Added "RESTORE" protocol command. Using "protocol command" in place of "function" for 
                                   terminology accuracy.
       7           Apr 13, 2006    Added "QUIT" protocol command. Also added "END".
       8           Apr 20, 2006    Added "INFO" protocol command.
       9           May 16, 2006    Basic response service authentication support.

Description

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 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.

Definitions

     "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. This version will approximately be released into the development repository in the end of June, 2006 (see Milestones for details).

  • The protocol commands PASS, HANDSHAKE, QUERY, GET, INIT, ABORT, OPEN, STATUS, STORE, QUIT and SETTING have been fully implemented.
  • The protocol commands USER, SHUTDOWN have been partially implemented.
  • The protocol commands ACCESS, KICK, UNKICK and RESTORE have not been 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
                         time.
  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:               ACCESS [session] [user] [pass] [ip] [role]
     string [user]       A username or "*" for a FFA session.
     string [pass]       A password.
     string [ip]         An ip number, or "*" for unspecified.
     string [role]       "none", "reader", "writer", or "admin"
  Success response:      ACK
  Failure response:      NAK
  Description:           Define a user access rule. 
  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.
  Command:               KICK [user] [time] [message]
     int [time]          Determines, if set, the # of minutes before [user] may return.
     string [message]    The message to display to [user] upon being kicked.
  Success response:      ACK
  Failure response:      NAK
  Description:           Remove a user from the session.
  Command:               UNKICK [user]
  Success response:      ACK
  Failure responses:     UNKNOWN, CLEAN
  Description:           Remove a timer upon a user. Returns "UNKNOWN" if user
                         is not a known editor of the session. Returns "CLEAN"
                         if the user does not have a kick timer.

Example connection sequence

  1. Server→Client> SynchroEdit 0.3.9 running on example.com

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