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


-- | Native implementation of the FastCGI protocol.
--   
--   This package is a native implementation of the FastCGI protocol,
--   allowing Haskell to work with any webserver that supports it. It makes
--   no attempt to imitate the interface of the cgi-3000 and fastcgi-3000
--   packages, because that API is tied too heavily to legacy interfaces,
--   as with its handling of exceptions, logging, and time. Its advantage
--   over those packages is primarily in the area of clean exception
--   management and better control structure which allows more versatility
--   in processing requests which are not simple GETs. In particular, POST
--   of large files should be possible, as should server-push responses
--   which return content a piece at a time. Also, of course, as a native
--   implementation, there is no dependency on a C library, which
--   simplifies the install process. Version 1.0.3 adds support for the new
--   version of the network package, which integrates what used to be a
--   separate package, network-bytestring. It also provides compatibility
--   with (unreleased as of this writing) GHC 7.1. Version 1.0.2 fixes a
--   bug; response headers are now sent if they have not already been when
--   fCloseOutput is called explicitly. It also removes spurious debug
--   output that had been left in by mistake.
@package direct-fastcgi
@version 1.0.3

module Network.FastCGI

-- | The monad within which each single connection from the web server is
--   handled.
type FastCGI = ReaderT FastCGIState IO

-- | An opaque type representing the state of a single connection from the
--   web server.
data FastCGIState

-- | The class of monads within which the FastCGI calls are valid. You may
--   wish to create your own monad implementing this class.
class MonadIO m => MonadFastCGI m
getFastCGIState :: MonadFastCGI m => m FastCGIState
implementationThrowFastCGI :: (MonadFastCGI m, Exception e) => e -> m a
implementationCatchFastCGI :: (MonadFastCGI m, Exception e) => m a -> (e -> m a) -> m a
implementationBlockFastCGI :: MonadFastCGI m => m a -> m a
implementationUnblockFastCGI :: MonadFastCGI m => m a -> m a

-- | Takes a forking primitive, such as <a>forkIO</a> or <a>forkOS</a>, and
--   a handler, and concurrently accepts requests from the web server,
--   forking with the primitive and invoking the handler in the forked
--   thread inside the <a>FastCGI</a> monad for each one.
--   
--   It is valid to use a custom forking primitive, such as one that
--   attempts to pool OS threads, but the primitive must actually provide
--   concurrency - otherwise there will be a deadlock. There is no support
--   for single-threaded operation.
--   
--   Note that although there is no mechanism to substitute another type of
--   monad for FastCGI, you can enter your own monad within the handler,
--   much as you would enter your own monad within IO. You simply have to
--   implement the <a>MonadFastCGI</a> class.
--   
--   Any exceptions not caught within the handler are caught by
--   <tt>concurrentAcceptLoop</tt>, and cause the termination of that
--   handler, but not of the accept loop. Furthermore, the exception is
--   logged through the FastCGI protocol if at all possible.
--   
--   In the event that the program was not invoked according to the FastCGI
--   protocol, returns.
acceptLoop :: (IO () -> IO ThreadId) -> (FastCGI ()) -> IO ()

-- | Logs a message using the web server's logging facility.
fLog :: MonadFastCGI m => String -> m ()

-- | Queries the value from the web server of the CGI/1.1 request variable
--   with the given name for this request.
getRequestVariable :: MonadFastCGI m => String -> m (Maybe String)

-- | Returns an association list of name-value pairs of all the CGI/1.1
--   request variables from the web server.
getAllRequestVariables :: MonadFastCGI m => m [(String, String)]

-- | Headers are classified by HTTP/1.1 as request headers, response
--   headers, or entity headers.
data Header

-- | Request headers
HttpAccept :: Header
HttpAcceptCharset :: Header
HttpAcceptEncoding :: Header
HttpAcceptLanguage :: Header
HttpAuthorization :: Header
HttpExpect :: Header
HttpFrom :: Header
HttpHost :: Header
HttpIfMatch :: Header
HttpIfModifiedSince :: Header
HttpIfNoneMatch :: Header
HttpIfRange :: Header
HttpIfUnmodifiedSince :: Header
HttpMaxForwards :: Header
HttpProxyAuthorization :: Header
HttpRange :: Header
HttpReferer :: Header
HttpTE :: Header
HttpUserAgent :: Header

