version 0.1.0.3: updated library; added documentation

Author: ozzzzz

README.md

@@ -1 +1,44 @@
 # web-template
+
+This is library that encapsulate settings and error-catching for REST-services.
+
+Convention, that are inside:
+
+* every route has the following structure: `HOST:PORT/v{PATH VERSION}/PATH`;
+* every path can be under authorization. Authorization means that server will look for the field `id` in Cookies.
+
+## Example
+
+Look for example in `add/Main.hs` file. To run simple server on port 5000 just run:
+```
+stack build
+stack exec web-template
+```
+
+Then you can ask server with curl requests:
+
+* not processing path:
+```
+>>> curl localhost:5000/abracadabra
+<h1>404: File Not Found!</h1>
+```
+
+* processing path with no authorization needed:
+```
+>>> curl localhost:5000/v1/ping
+Pong!
+Current environment: 0.%
+```
+
+* processing path with authorization without authorization:
+```
+>>> curl localhost:5000/v1/pong
+{"error":"Authorization failed"}
+```
+
+* processing path with authorization with authorization:
+```
+>>> curl localhost:5000/v1/pong --cookie "id=0000-0000-0000-000000000000"
+Ping!
+Authorised: 0000-0000-0000-000000000000.
+```

app/Main.hs

@@ -2,28 +2,27 @@
 
 module Main where
 
-import           Control.Monad.Reader (ask, lift, liftIO)
-import           Data.Text            (unpack)
+import           Control.Monad.Reader (ask, lift)
+import           Data.Text            (pack)
+import           Data.Text.Lazy       (fromStrict)
+import           Text.Printf          (printf)
 import           Web.Scotty.Trans     (get, text)
 import           Web.Template         (CustomWebServer (..), Process (..),
                                        Route (..), runWebServer)
 
 
-
 main :: IO ()
-main = let myState = True
-           myWebServer = CustomWebServer myState [ Route get 1 "/ping" pingR
-                                                 , Route get 1 "/pong" pongR
-                                                 ]
-       in runWebServer myWebServer
+main = runWebServer 5000 myWebServer
+  where env = 0
+        myWebServer = CustomWebServer env [ Route get 1 "/ping" pingR
+                                          , Route get 1 "/pong" pongR
+                                          ]
 
-pingR :: Process Bool
+pingR :: Process Int
 pingR = Process $ do
-    state <- lift ask
-    liftIO $ print state
-    text "Pong!"
+    env <- lift ask
+    text . fromStrict . pack $ printf "Pong!\nCurrent environment: %d." env
 
-pongR :: Process Bool
-pongR = AuthProcess $ \userId -> do
-  liftIO . print $ "Authorised: " ++ unpack userId
-  text "Ping!"
+pongR :: Process Int
+pongR = AuthProcess $ \userId ->
+    text . fromStrict . pack $ printf "Ping!\nAuthorised: %s." userId

src/Web/Template.hs

@@ -1,13 +1,11 @@
 module Web.Template
