Architecture

Crate Structure

Ferro is built as a Rust workspace with 20 crates:

ferro/
+-- crates/
|   +-- common/       # Shared types, StorageEngine trait, error handling
|   +-- core/         # Storage backends, search engine, WASM runtime
|   +-- server/       # Axum web server, WebDAV, REST API, all HTTP handlers
|   +-- dav/          # CalDAV/CardDAV parsers, store traits, Axum handlers
|   +-- crypto/       # Cryptographic primitives (hashing, HMAC, bcrypt)
|   +-- client/       # Async WebDAV client SDK with optional C-FFI
|   +-- fuse/         # FUSE3 filesystem mount (Linux only)
|   +-- web/          # Leptos WASM web frontend
|   +-- cli/          # Admin CLI tool
|   +-- desktop/      # Tauri desktop application
|   +-- admin/        # Leptos WASM admin dashboard
|   +-- auth/         # Authentication (simple, OIDC), authorization (Cedar)
|   +-- webdav-handler/ # WebDAV XML request/response builders
|   +-- server-activitypub/ # ActivityPub federation
|   +-- server-webrtc/     # WebRTC signaling
|   +-- server-wopi/       # WOPI protocol for office documents
|   +-- server-versioning/ # File versioning and diff
|   +-- graphql/       # GraphQL API (async-graphql)
|   +-- observability/ # Metrics, logging, health checks
|   +-- benchmarks/    # Criterion benchmark suite
+-- deploy/           # Deployment configurations (Docker, K8s, Terraform, etc.)

Request Flow

HTTP Request
    |
    v
+------------------+
| Compression Layer|  (gzip, brotli)
+--------+---------+
         |
+--------+---------+
| Security Headers |  (HSTS, CSP, X-Content-Type-Options, X-Frame-Options)
+--------+---------+
         |
+--------+---------+
| Request Logging  |  (X-Request-ID, request counter)
+--------+---------+
         |
+--------+---------+
| Request ID       |  (assigns unique X-Request-ID header)
+--------+---------+
         |
+--------+---------+
| CORS Layer       |  (configurable origins, preflight handling)
+--------+---------+
         |
+--------+---------+
| Simple Auth      |  (HTTP Basic Auth if configured)
+--------+---------+
         |
+--------+---------+
| OIDC Auth        |  (PKCE flow if configured)
+--------+---------+
         |
+--------+---------+
| Cedar AuthZ      |  (policy-based authorization if configured)
+--------+---------+
         |
+--------+---------+
| Rate Limiter     |  (10,000 req/min per IP)
+--------+---------+
         |
+--------+---------+
|   Router         |  (Axum)
|  +------------+  |
|  | Handler(s) |  |  (WebDAV, REST, GraphQL, CalDAV, etc.)
|  +------------+  |
|  |  AppState   |  |
|  +------------+  |
+------------------+
         |
+--------+---------+
|  Storage Engine  |  (In-Memory, Local FS, S3, GCS, Azure)
+------------------+

The middleware stack processes requests in order. Each layer can short-circuit the request (e.g., rate limiter returns 429, auth returns 401).

Storage Abstraction

All storage operations go through the StorageEngine trait defined in ferro-common:

#![allow(unused)]
fn main() {
pub trait StorageEngine: Send + Sync {
    async fn head(&self, path: &str) -> Result<FileMetadata>;
    async fn get(&self, path: &str) -> Result<Bytes>;
    async fn get_stream(&self, path: &str) -> Result<StorageReader>;
    async fn put(&self, path: &str, content: Bytes, owner: &str) -> Result<FileMetadata>;
    async fn delete(&self, path: &str) -> Result<()>;
    async fn list(&self, path: &str) -> Result<Vec<FileMetadata>>;
    async fn copy(&self, from: &str, to: &str) -> Result<()>;
    async fn move_path(&self, from: &str, to: &str) -> Result<()>;
    async fn exists(&self, path: &str) -> Result<bool>;
    async fn create_collection(&self, path: &str, owner: &str) -> Result<FileMetadata>;
    async fn list_all(&self, path: &str, max_depth: u32) -> Result<Vec<FileMetadata>>;
    async fn put_multipart(&self, path: &str, parts: Vec<Bytes>, owner: &str) -> Result<FileMetadata>;
}
}

This allows swapping backends without changing any server code. The ObjectStoreStorageEngine in ferro-core wraps the object_store crate to support S3, GCS, and Azure via a single implementation.

Feature Flags

# Build with all storage backends
cargo build --features s3,gcs,azure

# Build with PostgreSQL and Redis
cargo build --features pg,redis  # Note: server feature is "pg", core feature is "postgres"

AppState

The central state object shared across all handlers: