From: daleharvey Date: Sun, 25 Jun 2006 19:26:36 +0000 (+0000) Subject: added protocol documents to jabber_whiteboard X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=dbdbcd1a49a62fa24fa6a53f5ad833499eeaef4b;p=inkscape.git added protocol documents to jabber_whiteboard --- diff --git a/src/jabber_whiteboard/architecture/components.svg b/src/jabber_whiteboard/architecture/components.svg new file mode 100644 index 000000000..ba082ac72 --- /dev/null +++ b/src/jabber_whiteboard/architecture/components.svg @@ -0,0 +1,445 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + Inkscape interface + + Protocol implementations + (implementors ofInkscape::Whiteboard::Protocolinterface) + + + + ... + SessionManager::_inkboards + + interacts with + + + + + + + Inkboard component diagram + + SessionManager + + + InkboardProtocol + + + + JabberWhiteboardProtocol + + + + InkboardDocument + + + + InkboardDocument + + + + InkboardDocument + + + + + + XML::LogBuilder + + + + + + diff --git a/src/jabber_whiteboard/architecture/inkboard-document.svg b/src/jabber_whiteboard/architecture/inkboard-document.svg new file mode 100644 index 000000000..04d4a19c4 --- /dev/null +++ b/src/jabber_whiteboard/architecture/inkboard-document.svg @@ -0,0 +1,287 @@ + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + Inkscape::Whiteboard::InkboardDocument + + + + Serializer + + + + Deserializer + + + + KeyNodeTable + + (from SessionManager) + (to XML::LogBuilder) + + (to SessionManager) + + + + + (sp_repr_replay_logactually commits changes) + + diff --git a/src/jabber_whiteboard/protocol/README.txt b/src/jabber_whiteboard/protocol/README.txt new file mode 100644 index 000000000..b13a2efa0 --- /dev/null +++ b/src/jabber_whiteboard/protocol/README.txt @@ -0,0 +1,11 @@ +To do a LaTeX compilation of the Inkboard protocol specification, do the following: + +1) Run svg2eps.sh to convert the SVGs to EPS files, or do some equivalent procedure. +2) Run the command + + latex protocol + +The fancyvrb, enumerate, and graphicx packages are required. + + +IMPORTANT NOTE: This protocol specification is nowhere near finalized. \ No newline at end of file diff --git a/src/jabber_whiteboard/protocol/disconnect-u2u-01.svg b/src/jabber_whiteboard/protocol/disconnect-u2u-01.svg new file mode 100644 index 000000000..3977edc8c --- /dev/null +++ b/src/jabber_whiteboard/protocol/disconnect-u2u-01.svg @@ -0,0 +1,167 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + Romeo + + DISCONNECTED_FROM_USER_SIGNAL + Inkboard session: disconnection and termination of session (user-to-user) + + Juliet + Client disconnect; Inkboard document is removedfrom tracking queue + Client disconnect; Inkboard document is removedfrom tracking queue.Inkboard notifies Juliet of Romeo's disconnection. + + diff --git a/src/jabber_whiteboard/protocol/protocol.bib b/src/jabber_whiteboard/protocol/protocol.bib new file mode 100644 index 000000000..181242cc2 --- /dev/null +++ b/src/jabber_whiteboard/protocol/protocol.bib @@ -0,0 +1,38 @@ +@misc{rfc3920, + author="P. Saint-Andre", + title="{Extensible Messaging and Presence Protocol (XMPP): Core}", + series="Request for Comments", + number="3920", + howpublished="RFC 3920 (Proposed Standard)", + publisher="IETF", + organisation="Internet Engineering Task Force", + year=2004, + month=oct, + url="http://www.ietf.org/rfc/rfc3920.txt", +} + +@misc{jep0045, + author="P. Saint-Andre", + title="{Multi-User Chat}", + series="Jabber Enhancement Proposals", + number="0045", + howpublished="JEP 0045 (Standards Track)", + publisher="Jabber Foundation", + organisation="Jabber Software Foundation", + year=2005, + month=sep, + url="http://www.jabber.org/jeps/jep-0045.html", +} + +@misc{rfc2119, + author="S. Bradner", + title="{Key words for use in RFCs to Indicate Requirement Levels}", + series="Request for Comments", + number="2119", + howpublished="RFC 2119 (Best Current Practice)", + publisher="IETF", + organisation="Internet Engineering Task Force", + year=1997, + month=mar, + url="http://www.ietf.org/rfc/rfc2119.txt", +} \ No newline at end of file diff --git a/src/jabber_whiteboard/protocol/protocol.tex b/src/jabber_whiteboard/protocol/protocol.tex new file mode 100644 index 000000000..cdd03d297 --- /dev/null +++ b/src/jabber_whiteboard/protocol/protocol.tex @@ -0,0 +1,227 @@ +\documentclass[11pt]{article} +\usepackage{enumerate,fancyvrb,graphicx} +\usepackage[utf8x]{inputenc} +\usepackage{fullpage} +\linespread{1.25} + +\begin{document} +\title{The Inkboard protocol specification} +\author{David Yip} +\maketitle + +\begin{abstract} +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. +\end{abstract} + +\tableofcontents + +\section{Introduction} +\subsection{Overview} +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. + +\subsection{Terminology} +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}. + +\section{Definitions} +The following definitions are used throughout this document. +\begin{itemize} +\item {\em Inkboard user}: The user of an Inkboard client. +\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}. +\item {\em User-to-user session}: An Inkboard session only occurring between two users. Analogous to traditional text-based instant messaging between two users. +\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. +\end{itemize} + +\subsection{Dramatis Personae} +Throughout this document, references will be made to the following fictional entities: +\begin{center} +\begin{tabular}[t]{|c|c|} +\hline +Entity Name & Role \\ +\hline +Romeo & Inkboard user \\ +\hline +Juliet & Inkboard user \\ +\hline +Chat & Conference room \\ +\hline +\end{tabular} +\end{center} + +\section{A brief overview of the Inkboard architecture} +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. + +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: + +\begin{enumerate} +\item An undo action was requested by the user. +\item A redo action was requested by the user. +\item A set of changes was committed to the undo log. +\end{enumerate} + +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. + +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. + +\section{Inkboard and XMPP} +\subsection{Format of Inkboard messages} +Inkboard messages are encapsulated in XMPP message stanzas, the format of which is described in \cite{rfc3920}. Inkboard data is wrapped in an \texttt{} element which MUST contain the following attributes: +\begin{center} +\begin{tabular}[t]{|c|c|} +\hline +Attribute & Description \\ +\hline +\texttt{protocol} & Version of the Inkboard protocol utilized by the client that sent the message.\\ +& Clients conforming to this specification MUST use version number 2 in this field. \\ +\hline +\texttt{type} & Numeric identifier of a message type. \\ +& See Section \ref{message-types} for a full listing of Inkboard message types. \\ +\hline +\texttt{seq} & Sequence number of the message. This MUST be monotonically increasing. \\ +\hline +\end{tabular} +\end{center} + +Inkboard changes MUST be wrapped inside an \texttt{} element inside the \texttt{} element. The \texttt{} 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. + +The Inkboard XML schema is available at \texttt{http://inkscape.org/inkboard}. + +\subsection{Inkboard message queuing rules} +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}. + +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. + +\subsection{Example Inkboard messages} +\label{example-messages} +\subsubsection{Null message} +\VerbatimInput[tabsize=2]{inkboard-message-examples/null-message.txt} + +\subsubsection{Sending a change} +\VerbatimInput[tabsize=2]{inkboard-message-examples/1-1-change-message.txt} + +\section{Session establishment} +\subsection{User-to-user} +User-to-user sessions MUST be negotiated according to the procedure outlined below. + +\begin{figure} +\label{u2u-session-establishment-figure-accept} +\centering +\includegraphics[width=5in]{eps/session-invite-u2u-01.eps} +\caption{Initiation of an Inkboard session between two users.} +\end{figure} + +\begin{figure} +\label{u2u-session-establishment-figure-reject} +\centering +\includegraphics[width=5in]{eps/session-invite-u2u-02.eps} +\caption{Attempt to initiate an Inkboard session between two users, with the second user rejecting the invitiation.} +\end{figure} + +\begin{enumerate} +\item Romeo invites Juliet to a user-to-user session using his Inkboard client. +\item Romeo's Inkboard client sends a \texttt{CONNECT\_REQUEST\_USER} message to Juliet's Inkboard client. +\item Juliet's Inkboard client notifies Juliet that Romeo has invited her to a user-to-user session. +\begin{enumerate} +\item If Juliet accepts Romeo's invitation: +\begin{enumerate} +\item Juliet's Inkboard client sends a \texttt{CONNECT\_REQUEST\_RESPONSE\_USER} message to Romeo's Inkboard client. +\item Romeo's Inkboard client notifies Romeo that Juliet has accepted his invitation. +\item Romeo's Inkboard client sends a \texttt{CONNECTED\_SIGNAL} message to Juliet's Inkboard client. +\item Romeo's Inkboard client serializes the current contents of Romeo's SVG document. +\item Romeo's Inkboard client sends a \texttt{DOCUMENT\_BEGIN} message to Juliet's Inkboard client. +\item Romeo's Inkboard client sends the serialized document to Juliet's Inkboard client as a series of \texttt{CHANGE} messages. +\item Romeo's Inkboard client sends a \texttt{COMMIT} message to Juliet's Inkboard client. +\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: +\begin{enumerate} +\item Juliet's existing document is cleared. +\item Juliet's Inkboard client prepares to receive and process incoming \texttt{CHANGE} messages. +\end{enumerate} +\item Upon receipt of Romeo's \texttt{COMMIT} message, Juliet's Inkboard client commits all changes sent by Romeo's Inkboard client. +\end{enumerate} +\item If Juliet rejects Romeo's invitation: +\begin{enumerate} +\item Juliet's Inkboard client sends a \texttt{CONNECT\_REQUEST\_REFUSED\_BY\_PEER} message to Romeo's Inkboard client. +\item Romeo's Inkboard client notifies Romeo that Juliet refused his invitation. +\end{enumerate} +\end{enumerate} +\end{enumerate} + +\subsubsection{Example of accepted invitation} + +\subsubsection{Example of rejected invitation} + +\subsection{User-to-conference} +User-to-conference sessions MUST be negotiated according to the procedures outlined below. + +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: + +\begin{enumerate} +\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. +\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. +\end{enumerate} + +Room rosters MUST be processed according to the procedures given in Section 6.3.3 of \cite{jep0045}. + +\begin{figure} +\label{u2c-session-establishment-figure-accept} +\centering +\includegraphics[width=5in]{eps/session-invite-u2c-01.eps} +\caption{Initiation of an Inkboard session between a user and a conference in which Inkboard users are already involved in a conference.} +\end{figure} + +\subsubsection{User establishing a new conference} +\begin{enumerate} +\item +\end{enumerate} + +\subsubsection{User joining an existing conference} +\label{joining-existing-conference} +\begin{enumerate} +\item +\end{enumerate} + +\section{Session establishment error cases} +\subsection{Incompatible protocol versions} + +\subsubsection{User-to-user} + +\subsubsection{User-to-conference} + +\subsection{Duplicate session establishment requests} + +\subsection{Mutual invitation} + +\section{Transmitting changes} +\subsection{User-to-user} + +\subsection{User-to-conference} + +\section{Change conflict resolution} + +\section{Client requirements} +[describe what is required of a client implementing this protocol; this will probably need to delve into the Inkscape document model a little bit] + +\section{Contributors} +[TBW] + +\section{Acknowledgments} +[TBW] + +\section{Security considerations} +[TBW] + +\section{IANA Considerations} +[TBW, although most likely ``None''] + +\appendix +\section{Appendices} + +\subsection{Full listing of message types} +\label{message-types} + +\subsection{Full listing of change types} +\label{change-types} + +\bibliographystyle{alpha} +\bibliography{protocol.bib} + +\end{document} \ No newline at end of file diff --git a/src/jabber_whiteboard/protocol/session-invite-u2c-01.svg b/src/jabber_whiteboard/protocol/session-invite-u2c-01.svg new file mode 100644 index 000000000..c608812d8 --- /dev/null +++ b/src/jabber_whiteboard/protocol/session-invite-u2c-01.svg @@ -0,0 +1,376 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + Romeo + Chat + + CHATROOM_SYNCHRONIZE_REQUEST + Inkboard session invitation (user-to-chatroom): Inkboard users already in chat + + CHATROOM_SYNCHRONIZE_RESPONSE + (from Romeo)(future synchresponsesignored byRomeo) + + DOCUMENT_SENDER_REQUEST + + CHATROOM_SYNCHRONIZE_RESPONSE + + DOCUMENT_BEGIN + Juliet + + + + + (...data...) + Juliet sendscontents of document at the time ofreceipt of Romeo's request. + + + PROBLEM: There is not yet any way to storemultiple revisions of a node in an SVGdocument. This needs to be worked outbefore the circled criteria can actuallybe implemented. + Romeoreceivesacknowledgementfrom Juliet + + CHANGE_COMMIT + Romeo commits changessent by Juliet + + diff --git a/src/jabber_whiteboard/protocol/session-invite-u2u-01.svg b/src/jabber_whiteboard/protocol/session-invite-u2u-01.svg new file mode 100644 index 000000000..fa19a2345 --- /dev/null +++ b/src/jabber_whiteboard/protocol/session-invite-u2u-01.svg @@ -0,0 +1,306 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + Romeo + Juliet + + CONNECT_REQUEST_USER + Inkboard session invitation (user-to-user): recipient Juliet accepts invitation + + CONNECT_REQUEST_RESPONSE_USER + + DOCUMENT_BEGIN + + + (...more CHANGE data...) + + Begin deserialization + Inkboard notifies Juliet of Romeo's invitation. Juliet accepts. + + COMMIT + Juliet commits changessent by Romeo. + + CONNECTED_SIGNAL + Inkboard notifies Romeo that Juliet hasaccepted the invitation. + Inkboard notifies Juliet that Romeo hasacknowledged the invitation acceptance. + CHANGE + CHANGE + + diff --git a/src/jabber_whiteboard/protocol/session-invite-u2u-02.svg b/src/jabber_whiteboard/protocol/session-invite-u2u-02.svg new file mode 100644 index 000000000..84db6d282 --- /dev/null +++ b/src/jabber_whiteboard/protocol/session-invite-u2u-02.svg @@ -0,0 +1,168 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + Romeo + Juliet + + CONNECT_REQUEST_USER + Inkboard session invitation (user-to-user): recipient Juliet rejects invitation + + CONNECT_REQUEST_REFUSED_BY_PEER + Inkboard notifies Romeo of invitation refusal. + Inkboard notifies Juliet of Romeo's invitation; Juliet rejects it. + + diff --git a/src/jabber_whiteboard/protocol/session-invite-u2u-03.svg b/src/jabber_whiteboard/protocol/session-invite-u2u-03.svg new file mode 100644 index 000000000..1161e77c4 --- /dev/null +++ b/src/jabber_whiteboard/protocol/session-invite-u2u-03.svg @@ -0,0 +1,202 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + Romeo + Juliet + + CONNECT_REQUEST_USER + Inkboard session invitation (user-to-user): recipients invite each other + + CONNECT_REQUEST_USER + + CONNECT_REQUEST_REFUSED_BY_PEER + + CONNECT_REQUEST_REFUSED_BY_PEER + Inkboard notifies Romeo of double-invite situation and automatic sending of invitation refusal. + Inkboard notifies Juliet of double-invite situation and automatic sending of invitation refusal. + + diff --git a/src/jabber_whiteboard/protocol/session-invite-u2u-04.svg b/src/jabber_whiteboard/protocol/session-invite-u2u-04.svg new file mode 100644 index 000000000..842b65e20 --- /dev/null +++ b/src/jabber_whiteboard/protocol/session-invite-u2u-04.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + Romeo + + CONNECT_REQUEST_USER + Inkboard session invitation (user-to-user): Romeo and Juliet are already in a session + + Juliet + + ALREADY_IN_SESSION + + diff --git a/src/jabber_whiteboard/protocol/svg2eps.sh b/src/jabber_whiteboard/protocol/svg2eps.sh new file mode 100755 index 000000000..ed5c6287e --- /dev/null +++ b/src/jabber_whiteboard/protocol/svg2eps.sh @@ -0,0 +1,4 @@ +#!/bin/bash +for i in *.svg; do \ + inkscape -E eps/`echo $i | sed -r 's/([a-zA-Z0-9\-]+)\.svg/\1/g;'`.eps $i; \ +done diff --git a/src/jabber_whiteboard/protocol/unsupported-protocol-u2c-01.svg b/src/jabber_whiteboard/protocol/unsupported-protocol-u2c-01.svg new file mode 100644 index 000000000..36ddf78ba --- /dev/null +++ b/src/jabber_whiteboard/protocol/unsupported-protocol-u2c-01.svg @@ -0,0 +1,277 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + Romeo + + CHATROOM_SYNCHRONIZE_REQUEST + Inkboard session: unsupported protocol version error signaling (user-to-chat) + + Chat + + UNSUPPORTED_PROTOCOL_VERSION + (from user Juliet)Message MUSTbe sent withAlice's protocolrevision. + Inkboard notifies Romeo that she is attemptingto connect to a chatroom in which all clientsare using a version of the Inkboard protocolthat is incompatible with Romeo's client. + + UNSUPPORTED_PROTOCOL_VERSION + Other notifications of incorrect protocol versionfrom other chatroom usersare ignored by Romeo. + NOTE: This scheme has at least one big flaw.It allows for the creation of malicious agents that could be targeted to try to block a specific user by sending UNSUPPORTED_PROTOCOL_VERSIONmessages.The ordering of messages is handled by the Jabber MUC server, so such anattack will not always work, but the possibility of it working certainlyexists. A better way would be to encode the required protocol version(s)in the chatroom itself, but I haven't worked that out just yet. + + diff --git a/src/jabber_whiteboard/protocol/unsupported-protocol-u2u-01.svg b/src/jabber_whiteboard/protocol/unsupported-protocol-u2u-01.svg new file mode 100644 index 000000000..5e7c4156c --- /dev/null +++ b/src/jabber_whiteboard/protocol/unsupported-protocol-u2u-01.svg @@ -0,0 +1,174 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + Romeo + + CONNECT_REQUEST_USER + Inkboard session: unsupported protocol version error signaling (user-to-user) + + Juliet + + UNSUPPORTED_PROTOCOL_VERSION + Inkboard notifies Romeo that Juliet is not runninga compatible Inkboard client. + Inkboard does not notify Juliet of Bob'sconnection attempt. + +