Safe Haskell	None
Language	Haskell2010
Extensions	UndecidableInstances ScopedTypeVariables AllowAmbiguousTypes OverloadedStrings DisambiguateRecordFields RecordWildCards ViewPatterns ConstraintKinds InstanceSigs DerivingStrategies TypeSynonymInstances FlexibleContexts FlexibleInstances ConstrainedClassMethods MultiParamTypeClasses ExistentialQuantification GeneralizedNewtypeDeriving RankNTypes ExplicitForAll LambdaCase PatternSynonyms StrictData

Okapi

Contents

Parsing
Responding
Middleware
Routing
Relative URLs
Testing
WAI
Utilities
- Server Sent Events
- Sessions

Description

Okapi is a micro web framework.

Synopsis

type MonadOkapi m = (Functor m, Applicative m, Alternative m, Monad m, MonadPlus m, MonadError Failure m, MonadState State m)
newtype OkapiT m a = OkapiT {
- unOkapiT :: ExceptT Failure (StateT State m) a
}
data Failure
- = Skip
- | Error Response
data State = State {
- stateRequest :: Request
- stateVault :: Vault
}
data Request
type Method = Maybe ByteString
type Path = [Text]
type Query = [QueryItem]
type QueryItem = (Text, QueryValue)
data QueryValue
- = QueryParam Text
- | QueryFlag
type Body = ByteString
type Headers = [Header]
type Header = (HeaderName, ByteString)
type HeaderName = HeaderName
type Cookie = [Crumb]
type Crumb = (ByteString, ByteString)
request :: MonadOkapi m => m Request
requestEnd :: MonadOkapi m => m ()
method :: MonadOkapi m => m Method
methodGET :: MonadOkapi m => m ()
methodPOST :: MonadOkapi m => m ()
methodHEAD :: MonadOkapi m => m ()
methodPUT :: MonadOkapi m => m ()
methodPATCH :: MonadOkapi m => m ()
methodDELETE :: MonadOkapi m => m ()
methodOPTIONS :: MonadOkapi m => m ()
methodTRACE :: MonadOkapi m => m ()
methodCONNECT :: MonadOkapi m => m ()
methodEnd :: MonadOkapi m => m ()
path :: MonadOkapi m => m [Text]
pathParam :: (FromHttpApiData a, MonadOkapi m) => m a
pathEnd :: MonadOkapi m => m ()
query :: MonadOkapi m => m Query
queryValue :: MonadOkapi m => Text -> m QueryValue
queryFlag :: MonadOkapi m => Text -> m ()
queryParam :: (FromHttpApiData a, MonadOkapi m) => Text -> m a
queryList :: (FromHttpApiData a, MonadOkapi m) => Text -> m (NonEmpty a)
queryEnd :: MonadOkapi m => m ()
body :: MonadOkapi m => m Body
bodyJSON :: (FromJSON a, MonadOkapi m) => m a
bodyForm :: (FromForm a, MonadOkapi m) => m a
bodyEnd :: MonadOkapi m => m ()
headers :: MonadOkapi m => m Headers
header :: MonadOkapi m => HeaderName -> m ByteString
basicAuth :: MonadOkapi m => m (Text, Text)
headersEnd :: MonadOkapi m => m ()
cookie :: MonadOkapi m => m Cookie
cookieCrumb :: MonadOkapi m => ByteString -> m ByteString
cookieEnd :: MonadOkapi m => m ()
vaultLookup :: MonadOkapi m => Key a -> m a
vaultInsert :: MonadOkapi m => Key a -> a -> m ()
vaultDelete :: MonadOkapi m => Key a -> m ()
vaultAdjust :: MonadOkapi m => (a -> a) -> Key a -> m ()
vaultWipe :: MonadOkapi m => m ()
is :: (Eq a, MonadOkapi m) => m a -> a -> m ()
satisfies :: (Eq a, MonadOkapi m) => m a -> (a -> Bool) -> m ()
look :: MonadOkapi m => m a -> m a
next :: MonadOkapi m => m a
throw :: MonadOkapi m => Response -> m a
(<!>) :: MonadOkapi m => m a -> m a -> m a
guardThrow :: MonadOkapi m => Response -> Bool -> m ()
type Handler m = m Response
data Response = Response {
- responseStatus :: Status
- responseHeaders :: Headers
- responseBody :: ResponseBody
}
type Status = Natural
data ResponseBody
- = ResponseBodyRaw ByteString
- | ResponseBodyFile FilePath
- | ResponseBodyEventSource EventSource
ok :: Response
notFound :: Response
redirect :: Status -> Text -> Response
forbidden :: Response
internalServerError :: Response
setStatus :: Status -> Response -> Response
setHeaders :: Headers -> Response -> Response
setHeader :: Header -> Response -> Response
addHeader :: Header -> Response -> Response
addSetCookie :: (ByteString, ByteString) -> Response -> Response
setBody :: ResponseBody -> Response -> Response
setBodyRaw :: ByteString -> Response -> Response
setBodyFile :: FilePath -> Response -> Response
setBodyEventSource :: EventSource -> Response -> Response
setPlaintext :: Text -> Response -> Response
setHTML :: ByteString -> Response -> Response
setJSON :: ToJSON a => a -> Response -> Response
static :: MonadOkapi m => Handler m
type Middleware m = Handler m -> Handler m
applyMiddlewares :: MonadOkapi m => [Middleware m] -> Middleware m
scope :: MonadOkapi m => Path -> [Middleware m] -> Middleware m
clearHeadersMiddleware :: MonadOkapi m => Middleware m
prefixPathMiddleware :: MonadOkapi m => Path -> Middleware m
type Router m a = m a -> (a -> Handler m) -> Handler m
route :: MonadOkapi m => Router m a
pattern PathParam :: (ToHttpApiData a, FromHttpApiData a) => a -> Text
pattern GET :: Method
pattern POST :: Method
pattern DELETE :: Method
pattern PUT :: Method
pattern PATCH :: Method
pattern IsQueryParam :: (ToHttpApiData a, FromHttpApiData a) => a -> QueryValue
pattern HasQueryFlag :: Maybe QueryValue
viewQuery :: Text -> Query -> (Maybe QueryValue, Query)
viewQueryParam :: FromHttpApiData a => Text -> Query -> (Maybe a, Query)
data RelURL = RelURL Path Query
renderRelURL :: RelURL -> Text
renderPath :: Path -> Text
renderQuery :: Query -> Text
parseRelURL :: Text -> Maybe RelURL
testParser :: Monad m => OkapiT m Response -> Request -> m (Either Failure Response, State)
testParserPure :: OkapiT Identity Response -> Request -> Identity (Either Failure Response, State)
testParserIO :: OkapiT IO Response -> Request -> IO (Either Failure Response, State)
assert :: ((Either Failure Response, State) -> Bool) -> (Either Failure Response, State) -> Bool
assert200 :: (Either Failure Response, State) -> Bool
assert404 :: (Either Failure Response, State) -> Bool
assert500 :: (Either Failure Response, State) -> Bool
run :: Monad m => (forall a. m a -> IO a) -> OkapiT m Response -> IO ()
serve :: Monad m => Int -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO ()
serveTLS :: Monad m => TLSSettings -> Settings -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO ()
serveWebsockets :: Monad m => ConnectionOptions -> ServerApp -> Int -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO ()
serveWebsocketsTLS :: Monad m => TLSSettings -> Settings -> ConnectionOptions -> ServerApp -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO ()
app :: Monad m => Response -> (forall a. m a -> IO a) -> OkapiT m Response -> Application
websocketsApp :: Monad m => ConnectionOptions -> ServerApp -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> Application
testRunSession :: Monad m => Session a -> (forall a. m a -> IO a) -> OkapiT m Response -> IO a
testWithSession :: Monad m => (forall a. m a -> IO a) -> OkapiT m Response -> Session a -> IO a
testRequest :: Request -> Session SResponse
data Event
- = Event {
  - eventName :: Maybe Text
  - eventID :: Maybe Text
  - eventData :: ByteString
  }
