feat: assemble completed uploads

Implement POST /api/uploads/{id}/complete. The storage layer now reloads upload
metadata, verifies that every expected chunk exists with the exact expected
length, concatenates chunks in order into a temporary final file, flushes it,
and renames it into data/complete only after assembly succeeds.

The endpoint preserves staging data after completion, rejects incomplete uploads
with a conflict response, and refuses to overwrite an existing completed file.
This keeps failed or duplicate completion attempts explicit rather than silently
clobbering local files.

Extend the model, router, documentation, and test checklist for completion
responses and add integration coverage for successful assembly, incomplete
uploads, staging preservation, and duplicate completion conflicts.

Test Plan:
- just check

Refs: PLAN.md milestone 8

src/api.rs

@@ -10,7 +10,7 @@ use serde::Serialize;
 
 use crate::{
     app::AppState,
-    model::{CreateUploadRequest, CreateUploadResponse},
+    model::{CompleteUploadResponse, CreateUploadRequest, CreateUploadResponse},
     storage::StorageError,
 };
 
@@ -56,6 +56,19 @@ pub async fn put_chunk(
     Ok(StatusCode::NO_CONTENT)
 }
 
+/// Assembles uploaded chunks into the final completed file.
+///
+/// # Errors
+///
+/// Returns an API error when the upload is unknown, incomplete, invalid, or
+/// cannot be assembled on disk.
+pub async fn complete_upload(
+    State(state): State<AppState>,
+    Path(upload_id): Path<String>,
+) -> Result<Json<CompleteUploadResponse>, ApiError> {
+    Ok(Json(state.storage.complete_upload(&upload_id).await?))
+}
+
 #[derive(Debug)]
 pub struct ApiError {
     status: StatusCode,
@@ -78,6 +91,8 @@ impl From<StorageError> for ApiError {
     fn from(error: StorageError) -> Self {
         let status = if error.is_not_found() {
             StatusCode::NOT_FOUND
+        } else if error.is_conflict() {
+            StatusCode::CONFLICT
         } else if error.is_invalid_input() {
             StatusCode::BAD_REQUEST
         } else {

src/app.rs

@@ -75,6 +75,10 @@ pub fn build_router(config: &AppConfig) -> Router {
         .route("/healthz", get(healthz))
         .route("/api/uploads", post(api::create_upload))
         .route("/api/uploads/{upload_id}", get(api::get_upload))
+        .route(
+            "/api/uploads/{upload_id}/complete",
+            post(api::complete_upload),
+        )
         .route(
             "/api/uploads/{upload_id}/chunks/{index}",
             axum::routing::put(api::put_chunk),

src/model.rs

@@ -27,6 +27,13 @@ pub struct UploadProgressResponse {
     pub completed_chunks: Vec<u64>,
 }
 
+#[derive(Debug, Deserialize, Serialize)]
+pub struct CompleteUploadResponse {
+    pub upload_id: String,
+    pub name: String,
+    pub file_path: String,
+}
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct UploadMeta {
     pub id: String,
@@ -61,4 +68,13 @@ impl UploadMeta {
             completed_chunks,
         }
     }
+
+    #[must_use]
+    pub fn complete_response(&self, file_path: String) -> CompleteUploadResponse {
+        CompleteUploadResponse {
+            upload_id: self.id.clone(),
+            name: self.safe_name.clone(),
+            file_path,
+        }
+    }
 }

src/storage.rs

@@ -5,10 +5,12 @@ use std::{
 };
 
 use time::{OffsetDateTime, format_description::well_known::Rfc3339};
-use tokio::fs;
+use tokio::{fs, io::AsyncWriteExt};
 use uuid::Uuid;
 
-use crate::model::{CHUNK_SIZE, CreateUploadRequest, UploadMeta, UploadProgressResponse};
+use crate::model::{
+    CHUNK_SIZE, CompleteUploadResponse, CreateUploadRequest, UploadMeta, UploadProgressResponse,
+};
 
 #[derive(Clone, Debug)]
 pub struct Storage {
@@ -123,6 +125,52 @@ impl Storage {
         Ok(())
     }
 
+    /// Assembles a complete upload from verified chunk files.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the upload is unknown, any expected chunk is
+    /// missing or has the wrong length, the final file already exists, or the
+    /// assembled file cannot be written and renamed.
+    pub async fn complete_upload(
+        &self,
+        upload_id: &str,
+    ) -> Result<CompleteUploadResponse, StorageError> {
+        let meta = self.load_meta(upload_id).await?;
+
+        self.verify_all_chunks(&meta).await?;
+
+        let final_path = self.complete_dir().join(&meta.safe_name);
+        if fs::try_exists(&final_path).await? {
+            return Err(StorageError::Conflict("complete file already exists"));
+        }
+
+        let tmp_path = self
+            .complete_dir()
+            .join(format!(".{}.{}.tmp", meta.safe_name, meta.id));
+        if fs::try_exists(&tmp_path).await? {
+            fs::remove_file(&tmp_path).await?;
+        }
+
+        let mut output = fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&tmp_path)
+            .await?;
+
+        for index in 0..meta.total_chunks {
+            let bytes = fs::read(self.chunk_path(upload_id, index)).await?;
+            output.write_all(&bytes).await?;
+        }
+
+        output.flush().await?;
+        drop(output);
+
+        fs::rename(&tmp_path, &final_path).await?;
+
+        Ok(meta.complete_response(final_path.display().to_string()))
+    }
+
     #[must_use]
     pub fn data_dir(&self) -> &Path {
         &self.data_dir
@@ -190,10 +238,26 @@ impl Storage {
 
         Ok(completed)
     }
+
+    async fn verify_all_chunks(&self, meta: &UploadMeta) -> Result<(), StorageError> {
+        for index in 0..meta.total_chunks {
+            let expected_len = expected_chunk_len(meta, index)?;
+            let actual_len = file_len(&self.chunk_path(&meta.id, index)).await?;
+
+            if actual_len != Some(expected_len) {
+                return Err(StorageError::Conflict(
+                    "upload is missing one or more complete chunks",
+                ));
+            }
+        }
+
+        Ok(())
+    }
 }
 
 #[derive(Debug)]
 pub enum StorageError {
+    Conflict(&'static str),
     Format(time::error::Format),
     IdCollision,
     InvalidInput(&'static str),
@@ -212,6 +276,11 @@ impl StorageError {
     pub fn is_not_found(&self) -> bool {
         matches!(self, Self::NotFound)
     }
+
+    #[must_use]
+    pub fn is_conflict(&self) -> bool {
+        matches!(self, Self::Conflict(_))
+    }
 }
 
 impl Display for StorageError {
@@ -219,7 +288,7 @@ impl Display for StorageError {
         match self {
             Self::Format(error) => write!(formatter, "failed to format timestamp: {error}"),
             Self::IdCollision => formatter.write_str("could not allocate a unique upload id"),
-            Self::InvalidInput(message) => formatter.write_str(message),
+            Self::Conflict(message) | Self::InvalidInput(message) => formatter.write_str(message),
             Self::Io(error) => write!(formatter, "storage I/O error: {error}"),
             Self::Json(error) => write!(formatter, "metadata JSON error: {error}"),
             Self::NotFound => formatter.write_str("upload not found"),
@@ -233,7 +302,7 @@ impl Error for StorageError {
             Self::Format(error) => Some(error),
             Self::Io(error) => Some(error),
             Self::Json(error) => Some(error),
-            Self::IdCollision | Self::InvalidInput(_) | Self::NotFound => None,
+            Self::Conflict(_) | Self::IdCollision | Self::InvalidInput(_) | Self::NotFound => None,
         }
     }
 }