-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A simple, flexible and composable web-router
--   
--   An HTTP server can be defined as a request parser, which produces a
--   response, while managing some state. As simple as that. This library
--   exploits that fact to produce a very simple and flexible API, which
--   can then be used on top of any server implementation.
--   
--   <ul>
--   <li><i>Server Bindings</i> Currently only a binding to WAI and Warp is
--   known: <a>http://hackage.haskell.org/package/strelka-wai</a>.</li>
--   <li><i>Demo</i> For a thorough demonstration of the library and
--   suggested usage patterns check out the following project:
--   <a>https://github.com/nikita-volkov/strelka-demo</a>.</li>
--   </ul>
@package strelka
@version 1

module Strelka.ResponseBodyBuilder

-- | A builder of the response body.
newtype ResponseBodyBuilder
ResponseBodyBuilder :: ((ByteString -> IO ()) -> IO () -> IO ()) -> ResponseBodyBuilder

-- | Lift ByteString.
bytes :: ByteString -> ResponseBodyBuilder

-- | Lift lazy ByteString.
lazyBytes :: ByteString -> ResponseBodyBuilder

-- | Lift ByteString Builder.
bytesBuilder :: Builder -> ResponseBodyBuilder

-- | Lift Text.
text :: Text -> ResponseBodyBuilder

-- | Lift lazy Text.
lazyText :: Text -> ResponseBodyBuilder

-- | Lift ByteString Builder.
textBuilder :: Builder -> ResponseBodyBuilder
instance Data.String.IsString Strelka.ResponseBodyBuilder.ResponseBodyBuilder
instance GHC.Base.Monoid Strelka.ResponseBodyBuilder.ResponseBodyBuilder
instance Data.Semigroup.Semigroup Strelka.ResponseBodyBuilder.ResponseBodyBuilder

module Strelka.ResponseBuilder

-- | A composable abstraction for building an HTTP response.
type ResponseBuilder = ResponseBuilder

-- | Add a header by name and value.
header :: ByteString -> ByteString -> ResponseBuilder

-- | Add a <tt>Content-type</tt> header.
contentTypeHeader :: ByteString -> ResponseBuilder

-- | Add a <tt>Location</tt> header.
locationHeader :: ByteString -> ResponseBuilder

-- | Set the status code.
status :: Int -> ResponseBuilder

-- | Set the status code to <tt>200</tt>. Following is the description of
--   this status.
--   
--   The request has succeeded. The information returned with the response
--   is dependent on the method used in the request, for example:
--   
--   GET an entity corresponding to the requested resource is sent in the
--   response;
--   
--   HEAD the entity-header fields corresponding to the requested resource
--   are sent in the response without any message-body;
--   
--   POST an entity describing or containing the result of the action;
--   
--   TRACE an entity containing the request message as received by the end
--   server.
okayStatus :: ResponseBuilder

-- | Set the status code to <tt>301</tt>. Following is the description of
--   this status.
--   
--   The requested resource has been assigned a new permanent URI and any
--   future references to this resource SHOULD use one of the returned
--   URIs. Clients with link editing capabilities ought to automatically
--   re-link references to the Request-URI to one or more of the new
--   references returned by the server, where possible. This response is
--   cacheable unless indicated otherwise.
--   
--   The new permanent URI SHOULD be given by the Location field in the
--   response. Unless the request method was HEAD, the entity of the
--   response SHOULD contain a short hypertext note with a hyperlink to the
--   new URI(s).
--   
--   If the 301 status code is received in response to a request other than
--   GET or HEAD, the user agent MUST NOT automatically redirect the
--   request unless it can be confirmed by the user, since this might
--   change the conditions under which the request was issued.
--   
--   Note: When automatically redirecting a POST request after receiving a
--   301 status code, some existing HTTP/1.0 user agents will erroneously
--   change it into a GET request.
movedPermanentlyStatus :: ResponseBuilder

-- | Set the status code to <tt>400</tt>. Following is the description of
--   this status.
--   
--   The request could not be understood by the server due to malformed
--   syntax. The client SHOULD NOT repeat the request without
--   modifications.
badRequestStatus :: ResponseBuilder

-- | Set the status code to <tt>401</tt>. Following is the description of
--   this status.
--   
--   The request requires user authentication. The response MUST include a
--   WWW-Authenticate header field (section 14.47) containing a challenge
--   applicable to the requested resource. The client MAY repeat the
--   request with a suitable Authorization header field (section 14.8). If
--   the request already included Authorization credentials, then the 401
--   response indicates that authorization has been refused for those
--   credentials. If the 401 response contains the same challenge as the
--   prior response, and the user agent has already attempted
--   authentication at least once, then the user SHOULD be presented the
--   entity that was given in the response, since that entity might include
--   relevant diagnostic information. HTTP access authentication is
--   explained in "HTTP Authentication: Basic and Digest Access
--   Authentication".
unauthorizedStatus :: ResponseBuilder

