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.

One module is a function rather than a shape: commit_identity computes the durable fingerprint of a mutation. It lives here for the same reason the operation language does — the engine that stamps a fingerprint on a commit receipt and the client that recomputes one to prove a retry is the same request must produce identical values, so there is one implementation and no second reading of the rules.

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::AuthoritativeFileBytes;

pub use v0::AuthoritativePathEntry;

pub use v0::CheckpointOwnerSummary;

pub use v0::CheckpointSummary;

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::MaintenanceStepKind;

pub use v0::MaintenanceStepRequest;

pub use v0::MaintenanceStepResponse;

pub use v0::NamespaceStatusResponse;

pub use v0::NamespaceSummary;

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

options

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

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.

CapabilityDocument

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

ChangeSeq

Monotonically increasing namespace commit sequence number.

CheckpointId

Durable checkpoint identifier.

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.

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.

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

Monotonically increasing namespace manifest identity.

ManifestObjectId

Durable object id for one namespace manifest candidate.

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

Deployment or namespace policy for paginated endpoints.

PathComponent

One path segment as stored, preserving display spelling.

RevisionNo

Monotonically increasing file revision counter within one file inode.

SemanticFingerprintError

A canonical preimage that could not be encoded.

Sha256

SHA-256 over a payload delivered in pieces.

StorageChecksum

A checksum computed over the complete bytes of one content object.

TrashPageCursor

Cursor for one trash listing position.

UploadId

Durable id for one upload session.

WalSegmentId

Durable id for one WAL segment.

WriterEpoch

Monotonically increasing writer epoch for namespace write fencing.

Enums

CapabilityDocumentError

Violation of the capability document rules.

ChecksumAlgorithm

Algorithm of a stored full-object checksum.

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.

PaginationPolicyError

Invalid pagination policy configuration.

PathError

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

StreamingChecksum

One full-object checksum folded over a payload delivered in pieces.

Constants

DEFAULT_MAX_PAGE_LIMIT

Default maximum accepted page size.

DEFAULT_PAGE_LIMIT

Default page size for endpoints that can return unbounded result sets.

FEATURE_DOWNLOADS_DIRECT_GET

Gates download grants that are authorized with short-lived presigned URLs. It rests on the same proof the two upload keys do, and is advertised with them, because a deployment that lets a client write an object it is too large to proxy back has to be 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 steady-state grep root is the data half.

FEATURE_UPLOADS_DIRECT_MULTIPART

Starting presigned direct_multipart upload sessions.

FEATURE_UPLOADS_DIRECT_PUT

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

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_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.

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.

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.

ROOT_INODE_ID

Inode 1 is always the root directory of a namespace.

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.

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.

put_retry_fingerprint

The fingerprint the original request must have had, if this retry is the same single put with only the content id renamed.

semantic_commit_fingerprint

The semantic identity of one mutation request: what a reused commit id is compared against.

sha256_digest

Computes the durable sha256: digest spelling used by content and envelope references.

wal_segment_id_start_seq

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