Crate loonfs_api 

Wire types and durable-format codecs for LoonFS.

Everything that crosses a process or storage boundary is defined here: validated identifier and path types at the crate root, the versioned HTTP protocol shapes in v0, and the durable storage formats in wire (WAL segments, metadata SSTs, namespace manifests, and control objects). Other LoonFS crates depend on this one for vocabulary; it depends on none of them.

One module here is deliberately not a boundary format: options holds the per-operation argument structs that the embedded runtime and the HTTP client both expose. They parameterize the same semantic operations on both surfaces, so this crate — the shared vocabulary — owns the single definition rather than each surface keeping its own copy to drift.

The commit_identity module contains shared logic rather than wire types. It computes durable mutation fingerprints and verifies retried PUT requests against existing commit receipts. Keeping this logic here ensures that the embedded runtime and HTTP client apply the same identity and content checks.

Module rule: v0 HTTP shapes live in v0; the crate root keeps the ids/paths/errors/wire-format modules and re-exports the common v0 surface as a curated explicit list below.

Re-exports

pub use v0::AdvanceRetentionResponse;

pub use v0::ApiError;

pub use v0::AttributesProjection;

pub use v0::AuthoritativeFileBytes;

pub use v0::AuthoritativePathEntry;

pub use v0::AuthoritativePathEntryKind;

pub use v0::Checkpoint;

pub use v0::CheckpointOwnerSummary;

pub use v0::CommitRequest;

pub use v0::CommitResponse;

pub use v0::CreateCheckpointRequest;

pub use v0::CreateCheckpointResponse;

pub use v0::CreateNamespaceRequest;

pub use v0::DeleteDirectoryBehavior;

pub use v0::DeleteNamespaceResponse;

pub use v0::DestinationBehavior;

pub use v0::ErrorDetails;

pub use v0::FileRevision;

pub use v0::FilesystemOperation;

pub use v0::FlushWalOutcome;

pub use v0::FlushWalResponse;

pub use v0::ForkNamespaceRequest;

pub use v0::GcRequest;

pub use v0::GcResponse;

pub use v0::GrepMatch;

pub use v0::GrepRequest;

pub use v0::GrepResponse;

pub use v0::ListCheckpointsResponse;

pub use v0::ListFileRevisionsResponse;

pub use v0::ListPathEntriesResponse;

pub use v0::ListTrashResponse;

pub use v0::MaintenanceStepRequest;

pub use v0::MaintenanceStepResponse;

pub use v0::MetadataMaintenanceRequest;

pub use v0::MetadataMaintenanceResponse;

pub use v0::NamespaceStatusResponse;

pub use v0::ReleaseCheckpointResponse;

pub use v0::ReorganizeStepOutcome;

pub use v0::RetainedCandidates;

pub use v0::RetainedReason;

pub use v0::TrashEntry;

pub use v0::WalFlushStepOutcome;

Modules

env

Environment variables used by more than one LoonFS process.

options

Per-operation option shapes shared by the runtime and client surfaces.

public_inode_id

Converts inode IDs between internal numbers and public API strings.

v0

The v0 HTTP protocol shapes.

wire

Durable wire formats grouped by their owning format family.

Structs

AbsolutePath

Canonical absolute path plus its parsed components.

ActorId

A validated actor identifier supplied by the application.

ActorIdValidationError

An error returned when an actor ID is invalid.

ActorRef

Identifies the user, service, or system responsible for a commit.

AttributeKey

Validated name of one inode attribute.

AttributeKeyValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

AttributeRevisionNo

Revision number for an inode’s attributes.

AttributeValue

One validated attribute value.

AttributeValueValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

Attributes

A validated attribute map for one inode.

CapabilityDocument

A deployment’s self-description (API spec, “Capability discovery”).

ChangeSeq

Sequence number assigned to a namespace commit.

CheckpointId

Durable checkpoint identifier.

Checksum

