doc/sp.texi

   1 @node Sync
   2 @unnumbered Synchronization protocol
   3
   4 So-called synchronization protocol (SP) is used in current TCP daemon's
   5 implementation. It is used for synchronizing @ref{Spool, spool}
   6 directory contents between two nodes.
   7
   8 It is aimed to be very simple and effective. It uses reliable transport
   9 like TCP connections. It must be effective both on single-duplex and
  10 full-duplex links: for example satellites have very high throughput but
  11 high-delay links, so acknowledging of each received packet, like
  12 @url{https://en.wikipedia.org/wiki/XMODEM, XMODEM} does, causes
  13 unacceptable performance degradation.
  14
  15 SP works on top of
  16 @url{http://noiseprotocol.org/noise.html#interactive-patterns,
  17 @code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet
  18 are sent inside XDR envelope:
  19
  20 @verbatim
  21 +-----------------+
  22 | MAGIC | PAYLOAD |
  23 +-----------------+
  24 @end verbatim
  25
  26 @multitable @columnfractions 0.2 0.3 0.5
  27 @headitem  @tab XDR type @tab Value
  28 @item Magic number @tab
  29     8-byte, fixed length opaque data @tab
  30     @code{NNCPS0x10x00x00}
  31 @item Payload @tab
  32     variable length opaque data @tab
  33     Noise packet itself
  34 @end multitable
  35
  36 Peers static keys are specified as @ref{Configuration, @code{noisepub}}
  37 configuration entry.
  38
  39 Payload inside Noise packets has maximum size of @code{65 KiB - 256 B =
  40 65280 B}. It is sent immediately in the first message by each side. The
  41 very first payload (that is carried inside handshake messages) is always
  42 padded to the maximum size with @code{HALT} packets (read below), for
  43 hiding actual number of @code{INFO} packets (number of files available
  44 for transmission).
  45
  46 Each SP payload is a concatenation of SP packets. Each packet has
  47 XDR-encoded header and then corresponding XDR-encoded body. Header is
  48 just an unsigned integer telling what body structure follows.
  49
  50 @table @code
  51
  52 @item HALT
  53     Stop file transmission, empty sending queue on the remote side.
  54     Actually @code{HALT} packet does not have any body, only the header
  55     with the type. It is also used in the first payload for padding to
  56     the maximum size.
  57
  58 @item INFO
  59     Information about the file we have for transmission.
  60 @verbatim
  61 +--------------------+
  62 | NICE | SIZE | HASH |
  63 +--------------------+
  64 @end verbatim
  65     @multitable @columnfractions 0.2 0.3 0.5
  66     @headitem  @tab XDR type @tab Value
  67     @item Niceness @tab
  68         unsigned integer @tab
  69         1-255, file niceness level
  70     @item Size @tab
  71         unsigned hyper integer @tab
  72         File size
  73     @item Hash @tab
  74         32-byte, fixed length opaque data @tab
  75         Unique file identifier, its checksum
  76     @end multitable
  77
  78 @item FREQ
  79     File transmission request. Ask remote side to queue the file for
  80     transmission.
  81 @verbatim
  82 +---------------+
  83 | HASH | OFFSET |
  84 +---------------+
  85 @end verbatim
  86     @multitable @columnfractions 0.2 0.3 0.5
  87     @headitem  @tab XDR type @tab Value
  88     @item Hash @tab
  89         32-byte, fixed length opaque data @tab
  90         Unique file identifier, its checksum
  91     @item Offset @tab
  92         unsigned hyper integer @tab
  93         Offset from which remote side must transmit the file
  94     @end multitable
  95
  96 @item FILE
  97     Chunk of file.
  98 @verbatim
  99 +-------------------------+
 100 | HASH | OFFSET | PAYLOAD |
 101 +-------------------------+
 102 @end verbatim
 103     @multitable @columnfractions 0.2 0.3 0.5
 104     @headitem  @tab XDR type @tab Value
 105     @item Hash @tab
 106         32-byte, fixed length opaque data @tab
 107         Unique file identifier, its checksum
 108     @item Offset @tab
 109         unsigned hyper integer @tab
 110         Offset from which transmission goes
 111     @item Payload @tab
 112         variable length opaque data @tab
 113         Chunk of file itself
 114     @end multitable
 115
 116 @item DONE
 117     Signal remote side that we have successfully downloaded the file.
 118 @verbatim
 119 +------+
 120 | HASH |
 121 +------+
 122 @end verbatim
 123     @multitable @columnfractions 0.2 0.3 0.5
 124     @headitem  @tab XDR type @tab Value
 125     @item Hash @tab
 126         32-byte, fixed length opaque data @tab
 127         Unique file identifier, its checksum
 128     @end multitable
 129
 130 @end table