-- | Set the status code to <tt>403</tt>. Following is the description of
--   this status.
--   
--   The server understood the request, but is refusing to fulfill it.
--   Authorization will not help and the request SHOULD NOT be repeated. If
--   the request method was not HEAD and the server wishes to make public
--   why the request has not been fulfilled, it SHOULD describe the reason
--   for the refusal in the entity. If the server does not wish to make
--   this information available to the client, the status code 404 (Not
--   Found) can be used instead.
forbiddenStatus :: ResponseBuilder

-- | Set the status code to <tt>404</tt>. Following is the description of
--   this status.
--   
--   The server has not found anything matching the Request-URI. No
--   indication is given of whether the condition is temporary or
--   permanent. The 410 (Gone) status code SHOULD be used if the server
--   knows, through some internally configurable mechanism, that an old
--   resource is permanently unavailable and has no forwarding address.
--   This status code is commonly used when the server does not wish to
--   reveal exactly why the request has been refused, or when no other
--   response is applicable.
notFoundStatus :: ResponseBuilder

-- | Set the status code to <tt>405</tt>. Following is the description of
--   this status.
--   
--   The method specified in the Request-Line is not allowed for the
--   resource identified by the Request-URI. The response MUST include an
--   Allow header containing a list of valid methods for the requested
--   resource.
methodNotAllowedStatus :: ResponseBuilder

-- | Set the status code to <tt>406</tt>. Following is the description of
--   this status.
--   
--   The resource identified by the request is only capable of generating
--   response entities which have content characteristics not acceptable
--   according to the accept headers sent in the request.
--   
--   Unless it was a HEAD request, the response SHOULD include an entity
--   containing a list of available entity characteristics and location(s)
--   from which the user or user agent can choose the one most appropriate.
--   The entity format is specified by the media type given in the
--   Content-Type header field. Depending upon the format and the
--   capabilities of the user agent, selection of the most appropriate
--   choice MAY be performed automatically. However, this specification
--   does not define any standard for such automatic selection.
--   
--   Note: HTTP/1.1 servers are allowed to return responses which are not
--   acceptable according to the accept headers sent in the request. In
--   some cases, this may even be preferable to sending a 406 response.
--   User agents are encouraged to inspect the headers of an incoming
--   response to determine if it is acceptable.
--   
--   If the response could be unacceptable, a user agent SHOULD temporarily
--   stop receipt of more data and query the user for a decision on further
--   actions.
notAcceptableStatus :: ResponseBuilder

-- | Set the status code to <tt>500</tt>. Following is the description of
--   this status.
--   
--   The server encountered an unexpected condition which prevented it from
--   fulfilling the request.
internalErrorStatus :: ResponseBuilder

-- | Set the body.
body :: ResponseBodyBuilder -> ResponseBuilder

-- | Add a <tt>Content-type</tt> header with the value of
--   <tt>text/plain</tt> and set the body.
text :: ResponseBodyBuilder -> ResponseBuilder

-- | Add a <tt>Content-type</tt> header with the value of
--   <tt>text/html</tt> and set the body.
html :: ResponseBodyBuilder -> ResponseBuilder

-- | Add a <tt>Content-type</tt> header with the value of
--   <tt>application/json</tt> and set the body.
json :: ResponseBodyBuilder -> ResponseBuilder

-- | Set the status code to 401, adding a <tt>WWW-Authenticate</tt> header
--   with specified Realm.
unauthorized :: ByteString -> ResponseBuilder

-- | Set the status code to 301, adding a <tt>Location</tt> header with the
--   specified URL.
redirect :: ByteString -> ResponseBuilder

module Strelka.RequestBodyConsumer

-- | A specification of how to consume the request body byte-stream.
newtype RequestBodyConsumer a
RequestBodyConsumer :: (IO ByteString -> IO a) -> RequestBodyConsumer a

-- | Fold with support for early termination, which is interpreted from
--   <a>Left</a>.
foldBytesWithTermination :: (a -> ByteString -> Either a a) -> a -> RequestBodyConsumer a

-- | Fold with support for early termination, which is interpreted from
--   <a>Left</a>.
foldTextWithTermination :: (a -> Text -> Either a a) -> a -> RequestBodyConsumer a

-- | Fold over ByteString chunks.
foldBytes :: (a -> ByteString -> a) -> a -> RequestBodyConsumer a

-- | Fold over text chunks decoded using UTF8.
foldText :: (a -> Text -> a) -> a -> RequestBodyConsumer a

-- | Similar to <a>Foldable</a>'s <a>foldMap</a>.
buildFromBytes :: Monoid a => (ByteString -> a) -> RequestBodyConsumer a

-- | Similar to <a>Foldable</a>'s <a>foldMap</a>.
buildFromText :: Monoid a => (Text -> a) -> RequestBodyConsumer a