-- | Response headers
HttpAcceptRanges :: Header
HttpAge :: Header
HttpETag :: Header
HttpLocation :: Header
HttpProxyAuthenticate :: Header
HttpRetryAfter :: Header
HttpServer :: Header
HttpVary :: Header
HttpWWWAuthenticate :: Header

-- | Entity headers
HttpAllow :: Header
HttpContentEncoding :: Header
HttpContentLanguage :: Header
HttpContentLength :: Header
HttpContentLocation :: Header
HttpContentMD5 :: Header
HttpContentRange :: Header
HttpContentType :: Header
HttpExpires :: Header
HttpLastModified :: Header
HttpExtensionHeader :: String -> Header

-- | Nonstandard headers
HttpConnection :: Header
HttpCookie :: Header
HttpSetCookie :: Header

-- | Queries the value from the user agent of the given HTTP/1.1 header.
getRequestHeader :: MonadFastCGI m => Header -> m (Maybe String)

-- | Returns an association list of name-value pairs of all the HTTP/1.1
--   request or entity headers from the user agent.
getAllRequestHeaders :: MonadFastCGI m => m [(Header, String)]
data Cookie
Cookie :: String -> String -> Int -> Maybe String -> Maybe String -> Maybe Int -> Bool -> Maybe String -> Cookie
cookieName :: Cookie -> String
cookieValue :: Cookie -> String
cookieVersion :: Cookie -> Int
cookiePath :: Cookie -> Maybe String
cookieDomain :: Cookie -> Maybe String
cookieMaxAge :: Cookie -> Maybe Int
cookieSecure :: Cookie -> Bool
cookieComment :: Cookie -> Maybe String

-- | Returns a <a>Cookie</a> object for the given name, if the user agent
--   provided one in accordance with RFC 2109.
getCookie :: MonadFastCGI m => String -> m (Maybe Cookie)

-- | Returns all <a>Cookie</a> objects provided by the user agent in
--   accordance RFC 2109.
getAllCookies :: MonadFastCGI m => m [Cookie]

-- | A convenience method; as <a>getCookie</a>, but returns only the value
--   of the cookie rather than a <a>Cookie</a> object.
getCookieValue :: MonadFastCGI m => String -> m (Maybe String)

-- | Return the document root, as provided by the web server, if it was
--   provided.
getDocumentRoot :: MonadFastCGI m => m (Maybe String)

-- | Return the gateway interface, as provided by the web server, if it was
--   provided.
getGatewayInterface :: MonadFastCGI m => m (Maybe String)

-- | Return the path info, as provided by the web server, if it was
--   provided.
getPathInfo :: MonadFastCGI m => m (Maybe String)

-- | Return the path-translated value, as provided by the web server, if it
--   was provided.
getPathTranslated :: MonadFastCGI m => m (Maybe String)

-- | Return the query string, as provided by the web server, if it was
--   provided.
getQueryString :: MonadFastCGI m => m (Maybe String)

-- | Return the redirect status, as provided by the web server, if it was
--   provided.
getRedirectStatus :: MonadFastCGI m => m (Maybe Int)

-- | Return the redirect URI, as provided by the web server, if it was
--   provided.
getRedirectURI :: MonadFastCGI m => m (Maybe String)

-- | Return the remote address, as provided by the web server, if it was
--   provided.
getRemoteAddress :: MonadFastCGI m => m (Maybe HostAddress)

-- | Return the remote port, as provided by the web server, if it was
--   provided.
getRemotePort :: MonadFastCGI m => m (Maybe Int)

-- | Return the remote hostname, as provided by the web server, if it was
--   provided.
getRemoteHost :: MonadFastCGI m => m (Maybe String)

-- | Return the remote ident value, as provided by the web server, if it
--   was provided.
getRemoteIdent :: MonadFastCGI m => m (Maybe String)

-- | Return the remote user name, as provided by the web server, if it was
--   provided.
getRemoteUser :: MonadFastCGI m => m (Maybe String)

-- | Return the request method, as provided by the web server, if it was
--   provided.
getRequestMethod :: MonadFastCGI m => m (Maybe String)

