File Uploads

21 min read

Quick Overview

A file upload is just an HTTP POST whose body is encoded as multipart/form-data: a sequence of named parts, each of which is either a plain form field or a file with a filename and content type. In Express you almost always reach for multer to parse that body and hand you req.file/req.files; in Axum the Multipart extractor (an opt-in feature) gives you an async stream of parts that you consume one field at a time. The big practical difference is that Axum lets you stream each file straight to disk without ever buffering the whole thing in memory, which matters once uploads get large.

Note: The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. This page targets axum 0.8 (axum::serve + tokio::net::TcpListener, {id} path captures — not the old :id). For the request body in general (Json, raw Bytes) see Request and Response Handling; for the extractor model that Multipart plugs into see Extractors. Serving the files you save back out is covered in Static Files.

TypeScript/JavaScript Example

A realistic Express upload endpoint using multer (npm i multer, currently 2.x). It accepts an avatar image plus a text field, validates the MIME type, caps the size, and writes the file to disk with a generated name.

1
// uploads.ts — Express 5 + multer 2.x
2
import express, { Request, Response } from "express";
3
import multer from "multer";
4
import { randomUUID } from "node:crypto";
5
import path from "node:path";
6

7
const UPLOAD_DIR = "/var/app/uploads";
8
const ALLOWED = new Set(["image/png", "image/jpeg", "image/webp"]);
9

10
// multer streams the part to disk; `storage` controls the destination + name.
11
const storage = multer.diskStorage({
12
  destination: (_req, _file, cb) => cb(null, UPLOAD_DIR),
13
  filename: (_req, file, cb) =>
14
    cb(null, `${randomUUID()}${path.extname(file.originalname)}`),
15
});
16

17
const upload = multer({
18
  storage,
19
  limits: { fileSize: 5 * 1024 * 1024 }, // 5 MiB
20
  fileFilter: (_req, file, cb) => {
21
    if (!ALLOWED.has(file.mimetype)) {
22
      cb(new Error(`content type ${file.mimetype} not allowed`));
23
    } else {
24
      cb(null, true);
25
    }
26
  },
27
});
28

29
const app = express();
30

31
// `upload.single("avatar")` parses ONE file field named "avatar".
32
app.post(
33
  "/users/:id/avatar",
34
  upload.single("avatar"),
35
  (req: Request, res: Response) => {
36
    if (!req.file) {
37
      return res.status(400).json({ error: "no file field named `avatar`" });
38
    }
39
    // Plain text fields land on req.body (parsed by multer, not express.json()).
40
    const caption = (req.body.caption as string) ?? "";
41
    res.status(201).json({
42
      id: path.basename(req.file.filename),
43
      bytes: req.file.size,
44
      contentType: req.file.mimetype,
45
      caption,
46
    });
47
  },
48
);
49

50
// multer errors (e.g. LIMIT_FILE_SIZE, or a fileFilter rejection) arrive here.
51
app.use((err: Error, _req: Request, res: Response, _next: express.NextFunction) => {
52
  res.status(400).json({ error: err.message });
53
});
54

55
app.listen(3000);

Two things are worth pinning down because they map directly to the Rust version:

multer does the buffering/streaming and the field parsing for you; your handler only sees the result (req.file, req.body).
The size limit and MIME filter are configured declaratively, and a violation surfaces as a thrown error that your error middleware turns into a response.

Note: express.json() does not parse multipart/form-data. If you forget multer (or busboy), req.body is empty and req.file is undefined — a classic “why is my upload empty” bug.

Rust Equivalent

The same endpoint in Axum. Enable the extractor with cargo add axum --features multipart, and add Tokio’s filesystem and stream-bridge helpers:

1
[dependencies]
2
axum = { version = "0.8", features = ["multipart"] }
3
tokio = { version = "1", features = ["full"] }
4
tokio-util = { version = "0.7", features = ["io"] } # StreamReader: Stream -> AsyncRead
5
futures-util = "0.3"                                # TryStreamExt::map_err
6
serde = { version = "1", features = ["derive"] }
7
serde_json = "1"
8
uuid = { version = "1", features = ["v4"] }         # random file names