-- | Consume as ByteString.
bytes :: RequestBodyConsumer ByteString

-- | Consume as lazy ByteString.
lazyBytes :: RequestBodyConsumer ByteString

-- | Consume as ByteString Builder.
bytesBuilder :: RequestBodyConsumer Builder

-- | Consume as Text.
text :: RequestBodyConsumer Text

-- | Consume as lazy Text.
lazyText :: RequestBodyConsumer Text

-- | Consume as Text Builder.
textBuilder :: RequestBodyConsumer Builder

-- | Lift an Attoparsec ByteString parser.
--   
--   Consumption is non-greedy and terminates when the parser is done.
bytesParser :: Parser a -> RequestBodyConsumer (Either Text a)

-- | Lift an Attoparsec Text parser.
--   
--   Consumption is non-greedy and terminates when the parser is done.
textParser :: Parser a -> RequestBodyConsumer (Either Text a)

-- | Given a chunk-specialized terminating fold implementation lifts a
--   generic Attoparsec result.
parserResult :: Monoid i => (forall a. (a -> i -> Either a a) -> a -> RequestBodyConsumer a) -> IResult i a -> RequestBodyConsumer (Either Text a)
instance GHC.Base.Functor Strelka.RequestBodyConsumer.RequestBodyConsumer


-- | DSL for parsing the request.
module Strelka.RequestParser

-- | Parser of an HTTP request. Analyzes its meta information, consumes the
--   path segments and the body.
type RequestParser = RequestParser

-- | Fail with a text message.
fail :: Monad m => Text -> RequestParser m a

-- | Lift Either, interpreting Left as a failure.
liftEither :: Monad m => Either Text a -> RequestParser m a

-- | Lift Maybe, interpreting Nothing as a failure.
liftMaybe :: Monad m => Maybe a -> RequestParser m a

-- | Try a parser, extracting the error as Either.
unliftEither :: Monad m => RequestParser m a -> RequestParser m (Either Text a)

-- | Consume the next segment of the path.
consumeSegment :: Monad m => RequestParser m Text

-- | Consume the next segment of the path with Attoparsec parser.
consumeSegmentWithParser :: Monad m => Parser a -> RequestParser m a

-- | Consume the next segment if it matches the provided value and fail
--   otherwise.
consumeSegmentIfIs :: Monad m => Text -> RequestParser m ()

-- | Fail if there's any path segments left unconsumed.
ensureThatNoSegmentsIsLeft :: Monad m => RequestParser m ()

-- | Get a parameter's value by its name, failing if the parameter is not
--   present.
--   
--   <tt>Maybe</tt> encodes whether a value was specified at all, i.e.
--   <tt>?name=value</tt> vs <tt>?name</tt>.
getParam :: Monad m => ByteString -> RequestParser m (Maybe ByteString)

-- | Get the request method.
getMethod :: Monad m => RequestParser m ByteString

-- | Ensure that the method matches the provided value <b>in
--   lower-case</b>.
ensureThatMethodIs :: Monad m => ByteString -> RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "get"</tt>.
ensureThatMethodIsGet :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "post"</tt>.
ensureThatMethodIsPost :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "put"</tt>.
ensureThatMethodIsPut :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "delete"</tt>.
ensureThatMethodIsDelete :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "head"</tt>.
ensureThatMethodIsHead :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatMethodIs</a> "trace"</tt>.
ensureThatMethodIsTrace :: Monad m => RequestParser m ()

-- | Lookup a header by name <b>in lower-case</b>.
getHeader :: Monad m => ByteString -> RequestParser m ByteString

-- | Ensure that the request provides an Accept header, which includes the
--   specified content type. Content type must be <b>in lower-case</b>.
ensureThatAccepts :: Monad m => ByteString -> RequestParser m ()

-- | Same as <tt><a>ensureThatAccepts</a> "text/plain"</tt>.
ensureThatAcceptsText :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatAccepts</a> "text/html"</tt>.
ensureThatAcceptsHTML :: Monad m => RequestParser m ()

-- | Same as <tt><a>ensureThatAccepts</a> "application/json"</tt>.
ensureThatAcceptsJSON :: Monad m => RequestParser m ()

-- | Check whether the request provides an Accept header, which includes
--   the specified content type. Content type must be <b>in lower-case</b>.
checkIfAccepts :: Monad m => ByteString -> RequestParser m Bool

-- | Parse the username and password from the basic authorization header.
getAuthorization :: Monad m => RequestParser m (Text, Text)

-- | Consume the request body using the provided RequestBodyConsumer.
--   
--   <ul>
--   <li><i>NOTICE</i> Since the body is consumed as a stream, you can only
--   consume it once regardless of the Alternative branching.</li>
--   </ul>
consumeBody :: MonadIO m => RequestBodyConsumer a -> RequestParser m a