loonfs_api/
lib.rs

1//! Wire types and durable-format codecs for LoonFS.
2//!
3//! Everything that crosses a process or storage boundary is defined here:
4//! validated identifier and path types at the crate root, the versioned HTTP
5//! protocol shapes in [`v0`], and the durable storage formats in [`wire`]
6//! (WAL segments, metadata SSTs, namespace manifests, and control objects).
7//! Other LoonFS crates depend on this one for vocabulary; it depends on none
8//! of them.
9//!
10//! One module here is deliberately not a boundary format: [`options`] holds
11//! the per-operation argument structs that the embedded runtime and the HTTP
12//! client both expose. They parameterize the same semantic operations on both
13//! surfaces, so this crate — the shared vocabulary — owns the single
14//! definition rather than each surface keeping its own copy to drift.
15//!
16//! The `commit_identity` module contains shared logic rather than wire types.
17//! It computes durable mutation fingerprints and verifies retried PUT requests
18//! against existing commit receipts. Keeping this logic here ensures that the
19//! embedded runtime and HTTP client apply the same identity and content checks.
20//!
21//! Module rule: v0 HTTP shapes live in [`v0`]; the crate root keeps the
22//! ids/paths/errors/wire-format modules and re-exports the common v0
23//! surface as a curated explicit list below.
24
25#![warn(missing_docs)]
26
27mod actor;
28mod attributes;
29mod capability;
30mod commit_identity;
31mod content;
32mod control;
33mod digest;
34pub mod env;
35mod envelope;
36mod error;
37mod hex;
38mod ids;
39mod manifest;
40mod name_policy;
41pub mod options;
42mod pagination;
43mod path;
44pub mod public_inode_id;
45mod secret;
46mod sst_blocks;
47pub mod v0;
48mod wal;
49
50pub mod wire {
51    //! Durable wire formats grouped by their owning format family.
52
53    pub mod hex {
54        //! Lowercase hexadecimal primitives shared by durable codecs.
55
56        pub use crate::hex::*;
57    }
58
59    pub mod manifest {
60        //! Namespace-manifest envelopes, rows, and key constructors.
61
62        pub use crate::manifest::*;
63    }
64
65    pub mod control {
66        //! Mutable namespace control-object envelopes and payloads.
67
68        pub use crate::control::*;
69    }
70
71    pub mod envelope {
72        //! The shared durable envelope codec: probe, validation rules, JSON
73        //! codec, and the one error vocabulary every family reports through.
74        //!
75        //! Published so a durable format outside this crate — a first-party
76        //! extension's own objects — parameterizes the same codec instead of
77        //! copying it and drifting from the rules in section 4 of the format
78        //! spec.
79
80        pub use crate::envelope::*;
81    }
82
83    pub mod sst_blocks {
84        //! Metadata SST block handles, builders, and codecs.
85
86        pub use crate::sst_blocks::*;
87    }
88
89    pub mod wal {
90        //! WAL segment envelopes, records, and codecs.
91
92        pub use crate::wal::*;
93    }
94}
95
96pub use actor::{ActorId, ActorIdValidationError, ActorKind, ActorRef};
97pub use attributes::{
98    AttributeKey, AttributeKeyValidationError, AttributeRevisionNo, AttributeValue,
99    AttributeValueValidationError, Attributes, AttributesError, MAX_ATTRIBUTES_TOTAL_BYTES,
100    MAX_ATTRIBUTE_ENTRIES, MAX_ATTRIBUTE_KEY_BYTES, MAX_ATTRIBUTE_VALUE_BYTES,
101    RESERVED_ATTRIBUTE_KEY_PREFIX,
102};
103pub use capability::{
104    direct_put_checksum_feature, CapabilityDocument, CapabilityDocumentError,
105    FEATURE_ADMIN_GREP_INDEX, FEATURE_ATTRIBUTES, FEATURE_DOWNLOADS_DIRECT_GET,
106    FEATURE_NAMESPACES_CREATE, FEATURE_NAMESPACES_DELETE, FEATURE_NAMESPACES_FORK,
107    FEATURE_QUERY_GREP, FEATURE_UPLOADS_DIRECT_MULTIPART, FEATURE_UPLOADS_DIRECT_PUT,
108    FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_CRC32C, FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_CRC64NVME,
109    FEATURE_UPLOADS_DIRECT_PUT_CHECKSUM_SHA256, LIMIT_COMMIT_MAX_CONTENT_TOKENS,
110    LIMIT_COMMIT_MAX_EXTERNAL_CONTENT_REFS, LIMIT_COMMIT_MAX_MESSAGE_BYTES,
111    LIMIT_COMMIT_MAX_OPERATIONS, LIMIT_DOWNLOAD_MAX_CONCURRENT, LIMIT_DOWNLOAD_MAX_CONTENT_BYTES,
112    LIMIT_GC_MIN_GRACE_WINDOW_MS, LIMIT_PAGINATION_DEFAULT, LIMIT_PAGINATION_MAX,
113    LIMIT_QUERY_GREP_DEFAULT, LIMIT_QUERY_GREP_MAX, LIMIT_QUERY_GREP_SCAN_BUDGET_FILES,
114    LIMIT_QUERY_GREP_TAIL_BUDGET_FILES, LIMIT_UPLOAD_COMPLETION_MAX_BODY_BYTES,
115    LIMIT_UPLOAD_DIRECT_PUT_MAX_CONTENT_BYTES, LIMIT_UPLOAD_MAX_CONCURRENT,
116    LIMIT_UPLOAD_MAX_CONTENT_BYTES, PROFILE_ADMIN_V0, PROFILE_CORE_V0, PROFILE_QUERY_V0,
117    PROTOCOL_VERSION, UPLOADS_DIRECT_PUT_CHECKSUM_FEATURES,
118};
119pub use commit_identity::{
120    put_retry_fingerprint, reconcile_put_commit_id_reuse, semantic_commit_fingerprint,
121    PutRetryAttempt, PutRetryErrorClassification, PutRetryReceipt, SemanticFingerprintError,
122};
123pub use content::{
124    Checksum, ChecksumAlgorithm, ChecksumValidationError, ContentEvidence, ContentRef,
125    ContentRefKind, ContentRefValidationError, Crc32c, Crc64Nvme, Sha256, StreamingChecksum,
126};
127pub use digest::sha256_digest;
128pub use error::{ErrorCode, ErrorKind};
129pub use ids::{
130    generated_id, manifest_object_id_manifest_id, next_public_ordinal, wal_segment_id_start_seq,
131    ChangeSeq, CheckpointId, CommitId, CommitIdValidationError, ContentId, ContentStoreId,
132    GeneratedIdValidationError, GrepManifestId, IndexSegmentId, InodeId, InodeKind, ManifestId,
133    ManifestObjectId, MetadataCompactionId, MetadataTableId, NameKey, NameKeyValidationError,
134    NamespaceId, NamespaceIdValidationError, PublicOrdinalRangeError, RevisionNo, UploadId,
135    WalSegmentId, WriterEpoch, FIRST_ALLOCATABLE_INODE_ID, MAX_ID_BYTES, MAX_NAME_KEY_BYTES,
136    MAX_PUBLIC_INTEGER, ROOT_INODE_ID,
137};
138pub use name_policy::name_key_for_display_name;
139pub use pagination::{
140    decode_cursor, decode_namespace_cursor, encode_cursor, DirectoryPageCursor, EffectiveLimit,
141    FileRevisionsPageCursor, GrepPageCursor, LimitError, NamespaceCursor, NamespaceCursorError,
142    Page, PageCursor, PageCursorError, PageRequest, PaginationPolicy, TrashPageCursor,
143    DEFAULT_MAX_PAGE_LIMIT, DEFAULT_PAGE_LIMIT, PAGE_CURSOR_VERSION,
144};
145pub use path::{
146    AbsolutePath, DisplayName, PathComponent, PathError, MAX_DISPLAY_NAME_BYTES, MAX_PATH_BYTES,
147    MAX_PATH_DEPTH,
148};
149pub use secret::SecretString;
150
151// Curated root re-exports of the common v0 HTTP surface. v0 HTTP shapes live
152// in `v0`; add here only what most consumers touch.
153pub use v0::{
154    AdvanceRetentionResponse, ApiError, AttributesProjection, AuthoritativeFileBytes,
155    AuthoritativePathEntry, AuthoritativePathEntryKind, Checkpoint, CheckpointOwnerSummary,
156    CommitRequest, CommitResponse, CreateCheckpointRequest, CreateCheckpointResponse,
157    CreateNamespaceRequest, DeleteDirectoryBehavior, DeleteNamespaceResponse, DestinationBehavior,
158    ErrorDetails, FileRevision, FilesystemOperation, FlushWalOutcome, FlushWalResponse,
159    ForkNamespaceRequest, GcRequest, GcResponse, GrepMatch, GrepRequest, GrepResponse,
160    ListCheckpointsResponse, ListFileRevisionsResponse, ListPathEntriesResponse, ListTrashResponse,
161    MaintenanceStepRequest, MaintenanceStepResponse, MetadataMaintenanceRequest,
162    MetadataMaintenanceResponse, NamespaceStatusResponse, ReleaseCheckpointResponse,
163    ReorganizeStepOutcome, RetainedCandidates, RetainedReason, TrashEntry, WalFlushStepOutcome,
164};
loonfs_api/lib.rs

loonfs_api/
lib.rs