- | CommentEvent ByteString
- | CloseEvent
class ToSSE a where
- toSSE :: a -> Event
type EventSource = Chan Event
newEventSource :: IO EventSource
sendValue :: ToSSE a => EventSource -> a -> IO ()
sendEvent :: EventSource -> Event -> IO ()
type Session = Map ByteString ByteString
class Monad m => HasSession m where
- sessionSecret :: m ByteString
- getSession :: m (Maybe Session)
- putSession :: Session -> m ()
session :: (MonadOkapi m, HasSession m) => m Session
sessionLookup :: HasSession m => MonadOkapi m => ByteString -> m ByteString
sessionInsert :: HasSession m => MonadOkapi m => ByteString -> ByteString -> m ()
sessionDelete :: HasSession m => MonadOkapi m => ByteString -> m ()
sessionClear :: HasSession m => m ()
withSession :: (MonadOkapi m, HasSession m) => Middleware m

Parsing

These are the parsers that you'll use to build you own app.

type MonadOkapi m = (Functor m, Applicative m, Alternative m, Monad m, MonadPlus m, MonadError Failure m, MonadState State m) Source #

A type constraint representing monads that have the ability to parse an HTTP request.

newtype OkapiT m a Source #

A concrete implementation of the MonadOkapi type constraint.

