webcrank-0.1: Webmachine inspired toolkit for building http applications and services.

Safe HaskellNone
LanguageHaskell98

Webcrank

Contents

Synopsis

Resources

data Resource m Source

A Resource is a dictionary of functions which are used in the Webcrank decision process to determine how requests should be handled.

Each function has a type of either m a or HaltT m a. A resource function which yields a HaltT m a value allows the function to terminate the request processing early using halt or werror.

The defaults documented are used by the resource smart constructor. A resource that responds to GET requests with an HTML response would be written as

myResource = resource { contentTypesProvided = return $ [("text/html", return "Hello world!")] }

responseWithBody and responseWithHtml are additional smart constructors useful creating resources.

Constructors

Resource 

Fields

serviceAvailable :: HaltT m Bool

False will result in 503 Service Unavailable. Defaults to True.

uriTooLong :: HaltT m Bool

True will result in 414 Request Too Long. Defaults to False.

allowedMethods :: m [Method]

If a Method not in this list is requested, then a 405 Method Not Allowed will be sent. Defaults to [GET, HEAD].

malformedRequest :: HaltT m Bool

True will result in 400 Bad Request. Defaults to False.

isAuthorized :: HaltT m Authorized

If Authorized, the response will be 401 Unauthorized. Unauthorized will be used as the challenge in the WWW-Authenticate header, e.g. Basic realm=Webcrank. Defaults to Authorized.

forbidden :: HaltT m Bool

True will result in 403 Forbidden. Defaults to False.

validContentHeaders :: HaltT m Bool

False will result in 501 Not Implemented. Defaults to True.

knownContentType :: HaltT m Bool

False will result in 415 Unsupported Media Type. Defaults to True.

validEntityLength :: HaltT m Bool

False will result in 413 Request Entity Too Large. Defaults to True.

options :: m ResponseHeaders

If the OPTIONS method is supported and is used, the headers that should appear in the response. Defaults to [].

contentTypesProvided :: m [(MediaType, HaltT m Body)]

Content negotiation is driven by this function. For example, if a client request includes an Accept header with a value that does not appear as a MediaType in any of the tuples, then a 406 Not Acceptable will be sent. If there is a matching MediaType, that function is used to create the entity when a response should include one. Defaults to [].

charsetsProvided :: m CharsetsProvided

Used on GET requests to ensure that the entity is in Charset. Defaults to NoCharset.

encodingsProvided :: m [(Encoding, Body -> Body)]

Used on GET requests to ensure that the body is encoded. One useful setting is to have the function check on method, and on GET requests return [("identity", id), ("gzip", compress)] as this is all that is needed to support gzip content encoding. Defaults to [].

resourceExists :: HaltT m Bool

False will result in 404 Not Found. Defaults to True.

generateETag :: MaybeT m ETag

If this returns an ETag, it will be used for the ETag header and for comparison in conditional requests. Defaults to mzero.

lastModified :: MaybeT m HTTPDate

If this returns a HTTPDate, it will be used for the Last-Modified header and for comparison in conditional requests. Defaults to mzero.

expires :: MaybeT m HTTPDate

If this returns a HTTPDate, it will be used for the Expires header. Defaults to mzero.

movedPermanently :: MaybeT (HaltT m) ByteString

If this returns a URI, the client will receive a 301 Moved Permanently with the URI in the Location header. Defaults to mzero.

movedTemporarily :: MaybeT (HaltT m) ByteString

If this returns a URI, the client will receive a 307 Temporary Redirect with URI in the Location header. Defaults to mzero.

previouslyExisted :: HaltT m Bool

If this returns True, the movedPermanently and movedTemporarily callbacks will be invoked to determine whether the response should be 301 Moved Permanently, 307 Temporary Redirect, or 410 Gone. Defaults to False.

allowMissingPost :: HaltT m Bool

If the resource accepts POST requests to nonexistent resources, then this should return True. Defaults to False.

deleteResource :: HaltT m Bool

This is called when a DELETE request should be enacted, and should return True if the deletion succeeded or has been accepted. Defaults to True.

deleteCompleted :: HaltT m Bool

This is only called after a successful deleteResource call, and should return False if the deletion was accepted but cannot yet be guaranteed to have finished. Defaults to True.

postAction :: m (PostAction m)

If POST requests should be treated as a request to put content into a (potentially new) resource as opposed to being a generic submission for processing, then this function should return PostCreate path. If it does return PostCreate path, then the rest of the request will be treated much like a PUT to the path entry. Otherwise, if it returns PostProcess a, then the action a will be run. Defaults to PostProcess $ return ().

contentTypesAccepted :: m [(MediaType, HaltT m ())]

