Skip to main content
Be Bitwise
C++C++ Systems Programming

Capstone: Build a File Synchronizer

Time to build something with moving parts: a file synchroniser that watches a directory, hashes files to spot real changes, and ships them across a TCP socket to a remote target. Every system you've met in this module — filesystem, networking, hashing, threads — earns a slot.

Architecture

Three components do all the work:

  1. File watcher — spots adds, modifications, and deletions in the watched tree.
  2. Hash engine — fingerprints contents so we don't re-send unchanged bytes.
  3. Sync protocol — frames changed files and pushes them across TCP.

File Hashing

Detecting real changes needs a fast hash. We'll use size and mtime as a cheap first-pass sieve and only hash the contents, byte by byte with a simple mixing function, when those change. It's fine for spotting edits, but it isn't collision-resistant; a real tool would use something like xxHash or SHA-256.

cpp
#include <filesystem>
#include <fstream>
#include <string>
#include <cstdint>
#include <functional>
namespace fs = std::filesystem;
struct FileFingerprint {
std::string path;
size_t hash;
uintmax_t size;
fs::file_time_type modified;
};
size_t hash_file_contents(const fs::path& path) {
std::ifstream file(path, std::ios::binary);
if (!file) return 0;
size_t hash = 0;
char buffer[8192];
while (file.read(buffer, sizeof(buffer)) || file.gcount() > 0) {
for (std::streamsize i = 0; i < file.gcount(); i++) {
hash ^= std::hash<char>{}(buffer[i]) +
0x9e3779b9 + (hash << 6) + (hash >> 2);
}
}
return hash;
}

Directory Scanner

cpp
#include <map>
#include <vector>
struct ScanResult {
std::vector<std::string> added;
std::vector<std::string> modified;
std::vector<std::string> removed;
};
class DirectoryScanner {
fs::path root_;
std::map<std::string, FileFingerprint> known_files_;
public:
explicit DirectoryScanner(const fs::path& root) : root_(root) {}
ScanResult scan() {
ScanResult result;
std::map<std::string, FileFingerprint> current_files;
for (const auto& entry : fs::recursive_directory_iterator(root_)) {
if (!entry.is_regular_file()) continue;
auto rel = fs::relative(entry.path(), root_).string();
FileFingerprint fp;
fp.path = rel;
fp.size = entry.file_size();
fp.modified = entry.last_write_time();
auto it = known_files_.find(rel);
if (it == known_files_.end()) {
fp.hash = hash_file_contents(entry.path());
result.added.push_back(rel);
} else if (it->second.size != fp.size ||
it->second.modified != fp.modified) {
// Compare against the hash stored at the previous scan. Hashing
// the file on disk again would hash the new contents twice.
fp.hash = hash_file_contents(entry.path());
if (fp.hash != it->second.hash) {
result.modified.push_back(rel);
}
} else {
fp.hash = it->second.hash; // Unchanged: carry the old hash forward
}
current_files[rel] = fp;
}
for (const auto& [path, _] : known_files_) {
if (current_files.find(path) == current_files.end()) {
result.removed.push_back(path);
}
}
known_files_ = std::move(current_files);
return result;
}
};

Sync Protocol

A skinny protocol gets us moving files over the wire:

cpp
#include <cstdint>
#include <cstring>
#include <string>
#include <vector>
enum class MessageType : uint8_t {
FileData = 1, // Sending file contents
FileDelete = 2, // File was deleted
SyncComplete = 3 // All changes sent
};
struct MessageHeader {
MessageType type;
uint32_t path_length;
uint64_t data_length;
} __attribute__((packed));
// Serialize a file transfer message
std::vector<char> make_file_message(const std::string& path,
const std::vector<char>& data) {
MessageHeader header;
header.type = MessageType::FileData;
header.path_length = path.size();
header.data_length = data.size();
std::vector<char> msg(sizeof(header) + path.size() + data.size());
std::memcpy(msg.data(), &header, sizeof(header));
std::memcpy(msg.data() + sizeof(header), path.data(), path.size());
std::memcpy(msg.data() + sizeof(header) + path.size(),
data.data(), data.size());
return msg;
}

