|
1 | 1 | # File Uploads |
2 | 2 |
|
3 | | -Handling file uploads efficiently is crucial. RustAPI allows you to stream `Multipart` data, meaning you can handle 1GB uploads without using 1GB of RAM. |
| 3 | +Handling file uploads efficiently is crucial for modern applications. RustAPI provides a `Multipart` extractor that allows you to stream uploads, enabling you to handle large files (e.g., 1GB+) without consuming proportional RAM. |
4 | 4 |
|
5 | 5 | ## Dependencies |
6 | 6 |
|
| 7 | +Add `uuid` and `tokio` with `fs` features to your `Cargo.toml`. |
| 8 | + |
7 | 9 | ```toml |
8 | 10 | [dependencies] |
9 | 11 | rustapi-rs = "0.1.335" |
10 | 12 | tokio = { version = "1", features = ["fs", "io-util"] } |
11 | 13 | uuid = { version = "1", features = ["v4"] } |
12 | 14 | ``` |
13 | 15 |
|
14 | | -## Streaming Upload Handler |
| 16 | +## Streaming Upload Example |
15 | 17 |
|
16 | | -This handler reads the incoming stream part-by-part and writes it directly to disk (or S3). |
| 18 | +Here is a complete, runnable example of a file upload server that streams files to a `./uploads` directory. |
17 | 19 |
|
18 | 20 | ```rust |
19 | 21 | use rustapi_rs::prelude::*; |
20 | | -use rustapi_rs::extract::Multipart; |
| 22 | +use rustapi_rs::extract::{Multipart, DefaultBodyLimit}; |
21 | 23 | use tokio::fs::File; |
22 | 24 | use tokio::io::AsyncWriteExt; |
| 25 | +use std::path::Path; |
| 26 | + |
| 27 | +#[tokio::main] |
| 28 | +async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> { |
| 29 | + // Ensure uploads directory exists |
| 30 | + tokio::fs::create_dir_all("./uploads").await?; |
| 31 | + |
| 32 | + println!("Starting Upload Server at http://127.0.0.1:8080"); |
| 33 | + |
| 34 | + RustApi::new() |
| 35 | + .route("/upload", post(upload_handler)) |
| 36 | + // Increase body limit to 1GB (default is usually 2MB) |
| 37 | + .layer(DefaultBodyLimit::max(1024 * 1024 * 1024)) |
| 38 | + .run("127.0.0.1:8080") |
| 39 | + .await |
| 40 | +} |
23 | 41 |
|
24 | | -async fn upload_file(mut multipart: Multipart) -> Result<StatusCode, ApiError> { |
25 | | - // Iterate over the fields |
26 | | - while let Some(field) = multipart.next_field().await.map_err(|_| ApiError::BadRequest)? { |
| 42 | +async fn upload_handler(mut multipart: Multipart) -> Result<Json<UploadResponse>> { |
| 43 | + let mut uploaded_files = Vec::new(); |
| 44 | + |
| 45 | + // Iterate over the fields in the multipart form |
| 46 | + while let Some(mut field) = multipart.next_field().await.map_err(|_| ApiError::bad_request("Invalid multipart"))? { |
27 | 47 |
|
28 | | - let name = field.name().unwrap_or("file").to_string(); |
29 | 48 | let file_name = field.file_name().unwrap_or("unknown.bin").to_string(); |
30 | 49 | let content_type = field.content_type().unwrap_or("application/octet-stream").to_string(); |
31 | 50 |
|
32 | | - println!("Uploading: {} ({})", file_name, content_type); |
| 51 | + // ⚠️ Security: Never trust the user-provided filename directly! |
| 52 | + // It could contain paths like "../../../etc/passwd". |
| 53 | + // Always generate a safe filename or sanitize inputs. |
| 54 | + let safe_filename = format!("{}-{}", uuid::Uuid::new_v4(), file_name); |
| 55 | + let path = Path::new("./uploads").join(&safe_filename); |
33 | 56 |
|
34 | | - // Security: Create a safe random filename to prevent overwrites or path traversal |
35 | | - let new_filename = format!("{}-{}", uuid::Uuid::new_v4(), file_name); |
36 | | - let path = std::path::Path::new("./uploads").join(new_filename); |
| 57 | + println!("Streaming file: {} -> {:?}", file_name, path); |
37 | 58 |
|
38 | 59 | // Open destination file |
39 | | - let mut file = File::create(&path).await.map_err(|e| ApiError::InternalServerError(e.to_string()))?; |
| 60 | + let mut file = File::create(&path).await.map_err(|e| ApiError::internal(e.to_string()))?; |
40 | 61 |
|
41 | | - // Write stream to file chunk by chunk |
42 | | - // In RustAPI/Axum multipart, `field.bytes()` loads the whole field into memory. |
43 | | - // To stream efficiently, we use `field.chunk()`: |
44 | | - |
45 | | - while let Some(chunk) = field.chunk().await.map_err(|_| ApiError::BadRequest)? { |
46 | | - file.write_all(&chunk).await.map_err(|e| ApiError::InternalServerError(e.to_string()))?; |
| 62 | + // Stream the field content chunk-by-chunk |
| 63 | + // This is memory efficient even for large files. |
| 64 | + while let Some(chunk) = field.chunk().await.map_err(|_| ApiError::bad_request("Stream error"))? { |
| 65 | + file.write_all(&chunk).await.map_err(|e| ApiError::internal(e.to_string()))?; |
47 | 66 | } |
| 67 | + |
| 68 | + uploaded_files.push(FileResult { |
| 69 | + original_name: file_name, |
| 70 | + stored_name: safe_filename, |
| 71 | + content_type, |
| 72 | + }); |
48 | 73 | } |
49 | 74 |
|
50 | | - Ok(StatusCode::CREATED) |
| 75 | + Ok(Json(UploadResponse { |
| 76 | + message: "Upload successful".into(), |
| 77 | + files: uploaded_files, |
| 78 | + })) |
| 79 | +} |
| 80 | + |
| 81 | +#[derive(Serialize, Schema)] |
| 82 | +struct UploadResponse { |
| 83 | + message: String, |
| 84 | + files: Vec<FileResult>, |
| 85 | +} |
| 86 | + |
| 87 | +#[derive(Serialize, Schema)] |
| 88 | +struct FileResult { |
| 89 | + original_name: String, |
| 90 | + stored_name: String, |
| 91 | + content_type: String, |
51 | 92 | } |
52 | 93 | ``` |
53 | 94 |
|
54 | | -## Handling Constraints |
| 95 | +## Key Concepts |
55 | 96 |
|
56 | | -You should always set limits to prevent DoS attacks. |
| 97 | +### 1. Streaming vs Buffering |
| 98 | +By default, some frameworks load the entire file into RAM. RustAPI's `Multipart` allows you to process the stream incrementally using `field.chunk()`. |
| 99 | +- **Buffering**: `field.bytes().await` (Load all into RAM - simple but dangerous for large files) |
| 100 | +- **Streaming**: `field.chunk().await` (Load small chunks - scalable) |
57 | 101 |
|
58 | | -```rust |
59 | | -use rustapi_rs::extract::DefaultBodyLimit; |
| 102 | +### 2. Body Limits |
| 103 | +The default request body limit is often small (e.g., 2MB) to prevent DoS attacks. You must explicitly increase this limit for file upload routes using `DefaultBodyLimit::max(size)`. |
60 | 104 |
|
61 | | -let app = RustApi::new() |
62 | | - .route("/upload", post(upload_file)) |
63 | | - // Limit request body to 10MB |
64 | | - .layer(DefaultBodyLimit::max(10 * 1024 * 1024)); |
65 | | -``` |
| 105 | +### 3. Security |
| 106 | +- **Path Traversal**: Malicious users can send filenames like `../../system32/cmd.exe`. Always rename files or sanitize filenames strictly. |
| 107 | +- **Content Type Validation**: The `Content-Type` header is client-controlled and can be spoofed. Do not rely on it for security execution checks (e.g., preventing `.php` execution). |
| 108 | +- **Executable Permissions**: Store uploads in a directory where script execution is disabled. |
66 | 109 |
|
67 | | -## Validating Content Type |
| 110 | +## Testing with cURL |
68 | 111 |
|
69 | | -Never trust the `Content-Type` header sent by the client implicitly for security (e.g., executing a PHP script uploaded as an image). |
| 112 | +You can test this endpoint using `curl`: |
70 | 113 |
|
71 | | -Verify the "magic bytes" of the file content itself if strictly needed, or ensure uploaded files are stored in a non-executable directory (or S3 bucket). |
| 114 | +```bash |
| 115 | +curl -X POST http://localhost:8080/upload \ |
| 116 | + -F "file1=@./image.png" \ |
| 117 | + -F "file2=@./document.pdf" |
| 118 | +``` |
72 | 119 |
|
73 | | -```rust |
74 | | -// Simple check on the header (not fully secure but good UX) |
75 | | -if let Some(ct) = field.content_type() { |
76 | | - if !ct.starts_with("image/") { |
77 | | - return Err(ApiError::BadRequest("Only images are allowed".into())); |
78 | | - } |
| 120 | +Response: |
| 121 | +```json |
| 122 | +{ |
| 123 | + "message": "Upload successful", |
| 124 | + "files": [ |
| 125 | + { |
| 126 | + "original_name": "image.png", |
| 127 | + "stored_name": "550e8400-e29b-41d4-a716-446655440000-image.png", |
| 128 | + "content_type": "image/png" |
| 129 | + }, |
| 130 | + ... |
| 131 | + ] |
79 | 132 | } |
80 | 133 | ``` |
0 commit comments