1
use axum::{
2
    extract::{DefaultBodyLimit, Multipart, State},
3
    http::StatusCode,
4
    response::IntoResponse,
5
    routing::post,
6
    Json, Router,
7
};
8
use futures_util::TryStreamExt;
9
use serde::Serialize;
10
use std::{io, path::PathBuf, sync::Arc};
11
use tokio::io::{AsyncWriteExt, BufWriter};
12
use tokio_util::io::StreamReader;
13

14
#[derive(Clone)]
15
struct AppState {
16
    upload_dir: Arc<PathBuf>,
17
}
18

19
#[derive(Serialize)]
20
struct UploadOk {
21
    id: String,
22
    bytes: u64,
23
    content_type: String,
24
}
25

26
const MAX_BYTES: u64 = 5 * 1024 * 1024; // 5 MiB per file
27
const ALLOWED: [&str; 3] = ["image/png", "image/jpeg", "image/webp"];
28

29
async fn upload_avatar(
30
    State(state): State<AppState>,
31
    mut multipart: Multipart,
32
) -> Result<Json<UploadOk>, (StatusCode, String)> {
33
    // Pull parts off the stream one at a time.
34
    while let Some(field) = multipart
35
        .next_field()
36
        .await
37
        .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))?
38
    {
39
        // Skip everything that is not the "avatar" file field.
40
        if field.name() != Some("avatar") {
41
            continue;
42
        }
43

44
        let content_type = field.content_type().unwrap_or("").to_string();
45
        if !ALLOWED.contains(&content_type.as_str()) {
46
            return Err((
47
                StatusCode::UNSUPPORTED_MEDIA_TYPE,
48
                format!("content type {content_type} not allowed"),
49
            ));
50
        }
51

52
        let id = uuid::Uuid::new_v4().to_string();
53
        let path = state.upload_dir.join(&id);
54

55
        // Stream the body to disk; never hold the whole file in memory.
56
        let bytes = stream_to_file(field, &path)
57
            .await
58
            .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("write failed: {e}")))?;
59

60
        return Ok(Json(UploadOk { id, bytes, content_type }));
61
    }
62

63
    Err((StatusCode::BAD_REQUEST, "no file field named `avatar`".into()))
64
}
65

66
/// Bridge the field's byte stream into an `AsyncRead` and copy it to a file.
67
async fn stream_to_file(
68
    field: axum::extract::multipart::Field<'_>,
69
    path: &std::path::Path,
70
) -> io::Result<u64> {
71
    // A `Field` is a `Stream<Item = Result<Bytes, MultipartError>>`.
72
    // StreamReader needs the error to be `std::io::Error`, so map it first.
73
    let body = field.map_err(io::Error::other);
74
    let mut reader = StreamReader::new(body);
75

76
    let file = tokio::fs::File::create(path).await?;
77
    let mut writer = BufWriter::new(file);
78

79
    let copied = tokio::io::copy(&mut reader, &mut writer).await?;
80
    writer.flush().await?;
81
    Ok(copied)
82
}
83

84
#[tokio::main]
85
async fn main() {
86
    let upload_dir = PathBuf::from("/var/app/uploads");
87
    tokio::fs::create_dir_all(&upload_dir).await.unwrap();
88
    let state = AppState { upload_dir: Arc::new(upload_dir) };
89

90
    let app = Router::new()
91
        .route("/users/{id}/avatar", post(upload_avatar))
92
        // Multipart bodies are NOT covered by the default 2 MiB limit's intent;
93
        // set an explicit ceiling. Keep it above MAX_BYTES (see Common Pitfalls).
94
        .layer(DefaultBodyLimit::max(8 * 1024 * 1024))
95
        .with_state(state);
96

97
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
98
    println!("listening on {}", listener.local_addr().unwrap());
99
    axum::serve(listener, app).await.unwrap();
100
}

Driving it with curl produces real, typed JSON responses:

1
$ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \
2
    -F "avatar=@avatar.png;type=image/png"
3
{"id":"a2c17697-4b96-400f-a4bf-0c29b892e2b5","bytes":4008,"content_type":"image/png"} HTTP 200
4

5
$ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \
6
    -F "avatar=@notes.txt;type=text/plain"
7
content type text/plain not allowed HTTP 415

