Write-ahead log
The write-ahead log (WAL) is the ordered record of accepted commits submitted by clients. Commits are grouped into WAL segments to work around certain object-storage rate limits.
┌──────────────────────────────────────────────────────────────────────┐ │ Write-ahead log (WAL) │ │ logical commits, ordered by seq │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ seq 417 │ │ seq 418 │ │ seq 419 │ │ seq 420 │ │ seq 421 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘
Commits
Section titled “Commits”Commits are the unit of atomic client requests, and bundle three things: commit_id (the client’s idempotency key, reused on retries), an optional set of preconditions, and an ordered list of ops (operations).
┌──────────────────────────────────────────────────────────────────────┐
│ Write-ahead log (WAL) │
│ logical commits, ordered by seq │
│ │
│ ┌──────────┐ ┌──────────┐ ┏━━━━━━━━━━┓ ┌──────────┐ ┌──────────┐ │
│ │ seq 417 │ │ seq 418 │ ┃ seq 419 ┃ │ seq 420 │ │ seq 421 │ │
│ └──────────┘ └──────────┘ ┗━━━━━━━━━━┛ └──────────┘ └──────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Commit · seq 419 │
│ one request · one commit_id · one seq │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Preconditions │ │
│ │ child_name_absent · ancestors_not_subtree_deleted │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ ╔════════════════════════════════════════════════════════════════╗ │
│ ║ Operation 0: create_file ║ │
│ ║ compiled from put('/docs/report.txt') ║ │
│ ║ ║ │
│ ║ ┌──────────────────────────────────────────────────────────┐ ║ │
│ ║ │ delta 0 · create_inode │ ║ │
│ ║ │ allocate file inode 42 │ ║ │
│ ║ └──────────────────────────────────────────────────────────┘ ║ │
│ ║ ║ │
│ ║ ┌──────────────────────────────────────────────────────────┐ ║ │
│ ║ │ delta 1 · bind_direntry │ ║ │
│ ║ │ bind 'report.txt' → inode 42 in parent │ ║ │
│ ║ └──────────────────────────────────────────────────────────┘ ║ │
│ ║ ║ │
│ ║ ┌──────────────────────────────────────────────────────────┐ ║ │
│ ║ │ delta 2 · append_file_revision │ ║ │
│ ║ │ revision 1 → content_ref (sha256) │ ║ │
│ ║ └──────────────────────────────────────────────────────────┘ ║ │
│ ║ ║ │
│ ╚════════════════════════════════════════════════════════════════╝ │
│ │
└──────────────────────────────────────────────────────────────────────┘
Operations
Section titled “Operations”Operations are the unit of semantic mutations a client may want to make to the filesystem. LoonFS supports most common filesystem operations: create_file, replace_file, rename, delete_subtree, and so on.
LoonFS also supports specific preconditions depending on the intended operation, to provide greater support for transactional operations within a namespace. For example, a client may specify one or more preconditions on a put(file) operation, including child_name_absent (commit only if the target name is still available) or inode_revision_is (replace the file only if it is still at the revision the client last saw). The server validates these against authoritative namespace state immediately before committing, and rejects the request outright if any check fails — so concurrent writes race explicitly rather than silently overwriting one another.
To understand how content and metadata are stored, see Storage model.
Deltas
Section titled “Deltas”At the lowest level, all operations are compiled into a sequence of deltas.
For example, a put(file) results in a single logical commit whose deltas depend on whether the target path already exists. Creating a new file compiles into three ordered deltas — create_inode (allocate the file’s inode), bind_direntry (bind the filename to that inode under its parent directory), and append_file_revision (record revision 1, pointing at the staged content) — whereas overwriting an existing file compiles into a single append_file_revision delta recording the next revision. The commit is assigned one sequence number when its WAL segment is durably written, and the change becomes visible only once the namespace head advances to reference that segment.