An algorithm and its canonical lowercase-hex checksum value.

CommitId

Client-supplied idempotency key for one logical commit.

CommitIdValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

ContentId

Durable identity of one immutable content object.

ContentRef

Pointer to one immutable content object.

ContentStoreId

Durable id for an immutable content store.

Crc32c

Incremental CRC-32C (Castagnoli) checksum.

Crc64Nvme

CRC-64/NVME over a payload delivered in pieces.

DirectoryPageCursor

Cursor for one directory listing position.

DisplayName

User-facing spelling of one path component.

EffectiveLimit

A validated page size selected from a caller request and a policy.

FileRevisionsPageCursor

Cursor for one file revision listing position.

GeneratedIdValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

GrepManifestId

Identifies one stored grep manifest.

GrepPageCursor

Cursor for one content-search (grep) snapshot.

IndexSegmentId

Durable id for one derived-index segment file.

InodeId

Numeric identity of a file or directory within a namespace.

ManifestId

Version number for a namespace manifest.

ManifestObjectId

Durable object id for one namespace manifest candidate.

MetadataCompactionId

Durable id for one streaming metadata compaction job.

MetadataTableId

Durable id for one metadata SST table file.

NameKey

Name-policy-derived directory entry key.

NameKeyValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

NamespaceId

Durable id for one namespace.

NamespaceIdValidationError

Describes why supplied text does not satisfy this identifier’s validation contract.

Page

Typed result envelope for internal runtime/core page methods.

PageRequest

Typed request envelope for internal runtime/core page methods.

PaginationPolicy

Fixed pagination contract for endpoints with potentially unbounded results.

PathComponent

One path segment as stored, preserving display spelling.

PublicOrdinalRangeError

Returned when an ordinal exceeds MAX_PUBLIC_INTEGER.

PutRetryAttempt

Details of the retried PUT being compared with an existing receipt.

PutRetryReceipt

Receipt data needed to verify a PUT that reused a commit ID.

RevisionNo

Revision number for a file’s content.

SecretString

A secret string such as an access key, token, or signing secret.

SemanticFingerprintError

Error returned when the canonical fingerprint input cannot be encoded.

Sha256

SHA-256 over a payload delivered in pieces.

TrashPageCursor

Cursor for one trash listing position.

UploadId

Durable id for one upload session.

WalSegmentId

Durable id for one WAL segment.

WriterEpoch

Counter used to reject writes from an older writer.

Enums

ActorKind

The type of actor responsible for a commit.

AttributesError

Describes which attribute-map limit an input broke.

CapabilityDocumentError

Violation of the capability document rules.

ChecksumAlgorithm

Supported checksum algorithms.

ChecksumValidationError

Describes why a checksum is not in its canonical wire form.

ContentEvidence

Available proof that a payload matches a committed content reference.

ContentRefKind

Kind of content reference.

ContentRefValidationError

Describes why a content reference cannot be part of a durable commit.

ErrorCode

Stable machine-readable error reason.

ErrorKind

Broad error category for caller or operator action.

InodeKind

Filesystem item kind.

LimitError

Invalid caller-supplied page size.

NamespaceCursorError

Why a namespace-bound cursor cannot resume the enumeration replaying it.

PageCursorError

Invalid opaque page cursor.

PathError

Describes why caller-supplied path or display-name text is not admissible.

PutRetryErrorClassification

Classification of an error encountered while verifying a retried PUT.

StreamingChecksum

Incremental checksum for streamed reads and writes.

Constants

DEFAULT_MAX_PAGE_LIMIT

Contract maximum accepted page size.

DEFAULT_PAGE_LIMIT

Contract page size for endpoints that omit a caller-supplied limit.

FEATURE_ADMIN_GREP_INDEX

Gates grep-index administration: enabling a namespace’s grep root, disabling it, collecting its garbage, and reading its lifecycle.

FEATURE_ATTRIBUTES