(The numbers above are genuine output from running this exact code; your UUID and byte count will differ.)

Detailed Explanation

Multipart is an extractor, but a special one. Like Json or Path, it implements the extractor machinery (FromRequest), so you list it as a handler argument and Axum builds it from the request. Unlike Json, it does not read the whole body up front — it hands you a cursor over the parts. Because it consumes the request body, Multipart must be the last argument in your handler (it implements FromRequest, not FromRequestParts). Put State, Path, and header extractors before it. See Extractors for the ordering rule and why only one body-consuming extractor is allowed.

next_field().await walks the parts. Each call returns Result<Option<Field>, MultipartError>:

Ok(Some(field)) — another part is ready.
Ok(None) — the body is exhausted; the loop ends.
Err(_) — the body was malformed or violated a limit.

You must drive this loop in order. A Field borrows the Multipart mutably, so you can only hold one field at a time — you cannot collect them into a Vec and process them later (the borrow checker enforces this; see Common Pitfalls).

Reading a field’s metadata. field.name() is the form field name (the name="..." in the part header), field.file_name() is the client-supplied original filename (present only for file parts), and field.content_type() returns the part’s declared MIME type. All three return Option<&str> — a TS dev should treat them like values that might be undefined, because a malicious or buggy client can omit any of them.

Reading a field’s body — buffered vs. streamed. This is the heart of the page:

field.bytes().await collects the entire part into a Bytes (an in-memory buffer). Convenient for small things (a JSON blob, a thumbnail), dangerous for large uploads — it is the moral equivalent of multer’s memoryStorage.
field.text().await is bytes() plus UTF-8 decoding, for plain text fields.
A Field is itself a Stream of Bytes chunks, so you can stream it. Either pull chunks manually with field.chunk().await (returns Ok(Some(Bytes)) per chunk), or — as above — wrap it in tokio_util::io::StreamReader to turn the Stream into an AsyncRead and tokio::io::copy it into a file. Nothing larger than one chunk (a few KiB) is ever resident in memory.

The map_err(io::Error::other) line. StreamReader requires the stream’s error type to be std::io::Error, but a Field yields MultipartError. TryStreamExt::map_err (from futures-util) converts each error, and io::Error::other wraps any std::error::Error into an io::Error. This adapter is the small bit of glue that connects Axum’s multipart stream to Tokio’s filesystem I/O.

DefaultBodyLimit. Axum applies a default request-body limit (2 MiB). Multipart uploads routinely exceed that, so you set an explicit limit per route or per router with the DefaultBodyLimit layer. This is a coarse, whole-request guard that runs before your handler — it is not the same as a per-file cap (more on that contrast below).

No streaming-vs-buffered footgun in Express. multer’s diskStorage already streams to disk for you, so the Express version doesn’t expose this choice. In Axum the choice is explicit and in your hands — which is more code, but also why you can do things like enforce a byte budget mid-stream or pipe directly to S3 without a temp file.

Key Differences

Concern	Express + multer	Axum + `Multipart`
Parsing the body	Middleware (`multer(...)`) populates `req.file`/`req.body`	`Multipart` extractor yields a `Field` stream you consume
Streaming to disk	`diskStorage` does it implicitly	Explicit: `StreamReader` + `tokio::io::copy`, or `field.chunk()`
Buffer in memory	`memoryStorage` (`req.file.buffer`)	`field.bytes().await`
Field ordering	All fields available after middleware runs	One `Field` at a time, in body order; cannot hold two at once
Size limit	`limits.fileSize` (per file, enforced by multer)	`DefaultBodyLimit` (whole request) + your own per-field counter
MIME validation	`fileFilter` callback	`field.content_type()` check in the loop
Where errors surface	Thrown into error middleware	A `Result` your handler returns, or `MultipartError`’s own response
Memory profile	Configurable, defaults to streaming via `diskStorage`	Streaming by default if you write streaming code

The conceptual shift: multer is a declarative parser you configure once; Axum’s Multipart is an imperative stream you iterate. That costs a few more lines but removes the magic — there is no hidden req.file, only the bytes you chose to read and where you chose to put them.

Tip: The “trust nothing from the client” rules are identical to Express. file_name() can contain ../ or absolute paths; never join it onto a directory unsanitized. The Best Practices section shows the fix.

