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