Limits
Limits are deployment-specific. LoonFS deployments should tune their limits based on their unique constraints. The reference server is built around a safe set of limits that serve as a reasonable lower bound, but can be increased and tuned as needed.
Complying servers should publish the values they enforce as a response to GET /v0/capabilities. Clients should use that response instead of assuming any universal defaults.
Transfers
Section titled “Transfers”| Capability limit | Default | Meaning |
|---|---|---|
upload.max_content_bytes | 256 MiB | Largest service-proxied upload body. |
download.max_content_bytes | 256 MiB | Largest file returned through a service-proxied content read. |
upload.max_concurrent | 8 | Proxied uploads the server accepts concurrently. |
download.max_concurrent | 16 | Proxied content reads the server accepts concurrently. |
These byte limits are specific to service-proxied uploads and downloads (when content passes through the LoonFS server). They are not maximum file sizes. A deployment may support larger files using direct uploads, multipart uploads, and direct download grants.
Commits
Section titled “Commits”| Capability limit | Default | Meaning |
|---|---|---|
commit.max_operations | 4,096 | Filesystem operations in one commit. |
commit.max_content_tokens | 4,096 | Content-preparation tokens carried by one commit. |
commit.max_external_content_refs | 4,096 | Distinct external content references named by one commit. |
commit.max_message_bytes | 4,096 bytes | UTF-8 byte length of the optional commit message. |
Pagination and search
Section titled “Pagination and search”| Capability limit | Default | Meaning |
|---|---|---|
pagination.default_limit | 1,000 | Items returned when a standard paged request omits limit. |
pagination.max_limit | 1,000 | Largest accepted standard page size. |
query.grep.default_limit | 100 | Matches returned when a grep request omits limit. |
query.grep.max_limit | 1,000 | Largest accepted grep page size. |
query.grep.scan_budget_files | 4,096 | Files a plan-less allow_scan query may scan. |
query.grep.tail_budget_files | 512 | Unindexed revisions a query may scan before reporting index lag. |
The query.grep.* limits are advertised only when the deployment serves the optional grep query capability.
Maintenance
Section titled “Maintenance”| Capability limit | Default | Meaning |
|---|---|---|
maintenance.gc.min_grace_window_ms | 1,230,000 ms | Smallest accepted garbage-collection grace window: 20 minutes, 30 seconds. |
Paths and namespace size
Section titled “Paths and namespace size”These protocol-wide path constraints apply across all deployments. These constraints are enforced for interoperability reasons, not for performance.
| Path constraint | Maximum | Meaning |
|---|---|---|
| Display-name length | 255 UTF-8 bytes | Largest stored name for one path component. |
| Canonical absolute-path length | 4,096 UTF-8 bytes | Largest complete canonical path. |
| Path depth | 128 components | Deepest nesting an absolute path may express. |
LoonFS does not currently impose a fixed inode-count ceiling, and all releases are tested for scale through millions of inodes per namespace.
Commit-throughput is a function of commit.max_operations and the CAS rate limit on the object store provider (e.g., GCS has a rate limit of 1 CAS per second).