Constructors

OkapiT
Fields unOkapiT :: ExceptT Failure (StateT State m) a

Instances

Instances details

MonadTrans OkapiT Source #
Instance details Defined in Okapi Methods lift :: Monad m => m a -> OkapiT m a #
Monad m => MonadState State (OkapiT m) Source #
Instance details Defined in Okapi Methods get :: OkapiT m State # put :: State -> OkapiT m () # state :: (State -> (a, State)) -> OkapiT m a #
MonadReader r m => MonadReader r (OkapiT m) Source #
Instance details Defined in Okapi Methods ask :: OkapiT m r # local :: (r -> r) -> OkapiT m a -> OkapiT m a # reader :: (r -> a) -> OkapiT m a #
Monad m => MonadError Failure (OkapiT m) Source #
Instance details Defined in Okapi Methods throwError :: Failure -> OkapiT m a # catchError :: OkapiT m a -> (Failure -> OkapiT m a) -> OkapiT m a #
Monad m => Monad (OkapiT m) Source #
Instance details Defined in Okapi Methods (>>=) :: OkapiT m a -> (a -> OkapiT m b) -> OkapiT m b # (>>) :: OkapiT m a -> OkapiT m b -> OkapiT m b # return :: a -> OkapiT m a #
Functor m => Functor (OkapiT m) Source #
Instance details Defined in Okapi Methods fmap :: (a -> b) -> OkapiT m a -> OkapiT m b # (<$) :: a -> OkapiT m b -> OkapiT m a #
Monad m => Applicative (OkapiT m) Source #
Instance details Defined in Okapi Methods pure :: a -> OkapiT m a # (<>) :: OkapiT m (a -> b) -> OkapiT m a -> OkapiT m b # liftA2 :: (a -> b -> c) -> OkapiT m a -> OkapiT m b -> OkapiT m c # (>) :: OkapiT m a -> OkapiT m b -> OkapiT m b # (<*) :: OkapiT m a -> OkapiT m b -> OkapiT m a #
MonadIO m => MonadIO (OkapiT m) Source #
Instance details Defined in Okapi Methods liftIO :: IO a -> OkapiT m a #
Monad m => Alternative (OkapiT m) Source #
Instance details Defined in Okapi Methods empty :: OkapiT m a # (<\|>) :: OkapiT m a -> OkapiT m a -> OkapiT m a # some :: OkapiT m a -> OkapiT m [a] # many :: OkapiT m a -> OkapiT m [a] #
Monad m => MonadPlus (OkapiT m) Source #
Instance details Defined in Okapi Methods mzero :: OkapiT m a # mplus :: OkapiT m a -> OkapiT m a -> OkapiT m a #
MFunctor OkapiT Source #
Instance details Defined in Okapi Methods hoist :: forall m n (b :: k). Monad m => (forall a. m a -> n a) -> OkapiT m b -> OkapiT n b

