doc/protocol/protocol.tex

   1 \documentclass[twoside,a4paper,11pt]{article}
   2
   3 \newcommand{\url}[1]{\texttt{<#1>}}
   4 \newcommand{\unix}{\textsc{Unix}}
   5
   6 \title{Dolda Connect protocol}
   7 \author{Fredrik Tolf\\\texttt{<fredrik@dolda2000.com>}}
   8
   9 \begin{document}
  10
  11 \maketitle
  12
  13 \section{Introduction}
  14 Dolda Connect consists partly of a daemon (a.k.a. server) that runs in
  15 the background and carries out all the actual work, and a number of
  16 client programs (a.k.a. user interfaces) that connect to the daemon in
  17 order to tell it what to do. In order for the daemon and the clients
  18 to be able to talk to each other, a protocol is needed. This document
  19 intends to document that protocol, so that third parties can write
  20 their own client programs.
  21
  22 It is worthy of note that there exists a library, called
  23 \texttt{libdcui} that carries out much of the low level work of
  24 speaking the protocol, facilitating the creation of new client
  25 programs. In itself, \texttt{libdcui} is written in the C programming
  26 language and is intended to be used by other programs written in C,
  27 but there also exist wrapper libraries for both GNU Guile (the GNU
  28 project's Scheme interpreter) and for Python. The former is
  29 distributed with the main Dolda Connect source tree, while the latter
  30 is distributed separately (for technical reasons). To get a copy,
  31 please refer to Dolda Connect's homepage at
  32 \url{http://www.dolda2000.com}.
  33
  34 \section{Transport format}
  35 The protocol can be spoken over any channel that features a
  36 byte-oriented, reliable virtual (or not) circuit. Usually, it is
  37 spoken over a TCP connection or a byte-oriented \unix\ socket. The
  38 usual port number for TCP connections is 1500, but any port could be
  39 used\footnote{However, port 1500 is what the \texttt{libdcui} library
  40   uses if no port is explicitly stated, so it is probably to be
  41   preferred}. What follows hereon is an informal description of the
  42 protocol.
  43
  44 On top of the provided byte-oriented connection, the most basic level
  45 of the protocol is a stream of Unicode characters, encoded with
  46 UTF-8. The Unicode stream is then grouped in two levels: lines
  47 consisting of words (a.k.a. tokens). Lines are separated by CRLF
  48 sequences (\emph{not} just CR or LF), and words are separated by
  49 whitespace. Both whitespace and CRLFs can be quoted, however,
  50 overriding their normal interpretation of separators and allowing them
  51 to be parts of words. NUL characters are not allowed to be transferred
  52 at all, but all other Unicode codepoints are allowed.
  53
  54 Lines transmitted from the daemon to the client are slightly
  55 different, however. They all start with a three-digit code, followed
  56 by either a space or a dash\footnote{Yes, this is inspired by FTP and
  57   SMTP.}, followed by the normal sequence of words. The three-digit
  58 code identifies that type of line. Overall, the protocol is a
  59 lock-step protocol, where the clients sends one line that is
  60 interpreted as a request, and the daemon replies with one or more
  61 lines. In a multi-line response, all lines except the last have the
  62 three-digit code followed by a dash. The last line of a multi-line
  63 response and the only line of a single-line response have the
  64 three-digit code followed by a space. All lines of a multi-line
  65 response have the same three-digit code. The client is not allowed to
  66 send another request until the last line of the previous response has
  67 been received.
  68
  69 \end{document}