-- | Return the request URI, as provided by the web server, if it was
--   provided.
getRequestURI :: MonadFastCGI m => m (Maybe String)

-- | Return the script filename, as provided by the web server, if it was
--   provided.
getScriptFilename :: MonadFastCGI m => m (Maybe String)

-- | Return the script name, as provided by the web server, if it was
--   provided.
getScriptName :: MonadFastCGI m => m (Maybe String)

-- | Return the server address, as provided by the web server, if it was
--   provided.
getServerAddress :: MonadFastCGI m => m (Maybe HostAddress)

-- | Return the server name, as provided by the web server, if it was
--   provided.
getServerName :: MonadFastCGI m => m (Maybe String)

-- | Return the server port, as provided by the web server, if it was
--   provided.
getServerPort :: MonadFastCGI m => m (Maybe Int)

-- | Return the server protocol, as provided by the web server, if it was
--   provided.
getServerProtocol :: MonadFastCGI m => m (Maybe String)

-- | Return the server software name and version, as provided by the web
--   server, if it was provided.
getServerSoftware :: MonadFastCGI m => m (Maybe String)

-- | Return the authentication type, as provided by the web server, if it
--   was provided.
getAuthenticationType :: MonadFastCGI m => m (Maybe String)

-- | Return the content length, as provided by the web server, if it was
--   provided.
getContentLength :: MonadFastCGI m => m (Maybe Int)

-- | Return the content type, as provided by the web server, if it was
--   provided.
getContentType :: MonadFastCGI m => m (Maybe String)

-- | Reads up to a specified amount of data from the input stream of the
--   current request, and interprets it as binary data. This is the content
--   data of the HTTP request, if any. If input has been closed, returns an
--   empty bytestring. If insufficient input is available, blocks until
--   there is enough. If output has been closed, causes an
--   <a>OutputAlreadyClosed</a> exception.
fGet :: MonadFastCGI m => Int -> m ByteString

-- | Reads up to a specified amount of data from the input stream of the
--   curent request, and interprets it as binary data. This is the content
--   data of the HTTP request, if any. If input has been closed, returns an
--   empty bytestring. If insufficient input is available, returns any
--   input which is immediately available, or an empty bytestring if there
--   is none, never blocking. If output has been closed, causes an
--   <a>OutputAlreadyClosed</a> exception.
fGetNonBlocking :: MonadFastCGI m => Int -> m ByteString

-- | Reads all remaining data from the input stream of the current request,
--   and interprets it as binary data. This is the content data of the HTTP
--   request, if any. Blocks until all input has been read. If input has
--   been closed, returns an empty bytestring. If output has been closed,
--   causes an <a>OutputAlreadyClosed</a> exception.
fGetContents :: MonadFastCGI m => m ByteString

-- | Returns whether the input stream of the current request potentially
--   has data remaining, either in the buffer or yet to be read. This is
--   the content data of the HTTP request, if any.
fIsReadable :: MonadFastCGI m => m Bool

-- | Sets the response status which will be sent with the response headers.
--   If the response headers have already been sent, causes a
--   <a>ResponseHeadersAlreadySent</a> exception.
setResponseStatus :: MonadFastCGI m => Int -> m ()

-- | Returns the response status which will be or has been sent with the
--   response headers.
getResponseStatus :: MonadFastCGI m => m Int

-- | Sets the given <tt>HttpHeader</tt> response header to the given string
--   value, overriding any value which has previously been set. If the
--   response headers have already been sent, causes a
--   <a>ResponseHeadersAlreadySent</a> exception. If the header is not an
--   HTTP/1.1 or extension response or entity header, ie, is not valid as
--   part of a response, causes a <a>NotAResponseHeader</a> exception.
--   
--   If a value is set for the <a>HttpSetCookie</a> header, this overrides
--   all cookies set for this request with <a>setCookie</a>.
setResponseHeader :: MonadFastCGI m => Header -> String -> m ()

