core/org.http4s/org.http4s.multipart/MultipartReceiver

MultipartReceiver

org.http4s.multipart.MultipartReceiver

See theMultipartReceiver companion object

Composable logic for receiving data from multipart/form-data request bodies.

A MultipartReceiver works by delegating to a PartReceiver for each Part in the body. It may or may not use the same PartReceiver for each Part. The results from each Part are collected to a List[Partial] (where Partial is an abstract type significant to the specific MultipartReceiver instance), then post-processed into a final result of type A.

For the simplest use-cases, MultipartReceiver.auto will suffice. However, MultipartReceiver is designed for customizability and control over how each Part is handled as its data is received.

MultipartReceiver is Applicative in type F, allowing receiver logic to be defined for one field at a time, then compose the logic for each field into a single receiver. You can define single-field receivers with the DSL starting at MultipartReceiver.at. For example:

case class Nominee(name: String, age: Int, accolades: List[String], photo: fs2.io.file.Path)

val nomineeReceiver: MultipartReceiver[IO, Nominee] = (
 MultipartReceiver.at("name", PartReceiver.bodyText[IO].withSizeLimit(256)).once,
 MultipartReceiver.at("age", PartReceiver.decode[IO, Int].withSizeLimit(8)).once,
 MultipartReceiver.at("accolades", PartReceiver.bodyText[IO].withSizeLimit(1024)).asList,
 MultipartReceiver.at("photo", PartReceiver.toTempFile[IO].withSizeLimit(2 * 1024 * 1024)).once,
).mapN(Nominee.apply)

val nomineeDecoderRes: Resource[IO, EntityDecoder[IO, Nominee]] =
 MultipartDecoder.fromReceiver(nomineeReceiver)

When used to construct an EntityDecoder via MultipartDecoder.fromReceiver, the result is expressed as a Resource. This allows the MultipartReceiver to allocate resources (like temp files) whose lifetimes are tied to the decoder resource. I.e.

nomineeDecoderRes.use { nomineeDecoder =>
 nomineeDecoder
   .decode(request, strict = false) // <- may allocate temp files
} // <- temp files deleted on release

Type parameters

A: The result type
F: The effect type

Attributes

Companion: object
Source: MultipartReceiver.scala
Graph
Supertypes: class Object

trait Matchable

class Any
Self type: MultipartReceiver[F, A]

Members list

Type members

Types

Common supertype for the values decoded from each received part.

Attributes

Source: MultipartReceiver.scala

Value members

Abstract methods

At the end of the decoding process, assemble a final result from the individual part-decode results that were returned by the decide method for each part.

Value parameters

partials: A list of decoded results as returned by the decide method for each part

Attributes

Returns: Right to indicate a successful result, or Left if something went wrong
Source: MultipartReceiver.scala

Upon encountering the Headers for a new part, decide how (if at all) to handle the body of that part.

Return a PartReceiver wrapped in Some to use that receiver to decode the body of the part.

Return None to indicate the part is unexpected. By default, this will result in a decode error upon encountering an unexpected part, but by calling ignoreUnexpectedParts you can create a MultipartReceiver that instead discards the body of any unexpected parts, without raising an error.