Common Pitfalls

1. Holding two fields at once (the borrow that won’t compile)

A Field borrows the Multipart mutably, so you cannot fetch a second field while still holding the first:

1
use axum::extract::Multipart;
2

3
async fn bad(mut multipart: Multipart) {
4
    let first = multipart.next_field().await.unwrap().unwrap();
5
    let second = multipart.next_field().await.unwrap().unwrap(); // does not compile (error[E0499])
6
    println!("{:?} {:?}", first.name(), second.name());
7
}

The real compiler error:

1
error[E0499]: cannot borrow `multipart` as mutable more than once at a time
2
 --> examples/bad.rs:5:18
3
  |
4
4 |     let first = multipart.next_field().await.unwrap().unwrap();
5
  |                 --------- first mutable borrow occurs here
6
5 |     let second = multipart.next_field().await.unwrap().unwrap();
7
  |                  ^^^^^^^^^ second mutable borrow occurs here
8
6 |     println!("{:?} {:?}", first.name(), second.name());
9
  |                           ----- first borrow later used here

The fix is to fully process (or copy out) one field — call .bytes()/.text()/stream it — before calling next_field() again. This is by design: it is what makes true streaming possible without buffering everything.

2. Forgetting the `multipart` feature

Multipart does not exist in axum’s default build. Without features = ["multipart"], use axum::extract::Multipart; fails to resolve (error[E0432]: unresolved import). Run cargo add axum --features multipart.

3. `DefaultBodyLimit` set below your per-field cap — and the resulting status

This one is subtle and bites in production. The DefaultBodyLimit layer is a whole-request guard that trips while the stream is being read, surfacing inside your handler as a stream error — not as a clean “too large” you can branch on. If you map every multipart error to 400, an over-limit upload returns 400 with a confusing message:

1
$ curl -s -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/upload-stream \
2
    -F "data=@big.bin"      # body > DefaultBodyLimit
3
malformed multipart: Error parsing `multipart/form-data` request
4
HTTP 400

MultipartError actually carries the correct status itself. If you let ? propagate it (handler returns Result<_, MultipartError>, since MultipartError: IntoResponse), the same request returns the right code:

1
$ curl -s -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/upload-native \
2
    -F "data=@big.bin"
3
Request payload is too large
4
HTTP 413

The practical rule: keep DefaultBodyLimit as a generous outer ceiling, and if you want a precise per-file limit with a clean 413 and partial-file cleanup, count bytes yourself as you stream (shown in the Real-World Example). If your outer limit is smaller than your per-field cap, the outer limit wins and your cap never runs.

4. Calling `field.bytes()` on a huge upload

field.bytes().await allocates the whole part in memory. A handful of concurrent multi-hundred-MB uploads will exhaust RAM. Use it only for fields you know are small; stream everything else.

5. Expecting `Json`/`express.json()`-style parsing

multipart/form-data is not JSON. There is no Json extractor that magically parses it, and (mirroring Express) a JSON body parser will not touch it. Use Multipart, then read text fields with field.text().

Best Practices

Stream large uploads; buffer only small ones. Default to StreamReader + tokio::io::copy (or field.chunk()). Reserve field.bytes() for parts you know are small.
Always sanitize the client filename. Never trust field.file_name(). Generate your own name (a UUID) for storage and treat the original name as untrusted display metadata. If you must keep the original, run it through sanitize-filename (cargo add sanitize-filename):
```
1
// `safe` strips path separators and other dangerous characters.
2
let safe = sanitize_filename::sanitize(field.file_name().unwrap_or("upload"));
```
Validate content type, but don’t trust it. field.content_type() is what the client claimed. For security-sensitive uploads, also sniff the first bytes (e.g. magic numbers) or re-encode images server-side.
Set an explicit DefaultBodyLimit sized to your largest legitimate upload, kept above any per-field cap you enforce in code.
Write to a temp file, then atomically rename into place once the upload completes and validation passes, so partial or rejected uploads never appear as real files.
Clean up on failure. If a per-field cap or validation fails mid-stream, remove_file the partial.
Put filesystem paths and limits in state/config, not hardcoded — inject the upload directory via State<T> (see State Management).
For a clean error type, return your own AppError: IntoResponse instead of (StatusCode, String) tuples once the handler grows. See Error Handling in Web Apps.

