Crate loonfs_api 

Wire types and durable-format codecs for LoonFS.

The crate defines validated identifiers and paths, HTTP protocol shapes in v0, durable storage formats in wire, and shared operation options in options.

Re-exports

pub use options::AttributeInclusion;

pub use v0::AdvanceRetentionRequest;

pub use v0::AdvanceRetentionResponse;

pub use v0::ApiError;

pub use v0::AttributesProjection;

pub use v0::Checkpoint;

pub use v0::CheckpointOwnerSummary;

pub use v0::Commit;

pub use v0::CommitPrecondition;

pub use v0::CommitRequest;

pub use v0::CreateCheckpointRequest;

pub use v0::CreateNamespaceRequest;

pub use v0::CreateSnapshotRequest;

pub use v0::DeleteCheckpointResponse;

pub use v0::DeleteDirectoryBehavior;

pub use v0::DeleteNamespaceResponse;

pub use v0::DeleteSnapshotResponse;

pub use v0::DeletedCheckpointsByOwner;

pub use v0::DeletedObjectCounts;

pub use v0::DestinationBehavior;

pub use v0::DestinationPrecondition;

pub use v0::DestinationPreconditionError;

pub use v0::ErrorDetails;

pub use v0::ExpectedFileState;

pub use v0::ExtendSnapshotRequest;

pub use v0::FileBytes;

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

pub use v0::ListPathEntriesResponse;

pub use v0::ListSnapshotsResponse;

pub use v0::ListTrashResponse;

pub use v0::MetadataCompactionOutcome;

pub use v0::MetadataCompactionRequest;

pub use v0::MetadataCompactionResponse;

pub use v0::MetadataMaintenanceRequest;

pub use v0::MetadataMaintenanceResponse;

pub use v0::Namespace;

pub use v0::NamespaceAccessMode;

pub use v0::NamespaceDiagnostics;

pub use v0::NamespaceForkBasis;

pub use v0::PathEntry;

pub use v0::PathEntryKind;

pub use v0::PreconditionFields;

pub use v0::RecoverAdministratorRequest;

pub use v0::RecoverAdministratorResponse;

pub use v0::ReorganizeStepOutcome;

pub use v0::RetainedCandidates;

pub use v0::RetainedReason;

pub use v0::RunMaintenanceRequest;

pub use v0::RunMaintenanceResponse;

pub use v0::SnapshotSummary;

pub use v0::TrashEntry;

pub use v0::WalFlushStepOutcome;

Modules

env

Environment variables used by more than one LoonFS process.

options

Per-operation options shared by the embedded runtime and HTTP client.

public_inode_id

Converts inode IDs between internal numbers and public API strings.

v0

Request and response shapes for the v0 HTTP API.

wire

Durable wire formats grouped by their owning format family.

Structs

AbsolutePath

Canonical absolute path plus its parsed components.

AccessGrants

A validated map from principal to rights, limited to MAX_ACCESS_GRANT_ENTRIES entries and MAX_ACCESS_GRANTS_PRINCIPAL_BYTES bytes of principal ids. No entry has an empty set of rights. Decoding rejects repeated principals.

AccessRevisionNo

Monotonic per-inode access revision.

AccessRights

A set of rights. Encoded as distinct names in read, history, write, create, remove, share, manage, admin order. Decoding accepts any order and rejects repeated names.

ActorId

A validated actor identifier supplied by the application.

ActorIdValidationError

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

AttributeKey

A validated inode attribute name from 1 to 128 UTF-8 bytes without control characters.

AttributeKeyValidationError

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

AttributeRevisionNo

The revision number for an inode’s attribute map.

AttributeValue

A validated inode attribute value of at most MAX_ATTRIBUTE_VALUE_BYTES UTF-8 bytes.

AttributeValueValidationError

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

Attributes

A validated attribute map limited to MAX_ATTRIBUTE_ENTRIES entries and MAX_ATTRIBUTES_TOTAL_BYTES total key and value UTF-8 bytes.

BindingGeneration

Opaque token identifying one parent and name binding generation.

BindingGenerationValidationError

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

CapabilityDocument

The API groups, features, and limits advertised by a deployment.

ChangeSeq

Sequence number assigned to a namespace commit.

CheckpointId

Durable checkpoint identifier.

Checksum

A checksum algorithm and its canonical lowercase hexadecimal value.

CommitFingerprint

The semantic identity of one mutation request.

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

A reference to one immutable content object.

ContentStoreId

Durable id for an immutable content store.

Crc32c

An incremental CRC-32C checksum.

Crc64Nvme

An incremental CRC-64/NVME checksum.

DirectoryPageCursor

A cursor that resumes one directory listing after last_name_key.

DisplayName

User-facing spelling of one path component.

EffectiveLimit

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

FileRevisionsPageCursor

A cursor that resumes a newest-first revision listing for one file.

GeneratedIdValidationError

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

GrepPageCursor

A cursor that resumes content search after one (inode_id, byte_offset) position.

IndexSegmentId

Durable id for one derived-index segment file.

InodeId

Numeric identity of a file or directory within a namespace.

ManifestNo

Monotonic manifest counter for one namespace.

MetadataCompactionId

Identifies one streaming metadata compaction job for log correlation only.

MetadataSegmentId

Durable id for one metadata segment.

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.

OperationDeadline

Elapsed-time state for one logical operation’s retry loop.

Page

A typed page result for internal runtime and core methods.

PageRequest

A typed page request for internal runtime and core methods.

Pager

Fetches pages and retains unused items between bounded collections.

PaginationPolicy

