SessionProtocol
From SynchroEdit
Contents |
Interface specification "SessionProtocol"
Revision 10 (October 31, 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" 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)
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 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.
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.
- 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
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: 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
- 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]".
- 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.
- 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.
