-- 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 the application state. As simple as that.
--   This library exploits that fact to produce a very simple and flexible
--   API, which can be executed on top of any specific HTTP-server
--   implementation (e.g., Warp).
--   
--   <ul>
--   <li><i>Library Structure</i> The API is split into a set of DSLs
--   targeted at solving specific problems in isolation, thus facilitating
--   a proper separation of concerns.</li>
--   <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 2


-- | DSL for building of the response body.
module Strelka.ResponseBodyBuilding

-- | A builder of the response body.
data Builder

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

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

-- | Lift a ByteString builder.
lazyBytesBuilder :: Builder -> Builder

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

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

-- | Lift a Text builder.
lazyTextBuilder :: Builder -> Builder

-- | Lift a handler of the feeding and flushing actions.
actions :: ((ByteString -> IO ()) -> IO () -> IO ()) -> Builder

module Strelka.ResponseBuilding

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

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

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

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

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

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | 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 :: Builder

-- | Set the body.
body :: Builder -> Builder

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

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

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

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

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

module Strelka.RequestBodyParsing

-- | A specification of how to consume the request body byte-stream.
data Parser a

-- | Result of a folding step.
data Folded a
Unfinished :: !a -> Folded a
Finished :: !a -> Folded a
Failed :: Text -> Folded a

-- | Fail with a message.
fail :: Text -> Parser a

-- | Fold with support for early termination and failure.
foldBytes :: (a -> ByteString -> Folded a) -> a -> Parser a

-- | Fold with support for early termination and failure.
foldText :: (a -> Text -> Folded a) -> a -> Parser a

-- | Fold over the input chunks, projecting them into a monoid. Similar to
--   <a>Foldable</a>'s <a>foldMap</a>.
buildFromBytes :: Monoid a => (ByteString -> a) -> Parser a

-- | Fold over the input chunks, projecting them into a monoid. Similar to
--   <a>Foldable</a>'s <a>foldMap</a>.
buildFromText :: Monoid a => (Text -> a) -> Parser a

-- | Lift an Attoparsec ByteString parser.
--   
--   Consumption is non-greedy and terminates when the parser is done.
parseBytes :: Parser a -> Parser a

-- | Lift an Attoparsec Text parser.
--   
--   Consumption is non-greedy and terminates when the parser is done.
parseText :: Parser a -> Parser a

-- | Parses the input stream as "application/x-www-form-urlencoded".
parseParams :: Params a -> Parser a

-- | Provides a default request body parser.
class DefaultParser a
defaultParser :: DefaultParser a => Parser a


-- | DSL for parsing of parameters.
module Strelka.ParamsParsing

-- | Parser of a product of parameters.
--   
--   Can be composed using the Applicative interface.
data Params a

-- | Parse a param by its name using an explicit parser.
param :: Text -> Value a -> Params a

-- | Parse a param by its name using the implicit default parser.
defaultParam :: DefaultValue a => Text -> Params a

-- | Same as <a>defaultParam</a>.
defaultParams1 :: DefaultValue a => Text -> Params a

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams2 :: (DefaultValue a, DefaultValue b) => Text -> Text -> Params (a, b)

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams3 :: (DefaultValue a, DefaultValue b, DefaultValue c) => Text -> Text -> Text -> Params (a, b, c)

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams4 :: (DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d) => Text -> Text -> Text -> Text -> Params (a, b, c, d)

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams5 :: (DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e) => Text -> Text -> Text -> Text -> Text -> Params (a, b, c, d, e)

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams6 :: (DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e, DefaultValue f) => Text -> Text -> Text -> Text -> Text -> Text -> Params (a, b, c, d, e, f)

-- | A helper abstracting over the Applicative composition of multiple
--   <a>defaultParam</a>.
defaultParams7 :: (DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e, DefaultValue f, DefaultValue g) => Text -> Text -> Text -> Text -> Text -> Text -> Text -> Params (a, b, c, d, e, f, g)

-- | A parser of a parameter value.
data Value a

-- | Lifts an Attoparsec parser into Value.
parser :: Parser a -> Value a