data Failure Source #

Represents the two variants of failure that can occur when parsing a HTTP request.

Constructors

Skip
Error Response

Instances

Instances details

Show Failure Source #
Instance details Defined in Okapi Methods showsPrec :: Int -> Failure -> ShowS # show :: Failure -> String # showList :: [Failure] -> ShowS #
Monad m => MonadError Failure (OkapiT m) Source #
Instance details Defined in Okapi Methods throwError :: Failure -> OkapiT m a # catchError :: OkapiT m a -> (Failure -> OkapiT m a) -> OkapiT m a #

data State Source #

Represents the state of a parser. Set on every request to the Okapi server.

Constructors

State
Fields stateRequest :: Request stateVault :: Vault

Instances

Instances details

Monad m => MonadState State (OkapiT m) Source #
Instance details Defined in Okapi Methods get :: OkapiT m State # put :: State -> OkapiT m () # state :: (State -> (a, State)) -> OkapiT m a #

data Request Source #

Represents the HTTP request being parsed.

Instances

Instances details

Eq Request Source #
Instance details Defined in Okapi Methods (==) :: Request -> Request -> Bool # (/=) :: Request -> Request -> Bool #
Show Request Source #
Instance details Defined in Okapi Methods showsPrec :: Int -> Request -> ShowS # show :: Request -> String # showList :: [Request] -> ShowS #

type Method = Maybe ByteString Source #

type Path = [Text] Source #

type Query = [QueryItem] Source #

type QueryItem = (Text, QueryValue) Source #

data QueryValue Source #

Constructors

QueryParam Text
QueryFlag

Instances

Instances details

Eq QueryValue Source #
Instance details Defined in Okapi Methods (==) :: QueryValue -> QueryValue -> Bool # (/=) :: QueryValue -> QueryValue -> Bool #
Show QueryValue Source #
Instance details Defined in Okapi Methods showsPrec :: Int -> QueryValue -> ShowS # show :: QueryValue -> String # showList :: [QueryValue] -> ShowS #

type Body = ByteString Source #

type Headers = [Header] Source #

type Header = (HeaderName, ByteString) Source #

type HeaderName = HeaderName Source #

type Cookie = [Crumb] Source #

type Crumb = (ByteString, ByteString) Source #

Request Parsers

request :: MonadOkapi m => m Request Source #

Parses the entire request.

requestEnd :: MonadOkapi m => m () Source #

Method Parsers

method :: MonadOkapi m => m Method Source #

methodGET :: MonadOkapi m => m () Source #

methodPOST :: MonadOkapi m => m () Source #

methodHEAD :: MonadOkapi m => m () Source #

methodPUT :: MonadOkapi m => m () Source #

methodPATCH :: MonadOkapi m => m () Source #

methodDELETE :: MonadOkapi m => m () Source #

methodOPTIONS :: MonadOkapi m => m () Source #

methodTRACE :: MonadOkapi m => m () Source #

methodCONNECT :: MonadOkapi m => m () Source #

methodEnd :: MonadOkapi m => m () Source #

Path Parsers

These are the path parsers.

path :: MonadOkapi m => m [Text] Source #

Parses and discards mutiple path segments matching the values and order of the given [Text] value

pathParam :: (FromHttpApiData a, MonadOkapi m) => m a Source #

Parses and discards a single path segment matching the given Text value

pathEnd :: MonadOkapi m => m () Source #

Query Parsers

These are the query parsers.

query :: MonadOkapi m => m Query Source #

queryValue :: MonadOkapi m => Text -> m QueryValue Source #

queryFlag :: MonadOkapi m => Text -> m () Source #

Test for the existance of a query flag

queryParam :: (FromHttpApiData a, MonadOkapi m) => Text -> m a Source #

Parses the value of a query parameter with the given type and name

queryList :: (FromHttpApiData a, MonadOkapi m) => Text -> m (NonEmpty a) Source #

queryEnd :: MonadOkapi m => m () Source #

Body Parsers

body :: MonadOkapi m => m Body Source #

bodyJSON :: (FromJSON a, MonadOkapi m) => m a Source #

