Garage: Orientation

Garage is a geo-distributed object store with an S3-compatible API. It splits small, mergeable metadata from large, immutable content-addressed blocks, then replicates both according to the cluster layout.

S3 request
    ↓
object/version metadata ── CRDT table ── quorum replicas
    ↓ block references
content-addressed blocks ── streamed RPC ── storage replicas
                                      ↓
                         background sync, repair, and GC

Design thesis

Garage makes distributed failure manageable by giving metadata and bytes different representations, making metadata mergeable and blocks immutable, and treating repair as a permanent background responsibility.

This case study focuses on one large PutObject, then follows the same data through quorum replication, failure cleanup, and repair. Garage also supports multipart uploads, K2V, websites, administration, several metadata databases, and many S3 endpoints; those are important product features, but not the architectural center we are rebuilding.

What to know first

• An async task can wait without occupying an OS thread.
• A bounded channel limits queued values and propagates backpressure.
• A content hash can name immutable bytes.
• A quorum means an operation succeeds after enough replicas respond.
• A CRDT defines how concurrent replicas merge without a single primary.

You do not need to know distributed-systems theory in advance. The chapters introduce each term where Garage makes it concrete.