Fixed pagination contract for endpoints with potentially unbounded results.

PathComponent

One path segment as stored, preserving display spelling.

PrincipalId

A validated principal identifier supplied by the application.

PrincipalIdValidationError

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

PrincipalScope

The identity domain a namespace’s principal ids belong to.

PrincipalScopeValidationError

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

PrincipalSet

The principals a request acts as: distinct ids, at most MAX_SUBJECT_PRINCIPALS of them.

PublicOrdinalRangeError

Returned when an ordinal exceeds MAX_PUBLIC_INTEGER.

RevisionNo

Revision number for a file’s content.

RunNo

Monotonic run counter allocated by the manifest that names the run.

SecretString

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

Sha256

An incremental SHA-256 checksum.

SnapshotId

Id of a snapshot.

SnapshotIdValidationError

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

StdMonotonicTimer

Process-clock implementation backed by std::time::Instant.

Subject

Who a request acts as: a principal scope, stable id, and applicable principals.

SubjectId

The stable identity a request acts as, used for upload ownership and commit replay.

SubjectIdValidationError

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

TransportRetryPolicy

Bounded retry configuration for replay-safe transport operations.

TrashPageCursor

A cursor that resumes an oldest-first trash listing after one deletion.

UploadId

Durable id for one upload session.

WalNo

Contiguous WAL object number within one namespace.

WriterEpoch

Counter used to reject writes from an older writer.

WriterId

Stable writer label supplied by the embedding process.

WriterIdValidationError

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

Enums

AccessGrantsError

Why a grant map was rejected.

AccessRight

One right a grant can carry.

AttributesError

Describes which attribute-map limit an input broke.

CapabilityDocumentError

Violation of the capability document rules.

ChecksumAlgorithm

A supported checksum algorithm.

ChecksumValidationError

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

ContentRefKind

A supported content reference kind serialized as a string.

ContentRefValidationError

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

ErrorCode

A stable machine-readable error reason.

ErrorKind

The broad caller or operator action required for an error.

InodeKind

Filesystem item kind.

LimitError

Invalid caller-supplied page size.

MetadataFamilyGroup

Metadata families merged together as one consistency unit.

NamespaceAccess

A namespace’s access mode, fixed at creation.

NamespaceCursorError

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

OpaqueTokenError

Invalid opaque token encoding, version, kind, or body.

PageCursorError

Invalid opaque page cursor.

PathError

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

PrincipalSetError

Why a request’s principal set was rejected.

SemanticFingerprintError

A request cannot be represented by the version 1 fingerprint scheme.

StreamingChecksum

An incremental checksum for streamed reads and writes.

Constants

ALL_LIMIT_KEYS

Every registered advisory limit key.

API_GROUP_FILESYSTEM_V0

The mandatory filesystem API group.

API_GROUP_MAINTENANCE_V0

The optional maintenance API group.

API_GROUP_QUERY_V0

The optional derived-index query API group.

DEFAULT_MAX_PAGE_LIMIT

Contract maximum accepted page size.

DEFAULT_PAGE_LIMIT

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

FEATURE_ATTRIBUTES

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

FEATURE_COMMIT_INLINE_CONTENT

Gates inline bytes on commit operations.

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_INODES_LIST_CHILDREN

Gates listing a directory’s children by parent inode ID. Part of the filesystem API group and implemented by the runtime, so current deployments advertise it; the key exists so inode-driven sync clients can gate on deployments built before the route.

FEATURE_MAINTENANCE_GREP_INDEX

Gates grep index maintenance: enabling a namespace’s grep manifest, disabling it, collecting its garbage, and reading its lifecycle.

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 manifest is the data half.

FEATURE_SNAPSHOTS

Gates read-snapshot lifecycle operations.

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.

FIRST_ALLOCATABLE_INODE_ID

First inode id available after the root inode.

LIMIT_ACCESS_MAX_PRINCIPALS

Most principal ids one request may act as.

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_INLINE_CONTENT_BYTES

Largest inline value accepted on a commit operation.

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_COMMIT_MAX_PRECONDITIONS

Counts precondition entries, not resources; 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_SNAPSHOT_MAX_LIFETIME_MS

Advisory limit: the largest snapshot expiry measured from record creation.

LIMIT_SNAPSHOT_MAX_LIVE_PER_NAMESPACE

Advisory limit: the most live snapshots one namespace may hold.

LIMIT_SNAPSHOT_MAX_TTL_MS

Advisory limit: the largest snapshot TTL one request may ask for.

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_ACCESS_GRANTS_PRINCIPAL_BYTES

Most bytes of principal ids one access row may hold, summed over its entries.

MAX_ACCESS_GRANT_ENTRIES

Most principals one access row may name.

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.

MAX_SUBJECT_PRINCIPALS

Most principals one request may act as.

PAGE_CURSOR_FORMAT_VERSION

Format version written into every encoded cursor.

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.

Traits

MonotonicTimer

Supplies monotonic milliseconds for retry deadlines and deterministic test injection.

NamespaceCursor

A cursor bound to one namespace keyspace.

OpaqueToken

A serializable value with a frozen opaque-token discriminator.

PageCursor

A serializable cursor with an endpoint discriminator.

PagedResponse

A response that carries items and a continuation position.

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.

decode_token

Decodes a lowercase hexadecimal JSON token with the expected version and kind.

encode_cursor

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

encode_token

Encodes a value as lowercase hexadecimal JSON with a version and kind.

generated_id

Generates a project-standard opaque durable identifier.

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.

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.

transport_retry_backoff

Computes capped exponential backoff for a retry number starting at one.