Database.Couch.RequestBuilder

Documentation

data BuilderState

The state of our request as it's being built

Constructors

BuilderState

Fields

bsRequest :: Request

The base request being built

bsQueryParam :: [(ByteString, Maybe ByteString)]

The request itself only stores the queryString, so we accumulate pairs during construction, and use them to set the query string at the end.

bsDb :: ByteString

If this is set, it will be prepended to the path.

bsPathSegments :: [ByteString]

Again, stored this way for ease of manipulation, then properly assembled at the end.

type RequestBuilder = StateT BuilderState (Reader Context)

A type synonym for our builder monad

runBuilder :: RequestBuilder () -> Context -> Request

Given a Context, run our monadic builder function to produce a Request.

finalize :: BuilderState -> Request

This actually takes the BuilderState and does the assembly of the various state bits into a single Request.

defaultRequest :: RequestBuilder ()

The default set of modifications applied to the request.

• The host/port connection information is set
• The Accept header is set to 'application/json'
• The 'Content-Type' headers is set to 'application/json'
• Any authentication session in the cookie jar is set
• Any Basic Authentication information is applied

Any or all of these may be overridden, but probably shouldn't be.

Applying Context to the Request

selectDb :: RequestBuilder ()

Choose the database for the Request, based on what's in the Context. This is the one thing that could arguably throw an error.

setAuth :: RequestBuilder ()

Set the appropriate authentication markers on the Request, based on what's in the Context.

setConnection :: RequestBuilder ()

Set the host and port for the Request, based on what's in the Context.

setCookieJar :: RequestBuilder ()

Set the CookieJar for the Request, based on what's in the Context.

Setting Headers

addHeaders :: RequestHeaders -> RequestBuilder ()

Add headers to a Request, leaving existing instances undisturbed.

defaultHeaders :: RequestHeaders -> RequestBuilder ()

Add headers to a Request, if they aren't already present.

setHeaders :: RequestHeaders -> RequestBuilder ()

Set headers on the Request, overriding any existing instances.

Setting Query Parameters

addQueryParam :: [(ByteString, Maybe ByteString)] -> RequestBuilder ()

Add query parameters to a Request, leaving existing parameters undisturbed.

defaultQueryParam :: [(ByteString, Maybe ByteString)] -> RequestBuilder ()

Add query parameters to a Request, if they aren't already present

setQueryParam :: [(ByteString, Maybe ByteString)] -> RequestBuilder ()

Set query parameters on the Request, overriding any existing instances.

Setting the document path

addPath :: ByteString -> RequestBuilder ()

Add a path segment to the Request. This is only appropriate for static paths.

selectDoc :: DocId -> RequestBuilder ()

Add a path segment to the Request, given a DocId.

Handling optional revision information

addRev :: DocRev -> RequestBuilder ()

Set the rev for the Request.

maybeAddRev :: Maybe DocRev -> RequestBuilder ()

Set the rev for the Request if you have it.

Miscellaneous request options

setJsonBody

Arguments

:: ToJSON a

=> a

The document content

-> RequestBuilder ()

Set the body of the request to the encoded JSON value

setMethod :: ByteString -> RequestBuilder ()

Set the method for the Request.