botserver/docs/platform/guide/file.md

File Upload Service with Actix Web and S3/MinIO

Overview

This service provides a REST API endpoint for uploading files to S3-compatible storage (including MinIO) using Actix Web. It handles multipart form data, temporarily stores files locally, and transfers them to object storage.

BASIC Keywords Reference

• UPLOAD: Handles file uploads via multipart form data
• CONFIG: Manages S3/MinIO configuration and client initialization
• TEMP: Uses temporary files for processing uploads
• CLIENT: Maintains S3 client connection
• ERROR: Comprehensive error handling for upload failures
• BUCKET: Configures and uses S3 buckets for storage
• PATH: Manages folder paths for object organization

API Reference

POST /files/upload/{folder_path}

Uploads a file to the specified folder in S3/MinIO storage.

Path Parameters:

• folder_path (string): Target folder path in S3 bucket

Request:

• Content-Type: multipart/form-data
• Body: File data in multipart format

Response:

• 200 OK: Upload successful
• 500 Internal Server Error: Upload failed

Example:

curl -X POST \
  http://localhost:8080/files/upload/documents \
  -F "file=@report.pdf"

Configuration

DriveConfig Structure

// Example configuration
let config = DriveConfig {
    access_key: "your-access-key".to_string(),
    secret_key: "your-secret-key".to_string(),
    server: "minio.example.com:9000".to_string(),
    s3_bucket: "my-bucket".to_string(),
    use_ssl: false,
};

Client Initialization

use crate::config::DriveConfig;

// Initialize S3 client
let drive_config = DriveConfig {
    access_key: "minioadmin".to_string(),
    secret_key: "minioadmin".to_string(),
    server: "localhost:9000".to_string(),
    s3_bucket: "uploads".to_string(),
    use_ssl: false,
};

let s3_client = init_drive(&drive_config).await?;

Implementation Guide

1. Setting Up AppState

use crate::shared::state::AppState;

// Configure application state with S3 client
let app_state = web::Data::new(AppState {
    s3_client: Some(s3_client),
    config: Some(drive_config),
    // ... other state fields
});

2. Error Handling Patterns

The service implements several error handling strategies:

// Configuration errors
let bucket_name = state.get_ref().config.as_ref()
    .ok_or_else(|| actix_web::error::ErrorInternalServerError(
        "S3 bucket configuration is missing"
    ))?;

// Client initialization errors
let s3_client = state.get_ref().s3_client.as_ref()
    .ok_or_else(|| actix_web::error::ErrorInternalServerError(
        "S3 client is not initialized"
    ))?;

// File operation errors with cleanup
let mut temp_file = NamedTempFile::new().map_err(|e| {
    actix_web::error::ErrorInternalServerError(format!(
        "Failed to create temp file: {}", e
    ))
})?;

3. File Processing Flow

// 1. Create temporary file
let mut temp_file = NamedTempFile::new()?;

// 2. Process multipart data
while let Some(mut field) = payload.try_next().await? {
    // Extract filename from content disposition
    if let Some(disposition) = field.content_disposition() {
        file_name = disposition.get_filename().map(|s| s.to_string());
    }

    // Stream data to temporary file
    while let Some(chunk) = field.try_next().await? {
        temp_file.write_all(&chunk)?;
    }
}

// 3. Upload to S3
upload_to_s3(&s3_client, &bucket_name, &s3_key, &temp_file_path).await?;

// 4. Cleanup temporary file
let _ = std::fs::remove_file(&temp_file_path);

Key Features

Temporary File Management

• Uses NamedTempFile for secure temporary storage
• Automatic cleanup on both success and failure
• Efficient streaming of multipart data

S3/MinIO Compatibility

• Path-style addressing for MinIO compatibility
• Configurable SSL/TLS
• Custom endpoint support

Security Considerations

• Temporary files are automatically deleted
• No persistent storage of uploaded files on server
• Secure credential handling

Error Scenarios

1. Missing Configuration: Returns 500 if S3 bucket or client not configured
2. File System Errors: Handles temp file creation/write failures
3. Network Issues: Manages S3 connection timeouts and errors
4. Invalid Uploads: Handles malformed multipart data

Performance Notes

• Streams data directly from multipart to temporary file
• Uses async operations for I/O-bound tasks
• Minimal memory usage for large file uploads
• Efficient cleanup prevents disk space leaks