Module protocol

remote

Module protocol 

Source
Expand description

Remote copy protocol definitions for source-destination communication.

§Protocol Overview

The remote copy protocol uses TCP for communication between source and destination. The source listens on two ports: a control port for bidirectional messages and a data port for file transfers. Both sides exchange messages to coordinate directory creation, file transfers, and completion.

See docs/remote_protocol.md for the full protocol specification.

§Message Flow

Source                              Destination
  |                                      |
  |  ---- Directory(root, meta) -------> |  Create root, store metadata
  |  ---- Directory(child, meta) ------> |  Create child, store metadata
  |  ---- Symlink(...) ----------------> |  Create symlink
  |  ---- DirStructureComplete --------> |  Structure complete
  |                                      |
  |  <--- DirectoryCreated(root) ------- |
  |  <--- DirectoryCreated(child) ------ |
  |                                      |
  |  ~~~~ File(f, total=N) ~~~~~~~~~~~~> |  Write file, track count
  |  ~~~~ File(...) ~~~~~~~~~~~~~~~~~~-> |  ...
  |                                      |  All files done → apply metadata
  |                                      |
  |  <--- DestinationDone -------------- |  Close send side
  |  (close send side)                   |  (detect EOF)
  |  (detect EOF)                        |  Close connection

§Error Communication

The protocol uses asymmetric error communication:

  • Source → Destination: Must communicate failures (FileSkipped, SymlinkSkipped) so destination can track file counts correctly
  • Destination → Source: Does NOT communicate failures. Destination handles errors locally and source continues sending the full structure.

§Shutdown Sequence

Shutdown is coordinated through TCP connection closure:

  1. Destination sends DestinationDone and closes its send side
  2. Source detects EOF on recv, closes its send side
  3. Destination detects EOF on recv, closes connection

Structs§

File
File header sent on unidirectional streams, followed by raw file data.
FileMetadata
Wrapper that includes size for comparison purposes.
Metadata
RcpdConfig
RuntimeStats
runtime statistics collected from a process (CPU time, memory usage)
SourceMasterHello
SrcDst
TracingHello

Enums§

DestinationMessage
Messages sent from destination to source on the control stream.
MasterHello
RcpdResult
RcpdRole
SourceMessage
Messages sent from source to destination on the control stream.

Type Aliases§

CertFingerprint
TLS certificate fingerprint (SHA-256 of DER-encoded certificate).