Commit | Line | Data |
---|---|---|
4ae8ca60 FT |
1 | \documentclass[twoside,a4paper,11pt]{article} |
2 | ||
66e1551f FT |
3 | \usepackage[T1]{fontenc} |
4 | \usepackage[utf8x]{inputenc} | |
f6d0f511 | 5 | \usepackage[ps2pdf]{hyperref} |
66e1551f | 6 | \usepackage{reqlist} |
f7932303 | 7 | \usepackage{longtable} |
66e1551f | 8 | |
75053ec3 | 9 | \newcommand{\urlink}[1]{\texttt{<\url{#1}>}} |
4ae8ca60 FT |
10 | \newcommand{\unix}{\textsc{Unix}} |
11 | ||
12 | \title{Dolda Connect protocol} | |
13 | \author{Fredrik Tolf\\\texttt{<fredrik@dolda2000.com>}} | |
14 | ||
15 | \begin{document} | |
16 | ||
17 | \maketitle | |
18 | ||
47b71ed4 FT |
19 | \tableofcontents |
20 | ||
4ae8ca60 FT |
21 | \section{Introduction} |
22 | Dolda Connect consists partly of a daemon (a.k.a. server) that runs in | |
23 | the background and carries out all the actual work, and a number of | |
24 | client programs (a.k.a. user interfaces) that connect to the daemon in | |
25 | order to tell it what to do. In order for the daemon and the clients | |
26 | to be able to talk to each other, a protocol is needed. This document | |
27 | intends to document that protocol, so that third parties can write | |
28 | their own client programs. | |
29 | ||
30 | It is worthy of note that there exists a library, called | |
03c10091 | 31 | \texttt{libdcui}, that carries out much of the low level work of |
4ae8ca60 FT |
32 | speaking the protocol, facilitating the creation of new client |
33 | programs. In itself, \texttt{libdcui} is written in the C programming | |
34 | language and is intended to be used by other programs written in C, | |
35 | but there also exist wrapper libraries for both GNU Guile (the GNU | |
36 | project's Scheme interpreter) and for Python. The former is | |
37 | distributed with the main Dolda Connect source tree, while the latter | |
38 | is distributed separately (for technical reasons). To get a copy, | |
75053ec3 FT |
39 | please refer to Dolda Connect's homepage: |
40 | ||
41 | \urlink{http://www.dolda2000.com/~fredrik/doldaconnect/} | |
4ae8ca60 FT |
42 | |
43 | \section{Transport format} | |
66e1551f FT |
44 | Note: Everything covered in this section is handled by the |
45 | \texttt{libdcui} library. Thus, if you read this because you just want | |
46 | to write a client, and are using the library (or any of the wrapper | |
47 | libraries), you can safely skip over this section. It may still be | |
48 | interesting to read in order to understand the semantics of the | |
49 | protocol, however. | |
50 | ||
4ae8ca60 FT |
51 | The protocol can be spoken over any channel that features a |
52 | byte-oriented, reliable virtual (or not) circuit. Usually, it is | |
53 | spoken over a TCP connection or a byte-oriented \unix\ socket. The | |
54 | usual port number for TCP connections is 1500, but any port could be | |
55 | used\footnote{However, port 1500 is what the \texttt{libdcui} library | |
56 | uses if no port is explicitly stated, so it is probably to be | |
66e1551f FT |
57 | preferred}. |
58 | ||
59 | \subsection{Informal description} | |
4ae8ca60 FT |
60 | |
61 | On top of the provided byte-oriented connection, the most basic level | |
62 | of the protocol is a stream of Unicode characters, encoded with | |
63 | UTF-8. The Unicode stream is then grouped in two levels: lines | |
64 | consisting of words (a.k.a. tokens). Lines are separated by CRLF | |
65 | sequences (\emph{not} just CR or LF), and words are separated by | |
66 | whitespace. Both whitespace and CRLFs can be quoted, however, | |
67 | overriding their normal interpretation of separators and allowing them | |
68 | to be parts of words. NUL characters are not allowed to be transferred | |
69 | at all, but all other Unicode codepoints are allowed. | |
70 | ||
71 | Lines transmitted from the daemon to the client are slightly | |
72 | different, however. They all start with a three-digit code, followed | |
73 | by either a space or a dash\footnote{Yes, this is inspired by FTP and | |
74 | SMTP.}, followed by the normal sequence of words. The three-digit | |
75 | code identifies that type of line. Overall, the protocol is a | |
76 | lock-step protocol, where the clients sends one line that is | |
77 | interpreted as a request, and the daemon replies with one or more | |
78 | lines. In a multi-line response, all lines except the last have the | |
79 | three-digit code followed by a dash. The last line of a multi-line | |
80 | response and the only line of a single-line response have the | |
81 | three-digit code followed by a space. All lines of a multi-line | |
82 | response have the same three-digit code. The client is not allowed to | |
83 | send another request until the last line of the previous response has | |
66e1551f FT |
84 | been received. The exception is that the daemon might send (but only |
85 | if the client has requested it to do so) sporadic lines of | |
86 | asynchronous notification messages. Notification message lines are | |
87 | distinguished by having their three-digit codes always begin with the | |
88 | digit 6. Otherwise, the first digit of the three-digit code indicates | |
89 | the overall success or failure of a request. Codes beginning with 2 | |
90 | indicate the the request to which they belong succeeded. Codes | |
91 | beginning with 3 indicate that the request succeeded in itself, but | |
92 | that it is considered part of a sequence of commands, and that the | |
93 | sequence still requires additional interaction before considered | |
94 | successful. Codes beginning with 5 are indication of errors. The | |
95 | remaining two digits merely distinguish between different | |
96 | outcomes. Note that notification message lines may come at \emph{any} | |
97 | time, even in the middle of multiline responses (though not in the | |
98 | middle of another line). There are no multiline notifications. | |
99 | ||
100 | The act of connecting to the daemon is itself considered a request, | |
101 | solicitating a success or failure response, so it is the daemon that | |
102 | first transmits actual data. A failure response may be provoked by a | |
103 | client connecting from a prohibited source. | |
104 | ||
105 | Quoting of special characters in words may be done in two ways. First, | |
106 | the backslash character escapes any special interpretation of the | |
107 | character that comes after it, no matter where or what the following | |
108 | character is (it is not required even to be a special | |
109 | character). Thus, the only way to include a backslash in a word is to | |
110 | escape it with another backslash. Second, any interpretation of | |
111 | whitespace may be escaped using the citation mark character (only the | |
112 | ASCII one, U+0022 -- not any other Unicode quotes), by enclosing a | |
113 | string containing whitespace in citation marks. (Note that the citation | |
114 | marks need not necessarily be placed at the word boundaries, so the | |
115 | string ``\texttt{a"b c"d}'' is parsed as a single word ``\texttt{ab | |
116 | cd}''.) Technically, this dual layer of quoting may seem like a | |
117 | liability when implementing the protocol, but it is quite convenient | |
118 | when talking directly to the daemon with a program such as | |
119 | \texttt{telnet}. | |
120 | ||
121 | \subsection{Formal description} | |
122 | ||
123 | Formally, the syntax of the protocol may be defined with the following | |
124 | BNF rules. Note that they all operate on Unicode characters, not bytes. | |
125 | ||
f7932303 | 126 | \begin{longtable}{lcl} |
66e1551f FT |
127 | <session> & ::= & <SYN> <response> \\ |
128 | & & | <session> <transaction> \\ | |
129 | & & | <session> <notification> \\ | |
130 | <transaction> & ::= & <request> <response> \\ | |
131 | <request> & ::= & <line> \\ | |
132 | <response> & ::= & <resp-line-last> \\ | |
133 | & & | <resp-line-not-last> <response> \\ | |
134 | & & | <notification> <response> \\ | |
135 | <resp-line-last> & ::= & <resp-code> <SPACE> <line> \\ | |
136 | <resp-line-not-last> & ::= & <resp-code> <DASH> <line> \\ | |
137 | <notification> & ::= & <notification-code> <SPACE> <line> \\ | |
138 | <resp-code> & ::= & ``\texttt{2}'' <digit> <digit> \\ | |
139 | & & | ``\texttt{3}'' <digit> <digit> \\ | |
140 | & & | ``\texttt{5}'' <digit> <digit> \\ | |
141 | <notification-code> & ::= & ``\texttt{6}'' <digit> <digit> \\ | |
142 | <line> & ::= & <CRLF> \\ | |
143 | & & | <word> <ws> <line> \\ | |
144 | <word> & ::= & <COMMON-CHAR> \\ | |
145 | & & | ``\texttt{$\backslash$}'' <CHAR> \\ | |
146 | & & | ``\texttt{"}'' <quoted-word> ``\texttt{"}'' \\ | |
147 | & & | <word> <word> \\ | |
148 | <quoted-word> & ::= & ``'' \\ | |
149 | & & | <COMMON-CHAR> <quoted-word> \\ | |
150 | & & | <ws> <quoted-word> \\ | |
151 | & & | ``\texttt{$\backslash$}'' <CHAR> <quoted-word> \\ | |
152 | <ws> & ::= & <1ws> | <1ws> <ws> \\ | |
153 | <1ws> & ::= & <SPACE> | <TAB> \\ | |
154 | <digit> & ::= & ``\texttt{0}'' | | |
155 | ``\texttt{1}'' | ``\texttt{2}'' | | |
156 | ``\texttt{3}'' | ``\texttt{4}'' \\ | |
157 | & & | ``\texttt{5}'' | ``\texttt{6}'' | | |
158 | ``\texttt{7}'' | ``\texttt{8}'' | | |
159 | ``\texttt{9}'' | |
f7932303 | 160 | \end{longtable} |
66e1551f FT |
161 | |
162 | As for the terminal symbols, <SPACE> is U+0020, <TAB> is U+0009, | |
163 | <CRLF> is the sequence of U+000D and U+000A, <DASH> is U+002D, <CHAR> | |
164 | is any Unicode character except U+0000, <COMMON-CHAR> is any | |
165 | Unicode character except U+0000, U+0009, U+000A, U+000D, U+0020, | |
166 | U+0022 and U+005C, and <SYN> is the out-of-band message that | |
167 | establishes the communication channel\footnote{This means that the | |
168 | communication channel must support such a message. For example, raw | |
169 | RS-232 would be hard to support.}. The following constraints also | |
170 | apply: | |
171 | \begin{itemize} | |
172 | \item <SYN> and <request> must be sent from the client to the daemon. | |
173 | \item <response> and <notification> must be sent from the daemon to | |
174 | the client. | |
175 | \end{itemize} | |
176 | Note that the definition of <word> means that the only way to | |
177 | represent an empty word is by a pair of citation marks. | |
178 | ||
179 | In each request line, there should be at least one word, but it is not | |
180 | considered a syntax error if there is not. The first word in each | |
181 | request line is considered the name of the command to be carried out | |
182 | by the daemon. An empty line is a valid request as such, but since no | |
183 | matching command, it will provoke the same kind of error response as | |
184 | if a request with any other non-existing command were sent. Any | |
185 | remaining words on the line are considered arguments to the command. | |
186 | ||
187 | \section{Requests} | |
188 | For each arriving request, the daemon checks so that the request | |
189 | passes a number of tests before carrying it out. First, it matches the | |
190 | name of the command against the list of known commands to see if the | |
191 | request calls a valid command. If the command is not valid, the daemon | |
192 | sends a reponse with code 500. Then, it checks so that the request has | |
193 | the minimum required number of parameters for the given command. If it | |
194 | does not, it responds with a 501 code. Last, it checks so that the | |
195 | user account issuing the request has the necessary permissions to have | |
196 | the request carried out. If it does not, it responds with a 502 | |
197 | code. After that, any responses are individual to the command in | |
198 | question. The intention of this section is to list them all. | |
199 | ||
200 | \subsection{Permissions} | |
201 | ||
202 | As for the permissions mentioned above, it is outside the scope of | |
203 | this document to describe the administration of | |
204 | permissions\footnote{Please see the \texttt{doldacond.conf(5)} man | |
205 | page for more information on that topic.}, but some commands require | |
206 | certain permission, they need at least be specified. When a connection | |
207 | is established, it is associated with no permissions. At that point, | |
208 | only requests that do not require any permissions can be successfully | |
209 | issued. Normally, the first thing a client would do is to authenticate | |
210 | to the daemon. At the end of a successful authentication, the daemon | |
211 | associates the proper permissions with the connection over which | |
212 | authentication took place. The possible permissions are listed in | |
213 | table \ref{tab:perm}. | |
214 | ||
215 | \begin{table} | |
216 | \begin{tabular}{rl} | |
217 | Name & General description \\ | |
218 | \hline | |
219 | \texttt{admin} & Required for all commands that administer the | |
220 | daemon. \\ | |
221 | \texttt{fnetctl} & Required for all commands that alter the state of | |
222 | connected hubs. \\ | |
223 | \texttt{trans} & Required for all commands that alter the state of | |
224 | file transfers. \\ | |
225 | \texttt{transcu} & Required specifically for cancelling uploads. \\ | |
226 | \texttt{chat} & Required for exchanging chat messages. \\ | |
227 | \texttt{srch} & Required for issuing and querying searches. \\ | |
228 | \end{tabular} | |
229 | \caption{The list of available permissions} | |
230 | \label{tab:perm} | |
231 | \end{table} | |
232 | ||
233 | \subsection{Protocol revisions} | |
03ee2e4a | 234 | \label{rev} |
66e1551f FT |
235 | Since Dolda Connect is developing, its command set may change |
236 | occasionally. Sometimes new commands are added, sometimes commands | |
237 | change argument syntax, and sometimes commands are removed. In order | |
238 | for clients to be able to cleanly cope with such changes, the protocol | |
239 | is revisioned. When a client connects to the daemon, the daemon | |
240 | indicates in the first response it sends the range of protocol | |
241 | revisions it supports, and each command listed below specifies the | |
242 | revision number from which its current specification is valid. A | |
243 | client should should check the revision range from the daemon so that | |
244 | it includes the revision that incorporates all commands that it wishes | |
245 | to use. | |
246 | ||
247 | Whenever the protocol changes at all, it is given a new revision | |
248 | number. If the entire protocol is backwards compatible with the | |
249 | previous version, the revision range sent by the server is updated to | |
250 | extend forward to the new revision. If the protocol in any way is not | |
251 | compatible with the previous revision, the revision range is moved | |
252 | entirely to the new revision. Therefore, a client can check for a | |
253 | certain revision and be sure that everything it wants is supported by | |
254 | the daemon. | |
255 | ||
03ee2e4a FT |
256 | At the time of this writing, the latest protocol revision is 2. Please |
257 | see the file \texttt{doc/protorev} that comes with the Dolda Connect | |
258 | source tree for a full list of revisions and what changed between | |
259 | them. | |
260 | ||
66e1551f FT |
261 | \subsection{List of commands} |
262 | ||
263 | Follows does a (hopefully) exhaustive listing of all commands valid | |
264 | for a request. For each possible request, it includes the name of the | |
03ee2e4a | 265 | command for the request, the permissions required, the syntax for the |
66e1551f FT |
266 | entire request line, and the possible responses. |
267 | ||
268 | The syntax of the request and response lines is described in a format | |
269 | like that traditional of \unix\ man pages, with a number of terms, | |
270 | each corresponding to a word in the line. Each term in the syntax | |
271 | description is either a literal string, written in lower case; an | |
272 | argument, written in uppercase and meant to be replaced by some other | |
273 | text as described; an optional term, enclosed in brackets | |
274 | (``\texttt{[}'' and ``\texttt{]}''); or a list of alternatives, | |
275 | enclosed in braces (``\texttt{\{}'' and ``\texttt{\}}'') and separated | |
276 | by pipes (``\texttt{|}''). Possible repetition of a term is indicated | |
277 | by three dots (``\texttt{...}''), and, for the purpose of repition, | |
278 | terms may be groups with parentheses (``\texttt{(}'' and | |
279 | ``\texttt{)}''). | |
280 | ||
281 | Two things should be noted regarding the responses. First, in the | |
282 | syntax description of responses, the response code is given as the | |
283 | first term, even though it is not actually considered a word. Second, | |
284 | more words may follow after the specified syntax, and should be | |
285 | discarded by a client. Many responses use that to include a human | |
286 | readable string to indicate the conclusion of the request. | |
287 | ||
288 | \subsubsection{Connection} | |
289 | As mentioned above, the act of connecting to the daemon is itself | |
290 | considered a request, soliciting a response. Such a request obviously | |
291 | has no command name and no syntax, but needs a description | |
292 | nonetheless. | |
293 | ||
03ee2e4a FT |
294 | \revision{1} |
295 | ||
66e1551f FT |
296 | \noperm |
297 | ||
298 | \begin{responses} | |
299 | \response{200} | |
300 | The old response given by daemons not yet using the revisioned | |
301 | protocol. Clients receiving this response should consider it an | |
302 | error. | |
03ee2e4a FT |
303 | \response{201 LOREV HIREV} |
304 | Indicates that the connection is accepted. The \param{LOREV} and | |
305 | \param{HIREV} parameters specify the range of supported protocol | |
306 | revisions, as described in section \ref{rev}. | |
307 | \response{502 REASON} | |
308 | The connection is refused by the daemon and will be closed. The | |
309 | \param{REASON} parameter states the reason for the refusal in | |
310 | English\footnote{So it is probably not suitable for localized | |
311 | programs}. | |
66e1551f | 312 | \end{responses} |
4ae8ca60 | 313 | |
f6d0f511 FT |
314 | \input{commands} |
315 | ||
4ae8ca60 | 316 | \end{document} |