Two things about that header will bite once the receiver runs on another machine. A packed struct copied with memcpy goes out in the sender's byte order, and the receiver has to decide what to do with a path it didn't choose: ../../home/me/.bashrc is a perfectly valid string. This version writes each field big-endian by hand, adds a version byte, and gives the receiver a path check. Predict which of the six paths get written before you run it.

Try itAdd paths of your own to the list, then change a byte in the header (the version, or a length) before calling receive() and check the frame gets rejected.
C++ (GCC 9.2.0)

TCP Sender

cpp
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <unistd.h>
#include <fstream>
#include <iterator>
class SyncSender {
int sock_ = -1;
public:
bool connect(const std::string& host, int port) {
sock_ = socket(AF_INET, SOCK_STREAM, 0);
if (sock_ < 0) return false;
struct sockaddr_in addr{};
addr.sin_family = AF_INET;
addr.sin_port = htons(port);
inet_pton(AF_INET, host.c_str(), &addr.sin_addr);
return ::connect(sock_, (struct sockaddr*)&addr, sizeof(addr)) == 0;
}
bool send_file(const fs::path& root, const std::string& rel_path) {
auto full_path = root / rel_path;
std::ifstream file(full_path, std::ios::binary);
if (!file) return false;
std::vector<char> data((std::istreambuf_iterator<char>(file)),
std::istreambuf_iterator<char>());
auto msg = make_file_message(rel_path, data);
return send_all(msg.data(), msg.size());
}
bool send_delete(const std::string& rel_path) {
MessageHeader header;
header.type = MessageType::FileDelete;
header.path_length = rel_path.size();
header.data_length = 0;
std::vector<char> msg(sizeof(header) + rel_path.size());
std::memcpy(msg.data(), &header, sizeof(header));
std::memcpy(msg.data() + sizeof(header),
rel_path.data(), rel_path.size());
return send_all(msg.data(), msg.size());
}
~SyncSender() {
if (sock_ >= 0) close(sock_);
}
private:
bool send_all(const char* data, size_t len) {
size_t sent = 0;
while (sent < len) {
ssize_t n = ::send(sock_, data + sent, len - sent, 0);
if (n <= 0) return false;
sent += n;
}
return true;
}
};

send_file reads the whole file into a vector before framing it. That keeps the code short, but a multi-gigabyte file means a multi-gigabyte allocation. Once it works, send the header with the known size and then stream the body in fixed-size chunks.

Main Sync Loop

cpp
#include <chrono>
#include <iostream>
#include <thread>
int main(int argc, char* argv[]) {
if (argc < 4) {
std::cerr << "Usage: sync <directory> <host> <port>\n";
return 1;
}
fs::path watch_dir = argv[1];
std::string host = argv[2];
int port = std::stoi(argv[3]);
DirectoryScanner scanner(watch_dir);
SyncSender sender;
if (!sender.connect(host, port)) {
std::cerr << "Failed to connect to " << host << ":" << port << "\n";
return 1;
}
std::cout << "Watching " << watch_dir << ", syncing to "
<< host << ":" << port << "\n";
// Initial full sync
auto initial = scanner.scan();
for (const auto& path : initial.added) {
std::cout << "Syncing: " << path << "\n";
sender.send_file(watch_dir, path);
}
// Watch loop
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(2));
auto changes = scanner.scan();
for (const auto& path : changes.added) {
std::cout << "+ " << path << "\n";
sender.send_file(watch_dir, path);
}
for (const auto& path : changes.modified) {
std::cout << "~ " << path << "\n";
sender.send_file(watch_dir, path);
}
for (const auto& path : changes.removed) {
std::cout << "- " << path << "\n";
sender.send_delete(path);
}
}
return 0;
}

Extensions

Once the bones work, push it:

  • Delta transfers — ship only the changed chunks, the way rsync does.
  • Compression — zlib or lz4 before the bytes hit the socket.
  • Bidirectional sync — handle conflicting edits from both sides without losing work.
  • Encryption — wrap the TCP socket in TLS.
  • Resumable transfers — checkpoint progress so a dropped connection isn't a full restart.

This capstone pulls together everything from the module: directory monitoring, TCP, binary framing, and the discipline of moving bytes efficiently.