All projects

Project case study

Disk-Mesh

Follow a file across a storage cluster

A Java distributed file-system prototype that splits files into checksummed chunks, pipelines replicas, and coordinates repair through heartbeats.

  • Java
  • TCP
  • SHA-256
  • Distributed storage
Try demo GitHub
EvidenceIncludes a four-node recovery scenario that checks restoration to three replicas.

The problem

Copying a file to several machines is only the beginning. A client also needs to locate its chunks, detect damaged bytes, and keep reading when a storage node disappears. Disk-Mesh makes these responsibilities visible through a metadata master, storage nodes, and a client that verifies the data it receives.

How it fits together

  1. 01

    Allocate

    The master assigns chunk IDs and a replica pipeline.

  2. 02

    Replicate

    The client sends each checksummed chunk through the chosen nodes.

  3. 03

    Commit

    Publish file metadata after the write pipeline acknowledges.

  4. 04

    Reconcile

    Heartbeats report replicas and carry commands to make more copies.

File bytes travel directly between clients and storage nodes. Downloads use the master’s locations, try another replica when a read fails, and verify both chunk checksums and the assembled file’s SHA-256 digest.

Interactive demo

Watch replicas recover

Take a node offline, then press Play or Step to follow missed heartbeats, a repair decision, and a copy between storage nodes.

Browser simulation · 4 nodes · target: 3 replicas per chunk

Step 0 · Idle

Metadata master

4 / 4 nodes online

  1. 01Detect
  2. 02Plan
  3. 03Copy

Every chunk meets the replica target

Each chunk has at least three live copies. Take a node offline to explore another failure.

No copy in flight

Take a storage node offline to start a recovery.

  • Node 1

    Online

    Chunk A: live copyChunk B: live copyChunk C: live copy

    3 stored chunks

  • Node 2

    Online

    Chunk A: live copyChunk B: live copyChunk C: no copy

    2 stored chunks

  • Node 3

    Online

    Chunk A: live copyChunk B: no copyChunk C: live copy

    2 stored chunks

  • Node 4

    Online

    Chunk A: no copyChunk B: live copyChunk C: live copy

    2 stored chunks

A, B, and C are chunks of one file. Offline copies stay on disk and become available when the node returns.

Live copies · target: 3 per chunk
ChunkCopiesLive holders
Chunk A3 / 3N1, N2, N3
Chunk B3 / 3N1, N2, N4
Chunk C3 / 3N1, N3, N4

Step 0 · At target

All three chunks have three live copies. Take Node 1 offline to begin.

Recent events
  1. 00All three chunks have three live copies. Take Node 1 offline to begin.

This illustrative model runs in your browser: three equal-size chunks, a two-step heartbeat timeout, and one repair at a time. Each completed copy includes the next replica report. Returning nodes keep extra copies; steps represent event order, with no network or disk I/O.

Decisions & tradeoffs

Keep metadata separate from file bytes

One master owns the namespace and placement decisions while storage nodes handle the data. This keeps bulk transfers off the master, but makes its availability a shared dependency. Periodic snapshots support restart; there is no metadata write-ahead log, so an abrupt failure can lose changes made since the last snapshot.

Chain replicas before acknowledging a chunk

The client sends one copy to the first node, which stores it and forwards it down the chain. Acknowledgements return after downstream writes finish, making the slowest link part of upload latency. Allocation caps the replication factor at the number of live nodes, so a successful upload can have fewer copies than the configured target.

Repair from observed replica reports

Heartbeats include each node’s chunk list. After a timeout removes a node from replica sets, the master asks surviving holders to copy chunks to other nodes, favoring free capacity. Repair needs a healthy source and an available destination; a timeout can also mistake a slow node for a failed one.

Evidence & validation

The repository defines nine integration scenarios, including byte-for-byte round trips, concurrent transfers, corrupt-replica handling, node loss, and garbage collection. These are inspected test definitions; no fresh execution results are claimed here.

The recovery scenario starts four storage nodes with a replication factor of three, stops one node, waits for every chunk to have three live replicas again, and compares a downloaded file with its original bytes. This checks storage-node recovery within an in-process cluster; it does not exercise abrupt master failure.

Chunk data and checksum sidecars are written separately without an explicit disk synchronization call. Replication and checksum validation therefore do not establish power-loss durability. Master-crash and interrupted-write scenarios are useful next checks before making stronger persistence claims.

Run the cluster scenarios

With Java 22 or newer installed, run this command from a repository checkout. The supplied runner starts an in-process master and storage nodes and exercises the nine integration scenarios.

bash scripts/test.sh