Gates inode attributes: writing them, and projecting them onto reads. Attributes are part of the core plane, not a composed extension, so a deployment that serves the core profile serves them.

FEATURE_DOWNLOADS_DIRECT_GET

Gates download grants that are authorized with short-lived presigned URLs. A deployment that offers any direct transfer advertises this one, because letting a client write an object too large to proxy back means being able to hand it back.

FEATURE_NAMESPACES_CREATE

Gates namespace creation.

FEATURE_NAMESPACES_DELETE

Gates namespace deletion.

FEATURE_NAMESPACES_FORK

Gates namespace forking.

FEATURE_QUERY_GREP

Gates grep-index content search: the serving half of the capability; the namespace’s verified active grep root is the data half.

FEATURE_UPLOADS_DIRECT_MULTIPART

Starting presigned direct_multipart upload sessions. Independent of FEATURE_UPLOADS_DIRECT_PUT: a provider may sign whole-object writes without having an S3-style multipart API at all.

FEATURE_UPLOADS_DIRECT_PUT

Gates direct upload sessions that are authorized with short-lived presigned URLs.

FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_CRC32C

direct_put with a CRC-32C whole-object checksum.

FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_CRC64NVME

direct_put with a CRC-64/NVME whole-object checksum.

FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_SHA256

direct_put with a SHA-256 whole-object checksum.

FIRST_ALLOCATABLE_INODE_ID

First inode id available after the root inode.

LIMIT_COMMIT_MAX_CONTENT_TOKENS

Advisory limit: the most content tokens one commit may carry.

LIMIT_COMMIT_MAX_EXTERNAL_CONTENT_REFS

Advisory limit: the most distinct external content refs one commit’s operations may name.

LIMIT_COMMIT_MAX_MESSAGE_BYTES

Advisory limit: the largest accepted commit message, in bytes.

LIMIT_COMMIT_MAX_OPERATIONS

Advisory limit: the most path operations one commit may carry; a longer list answers invalid_request before planning.

LIMIT_DOWNLOAD_MAX_CONCURRENT

Advisory limit: how many service-proxied content reads the deployment materializes at once; requests past the cap answer server_busy.

LIMIT_DOWNLOAD_MAX_CONTENT_BYTES

Advisory limit: the largest file content a service-proxied read will buffer and return in one response.

LIMIT_GC_MIN_GRACE_WINDOW_MS

Advisory limit: the smallest accepted grace_window_ms on a gc request; smaller values answer invalid_request. Derived from the publication budgets, not tuned.

LIMIT_PAGINATION_DEFAULT

Advisory capability key for the default page size applied when callers omit limit.

LIMIT_PAGINATION_MAX

Advisory capability key for the largest page size accepted by a deployment.

LIMIT_QUERY_GREP_DEFAULT

Advisory limit: matches per grep page when the request omits limit.

LIMIT_QUERY_GREP_MAX

Advisory limit: the largest accepted grep page limit. Distinct from the pagination keys — a grep item costs a verified file read, not a row.

LIMIT_QUERY_GREP_SCAN_BUDGET_FILES

Advisory limit: files a plan-less allow_scan grep will scan before refusing with query_unindexable.

LIMIT_QUERY_GREP_TAIL_BUDGET_FILES

Advisory limit: unindexed-tail revisions one grep scans exhaustively before failing with index_lagging.

LIMIT_UPLOAD_COMPLETION_MAX_BODY_BYTES

Advisory limit: the largest JSON body accepted when completing an upload. It is large enough for the maximum number of multipart entries.

LIMIT_UPLOAD_DIRECT_PUT_MAX_CONTENT_BYTES

Advisory limit: the largest object this deployment’s provider accepts in one presigned direct_put request.

LIMIT_UPLOAD_MAX_CONCURRENT

Advisory limit: how many service-proxied upload bodies the deployment buffers at once; requests past the cap answer server_busy.

