Yam

A out-of-the-box wrapper of servant, providing configuration loader salak and flexible extension with AppMiddleware.

How to use this library

import           Salak
import           Salak.Yaml
import           Servant
import           Yam
import qualified Control.Category    as C
import           Data.Version

type API = "hello" :> Get '[PlainText] Text

service :: ServerT API AppSimple
service = return "world"

main = runSalakWith "app" YAML $ do
  al <- require  "yam.application"
  sw <- require  "yam.swagger"
  lc <- requireD "yam.logging"
  start al sw (makeVersion []) lc spanNoNotifier emptyAM serveWarp (Proxy @API) service

Yam Server

start

Arguments

:: (HasServer api cxt, HasSwagger api)

=> AppConfig

Application Config

-> SwaggerConfig

SwaggerConfig

-> Version

Application Version

-> IO LogConfig

Logger Config

-> (Span -> AppV cxt IO ())

Opentracing notifier

-> AppMiddleware Simple cxt

Application Middleware

-> (AppConfig -> Application -> IO ())

Run Application

-> Proxy api

Application API Proxy

-> ServerT api (AppV cxt IO)

Application API Server

-> IO ()

Standard Starter of Yam.

serveWarp :: AppConfig -> Application -> IO ()

default http server by warp.

Application Configuration

data AppConfig

Application Configuration.

Constructors

AppConfig

Fields

• name :: Text

  Application name.

• hostname :: String

  Applicatoin hostname, used in swagger.

• port :: Int

  Application http port.

• slowlorisSize :: Int

  Slowloris size in Bytes, show in Settings

Instances

Eq AppConfig

Defined in Yam.Config

Methods

(==) :: AppConfig -> AppConfig -> Bool

(/=) :: AppConfig -> AppConfig -> Bool

Show AppConfig

Defined in Yam.Config

Methods

showsPrec :: Int -> AppConfig -> ShowS

show :: AppConfig -> String

showList :: [AppConfig] -> ShowS

Default AppConfig

Defined in Yam.Config

Methods

def :: AppConfig

FromProp AppConfig

Defined in Yam.Config

Methods

fromProp :: Prop AppConfig

Application Context

data AppT cxt m a

Application Context Monad.

Instances

MonadTrans (AppT cxt)

Defined in Yam.App

Methods

lift :: Monad m => m a -> AppT cxt m a

Monad m => MonadReader (Context cxt) (AppT cxt m)

Defined in Yam.App

Methods

ask :: AppT cxt m (Context cxt)

local :: (Context cxt -> Context cxt) -> AppT cxt m a -> AppT cxt m a

reader :: (Context cxt -> a) -> AppT cxt m a

Monad m => Monad (AppT cxt m)

Defined in Yam.App

Methods

(>>=) :: AppT cxt m a -> (a -> AppT cxt m b) -> AppT cxt m b

(>>) :: AppT cxt m a -> AppT cxt m b -> AppT cxt m b

return :: a -> AppT cxt m a

fail :: String -> AppT cxt m a

Functor m => Functor (AppT cxt m)

Defined in Yam.App

Methods

fmap :: (a -> b) -> AppT cxt m a -> AppT cxt m b

(<$) :: a -> AppT cxt m b -> AppT cxt m a

Applicative m => Applicative (AppT cxt m)

Defined in Yam.App

Methods

pure :: a -> AppT cxt m a

(<*>) :: AppT cxt m (a -> b) -> AppT cxt m a -> AppT cxt m b

liftA2 :: (a -> b -> c) -> AppT cxt m a -> AppT cxt m b -> AppT cxt m c

(*>) :: AppT cxt m a -> AppT cxt m b -> AppT cxt m b

(<*) :: AppT cxt m a -> AppT cxt m b -> AppT cxt m a

MonadIO m => MonadIO (AppT cxt m)

Defined in Yam.App

Methods

liftIO :: IO a -> AppT cxt m a

MonadUnliftIO m => MonadUnliftIO (AppT cxt m)

Defined in Yam.App

Methods

askUnliftIO :: AppT cxt m (UnliftIO (AppT cxt m))

withRunInIO :: ((forall a. AppT cxt m a -> IO a) -> IO b) -> AppT cxt m b

(HasLogger cxt, MonadIO m) => HasValid (AppT cxt m)

