hanna/fabrica

feat(web): route avatars, release assets, and LFS through the blob store

98dd84f · hanna committed on 2026-07-26

Wire the `BlobStore` into `AppState` and replace the direct filesystem calls in
the avatar, release-asset, and LFS handlers with namespaced blob operations, so
all three upload kinds honour `storage.backend`. Uploads still stream to a local
scratch file (to hash/size LFS objects) before being handed to the store, which
renames them into place locally or uploads them to S3. Surface the active
backend in `/healthz` and `fabrica doctor`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

crates/cli/src/admin_cmd.rs +20 −0

crates/web/Cargo.toml +1 −0

crates/web/src/avatar.rs +11 −16

crates/web/src/lfs.rs +24 −17

crates/web/src/lib.rs +10 −1

crates/web/src/releases.rs +21 −7

crates/web/src/serve.rs +10 −0

     check("config", Ok("loaded".to_string()));
     check("git", check_git(&loaded.config));
+    check("storage", Ok(describe_storage(&loaded.config)));
     let database = block_on(async { anyhow::Ok(check_database(&loaded.config).await) })?;
     check("database", database);
+    }
+}
+/// Describe the upload storage backend (config is already validated by load).
+fn describe_storage(config: &Config) -> String {
+    match config.storage.backend {
+        config::StorageBackend::Local => {
+            format!("local ({})", config.storage.data_dir.display())
+        }
+        config::StorageBackend::S3 => match &config.storage.s3 {
+            Some(s3) => {
+                let endpoint = s3.endpoint.as_deref().unwrap_or("aws");
+                format!(
+                    "s3 (bucket {}, region {}, {endpoint})",
+                    s3.bucket, s3.region
+                )
+            }
+            None => "s3 (unconfigured)".to_string(),
+        },
+    }
+}
 /// Verify the configured `git` binary is present and recent enough.
 fn check_git(config: &Config) -> Result<String, String> {
     let output = Command::new(&config.git.binary)

 config = { workspace = true }
 store = { workspace = true }
 model = { workspace = true }
+blob = { workspace = true }
 auth = { workspace = true }
 mail = { workspace = true }
 git = { workspace = true }

 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Avatars: an uploaded image when the user has one, else a deterministic
-//! identicon generated from the username. Bytes live on disk under
+//! identicon generated from the username. Bytes live in the `avatars` blob
-//! `{storage.data_dir}/avatars/{id}`; the `users.avatar_mime` column records the
+//! namespace (local disk or S3), keyed by user id; the `users.avatar_mime`
-//! content type (its presence means "serve the file"). No network requests and
+//! column records the content type (its presence means "serve the file"). No
-//! no remote gravatar (§9.5).
+//! network requests and no remote gravatar (§9.5).
 use std::fmt::Write as _;
-use std::path::PathBuf;
 use axum::extract::{Multipart, Path, State};
 use axum::http::{StatusCode, header};
 use axum::response::{IntoResponse, Redirect, Response};
 use axum_extra::extract::cookie::CookieJar;
+use blob::Namespace;
 use crate::AppState;
 use crate::error::AppError;
 /// avoid serving user-supplied markup; identicons are our own SVG.
 const ALLOWED_MIME: &[&str] = &["image/png", "image/jpeg", "image/gif", "image/webp"];
-/// The on-disk path of a user's uploaded avatar.
-fn avatar_path(state: &AppState, user_id: &str) -> PathBuf {
-    state.config.storage.data_dir.join("avatars").join(user_id)
-}
 /// `GET /avatar/{username}` — the user's uploaded avatar, or a generated
 /// identicon. Always renders an image so `<img>` tags never break.
 pub async fn show(State(state): State<AppState>, Path(username): Path<String>) -> Response {
     let user = state.store.user_by_username(&username).await.ok().flatten();
     if let Some(user) = &user
         && let Some(mime) = &user.avatar_mime
-        && let Ok(bytes) = tokio::fs::read(avatar_path(&state, &user.id)).await
+        && let Ok(Some(bytes)) = state.blobs.get_bytes(Namespace::Avatars, &user.id).await
+    {
         return (
+            [
             .into_response();
+    }
-    let dir = state.config.storage.data_dir.join("avatars");
+    if let Err(e) = state
-    if let Err(e) = tokio::fs::create_dir_all(&dir).await {
+        .blobs
-        return AppError::internal(e).into_response();
+        .put_bytes(Namespace::Avatars, &user.id, bytes, &mime)
-    }
+        .await
-    if let Err(e) = tokio::fs::write(dir.join(&user.id), &bytes).await {
+    {
         return AppError::internal(e).into_response();
+    }
     if let Err(e) = state.store.set_avatar_mime(&user.id, Some(&mime)).await {

 //! [Batch API]: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md
 use std::collections::HashMap;
-use std::path::PathBuf;
 use std::sync::atomic::{AtomicU64, Ordering};
 use axum::body::Body;
 use axum::http::{HeaderMap, StatusCode, header};
 use axum::response::{IntoResponse, Response};
 use axum_extra::extract::cookie::CookieJar;
+use blob::Namespace;
 use futures_util::TryStreamExt as _;
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
             .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
+}
-/// The on-disk path for an object, sharded by the first two byte-pairs of the oid.
+/// The blob key for an object, sharded by the first two byte-pairs of the oid.
-fn object_path(lfs_dir: &std::path::Path, oid: &str) -> PathBuf {
+/// Callers pass only validated 64-char oids, so the slices are in bounds.
-    lfs_dir.join(&oid[0..2]).join(&oid[2..4]).join(oid)
+fn object_key(oid: &str) -> String {
+    format!("{}/{}/{}", &oid[0..2], &oid[2..4], oid)
+}
 /// Hex-encode a byte slice (lowercase), for comparing a computed digest to an oid.
+    {
         return StatusCode::NOT_FOUND.into_response();
+    }
-    let path = object_path(&state.config.storage.lfs_dir, &oid);
+    let Ok(Some(read)) = state.blobs.open(Namespace::Lfs, &object_key(&oid)).await else {
-    let Ok(file) = tokio::fs::File::open(&path).await else {
         return StatusCode::NOT_FOUND.into_response();
     };
-    let len = file.metadata().await.map_or(0, |m| m.len());
+    let body = Body::from_stream(ReaderStream::new(read.reader));
-    let body = Body::from_stream(ReaderStream::new(file));
+    (
+        [
             (header::CONTENT_TYPE, "application/octet-stream".to_string()),
-            (header::CONTENT_LENGTH, len.to_string()),
+            (header::CONTENT_LENGTH, read.size.to_string()),
         ],
         body,
+    )
         return StatusCode::OK.into_response();
+    }
-    let lfs_dir = &state.config.storage.lfs_dir;
+    // Stream to a local scratch file to hash and size it before it becomes
-    let tmp_dir = lfs_dir.join("tmp");
+    // servable; `data_dir` is always local, whatever the blob backend is.
+    let tmp_dir = state.config.storage.data_dir.join("tmp");
     if tokio::fs::create_dir_all(&tmp_dir).await.is_err() {
         return lfs_error(StatusCode::INTERNAL_SERVER_ERROR, "storage error");
+    }
     let tmp = tmp_dir.join(format!(
-        "{}.{}.tmp",
+        "lfs-{}.{}.tmp",
         std::process::id(),
         TMP_SEQ.fetch_add(1, Ordering::Relaxed)
     ));
         return lfs_error(StatusCode::UNPROCESSABLE_ENTITY, "oid mismatch");
+    }
-    let dest = object_path(lfs_dir, &oid);
+    // Move the verified object into the blob store (local rename or S3 upload).
-    if let Some(parent) = dest.parent() {
+    if state
-        let _ = tokio::fs::create_dir_all(parent).await;
+        .blobs
-    }
+        .put_file(
-    if tokio::fs::rename(&tmp, &dest).await.is_err() {
+            Namespace::Lfs,
+            &object_key(&oid),
+            &tmp,
+            "application/octet-stream",
+        )
+        .await
+        .is_err()
+    {
         let _ = tokio::fs::remove_file(&tmp).await;
         return lfs_error(StatusCode::INTERNAL_SERVER_ERROR, "storage error");
+    }

     /// The mailer could not be constructed from configuration.
     #[error("mail configuration error: {0}")]
     Mail(String),
+    /// The upload storage backend could not be constructed from configuration.
+    #[error("storage configuration error: {0}")]
+    Blob(String),
     /// The server socket failed to bind or serve.
     #[error(transparent)]
     Io(#[from] std::io::Error),
     pub config: Arc<Config>,
     /// The database handle.
     pub store: Store,
+    /// Upload storage (avatars, release assets, LFS) — local disk or S3.
+    pub blobs: blob::BlobStore,
     /// The configured mailer (invite emails).
     pub mailer: Arc<Mailer>,
     /// The instance signing secret (API tokens, future session signing).
     ///
     /// # Errors
     ///
-    /// Returns [`WebError::Mail`] if the mailer cannot be constructed.
+    /// Returns [`WebError::Mail`] if the mailer cannot be constructed, or
+    /// [`WebError::Blob`] if the upload storage backend is misconfigured.
     pub fn build(config: Arc<Config>, store: Store, secret: String) -> Result<Self, WebError> {
         let mailer = Mailer::build(&config.mail).map_err(|e| WebError::Mail(e.to_string()))?;
+        let blobs = blob::BlobStore::from_config(&config.storage)
+            .map_err(|e| WebError::Blob(e.to_string()))?;
         let assets = Assets::new(config.ui.assets_dir.clone(), config.ui.themes_dir.clone());
         Ok(Self {
             config,
             store,
+            blobs,
             mailer: Arc::new(mailer),
             secret: Arc::new(secret),
             signatures: git::SignatureCache::new(4096),

     let result = async {
         let (release, repo, user) = writer_release(&state, viewer.as_ref(), &id).await?;
         for a in state.store.list_release_assets(&release.id).await? {
-            let _ = tokio::fs::remove_file(assets_dir(&state).join(&a.id)).await;
+            let _ = state.blobs.delete(blob::Namespace::Releases, &a.id).await;
+        }
         state.store.delete_release(&release.id).await?;
         Ok::<String, AppError>(format!("/{}/{}/-/releases", user.username, repo.path))
                 .store
                 .add_release_asset(&release.id, &name, size, &ctype)
                 .await?;
-            let dest = assets_dir(&state).join(&asset.id);
+            // Move the streamed temp file into the blob store (local rename or
+            // S3 upload); a failure rolls the row back.
             let tmp = assets_dir(&state).join("tmp").join(&tmp_name);
-            if tokio::fs::rename(&tmp, &dest).await.is_err() {
+            if state
+                .blobs
+                .put_file(blob::Namespace::Releases, &asset.id, &tmp, &ctype)
+                .await
+                .is_err()
+            {
                 let _ = tokio::fs::remove_file(&tmp).await;
                 let _ = state.store.delete_release_asset(&asset.id).await;
                 return Err(AppError::internal("storage error"));
         .ok_or(AppError::NotFound)?;
     // The viewer must be able to read the repo the release belongs to.
     let _ = require_readable_repo(&state, viewer.as_ref(), &release.repo_id).await?;
-    let path = assets_dir(&state).join(&asset.id);
+    let Some(read) = state
-    let Ok(file) = tokio::fs::File::open(&path).await else {
+        .blobs
+        .open(blob::Namespace::Releases, &asset.id)
+        .await
+        .map_err(AppError::internal)?
+    else {
         return Err(AppError::NotFound);
     };
     let _ = state.store.bump_asset_download(&asset.id).await;
+        [
             (header::CONTENT_TYPE, asset.content_type.clone()),
             (header::CONTENT_DISPOSITION, disposition),
+            (header::CONTENT_LENGTH, read.size.to_string()),
         ],
-        Body::from_stream(ReaderStream::new(file)),
+        Body::from_stream(ReaderStream::new(read.reader)),
+    )
         .into_response())
+}
             .ok_or(AppError::NotFound)?;
         let (release, _repo, _user) =
             writer_release(&state, viewer.as_ref(), &asset.release_id).await?;
-        let _ = tokio::fs::remove_file(assets_dir(&state).join(&asset.id)).await;
+        let _ = state
+            .blobs
+            .delete(blob::Namespace::Releases, &asset.id)
+            .await;
         state.store.delete_release_asset(&asset.id).await?;
         Ok::<String, AppError>(format!("/release/{}/edit", release.id))
+    }

     let git = git_version(&state.config.git.binary);
     let db_ok = state.store.migrate().await.is_ok();
     let healthy = git.is_some() && db_ok;
+    let storage = match state.config.storage.backend {
+        config::StorageBackend::Local => "local".to_string(),
+        config::StorageBackend::S3 => state
+            .config
+            .storage
+            .s3
+            .as_ref()
+            .map_or_else(|| "s3".to_string(), |s3| format!("s3:{}", s3.bucket)),
+    };
     let body = serde_json::json!({
         "status": if healthy { "ok" } else { "degraded" },
         "git": git,
         "git_binary": state.config.git.binary,
         "database": if db_ok { "ok" } else { "error" },
+        "storage": storage,
     });
     let status = if healthy {
         StatusCode::OK