Module protocol 

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
  |                                      |
  |  <--- DirectoryManifestChunk(root,..)|  0+ manifest chunks for reused dirs
  |                                      |  under --overwrite/--ignore-existing,
  |                                      |  sent BEFORE the trigger (FIFO)
  |  <--- DirectoryCreated(root) -------- |  Pass-2 trigger
  |  <--- DirectoryCreated(child) ------- |
  |                                      |
  |  ~~~~ File(f) ~~~~~~~~~~~~~~~~~~~~~> |  Write file (not in manifest / differs)
  |  ---- FileUnchanged(g) -----------> |  identical g not transferred
  |                                      |  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. FileUnchanged is also sent Source → Destination but is an optimization notification (not a failure): it signals the source skipped a file whose destination copy is already identical, and is counted as files_unchanged on the destination.
• 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

ExistingEntry

One pre-existing destination directory entry, sent in a DirectoryManifestChunk so the source can skip transferring identical files. name is the child name (serialized as a PathBuf, matching the rest of the protocol’s path handling). metadata/size are only meaningful when is_file.

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.

Constants

DEFAULT_OVERWRITE_MANIFEST_MAX_ENTRIES

Default cap on the number of pre-existing destination entries the destination will put in a directory’s overwrite/ignore-existing manifest. Above this, the manifest is omitted and that directory falls back to transferring-and-draining files (see docs/remote_protocol.md). High by default — rcp typically runs on large hosts; the cap is a backstop, not a normal limit.

MANIFEST_CHUNK_BYTE_BUDGET

Conservative byte budget for a single DirectoryManifestChunk. Well under the control stream’s 8 MiB LengthDelimitedCodec frame limit, leaving ample margin for the message envelope and the worst-case final entry (a single ~PATH_MAX name).

Functions

chunk_manifest

Split a directory manifest into chunks each estimated to stay within byte_budget, so every DirectoryManifestChunk frame fits under the control stream’s frame limit. A single entry larger than the budget still gets its own chunk (it cannot be split further); with the 4 MiB budget versus a worst-case ~4 KiB path, a chunk never approaches the 8 MiB frame limit. chunk_manifest(v, b).concat() == v for any v (no entries lost or reordered).

Type Aliases

CertFingerprint

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