Defined in Yam.App

Methods

invalid :: HasI18n a => a -> AppT cxt m b

mark :: String -> AppT cxt m a -> AppT cxt m a

(HasLogger cxt, MonadIO m) => MonadLogger (AppT cxt m)

Defined in Yam.App

Methods

monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> AppT cxt m ()

(HasLogger cxt, MonadIO m) => MonadLoggerIO (AppT cxt m)

Defined in Yam.App

Methods

askLoggerIO :: AppT cxt m (Loc -> LogSource -> LogLevel -> LogStr -> IO ())

(HasContextEntry cxt SourcePack, Monad m) => HasSourcePack (AppT cxt m)

Defined in Yam.App

Methods

askSourcePack :: AppT cxt m SourcePack

type AppV cxt = AppT (VaultHolder ': cxt)

Application with Vault

type AppIO cxt = AppT cxt IO

Application on IO.

type AppSimple = AppV Simple IO

Simple Application with logger context.

type Simple = '[LogFuncHolder]

Simple Application context

runAppT :: Context cxt -> AppT cxt m a -> m a

Run Application with context.

runVault :: MonadIO m => Context cxt -> Vault -> AppV cxt IO a -> m a

Run Application with Vault.

throwS

Arguments

:: (HasCallStack, MonadIO m, MonadLogger m)

=> ServerError

Server error

-> Text

message

-> m a

throw ServerError with message

Application Middleware

newtype AppMiddleware a b

Application Middleware.

Constructors

AppMiddleware

Fields

• runAM :: Context a -> Middleware -> (Context b -> Middleware -> LoggingT IO ()) -> LoggingT IO ()

Instances

Category AppMiddleware

Defined in Yam

Methods

id :: AppMiddleware a a

(.) :: AppMiddleware b c -> AppMiddleware a b -> AppMiddleware a c

emptyAM :: AppMiddleware cxt cxt

Empty Application Middleware.

simpleContext :: a -> AppMiddleware cxt (a ': cxt)

Simple Application Middleware, just provide a config to context.

simpleConfig :: (HasSalak cxt, FromProp a) => Text -> AppMiddleware cxt (a ': cxt)

Simple Application Middleware, just provide a config to context.

simpleConfig' :: (HasSalak cxt, FromProp a) => Text -> (a -> AppT cxt (LoggingT IO) b) -> AppMiddleware cxt (b ': cxt)

Simple Application Middleware, just provide a config to context.

simpleMiddleware :: Middleware -> AppMiddleware cxt cxt

Simple Application Middleware, promote a Middleware to AppMiddleware

Modules

Logger

data LogConfig

Logger config

Constructors

LogConfig

Fields

• bufferSize :: Word16

  Logger buffer size.

• file :: FilePath

  Logger file path.

• maxSize :: Word32

  Max logger file size.

• rotateHistory :: Word16

  Max number of logger files should be reserved.

• level :: LogLevel

  Log level to show.

Instances

Eq LogConfig

Defined in Yam.Logger

Methods

(==) :: LogConfig -> LogConfig -> Bool

(/=) :: LogConfig -> LogConfig -> Bool

Show LogConfig

Defined in Yam.Logger

Methods

showsPrec :: Int -> LogConfig -> ShowS

show :: LogConfig -> String

showList :: [LogConfig] -> ShowS

Default LogConfig

Defined in Yam.Logger

Methods

def :: LogConfig

FromProp LogConfig

Defined in Yam.Logger

Methods

fromProp :: Prop LogConfig

type HasLogger cxt = (HasContextEntry cxt LogFuncHolder, TryContextEntry cxt VaultHolder)

Context with logger.

data LogFuncHolder

Holder for LogFunc

data VaultHolder

Holder for Vault

Context

data Context (contextTypes :: [Type]) where

Contexts are used to pass values to combinators. (They are not meant to be used to pass parameters to your handlers, i.e. they should not replace any custom ReaderT-monad-stack that you're using with hoistServer.) If you don't use combinators that require any context entries, you can just use serve as always.

If you are using combinators that require a non-empty Context you have to use serveWithContext and pass it a Context that contains all the values your combinators need. A Context is essentially a heterogenous list and accessing the elements is being done by type (see getContextEntry). The parameter of the type Context is a type-level list reflecting the types of the contained context entries. To create a Context with entries, use the operator (:.):

>>> :type True :. () :. EmptyContext
True :. () :. EmptyContext :: Context '[Bool, ()]

Constructors

EmptyContext :: forall (contextTypes :: [Type]). Context ([] :: [Type])

(:.) :: forall (contextTypes :: [Type]) x (xs :: [Type]). x -> Context xs -> Context (x ': xs) infixr 5

Instances

(Eq a, Eq (Context as)) => Eq (Context (a ': as))

Defined in Servant.Server.Internal.Context

Methods

(==) :: Context (a ': as) -> Context (a ': as) -> Bool

(/=) :: Context (a ': as) -> Context (a ': as) -> Bool

Eq (Context ([] :: [Type]))

Defined in Servant.Server.Internal.Context

Methods

(==) :: Context [] -> Context [] -> Bool

(/=) :: Context [] -> Context [] -> Bool

(Show a, Show (Context as)) => Show (Context (a ': as))

Defined in Servant.Server.Internal.Context

Methods

showsPrec :: Int -> Context (a ': as) -> ShowS

show :: Context (a ': as) -> String

showList :: [Context (a ': as)] -> ShowS

Show (Context ([] :: [Type]))

Defined in Servant.Server.Internal.Context

Methods

showsPrec :: Int -> Context [] -> ShowS

show :: Context [] -> String

showList :: [Context []] -> ShowS

Monad m => MonadReader (Context cxt) (AppT cxt m)

Defined in Yam.App

Methods

ask :: AppT cxt m (Context cxt)

local :: (Context cxt -> Context cxt) -> AppT cxt m a -> AppT cxt m a

reader :: (Context cxt -> a) -> AppT cxt m a

class HasContextEntry (context :: [Type]) val where

This class is used to access context entries in Contexts. getContextEntry returns the first value where the type matches:

>>> getContextEntry (True :. False :. EmptyContext) :: Bool
True

If the Context does not contain an entry of the requested type, you'll get an error:

>>> getContextEntry (True :. False :. EmptyContext) :: String
...
...No instance for (HasContextEntry '[] [Char])
...

Methods

getContextEntry :: Context context -> val

Instances

HasContextEntry xs val => HasContextEntry (notIt ': xs) val

Defined in Servant.Server.Internal.Context

Methods

getContextEntry :: Context (notIt ': xs) -> val

HasContextEntry (val ': xs) val

Defined in Servant.Server.Internal.Context

Methods

getContextEntry :: Context (val ': xs) -> val

class TryContextEntry (cxt :: [*]) (entry :: *) where

This class provide a optional supports for get entry from Context.

Methods

tryContextEntry :: Context cxt -> Maybe entry

Instances

TryContextEntry a entry

Defined in Yam.Prelude

Methods

tryContextEntry :: Context a -> Maybe entry

TryContextEntry (entry ': as) entry

Defined in Yam.Prelude

Methods

tryContextEntry :: Context (entry ': as) -> Maybe entry

TryContextEntry as entry => TryContextEntry (a ': as) entry

Defined in Yam.Prelude

Methods

tryContextEntry :: Context (a ': as) -> Maybe entry

getEntry :: (HasContextEntry cxt entry, Monad m) => AppT cxt m entry

Get entry from AppT

tryEntry :: (TryContextEntry cxt entry, Monad m) => AppT cxt m (Maybe entry)

Try get entry from AppT

Swagger

data SwaggerConfig

Swagger Configuration

Constructors

SwaggerConfig

Fields

• urlDir :: String

  Url path for swagger.

• urlSchema :: String

  Api schema path for swagger.

• enabled :: Bool

  If enable swagger.

Instances

Eq SwaggerConfig

Defined in Yam.Swagger

Methods

(==) :: SwaggerConfig -> SwaggerConfig -> Bool

(/=) :: SwaggerConfig -> SwaggerConfig -> Bool

Show SwaggerConfig

Defined in Yam.Swagger

Methods

showsPrec :: Int -> SwaggerConfig -> ShowS

show :: SwaggerConfig -> String

showList :: [SwaggerConfig] -> ShowS

FromProp SwaggerConfig

Defined in Yam.Swagger

Methods

fromProp :: Prop SwaggerConfig

serveWithContextAndSwagger

Arguments

:: (HasSwagger api, HasServer api context)

=> SwaggerConfig

Swagger configuration.

-> (Swagger -> Swagger)

Swagger modification.

-> Proxy api

Application API Proxy.

-> Context context

Application context.

-> ServerT api Handler

Application API Server

-> Application

Serve with swagger.

baseInfo

Arguments

:: String

Hostname

-> Text

Server Name

-> Version

Server version

-> Int

Port

-> Swagger

Old swagger

-> Swagger

Swagger modification

Reexport

spanNoNotifier :: Span -> AppV cxt IO ()

Empty span notifier.

data Span

Constructors

Span

Fields

• spanId :: ByteString
• name :: Text
• startTime :: Int
• finishTime :: Maybe Int
• tags :: HashMap Text SpanTag
• logs :: HashMap Text Text
• context :: SpanContext
• references :: [SpanReference]

Instances

Eq Span

Defined in Data.Opentracing.Types

Methods

(==) :: Span -> Span -> Bool

(/=) :: Span -> Span -> Bool

Show Span

Defined in Data.Opentracing.Types

Methods

showsPrec :: Int -> Span -> ShowS

show :: Span -> String

showList :: [Span] -> ShowS

data SpanContext

Constructors

SpanContext

Fields

• traceId :: ByteString
• baggage :: HashMap Text (Maybe Text)

Instances

Eq SpanContext

Defined in Data.Opentracing.Types

Methods

(==) :: SpanContext -> SpanContext -> Bool

(/=) :: SpanContext -> SpanContext -> Bool

Show SpanContext

Defined in Data.Opentracing.Types

Methods

showsPrec :: Int -> SpanContext -> ShowS

show :: SpanContext -> String

showList :: [SpanContext] -> ShowS

data SpanTag

Constructors

TagString Text

TagBool Bool

TagNum Scientific

Instances

Eq SpanTag

Defined in Data.Opentracing.Types

Methods

(==) :: SpanTag -> SpanTag -> Bool

(/=) :: SpanTag -> SpanTag -> Bool

Show SpanTag

Defined in Data.Opentracing.Types

Methods

showsPrec :: Int -> SpanTag -> ShowS

show :: SpanTag -> String

showList :: [SpanTag] -> ShowS

data SpanReference

Constructors

SpanReference

Fields

• referenceType :: SpanReferenceType
• parentId :: ByteString

Instances

Eq SpanReference

Defined in Data.Opentracing.Types

Methods

(==) :: SpanReference -> SpanReference -> Bool

(/=) :: SpanReference -> SpanReference -> Bool

Show SpanReference

Defined in Data.Opentracing.Types

Methods

showsPrec :: Int -> SpanReference -> ShowS

show :: SpanReference -> String

showList :: [SpanReference] -> ShowS

showText :: Show a => a -> Text

Show text.

randomString :: IO ByteString

Utility

randomCode :: Vector Char -> Int -> IO String

Utility

decodeUtf8 :: ByteString -> Text

Decode a ByteString containing UTF-8 encoded text that is known to be valid.

If the input contains any invalid UTF-8 data, an exception will be thrown that cannot be caught in pure code. For more control over the handling of invalid data, use decodeUtf8' or decodeUtf8With.

encodeUtf8 :: Text -> ByteString

Encode text using UTF-8 encoding.

pack :: String -> Text

O(n) Convert a String into a Text. Subject to fusion. Performs replacement on invalid scalar values.

liftIO :: MonadIO m => IO a -> m a

Lift a computation from the IO monad.

fromMaybe :: a -> Maybe a -> a

The fromMaybe function takes a default value and and Maybe value. If the Maybe is Nothing, it returns the default values; otherwise, it returns the value contained in the Maybe.

Examples

Basic usage:

>>> fromMaybe "" (Just "Hello, World!")
"Hello, World!"

>>> fromMaybe "" Nothing
""

Read an integer from a string using readMaybe. If we fail to parse an integer, we want to return 0 by default:

>>> import Text.Read ( readMaybe )
>>> fromMaybe 0 (readMaybe "5")
5
>>> fromMaybe 0 (readMaybe "")
0

throw :: Exception e => e -> a

Throw an exception. Exceptions may be thrown from purely functional code, but may only be caught within the IO monad.