Capabilities

Understanding deployment-specific capabilities — protocol versions, API groups, optional features, and limits.

Understanding capabilities

Different LoonFS deployment may support different features. In order for clients to adapt to different servers, every deployment should produce a capability document to advertise supported functionality.

A remote client can fetch it from get capabilities, and embedded engines should expose the same document just as a constant.

Contents of the capability document

The top-level categories of advertised “capabilities” are:

Field	Meaning
`protocol_version`	The protocol generation, currently `v0`
`api_groups`	All-or-nothing API groups, such as the filesystem or optional queries.
`features`	Specific optional behavior within the set, such as `query.grep`.
`limits`	Deployment limits that clients may optionally use to pre-validate requests.

API groups are all-or-nothing

Today, there are three API groups:

API group	Group	Role
`filesystem/v0`	`filesystem`	The mandatory filesystem operations.
`maintenance/v0`	`maintenance`	Optional. Maintenance operations.
`query/v0`	`query`	Optional. Derived-index queries, such as grep.

API groups advertise which complete families of operations the deployment supports; features indicate which optional parts of those families are available. (Maintenance endpoints are not included in this public API reference.)

Filesystem feature keys

Feature	Meaning
`filesystem.namespaces.create`	Create namespaces.
`filesystem.namespaces.fork`	Fork namespaces.
`filesystem.namespaces.delete`	Permanently delete and retire namespaces.
`filesystem.snapshots`	Create, list, extend, delete, and read from leased snapshots.
`filesystem.commits.inline_content`	Send small file contents directly in a commit, up to `commit.max_inline_content_bytes_per_operation` decoded bytes per file.
`filesystem.uploads.direct_put`	Upload an object through one presigned request.
`filesystem.uploads.direct_multipart`	Upload an object through presigned multipart requests.
`filesystem.downloads.direct_get`	Download an object through a presigned request.

Attributes and listing a directory by inode ID are no longer optional features. Every deployment that serves filesystem/v0 supports them.

A sample capability document

{
  "protocol_version": "v0",
  "api_groups": ["filesystem/v0", "query/v0"],
  "features": {
    "filesystem.namespaces.create": true,
    "filesystem.namespaces.fork": true,
    "filesystem.namespaces.delete": true,
    "filesystem.snapshots": true,
    "filesystem.commits.inline_content": true,
    "filesystem.uploads.direct_put": true,
    "filesystem.uploads.direct_multipart": true,
    "filesystem.downloads.direct_get": true,
    "query.grep": true
  },
  "limits": {
    "upload.service_proxied.max_content_bytes": 268435456,
    "upload.direct_put.max_content_bytes": 5368709120,
    "upload.complete.max_request_body_bytes": 8388608,
    "download.service_proxied.max_content_bytes": 268435456,
    "upload.service_proxied.max_concurrent_requests": 8,
    "download.service_proxied.max_concurrent_requests": 16,
    "snapshot.max_ttl_ms": 86400000,
    "snapshot.max_lifetime_ms": 604800000,
    "snapshot.max_live_per_namespace": 16,
    "commit.max_operations": 4096,
    "commit.max_preconditions": 1024,
    "commit.max_inline_content_bytes_per_operation": 65536,
    "commit.max_content_tokens": 4096,
    "commit.max_external_content_refs": 4096,
    "commit.max_message_bytes": 4096,
    "access.max_principals_per_request": 64,
    "maintenance.gc.min_grace_window_ms": 1335000,
    "pagination.default_limit": 1000,
    "pagination.max_limit": 1000,
    "query.grep.default_limit": 1000,
    "query.grep.max_limit": 1000,
    "query.grep.scan_budget_files": 4096,
    "query.grep.tail_budget_files": 512
  }
}

How to interpret this example: “This deployment serves the filesystem and grep, but not maintenance — maintenance/v0 is absent, so no maintenance operations are supported.”