[<<<][^^^][>>>]


Synchronization protocol

So-called synchronization protocol (SP) is used in current TCP daemon’s implementation. It is used for synchronizing spool directory contents between two nodes.

It is aimed to be very simple and effective. It uses reliable transport like TCP connections. It must be effective both on single-duplex and full-duplex links: for example satellites have very high throughput but high-delay links, so acknowledging of each received packet, like XMODEM does, causes unacceptable performance degradation.

SP works on top of Noise_IK_25519_ChaChaPoly_BLAKE2b protocol. Each Noise packet is sent inside an XDR envelope:

+-----------------+
| MAGIC | PAYLOAD |
+-----------------+
XDR typeValue
Magic number8-byte, fixed length opaque dataN N C P S 0x00 0x00 0x01
Payloadvariable length opaque dataNoise packet itself

Peers static keys are specified as noisepub configuration entry.

Payload inside Noise packets has maximum size of 64 KiB - 256 B = 65280 B. It is sent immediately in the first message by each side. The very first payload (that is carried inside handshake messages) is always padded to the maximum size with HALT packets (read below), for hiding actual number of INFO packets (number of files available for transmission).

Each SP payload is a concatenation of SP packets. Each packet has XDR-encoded header and then corresponding XDR-encoded body. Header is just an unsigned integer telling what body structure follows.

HALT

Stop file transmission, empty sending queue on the remote side. Actually HALT packet does not have any body, only the header with the type. It is also used in the first payload for padding to the maximum size.

+------+
| HALT |
+------+
INFO

Information about the file we have for transmission.

+------+--------------------+
| INFO | NICE | SIZE | HASH |
+------+--------------------+
XDR typeValue
Nicenessunsigned integer1-255, file niceness level
Sizeunsigned hyper integerFile size
Hash32-byte, fixed length opaque dataUnique file identifier, its checksum
FREQ

File transmission request. Ask remote side to queue the file for transmission.

+------+---------------+
| FREQ | HASH | OFFSET |
+------+---------------+
XDR typeValue
Hash32-byte, fixed length opaque dataUnique file identifier, its checksum
Offsetunsigned hyper integerOffset from which remote side must transmit the file
FILE

Chunk of file.

+------+-------------------------+
| FILE | HASH | OFFSET | PAYLOAD |
+------+-------------------------+
XDR typeValue
Hash32-byte, fixed length opaque dataUnique file identifier, its checksum
Offsetunsigned hyper integerOffset from which transmission goes
Payloadvariable length opaque dataChunk of file itself
DONE

Signal remote side that we have successfully downloaded the file.

+------+------+
| DONE | HASH |
+------+------+
XDR typeValue
Hash32-byte, fixed length opaque dataUnique file identifier, its checksum

Typical peer’s behaviour is following:

     ┌─────────┐                       ┌─────────┐     
     │Initiator│                       │Responder│     
     └────┬────┘                       └────┬────┘     
          │                                 │          
          │         ╔═════════════╗         │          
══════════╪═════════╣ preparation ╠═════════╪══════════
          │         ╚═════════════╝         │          
          │                                 │          
          │              [s]                │          
          │<────────────────────────────────│          
          │                                 │          
          │                                 │          
          │         ╔═════════════╗         │          
══════════╪═════════╣ interactive ╠═════════╪══════════
          │         ╚═════════════╝         │          
          │                                 │          
          │[e, es, s, ss], INFO..., HALT... │          
          │────────────────────────────────>│          
          │                                 │          
          │ [e, ee, se], INFO..., HALT...   │          
          │<────────────────────────────────│          
          │                                 │          
          │   INFO..., FREQ..., DONE...     │          
          │────────────────────────────────>│          
          │                                 │          
          │   INFO..., FREQ..., DONE...     │          
          │<────────────────────────────────│          
          │                                 │          
          │   FILE..., INFO..., DONE...     │          
          │────────────────────────────────>│          
          │                                 │          
          │   FILE..., INFO..., DONE...     │          
          │<────────────────────────────────│          
          │                                 │          
  1. Perform Noise-IK handshake:
    Initiator

    Collects all tx-related files information and prepares payload filled with INFOs for including in the first handshake message.

    Responder

    After receiving the first handshake message, it gains remote identity knowledge and similarly prepares the payload for including in the second handshake message.

    All payloads are padded to maximal message size with HALTs.

  2. If queued INFOs are not sent completely in handshake payloads, then send all of remaining in the transport stage.
  3. When INFO packet received:
  4. When FREQ packet received, insert it to current sending queue with niceness level sort: higher priority packets will be sent first. Sending queue contains files with offsets that are needed to be sent.
  5. While sending queue is not empty, send FILE packets. FREQ could contain offset equal to size – anyway sent FILE packet with an empty payload. FILE sending is performed only if no other outgoing packets are queued: INFOs have higher priority.
  6. When FILE packet received, check if it is completely downloaded (comparing to INFO’s packet size information). If so, then run background integrity checker on it. If check succeeds, then delete .part suffix from file’s name and send DONE packet.
  7. When DONE packet received, delete corresponding file.
  8. When HALT packet received, empty file sending queue.
  9. Each second, node checks: are there any new tx packets appeared and queues corresponding INFO packets.
  10. If no packets are sent and received during onlinedeadline duration, then close the connection. There is no explicit indication that session is over.

[<<<][^^^][>>>]