Support Multipart Forms

Currently I cannot find any support for sending multipart Form data (multipart/form-data), It would be great If that was possible.

[johan-bjareholt]

It's quite easy to do youself, just:

1. generate a random boundary
2. Set HTTP content type header with said boundary like this "multipart/form-data; boundary={}"
3. For each part, loop this to create the HTTP body
   • write start delimiter --BOUNDARY
   • write "Content-Disposition" header and other optional HTTP headers for this specific part
   • write \r\n\r\n to end header section
   • write part body
   • write \r\n
4. Write ending boundary --BOUNDARY--

I have done this, but it is unfortunately not open source and has multiple very specific details that only fits my rare use-case so it's not really suitable for upstreaming.

[algesten]

This needs doing for ureq 3.x as well. Let's study the API in reqwest (and others?). Maybe behind a feature flag depending on how messy it becomes.

Help wanted.

[TristanWasTaken]

Let's study the API in reqwest (and others?)

• https://docs.rs/reqwest/latest/reqwest/multipart/index.html
• https://docs.rs/reqwest/latest/reqwest/blocking/multipart/index.html

#120 (comment)

I like that reqwest accepts multiple input types (reader, bytes) and not just a reader.

[algesten]

Yeah. That's neat. We should be able to reuse the AsSendBody trait for that.

[gmacon]

I ran into this today, and tonight took a stab at moving part of the implementation from the now-unmaintaned multipart crate (since it is compatibly licensed) into ureq. My work in progress is at https://github.com/gmacon/ureq/tree/multipart, but there's something wrong with the content-length calculations, and I don't feel like debugging it tonight.

[algesten]

Looks good. I skimmed the code, and two things popped out.

1. Cows 🐮 in public interfaces. This is a type I don't want to subject ureq's users to. Generally the philosophy of ureq is to make the API as accommodating to new user's of Rust as possible. From a high level view, I don't see what Cow give us here. It looks like the entire built multipart could have lifetimes and accept never being 'static, but I might be missing something.
2. Use AsSendBody – we don't need a new function to send these bodies. Once constructed, it should fit in to the "general" body handling.

[algesten]

I'm also interested in looking at reqwest's API here, because it looks very neat in the examples.

[gmacon]

I can definitely look at those things; this started as an experiment to see if it was worth trying to use this existing code as a base. I think we do need a separate function, parallel to send_form, in order to set up the Content-Length and Content-Type headers, unless there's something I missed...

[gmacon]

OK, I have found and fixed the bug, so the example is now working!

I started thinking about how to make the API more like reqwest's. Here's my current thinking:

1. Rename Multipart to Form.
2. Change field names to Into<Cow<'static, str>>, matching reqwest. The benefit of using a Cow here is that it allows the Form to take ownership of a temporary String that would otherwise not live long enough. For example: form.add_text(format!("..."), ...) works with Cow, but using &str would require the caller to save the formatted result into a local variable. Though Cow appears in the API, the caller should never need to create one themselves; that will happen inside the function when name.into() is called. Changing to 'static gets rid of the 'n lifetime parameter.
3. Change to eager checking for existence of files. (This gets rid of LazyError and IntoCowPath.)
4. Change SendBody to track the size of the body in more cases (at least supporting File and &File).
5. Use AsSendBody as the trait bound on the data for add_stream.
6. Implement AsSendBody for the renamed Form. The implementation will parallel the current prepare, but the PreparedFields type (and subtypes) will become crate-private. After <Form as AsSendBody>::as_body returns, the Form will be empty.
7. I currently intend to keep send_multipart_form to set Content-Type: multipart/form-data; boundary="..." on the request, parallel to send_form, which sets Content-Type: application/x-www-form-urlencoded.