| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Servant.Multipart
Description
multipart/form-data support for servant.
This is mostly useful for adding file upload support to
an API. See haddocks of MultipartForm for an introduction.
- data MultipartForm a
- data MultipartData = MultipartData {}
- class FromMultipart a where
- lookupInput :: Text -> MultipartData -> Maybe Text
- lookupFile :: Text -> MultipartData -> Maybe FileData
- data MultipartOptions = MultipartOptions {}
- defaultMultipartOptions :: MultipartOptions
- data TmpBackendOptions = TmpBackendOptions {
- getTmpDir :: IO FilePath
- filenamePat :: String
- defaultTmpBackendOptions :: TmpBackendOptions
- data Input = Input {}
- data FileData = FileData {
- fdInputName :: Text
- fdFileName :: Text
- fdFileCType :: Text
- fdFilePath :: FilePath
Documentation
data MultipartForm a Source #
Combinator for specifying a multipart/form-data request
body, typically (but not always) issued from an HTML <form>.
multipart/form-data can't be made into an ordinary content
type for now in servant because it doesn't just decode the
request body from some format but also performs IO in the case
of writing the uploaded files to disk, e.g in /tmp, which is
not compatible with servant's vision of a content type as things
stand now. This also means that MultipartForm can't be used in
conjunction with ReqBody in an endpoint.
The a type parameter represents the Haskell type to which
you are going to decode the multipart data to, where the
multipart data consists in all the usual form inputs along
with the files sent along through <input type="file">
fields in the form.
One option provided out of the box by this library is to decode
to MultipartData.
Example:
type API = MultipartForm MultipartData :> Post '[PlainText] String
api :: Proxy API
api = Proxy
server :: MultipartData -> Handler String
server multipartData = return str
where str = "The form was submitted with "
++ show nInputs ++ " textual inputs and "
++ show nFiles ++ " files."
nInputs = length (inputs multipartData)
nFiles = length (files multipartData)
You can alternatively provide a FromMultipart instance
for some type of yours, allowing you to regroup data
into a structured form and potentially selecting
a subset of the entire form data that was submitted.
Example, where we only look extract one input, username, and one file, where the corresponding input field's name attribute was set to pic:
data User = User { username :: Text, pic :: FilePath }
instance FromMultipart User where
fromMultipart multipartData =
User <$> lookupInput "username" multipartData
<*> fmap fileContent (lookupFile "pic" multipartData)
type API = MultipartForm User :> Post '[PlainText] String
server :: User -> Handler String
server usr = return str
where str = username usr ++ "'s profile picture"
++ " got temporarily uploaded to "
++ pic usr ++ " and will be removed from there "
++ " after this handler has run."
Note that the behavior of this combinator is configurable,
by using serveWith from servant-server instead of serve,
which takes an additional Context argument. It simply is an
heterogeneous list where you can for example store
a value of type MultipartOptions that has the configuration that
you want, which would then get picked up by servant-multipart.
Important: as mentionned in the example above, the file paths point to temporary files which get removed after your handler has run, if they are still there. It is therefore recommended to move or copy them somewhere in your handler code if you need to keep the content around.
Instances
| HasLink * sub => HasLink * ((:>) * * (MultipartForm a) sub) Source # | |
| (FromMultipart a, LookupContext config MultipartOptions, HasServer * sublayout config) => HasServer * ((:>) * * (MultipartForm a) sublayout) config Source # | Upon seeing |
| type MkLink * ((:>) * * (MultipartForm a) sub) Source # | |
| type ServerT * ((:>) * * (MultipartForm a) sublayout) m Source # | |
data MultipartData Source #
What servant gets out of a multipart/form-data form submission.
The inputs field contains a list of textual Inputs, where
each input for which a value is provided gets to be in this list,
represented by the input name and the input value. See haddocks for
Input.
The files field contains a list of files that were sent along with the
other inputs in the form. Each file is represented by a value of type
FileData which among other things contains the path to the temporary file
(to be removed when your handler is done running) with a given uploaded
file's content. See haddocks for FileData.
Constructors
| MultipartData | |
Instances
class FromMultipart a where Source #
MultipartData is the type representing
multipart/form-data form inputs. Sometimes
you may instead want to work with a more structured type
of yours that potentially selects only a fraction of
the data that was submitted, or just reshapes it to make
it easier to work with. The FromMultipart class is exactly
what allows you to tell servant how to turn "raw" multipart
data into a value of your nicer type.
data User = User { username :: Text, pic :: FilePath }
instance FromMultipart User where
fromMultipart form =
User <$> lookupInput "username" (inputs form)
<*> fmap fdFilePath (lookupFile "pic" $ files form)
Minimal complete definition
Methods
fromMultipart :: MultipartData -> Maybe a Source #
Given a value of type MultipartData, which consists
in a list of textual inputs and another list for
files, try to extract a value of type a. When
extraction fails, servant errors out with status code 400.
Instances
lookupInput :: Text -> MultipartData -> Maybe Text Source #
Lookup a textual input with the given name attribute.
lookupFile :: Text -> MultipartData -> Maybe FileData Source #
Lookup a file input with the given name attribute.
data MultipartOptions Source #
Global options for configuring how the server should handle multipart data.
generalOptions lets you specify mostly multipart parsing
related options, such as the maximum file size, while
tmpOptions lets you configure aspects specific to
the temporary file backend. See haddocks for
ParseRequestBodyOptions and TmpBackendOptions respectively
for more information on what you can tweak.
Constructors
| MultipartOptions | |
defaultMultipartOptions :: MultipartOptions Source #
Default configuration for multipart handling.
Uses defaultParseRequestBodyOptions and
defaultTmpBackendOptions respectively.
data TmpBackendOptions Source #
Configuration for the temporary file based backend.
You can configure the way servant-multipart gets its hands
on a temporary directory (defaults to getTemporaryDirectory)
as well as the filename pattern used for generating the temporary files
(defaults to calling them servant-multipartXXX.buf, where XXX is some
random number).
Constructors
| TmpBackendOptions | |
Fields
| |
defaultTmpBackendOptions :: TmpBackendOptions Source #
Default options for the temporary file backend:
getTemporaryDirectory and "servant-multipart.buf"
Representation for a textual input (any <input> type but file).
<input name="foo" value="bar" /> would appear as Input "foo" "bar"
Constructors
| Input | |
Representation for an uploaded file, usually resulting from
picking a local file for an HTML input that looks like
<input type="file" name="somefile" />.
Constructors
| FileData | |
Fields
| |