Real-World Example

A production-flavored avatar endpoint that ties the practices together: it injects the upload directory via State, validates the MIME type, enforces a precise per-file byte budget while streaming (returning a clean 413 and cleaning up the partial file), and atomically renames a .part temp file into place on success. The custom UploadError maps each failure to the right status code.

1
use axum::{
2
    extract::{DefaultBodyLimit, Multipart, State},
3
    http::StatusCode,
4
    response::IntoResponse,
5
    routing::post,
6
    Json, Router,
7
};
8
use futures_util::TryStreamExt;
9
use serde::Serialize;
10
use std::{io, path::PathBuf, sync::Arc};
11
use tokio::io::{AsyncReadExt, AsyncWriteExt, BufWriter};
12
use tokio_util::io::StreamReader;
13

14
#[derive(Clone)]
15
struct AppState {
16
    upload_dir: Arc<PathBuf>,
17
}
18

19
#[derive(Serialize)]
20
struct UploadOk {
21
    id: String,
22
    bytes: u64,
23
    content_type: String,
24
}
25

26
#[derive(Debug)]
27
enum UploadError {
28
    NoFile,
29
    BadContentType(String),
30
    TooLarge,
31
    Multipart(String),
32
    Io(io::Error),
33
}
34

35
const MAX_BYTES: u64 = 5 * 1024 * 1024; // 5 MiB per file
36
const ALLOWED: [&str; 3] = ["image/png", "image/jpeg", "image/webp"];
37

