pub async fn read_content<T, B, S>(
request: &mut Request<B>,
store: &mut S,
cancellation: &Cancellation,
) -> Result<Accepted<T, S::Handle>, ReadError<B::Error, S::Error>>Expand description
Read a request’s content into the struct T declares, streaming its uploads to store, with the default ReadOptions.
The format is chosen by the request’s Content-Type. A request whose length, from its body or its Content-Length, exceeds the largest body T could need in that format is refused with ReadErrorKind::ContentTooLarge before any of its body is read; a request without a known length is refused as soon as its body exceeds it. The body is read as it arrives, retaining only what the parser has not yet consumed, and each upload is streamed to store as it arrives.
When the content is refused, or reading or storing fails, the upload still arriving is aborted and every upload stored so far is removed, without cancellation, before the error is returned; any failures to remove them are in ReadError::cleanup. When reading stops before the body’s end, the body is closed. The content is accepted exactly when ContentParser::finish accepts it, so a body that fails after the content is complete, in a multipart epilogue, still yields it. Accepted content holds its uploads’ handles, which belong to the application, as do those in Accepted::discarded, which later uploads for the same fields replaced; remove those with UploadStore::remove if they are not wanted.
Cleanup is asynchronous, so dropping the returned future before it completes skips it, and leaves everything it stored in place. To stop a read yourself, give it a child of the handler’s cancellation, from Cancellation::child, and cancel that: the body’s read and the store’s operations observe it, and the future, awaited, then cleans up. base-http-server drops a handler’s future when the server’s cancellation fires, at shutdown, so a read in progress then leaves everything it stored, and a handler still running leaves the uploads it accepted. Stage uploads in a directory the application clears when it starts, and move accepted uploads out of it. A client cannot make the server drop a handler, since its disconnection reaches the read as a body failure, which is cleaned up, but a client that stalls keeps its read in progress until shutdown.