SessionProtocol

From SynchroEdit

(Difference between revisions)
Jump to: navigation, search
Revision as of 10:47, 20 April 2006 (edit)
WikiAdm (Talk | contribs)

← Previous diff
Revision as of 10:47, 20 April 2006 (edit)
WikiAdm (Talk | contribs)

Next diff →
Line 67: Line 67:
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. 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: ====+==== <Request server> to <SynchroEdit> specification ====
Command: QUERY Command: QUERY
Success response: DOCUMENT [document] Success response: DOCUMENT [document]

Revision as of 10:47, 20 April 2006

Contents

Interface specification "SessionProtocol"

Revision 8 (Apr 20, 2006)

Changelog

       Revision    Date            Description
       1           Aug 25, 2005    Specification initiated.
       1-2         Aug 25, 2005    Renamed to "SessionProtocol" as it has nothing to do with DOM.
       2-3         Apr 10, 2006    Revamped specification completely.
       3-4         Apr 11, 2006    Added "QUERY", "STATUS" protocol command.
       4-5         Apr 12, 2006    Updated "QUERY" to list document on separate line to avoid ambiguity.
                                   Added "ABORT" protocol command.
       5-6         Apr 13, 2006    Added "RESTORE" protocol command. Using "protocol command" in place of "function" for 
                                   terminology accuracy.
       6-7         Apr 13, 2006    Added "QUIT" protocol command. Also added "END".
       7-8         Apr 20, 2006    Added "INFO" protocol command.

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 DomExport 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 April, 2006.

  • The protocol commands QUERY, GET, INIT, ABORT, OPEN, STATUS, STORE and QUIT have been fully implemented.
  • The protocol command SHUTDOWN has been partially implemented.
  • The protocol commands ACCESS, SETTING, 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> 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:               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.
Personal tools