stately_files/
lib.rs

1//! File upload, versioning, and download management for stately applications.
2//!
3//! This crate provides HTTP endpoints and path types for managing files with automatic
4//! UUID-based versioning, enabling entities to reference uploaded and stored files.
5//!
6//! # Features
7//!
8//! - **File Uploads**: Multipart form and JSON-based uploads with automatic versioning
9//! - **File Downloads**: Streaming downloads with content-type detection
10//! - **Path Types**: Configuration property types for referencing files in entities
11//! - **Version Resolution**: Automatic latest-version resolution for uploaded files
12//!
13//! # Storage Structure
14//!
15//! Uploaded files are stored with automatic versioning:
16//!
17//! ```text
18//! {data_dir}/uploads/{filename}/__versions__/{uuid}
19//! ```
20//!
21//! UUID v7 identifiers are time-sortable, so the latest version is the lexicographically
22//! largest UUID in the directory.
23//!
24//! # Path Types
25//!
26//! Use these types in entity configurations to reference files:
27//!
28//! - [`path::VersionedPath`]: Logical filename that resolves to latest version
29//! - [`path::RelativePath`]: Path relative to cache, data, or uploads directory
30//! - [`path::UserDefinedPath`]: Union of managed or external (user-provided) paths
31//!
32//! # API Endpoints
33//!
34//! The [`router::router`] function provides these endpoints:
35//!
36//! | Method | Path | Description |
37//! |--------|------|-------------|
38//! | `POST` | `/upload` | Upload via multipart form |
39//! | `POST` | `/save` | Save from JSON body |
40//! | `GET` | `/list` | List files and directories |
41//! | `GET` | `/file/cache/{path}` | Download from cache |
42//! | `GET` | `/file/data/{path}` | Download from data |
43//! | `GET` | `/file/upload/{path}` | Download uploaded file |
44//!
45//! # Usage
46//!
47//! ```rust,ignore
48//! use axum::Router;
49//! use stately_files::{router, state::FileState, settings::Dirs};
50//!
51//! // Create app state with custom directories
52//! let dirs = Dirs::new(
53//!     "/app/cache".into(),
54//!     "/app/data".into(),
55//! );
56//!
57//! // Mount the files router
58//! let app = Router::new()
59//!     .nest("/files", router::router(FileState::new(dirs)));
60//! ```
61
62pub mod error;
63pub mod handlers;
64pub mod openapi;
65pub mod path;
66pub mod request;
67pub mod response;
68pub mod router;
69pub mod settings;
70pub mod state;
71pub mod utils;
72
73// Re-export commonly used types at crate root
74pub use openapi::OpenApiDoc;
75pub use path::{RelativePath, UserDefinedPath, VersionedPath};
76pub use request::{FileDownloadQuery, FileListQuery, FileSaveRequest};
77pub use response::{FileEntryType, FileInfo, FileListResponse, FileUploadResponse, FileVersion};
78pub use settings::Dirs;
79pub use state::FileState;
stately_files/lib.rs

stately_files/
lib.rs