bodyForm :: (FromForm a, MonadOkapi m) => m a Source #

bodyEnd :: MonadOkapi m => m () Source #

Header Parsers

These are header parsers.

headers :: MonadOkapi m => m Headers Source #

header :: MonadOkapi m => HeaderName -> m ByteString Source #

basicAuth :: MonadOkapi m => m (Text, Text) Source #

headersEnd :: MonadOkapi m => m () Source #

cookie :: MonadOkapi m => m Cookie Source #

cookieCrumb :: MonadOkapi m => ByteString -> m ByteString Source #

cookieEnd :: MonadOkapi m => m () Source #

Vault Parsers

vaultLookup :: MonadOkapi m => Key a -> m a Source #

vaultInsert :: MonadOkapi m => Key a -> a -> m () Source #

vaultDelete :: MonadOkapi m => Key a -> m () Source #

vaultAdjust :: MonadOkapi m => (a -> a) -> Key a -> m () Source #

vaultWipe :: MonadOkapi m => m () Source #

Combinators

is :: (Eq a, MonadOkapi m) => m a -> a -> m () Source #

satisfies :: (Eq a, MonadOkapi m) => m a -> (a -> Bool) -> m () Source #

look :: MonadOkapi m => m a -> m a Source #

Parses without modifying the state, even if it succeeds.

Failure

next :: MonadOkapi m => m a Source #

throw :: MonadOkapi m => Response -> m a Source #

(<!>) :: MonadOkapi m => m a -> m a -> m a Source #

guardThrow :: MonadOkapi m => Response -> Bool -> m () Source #

Responding

type Handler m = m Response Source #

Represents monadic actions that return a Response, for some m.

data Response Source #

Represents HTTP responses that can be returned by a parser.

Constructors

Response
Fields responseStatus :: Status responseHeaders :: Headers responseBody :: ResponseBody

type Status = Natural Source #

data ResponseBody Source #

Represents the body of an HTTP response.

Constructors

ResponseBodyRaw ByteString
ResponseBodyFile FilePath
ResponseBodyEventSource EventSource

Values

ok :: Response Source #

notFound :: Response Source #

redirect :: Status -> Text -> Response Source #

forbidden :: Response Source #

internalServerError :: Response Source #

Setters

setStatus :: Status -> Response -> Response Source #

setHeaders :: Headers -> Response -> Response Source #

setHeader :: Header -> Response -> Response Source #

addHeader :: Header -> Response -> Response Source #

addSetCookie :: (ByteString, ByteString) -> Response -> Response Source #

setBody :: ResponseBody -> Response -> Response Source #

setBodyRaw :: ByteString -> Response -> Response Source #

setBodyFile :: FilePath -> Response -> Response Source #

setBodyEventSource :: EventSource -> Response -> Response Source #

setPlaintext :: Text -> Response -> Response Source #

setHTML :: ByteString -> Response -> Response Source #

setJSON :: ToJSON a => a -> Response -> Response Source #

Special

static :: MonadOkapi m => Handler m Source #

Middleware

Middlewares allow you to modify the behavior of Okapi handlers. Middlewares are functions that take a handler and return another handler. Middlewares can be composed with the fish operator >=>.

 clearHeadersMiddleware >=> pathPrefix ["jello"] :: forall m. Middleware m

type Middleware m = Handler m -> Handler m Source #

A middleware takes an action that returns a Response and can modify the action in various ways

applyMiddlewares :: MonadOkapi m => [Middleware m] -> Middleware m Source #

scope :: MonadOkapi m => Path -> [Middleware m] -> Middleware m Source #

clearHeadersMiddleware :: MonadOkapi m => Middleware m Source #

prefixPathMiddleware :: MonadOkapi m => Path -> Middleware m Source #

Routing

Okapi implements routes and type-safe relative URLs using bidirectional pattern synonyms and view patterns. Routing can be extended to dispatch on any property of the request, including method, path, query, headers, and even body. By default, Okapi provides a route function for dispatching on the path of the request.

type Router m a Source #

Arguments

= m a	Parser for dispatcher
-> (a -> Handler m)	Dispatches parser result to the correct handler
-> Handler m

