src/jabber_whiteboard/protocol/protocol.tex

   1 \documentclass[11pt]{article}
   2 \usepackage{enumerate,fancyvrb,graphicx}
   3 \usepackage[utf8x]{inputenc}
   4 \usepackage{fullpage}
   5 \linespread{1.25}
   6
   7 \begin{document}
   8 \title{The Inkboard protocol specification}
   9 \author{David Yip}
  10 \maketitle
  11
  12 \begin{abstract}
  13 Inkboard is a component of the Inkscape vector graphics editor that allows Inkscape users to collaborate on Inkscape documents.  This document describes the protocol used by Inkboard clients to manage sessions, communicate document changes, and resolve conflicting changes.
  14 \end{abstract}
  15
  16 \tableofcontents
  17
  18 \section{Introduction}
  19 \subsection{Overview}
  20 Inkboard is a component of the Inkscape vector graphics editor that allows Inkscape users to collaborate on Inkscape documents.  The protocol is implemented as a layer on top of the XMPP instant-messaging protocol\cite{rfc3920}, which is the core of the Jabber instant-messaging system.
  21
  22 \subsection{Terminology}
  23 The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119\cite{rfc2119}.
  24
  25 \section{Definitions}
  26 The following definitions are used throughout this document.
  27 \begin{itemize}
  28 \item {\em Inkboard user}: The user of an Inkboard client.
  29 \item {\em Inkboard change}: An XML fragment specifying a change to be made to a document.  A full listing of change types is given in Section \ref{change-types}.
  30 \item {\em User-to-user session}: An Inkboard session only occurring between two users.  Analogous to traditional text-based instant messaging between two users.
  31 \item {\em User-to-conference session}: An Inkboard session occurring between a user and a multi-user conference room.  Analogous to traditional text-based chat rooms.
  32 \end{itemize}
  33
  34 \subsection{Dramatis Personae}
  35 Throughout this document, references will be made to the following fictional entities:
  36 \begin{center}
  37 \begin{tabular}[t]{|c|c|}
  38 \hline
  39 Entity Name & Role \\
  40 \hline
  41 Romeo & Inkboard user \\
  42 \hline
  43 Juliet & Inkboard user \\
  44 \hline
  45 Chat & Conference room \\
  46 \hline
  47 \end{tabular}
  48 \end{center}
  49
  50 \section{A brief overview of the Inkboard architecture}
  51 Because the Inkboard protocol is heavily influenced by the architecture of the Inkboard component, a brief overview of Inkboard's architecture may be helpful in understanding the Inkboard protocol.
  52
  53 Inkboard is implemented as a listener attached to the Inkscape undo/redo mechanism.  Inkscape maintains one undo log and one redo log per document.  Inkscape undo log listeners receive notifications on the following events:
  54
  55 \begin{enumerate}
  56 \item An undo action was requested by the user.
  57 \item A redo action was requested by the user.
  58 \item A set of changes was committed to the undo log.
  59 \end{enumerate}
  60
  61 When any of these events occur, the Inkboard undo listener receives a pointer to an object of type \texttt{Inkscape::XML::Event}, which represents manipulations on the XML tree representing an SVG document.  The Inkboard undo listener serializes these \texttt{Inkscape::XML::Event} objects into Inkboard changes and then sends them out to the recipient.
  62
  63 The receiving Inkboard client attempts to deserialize these messages into \texttt{Inkscape::XML::Event} objects.  If deserialization is successful, these \texttt{Inkscape::XML::Event} objects are replayed using the Inkscape undo mechanism.
  64
  65 \section{Inkboard and XMPP}
  66 \subsection{Format of Inkboard messages}
  67 Inkboard messages are encapsulated in XMPP message stanzas, the format of which is described in \cite{rfc3920}.  Inkboard data is wrapped in an \texttt{<inkboard>} element which MUST contain the following attributes:
  68 \begin{center}
  69 \begin{tabular}[t]{|c|c|}
  70 \hline
  71 Attribute & Description \\
  72 \hline
  73 \texttt{protocol} & Version of the Inkboard protocol utilized by the client that sent the message.\\
  74 & Clients conforming to this specification MUST use version number 2 in this field. \\
  75 \hline
  76 \texttt{type} & Numeric identifier of a message type. \\
  77 &  See Section \ref{message-types} for a full listing of Inkboard message types. \\
  78 \hline
  79 \texttt{seq} & Sequence number of the message.  This MUST be monotonically increasing.  \\
  80 \hline
  81 \end{tabular}
  82 \end{center}
  83
  84 Inkboard changes MUST be wrapped inside an \texttt{<x:inkboard-data>} element inside the \texttt{<inkboard>} element.  The \texttt{<x:inkboard-data>} tag MUST contain zero or more Inkboard changes.  See Section \ref{example-messages} for examples of Inkboard messages, and Section \ref{change-types} for a full listing of Inkboard change types.
  85
  86 The Inkboard XML schema is available at \texttt{http://inkscape.org/inkboard}.
  87
  88 \subsection{Inkboard message queuing rules}
  89 Inkboard messages MUST be processed as soon as possible (i.e. as soon as they are received), with the sole exception of Inkboard messages of type \texttt{CHANGE}.
  90
  91 Inkboard messages of type \texttt{CHANGE} SHOULD NOT be applied to a document as they are received; instead, Inkboard clients SHOULD queue up changes until receipt of a \texttt{COMMIT} message.  Upon receipt of a \texttt{COMMIT} message from a particular Inkboard client, Inkboard clients implementing the queuing method MUST commit all uncommitted changes received from that particular client.
  92
  93 \subsection{Example Inkboard messages}
  94 \label{example-messages}
  95 \subsubsection{Null message}
  96 \VerbatimInput[tabsize=2]{inkboard-message-examples/null-message.txt}
  97
  98 \subsubsection{Sending a change}
  99 \VerbatimInput[tabsize=2]{inkboard-message-examples/1-1-change-message.txt}
 100
 101 \section{Session establishment}
 102 \subsection{User-to-user}
 103 User-to-user sessions MUST be negotiated according to the procedure outlined below.
 104
 105 \begin{figure}
 106 \label{u2u-session-establishment-figure-accept}
 107 \centering
 108 \includegraphics[width=5in]{eps/session-invite-u2u-01.eps}
 109 \caption{Initiation of an Inkboard session between two users.}
 110 \end{figure}
 111
 112 \begin{figure}
 113 \label{u2u-session-establishment-figure-reject}
 114 \centering
 115 \includegraphics[width=5in]{eps/session-invite-u2u-02.eps}
 116 \caption{Attempt to initiate an Inkboard session between two users, with the second user rejecting the invitiation.}
 117 \end{figure}
 118
 119 \begin{enumerate}
 120 \item Romeo invites Juliet to a user-to-user session using his Inkboard client.
 121 \item Romeo's Inkboard client sends a \texttt{CONNECT\_REQUEST\_USER} message to Juliet's Inkboard client.
 122 \item Juliet's Inkboard client notifies Juliet that Romeo has invited her to a user-to-user session.
 123 \begin{enumerate}
 124 \item If Juliet accepts Romeo's invitation:
 125 \begin{enumerate}
 126 \item Juliet's Inkboard client sends a \texttt{CONNECT\_REQUEST\_RESPONSE\_USER} message to Romeo's Inkboard client.
 127 \item Romeo's Inkboard client notifies Romeo that Juliet has accepted his invitation.
 128 \item Romeo's Inkboard client sends a \texttt{CONNECTED\_SIGNAL} message to Juliet's Inkboard client.
 129 \item Romeo's Inkboard client serializes the current contents of Romeo's SVG document.
 130 \item Romeo's Inkboard client sends a \texttt{DOCUMENT\_BEGIN} message to Juliet's Inkboard client.
 131 \item Romeo's Inkboard client sends the serialized document to Juliet's Inkboard client as a series of \texttt{CHANGE} messages.
 132 \item Romeo's Inkboard client sends a \texttt{COMMIT} message to Juliet's Inkboard client.
 133 \item Upon receipt of Romeo's \texttt{DOCUMENT\_BEGIN} message, Juliet's Inkboard client prepares to process incoming \texttt{CHANGE} messages from Romeo's Inkboard client by doing the following actions:
 134 \begin{enumerate}
 135 \item Juliet's existing document is cleared.
 136 \item Juliet's Inkboard client prepares to receive and process incoming \texttt{CHANGE} messages.
 137 \end{enumerate}
 138 \item Upon receipt of Romeo's \texttt{COMMIT} message, Juliet's Inkboard client commits all changes sent by Romeo's Inkboard client.
 139 \end{enumerate}
 140 \item If Juliet rejects Romeo's invitation:
 141 \begin{enumerate}
 142 \item Juliet's Inkboard client sends a \texttt{CONNECT\_REQUEST\_REFUSED\_BY\_PEER} message to Romeo's Inkboard client.
 143 \item Romeo's Inkboard client notifies Romeo that Juliet refused his invitation.
 144 \end{enumerate}
 145 \end{enumerate}
 146 \end{enumerate}
 147
 148 \subsubsection{Example of accepted invitation}
 149
 150 \subsubsection{Example of rejected invitation}
 151
 152 \subsection{User-to-conference}
 153 User-to-conference sessions MUST be negotiated according to the procedures outlined below.
 154
 155 The procedure for user-to-conference session establishment differs based on whether or not there already exist Inkboard users in a Jabber conference room; therefore, there are two modes of operation for Inkboard clients.  These two modes are dubbed {\em synchronization mode}, in which an Inkboard client synchronizes with the rest of the conference, and {\em transceiver mode}, in which an Inkboard client transmits and receives changes to/from all other conference members.  The presence of other Inkboard users is determined by the following rules:
 156
 157 \begin{enumerate}
 158 \item If the user joining a user-to-conference session is the only member of the conference, then that user's Inkboard client SHOULD assume that it is the first participant in a chatroom and immediately enters transceiver mode.
 159 \item If the user joining a user-to-conference session is not the only member of the conference, then that user's Inkboard client MUST enter synchronization mode.  See Section \ref{joining-existing-conference} for synchronization mode procedures.
 160 \end{enumerate}
 161
 162 Room rosters MUST be processed according to the procedures given in Section 6.3.3 of \cite{jep0045}.
 163
 164 \begin{figure}
 165 \label{u2c-session-establishment-figure-accept}
 166 \centering
 167 \includegraphics[width=5in]{eps/session-invite-u2c-01.eps}
 168 \caption{Initiation of an Inkboard session between a user and a conference in which Inkboard users are already involved in a conference.}
 169 \end{figure}
 170
 171 \subsubsection{User establishing a new conference}
 172 \begin{enumerate}
 173 \item
 174 \end{enumerate}
 175
 176 \subsubsection{User joining an existing conference}
 177 \label{joining-existing-conference}
 178 \begin{enumerate}
 179 \item
 180 \end{enumerate}
 181
 182 \section{Session establishment error cases}
 183 \subsection{Incompatible protocol versions}
 184
 185 \subsubsection{User-to-user}
 186
 187 \subsubsection{User-to-conference}
 188
 189 \subsection{Duplicate session establishment requests}
 190
 191 \subsection{Mutual invitation}
 192
 193 \section{Transmitting changes}
 194 \subsection{User-to-user}
 195
 196 \subsection{User-to-conference}
 197
 198 \section{Change conflict resolution}
 199
 200 \section{Client requirements}
 201 [describe what is required of a client implementing this protocol; this will probably need to delve into the Inkscape document model a little bit]
 202
 203 \section{Contributors}
 204 [TBW]
 205
 206 \section{Acknowledgments}
 207 [TBW]
 208
 209 \section{Security considerations}
 210 [TBW]
 211
 212 \section{IANA Considerations}
 213 [TBW, although most likely ``None'']
 214
 215 \appendix
 216 \section{Appendices}
 217
 218 \subsection{Full listing of message types}
 219 \label{message-types}
 220
 221 \subsection{Full listing of change types}
 222 \label{change-types}
 223
 224 \bibliographystyle{alpha}
 225 \bibliography{protocol.bib}
 226
 227 \end{document}