libfw_core/lib.rs
1//! Shared data structures, traits, protocol constants and streaming
2//! compression abstractions for the libfw transfer library.
3//!
4//! `libfw-core` is the foundation crate consumed by both
5//! [`libfw-server`](https://docs.rs/libfw-server) (server routing /
6//! middleware) and [`libfw-client`](https://docs.rs/libfw-client) (WASM
7//! engine + JS SDK). It contains no I/O of its own: it defines the
8//! *contracts*.
9//!
10//! # Highlights
11//!
12//! - [`TokenClaims`], [`Action`] and the [`Validator`] trait for
13//! fine-grained bearer-token authorization.
14//! - [`StorageBackend`] and [`UploadSink`] traits for pluggable storage.
15//! - [`Compressor`] / [`Decompressor`] streaming traits backed by
16//! [`zrip`] (zstd) with constant-memory guarantees.
17//! - Protocol constants: [`CHUNK_SIZE`], [`HEADER_COMPRESS`],
18//! [`HEADER_FILE_META`] and friends.
19//! - Transfer metadata ([`FileMeta`], [`TransferPlan`], [`ChunkMeta`]).
20//!
21//! # Example
22//!
23//! ```
24//! use libfw_core::auth::{Action, PathValidator, Validator};
25//! use libfw_core::claims::{TokenClaims, Permission};
26//!
27//! let claims = TokenClaims {
28//! sub: "user-42".into(),
29//! exp: None,
30//! permissions: vec![Permission::Read, Permission::Write],
31//! allowed_paths: vec!["/docs/".into()],
32//! };
33//! let validator = PathValidator::new();
34//! // `/docs/spec.pdf` sits under the allowed `/docs/` prefix.
35//! assert!(validator.validate(&claims, "/docs/spec.pdf", Action::Read).is_ok());
36//! ```
37
38pub mod auth;
39pub mod capabilities;
40pub mod claims;
41pub mod compress;
42pub mod constants;
43pub mod error;
44pub mod metadata;
45pub mod pathmap;
46pub mod range;
47pub mod storage;
48
49pub use auth::{Action, AuthError, PathValidator, TokenVerifier, Validator};
50pub use capabilities::{Capabilities, CompressionCaps, IntRange, Limits, ZripLevels};
51pub use claims::{Permission, TokenClaims};
52pub use compress::{
53 CompressionFormat, Compressor, Decompressor, ZRIP_DEFAULT_LEVEL, ZRIP_MAX_LEVEL,
54 ZRIP_MIN_LEVEL, compressor_with_level, is_valid_zrip_level, negotiate_level,
55};
56pub use constants::*;
57pub use error::{CompressError, DecompressError, StorageError};
58pub use metadata::{ChunkMeta, FileMeta, TransferPlan};
59pub use pathmap::{IdentityPathCodec, MountPathCodec, PathCodec, PathCodecError};
60#[cfg(feature = "path-encrypt")]
61pub use pathmap::EncryptedPathCodec;
62pub use range::RangeSpec;
63pub use storage::{DirEntry, StorageBackend, UploadSink, WriteMode};