route :: MonadOkapi m => Router m a Source #

pattern PathParam :: (ToHttpApiData a, FromHttpApiData a) => a -> Text Source #

pattern GET :: Method Source #

pattern POST :: Method Source #

pattern DELETE :: Method Source #

pattern PUT :: Method Source #

pattern PATCH :: Method Source #

pattern IsQueryParam :: (ToHttpApiData a, FromHttpApiData a) => a -> QueryValue Source #

pattern HasQueryFlag :: Maybe QueryValue Source #

viewQuery :: Text -> Query -> (Maybe QueryValue, Query) Source #

viewQueryParam :: FromHttpApiData a => Text -> Query -> (Maybe a, Query) Source #

Relative URLs

Relative URLs are useful when we want to refer to other locations within our app. Thanks to bidirectional patterns, we can use the same pattern to deconstruct an incoming request AND construct the relative URL that leads to itself.

data RelURL Source #

Constructors

RelURL Path Query

renderRelURL :: RelURL -> Text Source #

renderPath :: Path -> Text Source #

renderQuery :: Query -> Text Source #

parseRelURL :: Text -> Maybe RelURL Source #

Testing

There are two ways to test in Okapi.

testParser :: Monad m => OkapiT m Response -> Request -> m (Either Failure Response, State) Source #

testParserPure :: OkapiT Identity Response -> Request -> Identity (Either Failure Response, State) Source #

testParserIO :: OkapiT IO Response -> Request -> IO (Either Failure Response, State) Source #

assert :: ((Either Failure Response, State) -> Bool) -> (Either Failure Response, State) -> Bool Source #

assert200 :: (Either Failure Response, State) -> Bool Source #

assert404 :: (Either Failure Response, State) -> Bool Source #

assert500 :: (Either Failure Response, State) -> Bool Source #

WAI

These functions are for interfacing with WAI (Web Application Interface).

run :: Monad m => (forall a. m a -> IO a) -> OkapiT m Response -> IO () Source #

serve Source #

Arguments

:: Monad m
=> Int	Port
-> Response	Default Response
-> (forall a. m a -> IO a)	Monad unlift function
-> OkapiT m Response	Parser
-> IO ()

serveTLS :: Monad m => TLSSettings -> Settings -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO () Source #

serveWebsockets :: Monad m => ConnectionOptions -> ServerApp -> Int -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO () Source #

serveWebsocketsTLS :: Monad m => TLSSettings -> Settings -> ConnectionOptions -> ServerApp -> Response -> (forall a. m a -> IO a) -> OkapiT m Response -> IO () Source #

app Source #

Arguments

:: Monad m
=> Response	The default response to pure if parser fails
-> (forall a. m a -> IO a)	Function for "unlifting" monad inside `OkapiT` to `IO` monad
-> OkapiT m Response	The parser used to equals the request
-> Application

Turns a parser into a WAI application

websocketsApp Source #

Arguments

:: Monad m
=> ConnectionOptions	Connection options configuration for the WebSocket server
-> ServerApp	The server to use for handling WebSocket connections
-> Response
-> (forall a. m a -> IO a)
-> OkapiT m Response
-> Application

Turns a parsers into a WAI application with WebSocket functionality See __ for information on how to create a WebSocket server

testRunSession :: Monad m => Session a -> (forall a. m a -> IO a) -> OkapiT m Response -> IO a Source #

testWithSession :: Monad m => (forall a. m a -> IO a) -> OkapiT m Response -> Session a -> IO a Source #

testRequest :: Request -> Session SResponse Source #

Utilities

Server Sent Events

data Event Source #

Constructors

Event
Fields eventName :: Maybe Text eventID :: Maybe Text eventData :: ByteString
CommentEvent ByteString
CloseEvent

Instances

Instances details

Eq Event Source #
Instance details Defined in Okapi Methods (==) :: Event -> Event -> Bool # (/=) :: Event -> Event -> Bool #
Show Event Source #
Instance details Defined in Okapi Methods showsPrec :: Int -> Event -> ShowS # show :: Event -> String # showList :: [Event] -> ShowS #