Storage model

How LoonFS is architected on object storage, with caching for acceleration and a split between embedded and server modes.

Understanding the LoonFS durable storage model

LoonFS uses object storage as its only required durable dependency, with a 2-layer cache (memory and SSD) for acceleration.

In embedded mode, LoonFS coordinates transactions directly with the object store, and compaction and indexing must be explicitly triggered. In server mode, the LoonFS server is designed to serialize many client writers into a single batched commit stream and run background compaction and indexing.

Metadata and content

LoonFS is natively built on top of object storage, which is used to store both file content and metadata. The layout in object storage (not to be confused with the filesystem layout in a LoonFS namespace) looks like:

namespaces/{namespace_id}/
├── hint.json                    # starts manifest and WAL discovery
├── manifests/{manifest_no:020}.json
├── wal/{wal_no:020}.wal.zst
├── segments/{segment_id}.sst.zst
├── pins/{pin_id}.json
├── uploads/{upload_id}.json
├── content/{content_id}         # file bytes, one object per revision
└── extensions/
  └── grep/                     # optional

File content is stored under the namespace that first wrote it. A fork keeps reading its parent’s content objects in place, even after the parent namespace is deleted.

Small files can be stored inline in the WAL, then written to content objects during maintenance.