-- | Causes the given <tt>HttpHeader</tt> response header not to be sent,
--   overriding any value which has previously been set. If the response
--   headers have already been sent, causes a
--   <a>ResponseHeadersAlreadySent</a> exception. If the header is not an
--   HTTP/1.1 or extension response or entity header, ie, is not valid as
--   part of a response, causes a <a>NotAResponseHeader</a> exception.
--   
--   Does not prevent the <a>HttpSetCookie</a> header from being sent if
--   cookies have been set for this request with <a>setCookie</a>.
unsetResponseHeader :: MonadFastCGI m => Header -> m ()

-- | Returns the value of the given header which will be or has been sent
--   with the response headers. If the header is not an HTTP/1.1 or
--   extension response or entity header, ie, is not valid as part of a
--   response, causes a <a>NotAResponseHeader</a> exception.
getResponseHeader :: MonadFastCGI m => Header -> m (Maybe String)

-- | Causes the user agent to record the given cookie and send it back with
--   future loads of this page. Does not take effect instantly, but rather
--   when headers are sent. Cookies are set in accordance with RFC 2109. If
--   an <tt>HttpCookie</tt> header is set for this request by a call to
--   <a>setResponseHeader</a>, this function has no effect. If the response
--   headers have already been sent, causes a
--   <a>ResponseHeadersAlreadySent</a> exception. If the name is not a
--   possible name for a cookie, causes a <a>CookieNameInvalid</a>
--   exception.
setCookie :: MonadFastCGI m => Cookie -> m ()

-- | Causes the user agent to unset any cookie applicable to this page with
--   the given name. Does not take effect instantly, but rather when
--   headers are sent. If an <tt>HttpCookie</tt> header is set for this
--   request by a call to <a>setResponseHeader</a>, this function has no
--   effect. If the response headers have already been sent, causes a
--   <a>ResponseHeadersAlreadySent</a> exception. If the name is not a
--   possible name for a cookie, causes a <a>CookieNameInvalid</a>
--   exception.
unsetCookie :: MonadFastCGI m => String -> m ()

-- | Constructs a cookie with the given name and value. Version is set to
--   1; path, domain, and maximum age are set to <tt>Nothing</tt>; and the
--   secure flag is set to <tt>False</tt>. Constructing the cookie does not
--   cause it to be set; to do that, call <a>setCookie</a> on it.
mkSimpleCookie :: String -> String -> Cookie

-- | Constructs a cookie with the given parameters. Version is set to 1.
--   Constructing the cookie does not cause it to be set; to do that, call
--   <a>setCookie</a> on it.
mkCookie :: String -> String -> (Maybe String) -> (Maybe String) -> (Maybe Int) -> Bool -> Cookie

-- | Sets the HTTP/1.1 return status to 301 and sets the
--   <a>HttpLocation</a> header to the provided URL. This has the effect of
--   issuing a permanent redirect to the user agent. Permanent redirects,
--   as opposed to temporary redirects, may cause bookmarks or incoming
--   links to be updated. If the response headers have already been sent,
--   causes a <a>ResponseHeadersAlreadySent</a> exception.
permanentRedirect :: MonadFastCGI m => String -> m ()

-- | Sets the HTTP/1.1 return status to 303 and sets the
--   <a>HttpLocation</a> header to the provided URL. This has the effect of
--   issuing a see-other or <a>temporary</a> redirect to the user agent.
--   Temporary redirects, as opposed to permanent redirects, do not cause
--   bookmarks or incoming links to be updated. If the response headers
--   have already been sent, causes a <a>ResponseHeadersAlreadySent</a>
--   exception.
seeOtherRedirect :: MonadFastCGI m => String -> m ()

-- | Ensures that the response headers have been sent. If they are already
--   sent, does nothing. If output has already been closed, causes an
--   <a>OutputAlreadyClosed</a> exception.
sendResponseHeaders :: MonadFastCGI m => m ()

-- | Returns whether the response headers have been sent.
responseHeadersSent :: MonadFastCGI m => m Bool

-- | Sends data. This is the content data of the HTTP response. If the
--   response headers have not been sent, first sends them. If output has
--   already been closed, causes an <a>OutputAlreadyClosed</a> exception.
fPut :: MonadFastCGI m => ByteString -> m ()

-- | Sends text, encoded as UTF-8. This is the content data of the HTTP
--   response. if the response headers have not been sent, first sends
--   them. If output has already been closed, causes an
--   <a>OutputAlreadyClosed</a> exception.
fPutStr :: MonadFastCGI m => String -> m ()