38
// Each variant maps to a meaningful HTTP status + JSON error body.
39
impl IntoResponse for UploadError {
40
    fn into_response(self) -> axum::response::Response {
41
        let (status, msg) = match self {
42
            UploadError::NoFile => {
43
                (StatusCode::BAD_REQUEST, "no file field named `avatar`".to_string())
44
            }
45
            UploadError::BadContentType(ct) => {
46
                (StatusCode::UNSUPPORTED_MEDIA_TYPE, format!("content type {ct} not allowed"))
47
            }
48
            UploadError::TooLarge => {
49
                (StatusCode::PAYLOAD_TOO_LARGE, format!("file exceeds {MAX_BYTES} bytes"))
50
            }
51
            UploadError::Multipart(e) => (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")),
52
            UploadError::Io(e) => {
53
                (StatusCode::INTERNAL_SERVER_ERROR, format!("could not store file: {e}"))
54
            }
55
        };
56
        (status, Json(serde_json::json!({ "error": msg }))).into_response()
57
    }
58
}
59

60
async fn upload_avatar(
61
    State(state): State<AppState>,
62
    mut multipart: Multipart,
63
) -> Result<Json<UploadOk>, UploadError> {
64
    while let Some(field) = multipart
65
        .next_field()
66
        .await
67
        .map_err(|e| UploadError::Multipart(e.to_string()))?
68
    {
69
        if field.name() != Some("avatar") {
70
            continue;
71
        }
72

73
        let content_type = field.content_type().unwrap_or("").to_string();
74
        if !ALLOWED.contains(&content_type.as_str()) {
75
            return Err(UploadError::BadContentType(content_type));
76
        }
77

78
        let id = uuid::Uuid::new_v4().to_string();
79
        let final_path = state.upload_dir.join(&id);
80
        let tmp_path = state.upload_dir.join(format!("{id}.part"));
81

82
        let written = write_capped(field, &tmp_path).await?;
83

84
        // Only after a clean, fully-written upload do we publish the file.
85
        tokio::fs::rename(&tmp_path, &final_path)
86
            .await
87
            .map_err(UploadError::Io)?;
88

89
        return Ok(Json(UploadOk { id, bytes: written, content_type }));
90
    }
91

92
    Err(UploadError::NoFile)
93
}
94

95
/// Stream a field to `path`, aborting (and deleting the partial) past MAX_BYTES.
96
async fn write_capped(
97
    field: axum::extract::multipart::Field<'_>,
98
    path: &std::path::Path,
99
) -> Result<u64, UploadError> {
100
    let reader = StreamReader::new(field.map_err(io::Error::other));
101
    futures_util::pin_mut!(reader);
102

103
    let file = tokio::fs::File::create(path).await.map_err(UploadError::Io)?;
104
    let mut writer = BufWriter::new(file);
105

106
    let mut buf = vec![0u8; 64 * 1024];
107
    let mut total: u64 = 0;
108
    loop {
109
        let n = reader.read(&mut buf).await.map_err(UploadError::Io)?;
110
        if n == 0 {
111
            break; // EOF: the part is fully read
112
        }
113
        total += n as u64;
114
        if total > MAX_BYTES {
115
            let _ = tokio::fs::remove_file(path).await; // clean up the partial
116
            return Err(UploadError::TooLarge);
117
        }
118
        writer.write_all(&buf[..n]).await.map_err(UploadError::Io)?;
119
    }
120
    writer.flush().await.map_err(UploadError::Io)?;
121
    Ok(total)
122
}
123

124
#[tokio::main]
125
async fn main() {
126
    let upload_dir = PathBuf::from("/var/app/uploads");
127
    tokio::fs::create_dir_all(&upload_dir).await.unwrap();
128
    let state = AppState { upload_dir: Arc::new(upload_dir) };
129

130
    let app = Router::new()
131
        .route("/users/{id}/avatar", post(upload_avatar))
132
        // Generous outer ceiling; the precise per-file cap is enforced in code.
133
        .layer(DefaultBodyLimit::max(50 * 1024 * 1024))
134
        .with_state(state);
135

136
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
137
    println!("listening on {}", listener.local_addr().unwrap());
138
    axum::serve(listener, app).await.unwrap();
139
}

This needs serde_json in addition to the earlier deps: cargo add serde_json. Exercising all three paths against the running server gives real output:

1
$ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \
2
    -F "avatar=@avatar.png;type=image/png"
3
{"id":"a2c17697-4b96-400f-a4bf-0c29b892e2b5","bytes":4008,"content_type":"image/png"} HTTP 200
4

5
$ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \
6
    -F "avatar=@notes.txt;type=text/plain"
7
{"error":"content type text/plain not allowed"} HTTP 415
8

9
$ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \
10
    -F "avatar=@big.png;type=image/png"      # 6 MiB, over the per-file cap
11
{"error":"file exceeds 5242880 bytes"} HTTP 413

After these requests, the upload directory contains exactly one complete file (the valid PNG) and no leftover .part file — the over-limit upload was deleted mid-stream. That cleanup is the payoff of streaming with your own byte counter instead of leaning on field.bytes() or the outer body limit alone.

Note: For very large uploads in real deployments, prefer streaming straight to object storage (S3 multipart upload) or a reverse proxy that buffers to disk, rather than the application server’s local filesystem. The streaming pattern here is exactly what an S3 sink plugs into — replace the File with the storage client’s writer.

Exercises

Exercise 1 — Count and summarize fields

Difficulty: Beginner

Objective: Get comfortable iterating multipart fields and distinguishing file parts from plain text fields.

Instructions: Write a handler summarize(mut multipart: Multipart) that consumes a multipart/form-data body and returns JSON of the form { "text_fields": N, "files": M }, where text fields are parts with no filename and files are parts with one. Read each text field with .text() (you may discard the value) and each file with .bytes() for now. Map any MultipartError to a 400.

Solution

1
use axum::{extract::Multipart, http::StatusCode, Json};
2
use serde::Serialize;
3

4
#[derive(Serialize)]
5
struct Counts {
6
    text_fields: usize,
7
    files: usize,
8
}
9

10
async fn summarize(
11
    mut multipart: Multipart,
12
) -> Result<Json<Counts>, (StatusCode, String)> {
13
    let mut text_fields = 0usize;
14
    let mut files = 0usize;
15

16
    while let Some(field) = multipart
17
        .next_field()
18
        .await
19
        .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))?
20
    {
21
        if field.file_name().is_some() {
22
            // Consume the file body so we can advance to the next field.
23
            field
24
                .bytes()
25
                .await
26
                .map_err(|e| (StatusCode::BAD_REQUEST, format!("read failed: {e}")))?;
27
            files += 1;
28
        } else {
29
            field
30
                .text()
31
                .await
32
                .map_err(|e| (StatusCode::BAD_REQUEST, format!("read failed: {e}")))?;
33
            text_fields += 1;
34
        }
35
    }
