Crate stately_files 

File upload, versioning, and download management for stately applications.

This crate provides HTTP endpoints and path types for managing files with automatic UUID-based versioning, enabling entities to reference uploaded and stored files.

Features

• File Uploads: Multipart form and JSON-based uploads with automatic versioning
• File Downloads: Streaming downloads with content-type detection
• Path Types: Configuration property types for referencing files in entities
• Version Resolution: Automatic latest-version resolution for uploaded files

Storage Structure

Uploaded files are stored with automatic versioning:

{data_dir}/uploads/{filename}/__versions__/{uuid}

UUID v7 identifiers are time-sortable, so the latest version is the lexicographically largest UUID in the directory.

Path Types

Use these types in entity configurations to reference files:

• path::VersionedPath: Logical filename that resolves to latest version
• path::RelativePath: Path relative to cache, data, or uploads directory
• path::UserDefinedPath: Union of managed or external (user-provided) paths

API Endpoints

The router::router function provides these endpoints:

Method	Path	Description
POST	/upload	Upload via multipart form
POST	/save	Save from JSON body
GET	/list	List files and directories
GET	/file/cache/{path}	Download from cache
GET	/file/data/{path}	Download from data
GET	/file/upload/{path}	Download uploaded file

Usage

use axum::Router;
use stately_files::{router, state::FileState, settings::Dirs};

// Create app state with custom directories
let dirs = Dirs::new(
    "/app/cache".into(),
    "/app/data".into(),
);

// Mount the files router
let app = Router::new()
    .nest("/files", router::router(FileState::new(dirs)));

Re-exports

pub use openapi::OpenApiDoc;

pub use path::RelativePath;

pub use path::UserDefinedPath;

pub use path::VersionedPath;

pub use request::FileDownloadQuery;

pub use request::FileListQuery;

pub use request::FileSaveRequest;

pub use response::FileEntryType;

pub use response::FileInfo;

pub use response::FileListResponse;

pub use response::FileUploadResponse;

pub use response::FileVersion;

pub use settings::Dirs;

pub use state::FileState;

Modules

error

handlers

openapi

OpenAPI documentation for stately-files endpoints.

path

The files in this module are to be used throughout stately configuration.

request

Request types for file management endpoints.

response

Response types for file management endpoints.

router

settings

Directory configuration and constants for file storage.

state

Application state for file management handlers.

utils