-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Library for building servers with IterIO -- -- This module contains a set of generic building blocks for building -- servers with IterIO. @package iterio-server @version 0.3 -- | Generic building blocks for creating TCP Servers based on -- IterIO module Data.IterIO.Server.TCPServer -- | TCPServer holds all the information necessary to run bind to a -- sock and respond to TCP requests from the network. data TCPServer inp m TCPServer :: PortNumber -> Inum inp inp m () -> (Socket -> m (Iter inp m (), Onum inp m ())) -> (m () -> IO ()) -> TCPServer inp m -- | The TCP port the server will listen for incomming connections on. serverPort :: TCPServer inp m -> PortNumber -- | This Inum implements the actual functionality of the server. -- The input and output of the Inum correspond to the input and -- output of the socket. serverHandler :: TCPServer inp m -> Inum inp inp m () -- | A function to transform an accept incomming connection into an iter -- and onum. Most servers should just use defaultSocketAcceptor -- but this can be used for special cases, e.g. accepting SSL connections -- with iterSSL. serverAcceptor :: TCPServer inp m -> Socket -> m (Iter inp m (), Onum inp m ()) -- | Must execute the monadic result. Servers operating in the IO -- Monad can use id. serverResultHandler :: TCPServer inp m -> m () -> IO () -- | Runs a TCPServer in a loop. runTCPServer :: (ListLikeIO inp e, ChunkData inp, Monad m) => TCPServer inp m -> IO () -- | This acceptor creates an Iter and Onum using -- handleI and enumHandle respectively. defaultServerAcceptor :: (ListLikeIO inp e, ChunkData inp, MonadIO m) => Socket -> m (Iter inp m (), Onum inp m a) -- | For convenience, a TCPServer in the IO Monad with null -- defaults: -- -- minimalTCPServer :: (ListLikeIO inp e, ChunkData inp) => TCPServer inp IO -- | Creates a simple HTTP server from an HTTPRequestHandler. simpleHttpServer :: PortNumber -> HttpRequestHandler IO () -> TCPServer ByteString IO -- | Creates a TCPServer that echoes each line from the client until -- EOF. echoServer :: PortNumber -> TCPServer String IO instance Show (TCPServer inp m) -- | Defines the Action monad which abstracts some of the details of -- handling HTTP requests with IterIO. module Data.IterIO.Http.Support.Action -- | A StateT monad in which requests can be handled. It keeps track -- of the HttpReq, the form parameters from the request body and -- an HttpResp used to reply to the client. type Action t b m a = StateT (ActionState t b m) m a data ActionState t b m ActionState :: HttpReq t -> HttpResp m -> [Param] -> b -> ActionState t b m actionReq :: ActionState t b m -> HttpReq t actionResp :: ActionState t b m -> HttpResp m actionParams :: ActionState t b m -> [Param] actionBody :: ActionState t b m -> b -- | A request parameter from a form field in the HTTP body data Param Param :: ByteString -> ByteString -> [(ByteString, ByteString)] -> Param paramKey :: Param -> ByteString paramValue :: Param -> ByteString -- | Header of a multipart/form-data post paramHeaders :: Param -> [(ByteString, ByteString)] -- | Returns a list of all Params. params :: Monad m => Action t b m [Param] -- | Returns the Param corresponding to the specified key or -- Nothing if one is not present in the request. param :: Monad m => ByteString -> Action t b m (Maybe Param) -- | Force get parameter value paramVal :: Monad m => ByteString -> Action t b m (ByteString) -- | Get (maybe) paramater value and transform it with f paramValM :: Monad m => (ByteString -> a) -> ByteString -> Action t b m (Maybe a) -- | Set the list of Params. setParams :: Monad m => [Param] -> Action t b m [Param] -- | Returns the body of the current request. getBody :: Monad m => Action t b m b -- | Returns the HttpReq for the current request. getHttpReq :: Monad m => Action t b m (HttpReq t) -- | Sets a the value for "_sess" in the cookie to the given string. setSession :: Monad m => String -> Action t b m () -- | Removes the "_sess" key-value pair from the cookie. destroySession :: Monad m => Action t b m () -- | Returns the value of an Http Header from the request if it exists -- otherwise Nothing requestHeader :: Monad m => ByteString -> Action t b m (Maybe ByteString) instance [safe] Show Param -- | Utility functions for responding to HTTP requests from within an -- Action. module Data.IterIO.Http.Support.Responses -- | Responds to the client with a 200 (Success) response with the -- given body and mime-type. render :: Monad m => String -> ByteString -> Action t b m () -- | Responds to the client with a 303 (Temporary Redirect) -- response to the given path. redirectTo :: Monad m => String -> Action t b m () -- | Redirect "back" according to the "referer" header. redirectBack :: Monad m => Action t b m () -- | Responds to the client with an empty 404 (Not Found) -- response. respond404 :: Monad m => Action t b m () -- | Replaces the HTTP status in the current HttpResp with the given -- HttpStatus. respondStat :: Monad m => HttpStatus -> Action t b m () -- | Utility functions for routing. module Data.IterIO.Http.Support.Routing -- | An ActionRoute either matches an HttpReq and returns a -- corresponding Action that responds to it, or Nothing -- signifying, no approriate Action was found. -- ActionRoutes can be strung together with, e.g., -- mappend such that each will be searched in turn until an -- Action responding to the HttpReq is found. newtype ActionRoute b m s ActionRoute :: (HttpReq s -> m (Maybe (Action s b m ()))) -> ActionRoute b m s -- | Runs an ActionRoute. If it satisfies the request, the -- underlying Action is returned, otherwise an Action -- responding with HTTP 404 (Not Found) is returned instead. Can be used -- at the top of a request handler, for example: -- -- 
--   httpHandler :: Action b m ()
--   httpHandler = runActionRoute $ mconcat [
--       routeTop $ routeAction homeAction
--     , routeMethod "POST" $ routeAction handleForm
--     , routeMethod "GET" $ routeAction showForm
--     ]
--
-- -- But also can be nested inside of another action to created nested -- routes, or state dependant routes: -- -- 
--   httpHandler :: Action b m ()
--   httpHandler = runActionRoute $ mconcat [
--       routeTop $ routeAction homeAction
--     , routeName "foo" $ routeAction $ runActionRoute $ mconcat [
--           routeMethod "GET" $ runAction showForm
--         , routeMethod "POST" $ runAction handleForm
--         ]
--     ]
--
-- -- or -- -- 
--   handleForm = do
--     day <- lift $ getDayOfWeek
--     case mod day 2 of
--       0 -> runActionRoute $ routeName "stts" $ routeAction doRes
--       1 -> runActionRoute $ routeName "mwf" $ routeAction doRes
--
runActionRoute :: Monad m => ActionRoute b m s -> Action s b m () -- | Like runAction but consumes the rest of the request for the -- body runIterAction :: Monad m => Action s ByteString m a -> HttpReq s -> Iter ByteString m (HttpResp m) -- | Runs an Action given an HttpReq and body. Returns the -- HttpResp generated by the Action. runAction :: Monad m => Action s b m a -> HttpReq s -> b -> m (HttpResp m) -- | Routes an Action routeAction :: Monad m => Action t b m () -> ActionRoute b m t -- | Routes an Action to the given URL pattern. Patterns can include -- directories as well as variable patterns (prefixed with :) to -- be passed into the Action as extra Params. Some examples -- of URL patters: -- -- routePattern :: Monad m => String -> ActionRoute b m t -> ActionRoute b m t -- | Routes a specific directory name, like routeMap for a -- singleton map. routeName :: Monad m => String -> ActionRoute b m s -> ActionRoute b m s -- | Matches any directory name, but additionally pushes it onto the front -- of the reqPathParams list in the HttpReq structure. This -- allows the name to serve as a variable argument to the eventual -- handling function. routeVar :: Monad m => ActionRoute b m s -> ActionRoute b m s -- | Match request with path "/". routeTop :: Monad m => ActionRoute b m s -> ActionRoute b m s -- | Match requests with the given method ("GET", "POST", etc). routeMethod :: Monad m => String -> ActionRoute b m s -> ActionRoute b m s routeFileSys :: (String -> ByteString) -> FilePath -> ActionRoute b IO t instance [safe] Monad m => Monoid (ActionRoute b m s) -- | This module defines the RestController class module Data.IterIO.Http.Support.RestController -- | The class RestController allows a set of actions to be routed -- using RESTful HTTP verbs. class Monad m => RestController t b m a where restIndex _ = respond404 restShow _ _ = respond404 restNew _ = respond404 restCreate _ = respond404 restEdit _ _ = respond404 restUpdate _ _ = respond404 restDestroy _ _ = respond404 restIndex :: RestController t b m a => a -> Action t b m () restShow :: RestController t b m a => a -> ByteString -> Action t b m () restNew :: RestController t b m a => a -> Action t b m () restCreate :: RestController t b m a => a -> Action t b m () restEdit :: RestController t b m a => a -> ByteString -> Action t b m () restUpdate :: RestController t b m a => a -> ByteString -> Action t b m () restDestroy :: RestController t b m a => a -> ByteString -> Action t b m () -- | Routes URLs under the given String to actions in a -- RestController. For example -- -- 
--   routeRestController posts myRestController
--
-- -- will map the follwoing URLs: -- -- routeRestController :: RestController t b m a => String -> a -> ActionRoute b m t module Data.IterIO.Http.Support.Utils -- | For Actions where the body type is a ByteString, parse -- the body with 'parseParams\'' and prepend the result to the -- Action's Params parseParams :: Monad m => Action t ByteString m [Param] -- | Parse url encoded or form encoded paramters from an HTTP body. parseParams' :: Monad m => HttpReq a -> ByteString -> m [Param] module Data.IterIO.Http.Support