36

37
    Ok(Json(Counts { text_fields, files }))
38
}

Mount it with .route("/summarize", axum::routing::post(summarize)). A request with one text field and two files returns {"text_fields":1,"files":2}.

Exercise 2 — Stream to disk with a safe filename

Difficulty: Intermediate

Objective: Stream a single uploaded file to disk without buffering it, using a sanitized, collision-free name.

Instructions: Write save_upload(mut multipart: Multipart) that takes the first file part, builds a storage name of the form <uuid>-<sanitized-original-name>, streams the body to /tmp/uploads/<name> using StreamReader + tokio::io::copy (no .bytes()), and returns JSON { "saved": "<full path>", "bytes": N }. Use cargo add sanitize-filename uuid --features uuid/v4. Skip non-file parts.

Solution

1
use axum::{
2
    extract::Multipart,
3
    http::StatusCode,
4
    Json,
5
};
6
use futures_util::TryStreamExt;
7
use serde::Serialize;
8
use std::{io, path::PathBuf};
9
use tokio::io::AsyncWriteExt;
10
use tokio_util::io::StreamReader;
11

12
#[derive(Serialize)]
13
struct Saved {
14
    saved: String,
15
    bytes: u64,
16
}
17

18
async fn save_upload(
19
    mut multipart: Multipart,
20
) -> Result<Json<Saved>, (StatusCode, String)> {
21
    while let Some(field) = multipart
22
        .next_field()
23
        .await
24
        .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))?
25
    {
26
        let Some(original) = field.file_name().map(|s| s.to_string()) else {
27
            continue; // not a file part
28
        };
29

30
        let safe = sanitize_filename::sanitize(&original);
31
        let id = uuid::Uuid::new_v4();
32
        let path = PathBuf::from("/tmp/uploads").join(format!("{id}-{safe}"));
33

34
        tokio::fs::create_dir_all("/tmp/uploads")
35
            .await
36
            .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
37

38
        let bytes = stream_to_file(field, &path)
39
            .await
40
            .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("write failed: {e}")))?;
41

42
        return Ok(Json(Saved {
43
            saved: path.display().to_string(),
44
            bytes,
45
        }));
46
    }
47

48
    Err((StatusCode::BAD_REQUEST, "no file part found".into()))
49
}
50

51
async fn stream_to_file(
52
    field: axum::extract::multipart::Field<'_>,
53
    path: &std::path::Path,
54
) -> io::Result<u64> {
55
    let mut reader = StreamReader::new(field.map_err(io::Error::other));
56
    let mut file = tokio::fs::File::create(path).await?;
57
    let copied = tokio::io::copy(&mut reader, &mut file).await?;
58
    file.flush().await?;
59
    Ok(copied)
60
}

sanitize_filename::sanitize("../../etc/passwd") becomes "....etcpasswd", and the UUID prefix guarantees no two uploads collide.

Exercise 3 — Per-file size cap returning a clean 413

Difficulty: Advanced

Objective: Enforce a precise per-file byte limit while streaming, returning 413 Payload Too Large with a JSON body and leaving no partial file behind — without relying on DefaultBodyLimit.

Instructions: Implement write_limited(field, path, max: u64) -> Result<u64, UploadError> that streams the field to path chunk by chunk (manually, or via StreamReader + a read loop), tracks the running byte total, and as soon as it exceeds max, deletes the partial file and returns an error variant that your IntoResponse maps to 413. Wire it into a handler whose router uses a generous DefaultBodyLimit (so your cap is the binding constraint). Confirm that an over-cap upload returns 413 and that the directory is empty afterward.

Solution

1
use axum::{
2
    extract::{DefaultBodyLimit, Multipart},
3
    http::StatusCode,
4
    response::IntoResponse,
5
    routing::post,
6
    Json, Router,
7
};
8
use futures_util::TryStreamExt;
9
use serde::Serialize;
10
use std::{io, path::PathBuf};
11
use tokio::io::{AsyncReadExt, AsyncWriteExt, BufWriter};
12
use tokio_util::io::StreamReader;
13

