Inodes & paths
How LoonFS identifies resources — namespaces, inodes, and paths.
LoonFS identifies specific resources using three concepts: namespaces, inodes, and paths.
Namespaces
Section titled “Namespaces”A namespace is the root-level identity for a collection of files and folders. A “drive” or “collection” are analogous concepts in other cloud drive platforms. Operations within a namespace support a high degree of isolation and consistency; cross-namespace operations are not isolated.
See also Namespaces & forking.
Inodes
Section titled “Inodes”Within a namespace, inodes are the canonical identity for resources. LoonFS currently supports two types of inodes: files and directories. These resource IDs are stable even as files and folders are rearranged within a namespace.
Public inode IDs are opaque strings such as ino_42. The root directory is ino_1.
The HTTP API can stat an inode, list a directory’s children by inode, list a file inode’s revisions, and read or begin a download for a specific inode revision. Inode-addressed reads are safe even as inodes are renamed or moved during lookups.
Binding versions and inode-addressed mutations
Section titled “Binding versions and inode-addressed mutations”Every named entry has an opaque binding_version identifying its current parent/name binding. Creating, moving, or undeleting an entry produces a new version; changing file content or attributes does not. The nameless namespace root omits this field.
Clients can use inode-addressed commit operations when identity matters more than a mutable path:
| Operation | Purpose |
|---|---|
create_directory_by_inode | Create a directory under a parent directory inode. |
create_file_by_inode | Create a file under a parent directory inode. |
put_file_revision_by_inode | Append content to a file inode if its current revision still matches. |
move_by_inode | Move or rename an inode if its binding version still matches. |
delete_by_inode | Delete an inode if its binding version still matches. |
move_by_inode and delete_by_inode require the last-read expected_binding_version. A stale value returns binding_version_mismatch, preventing a request from moving or deleting an inode after another writer has updated the binding. See Transactions.
In LoonFS, paths are mutable “views” that can be used to identify inodes. Paths are useful as resource identifiers, but because they can change (when inodes are moved or renamed), they are not used as the canonical identity for any resource.
Paths can be used for many LoonFS operations as inode aliases, but they are ultimately resolved to the inode currently bound at that location. For some workflows, working with inode IDs directly ensures predictable behavior — especially in busy namespaces or in cases with many writers.