Webcrank

Resources

data Resource m

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

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

Creates a resource that provides a single content type.

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

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

type Encoding = CI ByteString

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

data Authorized

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

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

Constructors

StrongETag ByteString

WeakETag ByteString

Instances

Eq ETag

Show ETag

RenderHeader ETag

data PostAction m

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)

Create a PostAction which performs resource creation without redirecting.

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

Create a PostAction which performs resource creation and redirects.

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

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

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

Create a PostAction which runs some process and does redirects.

data HaltT m a

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.

Instances

MonadTrans HaltT

MonadState s m => MonadState s (HaltT m)

MonadReader r m => MonadReader r (HaltT m)

MonadWriter w m => MonadWriter w (HaltT m)

Monad m => Monad (HaltT m)

Monad m => Functor (HaltT m)

Monad m => Applicative (HaltT m)

MonadThrow m => MonadThrow (HaltT m)

MonadCatch m => MonadCatch (HaltT m)

MonadIO m => MonadIO (HaltT m)

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

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

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

werrorWith :: Monad m => Status -> ByteString -> HaltT m a

Immediately end processing of this request, returning a response with the given Status. The response body will contain the reason.

getDispatchPath :: (MonadState s m, HasReqData s) => m [Text]

The “local” path of the resource URI; the part after any prefix used in dispatch configuration. Of the three path accessors, this is the one you usually want. This is also the one that will change after postAction is called in your resource.

data ReqData

Container used to keep track of the decision state and what is known about response while processing a request.

Instances

HasReqData ReqData

Monad m => MonadState ReqData (WebcrankT m)

class HasReqData c

Minimal complete definition

reqData

Instances

HasReqData ReqData

Charsets

type Charset = CI ByteString

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

data CharsetsProvided

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

Shortcut for return . CharsetsProvided

Headers

type HeadersMap = HashMap HeaderName [ByteString]

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

Add a header to the response.

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

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

Body

type Body = ByteString

Response body type.

lazyByteStringBody :: ByteString -> Body

Create a response Body from a lazy ByteString.

byteStringBody :: ByteString -> Body

Create a response Body from a ByteString.

lazyTextBody :: Text -> Body

Create a response Body from lazy Text.

textBody :: Text -> Body

Create a response Body from strict Text.

strBody :: String -> Body

Create a response Body from a String.

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

Use the Body as the response body.

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

Use the lazy ByteString as the response body.

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

Use the ByteString as the response body.

writeLT :: (MonadState s m, HasReqData s) => Text -> m ()

Use the lazy Text as the response body.

writeText :: (MonadState s m, HasReqData s) => Text -> m ()

Use the Text as the response body.

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

Use the String as the response body.

Extra convience (re)exports

module Network.HTTP.Date

module Network.HTTP.Media

module Network.HTTP.Types

hAcceptCharset :: HeaderName

hAcceptEncoding :: HeaderName

hAllow :: HeaderName

hETag :: HeaderName

hExpires :: HeaderName

hIfMatch :: HeaderName

hIfNoneMatch :: HeaderName

hIfUnmodifiedSince :: HeaderName

hTransferEncoding :: HeaderName

hVary :: HeaderName

hWWWAuthenticate :: HeaderName