14
const MAX_BYTES: u64 = 1024 * 1024; // 1 MiB
15

16
#[derive(Debug)]
17
enum UploadError {
18
    NoFile,
19
    TooLarge,
20
    Multipart(String),
21
    Io(io::Error),
22
}
23

24
impl IntoResponse for UploadError {
25
    fn into_response(self) -> axum::response::Response {
26
        let (status, msg) = match self {
27
            UploadError::NoFile => (StatusCode::BAD_REQUEST, "no file part".to_string()),
28
            UploadError::TooLarge => {
29
                (StatusCode::PAYLOAD_TOO_LARGE, format!("file exceeds {MAX_BYTES} bytes"))
30
            }
31
            UploadError::Multipart(e) => (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")),
32
            UploadError::Io(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()),
33
        };
34
        (status, Json(serde_json::json!({ "error": msg }))).into_response()
35
    }
36
}
37

38
#[derive(Serialize)]
39
struct Saved {
40
    bytes: u64,
41
}
42

43
async fn upload(mut multipart: Multipart) -> Result<Json<Saved>, UploadError> {
44
    while let Some(field) = multipart
45
        .next_field()
46
        .await
47
        .map_err(|e| UploadError::Multipart(e.to_string()))?
48
    {
49
        if field.file_name().is_none() {
50
            continue;
51
        }
52
        tokio::fs::create_dir_all("/tmp/capped")
53
            .await
54
            .map_err(UploadError::Io)?;
55
        let path = PathBuf::from("/tmp/capped").join(uuid::Uuid::new_v4().to_string());
56
        let bytes = write_limited(field, &path, MAX_BYTES).await?;
57
        return Ok(Json(Saved { bytes }));
58
    }
59
    Err(UploadError::NoFile)
60
}
61

62
async fn write_limited(
63
    field: axum::extract::multipart::Field<'_>,
64
    path: &std::path::Path,
65
    max: u64,
66
) -> Result<u64, UploadError> {
67
    let reader = StreamReader::new(field.map_err(io::Error::other));
68
    futures_util::pin_mut!(reader);
69

70
    let file = tokio::fs::File::create(path).await.map_err(UploadError::Io)?;
71
    let mut writer = BufWriter::new(file);
72

73
    let mut buf = vec![0u8; 64 * 1024];
74
    let mut total: u64 = 0;
75
    loop {
76
        let n = reader.read(&mut buf).await.map_err(UploadError::Io)?;
77
        if n == 0 {
78
            break;
79
        }
80
        total += n as u64;
81
        if total > max {
82
            let _ = tokio::fs::remove_file(path).await;
83
            return Err(UploadError::TooLarge);
84
        }
85
        writer.write_all(&buf[..n]).await.map_err(UploadError::Io)?;
86
    }
87
    writer.flush().await.map_err(UploadError::Io)?;
88
    Ok(total)
89
}
90

91
#[tokio::main]
92
async fn main() {
93
    let app = Router::new()
94
        .route("/upload", post(upload))
95
        .layer(DefaultBodyLimit::max(50 * 1024 * 1024)); // generous outer ceiling
96

97
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
98
    axum::serve(listener, app).await.unwrap();
99
}

Uploading a 2 MiB file returns {"error":"file exceeds 1048576 bytes"} with HTTP 413, and /tmp/capped is left empty because the partial was removed mid-stream. The key design point — and the reason this exercise is “advanced” — is that the outer DefaultBodyLimit is set far above MAX_BYTES, so your in-handler counter is the constraint that actually fires, giving you control over both the status code and the cleanup.

File Uploads

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

1. Holding two fields at once (the borrow that won’t compile)

2. Forgetting the multipart feature

3. DefaultBodyLimit set below your per-field cap — and the resulting status

4. Calling field.bytes() on a huge upload

5. Expecting Json/express.json()-style parsing

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1 — Count and summarize fields

Exercise 2 — Stream to disk with a safe filename

Exercise 3 — Per-file size cap returning a clean 413

2. Forgetting the `multipart` feature

3. `DefaultBodyLimit` set below your per-field cap — and the resulting status

4. Calling `field.bytes()` on a huge upload

5. Expecting `Json`/`express.json()`-style parsing