This is used similarly to contentTypesProvided, except that it is for incoming resource representations -- for example, PUT requests. Handler functions usually want to use server specific functions to access the incoming request body. Defaults to [].

variances :: m [HeaderName]

This function should return a list of strings with header names that should be included in a given response's Vary header. The standard conneg headers (Accept, Accept-Encoding, Accept-Charset, Accept-Language) do not need to be specified here as Webcrank will add the correct elements of those automatically depending on resource behavior. Defaults to [].

multipleChoices :: HaltT m Bool

If this returns True, then it is assumed that multiple representations of the response are possible and a single one cannot be automatically chosen, so a 300 Multiple Choices will be sent instead of a 200 OK. Defaults to False.

isConflict :: m Bool

If this returns True, the client will receive a 409 Conflict. Defaults to False.

finishRequest :: m ()

Called just before the final response is constructed and sent.

resource :: Monad m => Resource m Source

Builds a Resource m value where all the resource functions will return default values as described in the Resource function documentation.

resourceWithBody :: Monad m => MediaType -> m Body -> Resource m Source

Creates a resource that provides a single content type.

resourceWithHtml :: Monad m => m Body -> Resource m Source

Creates a resource that provides a text/html content type.

type Encoding = CI ByteString Source

Content coding type, e.g. gzip, decompress. See encodingsProvided.

data Authorized Source

Indicates whether client is authorized to perform the requested operation on the resource. See isAuthorized.

Constructors

Authorized

Tells Webcrank that the client is authorized to perform the requested operation on the resource.

Unauthorized ByteString

Tells Webcrank that the client is not authorized to perform the operation on the resource. The value is sent in the WWW-Authenticate header of the response, e.g. Basic realm=Webcrank.

data ETag Source

Weak or strong entity tags as used in HTTP ETag and If-*-Match headers.

data PostAction m Source

How POST requests should be treated. See postAction.

Constructors

PostCreate [Text]

Treat POSTs as creating new resources and respond with 201 Created, with the given path in the Location header.

PostCreateRedir [Text]

Treat POSTs as creating new resources and respond with 301 See Other, redirecting the client to the new resource.

PostProcess (HaltT m ())

Treat POSTs as a process which is executed without redirect.

PostProcessRedir (HaltT m ByteString)

Treat POSTs as a process and redirect the client to a different (possibly new) resource.

postCreate :: Monad m => [Text] -> m (PostAction m) Source

Create a PostAction which performs resource creation without redirecting.

postCreateRedir :: Monad m => [Text] -> m (PostAction m) Source

Create a PostAction which performs resource creation and redirects.

postProcess :: Monad m => HaltT m () -> m (PostAction m) Source

Create a PostAction which runs some process and does not redirect.

postProcessRedir :: Monad m => HaltT m ByteString -> m (PostAction m) Source

Create a PostAction which runs some process and does redirects.

data HaltT m a Source

Monad transformer for Resource functions which can halt the request processing early with an error or some other response. Values are created with the smart constructors werror and halt.

halt :: Monad m => Status -> HaltT m a Source

Immediately end processing of the request, returning the response Status. It is the responsibility of the resource to ensure that all necessary response header and body elements have been added in order to make that response code valid.

werror :: Monad m => ByteString -> HaltT m a Source

Immediately end processing of this request, returning a 500 Internal Server Error response. The response body will contain the reason.

Charsets

type Charset = CI ByteString Source

Character set type, e.g. utf-8. See charsetsProvided.

data CharsetsProvided Source

Indicates whether the resource supports multiple character sets or not. See charsetsProvided

Constructors

NoCharset

Indicates that the resource doesn't support any additional character sets, all responses from the resource will have the same character set, regardless of what the client requests.

CharsetsProvided (NonEmpty (Charset, Body -> Body))

The character sets the resource supports along with functions for converting the response body.

provideCharsets :: Monad m => NonEmpty (Charset, Body -> Body) -> m CharsetsProvided Source

Shortcut for return . CharsetsProvided

Headers

addResponseHeader :: (MonadState s m, HasReqData s) => HeaderName -> ByteString -> m () Source

Add a header to the response.

putResponseHeader :: (MonadState s m, HasReqData s) => HeaderName -> ByteString -> m () Source

Replace any existing response headers for the header name with the new value.

Body

type Body = ByteString Source

Response body type.

textBody :: Text -> Body Source

Create a response Body from strict Text.

lazyTextBody :: Text -> Body Source

Create a response Body from lazy Text.

strBody :: String -> Body Source

Create a response Body from a String.

writeLBS :: (MonadState s m, HasReqData s) => ByteString -> m () Source

Use the lazy ByteString as the response body.

writeStr :: (MonadState s m, HasReqData s) => String -> m () Source

Set the response body from a String

Extra convience (re)exports