-- | Informs the web server and the user agent that the request has
--   completed. As side-effects, the response headers are sent if they have
--   not yet been, and any unread input is discarded and no more can be
--   read. This is implicitly called, if it has not already been, after the
--   handler returns; it may be useful within a handler if the handler
--   wishes to return results and then perform time-consuming computations
--   before exiting. If output has already been closed, causes an
--   <a>OutputAlreadyClosed</a> exception.
fCloseOutput :: MonadFastCGI m => m ()

-- | Returns whether it is possible to write more data; ie, whether output
--   has not yet been closed as by <a>fCloseOutput</a>.
fIsWritable :: MonadFastCGI m => m Bool

-- | An exception originating within the FastCGI infrastructure or the web
--   server.
data FastCGIException

-- | An exception thrown by operations which require the response headers
--   not to have been sent yet.
ResponseHeadersAlreadySent :: FastCGIException

-- | An exception thrown by operations which produce output when output has
--   been closed, as by <a>fCloseOutput</a>.
OutputAlreadyClosed :: FastCGIException

-- | An exception thrown by operations which are given a header that does
--   not meet their requirement of being valid in a response.
NotAResponseHeader :: Header -> FastCGIException

-- | An exception thrown by operations which are given cookie names that do
--   not meet the appropriate syntax requirements.
CookieNameInvalid :: String -> FastCGIException

-- | Throw an exception in any <a>MonadFastCGI</a> monad.
fThrow :: (Exception e, MonadFastCGI m) => e -> m a

-- | Perform an action, with a given exception-handler action bound. See
--   <tt>Control.Exception.catch</tt>. The type of exception to catch is
--   determined by the type signature of the handler.
fCatch :: (Exception e, MonadFastCGI m) => m a -> (e -> m a) -> m a

-- | Block exceptions within an action, as per the discussion in
--   <tt>Control.Exception</tt>.
fBlock :: MonadFastCGI m => m a -> m a

-- | Unblock exceptions within an action, as per the discussion in
--   <tt>Control.Exception</tt>.
fUnblock :: MonadFastCGI m => m a -> m a

-- | Acquire a resource, perform computation with it, and release it; see
--   the description of <tt>Control.Exception.bracket</tt>. If an exception
--   is raised during the computation, <a>fBracket</a> will re-raise it
--   after running the release function, having the effect of propagating
--   the exception further up the call stack.
fBracket :: MonadFastCGI m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Perform an action, with a cleanup action bound to always occur; see
--   the description of <tt>Control.Exception.finally</tt>. If an exception
--   is raised during the computation, <a>fFinally</a> will re-raise it
--   after running the cleanup action, having the effect of propagating the
--   exception further up the call stack. If no exception is raised, the
--   cleanup action will be invoked after the main action is performed.
fFinally :: MonadFastCGI m => m a -> m b -> m a

-- | Perform an action. If any exceptions of the appropriate type occur
--   within the action, return <a>Left</a> <tt>exception</tt>; otherwise,
--   return <a>Right</a> <tt>result</tt>.
fTry :: (Exception e, MonadFastCGI m) => m a -> m (Either e a)

-- | As <a>fCatch</a>, but with the arguments in the other order.
fHandle :: (Exception e, MonadFastCGI m) => (e -> m a) -> m a -> m a

-- | Perform an action, with a cleanup action bound to occur if and only if
--   an exception is raised during the action; see the description of
--   <tt>Control.Exception.finally</tt>. If an exception is raised during
--   the computation, <a>fFinally</a> will re-raise it after running the
--   cleanup action, having the effect of propagating the exception further
--   up the call stack. If no exception is raised, the cleanup action will
--   not be invoked.
fOnException :: MonadFastCGI m => m a -> m b -> m a
instance Typeable FastCGIException
instance Show FastCGIException
instance Eq HeaderType
instance Show HeaderType
instance Eq Header
instance Ord Header
instance Eq RecordType
instance Show RecordType
instance Show Record
instance Show Cookie
instance Exception FastCGIException
instance Show Header
instance Enum RecordType
instance MonadFastCGI FastCGI