1@node Sync 2@unnumbered Synchronization protocol 3 4So-called synchronization protocol (SP) is used in current TCP daemon's 5implementation. It is used for synchronizing @ref{Spool, spool} 6directory contents between two nodes. 7 8It is aimed to be very simple and effective. It uses reliable transport 9like TCP connections. It must be effective both on single-duplex and 10full-duplex links: for example satellites have very high throughput but 11high-delay links, so acknowledging of each received packet, like 12@url{https://en.wikipedia.org/wiki/XMODEM, XMODEM} does, causes 13unacceptable performance degradation. 14 15SP works on top of 16@url{http://noiseprotocol.org/noise.html#interactive-patterns, 17@code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet 18is sent inside an @url{https://tools.ietf.org/html/rfc4506, 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 @verb{|N N C P S 0x00 0x00 0x01|} 31@item Payload @tab 32 variable length opaque data @tab 33 Noise packet itself 34@end multitable 35 36Peers static keys are specified as @ref{Configuration, @emph{noisepub}} 37configuration entry. 38 39Payload inside Noise packets has maximum size of @emph{64 KiB - 256 B = 4065280 B}. It is sent immediately in the first message by each side. The 41very first payload (that is carried inside handshake messages) is always 42padded to the maximum size with @emph{HALT} packets (read below), for 43hiding actual number of @emph{INFO} packets (number of files available 44for transmission). 45 46Each SP payload is a concatenation of SP packets. Each packet has 47XDR-encoded header and then corresponding XDR-encoded body. Header is 48just an unsigned integer telling what body structure follows. 49 50@table @emph 51 52@item HALT 53 Stop file transmission, empty sending queue on the remote side. 54 Actually @emph{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@verbatim 59+------+ 60| HALT | 61+------+ 62@end verbatim 63 64@item PING 65 Dummy packet only used for determining workability of the connection. 66 67@verbatim 68+------+ 69| PING | 70+------+ 71@end verbatim 72 73@item INFO 74 Information about the file we have for transmission. 75 76@verbatim 77+------+--------------------+ 78| INFO | NICE | SIZE | HASH | 79+------+--------------------+ 80@end verbatim 81 82 @multitable @columnfractions 0.2 0.3 0.5 83 @headitem @tab XDR type @tab Value 84 @item Niceness @tab 85 unsigned integer @tab 86 1-255, file niceness level 87 @item Size @tab 88 unsigned hyper integer @tab 89 File size 90 @item Hash @tab 91 32-byte, fixed length opaque data @tab 92 Unique file identifier, its checksum 93 @end multitable 94 95@item FREQ 96 File transmission request. Ask remote side to queue the file for 97 transmission. 98 99@verbatim 100+------+---------------+ 101| FREQ | HASH | OFFSET | 102+------+---------------+ 103@end verbatim 104 105 @multitable @columnfractions 0.2 0.3 0.5 106 @headitem @tab XDR type @tab Value 107 @item Hash @tab 108 32-byte, fixed length opaque data @tab 109 Unique file identifier, its checksum 110 @item Offset @tab 111 unsigned hyper integer @tab 112 Offset from which remote side must transmit the file 113 @end multitable 114 115@item FILE 116 Chunk of file. 117 118@verbatim 119+------+-------------------------+ 120| FILE | HASH | OFFSET | PAYLOAD | 121+------+-------------------------+ 122@end verbatim 123 124 @multitable @columnfractions 0.2 0.3 0.5 125 @headitem @tab XDR type @tab Value 126 @item Hash @tab 127 32-byte, fixed length opaque data @tab 128 Unique file identifier, its checksum 129 @item Offset @tab 130 unsigned hyper integer @tab 131 Offset from which transmission goes 132 @item Payload @tab 133 variable length opaque data @tab 134 Chunk of file itself 135 @end multitable 136 137@item DONE 138 Signal remote side that we have successfully downloaded the file. 139 140@verbatim 141+------+------+ 142| DONE | HASH | 143+------+------+ 144@end verbatim 145 146 @multitable @columnfractions 0.2 0.3 0.5 147 @headitem @tab XDR type @tab Value 148 @item Hash @tab 149 32-byte, fixed length opaque data @tab 150 Unique file identifier, its checksum 151 @end multitable 152 153@end table 154 155Typical peer's behaviour is following: 156 157@verbatiminclude sp.plantuml.txt 158 159@enumerate 160@item Perform @emph{Noise-IK} handshake: 161 162 @table @strong 163 @item Initiator 164 Collects all @emph{tx}-related files information and prepares 165 payload filled with @emph{INFO}s for including in the @strong{first} 166 handshake message. 167 @item Responder 168 After receiving the first handshake message, it gains remote 169 identity knowledge and similarly prepares the payload for including 170 in the @strong{second} handshake message. 171 @end table 172 173 All payloads are padded to maximal message size with @emph{HALT}s. 174 175@item If queued @emph{INFO}s are not sent completely in handshake 176payloads, then send all of remaining in the transport stage. 177 178@item When @emph{INFO} packet received: 179 180 @itemize 181 @item Check that it has an acceptable niceness level. 182 Ignore it if it is too nice. 183 @item If already downloaded file exists, then queue @emph{DONE} 184 sending. 185 @item If @file{seen/XXX} exists, then queue @emph{DONE} sending. 186 @item If @file{.part} exists, then queue @emph{FREQ} sending with 187 corresponding offset. 188 @end itemize 189 190@item When @emph{FREQ} packet received, insert it to current sending 191queue with niceness level sort: higher priority packets will be sent 192first. Sending queue contains files with offsets that are needed to be 193sent. 194 195@item While sending queue is not empty, send @emph{FILE} packets. 196@emph{FREQ} could contain offset equal to size -- anyway sent 197@emph{FILE} packet with an empty payload. @emph{FILE} sending is 198performed only if no other outgoing packets are queued: @emph{INFO}s 199have higher priority. 200 201@item When @emph{FILE} packet received, check if it is completely 202downloaded (comparing to @emph{INFO}'s packet size information). If so, 203then run background integrity checker on it. If check succeeds, then 204delete @file{.part} suffix from file's name and send @emph{DONE} packet. 205 206@item When @emph{DONE} packet received, delete corresponding file. 207 208@item When @emph{HALT} packet received, empty file sending queue. 209 210@item Each second, node checks: are there any new @emph{tx} packets 211appeared and queues corresponding @emph{INFO} packets. 212 213@item Each minute, if no packets were sent, node sends @emph{PING} 214packet. 215 216@item If no non-PING packets are sent and received during 217@ref{CfgOnlineDeadline, onlinedeadline} duration, then close the 218connection. There is no explicit indication that session is over. 219 220@item If no packets are received during two minutes (two PING timeouts), 221then close the connection. 222 223@end enumerate 224