-  ( Route (..), WebM, CustomWebServer(..)
-  , UserId, Process (..)
-  , ServerConfig (..)
+  ( UserId, Port, Env, WebM, ScottyM
+  , CustomWebServer (..), Process (..), Route (..)
+  , runWebServer
   , JsonWebError (..)
-  , runWebServer, runWebServerConf
   ) where
 
-import           Web.Template.Server (CustomWebServer (..), Process (..),
-                                      Route (..), runWebServer,
-                                      runWebServerConf)
-import           Web.Template.Types  (UserId, WebM, ServerConfig (..))
-import           Web.Template.Except  (JsonWebError (..))
+import           Web.Template.Except (JsonWebError (..))
+import           Web.Template.Server (CustomWebServer (..), Env, Port,
+                                      Process (..), Route (..), ScottyM, UserId,
+                                      WebM, runWebServer)

src/Web/Template/Except.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE DeriveGeneric     #-}
+
 module Web.Template.Except
   ( Except (..), JsonWebError (..)
   , handleEx

src/Web/Template/Server.hs

@@ -2,12 +2,14 @@
 {-# LANGUAGE RecordWildCards   #-}
 
 module Web.Template.Server
-  ( CustomWebServer (..), Process (..), Route (..)
-  , runWebServerConf, runWebServer
+  ( UserId, Port, Env, WebM, ScottyM
+  , CustomWebServer (..), Process (..), Route (..)
+  , runWebServer
   ) where
 
-import           Control.Monad.Reader
+import           Control.Monad.Reader                 (ReaderT (..), runReaderT)
 import           Data.String                          (fromString)
+import           Data.Text                            as T (Text)
 import           Data.Text.Encoding                   (encodeUtf8)
 import           Data.Text.Lazy                       as TL (Text, toStrict)
 import           Network.HTTP.Types.Status            (status401, status405)
@@ -16,54 +18,69 @@ import           Network.Wai.Handler.Warp             (defaultSettings,
                                                        setOnExceptionResponse,
                                                        setPort)
 import           Network.Wai.Middleware.RequestLogger (logStdoutDev)
-import           Options.Generic                      (getRecord)
 import           Web.Cookie                           (parseCookiesText)
-import           Web.Scotty.Trans                     (Options (..),
+import           Web.Scotty.Trans                     (ActionT, Options (..),
                                                        RoutePattern, ScottyT,
                                                        defaultHandler, header,
                                                        json, middleware, param,
                                                        scottyOptsT, status)
-import           Web.Template.Except                  (Except, JsonWebError (..),
+import           Web.Template.Except                  (Except,
+                                                       JsonWebError (..),
                                                        handleEx)
-import           Web.Template.Types                   (ServerConfig (..), ScottyM,
-                                                       UserId, WebM)
 
+-- | Alias for UserId.
+type UserId = T.Text
 
+-- | Alias for Port.
+type Port = Int
 
+-- | Alias for environment.
+type Env env = ReaderT env IO
+
+-- | Alias for Web monad. Incapsulates 'Web.Scotty.Trans.ActionT'.
+type WebM env a = ActionT Except (Env env) a
+
+-- | Alias for Scotty monad. Encapsulates 'Web.Scotty.Trans.ScottyT'
+type ScottyM env a = ScottyT Except (Env env) a
+
+-- | 'Process' encapsulates what we what to do inside 'Route'.
+--   If your need to check authorization then use 'AuthProcess' constructor.
 data Process s = Process (WebM s ())
                | AuthProcess (UserId -> WebM s ())
 
-data Route s = Route { method :: RoutePattern -> WebM s () -> ScottyT Except (ReaderT s IO) ()
-                     , version :: Int
-                     , path :: String
-                     , process :: Process s
-                     }
+-- | 'Route' include every needed information to make some stuff with request. It includes:
+-- * environment @env@ that we can store and use (for example, connections for databases);
+-- * method (like POST or GET);
+-- * version of path (it should be like `/v{Integer}/`);
+-- * path (just name of path);
+-- * process (what should we do with request).
+data Route env = Route { method  :: RoutePattern -> WebM env () -> ScottyT Except (Env env) ()
+                       , version :: Int
+                       , path    :: String
+                       , process :: Process env
+                       }
 
-data CustomWebServer s = CustomWebServer { initialState :: s
-                                         , routes       :: [Route s]
-                                         }
+-- | Contains environment and processing routes.
+data CustomWebServer env = CustomWebServer { environment :: env
+                                           , routes      :: [Route env]
+                                           }
 
-runWebServerConf :: ServerConfig -> CustomWebServer s -> IO ()
-runWebServerConf conf CustomWebServer{..} = scottyOptsT (scottyOpts conf) (`runReaderT` initialState) $ do
+-- | For given port and server settings run the server.
+runWebServer :: Port -> CustomWebServer env -> IO ()
+runWebServer port CustomWebServer{..} = scottyOptsT (scottyOpts port) (`runReaderT` environment) $ do
     middleware logStdoutDev
     defaultHandler handleEx
     mapM_ runRoute routes
 
-runWebServer :: CustomWebServer s -> IO ()
-runWebServer cws = do
-    conf <- getRecord "Web template"
-    runWebServerConf conf cws
-
-runRoute :: Route s -> ScottyM s ()
+runRoute :: Route env -> ScottyM env ()
 runRoute Route{..} = method (fromString $ "/:version" ++ path) (checkVersion version . auth $ process)
 
-
-scottyOpts :: ServerConfig -> Options
-scottyOpts ServerConfig{..} = Options 1 warpSettings
+scottyOpts :: Port -> Options
+scottyOpts port = Options 1 warpSettings
   where warpSettings = setOnExceptionResponse exceptionResponseForDebug .
                        setPort port $ defaultSettings
 
-auth :: Process s -> WebM s ()
+auth :: Process env -> WebM env ()
 auth (Process p) = p
 auth (AuthProcess p) = do
     cookiesM <- header "Cookie"
@@ -73,13 +90,13 @@ auth (AuthProcess p) = do
         Nothing -> do status status401
                       json . JsonWebError $ "Authorization failed"
 
-checkVersion :: Int -> WebM s () -> WebM s ()
+checkVersion :: Int -> WebM env () -> WebM env ()
 checkVersion version route = do
     versionPath <- param "version" :: WebM s String
     if "v" ++ show version == versionPath
       then route
       else do status status405
-              json . JsonWebError $  "Server API version: " ++ show version ++ "; got version: " ++ versionPath
+              json . JsonWebError $ "Server API version: " ++ show version ++ "; got version: " ++ versionPath
 
 getIdFromCookies :: TL.Text -> Maybe UserId
 getIdFromCookies cookies = lookup "id" $ parseCookiesText $ encodeUtf8 $ toStrict cookies

src/Web/Template/Types.hs

@@ -1,4 +1,14 @@
-resolver: lts-9.3
+# before building, don`t forget to delete the cache file ~/.stack/custom-plan/yaml/
+
+resolver: https://lts.math.bio/bcd-lts-dev.yaml
+
+package-indices:
+- name: LTS-index
+  download-prefix: https://hackage.math.bio/hackage.fpcomplete.com/package/
+  http: https://hackage.math.bio/hackage.fpcomplete.com/00-index.tar.gz
+- name: Hackage Biocad
+  download-prefix: http://hackage.biocad.ru/package/
+  http: http://hackage.biocad.ru/00-index.tar.gz
 
 packages:
 - .
@@ -8,3 +18,8 @@ extra-deps: []
 flags: {}
 
 extra-package-dbs: []
+
+ignore-revision-mismatch: true
+
+ghc-options:
+  $locals: -Wall -fdiagnostics-color=always

stack.yaml

@@ -1,5 +1,5 @@
 name:                web-template
-version:             0.1.0.2
+version:             0.1.0.3
 synopsis:            Web template
 description:
             Web template includes:
@@ -22,7 +22,6 @@ library
   hs-source-dirs:      src
   exposed-modules:     Web.Template
   other-modules:       Web.Template.Except
-                     , Web.Template.Types
                      , Web.Template.Server
   build-depends:       base >= 4.7 && < 5
                      , scotty