LIMIT_UPLOAD_MAX_CONTENT_BYTES

Advisory limit: the largest request body accepted for service-proxied upload content requests. This is the proxy’s cap, not the provider’s.

MAX_ATTRIBUTES_TOTAL_BYTES

Maximum total size of one attribute map in logical UTF-8 bytes. The total counts every key’s bytes plus every value’s bytes. It excludes encoder framing, so the limit does not move when the map is written as JSON instead of CBOR.

MAX_ATTRIBUTE_ENTRIES

Maximum number of entries in one attribute map.

MAX_ATTRIBUTE_KEY_BYTES

Maximum attribute key length in UTF-8 bytes.

MAX_ATTRIBUTE_VALUE_BYTES

Maximum length of one attribute value in UTF-8 bytes.

MAX_DISPLAY_NAME_BYTES

Maximum stored display-name length in UTF-8 bytes: the 255-byte component cap of mainstream filesystems (ext4, APFS, NTFS components) and drives. Names are stored as given, so the cap applies to the bytes as given.

MAX_ID_BYTES

Maximum validated namespace and commit id length in UTF-8 bytes.

MAX_NAME_KEY_BYTES

Maximum name-key length in UTF-8 bytes. Keys are derived from display names capped at crate::path::MAX_DISPLAY_NAME_BYTES; case folding expands at most threefold in bytes, so 768 admits every key derivable from a valid name while bounding row keys, filter keys, and cursors.

MAX_PATH_BYTES

Largest canonical absolute path, in UTF-8 bytes. Bounded so every real filesystem, archive format, and sync client can materialize any stored tree; per-component limits alone allowed paths no target could hold.

MAX_PATH_DEPTH

Deepest directory nesting one path may express.

MAX_PUBLIC_INTEGER

Maximum value for an ordinal exposed through the API.

PAGE_CURSOR_VERSION

Wire cursor format version.

PROFILE_ADMIN_V0

The optional maintenance plane.

PROFILE_CORE_V0

The mandatory data plane.

PROFILE_QUERY_V0

The optional derived-index query plane.

PROTOCOL_VERSION

The protocol generation this build speaks.

RESERVED_ATTRIBUTE_KEY_PREFIX

Key prefix reserved for system-owned attributes.

ROOT_INODE_ID

Inode 1 is always the root directory of a namespace.

UPLOADS_DIRECT_PUT_CHECKSUM_FEATURES

Every direct_put checksum feature, paired with the algorithm it names.

Traits

NamespaceCursor

A cursor that resumes an enumeration of one namespace’s own keyspace.

PageCursor

One paginated endpoint’s cursor.

Functions

decode_cursor

Decodes a cursor issued by encode_cursor for the same endpoint.

decode_namespace_cursor

Decodes a cursor issued for expected_namespace_id’s own keyspace.

direct_put_checksum_feature

The feature key that names one direct_put checksum algorithm, or the parent FEATURE_UPLOADS_DIRECT_PUT key when no dedicated one is registered for it.

encode_cursor

Encodes a cursor as the opaque string clients round-trip.

generated_id

Generates a project-standard opaque durable identifier.

manifest_object_id_manifest_id

Logical manifest id encoded in a manifest object id’s 20-digit prefix.

name_key_for_display_name

Derives the canonical lookup key for a display name.

next_public_ordinal

Returns the next ordinal, or None if the value is already at the limit.

put_retry_fingerprint

Computes the fingerprint for a retried single-file PUT using the content reference from the original commit.

reconcile_put_commit_id_reuse

Checks whether a PUT rejected for commit-ID reuse is an exact retry of an earlier successful PUT.

semantic_commit_fingerprint

Computes the semantic fingerprint used to validate a reused commit ID.

sha256_digest

Computes the durable sha256: digest spelling used by envelope payloads and local compare tokens.

wal_segment_id_start_seq

Start seq encoded in a WAL segment id’s 20-digit position prefix.