Snapshots

Understanding snapshots

A snapshot is an expiring, read-only view of a namespace. Creating a snapshot reserves the namespace’s current state and returns a snapshot_id; a read that supplies that ID will resolve against the captured state (as long as the lease is live), even as new commits stream in.

Snapshots may be useful for multi-step reads, generating exports, and changefeed consumers that need a fixed view of the namespace.

Lease and lifecycle

Creating a snapshot requires a name and a TTL measured from the server’s current time:

{
  "name": "nightly-export",
  "ttl_ms": 3600000
}

The response includes captured_seq, created_at_ms, and expires_at_ms. (Snapshot names are just labels and do not need to be unique.)

Operation	Endpoint	Behavior
Create snapshot	POST …/snapshots	Captures the namespace’s current state under a new snapshot_id.
List snapshots	GET …/snapshots	Lists live snapshots; deleted and expired snapshots are omitted.
Extend snapshot	POST …/snapshots/{snapshot_id}/extend	Sets a new TTL from the server’s current time without passing the lifetime ceiling.
Delete snapshot	DELETE …/snapshots/{snapshot_id}	Removes the snapshot pin. A second delete returns snapshot_not_found.

An extension can move expires_at_ms later (but never beyond snapshot.max_lifetime_ms from the original created_at_ms).

Reading a snapshot

Pass snapshot_id to supported read operations:

Read	Snapshot behavior
Stat a path	Returns the entry as of the snapshot.
Stat an inode	Returns the inode entry as of the snapshot.
List path entries	Lists the directory state.
List inode children	Lists the directory state by inode ID.
Get file bytes	Reads the file revision as of the snapshot.
Create a download	Grants access to the snapshotted file revision.
List changes	Lists changes through the snapshot’s greatest sequence.

File-content and download requests cannot combine snapshot_id with revision_no (the snapshot already selects the revision as of the reservation). Similarly, for a snapshot-bounded changefeed, after_seq cannot be greater than the captured sequence.

Snapshot reads require a live lease. LoonFS never silently falls back to the current namespace:

Error code	HTTP	Meaning
snapshot_not_found	404	No checkpoint record exists under that ID, including after deletion.
snapshot_gone	410	The snapshot lease expired while its pin still exists.
snapshot_quota_exceeded	409	The namespace already has the maximum number of live snapshots.

Limits

Deployments advertise three snapshot limits through capabilities:

Limit	Meaning
snapshot.max_ttl_ms	Largest TTL accepted by create or extend.
snapshot.max_lifetime_ms	Latest expiry allowed relative to the snapshot’s original creation time.
snapshot.max_live_per_namespace	Maximum live, unexpired snapshots in one namespace.

See the reference server defaults on the Limits page.

Snapshots, checkpoints, and forks

All three use durable checkpoint records underneath, with different contracts:

Mechanism	Owner	Lifetime	Intended use
Snapshot	Application	Required lease, bounded by deployment limits	Stable public reads through snapshot_id.
User checkpoint	Operator	Until explicit deletion or optional expiry	Administrative pins and external maintenance workflows.
Fork checkpoint	Fork lifecycle	While the target namespace depends on its source basis	Internal copy-on-write namespace ancestry.

Snapshots are deleted through the snapshot API. The maintenance checkpoint deletion operation refuses snapshot- and fork-owned records so one API cannot invalidate another operation’s state. If you’re using ACLs, you need admin permissions to manage snapshots, and read and history permissions to read files from them. See Checkpoints and Namespaces & forking.

CLI

loonfs snapshot create demo --name nightly-export --ttl-ms 3600000
loonfs snapshot list demo
loonfs use demo
loonfs snapshot extend demo {snapshot_id} --ttl-ms 3600000

loonfs ls /reports --snapshot-id {snapshot_id}
loonfs get /reports/summary.csv --snapshot-id {snapshot_id}
loonfs changes --snapshot-id {snapshot_id}

loonfs snapshot delete demo {snapshot_id}