-- | Lifts a text-matching function into Value.
matcher :: (Text -> Either Text a) -> Value a

-- | Lifts a single value parser to the parser of a list of values.
--   
--   Useful for decoding lists of values of the same name. E.g., it'll work
--   for the both following cases:
--   
--   <pre>
--   ?param[]=1&amp;param[]=2
--   </pre>
--   
--   <pre>
--   ?param=1&amp;param=2
--   </pre>
--   
--   In both cases the name of the parameter to look up will be "param".
list :: Value a -> Value [a]

-- | Lifts a single value parser to the parser of a possibly specified
--   value.
--   
--   It's useful for decoding the difference between the following two
--   cases:
--   
--   <pre>
--   ?param=value
--   </pre>
--   
--   <pre>
--   ?param
--   </pre>
maybe :: Value a -> Value (Maybe a)

-- | Provides a default value parser.
class DefaultValue value
defaultValue :: DefaultValue value => Value value


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

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

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

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

-- | Consume the next segment of the path with an implicit lenient
--   Attoparsec parser.
segment :: (Monad m, LenientParser a) => Parser m a

-- | Consume the next segment of the path with an explicit Attoparsec
--   parser.
segmentWithParser :: Monad m => Parser a -> Parser m a

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

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

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query1 :: (Monad m, DefaultValue a) => Text -> Parser m a

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query2 :: (Monad m, DefaultValue a, DefaultValue b) => Text -> Text -> Parser m (a, b)

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query3 :: (Monad m, DefaultValue a, DefaultValue b, DefaultValue c) => Text -> Text -> Text -> Parser m (a, b, c)

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query4 :: (Monad m, DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d) => Text -> Text -> Text -> Text -> Parser m (a, b, c, d)

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query5 :: (Monad m, DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e) => Text -> Text -> Text -> Text -> Text -> Parser m (a, b, c, d, e)

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query6 :: (Monad m, DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e, DefaultValue f) => Text -> Text -> Text -> Text -> Text -> Text -> Parser m (a, b, c, d, e, f)

-- | Parse the query using implicit parsers by specifying the names of
--   parameters.
query7 :: (Monad m, DefaultValue a, DefaultValue b, DefaultValue c, DefaultValue d, DefaultValue e, DefaultValue f, DefaultValue g) => Text -> Text -> Text -> Text -> Text -> Text -> Text -> Parser m (a, b, c, d, e, f, g)

-- | Parse the request query, i.e. the URL part that is between the "?" and
--   "#" characters, with an explicitly specified parser.
queryWithParser :: Monad m => Params a -> Parser m a

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

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

-- | Same as <tt><a>methodIs</a> "get"</tt>.
methodIsGet :: Monad m => Parser m ()

-- | Same as <tt><a>methodIs</a> "post"</tt>.
methodIsPost :: Monad m => Parser m ()

-- | Same as <tt><a>methodIs</a> "put"</tt>.
methodIsPut :: Monad m => Parser m ()

-- | Same as <tt><a>methodIs</a> "delete"</tt>.
methodIsDelete :: Monad m => Parser m ()

-- | Same as <tt><a>methodIs</a> "head"</tt>.
methodIsHead :: Monad m => Parser m ()

-- | Same as <tt><a>methodIs</a> "trace"</tt>.
methodIsTrace :: Monad m => Parser m ()

-- | Lookup a header by name <b>in lower-case</b>.
header :: Monad m => ByteString -> Parser 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>.
accepts :: Monad m => ByteString -> Parser m ()

-- | Same as <tt><a>accepts</a> "text/plain"</tt>.
acceptsText :: Monad m => Parser m ()

-- | Same as <tt><a>accepts</a> "text/html"</tt>.
acceptsHTML :: Monad m => Parser m ()

-- | Same as <tt><a>accepts</a> "application/json"</tt>.
acceptsJSON :: Monad m => Parser m ()

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

-- | Consume the request body using an implicit parser.
--   
--   <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>
body :: (MonadIO m, DefaultParser a) => Parser m a

-- | Consume the request body using the explicitly specified parser.
--   
--   <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>
bodyWithParser :: MonadIO m => Parser a -> Parser m a