Okapi

Okapi is a micro web framework.

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)

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

newtype OkapiT m a

A concrete implementation of the MonadOkapi type constraint.

Constructors

OkapiT

Fields

• unOkapiT :: ExceptT Failure (StateT State m) a

Instances

MonadTrans OkapiT

Defined in Okapi

Methods

lift :: Monad m => m a -> OkapiT m a

Monad m => MonadState State (OkapiT m)

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)

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)

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)

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)

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)

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)

Defined in Okapi

Methods

liftIO :: IO a -> OkapiT m a

Monad m => Alternative (OkapiT m)

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)

Defined in Okapi

Methods

mzero :: OkapiT m a

mplus :: OkapiT m a -> OkapiT m a -> OkapiT m a

MFunctor OkapiT

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

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

Constructors

Skip

Error Response

Instances

Show Failure

Defined in Okapi

Methods

showsPrec :: Int -> Failure -> ShowS

show :: Failure -> String

showList :: [Failure] -> ShowS

Monad m => MonadError Failure (OkapiT m)

Defined in Okapi

Methods

throwError :: Failure -> OkapiT m a

catchError :: OkapiT m a -> (Failure -> OkapiT m a) -> OkapiT m a

data State

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

Constructors

State

Fields

• stateRequest :: Request
• stateVault :: Vault

Instances

Monad m => MonadState State (OkapiT m)

Defined in Okapi

Methods

get :: OkapiT m State

put :: State -> OkapiT m ()

state :: (State -> (a, State)) -> OkapiT m a

data Request

Represents the HTTP request being parsed.

Instances

Eq Request

Defined in Okapi

Methods

(==) :: Request -> Request -> Bool

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

Show Request

Defined in Okapi

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

type Method = Maybe ByteString

type Path = [Text]

type Query = [QueryItem]

type QueryItem = (Text, QueryValue)

data QueryValue

Constructors

QueryParam Text

QueryFlag

Instances

Eq QueryValue

Defined in Okapi

Methods

(==) :: QueryValue -> QueryValue -> Bool

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

Show QueryValue

Defined in Okapi

Methods

showsPrec :: Int -> QueryValue -> ShowS

show :: QueryValue -> String

showList :: [QueryValue] -> ShowS

type Body = ByteString

type Headers = [Header]

type Header = (HeaderName, ByteString)

type HeaderName = HeaderName

type Cookie = [Crumb]

type Crumb = (ByteString, ByteString)

Request Parsers

request :: MonadOkapi m => m Request

Parses the entire request.

requestEnd :: MonadOkapi m => m ()

Method Parsers

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 Parsers

These are the path parsers.

path :: MonadOkapi m => m [Text]

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

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

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

pathEnd :: MonadOkapi m => m ()

Similar to end function in https://github.com/purescript-contrib/purescript-routing/blob/main/GUIDE.md

Query Parsers

These are the query parsers.

query :: MonadOkapi m => m Query

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

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

Test for the existance of a query flag

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

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

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

queryEnd :: MonadOkapi m => m ()

Body Parsers

body :: MonadOkapi m => m Body

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

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

bodyEnd :: MonadOkapi m => m ()

Header Parsers

These are header parsers.

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 ()

Vault Parsers

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 ()

Combinators

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

Parses without modifying the state, even if it succeeds.

Failure

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 ()

Responding

type Handler m = m Response

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

data Response

Represents HTTP responses that can be returned by a parser.

Constructors

Response

Fields

• responseStatus :: Status
• responseHeaders :: Headers
• responseBody :: ResponseBody

type Status = Natural

data ResponseBody

Represents the body of an HTTP response.

Constructors

ResponseBodyRaw ByteString

ResponseBodyFile FilePath

ResponseBodyEventSource EventSource

Values

ok :: Response

notFound :: Response

redirect :: Status -> Text -> Response

forbidden :: Response

internalServerError :: Response

Setters

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

Special

static :: MonadOkapi m => Handler m

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

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

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

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

Arguments

 = m a

Parser for dispatcher

-> (a -> Handler m)

Dispatches parser result to the correct handler

-> 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)

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

Constructors

RelURL Path Query

renderRelURL :: RelURL -> Text

renderPath :: Path -> Text

renderQuery :: Query -> Text

parseRelURL :: Text -> Maybe RelURL

Testing

There are two ways to test in Okapi.

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

WAI

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

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

serve

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 ()

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

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

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

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

testRequest :: Request -> Session SResponse

Utilities

Server Sent Events

data Event

Constructors

Event

Fields

• eventName :: Maybe Text
• eventID :: Maybe Text
• eventData :: ByteString

CommentEvent ByteString

CloseEvent

Instances

Eq Event

Defined in Okapi

Methods

(==) :: Event -> Event -> Bool

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

Show Event

Defined in Okapi

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

class ToSSE a where

Methods

toSSE :: a -> Event

type EventSource = Chan Event

newEventSource :: IO EventSource

sendValue :: ToSSE a => EventSource -> a -> IO ()

sendEvent :: EventSource -> Event -> IO ()

Sessions

type Session = Map ByteString ByteString

class Monad m => HasSession m where

Methods

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