actix_multipart/lib.rs
1//! Multipart request & form support for Actix Web.
2//!
3//! The [`Multipart`] extractor aims to support all kinds of `multipart/*` requests, including
4//! `multipart/form-data`, `multipart/related` and `multipart/mixed`. This is a lower-level
5//! extractor which supports reading [multipart fields](Field), in the order they are sent by the
6//! client.
7//!
8//! Due to additional requirements for `multipart/form-data` requests, the higher level
9//! [`MultipartForm`] extractor and derive macro only supports this media type.
10//!
11//! # Examples
12//!
13//! ```no_run
14//! use actix_web::{post, App, HttpServer, Responder};
15//!
16//! use actix_multipart::form::{json::Json as MpJson, tempfile::TempFile, MultipartForm, MultipartFormConfig};
17//! use serde::Deserialize;
18//!
19//! #[derive(Debug, Deserialize)]
20//! struct Metadata {
21//! name: String,
22//! }
23//!
24//! #[derive(Debug, MultipartForm)]
25//! struct UploadForm {
26//! // Note: the form is also subject to the global limits configured using `MultipartFormConfig`.
27//! #[multipart(limit = "100MB")]
28//! file: TempFile,
29//! json: MpJson<Metadata>,
30//! }
31//!
32//! #[post("/videos")]
33//! pub async fn post_video(MultipartForm(form): MultipartForm<UploadForm>) -> impl Responder {
34//! format!(
35//! "Uploaded file {}, with size: {}",
36//! form.json.name, form.file.size
37//! )
38//! }
39//!
40//! #[actix_web::main]
41//! async fn main() -> std::io::Result<()> {
42//! HttpServer::new(move || {
43//! App::new()
44//! .service(post_video)
45//! // Also increase the global total limit to 100MiB.
46//! .app_data(MultipartFormConfig::default().total_limit(100 * 1024 * 1024))
47//! })
48//! .bind(("127.0.0.1", 8080))?
49//! .run()
50//! .await
51//! }
52//! ```
53//!
54//! cURL request:
55//!
56//! ```sh
57//! curl -v --request POST \
58//! --url http://localhost:8080/videos \
59//! -F 'json={"name": "Cargo.lock"};type=application/json' \
60//! -F file=@./Cargo.lock
61//! ```
62//!
63//! [`MultipartForm`]: struct@form::MultipartForm
64
65#![doc(html_logo_url = "https://actix.rs/img/logo.png")]
66#![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
67#![cfg_attr(docsrs, feature(doc_cfg))]
68
69// This allows us to use the actix_multipart_derive within this crate's tests
70#[cfg(test)]
71extern crate self as actix_multipart;
72
73mod error;
74mod extractor;
75pub(crate) mod field;
76pub mod form;
77mod multipart;
78pub(crate) mod payload;
79pub(crate) mod safety;
80pub mod test;
81
82pub use self::{
83 error::Error as MultipartError,
84 field::{Field, LimitExceeded},
85 multipart::{Multipart, MultipartConfig},
86};