Namespaces & forking

Understanding a namespace

A namespace is the identity of a collection of files and folders; think of it as the analogue of a “drive” or “collection” in other systems. It is also the isolation boundary of the system: operations in a given namespace are isolated and consistent, cross-namespace operations are not.

See also Inodes & paths.

Naming a namespace

A namespace ID is supplied by the caller at creation time. While it is perfectly acceptable to choose human readable namespace names, most applications create namespaces programmatically with generated IDs.

Namespace ID rules:

Rule	Detail
Length	1–128 bytes
First character	A lowercase ASCII letter or a digit
Remaining characters	Lowercase ASCII letters, digits, ., _, or -
Not allowed	Leading or trailing whitespace; the exact values . and ..
Reserved	The loonfs- prefix

Supported namespace operations

Operation	Endpoint
Create namespace	POST /v0/namespaces
Get namespace	GET /v0/namespaces/{namespace_id}
Fork namespace	POST /v0/namespaces/{namespace_id}/forks
Delete namespace	DELETE /v0/namespaces/{namespace_id}

In the CLI, use namespace create, namespace fork, namespace delete or use/current to select the active namespace.

Remember to include the required Loonfs-Actor header when creating or forking a namespace. The response records the actor ID as created_by. Namespaces default to unrestricted access. To enable ACLs, supply kind: "acl", principal_scope, and root_grants in access. You cannot change the access mode later.

Listing namespaces

For now, LoonFS intentionally does not expose a list-namespaces operation. instead, applications should keep their own catalog of namespace IDs.

Forking a namespace

Namespaces can be forked into new namespaces using a copy-on-write strategy. The operation is close to instant and very cost effecient.

The fork shares the source’s existing files instead of copying them. When forking the source’s current state, LoonFS may first flush the source’s recent writes, so that fork can take a little longer.

Forking a namespace creates a “checkpoint” (durable pin) in the source namespace and will affect garbage collection.

Supply snapshot_id to fork a live snapshot’s captured state; otherwise the fork uses the source’s current head.

See Understanding checkpoints for more information on these durable pins.