599 lines
26 KiB
Plaintext
599 lines
26 KiB
Plaintext
---
|
|
tags:
|
|
- Haskell
|
|
- Tutorial
|
|
categories:
|
|
- Haskell
|
|
- Tutorial
|
|
title: Webapp-Development in Haskell
|
|
abstract: |
|
|
Step-by-Step-Anleitung, wie man ein neues Projekt mit einer bereits erprobten Pipeline erstellt.
|
|
execute:
|
|
eval: false
|
|
date: 2020-04-01
|
|
---
|
|
|
|
## Definition der API
|
|
|
|
Erster Schritt ist immer ein wünsch-dir-was bei der Api-Defenition.
|
|
|
|
Die meisten Services haben offensichtliche Anforderungen (Schnittstellen nach
|
|
draußen, Schnittstellen intern, ...). Diese kann man immer sehr gut in einem
|
|
`Request -> Response`-Model erfassen.
|
|
|
|
Um die Anforderungen und Möglichkeiten des jeweiligen Services sauber zu
|
|
erfassen und automatisiert zu prüfen, dummy-implementationen zu bekommen und
|
|
vieles andere mehr, empfiehlt es sich den
|
|
**Openapi-generator** zu nutzen.
|
|
|
|
Diese Definition läuft über openapi-v3 und kann z.b. mit Echtzeit-Vorschau im
|
|
<http://editor.swagger.io/> erspielen. Per Default ist der noch auf openapi-v2
|
|
(aka swagger), kann aber auch v3.
|
|
|
|
Nach der Definition, was man am Ende haben möchte, muss man sich entscheiden, in
|
|
welcher Sprache man weiter entwickelt. Ich empfehle aus verschiedenen Gründen
|
|
primär 2 Sprachen: Python-Microservices (weil die ML-Libraries sehr gut sind,
|
|
allerdings Änderungen meist schwer sind und der Code wenig robust - meist nur 1
|
|
API-Endpunkt pro service) und Haskell (Stabilität, Performace, leicht zu ändern,
|
|
gut anzupassen).
|
|
|
|
Im folgenden wird (aus offensichtlichen Gründen) nur auf das Haskell-Projekt
|
|
eingegangen.
|
|
|
|
## Startprojekt in Haskell
|
|
|
|
### Erstellen eines neuen Projektes
|
|
|
|
Zunächst erstellen wir in normales Haskell-Projekt ohne Funktionalität &
|
|
Firlefanz:
|
|
|
|
```{.bash}
|
|
stack new myservice
|
|
```
|
|
|
|
Dies erstellt ein neues Verzeichnis und das generelle scaffolding. Nach einer
|
|
kurzen Anpassung der `stack.yaml` (resolver auf unserer setzen; aktuell:
|
|
`lts-17.4`) fügen wir am Ende der Datei
|
|
|
|
```{.yaml}
|
|
allow-newer: true
|
|
ghc-options:
|
|
"$locals": -fwrite-ide-info
|
|
```
|
|
|
|
ein. Anschließend organisieren™ wir uns noch eine gute `.gitignore` und
|
|
initialisieren das git mittels
|
|
`git init; git add .; git commit -m "initial scaffold"`
|
|
|
|
### Generierung der API
|
|
|
|
Da die API immer wieder neu generiert werden kann (und sollte!) liegt sich in
|
|
einem unterverzeichnis des Hauptprojektes.
|
|
|
|
Initial ist es das einfachste ein leeres temporäres Verzeichnis woanders zu
|
|
erstellen, die `api-doc.yml` hinein kopieren und folgendes ausführen:
|
|
|
|
```{.bash}
|
|
openapi-generator generate -g haskell -o . -i api-doc.yml
|
|
```
|
|
|
|
Dieses erstellt einem dann eine komplette library inkl. Datentypen. Wichtig: Der
|
|
Name in der `api-doc` sollte vom Namen des Services (oben `myservice`)
|
|
abweichen - entweder in Casing oder im Namen direkt. Suffixe wie API schneidet
|
|
der Generator hier leider ab. (Wieso das ganze? Es entstehen nachher 2
|
|
libraries, `foo` & `fooAPI`. Da der generator das API abschneidet endet man mit
|
|
foo & foo und der compiler meckert, dass er nicht weiß, welche lib gemeint ist).
|
|
|
|
danach: wie gewohnt `git init; git add .; git commit -m "initial"`. Auf dem
|
|
Server der Wahl (github, gitea, gitlab, ...) nun ein Repository erstellen (am
|
|
Besten: `myserviceAPI` - nach Konvention ist alles auf API endend
|
|
autogeneriert!) und den Anweisungen nach ein remote hinzufügen & pushen.
|
|
|
|
#### Wieder zurück im Haskell-Service
|
|
|
|
In unserem eigentlichen Service müssen wir nun die API einbinden. Dazu erstellen
|
|
wir ein Verzeichnis `libs` (Konvention) und machen ein
|
|
`git submodule add <repository-url> libs/myserviceAPI`
|
|
|
|
Git hat nun die API in das submodul gepackt und wir können das oben erstellte
|
|
temporäre Verzeichnis wieder löschen.
|
|
|
|
Anschließend müssen wir stack noch erklären, dass wir die API da nun liegen
|
|
haben und passen wieder die `stack.yaml` an, indem wir das Verzeichnis unter
|
|
packages hinzufügen.
|
|
|
|
```{.yaml}
|
|
packages:
|
|
- .
|
|
- libs/myserviceAPI # <<
|
|
```
|
|
|
|
Nun können wir in der `package.yaml` (oder `myservice.cabal`, falls kein `hpack`
|
|
verwendet wird) unter den dependencies unsere API hinzufügen (name wie die
|
|
cabal-Datei in `libs/myserviceAPI`).
|
|
|
|
### Einbinden anderer Microservices
|
|
|
|
Funktioniert komplett analog zu dem vorgehen oben (ohne das generieren natürlich
|
|
:grin:). `stack.yaml` editieren und zu den packages hinzufügen:
|
|
|
|
```{.yaml}
|
|
packages:
|
|
- .
|
|
- libs/myserviceAPI
|
|
- libs/myCoolMLServiceAPI
|
|
```
|
|
|
|
in der `package.yaml` (oder der cabal) die dependencies hinzufügen und schon
|
|
haben wir die Features zur Verfügung und können gegen diese Services reden.
|
|
|
|
### Entfernen von anderen Technologien/Microservices
|
|
|
|
In git ist das entfernen von Submodules etwas frickelig, daher hier ein
|
|
copy&paste der
|
|
[GitHub-Antwort](https://gist.github.com/myusuf3/7f645819ded92bda6677):
|
|
|
|
```{.bash}
|
|
## Remove the submodule entry from .git/config
|
|
git submodule deinit -f path/to/submodule
|
|
|
|
## Remove the submodule directory from the superproject's .git/modules directory
|
|
rm-rf .git/modules/path/to/submodule
|
|
|
|
## Remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule
|
|
git rm-f path/to/submodule
|
|
```
|
|
|
|
Falls das nicht klappt, gibt es alternative Vorschläge unter dem Link oben.
|
|
|
|
### Woher weiss ich, was wo liegt? Dokumentation? Halloo??
|
|
|
|
Keine Panik. Ein `stack haddock --open` hilft da. Das generiert die
|
|
Dokumentation für alle in der `package.yaml` (oder cabal-file) eingetragenen
|
|
dependencies inkl. aller upstream-dependencies. Man bekommt also eine komplette
|
|
lokale Dokumentation von allem. Geöffnet wird dann die Paket-Startseite inkl.
|
|
der direkten dependencies:
|
|
|
|
Es gibt 2 wichtige Pfade im Browser:
|
|
|
|
- `...../all/index.html` - hier sind alle Pakete aufgeführt
|
|
- `...../index.html` - hier sind nur die direkten dependencies aufgeführt.
|
|
|
|
Wenn man einen lokalen Webserver startet kann man mittels "s" auch die
|
|
interaktive Suche öffnen (Suche nach Typen, Funktionen, Signaturen, etc.). In
|
|
Bash mit `python3` geht das z.b. einfach über:
|
|
|
|
```{.bash}
|
|
cd $(stack path --local-doc-root)
|
|
python3 -m SimpleHTTPServer 8000
|
|
firefox "http://localhost:8000"
|
|
```
|
|
|
|
### Implementation des Services und Start
|
|
|
|
#### Loader/Bootstrapper
|
|
|
|
Generelles Vorgehen:
|
|
|
|
- in `app/Main.hs`: Hier ist quasi immer nur eine Zeile drin:
|
|
`main = myServiceMain`
|
|
|
|
Grund: Applications tauchen nicht im Haddock auf. Also haben wir ein
|
|
"src"-Modul, welches hier nur geladen & ausgeführt wird.
|
|
|
|
- in `src/MyService.hs`: `myServiceMain :: IO ()` definieren
|
|
|
|
Für die Main kann man prinzipiell eine Main andere Services copy/pasten. Im
|
|
folgenden eine Annotierte main-Funktion - zu den einzelnen Voraussetzungen
|
|
kommen wir im Anschluss.
|
|
|
|
{{< dstart summary="Main.hs anzeigen" >}}
|
|
|
|
```{.haskell code-fold=true code-summary="Code anzeigen"}
|
|
{-# OPTIONS_GHC -Wno-name-shadowing #-}
|
|
{-# LANGUAGE FlexibleContexts #-}
|
|
{-# LANGUAGE LambdaCase #-}
|
|
{-# LANGUAGE OverloadedStrings #-}
|
|
{-# LANGUAGE RankNTypes #-}
|
|
{-# LANGUAGE RecordWildCards #-}
|
|
{-# LANGUAGE ScopedTypeVariables #-}
|
|
module MyService where
|
|
|
|
-- generische imports aus den dependencies/base, nicht in der prelude
|
|
import Codec.MIME.Type
|
|
import Configuration.Dotenv as Dotenv
|
|
import Control.Concurrent (forkIO, threadDelay)
|
|
import Control.Concurrent.Async
|
|
import Control.Concurrent.STM
|
|
import Control.Monad
|
|
import Control.Monad.Catch
|
|
import Control.Monad.Except
|
|
import Conversion
|
|
import Conversion.Text ()
|
|
import Data.Binary.Builder
|
|
import Data.String (IsString (..))
|
|
import Data.Time
|
|
import Data.Time.Clock
|
|
import Data.Time.Format
|
|
import Data.Default
|
|
import Network.HostName
|
|
import Network.HTTP.Client as HTTP hiding
|
|
(withConnection)
|
|
import Network.HTTP.Types (Status, statusCode)
|
|
import Network.Mom.Stompl.Client.Queue
|
|
import Network.Wai (Middleware)
|
|
import Network.Wai.Logger
|
|
import Network.Wai.Middleware.Cors
|
|
import Network.Wai.Middleware.RequestLogger (OutputFormat (..),
|
|
logStdout,
|
|
mkRequestLogger,
|
|
outputFormat)
|
|
import Servant.Client (mkClientEnv,
|
|
parseBaseUrl)
|
|
import System.Directory
|
|
import System.Envy
|
|
import System.IO
|
|
import System.Log.FastLogger
|
|
import Text.PrettyPrint.GenericPretty
|
|
|
|
-- generische imports, aber qualified, weil es sonst zu name-clashes kommt
|
|
|
|
import qualified Data.ByteString as BS
|
|
-- import qualified Data.ByteString.Char8 as BS8
|
|
import qualified Data.ByteString.Lazy as LBS
|
|
import qualified Network.HTTP.Client.TLS as UseDefaultHTTPSSettings (tlsManagerSettings)
|
|
import qualified Network.Mom.Stompl.Client.Queue as AMQ
|
|
import qualified Network.Wai as WAI
|
|
|
|
-- Handler für den MyServiceBackend-Typen und Imports aus den Libraries
|
|
import MyService.Handler as H -- handler der H.myApiEndpointV1Post implementiert
|
|
import MyService.Types -- weitere Type (s. nächste box)
|
|
import MyServiceGen.API as MS -- aus der generierten library
|
|
|
|
|
|
myServicemain :: IO ()
|
|
myServicemain = do
|
|
-- .env-Datei ins Prozess-Environment laden, falls noch nicht von außen gesetzt
|
|
void $ loadFile $ Dotenv.Config [".env"] [] False
|
|
-- Config holen (defaults + overrides aus dem Environment)
|
|
sc@ServerConfig{..} <- decodeWithDefaults defConfig
|
|
-- Backend-Setup
|
|
-- legt sowas wie Proxy-Server fest und wo man wie dran kommt. Benötigt für das Sprechen mit anderen Microservices
|
|
let defaultHTTPSSettings = UseDefaultHTTPSSettings.tlsManagerSettings { managerResponseTimeout = responseTimeoutMicro $ 1000 * 1000 * myserviceMaxTimeout }
|
|
createBackend url proxy = do
|
|
manager <- newManager . managerSetProxy proxy
|
|
$ defaultHTTPSSettings
|
|
url' <- parseBaseUrl url
|
|
return (mkClientEnv manager url')
|
|
internalProxy = case myserviceInternalProxyUrl of
|
|
"" -> noProxy
|
|
url -> useProxy $ HTTP.Proxy (fromString url) myserviceInternalProxyPort
|
|
-- externalProxy = case myserviceExternalProxyUrl of
|
|
-- "" -> noProxy
|
|
-- url -> useProxy $ HTTP.Proxy (fromString url) myserviceExternalProxyPort
|
|
|
|
-- Definieren & Erzeugen der Funktionen um die anderen Services anzusprechen.
|
|
calls <- (,)
|
|
<$> createBackend myserviceAUri internalProxy
|
|
<*> createBackend myserviceBUri internalProxy
|
|
|
|
-- Logging-Setup
|
|
hSetBuffering stdout LineBuffering
|
|
hSetBuffering stderr LineBuffering
|
|
|
|
|
|
-- Infos holen, brauchen wir später
|
|
myName <- getHostName
|
|
today <- formatTime defaultTimeLocale "%F" . utctDay <$> getCurrentTime
|
|
|
|
|
|
-- activeMQ-Transaktional-Queue zum schreiben nachher vorbereiten
|
|
amqPost <- newTQueueIO
|
|
|
|
|
|
-- bracket a b c == erst a machen, ergebnis an c als variablen übergeben. Schmeisst c ne exception/wird gekillt/..., werden die variablen an b übergeben.
|
|
bracket
|
|
-- logfiles öffnen
|
|
(LogFiles <$> openFile ("/logs/myservice-"<>myName<>"-"<>today<>".info") AppendMode
|
|
<*> openFile (if myserviceDebug then "/logs/myservice-"<>myName<>"-"<>today<>".debug" else "/dev/null") AppendMode
|
|
<*> openFile ("/logs/myservice-"<>myName<>"-"<>today<>".error") AppendMode
|
|
<*> openFile ("/logs/myservice-"<>myName<>"-"<>today<>".timings") AppendMode
|
|
)
|
|
-- und bei exception/beendigung schlißen.h
|
|
(\(LogFiles a b c d) -> mapM_ hClose [a,b,c,d])
|
|
$ \logfiles -> do
|
|
|
|
|
|
-- logschreibe-funktionen aliasen; log ist hier abstrakt, iolog spezialisiert auf io.
|
|
let log = printLogFiles logfiles :: MonadIO m => [LogItem] -> m ()
|
|
iolog = printLogFilesIO logfiles :: [LogItem] -> IO ()
|
|
|
|
|
|
-- H.myApiEndpointV1Post ist ein Handler (alle Handler werden mit alias H importiert) und in einer eigenen Datei
|
|
-- Per Default bekommen Handler sowas wie die server-config, die Funktionen um mit anderen Services zu reden, die AMQ-Queue um ins Kibana zu loggen und eine Datei-Logging-Funktion
|
|
-- Man kann aber noch viel mehr machen - z.b. gecachte Daten übergeben, eine Talk-Instanz, etc. pp.
|
|
server = MyServiceBackend{ myApiEndpointV1Post = H.myApiEndpointV1Post sc calls amqPost log
|
|
}
|
|
config = MS.Config $ "http://" ++ myserviceHost ++ ":" ++ show myservicePort ++ "/"
|
|
iolog . pure . Info $ "Using Server configuration:"
|
|
iolog . pure . Info $ pretty sc { myserviceActivemqPassword = "******" -- Do NOT log the password ;)
|
|
, myserviceMongoPassword = "******"
|
|
}
|
|
-- alle Services starten (Hintergrund-Aktionen wie z.b. einen MongoDB-Dumper, einen Talk-Server oder wie hier die ActiveMQ
|
|
void $ forkIO $ keepActiveMQConnected sc iolog amqPost
|
|
-- logging-Framework erzeugen
|
|
loggingMW <- loggingMiddleware
|
|
-- server starten
|
|
if myserviceDebug
|
|
then runMyServiceMiddlewareServer config (cors (\_ -> Just (simpleCorsResourcePolicy {corsRequestHeaders = ["Content-Type"]})) . loggingMW . logStdout) server
|
|
else runMyServiceMiddlewareServer config (cors (\_ -> Just (simpleCorsResourcePolicy {corsRequestHeaders = ["Content-Type"]}))) server
|
|
|
|
|
|
-- Sollte bald in die Library hs-stomp ausgelagert werden
|
|
-- ist ein Beispiel für einen ActiveMQ-Dumper
|
|
keepActiveMQConnected :: ServerConfig -> ([LogItem] -> IO ()) -> TQueue BS.ByteString -> IO ()
|
|
keepActiveMQConnected sc@ServerConfig{..} printLog var = do
|
|
res <- handle (\(e :: SomeException) -> do
|
|
printLog . pure . Error $ "Exception in AMQ-Thread: "<>show e
|
|
return $ Right ()
|
|
) $ AMQ.try $ do -- catches all AMQ-Exception that we can handle. All others bubble up.
|
|
printLog . pure . Info $ "AMQ: connecting..."
|
|
withConnection myserviceActivemqHost myserviceActivemqPort [ OAuth myserviceActivemqUsername myserviceActivemqPassword
|
|
, OTmo (30*1000) {- 30 sec timeout -}
|
|
]
|
|
[] $ \c -> do
|
|
let oconv = return
|
|
printLog . pure . Info $ "AMQ: connected"
|
|
withWriter c "Chaos-Logger for Kibana" "chaos.logs" [] [] oconv $ \writer -> do
|
|
printLog . pure . Info $ "AMQ: queue created"
|
|
let postfun = writeQ writer (Type (Application "json") []) []
|
|
void $ race
|
|
(forever $ atomically (readTQueue var) >>= postfun)
|
|
(threadDelay (600*1000*1000)) -- wait 10 Minutes
|
|
-- close writer
|
|
-- close connection
|
|
-- get outside of all try/handle/...-constructions befor recursing.
|
|
case res of
|
|
Left ex -> do
|
|
printLog . pure . Error $ "AMQ: "<>show ex
|
|
keepActiveMQConnected sc printLog var
|
|
Right _ -> keepActiveMQConnected sc printLog var
|
|
|
|
|
|
-- Beispiel für eine Custom-Logging-Middleware.
|
|
-- Hier werden z.B. alle 4xx-Status-Codes inkl. Payload ins stdout-Log geschrieben.
|
|
-- Nützlich, wenn die Kollegen ihre Requests nicht ordentlich schreiben können und der Server das Format zurecht mit einem BadRequest ablehnt ;)
|
|
loggingMiddleware :: IO Middleware
|
|
loggingMiddleware = liftIO $ mkRequestLogger $ def { outputFormat = CustomOutputFormatWithDetails out }
|
|
where
|
|
out :: ZonedDate -> WAI.Request -> Status -> Maybe Integer -> NominalDiffTime -> [BS.ByteString] -> Builder -> LogStr
|
|
out _ r status _ _ payload _
|
|
| statusCode status < 300 = ""
|
|
| statusCode status > 399 && statusCode status < 500 = "Error code "<>toLogStr (statusCode status) <>" sent. Request-Payload was: "<> mconcat (toLogStr <$> payload) <> "\n"
|
|
| otherwise = toLogStr (show r) <> "\n"
|
|
|
|
```
|
|
|
|
{{< dend >}}
|
|
|
|
#### Weitere Instanzen und Definitionen, die der Generator (noch) nicht macht
|
|
|
|
In der `Myservice.Types` werden ein paar hilfreiche Typen und Typ-Instanzen
|
|
definiert. Im Folgenden geht es dabei um Dinge für:
|
|
|
|
- `Envy`
|
|
- Laden von `$ENV_VAR` in Datentypen
|
|
- Definitionen für Default-Settings
|
|
- `ServerConfig`
|
|
- Definition der Server-Konfiguration & Benennung der Environment-Variablen
|
|
- `ExtraTypes`
|
|
- ggf. Paketweite extra-Typen, die der Generator nicht macht, weil sie nicht
|
|
aus der API kommen (z.B. cache)
|
|
- `Out`/`BSON`-Instanzen
|
|
- Der API-Generator generiert nur wenige Instanzen automatisch (z.B. `aeson`),
|
|
daher werden hier die fehlenden definiert.
|
|
- `BSON`: Kommunikation mit `MongoDB`
|
|
- `Out`: pretty-printing im Log
|
|
- Nur nötig, wenn man pretty-printing via `Out` statt über Generics wie z.b.
|
|
`pretty-generic` oder die automatische Show-Instanz via `prerryShow`
|
|
macht.
|
|
|
|
{{< dstart summary="Types.hs anzeigen" >}}
|
|
|
|
```{.haskell}
|
|
{-# OPTIONS_GHC -Wno-orphans #-}
|
|
{-# OPTIONS_GHC -Wno-name-shadowing #-}
|
|
{-# LANGUAGE DeriveAnyClass #-}
|
|
{-# LANGUAGE DeriveFunctor #-}
|
|
{-# LANGUAGE DeriveGeneric #-}
|
|
{-# LANGUAGE DerivingVia #-}
|
|
{-# LANGUAGE DuplicateRecordFields #-}
|
|
{-# LANGUAGE FlexibleContexts #-}
|
|
{-# LANGUAGE FlexibleInstances #-}
|
|
{-# LANGUAGE GADTs #-}
|
|
{-# LANGUAGE LambdaCase #-}
|
|
{-# LANGUAGE MultiParamTypeClasses #-}
|
|
{-# LANGUAGE OverloadedStrings #-}
|
|
{-# LANGUAGE RankNTypes #-}
|
|
{-# LANGUAGE RecordWildCards #-}
|
|
module MyService.Types where
|
|
|
|
import Data.Aeson (FromJSON, ToJSON)
|
|
import Data.Text
|
|
import Data.Time.Clock
|
|
import GHC.Generics
|
|
import System.Envy
|
|
import Text.PrettyPrint (text)
|
|
import Text.PrettyPrint.GenericPretty
|
|
|
|
-- Out hat hierfür keine Instanzen, daher kurz eine einfach Definition.
|
|
instance Out Text where
|
|
doc = text . unpack
|
|
docPrec i a = text $ showsPrec i a ""
|
|
|
|
instance Out UTCTime where
|
|
doc = text . show
|
|
docPrec i a = text $ showsPrec i a ""
|
|
|
|
-- Der ServerConfig-Typ. Wird mit den defaults unten initialisiert, dann mit den Variablen aus der .env-Datei überschrieben und zum Schluss können Serveradmins diese via $MYSERVICE_FOO nochmal überschreiben.
|
|
data ServerConfig = ServerConfig
|
|
{ myserviceHost :: String -- ^ Environment: $MYSERVICE_HOST
|
|
, myservicePort :: Int -- ^ Environment: $MYSERVICE_PORT
|
|
, myserviceMaxTimeout :: Int -- ^ Environment: $MYSERVICE_MAX_TIMEOUT
|
|
, myserviceInternalProxyUrl :: String -- ^ Environment: $MYSERVICE_INTERNAL_PROXY_URL
|
|
, myserviceInternalProxyPort :: Int -- ^ Environment: $MYSERVICE_INTERNAL_PROXY_PORT
|
|
, myserviceExternalProxyUrl :: String -- ^ Environment: $MYSERVICE_EXTERNAL_PROXY_URL
|
|
, myserviceExternalProxyPort :: Int -- ^ Environment: $MYSERVICE_EXTERNAL_PROXY_PORT
|
|
, myserviceActivemqHost :: String -- ^ Environment: $MYSERVICE_ACTIVEMQ_HOST
|
|
, myserviceActivemqPort :: Int -- ^ Environment: $MYSERVICE_ACTIVEMQ_PORT
|
|
, myserviceActivemqUsername :: String -- ^ Environment: $MYSERVICE_ACTIVEMQ_USERNAME
|
|
, myserviceActivemqPassword :: String -- ^ Environment: $MYSERVICE_ACTIVEMQ_PASSWORD
|
|
, myserviceMongoUsername :: String -- ^ Environment: $MYSERVICE_MONGO_USERNAME
|
|
, myserviceMongoPassword :: String -- ^ Environment: $MYSERVICE_MONGO_PASSWORD
|
|
, myserviceDebug :: Bool -- ^ Environment: $MYSERVICE_DEBUG
|
|
} deriving (Show, Eq, Generic)
|
|
|
|
-- Default-Konfigurations-Instanz für diesen Service.
|
|
instance DefConfig ServerConfig where
|
|
defConfig = ServerConfig "0.0.0.0" 8080 20
|
|
""
|
|
""
|
|
""
|
|
0
|
|
""
|
|
0
|
|
""
|
|
0
|
|
""
|
|
""
|
|
""
|
|
""
|
|
False
|
|
|
|
-- Kann auch aus dem ENV gefüllt werden
|
|
instance FromEnv ServerConfig
|
|
-- Und hübsch ausgegeben werden.
|
|
instance Out ServerConfig
|
|
|
|
|
|
instance Out Response
|
|
instance FromBSON Repsonse -- FromBSON-Instanz geht immer davon aus, dass alle keys da sind (ggf. mit null bei Nothing).
|
|
```
|
|
|
|
{{< dend >}}
|
|
|
|
#### Was noch zu tun ist
|
|
|
|
Den Service implementieren. Einfach ein neues Modul aufmachen (z.B.
|
|
`MyService.Handler` oder
|
|
`MyService.DieserEndpunktbereich`/`MyService.JenerEndpunktbereich`) und dort die
|
|
Funktion implementieren, die man in der `Main.hs` benutzt hat. In dem Handler
|
|
habt ihr dann keinen Stress mehr mit Validierung, networking, logging, etc. pp.
|
|
weil alles in der Main abgehandelt wurde und ihr nur noch den "Happy-Case"
|
|
implementieren müsst. Beispiel für unseren Handler oben:
|
|
|
|
```{.haskell}
|
|
myApiEndpointV1Post :: MonadIO m => ServerConfig -> (ClientEnv,ClientEnv) -> TQueue BS.ByteString -> ([LogItem] -> IO ()) -> Request -> m Response
|
|
myApiEndpointV1Post sc calls amqPost log req = do
|
|
liftIO . log $ [Info $ "recieved "<>pretty req] -- input-logging
|
|
liftIO . atomically . writeTQueue . LBS.toStrict $ "{\"hey Kibana, i recieved:\"" <> A.encode (pretty req) <> "}" -- log in activeMQ/Kibana
|
|
|
|
|
|
--- .... gaaaanz viel komplizierter code um die Response zu erhalten ;)
|
|
let ret = Response 1337 Nothing -- dummy-response ;)
|
|
-- gegeben wir haben eine gültige mongodb-pipe;
|
|
-- mehr logik will ich in die Beispiele nicht packen.
|
|
-- Man kann die z.b. als weiteren Wert in einer TMVar (damit man sie ändern & updaten kann) an die Funktion übergeben.
|
|
liftIO . access pipe master "DatabaseName" $ do
|
|
ifM (auth (myServiceMongoUsername sc) (myServiceMongoPassword sc)) (return ()) (liftIO . printLog . pure . Error $ "MongoDB: Login failed.")
|
|
save "DatabaseCollection" ["_id" =: 1337, "entry" =: ret] -- selbe id wie oben ;)
|
|
return ret
|
|
```
|
|
|
|
Diese dummy-Antwort führt auf, wie gut man die ganzen Sachen mischen kann.
|
|
|
|
- Logging in die Dateien/`stdout` - je nach Konfiguration
|
|
- Logging von Statistiken in Kibana
|
|
- Speichern der Antwort in der MongoDB
|
|
- Generieren einer Serverantwort und ausliefern dieser über die Schnittstelle
|
|
|
|
#### Tipps & Tricks
|
|
|
|
##### Dateien, die statisch ausgeliefert werden sollen
|
|
|
|
Hierzu erstellt man ein Verzeichnis `static/` (Konvention; ist im generator so
|
|
generiert, dass das ausgeliefert wird). Packt man hier z.b. eine `index.html`
|
|
rein, erscheint die, wenn man den Service ansurft.
|
|
|
|
##### Wie bekomme ich diese fancy Preview hin?
|
|
|
|
Der Editor, der ganz am Anfang zum Einsatz gekommen ist, braucht nur die
|
|
`api-doc.yml` um diese Ansicht zu erzeugen. Daher empfiehlt sich hier ein
|
|
angepasster Fork davon indem die Pfade in der index.html korrigiert sind. Am
|
|
einfachsten (und von den meisten services so benutzt): In meiner Implementation
|
|
liegt dann nach dem starten auf <http://localhost:PORT/ui/> und kann direkt dort
|
|
getestet werden.
|
|
|
|
##### Wie sorge ich für bessere Warnungen, damit der Compiler meine Bugs fängt?
|
|
|
|
```{.bash}
|
|
stack build --file-watch --ghc-options '-freverse-errors -W -Wall -Wcompat' --interleaved-output
|
|
```
|
|
|
|
Was tut das?
|
|
|
|
- `--file-watch`: automatisches (minimales) kompilieren bei dateiänderungen
|
|
- `--ghc-options`
|
|
- `-freverse-errors`: Fehlermeldungen in umgekehrter Reihenfolge (Erster
|
|
Fehler ganz unten; wenig scrollen )
|
|
- `-W`: Warnungen an
|
|
- `-Wall`: Alle sinnvollen Warnungen an (im gegensatz zu `-Weverything`, was
|
|
WIRKLICH alles ist )
|
|
- `-Wcompat`: Warnungen für Sachen, die in der nächsten Compilerversion kaputt
|
|
brechen werden & vermieden werden sollten
|
|
- `--interleaved-output`: stack-log direkt ausgeben & nicht in Dateien schreiben
|
|
und die dann am ende zusammen cat\'en.
|
|
|
|
Um pro Datei Warnungen auszuschalten (z.B. weil man ganz sicher weiss, was man
|
|
tut -.-): `{-# OPTIONS_GHC -Wno-whatsoever #-}` als pragma in die Datei.
|
|
|
|
**Idealerweise sollte das Projekt keine Warnungen erzeugen.**
|
|
|
|
### Deployment
|
|
|
|
Als Beispiel sei hier ein einfaches Docker-Build mit Jenkins-CI gezeigt, weil
|
|
ich das aus Gründen rumliegen hatte. Kann man analog in fast alle anderen CI
|
|
übersetzen.
|
|
|
|
#### Docker
|
|
|
|
Die angehängten Scripte gehen von einer Standard-Einrichtung aus (statische
|
|
Sachen in static, 2-3 händische Anpassungen auf das eigene Projekt nach
|
|
auspacken). Nachher liegt dann auch unter static/version die gebaute
|
|
Versionsnummer & kann abgerufen werden. In der `Dockerfile.release` und der
|
|
`Jenkinsfile` müssen noch Anpassungen gemacht werden. Konkret:
|
|
|
|
- in der `Dockerfile.release`: alle `<<<HIER>>>`-Stellen sinnvoll befüllen
|
|
- in der `Jenkinsfile` die defs für "servicename" und "servicebinary" ausfüllen.
|
|
Binary ist das, was bei stack exec aufgerufen wird; name ist der Image-Name
|
|
für das docker-repository.
|
|
|
|
#### Jenkins
|
|
|
|
Änderungen die dann noch gemacht werden müssen:
|
|
|
|
- git-repository URL anpassen
|
|
- Environment-Vars anpassen (\$BRANCH = test & live haben keine zusatzdinger im
|
|
docker-image-repository; ansonsten hat das image \$BRANCH im Namen)
|
|
|
|
Wenn das fertig gebaut ist, liegt im test/live-repository ein docker-image
|
|
namens `servicename:version`.
|
|
|
|
### OMG! Ich muss meine API ändern. Was mache ich nun?
|
|
|
|
1. api-doc.yml bearbeiten, wie gewünscht
|
|
2. mittels generator die Api & submodule neu generieren
|
|
3. ggf. custom Änderungen übernehmen (:Gitdiffsplit hilft)
|
|
4. Alle Compilerfehler + Warnungen in der eigentlichen Applikation fixen
|
|
5. If it comipilez, ship it! (Besser nicht :grin:)
|